Order books

Order-book work starts with two decisions: which venue family, and how deep. L2 is aggregated price levels, L3 is individual orders, L4 is the full order-level book you can reconstruct. Different datasets, not one orderbook blob. This page covers all of them: full-depth L2 routes where they exist, native 20-level L2 source snapshots, then the L4 order-level book and reconstruction below.

Get an L2 snapshot

Pick your venue. The path and symbol format change. Lighter also exposes an L3 individual-order book where Hyperliquid exposes L4.

Hyperliquid
Spot
HIP-3
HIP-4
Lighter

curl "https://api.0xarchive.io/v1/hyperliquid/orderbook/BTC/l2?depth=200" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

Depth	Route
Full-depth L2 from L4	`/v1/hyperliquid/orderbook/{symbol}/l2`, `/l2/history`, `/l2/diffs`
Native L2 snapshot or history (20 levels)	`/v1/hyperliquid/orderbook/{symbol}`, `/v1/hyperliquid/orderbook/{symbol}/history`
L4 order-level	`/v1/hyperliquid/orderbook/{symbol}/l4`, `/l4/diffs`, `/l4/history`

Plain perp symbols such as BTC and ETH. Use the /l2 routes for full-depth aggregated L2 (request levels via depth) from March 10, 2026 onward.

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

Depth	Route
L2 snapshot	`/v1/hyperliquid/spot/orderbook/{symbol}`
L4 order-level	`/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/l2?depth=200" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

Depth	Route
Full-depth L2 from L4	`/v1/hyperliquid/hip3/orderbook/{symbol}/l2`, `/l2/history`, `/l2/diffs`
Native L2 snapshot or history (20 levels)	`/v1/hyperliquid/hip3/orderbook/{symbol}`, `/v1/hyperliquid/hip3/orderbook/{symbol}/history`
L4 order-level	`/v1/hyperliquid/hip3/orderbook/{symbol}/l4`, `/l4/diffs`, `/l4/history`

Namespaced builder symbols, case-sensitive (for example km:US500). Preserve the builder prefix. Use the /l2 routes for full-depth aggregated L2 (request levels via depth) from March 10, 2026 onward.

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

Depth	Route
Outcome order book plus history and L4	`/v1/hyperliquid/hip4/orderbook/{symbol}` and its history and L4 routes

Outcome side ids such as %230 (Yes). Books are probability-priced where documented.

curl "https://api.0xarchive.io/v1/lighter/orderbook/{symbol}?depth=3" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"

Depth	Route
L2 snapshot or history	`/v1/lighter/orderbook/{symbol}`, `/v1/lighter/orderbook/{symbol}/history`
L3 individual orders	`/v1/lighter/l3orderbook/{symbol}`, `/v1/lighter/l3orderbook/{symbol}/history`

Lighter exposes L3 individual orders rather than Hyperliquid-style L4. Find symbols on /v1/lighter/instruments.

For Hyperliquid core and HIP-3, use this route choice:

Job	Route
Full-depth aggregated L2 (request levels via `depth`)	`/v1/hyperliquid/orderbook/{symbol}/l2` or `/v1/hyperliquid/hip3/orderbook/{symbol}/l2`, with March 10, 2026+ coverage
Native source snapshot or older historical top-book windows	`/v1/hyperliquid/orderbook/{symbol}` and `/history`, or the HIP-3 equivalents; capped at 20 levels per side
Order-level reconstruction	`/v1/hyperliquid/orderbook/{symbol}/l4`, `/l4/history`, `/l4/diffs`, or the HIP-3 equivalents

Hyperliquid and HIP-3 native L2 routes mirror Hyperliquid’s source snapshot and top out at 20 levels per side. A request like depth=200 on /v1/hyperliquid/orderbook/BTC/history still returns at most 20 levels. For 200-level or full-depth aggregated Hyperliquid/HIP-3 L2, use the /l2 route family.

Request parameters

Parameter	In	Type	Required	Description
`symbol`	path	string	Yes	Trading pair symbol, e.g. `BTC`
`timestamp`	query	integer (ms)	No	Snapshot routes only; Unix milliseconds; omit for the latest snapshot
`start`, `end`	query	integer (ms)	No	History and diff routes; Unix-millisecond window bounds
`depth`	query	integer	No	Snapshot depth where documented. Native Hyperliquid/HIP-3 L2 caps at 20 levels (venue source limit); full-depth `/l2` snapshots return the depth you request. Not tier-gated.
`limit`	query	integer	No	Max rows or checkpoints on history/diff routes
`cursor`	query	string/integer	No	Continuation token from `meta.next_cursor`

Use /history with start and end for a past window. timestamp is for snapshot-at-time routes, not history routes. The L2 snapshot returns the same envelope across venues:

{
  "success": true,
  "data": {
    "coin": "BTC",
    "symbol": "BTC",
    "timestamp": "2026-06-05T13:53:33.971Z",
    "bids": [
      { "px": "61077.0", "sz": "0.0003", "n": 1 },
      { "px": "61075.0", "sz": "1.60628", "n": 6 },
      { "px": "61074.0", "sz": "0.8386", "n": 4 }
    ],
    "asks": [
      { "px": "61078.0", "sz": "11.73086", "n": 32 },
      { "px": "61079.0", "sz": "1.45565", "n": 4 },
      { "px": "61080.0", "sz": "7.83114", "n": 6 }
    ],
    "mid_price": "61077.5",
    "spread": "1",
    "spread_bps": "0.16372641316360362"
  },
  "meta": { "request_id": "req_2c9a7f10b8e34d52" }
}

Response fields

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

Field	Type	Description
`symbol`	string	Trading pair symbol (`coin` is a deprecated alias)
`timestamp`	string	Snapshot timestamp (UTC)
`bids`	array	Bid levels, best first. Each level has `px`, `sz`, `n`
`asks`	array	Ask levels, best first. Each level has `px`, `sz`, `n`
`bid_levels`, `ask_levels`	integer	Total available full-depth L2 levels before any depth cap, returned by `/l2` routes
`total_bid_size`, `total_ask_size`	number	Aggregate full-depth L2 size, returned by `/l2` routes
`mid_price`	string	(best bid + best ask) / 2
`spread`	string	best ask minus best bid
`spread_bps`	string	Spread in basis points

A price level is px (price), sz (total size), and n (order count). px, sz, mid_price, spread, and spread_bps are decimal strings, so parse them as decimals, not floats. n aggregates the orders at that level; L4 lists each one with its oid and user_address. Full field meanings live in the field dictionary.

Depth: L2 vs L3 vs L4

L2Aggregated levels

Price levels with total size and order count (px, sz, n). The shape of the book.

L3Individual orders

Each order at a level, on Lighter. Order-level detail without full lifecycle.

L4Every resting order

Every order with its oid and user_address, plus diffs to reconstruct the book.

Depth	What you get	Reach for it when
L2	Aggregated price levels (`px`, `sz`, `n`)	You need the shape of the book, spreads, or a light history window.
L3	Individual orders (Lighter)	You need order-level detail on Lighter without full lifecycle.
L4	Every resting order with `oid` + `user_address`, plus diffs and reconstruction	You need microstructure, queue position, or to roll the book forward from a checkpoint.

Each grain has a focused page with its routes, parameters, example, and export schema:

L2 order book

Aggregated price-level depth: native venue snapshots and full-depth aggregated L2 on Hyperliquid core and HIP-3.

L3 order book

Order-level depth on Lighter: every resting order with its order index and owner account index.

L4 order book

Full order-level book on Hyperliquid families: every order with oid and user_address, plus diffs and reconstruction.

For file exports, use Export schemas. The Data Catalog keys keep L2, L3, L4, and order events separate.

Full-depth L2 from L4

Hyperliquid core and HIP-3 have a primary full-depth L2 route family derived from L4, with March 10, 2026+ coverage:

Route	Use it for
`/v1/hyperliquid/orderbook/{symbol}/l2`	Latest or timestamped full-depth aggregated L2 snapshot
`/v1/hyperliquid/orderbook/{symbol}/l2/history`	Full-depth L2 checkpoint history
`/v1/hyperliquid/orderbook/{symbol}/l2/diffs`	Tick-level aggregate L2 diffs
`/v1/hyperliquid/hip3/orderbook/{symbol}/l2`	HIP-3 full-depth aggregated L2 snapshot
`/v1/hyperliquid/hip3/orderbook/{symbol}/l2/history`	HIP-3 full-depth L2 checkpoint history
`/v1/hyperliquid/hip3/orderbook/{symbol}/l2/diffs`	HIP-3 tick-level aggregate L2 diffs

The /l2/history routes return the checkpoint’s stored full depth and currently do not take a per-request depth override. Ask for a bounded start/end window and paginate with cursor.

L4 order-level book

L4 is the whole book, order by order: every resting order with its oid and user_address. It is the most detailed market data 0xArchive serves and carries the fields needed for deterministic order-level reconstruction. The L4 routes are in the venue switch above (/orderbook/{symbol}/l4, /l4/diffs, /l4/history).

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

{
  "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 }
    ],
    "asks": [
      { "oid": 459287726057, "user_address": "0x1c1c270b573d55b68b3d14722b5d5d401511bed0", "side": "A", "price": 61089, "size": 0.40924 }
    ],
    "bid_count": 24501,
    "ask_count": 18101,
    "total_bid_size": 10176.96,
    "total_ask_size": 5165.62
  },
  "meta": { "request_id": "req_5b1e0c47a9d23f88" }
}

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

L4 response fields

Field	Type	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`. Levels list orders in true queue priority (ALO insertions included).
`bid_count`, `ask_count`	integer	Full-book order counts, even though only the top orders are shown
`total_bid_size`, `total_ask_size`	number	Full-book aggregate sizes

price and size are numbers in L4 payloads, while L2/L3 return px/sz as decimal strings, so check types per route.

Reconstruct from diffs

A snapshot is a checkpoint. To follow the book over time, take an l4 checkpoint, then apply l4/diffs in order (honoring the optional insert_before field on new-order diffs; see L4 order books), or pull l4/history for a window. diffs_applied: 0 means a clean checkpoint; a higher number means it was rolled forward from the last one. When sequence and gap handling matter, move to WebSocket L4 order book and WebSocket replay, or let SDK reconstruction hold local book state for you. A current L2 snapshot is fine for inspecting the book or a spread. It is not the same product as a replayable L4 history window. If you are evaluating a provider, that distinction is the one to push on: what depth, which venue family, what timestamp semantics, and whether the historical book can be reconstructed the same way twice.

Stream it live

Every venue streams the book. Subscribe to orderbook for L2 and l4_diffs/l4_orders for order-level updates on Hyperliquid core; Spot, HIP-3, and HIP-4 use prefixed variants (spot_orderbook, hip3_l4_diffs, and so on), and Lighter adds lighter_l3_orderbook. For sequence and gap handling, see WebSocket L4 order book and WebSocket replay.

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

The full channel matrix is on WebSocket channels.

Export in bulk

Order books export at three depths, delivered as Parquet with ZSTD compression: l2_orderbook ($6/GB, $10 minimum), l3_orderbook ($6/GB, $10 minimum), and l4_orderbook ($8/GB, $25 minimum). Keep L2, L3, and L4 in separate tables. Build a selection in the Data catalog; columns and coverage keys are on Export schemas.

Plans and limits

Full-depth L2 is on every tier

Every tier, including Free, gets the full order-book catalog: native venue L2, full-depth aggregated L2 (snapshots, checkpoints, and diffs), L4 order-level reconstruction and diffs, order flow, and TP/SL, plus trades, candles, funding, open interest, and liquidations. Tiers differ only on credits, rate limits, concurrency, WebSocket scale, and replay speed.

Upgrade to Pro →

Use Order history and Order flow for the lifecycle around the book, WebSocket L4 order book when sequence matters, Example responses for more payload shapes, or Data quality before any long historical window.

Get started

Market data

Get connected

Plans & limits

Get an L2 snapshot

Request parameters

Response fields

Depth: L2 vs L3 vs L4

L2 order book

L3 order book

L4 order book

Full-depth L2 from L4

L4 order-level book

L4 response fields

Reconstruct from diffs

Stream it live

Export in bulk

Next

​Get an L2 snapshot

​Request parameters

​Response fields

​Depth: L2 vs L3 vs L4

L2 order book

L3 order book

L4 order book

​Full-depth L2 from L4

​L4 order-level book

​L4 response fields

​Reconstruct from diffs

​Stream it live

​Export in bulk

​Next

Get an L2 snapshot

Request parameters

Response fields

Depth: L2 vs L3 vs L4

Full-depth L2 from L4

L4 order-level book

L4 response fields

Reconstruct from diffs

Stream it live

Export in bulk

Next