Hyperliquid L4 Order Book API

L4 is the whole Hyperliquid book, order by order, on core, Spot, HIP-3, and HIP-4: every resting order across all served levels with its own oid and user_address, plus the diffs to roll the book forward and reconstruct it at any point in time. Use L4 when each resting order matters: microstructure, queue position, per-order user attribution, or a book you can reconstruct the same way twice. L2 is enough when aggregated levels answer the question, and Lighter exposes individual orders through L3 instead of L4. Order lifecycle, flow, fills, and TP/SL have their own routes: Order history, Order flow, Trades, and Take profits and stop losses. Each symbol’s L4 start date is on Venue coverage, and the exact operations are in OpenAPI.

Get an L4 snapshot

The path and symbol format change by venue family.

Hyperliquid
Spot
HIP-3
HIP-4

curl "https://api.0xarchive.io/v1/hyperliquid/orderbook/BTC/l4" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

/v1/hyperliquid/orderbook/{symbol}/l4, /l4/diffs, /l4/history. Plain perp symbols such as BTC and ETH.

curl "https://api.0xarchive.io/v1/hyperliquid/spot/orderbook/HYPE-USDC/l4" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

/v1/hyperliquid/spot/orderbook/{symbol}/l4, /l4/diffs, /l4/history. Pair symbols such as HYPE-USDC.

curl "https://api.0xarchive.io/v1/hyperliquid/hip3/orderbook/km:US500/l4" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

/v1/hyperliquid/hip3/orderbook/{symbol}/l4, /l4/diffs, /l4/history. Namespaced builder symbols, case-sensitive (for example km:US500). Preserve the builder prefix.

curl "https://api.0xarchive.io/v1/hyperliquid/hip4/orderbook/%230/l4" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

/v1/hyperliquid/hip4/orderbook/{symbol}/l4, /l4/diffs, /l4/history. Outcome side ids such as %230 (Yes).

Request parameters

Parameter	Description
`symbol`	Path, required, string. Trading pair symbol for the selected Hyperliquid family.
`timestamp`	Query, optional, integer (ms) or string. Snapshot routes only. Unix milliseconds or RFC 3339; omit for the latest snapshot.
`depth`	Query, optional, integer. Snapshot routes only. Maximum resting orders returned per side; omit for the full stored depth.
`start`, `end`	Query, optional, integer (ms) or string. History and diff routes. Window bounds in Unix milliseconds or RFC 3339
`cursor`	Query, optional, string (diffs) / integer (ms, history). Continuation token from `meta.next_cursor`; diff routes return strings and history routes return integer timestamps. Pass the returned value unchanged.
`limit`	Query, optional, integer. Diff routes default to 1000 and cap at 10000. Core, HIP-3, and HIP-4 history default to 100 and cap at 1000; Spot history defaults to 10 and caps at 10.

Current snapshot routes return one book object in data. History routes return arrays of snapshot objects, and diff routes return arrays of diff events. The cursor type and page-size cap are route-specific as shown above. Use /l4/history with start and end for a past window; timestamp is for the snapshot-at-time route. Check a long window with Data quality before relying on it.

Example response

{
  "success": true,
  "data": {
    "coin": "BTC",
    "timestamp": "2026-06-05T13:53:32.540Z",
    "checkpoint_timestamp": "2026-06-05T13:53:32.540Z",
    "diffs_applied": 0,
    "last_block_number": 1023882395,
    "bids": [
      { "oid": 459287722336, "user_address": "0xfcf104006bfff47695c1dc21dad3e9de1e72098e", "side": "B", "price": 61088, "size": 0.40603, "timestamp": 1773273600123 }
    ],
    "asks": [
      { "oid": 459287726057, "user_address": "0x1c1c270b573d55b68b3d14722b5d5d401511bed0", "side": "A", "price": 61089, "size": 0.40924, "timestamp": 1773273600123 }
    ],
    "bid_count": 24501,
    "ask_count": 18101,
    "total_bid_size": 10176.96,
    "total_ask_size": 5165.62
  },
  "meta": { "request_id": "34567890-3456-4345-8345-345678901234" }
}

bids and asks are truncated above. That snapshot carried 24,501 bids and 18,101 asks: the entire resting book, each order with its own oid and user_address.

Response fields

Responses use the { success, data, meta } envelope; the fields below are data.

Field	Description
`coin`	String. Symbol (the L4 payload uses `coin`)
`timestamp`	String. When the book was in this state (UTC)
`checkpoint_timestamp`	String. Instant the reconstruction is current to
`diffs_applied`	Integer. Diffs rolled onto the checkpoint; `0` is a clean checkpoint
`last_block_number`	Integer. Chain block the reconstruction is current to
`bids`, `asks`	Array. Resting orders, each with `oid`, `user_address`, `side`, `price`, `size`, and queue-join `timestamp`. Within each price level, orders are listed in true queue priority, ALO priority insertions included, not placement-time order.
`bid_count`, `ask_count`	Integer. Number of orders in the full stored or reconstructed checkpoint before optional `depth` truncates the returned arrays.
`total_bid_size`, `total_ask_size`	Number. Aggregate sizes in the full stored or reconstructed checkpoint before optional `depth` truncates the returned arrays.
`is_crossed`	Boolean, optional. Present when a reconstructed historical book has best bid greater than or equal to best ask; omitted for clean snapshots.

price and size are numbers in L4 payloads. Hyperliquid and Lighter L2 routes use px/sz decimal strings for aggregated levels, while the Lighter L3 route uses numeric price, remaining_size, and original_size fields. Check types per route; the Reference carries the exact types, and full field meanings live in the field dictionary.

Reconstruct from diffs

0xArchive runs collection, backfill, and reconstruction server-side and returns the reconstructed checkpoint/snapshot. To follow the book over time, take an l4 checkpoint, then apply l4/diffs in order, or pull l4/history for a window. Diff items may carry an optional insert_before field (an order ID, or null). For a new ALO order granted queue priority, it names the resting order this one is inserted ahead of within its price level. Insert the new order directly before that oid instead of appending; null or absent means tail append under the current update rule. The field is populated from July 21, 2026 onward. Earlier records lack this insertion information, so use a window from that date when your study requires recorded queue-priority changes. Depth truncation is by order count, so the orders at a depth cut can differ from responses served before that date. diffs_applied: 0 means a clean checkpoint; a higher number means it was rolled forward from the last one. A snapshot-only consumer can use the returned state directly. To keep a continuously updated local book, apply ordered diffs/replay after that checkpoint. See WebSocket L4 order book, WebSocket replay, or SDK reconstruction for sequence and gap handling. A current L2 snapshot is enough to inspect the book or a spread. It is not the same dataset as a replayable L4 history window, which keeps every order, its timestamp semantics, and a book that can be reconstructed the same way twice.

Access

Each venue’s start date, WebSocket channels, and page limit come from GET /v1/capabilities, followed by the SDK, CLI, and MCP names for the same data. The start date is the first served row on that venue; exact starts vary by market, so check /v1/symbols for a single symbol. Send 0xArchive-Version: 2026-10-01 for the current response contract; see API conventions.

Venue and data type	Availability
Hyperliquid: L4 order book	From 2026-03-11 01:03 UTC REST only, no WebSocket channel Up to 10 rows a page A live or replayed L4 diff stream opens with a full L4 snapshot.
Hyperliquid: L4 diffs	From 2026-03-11 01:03 UTC WebSocket `l4_diffs`: live and replay Up to 10,000 rows a page WebSocket replay is bulk (speed is ignored) and single-channel only; it starts at the nearest L4 checkpoint and opens with its snapshot.
Hyperliquid Spot: L4 order book	From 2026-05-05 22:57 UTC REST only, no WebSocket channel Up to 10 rows a page A live or replayed L4 diff stream opens with a full L4 snapshot. PURR-USDC has L4 checkpoints from 2026-03-11 01:03 UTC; other pairs from 2026-05-05 or later (HYPE-USDC from 2026-05-13 15:33 UTC).
Hyperliquid Spot: L4 diffs	From 2026-05-05 22:57 UTC WebSocket `spot_l4_diffs`: live and replay Up to 10,000 rows a page WebSocket replay is bulk (speed is ignored) and single-channel only; it starts at the nearest L4 checkpoint and opens with its snapshot. PURR-USDC has L4 checkpoints from 2026-03-11 01:03 UTC; other pairs from 2026-05-05 or later (HYPE-USDC from 2026-05-13 15:33 UTC).
HIP-3: L4 order book	From 2026-03-11 01:03 UTC REST only, no WebSocket channel Up to 10 rows a page A live or replayed L4 diff stream opens with a full L4 snapshot.
HIP-3: L4 diffs	From 2026-03-11 01:03 UTC WebSocket `hip3_l4_diffs`: live and replay Up to 10,000 rows a page WebSocket replay is bulk (speed is ignored) and single-channel only; it starts at the nearest L4 checkpoint and opens with its snapshot.
HIP-4: L4 order book	From 2026-05-02 07:47 UTC REST only, no WebSocket channel Up to 10 rows a page A live or replayed L4 diff stream opens with a full L4 snapshot.
HIP-4: L4 diffs	From 2026-05-02 07:47 UTC WebSocket `hip4_l4_diffs`: live and replay Up to 10,000 rows a page WebSocket replay is bulk (speed is ignored) and single-channel only; it starts at the nearest L4 checkpoint and opens with its snapshot.

Surface	Names
Python SDK	`client.hyperliquid.l4_orderbook.get(symbol)`, `.diffs(...)`, `.history(...)`
TypeScript SDK	`client.hyperliquid.l4Orderbook.get(symbol)`, `.diffs(...)`, `.history(...)`
Rust SDK	`client.hyperliquid.l4_orderbook.get`, `.diffs`, `.history`
CLI	`oxa l4 get`, `oxa l4 diffs`, `oxa l4 history` (`--exchange hyperliquid\|hip3\|hip4`); Spot `oxa spot l4`, `oxa spot l4-diffs`, `oxa spot l4-history`
MCP tools	`get_l4_orderbook`, `get_l4_diffs`, `get_l4_orderbook_history`, and the `get_spot_l4_`, `get_hip3_l4_`, and `get_hip4_l4_*` tools with the same suffixes

Stream or replay it

Order-level updates stream on l4_diffs and l4_orders for Hyperliquid core; Spot, HIP-3, and HIP-4 use prefixed variants (spot_l4_diffs, hip3_l4_diffs, hip4_l4_orders, and so on). Every one of these channels also supports checkpoint-anchored bulk replay: one channel per replay, starting from the nearest L4 checkpoint at or before start, with speed ignored. For sequence and gap handling, see WebSocket L4 order book and WebSocket replay.

ws.send(JSON.stringify({ op: "subscribe", channel: "l4_diffs", symbol: "BTC" }));

Endpoint reference

Requests and responses

Datasets

Venues

OpenAPI and schemas

Guides

Hyperliquid L4 Order Book API

Get an L4 snapshot

Request parameters

Example response

Response fields

Reconstruct from diffs

Access

Stream or replay it

Export in bulk

Next step

​Get an L4 snapshot

​Request parameters

​Example response

​Response fields

​Reconstruct from diffs

​Access

​Stream or replay it

​Export in bulk

​Next step

Get an L4 snapshot

Request parameters

Example response

Response fields

Reconstruct from diffs

Access

Stream or replay it

Export in bulk

Next step