SBE - Kraken Developers

Kraken US Perps publishes public market data over Simple Binary Encoding (SBE): a compact, fixed-layout binary format designed for low-latency decoding. The protocol is defined by two schemas — a session schema for TLS session negotiation, authentication, subscriptions and keepalive, and a market data schema for instrument definitions, order books, trades and trading status. For an overview of the US Perps APIs and how to connect, see the US Perps guides.

Schemas

Schema	Package	Schema ID	Wire version	Semantic version	Byte order	Role
Session	`Kraken.MarketDataAPIProto`	33	3	5.0.0	littleEndian	TLS session negotiation, authentication, subscriptions and keepalive
Market data	`Kraken.MarketDataProto`	34	11	10.0.0	littleEndian	Instrument definitions, books, trades and trading status

Every SBE message starts with the standard SBE messageHeader (blockLength:uint16, templateId:uint16, schemaId:uint16, version:uint16). Use schemaId and templateId to select the decoder. On the wire, each SBE message is carried inside a TCP frame that adds a framing header in front of the SBE messageHeader — see Framing.

Compatibility rule: new optional or versioned fields require a schema version increase. Existing field and template IDs are never reused or reordered.

Connections

The session uses two connections. Each compId allows one active live connection and one active snapshot connection.

Snapshot connection — send a SubscriptionRequest with subscriptionRequestType = Snapshot to receive one snapshot (instrument definitions, order book or, on Spot and Futures only, trading session status).
Live connection — send Subscribe or Unsubscribe to start or stop incremental delivery for a feed.

Feeds are selected with MarketDataFeed: InstrumentDefinition, OrderBookL3, Trade, InstrumentStatus and TradingSessionStatus.

TradingSessionStatus applies to Spot and Futures, not to US Perps. US Perps does not expose a global trading session status. It provides the status per instrument: use the InstrumentStatus feed, and the status carried by each InstrumentDefinition.

Framing

Each TCP frame carries exactly one SBE message, in both directions. TLS protects the TCP stream but does not change the frame bytes.

bytes 0..5       SOFH
bytes 6..13      Kraken TCP header
bytes 14..21     SBE message header
bytes 22..end    SBE message body

Offset	Size	Field	Type	Byte order	Description
0	4	`messageLength`	`uint32`	big endian	Total frame size in bytes, including the SOFH and the Kraken TCP header
4	2	`encodingType`	`uint16`	big endian	`0xEB50`: Kraken TCP header followed by an SBE 1.0 message in little endian byte order
6	8	`SendingTime`	`int64`	little endian	Unix epoch nanoseconds (Kraken TCP header)
14	8	SBE `messageHeader`	composite	little endian	`blockLength`, `templateId`, `schemaId`, `version`
22	variable	SBE message body		little endian	Root block, repeating groups and variable-length data

The first six bytes are the Simple Open Framing Header (SOFH). The eight-byte Kraken TCP header is a Kraken extension to the usual SOFH and SBE layout: a generic SOFH reader must skip those eight bytes before decoding the SBE messageHeader.

SendingTime is diagnostic only. The gateway stamps a shared market data frame once, when it enters the shared fanout, so every client sees the same time for that frame. It is not a kernel transmit timestamp, and it must not be used for authentication or replay checks.
Reading frames. TCP may split one frame across several reads or return several frames in one read. Read the full SOFH, check its fields, then wait until messageLength bytes have arrived.
Protocol errors. An unsupported encodingType, a messageLength below 22 (the minimum frame size), or a messageLength above the service limit is a protocol error. Kraken closes the connection instead of skipping the frame.
Repeating groups. Before reading a group, verify that its block length and entry count fit inside the enclosing frame. Check the size arithmetic for overflow.

Frame counting

Frame counting is implicit: there is no sequence number on the wire for session control.

Each direction has its own counter. Both start at 1 on a new connection, never wrap, and have no daily reset.
A sender advances its counter after it successfully sends a complete frame. A receiver advances its counter after it validates the complete SOFH and SBE frame.
Every frame counts, including negotiation, subscription, heartbeat, termination and market data messages. Zero means no frame has been received.
AdminHeartbeat.lastReceivedClientSequence reports the latest client frame Kraken accepted, and SubscriberHeartbeat.lastReceivedServerSequence reports the latest server frame the client processed.
An acknowledgement greater than the number of frames its peer has sent is a protocol violation. A lower value is allowed while frames are in flight or waiting to be processed; persistent lag is handled by the service’s slow consumer limits.
Heartbeat acknowledgements never request a replay. After a broken connection, start a new session and request a fresh snapshot.

Session schema (ID 33)

Template	Message	Description
1	Negotiate	Opens and authenticates a session.
2	NegotiationResponse	Confirms a successful negotiation.
3	NegotiationReject	Rejects a negotiation.
4	AdminHeartbeat	Keepalive from Kraken.
5	SubscriberHeartbeat	Keepalive from the client.
6	Terminate	Ends the session.
7	SubscriptionRequest	Requests a snapshot, or starts or stops incremental delivery.
8	SubscriptionResponse	Answers a SubscriptionRequest.

Enumerations and encodings: Session enums & encodings.

Market data schema (ID 34)

Template	Message	Description
1	InstrumentDefinitionSnapshot	Instrument definitions, one per message, within a snapshot cycle.
2	OrderBookIncremental	Order-by-order (L3) book updates.
3	TradeIncremental	Trades.
4	OrderBookSnapshot	Full L3 book snapshot, in chunks.
5	InstrumentStatusIncremental	Live instrument trading-status changes.
6	TradingSessionStatusIncremental	Trading session status changes. Spot and Futures only; not used on US Perps.
7	InstrumentDefinitionIncremental	Instrument additions, modifications and deletions.
10	TradingSessionStatusSnapshot	Current trading session status. Spot and Futures only; not used on US Perps.

Enumerations and encodings: Market data enums & encodings.

Sequencing

Incremental feeds carry contiguous per-instrument (or per-feed) sequence numbers starting at one — orderBookSeq, tradeSeq, instrumentStatusSeq, instrumentDefinitionSeq and tradingSessionSeq. Snapshots carry the last sequence number they include (for example lastOrderBookSeqProcessed), so you can apply buffered incrementals with a higher sequence number on top of the snapshot.

Gap recovery

There is no message replay. When you detect a gap, request a new snapshot on the snapshot connection and rebuild from it:

Feed	Gap recovered by
`OrderBookL3`	`OrderBookSnapshot`
`InstrumentDefinition`	`InstrumentDefinitionSnapshot`
`InstrumentStatus`	`InstrumentDefinitionSnapshot`, which carries each instrument’s current status and its `lastInstrumentStatusSeqProcessed`
`TradingSessionStatus` (Spot and Futures only)	`TradingSessionStatusSnapshot`
`Trade`	Not recoverable

There is no trade snapshot. A gap in tradeSeq can be detected, but trades missed during the gap, or while you were disconnected, cannot be recovered from a book snapshot or any other feed.

US Perps API overview

How order entry, market data and drop copy fit together.

Unified FIX v2

FIX 4.4 order entry for US Perps.

Drop Copy

FIX 4.4 copy of every execution report on your account.

US Perps connectivity

Connectivity and colocation documents.

​Schemas

​Connections

​Framing

​Frame counting

​Session schema (ID 33)

​Market data schema (ID 34)

​Sequencing

​Gap recovery

​Related

US Perps API overview

Unified FIX v2

Drop Copy

US Perps connectivity

Schemas

Connections

Framing

Frame counting

Session schema (ID 33)

Market data schema (ID 34)

Sequencing

Gap recovery

Related