Broker / Feed Plugin

Zorro supports most major brokers either with a direct connection, or by connecting through a platform, for instance with the MT4/5 bridge or the Sierra bridge. A connection to a broker API, exchange, market data feed, or platform is established with a DLL in Zorro's Plugin folder. Zorro automatically scans that folder at startup, and lists all valid DLLs in the [Broker / Account] scrollbox. The DLL uses the broker's API for placing orders and getting market data. The interface is organized for keeping the DLL as simple as possible. Only a few functions are required for basic automated trading. If you know programming, you can write a broker DLL in a few days. For downloading historical data in CSV or JSON format from online data sources you'll need no DLL; a small script is sufficient (see assetHistory).

Writing a broker plugin

Plugins can be written in any language that supports DLLs, such as Java, Pascal, C#, or C++. We reward proper C++ written plugins with a free Zorro S subscription, license, or update extension. Open source plugin code can be found in Zorro's Source folder and on the GitHub pages of plugins developed by Zorro users.

The source code of the included broker plugins is available on request to experienced programmers who are developing a similar plugin for the community. Please contact us with a short description of your project and your prior C++ experience. You'll need to sign a non-disclosure agreement, and send us back the final plugin with source code for review. Technical support for broker plugins is free; for this you'll need no support ticket or Zorro S subscription.

Setting up VC++

In the following you'll find instructions about how to set up Microsoft VC++ to write a broker plugin DLL for the Zorro broker API interface. The dialogs are slightly different for any VC++ version, but here's the general setup for a Win32 DLL. Create a new project (File->New Project). Select Win32 Project. When the Win32 Application Wizard pops up, select DLL in the application settings, then click [Finish]. Under VC++ 2017, select Windows Universal, then DLL. VC++ now creates a new DLL project for you, with a main cpp file that looks like this:

// Defines the entry point for the DLL application.

#include "stdafx.h"

BOOL APIENTRY DllMain( 
  HANDLE hModule,
  DWORD ul_reason_for_call,
  LPVOID lpReserved)
{
  return TRUE;
}

DllMain is the main entry point of the broker DLL, and you can leave that function unchanged. The broker functions require the DATE and T6 data types, thus you need to define DATE and include the trading.h header, like this:

typedef double DATE;
#include "whereever_you_installed_it\Zorro\include\trading.h"

If you want to distribute your broker DLL to other people, we suggest that you open Properties / C/C++ / Code Generation, and change the Runtime Library setting from Multi-threaded DLL (/MD) to Multi-threaded (/MT). Otherwise users won't be able to use the DLL without installing the VC++ Runtime Redistributable before - one of the funny ideas by Microsoft to make Windows user's life more interesting.

If your broker DLL accesses Zorro-specific structs, set struct alignment to 4, or use the #pragma pack(4) statement. Otherwise structs can have different sizes in lite-C and in VC++.

For a DLL to appear in the scrollbox, it must be located in the Plugin folder. Zorro first checks at start if the DLL can be opened with LoadLibrary(). If so, it checks if there is a BrokerOpen function (see below) and if it returns a valid version number. If both conditions are fulfilled, the DLL is registered and appears in the scrollbox. LoadLibrary will fail when DllMain does not return properly. Most frequent reasons are not creating a plain Win32 DLL (f.i. a 64-bit or MFC DLL) or a missing module that the DLL requires. Thus, the more complex libraries you're using, the more likely is your DLL to fail, probably not on your, but on other people's PCs. For being on the safe side, include in the distribution all modules that your DLLs needs. If in doubt, check your DLL's dependencies with DependencyWalker. For debugging, place breakpoints in DllMain and BrokerOpen and check what's happening when Zorro starts.

Plugin templates & the TradeTest script

The Source folder contains two broker plugin examples in .zip archives:

• Simulation is a simple 'broker simulation' plugin that generates random prices and allows to open a trade with an arbitrary asset. Use it in NFA mode.
• AllyInvest is a Github snaphot of a real broker plugin.

You can find more Zorro broker plugins on Github. Use the best suited as a template for your own plugin. Implement the DLL functions (see below) in this order: BrokerOpen, BrokerLogin, BrokerAsset, BrokerBuy2. These 4 functions (described below) are the minimum required for trading with the broker. Optionally, implement BrokerAccount, BrokerHistory2, BrokerTime, BrokerTrade, BrokerSell2, BrokerStop if supported by the API. Test any function after implementation with the TradeTest script.

Some functions need not be fully implemented, or not at all. The minimum functions for TradeTest to run are BrokerOpen and BrokerLogin. If a function, f.i. BrokerAsset, is not yet available in the DLL, Zorro simulates it with default values. So you can implement and test the functions step by step.

As soon as the BrokerAsset function is correctly implemented, you should see the current price in the Server window. The TradeTest script opens a panel with the following buttons for testing various broker functions:

[Auto On/Off] - Toggle button for a simulated trade session that automatically opens or closes a trade every minute.

[NFA On/Off] - Toggle the NFA flag. Required for most US accounts; not to be set for most Forex/CFD accounts.

[Hedge] - Toggle between Hedge modes 0, 2, 4,and 5. Some brokers do not support full hedging (mode 2) or partial closing (mode 5).

[Order] - Toggle between limit (LMT), market orders (MKT), good-til-cancelled (GTC) and adaptive orders (Adaptive) when supported by the plugin.

[Asset] - Enter the asset symbol to trade (default: asset from the scroll box).

[Buy Long] - Open a long position with the Lots and Stop value set up with the sliders.

[Buy Short] - Open a short position. Dependent on Hedge, close any open position in opposite direction.

[Close Long] - Close the given number of lots from an open long position. Partial closing is not supported by some brokers.

[Close Long] - Close the given number of lots from an open short position.

[Update Stop] - Sets the Stop of all open positions to the value (in Pips) set up with the slider. Stop adjustment is not supported by some brokers. Due to StopFactor, the broker stop is more distant than the real stop.

LMT orders attempt to open the position at half spread, adaptive orders at zero spread. The broker must support real limit orders for this; MT4 "pending positions" are no limit orders and will not work for LMT or adaptive orders. Various trading modes, broker commands, asset lists etc. can be set up in #define statements at the begin of the TradeTest script.

Broker API functions

The broker DLL exports functions that are described in the following list. With VC++, exported DLL functions must be either declared with the extern "C" __declspec(dllexport) attribute, or listed in a .def file. The DLL functions use only a small subset of a usual broker API. In the following list, pointer arguments printed in italic can be NULL; if they are nonzero, the function must fill them with the required data. All data is mandatory if not mentioned otherwise.

BrokerOpen (char* Name, FARPROC fpError, FARPROC fpProgress) : int

Parameters:

Returns:

BrokerHTTP (FARPROC fpSend, FARPROC fpStatus, FARPROC fpResult, FARPROC fpFree)

Parameters:

BrokerLogin (char* User, char* Pwd, char* Type, char* Accounts): int

Parameters:

Returns:

BrokerTime (DATE *pTimeUTC): int

Parameters:

Returns:

Remarks:

• If the UTC server time is not available in the broker API, *pTimeUTC can be left unchanged. If the market state is not available, let the function just return 2 or 0 dependent on whether the connection is established or not.
• If the server time is returned, but does not change for several minutes, Zorro assumes that the broker server is offline. It then displays "Offline" in the server window, and suspends trading and requesting price quotes.
• If the broker API uses a different time format, here's a C++ code example for converting DATE to/from the Linux time format, which is the number of seconds since January 1st 1970 midnight:

DATE convertTime(__time32_t t32)
{
  return (double)t32/(24.*60.*60.) + 25569.; // 25569. = DATE(1.1.1970 00:00)
}

__time32_t convertTime(DATE date)
{
  return (__time32_t)((date - 25569.)*24.*60.*60.);
}

BrokerAsset (char* Asset, double *pPrice, double *pSpread, double *pVolume, double *pPip, double *pPipCost, double *pLotAmount, double *pMarginCost, double *pRollLong, double *pRollShort): int

Parameters:

Returns:

Remarks:

• If parameters are not supplied by the broker API, they can be left unchanged. Zorro will then use default values from the asset list. Only price and spread must always be returned when the pPrice and pSpread parameters are nonzero.
• For receiving streaming price data, get the Zorro window handle from the SET_HWND command for sending messages to a Zorro window. The message WM_APP+1 triggers a price quote request.
• Dependent on the broker API, some asset parameters might require unit conversions because lots and pips can have special meanings. In most APIs, such as the FXCM API, the parameters are directly available. A more complicated example is the MT4™ API where the parameters must be corrected by the different scales of "Lot" and "Point" (MQ4 example):

double Price = MarketInfo(Asset,MODE_ASK);
double Spread = Price - MarketInfo(Asset,MODE_BID);
double Volume = 0;
double LotFactor = MarketInfo(Asset,MODE_MINLOT); // correction for different lot scale
double Pip = MarketInfo(Asset,MODE_POINT);
double PipCost = MarketInfo(Asset,MODE_TICKVALUE) * LotFactor;
int DigitSize = MarketInfo(Asset,MODE_DIGITS); // correction for brokers with 5 digits
if(DigitSize == 3 || DigitSize == 5) { 
  Pip *= 10.;
  PipCost *= 10.;
}
double MinAmount = MarketInfo(Asset,MODE_LOTSIZE) * LotFactor;
double Margin = MarketInfo(Asset,MODE_MARGINREQUIRED) * LotFactor;
double RollLong = MarketInfo(Asset,MODE_SWAPLONG);
double RollShort = MarketInfo(Asset,MODE_SWAPSHORT);
if(MarketInfo(Asset,MODE_SWAPTYPE) == 0.) {
  RollLong *= PipCost;
  RollShort *= PipCost;
}

• Asset parameters can be different dependent on when they are requested. For instance, some brokers charge a three times higher rollover fee on Wednesday for compensating the weekend. Spreads are usually higher when the market is closed or illiquid.
• If the broker API can not subscribe an asset, it must be manually subscribed in the broker platform or website.
  

BrokerHistory2 (char* Asset, DATE tStart, DATE tEnd, int nTickMinutes, int nTicks, T6* ticks): int

Parameters:

Returns:

BrokerAccount (char* Account, double *pBalance, double *pTradeVal, double *pMarginVal): int

Parameters:

Returns:

BrokerBuy2 (char* Asset, int Amount, double StopDist, double Limit, double *pPrice, int *pFill): int

Parameters:

Returns:

• 0 when a FOK or IOC order was not filled within 30 seconds (adjustable with the SET_WAIT command). Unfilled FOK / IOC orders must be cancelled.
• Trade or order ID number when either the order was filled, or when a GTC order was successfully placed. If the broker does not support individual trades or ID numbers, a unique 6-digit number, f.i. from a counter, can serve as a trade ID.
• -1 when the trade identifier is a UUID that must be retrieved with the GET_UUID command.
• -2 when the broker API did not respond at all within 30 seconds. The order must then be cancelled. Zorro displays a "possible orphan" warning.
• -3 when the trade was entered, but got no ID yet. The ID is then taken over from the next BrokerBuy call that returned a non-negative ID.
   

BrokerTrade (int nTradeID, double *pOpen, double *pClose, double *pCost, double *pProfit): int

Parameters:

Returns:

BrokerStop (int nTradeID, double dStop): int

Parameters:

Returns:

BrokerSell2 (int nTradeID, int nAmount, double Limit, double *pClose, double *pCost, double *pProfit, int *pFill): int

Parameters:

Returns:

BrokerCommand (int nCommand, DWORD dwParameter): var

Parameters:

Returns:

Remarks:

• A broker DLL must contain at least the BrokerOpen function for being recognized by Zorro and appearing in the scrollbox.
• Functions ending with '2' replace older functions that are however still supported. For instance, BrokerHistory2 replaced BrokerHistory, but old plugins with BrokerHistory will still work.
• Date/Time parameters and historical time stamps should be UTC. If GET_BROKERZONE is supported and returns a different time zone, they should be in that time zone.
• If the connection breaks down, BrokerTime will be called in TickTime intervals for determining if it is still broken. If interrupted for a longer time, Zorro will attempt to re-login in increasing intervals from minutes to hours until the connection is established again.
• If optional functions are not implemented or optional parameters not returned, Zorro replaces them with educated guesses and assumptions. For instance, if BrokerSell2 is not implemented, Zorro will assume that trades are closed by buying in opposite direction. If BrokerTrade is not implemented and thus the fill amount and fill price of GTC orders cannot be traced, Zorro will treat the order as if it were completely filled at the entry price, and will estimate the value of the position from the current price and entry price.
• If BrokerTrade is implemented, it is automatically called in regular intervals for updating the fill amounts and values of all open positions, except for contracts. For contracts it is only called by contractUpdate or contractPrice, and is preceded by a SET_SYMBOL command with the current contract symbol.
• The UUID of trades is not stored after terminatiung the session, so those trades are not resumed at next session start.
• For a script with low-level broker access, you can call the above functions of a broker plugin directly from your script. For this, open the plugin DLL with LoadLibrary or DefineApi as described under DLL / API implementation. The broker DLL may also contain other broker-specific functions that are not directly used by Zorro, but can be called this way from strategy scripts.
• For passing struct pointers via BrokerProgress from the API to the Zorro script, make sure that struct member alignment is set to 1 or 4 bytes. Lite-C does not align or pad struct members.
• For asynchronously triggering a price quote request, send a WM_APP+1 message to the window handle received by the SET_HWND command. For triggering the callback function, send a WM_APP+2 message. This can be used for prices streamed by another thread. An example for sending messages can be found under HWnd.
• Some crypto exchanges require HMAC authentication signatures for transmitting orders. There is public C++ code for that in many code libraries on Github (search for f.i. sha512.cpp).
• Since Zorro broker plugins are standard DLLs, they can also be used by third party software. For instance, the above functions can be called from Python using the ctypes library.

Example: see Source folder

See also: