Bitnomial Transfer Protocol (BTP) messages are made up of a standardized binary header and body. The header describes how the body is encoded.
Numerical fields are little endian byte order.
char
: 1 byte ASCII character.byte[]
: An array of bytes.uint
: Unsigned 2, 4, or 8 byte little endian integer depending on field’s byte length.int
: Signed 2, 4, or 8 byte little endian integer depending on field’s byte length.Byte Offset | Byte Length | Type | Name | Description |
---|---|---|---|---|
0 | 2 | byte[] | protocolId | ASCII string BT for “Bitnomial Transfer Protocol”. |
2 | 2 | uint16 | version | BTP protocol version. See Version |
4 | 4 | uint32 | sequenceId | Monotonically incremented message number per sender. See Sequence ID |
8 | 2 | byte[] | bodyEncoding | ASCII string for body encoding. See Body Encoding |
10 | 2 | uint16 | bodyLength | Length, in bytes, of the following message body. |
12 |
Sequence IDs sequentially identify each message in a single direction of a connection. Sequence IDs are monotonically
incremented so repeat sequence IDs identify a duplicate message while a gap identifies missed messages. Sequence IDs
start at 1
for disambiguation with NULL
. If an invalid Sequence ID fault is detected the connection is disconnected
with a Disconnect message.
For example, a Login Requests, as the first message in the stream, must have a Sequence ID of
1
. Subsequent messages must monotonically increment the Sequence ID.
The body encoding describes how to parse the body of the BTP message and may have the following values:
OE
: Order Entry ProtocolPF
: Pricefeed ProtocolLG
: Login ProtocolMS
: Market State ProtocolHB
: Heartbeat MessageDN
: Disconnect Message2
Versions will be updated according to the following guidelines:
Additionally, all BTP services are versioned together. So, for example, it would
not be valid for the Gateway to have version 2
while the Pricefeed is on version 3
.
The BTP version can be set to a future version for User Acceptability Testing. Connected sessions cannot mix different versions, the version set in the Login message must be used for all subsequent connection messages. Details of new protocol versions can be read in Upcoming Changes.
HB
(See BTP Body Encoding).Heartbeat messages are sent and expected to be received every heartbeatInterval (See Login Request) if no other messages have been sent within the interval. Connections are disconnected with a Disconnect Message if a heartbeat is not received in the interval period.
All BTP connections must send and receive heartbeat messages. Heartbeat messages must always be of the following form:
Field | Value |
---|---|
sequenceId | 0 |
bodyLength | 0 |
Body | Always Empty |
DN
(See BTP Body Encoding).An order entry gateway or pricefeed may disconnect a connection at any time for the following disconnect Disconnect Reasons.
Byte Offset | Byte Length | Type | Name | Description |
---|---|---|---|---|
0 | 1 | uint8 | disconnectReason | See Disconnect Reason |
1 | 4 | uint32 | expectedSequenceId | Sequence ID expected to see next, NULL if not a sequence ID fault. |
5 | 4 | uint32 | actualSequenceId | Sequence ID actually received, NULL if not a sequence ID fault. |
9 |
Value | Reason |
---|---|
0x01 |
Sequence ID fault |
0x02 |
Heartbeat fault |
0x03 |
Unused (reserved) |
0x04 |
Messaging rate exceeded (reserved) |
0x05 |
Failed to parse message |