Trading Router API Tutorial
We will learn how to use Trading Router Library API to develop our own EA and receive messages from Trading Router server. We will develop an example EA to receive messages from Trading Router server. You can download and test the example codes from Downloads page. It is Mt4LibExample.mq4 for MT4 and Mt5LibExample.mq5 for MT5.
If you are developing MT4 EA, you can download TradingRouterLibsMt4.ex4 and TradingRouterConstsMt4.mqh on the Downloads page.
If you are developing MT5 EA, you can download TradingRouterLibsMt5.ex4 and TradingRouterConstsMt5.mqh on the Downloads page.
TradingRouterLibsMt4.ex4/TradingRouterLibsMt5.ex5 is the Trading Router Library file while TradingRouterConstsMt4.mqh /TradingRouterConstsMt5.mqh has all the constants used by Trading Router Library.
First, create an empty EA file, named Mt4LibExample.mq4 if you use MT4 or Mt5LibExample.mq5 if you use MT5. There are completed Mt4LibExample.mq4 and Mt5LibExample.mq5 files on our Downloads page. But for tutorial purpose, you may create empty Mt4LibExample.mq4 or Mt5LibExample.mq5 file and finish it by following this tutorial.
1. Code the EA
1.1. Import Library Functions
First, import functions of Trading Router Library.
Put TradingRouterLibsMt4.ex4/TradingRouterLibsMt5.ex5 in the same folder of your Mt4LibExample.mq4 or Mt5LibExample.mq5, put TradingRouterConstsMt4.mqh/TradingRouterConstsMt5.mqh in the same folder of your Mt4LibExample.mq4 or Mt5LibExample.mq5.
Then use the following code to import all Trading Router Library functions
1.2. Input and Process Message
We need client token to connect to Trading Router server, we can make an input to get the client token from input. The following is the code
Next, we define a function to process the received message. Our function is simple, it just prints out the received message. You can make your own code here to process the message according to your EA's logic.
1.3. Code OnInit
The first thing in OnInit is "EventSetTimer(1);", which sets timer with 1 second as timeout. We have to do this for our TR_API_OnTimer to be called.
Then we call TR_API_OnInit. The TR_API_OnInit has two arguments, the first arguemnt is the client token. The second argument defines the size of receive message buffer. You can use any number greater than 100 for the size of receive message buffer, if your number is less than 100, Trading Router Library uses the default value of 100. Please refer to Retrieve Messages for detailed explanation of receive message buffer.
The tr_api_init_result is the return value of TR_API_OnInit. Return value RET_INIT_OK means everything is ok. If return value is not RET_INIT_OK, you can fail initialization of your EA by returning INIT_FAILED.
1.4. Code OnDeinit
This is simple, we just call TR_API_OnDeinit() then call EventKillTimer()
1.5. Code OnTimer
We first call TR_API_OnTimer() to check status of connection and get messages.
Then we call TR_API_CheckAndRestoreMessageLost() to check if there are lost messages. In fact you don't need to call TR_API_CheckAndRestoreMessageLost() if you always call TR_API_HasNextMessage and TR_API_GetNextMessage after calling TR_API_OnTimer or TR_API_OnChartEvent. Please refer to Retrive Messages for detailed explanation
We then use TR_API_HasNextMessage() and TR_API_GetNextMessage() to check and get messages. We use while loop so that we can get all messages. We call ProcessMessage to process the received message, which just prints out the message. You can define your ProcessMessage with your own logic.
Finally, we check the return value of TR_API_OnTimer(). For some return values we can just ignore them, for other return values, we are recommended to stop the EA by calling ExpertRemove(). Please refer to TR_API_OnTimer Introduction for detailed explanation about the return value of TR_API_OnTimer.
1.6. Code OnChartEvent
we first call TR_API_OnChartEvent with the same paramters passed in by OnChartEvent.
Then we call TR_API_CheckAndRestoreMessageLost() to check if there are lost messages. In fact you don't need to call TR_API_CheckAndRestoreMessageLost() if you always call TR_API_HasNextMessage and TR_API_GetNextMessage after calling TR_API_OnTimer or TR_API_OnChartEvent. Please refer to Retrive Messages for detailed explanation
We then use TR_API_HasNextMessage() and TR_API_GetNextMessage() to check and get messages. We use while loop so that we can get all messages. We call ProcessMessage to process the received message, which just prints out the message. You can define your ProcessMessage with your own logic.
2. Test Your EA
You can test your Mt4LibExample.mq4/Mt5LibExample.mq5 by using the Test Alert function of your Trading Router account.
You compile the Mt4LibExample.mq4/Mt5LibExample.mq5 into an EA, then launch this EA on your MT4/5 and input your client token. Then you send a message with your master token on the Test Webhook page of your Trading Router account. Then you check the Experts log of your MT4/5 to see if your EA receives this message. As our ProcessMessage() function just prints out the message, you will see the message in Experts log.
For example, you send a message token=masterxxxxxxxxxxxxxx,signal=test,m1=k1,price=1.12 (masterxxxxxxxxxxxxxx should be relaced with your master tokn)
Then your MT4/5 Experts log should have this message, Receive Message SIGNAL=TEST|PRICE=1.12|M1=k1|
