Skip to content

Connection modes

MetaTrader 5 only

The connection modes are for MetaTrader 5. MetaTrader 4 (MT4WebClient) always connects in Direct mode.

Direct (default) Browser Hybrid
Connection, login, encryption, keep-alive the library the official web terminal in a hidden browser the official web terminal in a hidden browser
Everything else (account, symbols, quotes, candles, history, trading...) commands of the library the interface of the web terminal (clicks, forms) commands of the library, sent through the connection of the web terminal
Quote subscription command Market Watch of the web terminal Market Watch of the web terminal
Speed fast slow (hundreds of ms to seconds per operation, one at a time) fast
Features all some parameters are not available (below) all
Affected by a change of MetaQuotes in... the protocol (connection, login, encryption, commands) the interface of the web terminal the formats of the commands (not the connection, login or encryption)
Needs nothing Edge, Chrome or Chromium Edge, Chrome or Chromium

In Hybrid mode the web terminal opens the only connection and logs in (with its login form). The library sends its commands through that connection, encrypted with the key the web terminal is using, and takes the responses to them out before the web terminal sees them (it never receives an answer to a request it did not make). For the server there is a single client. The options (BrowserPath, Headless, SelectorsFile) and the requirements are the same as in Browser mode, below; Mode = ConnectionMode.Hybrid (ConnectionMode.HYBRID in Python and Java).

Which one should I use?

It depends on what matters most in your case. Direct is the default and the fastest, and needs nothing else. Browser and Hybrid run the official web terminal in a hidden browser (Microsoft Edge, Google Chrome or Chromium), so they can keep working if MetaQuotes changes the protocol of the web terminal, but they take longer to start; Browser is also slower in every operation and does not send any command of its own.

Browser mode

By default (Direct mode) the library opens its own WebSocket to the web terminal and speaks its protocol: it is fast and offers every feature. In Browser mode the library starts a hidden browser that runs the official web terminal, and does every operation through its interface, as a person would (logging in with the login form, adding symbols to the Market Watch, filling in the order panel, dragging the chart...). The web terminal does all the protocol work (connection, encryption, login, keep-alive); the library only reads the messages it receives, already decrypted, and never sends a command of its own. A change of the protocol by MetaQuotes therefore does not affect Browser mode; a change of the web terminal interface does (see Selectors below).

The calls, the classes and the events are the same in both modes: only the option changes.

var client = new MT5WebClient("wss://web.metatrader.app/terminal",
    new MT5WebClientOptions { Mode = ConnectionMode.Browser, LicenseKey = key });
c = MT5WebClient(url, MT5WebClientOptions(mode=ConnectionMode.BROWSER, license_key=key))
MT5WebClient c = new MT5WebClient(url, new MT5WebClientOptions().mode(ConnectionMode.BROWSER).licenseKey(key));
MT5WebClientOptions o; o.mode = ConnectionMode::Browser; o.license_key = key;
MT5WebClient c(url, o);
let c = MT5WebClient::new(&url, MT5WebClientOptions { mode: ConnectionMode::Browser, license_key: Some(key), ..Default::default() })?;

Requirements: Microsoft Edge, Google Chrome or Chromium installed (Edge comes with Windows; on Linux install Chrome or Chromium). The library uses the first one it finds, in that order; BrowserPath / browser_path selects another one. Each client uses its own temporary browser profile, deleted when it disconnects, so nothing it does (for example the symbols added to the Market Watch) affects the web terminal you use yourself.

Options (Browser mode only):

Option Default
Mode / mode Direct Browser to use the web terminal
BrowserPath / browser_path installed Edge, Chrome or Chromium browser executable
Headless / headless true false shows the browser window: useful to watch what the library does
SelectorsFile / selectors_file none JSON file that replaces built-in selectors (below)

The URL can be the WebSocket address (wss://host/terminal, as in Direct mode) or the address of the web page (https://host/terminal); the page is always opened in English (lang=en).

Differences with Direct mode:

Browser mode
Speed Each operation takes what the interface takes (hundreds of milliseconds to a few seconds). Operations run one at a time: calls made at the same time wait for each other.
Quotes (Subscribe) The Market Watch of the browser is set to exactly the requested symbols (the web terminal subscribes to its Market Watch).
Candles The chart is set to the symbol and timeframe; older candles are loaded by dragging the chart, so long ranges in small timeframes are slow (they fail with a timeout after the long timeout, at least 60 s). Timeframes: M1, M5, M15, M30, H1, H4, D1, W1, MN1.
History Uses the "Custom Period" of the History tab (whole days); the library keeps the requested range.
Market depth One symbol at a time.
Not available (ArgumentException / ValueError / IllegalArgumentException / std::invalid_argument / Error::Argument) the filling type of an order or close; the price and the comment of a close; changing the comment of a pending order; market depth of more than one symbol.
A button disabled by the web terminal is not an error: the result has Retcode 10025 ("No changes", for Modify) or 10013 (invalid request), and nothing is sent.
Logout closes the browser (the web terminal has no logout of its own).
Economic calendar CalendarWebClient only has Direct mode (the web terminal has no calendar screen).

Selectors

The library finds the elements of the web terminal (the login form, the Market Watch rows, the fields and buttons of the order panel...) with selectors: CSS selectors and visible texts, listed with a name each in selectors.default.json (in this package). If MetaQuotes changes the interface and an operation fails with a message such as:

Browser mode: element not found (.market-watch tr.item[title="EURUSD"]) (selector 'mw.row'). The web terminal may have
changed: fix 'mw.row' in your selectors file (option SelectorsFile; see selectors.default.json).

you can keep working without waiting for a new version: copy selectors.default.json, change the entries that no longer match (only those: the others can be removed and keep their built-in value) and pass the file with the SelectorsFile option:

{
  "mw.row": ".market-watch div.row[data-symbol=\"{symbol}\"]"
}

{symbol}, {ticket} and {name} are filled in by the library. To find the new selector, open the web terminal in Chrome or Edge, right-click the element → Inspect. Run with Headless = false to watch the browser while you test. An unknown name or a value that is not a text in the file is reported when the client is created.