> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kraken.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SBE

> Simple Binary Encoding (SBE) market data for Kraken US Perps — session negotiation and public market data wire contract

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](/exchange/guides/us-perps/overview).

## 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](#framing).

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

## 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`](/exchange/api-reference/sbe/session-types#marketdatafeed): `InstrumentDefinition`, `OrderBookL3`, `Trade`, `InstrumentStatus` and `TradingSessionStatus`.

<Note>
  **`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`.
</Note>

## Framing

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

```text theme={null}
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](/exchange/api-reference/sbe/negotiate) | Opens and authenticates a session. |
| 2 | [NegotiationResponse](/exchange/api-reference/sbe/negotiation-response) | Confirms a successful negotiation. |
| 3 | [NegotiationReject](/exchange/api-reference/sbe/negotiation-reject) | Rejects a negotiation. |
| 4 | [AdminHeartbeat](/exchange/api-reference/sbe/admin-heartbeat) | Keepalive from Kraken. |
| 5 | [SubscriberHeartbeat](/exchange/api-reference/sbe/subscriber-heartbeat) | Keepalive from the client. |
| 6 | [Terminate](/exchange/api-reference/sbe/terminate) | Ends the session. |
| 7 | [SubscriptionRequest](/exchange/api-reference/sbe/subscription-request) | Requests a snapshot, or starts or stops incremental delivery. |
| 8 | [SubscriptionResponse](/exchange/api-reference/sbe/subscription-response) | Answers a SubscriptionRequest. |

Enumerations and encodings: [Session enums & encodings](/exchange/api-reference/sbe/session-types).

## Market data schema (ID 34)

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

Enumerations and encodings: [Market data enums & encodings](/exchange/api-reference/sbe/market-data-types).

## 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 |

<Note>
  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.
</Note>

## Related

<CardGroup cols={2}>
  <Card title="US Perps API overview" icon="layer-group" href="/exchange/guides/us-perps/api">
    How order entry, market data and drop copy fit together.
  </Card>

  <Card title="Unified FIX v2" icon="terminal" href="/exchange/api-reference/unified-fix-v2">
    FIX 4.4 order entry for US Perps.
  </Card>

  <Card title="Drop Copy" icon="copy" href="/exchange/api-reference/drop-copy">
    FIX 4.4 copy of every execution report on your account.
  </Card>

  <Card title="US Perps connectivity" icon="server" href="/exchange/guides/us-perps/connectivity">
    Connectivity and colocation documents.
  </Card>
</CardGroup>