Bitnomial Transfer Protocol

Bitnomial Transfer Protocol (BTP) messages are made up of a standardized binary header and body. The header describes how the body is encoded.

Types

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.

Header

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 ID

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.

Body Encoding

The body encoding describes how to parse the body of the BTP message and may have the following values:

• OE: Order Entry Protocol
• PF: Pricefeed Protocol
• LG: Login Protocol
• MS: Market State Protocol
• HB: Heartbeat Message
• DN: Disconnect Message

Version

• BTP Version 2

Versions will be updated according to the following guidelines:

• Breaking Changes
  • Updated or deleted messages
  • Updated/Added fields
  • Any header change
• Non-Breaking Changes
  • New message types (clients should skip ahead by body length when they find an unexpected message type)

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.

Heartbeat Message

• Body encoding 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

Disconnect Message

• Body encoding 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

Disconnect Reason

Value	Reason
0x01	Sequence ID fault
0x02	Heartbeat fault
0x03	Unused (reserved)
0x04	Messaging rate exceeded (reserved)
0x05	Failed to parse message