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.
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:
{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.