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 epoch, seq, and height 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 epoch, seq, and height for diff stream synchronization

• Returns zstd-compressed msgpack

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

Format: Zstd-compressed msgpack L2BookSnapshot:

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

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
epoch	string	Server epoch (UUID) — must match epoch in l2BookDiff messages
seq	number	Per-coin sequence number — use as starting point for diff stream

Bootstrapping the diff stream

1. Subscribe to l2BookDiff for your coin(s) — start buffering messages

2. Fetch this snapshot — note the epoch and seq for each coin

3. Discard buffered diffs where epoch doesn't match or seq <= snapshot.seq

4. Apply remaining diffs in order — the first should have prev_seq == snapshot.seq

5. If epoch changes or there's a seq gap, 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