Send and receive messages¶

Introduction¶

This article serves as an introduction to using FIX API for anyone interested in interacting with Spotware cServer using FIX.

In this article, we will use a C# example to describe in detail the principles of how to construct a FIX message, send it to the server and receive the response. This example is by no means a bullet-proof application and was kept as simple as possible to allow programmers to easily understand the concept of using FIX API messages.

In order to establish and maintain proper communication with the server and proper handling of the responses, additional functionality is required, which was skipped for the sake of simplicity and clarity. We will deal with these subjects in future articles.

Code sample¶

You can find the code sample discussed in this article on our GitHub repository

Overview of FIX communication¶

A FIX message is just a string composed of sets of numerical tags and values separated by a vertical bar (|). Each tag represents a different field for which a certain set of values is allowed. Below you can see a sample FIX message which requests authentication from the server.

8=FIX.4.4|9=126|35=A|49=theBroker.12345|56=CSERVER|34=1|52=20170117- 08:03:04|57=TRADE|50=any_string|98=0|108=30|141=Y|553=12345|554=passw0rd!|10=131|

As you can see, the repeatable pattern found in each FIX message is:

Tag=Value|Tag=Value|Tag=Value|...

Depending on the purpose of each message, a different set of tags and values is required each time. The tags and values required for each message are described in detail in the cTrader FIX engine Rules of Engagement (always check for the latest rules of engagement).

In a similar way, responses are sent back from the server. Below you can see the response of the server for the above message.

8=FIX.4.4|9=106|35=A|34=1|49=CSERVER|50=TRADE|52=20170117- 08:03:04.509|56=theBroker.12345|57=any_string|98=0|108=30|141=Y|10=066|

The steps involved in the process of communicating with a FIX server are the following:

1. Construct a FIX message

2. Transmit a FIX message

3. Receive a FIX message

4. Parse a FIX message

A raw FIX message is not a very readable format since it was designed with efficiency in mind rather than understandability. Therefore, for each software application there will always be a process of translating information provided into the respective FIX message.

In our C# sample application we have created a class for handling the message construction as well as functions for creating FIX messages based on the relevant information.

After the messages have been constructed, they are transmitted between a server and a client over the internet through network sockets. When the messages are received, they need to be parsed to be presented in a readable format.

In this article we will cover the process of construction, transmission and receipt of the reply. We will deal with parsing in a future article.

Construct a FIX message¶

Message structure¶

In our sample application we have created a class responsible of creating FIX messages. The class is called MessageConstructor and can be found in the FIX API Library project.

The MessageConstructor is initialised with the following parameters:

1. Host(*) – the address where our cServer is located.

2. Username(*) – the account number

3. Password(*) – the password

4. SenderCompID(*) – it is provided in the FIX API form of cTrader. It is in the format

5. SenderSubID* – it is the second part of SenderCompID

6. TargetCompID(*) – it is provided in the FIX API form of cTrader (usually it is cServer)

You can find this information in your cTrader FIX API form.

After we have initialised a MessageConstructor then we are ready to construct FIX API messages.

All the messages are constructed in a similar manner. Below there is a code sample of constructing a Logon message.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

public  string LogonMessage(SessionQualifier qualifier, int messageSequenceNumber,

            int  heartBeatSeconds,  bool  resetSeqNum)

       {

            var  body = new  StringBuilder ();

        //Defines a message encryption scheme.Currently, only transportlevel security

       //is supported.Valid value is "0"(zero) = NONE_OTHER (encryption is not used).

           body.Append( "98=0|");

            //Heartbeat interval in seconds. 

           //Value is set in the 'config.properties' file (client side) as 

         // 'SERVER.POLLING.INTERVAL' . 

           //30 seconds is default interval value. If HeartBtInt is set to 0, 

         no heartbeat message  

           //is required.

           body.Append( "108="  + heartBeatSeconds +  "|");

           // All sides of FIX session should have

           //sequence numbers reset. Valid value

            //is "Y" = Yes(reset). 

            if  (resetSeqNum)

               body.Append( "141=Y|");

            //The numeric User ID.  User is linked to SenderCompID (#49) value (the

            //user's organization). 

           body.Append( "553=" + _username + "|");

           //User Password

           body.Append( "554=" + _password + "|");

            var  header = ConstructHeader(qualifier, 

         SessionMessageCode( SessionMessageType.Logon), messageSequenceNumber,

          body.ToString());

            var  headerAndBody = header + body;            

            var  trailer = ConstructTrailer(headerAndBody);

            var  headerAndMessageAndTrailer = header + body + trailer;

            return  headerAndMessageAndTrailer.Replace("|", "\u0001");

       }

You can see that we first construct the body part, then we pass it to the header function and at last we pass both parts into the trailer function. These 3 parts are detailed below.

The message construction process is just the addition of the required tags, values and separators into a string.

Body¶

First we will start by describing the body construction, since the body of the message needs to be created first. We can see an example above (creating the Logon message).

We start by initialising a StringBuilder class and we append the tags one-by-one based on the function inputs. Based on the message type, the body must be composed of different sets of tags, some of them being mandatory and others being optional.

You can find the structure of each message in our Rules of Engagement (/FIX).

Then we create a header for a Logon message and append to it the body of the message. Finally, using the headerAndBody string we generate the trailer. Following on, we will see how we construct a header and a trailer.

Header¶

The header is the first part of the FIX message and it is composed of the following fields (same for all the messages):

1. BeginString – the begin string defines the FIX protocol version and in our case is fixed to FIX4.4.
2. BodyLength – the body length states the length of the message in characters, excluding the BeginString, the BodyLength and the trailer fields.
3. MsgType – in this field we define the message type, so that the receiver knows how to parse the body.
4. SenderCompID – here we set the SenderCompID.
5. TargetCompID – this is the target of our message. In our case, it will always be cServer.
6. SenderSubID – the trader login.
7. MsgSeqNum – this is the sequence number of the message. It needs to be increased for each message sent in the same session.
8. Sending Time – the time of message transmission.

Below you can see the ConstructHeader function, responsible for constructing the headers.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

private  string ConstructHeader(SessionQualifier qualifier, string type,

         int  messageSequenceNumber, string bodyMessage)

    {

         var  header = new  StringBuilder ();

        // Protocol version. FIX.4.4 (Always unencrypted, must be first field 

        // in message.

        header.Append( "8=FIX.4.4|");

         var  message = new  StringBuilder ();

        // Message type. Always unencrypted, must be third field in message.

        message.Append( "35=" + type + "|");

        // ID of the trading party in following format: <BrokerUID>.<Trader Login> 

        // where BrokerUID is provided by cTrader and Trader Login is numeric 

        // identifier of the trader account.

        message.Append( "49="  + _senderCompID +  "|");  

        // Message target. Valid value is "CSERVER"

        message.Append( "56="  + _targetCompID +  "|");  

        // Additional session qualifier. Possible values are: "QUOTE", "TRADE".

        message.Append( "57="  + qualifier.ToString() +  "|");  

        // Assigned value used to identify specific message originator.

        message.Append( "50="  + _senderSubID +  "|");

        // Message Sequence Number

        message.Append( "34="  + messageSequenceNumber +  "|");

         // Time of message transmission (always expressed in UTC(Universal Time  

        // Coordinated, also known as 'GMT').

        message.Append("52=" + DateTime.UtcNow.ToString("yyyyMMdd-HH:mm:ss") + "|");

         var  length = message.Length + bodyMessage.Length;

        // Message body length. Always unencrypted, must be second field in message.

        header.Append( "9=" + length + "|");

        header.Append(message);      

         return  header.ToString();

    }

Trailer¶

The trailer is just a tag containing the checksum of the rest of the message.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

private  string ConstructTrailer(string message)

       {

            //Three byte, simple checksum.  Always last field in message; i.e. serves,

           //with the trailing<SOH>, 

           //as the end - of - message delimiter. Always defined as three characters

           //(and always unencrypted).

            var  trailer = "10=" + CalculateChecksum(message.Replace("|", "\u0001").ToString()).ToString().PadLeft(3, '0') + "|";

            return  trailer;

       }

System messages¶

Our sample contains functions that return the following system messages:

• Heartbeat: MessageConstructor.HeartbeatMessage()
• Test request: MessageConstructor.TestRequestMessage()
• Logon: MessageConstructor.LogonMessage()
• Logout: MessageConstructor.LogoutMessage()
• Resend request: MessageConstructor.ResendMessage()
• Reject: MessageConstructor.RejectMessage()
• Sequence reset: MessageConstructor.SequenceResetMessage()

Application messages¶

Our sample contains functions that return the following system messages:

• Market data request: MessageConstructor.HeartbeatMessage()
• Market data snapshot/full refresh: MessageConstructor.MarketDataSnapshotMessage()
• Market data incremental refresh: MessageConstructor.MarketDataIncrementalRefreshMessage()
• New order single: MessageConstructor.NewOrderSingleMessage()
• Order status request: MessageConstructor.OrderStatusRequest()
• Execution report: MessageConstructor.ExecutionReport()
• Business message reject: MessageConstructor.BusinessMessageReject()
• Request for positions: MessageConstructor.RequestForPositions()
• Position report: MessageConstructor.PositionReport()

Send a message and receive a response¶

In order to send a FIX message to cServer you first need to establish a connection with the server. You can do this by creating a TcpClient. In our case we create two clients, since price quotation messages and trade messages are handled by different ports on the server.

Then, we need to get the two streams on which the messages will be sent. This process takes place in the form's constructor as shown below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

public  frmFIXAPISample()
{

   InitializeComponent();

    _priceClient = new  TcpClient( _host, _pricePort);           

   _priceStream = _ priceClient.GetStream ();            

   _tradeClient =  new  TcpClient ( _host, _tradePort);

   _tradeStream = _ tradeClient.GetStream ();

   _messageConstructor = new  MessageConstructor( _host, _username,

       _password, _senderCompID, _senderSubID, _targetCompID);

}

In the constructor, we also initialise a MessageConstructor class which will be used for generating the messages.

Next, to send the messages, we created two different functions, SendPriceMessage() and SendTradeMessage(). Each takes the FIX message as an input and then calls the SendMessage() function with the message and respective stream as an input.

The SendMessage() function works as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

private  string SendMessage(string message,  NetworkStream  stream)
{
    var  byteArray =  Encoding.ASCII.GetBytes (message);

    stream.Write(byteArray, 0, byteArray.Length);

    var  buffer = new byte[1024];

    int  i = 0;

    while  (!stream.DataAvailable && i < 100)
    {
         Thread.Sleep ( 100);
         i++;
    }

    if( stream.DataAvailable )
        stream.Read(buffer, 0, 1024);

    _messageSequenceNumber++;

    var  returnMessage = Encoding.ASCII.GetString(buffer);

    return  returnMessage;
}

The detailed steps are as follows:

1. Encode the message to a byte array.
2. Write the byte array on the stream.
3. Read the reply from the stream.
4. Increase the message sequence number.
5. Encode the message into a string.

The function should return the FIX message sent by the server.

As you would assume, you cannot show a raw FIX message to the user, so an additional step of parsing the incoming message should be developed.

Conclusion¶

This application is a brief demonstration on how to communicate with cServer using FIX messages. It is just an example illustrating the concepts of FIX Protocol and it is by no means a full FIX engine. If you would like to avoid building your own FIX engine, you might consider using one of the third-party FIX engines available.