​

Downloads

​

Historical XMLs

Previous versions of the SBE Order API schema. Each XML is the final state of that semantic version.

​

What is SBE?

SBE is a compact binary encoding format with fixed-width fields at fixed offsets, in contrast to standard FIX with ASCII-encoded human-readable tag=value pairs. SBE provides:

• Minimizes latency: Binary encoding eliminates text parsing overhead
• Reduces bandwidth: Compact binary representation uses less network bandwidth than text-based protocols
• Provides type safety: Strong typing ensures data integrity
• Fixed offsets: Fields are at fixed positions within each message

​

Message Structure

​

TCP messages

All SBE messages sent over TCP follow a consistent structure:

1. Message Header (32 bytes): Contains protocol identification, message type, sequence numbers, and timing information
2. Message Body: Contains the specific message data fields

Messages are sent over TCP connections and can be bidirectional - clients send requests and receive responses/updates on the same connection. Each message starts with the following 32-byte header:

​

UDP messages

Incremental, snapshot and retransmit channels share the same basic packet and message structure. Each UDP packet will start with a packet header followed by zero or more messages. Each message within the packet will start with a message header. All messages have a sequence number, although only the sequence number of the first message in the packet is specified (in the packet header). Thus the next expected sequence number in the next packet is packet sequenceNum plus messageCount.
Heartbeat packets will have a messageCount of 0 with the next expected sequence number. This same sequence number will be repeated with the first real message. Each UDP packet starts with the following 24-byte packet header: Each message within a packet starts with the following 16-byte header:

​

Key Concepts

Message Type ID: Each message type has a unique messageTypeId (uint16) that identifies its purpose. The messageTypeId is located in field 4 of the message header and is used to determine how to parse and process the message body. For example, a NewOrderRequest message has messageTypeId = 100. When the gateway receives a message with messageTypeId = 100 in the header, it knows to parse the message body as a NewOrderRequest containing fields such as clientOrderId, correlationId, limitPrice, amount, etc. Message Types: Each message type has a unique messageTypeId that identifies its purpose (e.g., NewOrderRequest (100), NewOrderResponse (200), OrderFilled (300)). Sequence Numbers: Every TCP message header includes:

• sequenceNum: Sequence number of the current message
• lastProcessedSeqNum: Sequence number of the last message received from the client (in responses)

Sequence numbers persist across reconnects unless reset. They are used for ordering, gap detection, and client-initiated recovery via ResendRequest. They are not a full FIX recovery session. In particular:

• The gateway never sends ResendRequest to the client.
• On reconnect with resetSeqNum=0, a too-low inbound seqNum is rejected (LoggedOut with sequence number too low); a gap (too high) is ignored.
• The exchange resets sequence numbers weekly on Saturday at approximately 12:00 US Central and disconnects sessions with reason SEQUENCE_RESET. Reconnect with resetSeqNum=1.

See Sequence numbers for the full logon and reset rules. Correlation IDs: Order entry messages (requests, responses, rejects, and OrderFilled) contain an 8-byte integer correlationId. Clients can assign any value to correlationId, which is not validated by the server. However, Deribit recommends monotonically increasing the value. correlationId is used for matching responses to requests and for indirectly correlated messages, such as order fill and system cancel notifications. Messages from server to client use the correlationId of either the corresponding request message from the client or of the last related request. Market data messages (order book updates, trades, reference data) do not contain correlation IDs. Protocol ID: All messages start with protocolId = 0xDB to identify the Deribit Starbase protocol.

​

Data Types

All multi-byte fields are encoded in little-endian byte order. SBE uses standard binary data types:

• int8/int16/int32/int64: Signed integers of various sizes
• uint8/uint16: Unsigned integers
• double: 64-bit floating point (used for prices)
• char: Fixed-length character arrays

In addition, Starbase uses the following custom composite types:

• Decimal72 (also referred to as DFP, or Decimal Floating Point): A 9-byte variable-precision quantity encoding defined as an SBE composite of a 64-bit signed integer mantissa and an 8-bit signed integer exponent, where value = mantissa × 10^exponent. The variable exponent provides a wide range of precision across different underlying assets. It is used for quantities throughout the protocol.
• QuantityMantissa: A 64-bit signed integer (int64) representing the mantissa component of a Decimal72 quantity. Used in market data messages where only the mantissa is transmitted (8 bytes).

​

Byte Alignment and Message Padding

The frame length of all outbound messages to the client is rounded up to the nearest multiple of 8. Clients are encouraged to do the same with inbound messages, although this is not required.

​

Clock Synchronization

Deribit exposes PTP (Precision Time Protocol) to clients colocated in LD4, allowing sendTime and transactTime (both nanoseconds since epoch) to be correlated against a client’s own clock. Contact colo-support@coinbase.com for the PTP service agreement.

​

Usage Workflow

1. Connect: Establish a TCP connection to the gateway
2. Authenticate: Authenticate using your API credentials
3. Send Requests: Send binary-encoded request messages
4. Receive Responses: Process binary-encoded response and update messages
5. Handle Sequence: Continue inbound sequence numbers across reconnects (resetSeqNum=0), or reset with resetSeqNum=1. After a successful logon to the same host, send ResendRequest if you need missed outbound events. See Sequence numbers.

​

Order Expiration

When an order expires (e.g., a day order at the close of a trading day or when an instrument expires), an OrderCanceled message is sent via the unsolicited events channel.

​

Rejection Reason Codes

Reject messages in the Starbase Binary API include a reason field that indicates why the request was rejected. The following table lists all possible rejection reason codes: These rejection reason codes are used in the following reject messages:

• NewOrderReject - Field 7 (reason)
• AmendOrderReject - Field 7 (reason)
• MassQuoteResponse - Fields 20 (bidRejectReason) and 21 (askRejectReason)

​

Cancel Reason Codes

The cancelReason field uses a single enumeration across all contexts, indicating why an order was (partially) canceled. Used in:

• NewOrderResponse, Field 14 (cancelReason)
• AmendOrderResponse, Field 13 (cancelReason)
• OrderPlaced, cancelReason field
• OrdersCanceled, Field 3 (cancelReason)
• MassQuoteOrdersPlaced, cancelReason field (per quote entry)