Metatrader4™ Bridge Plugin - version 1.14
Metatrader4™ (MT4) is a popular trading platform, supported by most brokers. It consists of two parts: The MT4 client terminal runs on the trader's PC and communicates with MT4 server via Internet. The MT4 server program runs on the broker's server; it generates prices and slippage as set up by the broker, and manages the trades. With the MT4 bridge, Zorro can control the MT4 client terminal as an Expert Advisor (EA) and this way trade with all brokers that provide the MT4 platform for their clients.
Through its DLL functions, the MT4 bridge can also be used for controlling Metatrader4 with third party software.
The MT4 bridge DLL has two sides. On the MT4 side it appears as a library DLL that can be called from any EA. On the Zorro side it appears as a Broker Plugin. This way the MT4 bridge can theoretically be used not only by Zorro, but also by any other software for reading prices and sending orders via MT4.
MT4 client with attached Zorro
Installation and startup
If you want to run Zorro on a VPS together with the MT4 bridge and have limited PC experience, you can subscribe a VPS installation service on the download page. Otherwise, here are the 4 steps for connecting Zorro to MT4 build 600 and above:
- Install Zorro. Install the broker's MT4 platform if you haven't already. Connect to to your MT4 account with the login data from your broker. Locate the ZorroMT4.zip archive in your Zorro folder. In the MT4 terminal, select File / Open Data Folder for locating the MQL4\Experts and MQL4\Libraries folders. Unzip the archive. It contains 3 files: Zorro.mq4 goes into the Experts folder, and ZorroMT4.ex4 and ZorroMT4.dll both go into the libraries folder. Zorro.mq4 is the EA, ZorroMT4.ex4 is its library for connecting MT4 to Zorro, and ZorroMT4.dll handles the communication between the two programs.
When your MT4 version is not running in "portable mode", Experts and Libraries are located in your user directory (under C:\Users\YourName\AppData\Roaming\MetaQuotes\Terminal\SomeStrangeCodeSequence\MQL4). There is also a MQL4 subfolder directly in the MT4 directory - that's NOT the folder that you need and copying files there will have no effect!
- In the MT4 terminal, check the Expert Options under Tools / Options / Expert Advisors, and make sure that [Allow Automated Trading] and [Allow DLL Imports] are enabled. In the MT4 Navigator under Expert Advisors you should now find the entry [Zorro] (if not, right click on Expert Advisors and select Refresh). Open a chart window with the asset that you want to trade; for multiple assets use an EUR/USD chart. The time frame of the chart does not matter. Drag the Zorro EA onto it. Confirm in the pop-up dialog that DLL imports and live trading are enabled. You should now see the comment "Controlled by Zorro Bridge" with a version number in the upper left corner of the chart (current bridge version is 1.9), and a smiling face next to "Zorro" in the upper right corner. If MT4 does not start the EA, look for the reason under the Experts tab: you might have forgotten to copy a file or to check an option. Some MT4 setups do not compile the EA automatically: In that case right click on the Zorro EA, select Modify, then click Compile in the editor window.
- Check the assets that you want to trade, and make sure that they are available in the MT4 market watch window (a right click and Show All enables all assets). Make also sure that the assets have similar names as the assets traded by your strategy. Forex pairs that differ in a missing slash and an added suffix (f.i. "EURUSDpro" instead of "EUR/USD") are corrected automatically. But if you want to trade other assets that have different names (f.i. "GOLD" instead of "XAU/USD", or "DE30EUR" instead of "GER30"), convert the names as described below under MT4 symbols. Also make sure that the time and time zone on your PC or VPS are set up correctly - Zorro needs the correct time while trading.
- Now start Zorro. Select [MT4] or [MT4 (demo)] in Zorro's Account scrollbox. Enter your MT4 account number in Zorro's [User] field (the content of the [Password] field does not matter). You can see the account number in MT4 Navigator / Accounts. Make sure that [Demo] / [Real] is set to the same account type as in the MT4 title bar. Clicking [Trade] will now attach Zorro to MT4 and handle price quotes and orders through the MT4 server. You should see the broker's name in Zorro's message window on login, and a"Zorro connected" comment in the upper left corner of the MT4 chart window. The asset prices are now downloaded from the MT4 server. When accessing an asset the very first time, MT4 will need a minute or longer for downloading it from the server (equivalent to the "Waiting For Update" message when opening a MT4 chart the first time). In that case you'll see an error message in the Zorro window since the data is not yet available; just connect again after a minute until all assets load. If you get other error messages, look under Known issues .
Most MT4 versions use special asset names with broker specific suffixes. For instance, the "EUR/USD" currency pair is called "EURUSD" in the MT4 version by FXCM™, "EURUSDm" in the IBFX™ version, "EURUSDi" in the version by Traders Way™, and "EURUSD.G" in the Global Prime™ version. The Zorro.mq4 EA automatically adapts the names by removing the slash and adding the broker specific suffix from EURUSD symbol name of the EA chart window. So no adaption is required on your side.
For non-currency assets with names longer than 6 characters, or for names that can not be automatically adapted this way - for instance, "GOLD" instead of "XAU/USD" - the MT4 symbols must be entered directly in the Symbol column of the AssetsFix.csv spreadsheet. Otherwise your selected assets are not found in the MT4 symbol list, and you'll get "asset unavailable" error messages when starting your script.
All assets you want to trade must be visible in the MT4 Market Watch window. If you still get error messages about unavailable assets, read the MT4 Experts log. It normally tells what the problem is.
Known MT4 Issues:
- Some MT4 clients don't have all assets enabled by default. Disabled assets are not visible in the "Market Watch" window and not available for trading. For enabling them, right click on "Market Watch", select "Symbols", select the symbol(s) you want to trade, and click "Show". But do not select more than you actually trade, since any additional asset in the Market Watch requires bandwidth, memory, and CPU resources.
- Some MT4 brokers - for instance, LMAX - provide different symbols for the same asset. Only one of the symbols is really traded, so make sure that you have the right symbol on the chart window with the Zorro EA.
- Some MT4 servers need a long time for the initial access of the price history of previously unused assets. This can cause a timeout. The strategy will then not start, and a Error 054 or Error 055 message is displayed. In that case just restart the strategy by clicking [Trade] again. Inbetween the server had enough time to upload the missing asset. You might need to repeat that step until all assets load properly.
- Some MT4 servers have no sufficient price history for systems with a long lookback period, such as Z1, Z2, or Z12 - especially when starting after a holiday. The strategy will then not start, and a Error 047 message is displayed. In that case use the PRELOAD flag or the Preload .ini setup for using Zorro's own history instead of the MT4 price server.
- Most MT4 servers can download only a limited live price history, such as 2000 hours. Therefore the assetHistory function and the Download script normally does not work with MT4; downloading large historical price data requires direct access to your broker's API.
- Many MT4 servers do not provide asset parameters such as RollLong/RollShort; others provide them, but in arbitrary units. Asset lists downloaded from MT4 servers often need manual correction.
- Some MT4 versions are set up to not automatically compile EAs. In this case the Zorro EA will appear grey in the Navigator and can not be attached to a chart. Open it with the MetaQuotes Language Editor and click [Compile] - this will encode the source code and store it as an .ex4 file, which can then be attached to a chart.
- Some old MT4 versions physically delete .ex4 files that have been generated with a newer MT4 version. The reason for that bizarre behavior is unknown, but you'll find that the ZorroMT4.ex4 file suddenly disappears from the libraries folder upon lauching MT4. Consequently the Zorro EA will generate an error message because the ZorroMT4 library is not found. In that case just update MT4 to the current version, and copy ZorroMT4.ex4 again into the libraries folder.
- When getting a practice account number and password directly from a MT4 broker, it's sometimes displayed as "Real Account" in the MT4 title bar. Since the 'demo only' version of the MT4 bridge can not trade with real accounts, you need to open a true demo account. You can open any number of demo accounts directly in MT4 by selecting File / Open an Account.
- Trades via MT4 are normally executed on a virtual market handled by the MT4 server. In that case you must NOT set the NFA flag, as the virtual trades are not NFA compliant. Still, hedging can be prohibited, so set Hedge mode to 0 or 4 in that case. If the account complies with NFA FIFO rules (first in, first out), you you must close old trades before new trades. Otherwise the trade won't open or close, and you'll see an error message like "Close failed - prohibited by FIFO rules" in the MT4 experts log. Use Hedge = 4 in such a case, which automatically ensures FIFO compliant closing of trades. Note that you can not run multiple strategies in parallel on no-hedging or FIFI compliant accounts.
- Some MT4 brokers do not support partially closing trades. You can see this from an error message like "invalid trade volume" in the MT4 experts log. In this case set Hedge to 4 or below for disabling partial closing.
- MT4 servers can reject trades ("Can't open...") for various reasons, for instance a too distant stop, a too close stop, too large slippage, or the wrong time of the day. The reason is normally visible in the MT4 Experts log.
- Some MT4 brokers use odd PIP sizes for CFDs, such as 0.25, and don't accept stop limits that are not a multiple of this pip size. In this case set up the correct PIP size and PIPCost value in the asset list.
- The MT4 bridge was tested with all currently available MT4 client builds, and is tested with any new upgrade. Since new MT4 builds are often not fully compatible to their predecessors, do not upgrade a working system.
If MT4 upgrades behind your back and you experience problems afterwards, please report on the user forum or to Zorro Support.
- Communication between Zorro and MT4 on the same PC is very fast, so trading with the MT4 bridge does not add noticeable latency compared to directly trading with an MT4 Expert Advisor. Still, if a broker offers both API and MT4 access, using the API is normally preferable. The API is faster than the MT4 server, and MT4 accounts are often slightly more expensive due to additional spread.
- The MT4 bridge of the free Zorro version supports demo accounts only. A MT4 bridge for real accounts is automatically included with Zorro S or can alternatively be subscribed on the Zorro Download Page. The MT4 client terminal and Zorro must run on the same PC in the same Windows environment, and must be started by the same user.
- With Zorro S, several Zorro instances can connect simultaneously to a single MT4 client terminal. Otherwise, only one Zorro instance can connect. Do not attach the Zorro EA to more than one chart window in a single MT4 instance. For running several MT4 instances simultaneously for special purposes - for instance, signal providing - install several MT4 clients in separate folders.
- MT4 is resource and bandwidth hungry, which can cause long response times of the MT4 bridge when several processes run in parallel. Depending on the Internet bandwidth, you should normally not run more than one MT4 client on a low-performance VPS (such as the free Amazon VPS), and not more than 3 clients on a high-performance VPS. Make sure that only the really traded assets are visible in the Market Watch window.
- While Zorro is connected to MT4 in [Trade] mode, do not close or reset the MT4 chart with the Zorro EA. Closing the chart will stop the EA and disconnect Zorro (visible by a red square next to the Server window, and a frozen server time). It must then be stopped and restarted.
- The MT4 client terminal displays prices as Bid prices, while Zorro always uses Ask prices. So you'll see different prices on the MT4 chart and in the Zorro window. This has no effect on trading, as Zorro internally converts all prices to Bid or Ask dependent on the trade direction.
The MT4 bridge supports the following data streams:
- marketVal: Not supported.
- marketVol: Not supported in historical data, tick frequency in live data.
Supported broker commands
The MT4 bridge supports the brokerCommand function with the following commands:
- brokerCommand(SET_PATCH, patch)
- brokerCommand(GET_TIME, 0)
- brokerCommand(SET_SLIPPAGE, slippage)
- brokerCommand(SET_MAGIC, magic)
- brokerCommand(SET_ORDERTEXT, string Text) (Zorro 1.48 and above)
- brokerCommand(SET_COMMENT, string Text)
- brokerCommand(PLOT_HLINE, var* p): id
- brokerCommand(PLOT_TEXT, var* p): id
- brokerCommand(PLOT_MOVE, var* p)
- brokerCommand(PLOT_REMOVE, id)
- brokerCommand(PLOT_REMOVEALL, 0)
- brokerCommand(PLOT_STRING, string)
More commands can be implemented by the user by editing the Zorro EA. Any brokerCommand(Command,Parameter) call in a Zorro script triggers the CMD_BCOMMAND part of the Zorro.mq4 run loop. The parameter is transferred in arr and can be used for calling arbitrary functions. Use arr for transferring the return value back to Zorro. Be aware that sent parameters are stored on the MT4 side and thus affect all Zorro instances connected - not only the instance that sent the parameter.
Zorro EA functions
Zorro can directly trade with MT4 through the Zorro.mq4 Expert Advisor. This EA is included in MQL4 source code, so it can be used as a template for writing own EAs that evaluate trade signals from Zorro. For this the following four functions are available in the ZorroMT4.ex4 library:
ZorroInit () : int
Open the Zorro plugin. Normally called in the MT4 init() function.
0 when the initialization failed, otherwise nonzero.
Release the Zorro plugin. Normally called in the MT4 deinit() function.
ZorroRequest (double& array): int
Receive a request from the DLL, f.i. for opening a trade.
Normally called in a loop in the MT4 start() function.
||Array of up to 10 double variables that are filled with the request parameters.
0 if no request is pending, otherwise one of the following commands: CMD_COMMENT, CMD_PRINT, CMD_ASSET, CMD_HISTORY, CMD_BALANCE, CMD_BUY, CMD_TRADE, CMD_SELL, CMD_STOP, CMD_BCOMMAND (see Zorro.mq4). The zstring() function returns a string containing the requested asset name or a text message. Asset names need possibly be converted to the specific symbol names of the MT4 version (see remarks).
ZorroRespond (int cmd, double& array)
Respond to a request from the DLL.
Normally called to transfer the result after receiving a request.
||One of the following commands: CMD_ASSET, CMD_TICK, CMD_HISTORY, CMD_BALANCE, CMD_BUY, CMD_TRADE, CMD_SELL,CMD_STOP, CMD_BCOMMAND (see Zorro.mq4).
||Array of up to 10 double variables containing the response parameters.
Example: see source\Zorro.mq4
Brokers, brokerCommand, order, broker plugin