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

# Orderbook

Subscribe to real-time orderbook updates for a market.

* Topic: `orderbook.<depth>.<symbol>` (e.g., `orderbook.1.BTC-USDC`)
* Stream: Public (`wss://api.ekiden.fi/ws/public`)

## Subscribe

```json theme={null}
{ "op": "subscribe", "args": ["orderbook.1.BTC-USDC"], "req_id": "101001" }
```

Ack:

```json theme={null}
{ "op": "subscribed", "args": ["orderbook.1.BTC-USDC"], "req_id": "101001" }
```

## Events

Messages arrive with `op: "event"`, `topic: "orderbook.<depth>.<symbol>"`, include `type` (`snapshot` or `delta`), and `data` is an `OrderBookSnapshot`.

Snapshot example:

```json theme={null}
{
    "op": "event",
    "topic": "orderbook.1.BTC-USDC",
    "server_ts_ms": 1731541800000,
    "type": "snapshot",
    "data": {
        "s": "BTC-USDC",
        "ts": "1731541800000",
        "mts": "1731541799990",
        "u": 123,
        "seq": 123,
        "a": [["100200", "3"], ["100300", "2"]],
        "b": [["100100", "5"], ["100000", "1"]]
    }
}
```

Delta example:

```json theme={null}
{
    "op": "event",
    "topic": "orderbook.1.BTC-USDC",
    "server_ts_ms": 1731541801000,
    "type": "delta",
    "data": {
        "s": "BTC-USDC",
        "ts": "1731541801000",
        "mts": "1731541800990",
        "u": 124,
        "seq": 124,
        "a": [["100300", "0"]],
        "b": [["100100", "7"]]
    }
}
```

## Building a Local Book

* On subscribe, wait for a snapshot, then apply subsequent deltas by ascending `seq`.
* Each price level is a two-element array `[price, size]`.
* Delta semantics: if `size === "0"`, delete the level at `price`; otherwise upsert the level to `size`.
* If you detect a gap in `seq`, resubscribe to receive a fresh snapshot.

### Notes

* Arrays `asks` and `bids` are ordered by ascending price.
* In the payload, asks are `a` and bids are `b`.
* `ts` and `mts` are Unix timestamps in milliseconds (encoded as strings).
* `server_ts_ms` is the gateway processing time in milliseconds.
* All numeric values in `data` are strings to preserve precision.

See schema details in [AsyncAPI](../websockets/public): `OrderBookSnapshot`.