> For the complete documentation index, see [llms.txt](https://docs.sfox.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sfox.com/websocket-api/market-data/order-book-delta-websocket-api.md).

# Order Book Delta WebSocket API

## Overview

The Order Book Delta feed provides real-time incremental updates for a specified currency pair. Use the first snapshot message as the authoritative starting state, then apply each sequential update message to maintain a synchronized local order book.

This feed uses the same WebSocket connection and subscription model as the [existing Order Book feed](https://docs.sfox.com/websocket-api/market-data/order-book)\*. The existing feed publishes full snapshots; the delta feed publishes both snapshot and update messages, with update messages containing only the levels that have changed.

## Subscribe

Subscribe using the feed name orderbook.delta.\<pair>, where \<pair> is the lowercase currency pair.

```
{
  "type": "subscribe",
  "feeds": ["orderbook.delta.btcusd"]
}
```

## Message format

| pair           | string  | Currency pair for the order book, for example btcusd.                  |
| -------------- | ------- | ---------------------------------------------------------------------- |
| type           | string  | Message type: snapshot or update.                                      |
| bids           | array   | Bid levels. Each level is \[price, quantity, liquidity\_source].       |
| asks           | array   | Ask levels. Each level is \[price, quantity, liquidity\_source].       |
| lu             | integer | UNIX timestamp in milliseconds when the order book was last updated.   |
| lp             | integer | UNIX timestamp in milliseconds when the order book was last published. |
| u              | integer | Incrementing update ID used to validate message order within the feed. |
| market\_making | object  | Separate top-of-book maker quotes, grouped into bids and asks.         |

### Order book level format

`[price, quantity, liquidity_source]`

Prices and quantities are represented as strings. For normal order book levels, maintain entries by the combination of side, price, and liquidity source.

## Snapshot message

A snapshot contains the complete normal and market-making state for the feed. Replace both local books in full and store its update ID for validation of the next update.

```
{
  "pair": "btcusd",
  "type": "snapshot",
  "bids": [
    ["92567.89", "2.34", "ox"],
    ["92566.12", "0.875", "ox"],
    ["92550.00", "15", "coinbase"]
  ],
  "asks": [
    ["92568.45", "1.12", "ox"],
    ["92570.00", "3.45", "ox"],
    ["92585.20", "0.5", "kraken"]
  ],
  "lu": 1737568923478,
  "lp": 1737568924001,
  "u": 10000,
  "market_making": {
    "bids": [
      ["92567.50", "2.34", "ox"],
      ["92549.80", "15", "coinbase"]
    ],
    "asks": [
      ["92568.80", "1.12", "ox"],
      ["92585.60", "0.5", "kraken"]
    ]
  }
}
```

## Update message

An update includes only levels that changed. Omitted levels and liquidity sources remain unchanged. A quantity of "0" removes the corresponding entry.

```
{
  "pair": "btcusd",
  "type": "update",
  "bids": [
    ["92567.89", "1.980", "ox"],
    ["92540.00", "0.420", "coinbase"],
    ["92566.12", "0", "ox"]
  ],
  "asks": [
    ["92568.45", "0.900", "ox"],
    ["92600.00", "2.000", "ox"]
  ],
  "lu": 1737568931123,
  "lp": 1737568931500,
  "u": 10001,
  "market_making": {
    "bids": [["92567.50", "1.980", "ox"]],
    "asks": [["92568.80", "0.900", "ox"]]
  }
}
```

### Apply normal order book updates

1. Locate the entry using side, price, and liquidity source.
2. If quantity is non-zero, insert the level or replace its current quantity.
3. If quantity is "0", remove the level.
4. Keep all levels omitted from the message unchanged.

## Synchronize with update IDs

Every message includes an update ID in u. Validate update IDs only against messages from the same feed, such as `orderbook.delta.btcusd`.

### When a snapshot is received

1. Replace the entire local normal order book with the message's bids and asks.
2. Replace the entire local market-making book with `market_making.bids` and `market_making.asks`.
3. Accept the snapshot regardless of whether its update ID is sequential from the preceding message.
4. Store the snapshot's update ID and use it to validate the next update.

### When an update is received

1. Confirm that the message's u equals the previously accepted u + 1.
2. If the update ID is sequential, apply the normal and market-making deltas.
3. If the update ID is not sequential, do not apply that message or any later updates from the feed.
4. Unsubscribe and subscribe again to start a new feed, then rebuild local state from a new snapshot.

**Important:** A gap, duplicate, or out-of-order update means local state can no longer be trusted. Resynchronize before applying further updates.

## Market-making book

`market_making` is a separate top-of-book view. It contains at most one maker bid and one maker ask per liquidity source and is independent from the normal bids and asks arrays.

Market-making prices are maker-fee-adjusted and may differ from the same source's levels in the normal order book.

| snapshot | Replace the full bids and asks state.  | Replace the full bids and asks maps.    |
| -------- | -------------------------------------- | --------------------------------------- |
| update   | Apply only the supplied level changes. | Apply only the supplied source changes. |

### Maintain market-making state

* Maintain separate bid and ask maps keyed by liquidity source, not by price.
* On a snapshot, replace both maps in full.
* On an update, upsert each supplied source on the indicated side.
* If quantity is "0", remove that source's quote on the indicated side.
* Sources omitted from an update remain unchanged.
* An empty bids or asks array means there were no changes on that side.

### Market-making removal example

```
{
  "pair": "btcusd",
  "type": "update",
  "bids": [],
  "asks": [],
  "lu": 1737568935000,
  "lp": 1737568935100,
  "u": 10002,
  "market_making": {
    "bids": [["92567.50", "0", "ox"]],
    "asks": []
  }
}
```

This update removes the ox market-making bid. The `coinbase` market-making bid and all market-making asks remain unchanged.

<br>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sfox.com/websocket-api/market-data/order-book-delta-websocket-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.