BTP Overview
Bitnomial Transfer Protocol (BTP) is the Exchange's low latency, direct market access, binary protocol for order entry and price feeds. 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 Request, 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 EntryPF: PricefeedLG: LoginMS: Market StateHB: Heartbeat MessageDN: Disconnect Message
Version
- BTP Version
3
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.
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.
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 |
Start Trading
Trade US Perpetual Futures, Physical Futures, and Options on the Bitcoin Complex®, XRP, ETH, SOL, and more.
Signing up with Bitnomial, Inc. requires additional verification with an FCM to trade futures. Futures accounts are offered by Bitnomial Clearing, LLC, a CFTC-registered FCM and NFA member. Trading in futures involves substantial risks. You should only trade in financial products that you are familiar with and understand the associated risks, and after carefully considering whether such trading is suitable in light of your investment experience, financial position, and investment objectives. Leverage in futures trading can work for you or against you. The risk of loss using leverage can exceed your initial investment amount. See Bitnomial entity affiliation and registration disclosures and FCM financial and risk disclosures.