Serialising and Deserialising Messages¶
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.
"keyOne": [1, 2, 10,],
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 (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
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
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.
1 2 3 4
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.
ProtoMessage has the following structure.
1 2 3 4 5
The structure contains two mandatory fields.
payloadType. Contains the
ProtoPayloadTypeID. This field denotes the type of the Protobuf object serialised in the
payload. Contains the actual serialised Protobuf message that corresponds to
One other field is optional.
clientMsgId. Contains the message ID which is assigned by the client.
The actual `ProtoMessage`` definition looks as follows.
1 2 3 4 5 6 7 8
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 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 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 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 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
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
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.