Skip to content

Serialising and Deserialising Messages

To serialise/deserialise messages sent to and from the cTrader backend, you can use either Protocol Buffers (Protobufs) or JSON (JavaScript Object Notation).

Protobufs vs JSON

You may want to consider using JSON in the following cases.

  • If you want to simplify integration as much as possible. JSON is easy-to-use, allowing you to serialise messages into human-readable strings.
  • If you have used JSON in the past when integrating with other APIs. In that case, you may want to stick to the format that you are most familiar with.

In contrast, you may choose to use Protobufs in the following cases.

  • If you want to make your integration as lightweight as possible. Protobuf messages are compact and, therefore, serialisation/deserialisation is faster compared to JSON.
  • If you intend to mostly rely on the official SDKs as they provide helpful methods and classes that you can use to abstract the most complex parts of working with Protobufs.

Open API Messages

All messages you can use in your integration can be found in the messages Github repo.

Below, we define each method of serialisation/deserialisation in detail.


JSON objects can be defined as simple key-value pairs. Note that keys are always strings while values can be of different data types as shown in the below example.

    "clientMsgId": "cm_id_2",
    "payloadType": 2100,
    "payload": {
        "keyOne": [1, 2, 10,],
        "keyTwo": "valueTwo",

In the example, the value of the "clientMsgId" key is a string while the value of the "payloadType" key is an integer. The "payload" key contains another JSON object which is nested in the body of the 'parent' object. The value of the "payload.keyOne" key is a list of integers.

Connecting to the Required Port

Note that you can only operate with JSON if you connect to port 5036 when establishing a connection with the cTrader backend.

For a tutorial on how you can send/receive JSON, click here.

Protocol Buffers

Protocol Buffers (or Protobufs) offer a language and platform-neutral, extensible mechanism for serialising structured data. By using Protobufs, you can encode structured data in an efficient yet extensible format.

With Protobufs, you only need to define how you want your data to be structured once. This is done by specifying Protobuf message types in .proto files.

Each Protobuf message is a record of information containing a series of name-value pairs. Below, you can find a basic example of a .proto file that defines a message containing information about a person.

message Person {

    required string name = 1;  
    required int32 id = 2;  
    optional string email = 3;  

    enum PhoneType {  
        MOBILE = 0;  
        HOME = 1;  
        WORK = 2;  

    message PhoneNumber {  
       required string number = 1;  
       optional PhoneType type = 2 [default = HOME];  

    repeated PhoneNumber phone = 4;  

As you can see, the message format is simple. Each message type has one or more uniquely numbered fields, and each field has a name and a value type, where value types can be numbers (integer or floating-point), booleans, strings, raw bytes, or even (as in the example above) other Protocol Buffer message types, allowing you to structure your data hierarchically.

You can find more information about writing .proto files in the Protocol Buffer Language Guide.

You can learn more about Protocol Buffers here.


Note that the cTrader Open API uses Protocol Buffers version 2 syntax. However, you can still use the latest versions of your chosen Protocol Buffers compiler/SDKs as they are backward compatible and work with both version 2 and version 3 message files.

For a tutorial on sending/receiving Protobufs, click here.


When working with Protobufs, you will be sending and receiving ProtoMessage objects designed by Spotware.

To handle network fragmentation, sending messages uses the following frame structure.

 | Message Length (4 bytes) | Serialized ProtoMessage object (byte[]) |  
                            |<---------- Message Length ------------->|


The system architecture is little-endian (that is, little end first), which means that you must reverse the length bytes when sending and receiving data.

Each ProtoMessage has the following structure.

 | int32 payloadType    |  
 | byte[] payload       |  
 | string clientMsgId   |  

The structure contains two mandatory fields.

  • payloadType. Contains the ProtoPayloadType ID. This field denotes the type of the Protobuf object serialised in the payload field.
  • payload. Contains the actual serialised Protobuf message that corresponds to payloadType.

One other field is optional.

  • clientMsgId. Contains the message ID which is assigned by the client.

The actual `ProtoMessage`` definition looks as follows.

message ProtoMessage {  
    required uint32 payloadType = 1; //Contains the ID of the ProtoPayloadType or other
    custom PayloadTypes (e.g. ProtoCHPayloadType).  
    optional bytes payload = 2; //The serialised Protobuf message that corresponds to
    the payloadType.  
    optional string clientMsgId = 3; //The request message ID which is assigned by the

Naming Convention

The Protobuf messages that form the cTrader Open API can be categorised into the following types.

  • Request messages
  • Response messages
  • Event messages
  • Model messages
Request Messages

Request messages are used to ask the cTrader backend for information or perform various operations.

Request messages are marked with Req at the end of their respective names. For example, the ProtoOAAssetListReq message requests the cTrader backend to return a list of all assets available for trading to a currently authorised account.

Response Messages

Response messages mark data that is received from the cTrader backend.

Response messages are marked with Res at the end of their respective names. As an illustration, the ProtoOAAssetListRes message has a repeated field (asset) that contains all assets that the currently authorised account can trade.

Event Messages

Event messages asynchronously notify all their subscribers that a particular event has been triggered.

Event messages are marked with Event at the end of their respective names. For instance, the ProtoOAMarginChangedEvent is sent every time when the amount of margin allocated to a specific position is changed.

Model Messages

Model messages describe the entities that form the domain model in the cTrader backend.

The names of model messages always end with the name of the entity that they are defining. As an example, the ProtoOAAsset message defines the Asset entity.

Messages Repository

You can download the latest version of the cTrader Open API Protocol Buffers message files from this repository.

We recommend you follow the messages repository if you want to get notified whenever a new version of the message files is released.

Compiling Protobuf Messages

Once you attain the required Protobuf messages, you can run the Protobuf compiler for your chosen language on the .proto files defining these messages. On success, the compiler will generate data access classes in your preferred language.

These classes provide simple accessors for each field (such as name() and set_name()) as well as methods for handling serialisation and deserialisaition. The name of each class should match the full name of each message that was compiled. At this point, you can freely use the generated classes in your application to populate, serialise and deserialise Protobuf messages.

To learn more about compiling protobuf messages using your language of choice, click here.

Last update: September 29, 2023