l2BookDiffSnapshot

Get L2 orderbook snapshot for bootstrapping the l2BookDiff WebSocket stream.

💧 New endpoint - this endpoint is not a part of original Hyperliquid API and is added by us for builder convenience.

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 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:

{
    "type": "l2BookDiffSnapshot",
    "coin": "ETH"
}

Multiple coins:

{
    "type": "l2BookDiffSnapshot",
    "coins": ["ETH", "BTC"]
}

All markets, perps only (default):

{
    "type": "l2BookDiffSnapshot"
}

All markets, perps + outcomes:

{
    "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:

{
    "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.

1. Subscribe to l2BookDiff 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). 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