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

# Book Stream

> Stream ten levels of order book depth for token pairs over WebSocket

The `book-stream` endpoint streams ten levels of order book depth per side for a
pair of token mints. See [Market Data Streams](/spot/trading/market-data-streams)
for what the depth means and when to use the stream; this page documents the
message format.

<Info>
  Book levels are **approximations** computed at runtime, on **direct routes
  only**. Each level's size is cumulative from the spot outward.
</Info>

<Note>
  Access to the book stream is gated. Reach out to the team to request access.
</Note>

## Connection

See the [Websockets Overview](/resources/trading-api/websockets/overview#connection)
for endpoint details.

## Subscribe

Send a `subscribe` op with the base and quote mints:

```json theme={null}
{
  "op": "subscribe",
  "base_mint": "So11111111111111111111111111111111111111112",
  "quote_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
}
```

## Unsubscribe

```json theme={null}
{
  "op": "unsubscribe",
  "base_mint": "So11111111111111111111111111111111111111112",
  "quote_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
}
```

## Message Format

Each message is a batch covering one slot. `b` and `a` each carry ten levels,
ordered nearest to spot outward:

```json theme={null}
{
  "u": 425218519,
  "ts": 1780964621,
  "subscribe": [
    {
      "sb": "So11111111111111111111111111111111111111112",
      "sq": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
    }
  ],
  "updates": [
    {
      "sb": "So11111111111111111111111111111111111111112",
      "sq": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "mid": 66.287,
      "tick": 0.0066287,
      "crossed": false,
      "b": [
        { "price": 66.2803713, "cumulative_size_human": 11.275078961 },
        { "price": 66.2737426, "cumulative_size_human": 4030.117529621 }
      ],
      "a": [
        { "price": 66.2936287, "cumulative_size_human": 727.767025378 },
        { "price": 66.3002574, "cumulative_size_human": 1606.23883139 }
      ]
    }
  ]
}
```

### Fields

| Field                       | Type   | Description                                                             |
| --------------------------- | ------ | ----------------------------------------------------------------------- |
| `u`                         | number | Slot the book was computed at                                           |
| `ts`                        | number | Unix timestamp in seconds                                               |
| `skipped`                   | number | Slots skipped before this batch under load. `0` when the stream kept up |
| `updates`                   | array  | Per-pair book updates for this slot                                     |
| `subscribe` / `unsubscribe` | array  | Acknowledgements of subscription changes                                |

Each entry in `updates` has:

| Field     | Type    | Description                                                                                      |
| --------- | ------- | ------------------------------------------------------------------------------------------------ |
| `sb`      | string  | Base mint                                                                                        |
| `sq`      | string  | Quote mint                                                                                       |
| `mid`     | number  | Mid price, quote per base                                                                        |
| `tick`    | number  | Tick width, quote per base                                                                       |
| `crossed` | boolean | Whether the aggregated book was crossed before being uncrossed                                   |
| `b`       | array   | Ten bid levels, nearest to spot outward                                                          |
| `a`       | array   | Ten ask levels, nearest to spot outward                                                          |
| `e`       | string  | Per-pair error code (for example `no_market`), present instead of a book when one is unavailable |

Each level in `b` and `a` has:

| Field                   | Type   | Description                                          |
| ----------------------- | ------ | ---------------------------------------------------- |
| `price`                 | number | Level price, quote per base                          |
| `cumulative_size_human` | number | Cumulative base size from the spot out to this level |

## Code Examples

<AccordionGroup>
  <Accordion title="Subscribe to a Pair">
    ```typescript theme={null}
    // Dev endpoint — no API key required, but rate-limited.
    // For production, use your production WS URL and add
    // { headers: { "x-api-key": "YOUR_API_KEY" } } as the second arg to new WebSocket().
    const WS_URL = "wss://dev-quote-api.dflow.net/book-stream";

    const SOL = "So11111111111111111111111111111111111111112";
    const USDC = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";

    const ws = new WebSocket(WS_URL);

    ws.onopen = () => {
      ws.send(JSON.stringify({ op: "subscribe", base_mint: SOL, quote_mint: USDC }));
    };

    ws.onmessage = (event) => {
      const frame = JSON.parse(event.data);
      for (const book of frame.updates ?? []) {
        if (book.e) {
          console.log(`${book.sb} / ${book.sq}: ${book.e}`);
          continue;
        }
        console.log(`slot ${frame.u}  mid ${book.mid}`);
        console.log("top ask:", book.a[0]);
        console.log("top bid:", book.b[0]);
      }
    };

    ws.onerror = (error) => console.error("WebSocket error:", error);
    ws.onclose = () => console.log("WebSocket connection closed");
    ```
  </Accordion>

  <Accordion title="TypeScript Interface">
    ```typescript theme={null}
    interface BookLevel {
      price: number;
      cumulative_size_human: number; // cumulative base size from spot to this level
    }

    interface BookUpdate {
      sb: string; // base mint
      sq: string; // quote mint
      mid?: number;
      tick?: number;
      crossed?: boolean;
      b?: BookLevel[]; // 10 bid levels
      a?: BookLevel[]; // 10 ask levels
      e?: string; // per-pair error code
    }

    interface BookFrame {
      u: number; // slot
      ts: number; // unix seconds
      skipped?: number; // slots skipped under load
      updates?: BookUpdate[];
      subscribe?: { sb: string; sq: string }[];
      unsubscribe?: { sb: string; sq: string }[];
    }
    ```
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Quote Stream" href="quote-stream" icon="signal-stream">
    Stream top-of-book bid and ask
  </Card>

  <Card title="Market Data Streams" href="/spot/trading/market-data-streams" icon="layer-group">
    How the streams work and when to use each
  </Card>

  <Card title="Websockets Overview" href="/resources/trading-api/websockets/overview" icon="plug">
    Connection details for Trading API streams
  </Card>

  <Card title="Stream Order Book Depth" href="/spot/recipes/stream-order-book" icon="code">
    Recipe: connect, subscribe, and render depth
  </Card>
</CardGroup>