> For the complete documentation index, see [llms.txt](https://docs.sodex.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sodex.com/for-developers/api-reference/trading-api/websocket-v1/l4book.md).

# L4 Book Stream

This subscription first sends a snapshot with up to the requested `level` price levels per side, then forwards changed price levels by block. The default snapshot depth is 10 levels per side.

## Update Speed

* Updates are grouped by block and sent when the subscribed symbol has depth changes.

## Maintain a local book

Maintain a separate book for each engine and symbol. In an update, `U` is the previous book update ID plus one, and `u` is the highest update ID in the batch.

1. Wait for the subscription acknowledgement and initial `snapshot`. Replace both local sides with its `a` and `b` levels and save its `u` as `last_u`.
2. For each `update`, ignore it if `u <= last_u`: the local snapshot or a previous update already covers it.
3. For each remaining update, require `U == last_u + 1`. If the check fails, discard the local book, unsubscribe and resubscribe, and restart at step 1 with the new snapshot.
4. If the check passes, apply each `[price, quantity]` as the new total quantity at that price, rather than adding it to the old quantity. A zero quantity removes the price level. Save the message's `u` as `last_u` after applying it.

Use exact integers for `U` and `u` and decimal values for price and quantity. Check continuity with update IDs, rather than event timestamps or the number of levels in a message. After a disconnect, rebuild from a new subscription snapshot.

The `level` parameter limits the initial snapshot; subsequent updates can include prices outside that initial window. Deeper levels absent from the snapshot remain unknown until updated, so a continuous update sequence alone does not establish a complete full-depth book.

For [L2 Book](https://docs.sodex.com/for-developers/api-reference/trading-api/websocket-v1/l2book.md), every book message is a fresh top-20 snapshot: replace the published view each time instead of applying this incremental algorithm.

## Subscribe Request

* Subscribe Schema

See [`WsL4BookSubscriptionParams`](https://docs.sodex.com/for-developers/api-reference/trading-api/rest-v1/schema.md#wsl4booksubscriptionparams) in [Schema](https://docs.sodex.com/for-developers/api-reference/trading-api/rest-v1/schema.md).

```typescript
interface SubscribeRequest {
  op: "subscribe";
  id: number | null; // Optional client originated request identifier sent as acknowledgment in the response.
  params: WsL4BookSubscriptionParams;
}
```

* Subscribe Ack Schema

See [`WsL4BookSubscriptionResult`](https://docs.sodex.com/for-developers/api-reference/trading-api/rest-v1/schema.md#wsl4booksubscriptionresult) in [Schema](https://docs.sodex.com/for-developers/api-reference/trading-api/rest-v1/schema.md).

```typescript
interface SubscriptionResult {
  op: "subscribe";
  id: number | null; // Optional client originated request identifier sent as acknowledgment in the response.
  result: WsL4BookSubscriptionResult | null;
  success: boolean; // Indicates if the request was successfully processed by the engine.
  connID: string;
  error: string | null; // Condition: If success is false. Error message.
  time_in: number; // The timestamp when the subscription was received on the wire, just prior to parsing data, in milliseconds.
  time_out: number; // The timestamp when the acknowledgement was sent on the wire, just prior to transmitting data, in milliseconds.
}
```

* Example: Subscribe

```json
{
  "op": "subscribe",
  "params": {
    "channel": "l4Book",
    "symbol": "BTC-USD"
  }
}
```

* Example: Subscribe Ack

```json
{
  "op": "subscribe",
  "result": {
    "channel": "l4Book",
    "symbol": "BTC-USD",
    "level": 10
  },
  "success": true,
  "connID": "0x14d927b9ee587b4f345219617e931984",
  "time_in": 1672515782130,
  "time_out": 1672515782136
}
```

## Unsubscribe Request

* Unsubscribe Schema

See [`WsL4BookSubscriptionParams`](https://docs.sodex.com/for-developers/api-reference/trading-api/rest-v1/schema.md#wsl4booksubscriptionparams) in [Schema](https://docs.sodex.com/for-developers/api-reference/trading-api/rest-v1/schema.md).

```typescript
interface UnsubscribeRequest {
  op: "unsubscribe";
  id: number | null; // Optional client originated request identifier sent as acknowledgment in the response.
  params: WsL4BookSubscriptionParams;
}
```

* Unsubscribe Ack Schema

See [`WsL4BookSubscriptionResult`](https://docs.sodex.com/for-developers/api-reference/trading-api/rest-v1/schema.md#wsl4booksubscriptionresult) in [Schema](https://docs.sodex.com/for-developers/api-reference/trading-api/rest-v1/schema.md).

```typescript
interface UnsubscriptionResult {
  op: "unsubscribe";
  id: number | null; // Optional client originated request identifier sent as acknowledgment in the response.
  result: WsL4BookSubscriptionResult | null;
  success: boolean; // Indicates if the request was successfully processed by the engine.
  connID: string;
  error: string | null; // Condition: If success is false. Error message.
  time_in: number; // The timestamp when the subscription was received on the wire, just prior to parsing data, in milliseconds.
  time_out: number; // The timestamp when the acknowledgement was sent on the wire, just prior to transmitting data, in milliseconds.
}
```

* Example: Unsubscribe

```json
{
  "op": "unsubscribe",
  "params": {
    "channel": "l4Book",
    "symbol": "BTC-USD",
    "level": 1000
  }
}
```

* Example: Unsubscribe Ack

```json
{
  "op": "unsubscribe",
  "result": {
    "channel": "l4Book",
    "symbol": "BTC-USD",
    "level": 1000
  },
  "success": true,
  "connID": "0x14d927b9ee587b4f345219617e931984",
  "time_in": 1672515782130,
  "time_out": 1672515782136
}
```

## Snapshot / Update Response

* Snapshot Schema

See [`WsDepthSnapshotData`](https://docs.sodex.com/for-developers/api-reference/trading-api/rest-v1/schema.md#wsdepthsnapshotdata) in [Schema](https://docs.sodex.com/for-developers/api-reference/trading-api/rest-v1/schema.md).

```typescript
interface L4BookResponse {
  channel: "l4Book";
  type: "snapshot";
  data: WsDepthSnapshotData;
}
```

* Update Schema

See [`WsDepthUpdateData`](https://docs.sodex.com/for-developers/api-reference/trading-api/rest-v1/schema.md#wsdepthupdatedata) in [Schema](https://docs.sodex.com/for-developers/api-reference/trading-api/rest-v1/schema.md).

```typescript
interface L4BookResponse {
  channel: "l4Book";
  type: "update";
  data: WsDepthUpdateData;
}
```

* Example: Snapshot

```json
{
  "channel": "l4Book",
  "type": "snapshot",
  "data": {
    "s": "BTC-USD",
    "u": 12345,
    "E": 1672515782136,
    "b": [
      ["0.5666", "4831.75496356"],
      ["0.5665", "4831.75496356"],
      ["0.5664", "4831.75496356"],
      ["0.5663", "4831.75496356"],
      ["0.5662", "4831.75496356"]
    ],
    "a": [
      ["0.5668", "4410.79769741"],
      ["0.5669", "4410.79769741"],
      ["0.567", "4410.79769741"],
      ["0.5671", "4410.79769741"],
      ["0.5672", "4410.79769741"]
    ]
  }
}
```

* Example: Update

```json
{
  "channel": "l4Book",
  "type": "update",
  "data": {
    "s": "BTC-USD",
    "u": 12346,
    "U": 12346,
    "E": 1672515782136,
    "b": [["0.5666", "4831.75496356"]],
    "a": [
      ["0.5668", "4410.79769741"],
      ["0.5669", "4410.79769741"]
    ]
  }
}
```
