> For the complete documentation index, see [llms.txt](https://docs.hydromancer.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hydromancer.xyz/readme/rest-api/market-data/l2bookdiffsnapshot.md). # l2BookDiffSnapshot {% hint style="info" %} 💧 New endpoint - this endpoint is not a part of original Hyperliquid API and is added by us for builder convenience. {% endhint %} ### Overview The `l2BookDiffSnapshot` endpoint returns full-depth L2 orderbook snapshots with `height`, `epoch`, and `seq` fields. This is the bootstrap endpoint for clients using the [`l2BookDiff`](/readme/websocket/l2bookdiff.md) WebSocket stream — fetch a snapshot here, then apply incremental diffs from the WebSocket to maintain a local orderbook. **Key details:** * Full-depth snapshots (all price levels) * Includes `height`, `epoch`, and `seq` for diff stream synchronization * Returns msgpack — zstd-compressed only when the request sends `Accept-Encoding: zstd`, otherwise uncompressed ### Request **Endpoint:** `POST /info` **Single coin:** ```json { "type": "l2BookDiffSnapshot", "coin": "ETH" } ``` **Multiple coins:** ```json { "type": "l2BookDiffSnapshot", "coins": ["ETH", "BTC"] } ``` **All markets, perps only (default):** ```json { "type": "l2BookDiffSnapshot" } ``` **All markets, perps + outcomes:** ```json { "type": "l2BookDiffSnapshot", "marketTypes": ["perp", "outcome"] } ``` **Parameters:** | Parameter | Type | Required | Description | | ------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `coin` | string | No | Single coin to fetch. | | `coins` | string\[] | No | Multiple coins to fetch. | | `marketTypes` | string\[] | No | All-markets only. Each entry is `"perp"`, `"spot"`, `"outcome"`, or the wildcard `"*"` (alone) for every type the server currently tracks. Omit for `["perp"]` (default). Rejected if combined with `coin` / `coins`. | Omit both `coin` and `coins` to fetch all markets. Always returns full-depth snapshots. ### Response **Headers:** * `Content-Type: application/octet-stream` * `Content-Encoding: zstd` — **only** when the request sends `Accept-Encoding: zstd`. Without it, the body is uncompressed msgpack. (Only `zstd` is supported; `gzip` is ignored.) **Format:** msgpack `L2BookSnapshot`. Each snapshot is encoded as a **positional array** (not a keyed map), always with this exact field order and length: ``` [coin, time, levels, height, epoch, seq] ``` All six elements are always present (`epoch` and `seq` are never omitted — `seq` is `0` only if the coin has had no diff this epoch). Shown as JSON for readability: ```json { "coin": "ETH", "time": 1704067200000, "levels": [ [ {"px": "3245.5", "sz": "12.4", "n": 3}, {"px": "3244.0", "sz": "8.7", "n": 5} ], [ {"px": "3246.0", "sz": "6.2", "n": 2}, {"px": "3247.5", "sz": "15.3", "n": 4} ] ], "height": 782007304, "epoch": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "seq": 206670 } ``` ### Field reference | Field | Type | Description | | --------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `coin` | string | Market symbol | | `time` | number | Block timestamp (milliseconds since epoch) | | `levels` | array | Tuple of `[bids, asks]`. Bids descending, asks ascending. | | `levels[][].px` | string | Price as decimal string | | `levels[][].sz` | string | Total size at this price level | | `levels[][].n` | number | Number of orders at this level | | `height` | number | Block height of this snapshot — use this to align with the `l2BookDiff` stream. | | `epoch` | string | Server epoch (UUID) — must match `epoch` in `l2BookDiff` messages. A different `epoch` means the snapshot is stale; re-fetch. | | `seq` | number | Per-coin sequence number as of this snapshot. Always present (`0` if the coin has had no diff this epoch). Matches the per-coin `seq` in the `l2BookDiff` stream — the first diff you apply for the coin should have `prev_seq == seq`. | ### Bootstrapping the diff stream Align on **`height`** — it is always present and is shared by this snapshot and every `l2BookDiff` batch. The snapshot already includes the diffs *up to and including* its own `height` (it is taken after that block is applied), so discard any diff at or below it. > Don't align on the diff stream's top-level `seq`; that is a per-connection message counter, unrelated to this snapshot. See [`l2BookDiff` → Sequencing and gap detection](/readme/websocket/l2bookdiff.md#sequencing-and-gap-detection). 1. Subscribe to [`l2BookDiff`](/readme/websocket/l2bookdiff.md) for your coin(s) — start buffering messages. 2. Fetch this snapshot — note `height`, `epoch`, and the per-coin `seq`. 3. Discard already-applied diffs: drop any buffered batch whose `data.height <= snapshot.height`. 4. Verify `epoch`: every remaining diff's `epoch` must equal the snapshot's `epoch`. A different `epoch` means the server restarted after the snapshot — re-fetch and restart. 5. Apply the remaining batches in `height` order. The first diff you apply for each coin should have `prev_seq == snapshot.seq` (the per-coin `seq`). 6. Ongoing gap detection: per coin, check `prev_seq` continuity against the last `seq` you applied (see [`l2BookDiff` → Sequencing and gap detection](/readme/websocket/l2bookdiff.md#sequencing-and-gap-detection)). On a gap or `epoch` change, re-fetch this snapshot. ### Common errors * **400**: Invalid `coin`/`coins` parameter * **403**: Permission denied - check API key * **404**: No snapshot available yet * **429**: Rate limit exceeded