> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xarchive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# L2 order book

> L2 price-level depth across Hyperliquid core, Spot, HIP-3, HIP-4, and Lighter, with native snapshots and full-depth Hyperliquid L2 from L4.

L2 is price-level aggregated depth on Hyperliquid core, Spot, HIP-3, HIP-4, Lighter, and Lighter on Robinhood Chain: each level carries a price, the total size resting at that price, and the order count behind it (`px`, `sz`, `n`), not the individual orders themselves.

L2 is the shape of the book: spreads, depth charts, a top-of-book monitor, or a light historical window. Step up to [L3](/rest-api/order-books-l3) or [L4](/rest-api/order-books-l4) only when individual resting orders matter, and use [Order history](/rest-api/order-history) or [Order flow](/rest-api/order-flow) for lifecycle records. Every venue serves native L2 snapshots, which on core and HIP-3 come from two sources and stop at 20 levels per side. Hyperliquid core and HIP-3 also serve full-depth aggregated L2 derived from L4. [Order books](/rest-api/order-books) compares the depths side by side.

## Get an L2 snapshot

The path and symbol format change by venue family.

<Tabs>
  <Tab title="Hyperliquid">
    ```bash theme={"theme":"github-dark"}
    curl "https://api.0xarchive.io/v1/hyperliquid/orderbook/BTC/l2?depth=200" \
      -H "X-API-Key: $OXARCHIVE_API_KEY"
    ```

    | Depth | Route |
    | - | - |
    | Full-depth aggregated 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` |

    Plain perp symbols such as `BTC` and `ETH`. Use the `/l2` routes for full-depth aggregated L2 (request levels via `depth`) from 2026-03-11 01:03 UTC onward.
  </Tab>

  <Tab title="Spot">
    ```bash theme={"theme":"github-dark"}
    curl "https://api.0xarchive.io/v1/hyperliquid/spot/orderbook/HYPE-USDC?depth=3" \
      -H "X-API-Key: $OXARCHIVE_API_KEY"
    ```

    | Depth | Route |
    | - | - |
    | Native L2 snapshot or history | `/v1/hyperliquid/spot/orderbook/{symbol}`, `/v1/hyperliquid/spot/orderbook/{symbol}/history` |

    Pair symbols such as `HYPE-USDC`. Spot serves native L2 depth; order-level detail on Spot is [L4](/rest-api/order-books-l4).
  </Tab>

  <Tab title="HIP-3">
    ```bash theme={"theme":"github-dark"}
    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 aggregated 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` |

    Namespaced builder symbols, case-sensitive (for example `km:US500`). Preserve the builder prefix.
  </Tab>

  <Tab title="HIP-4">
    ```bash theme={"theme":"github-dark"}
    curl "https://api.0xarchive.io/v1/hyperliquid/hip4/orderbook/%230?depth=3" \
      -H "X-API-Key: $OXARCHIVE_API_KEY"
    ```

    | Depth | Route |
    | - | - |
    | Native outcome book snapshot or history | `/v1/hyperliquid/hip4/orderbook/{symbol}`, `/v1/hyperliquid/hip4/orderbook/{symbol}/history` |

    Outcome side ids such as `%230` (Yes). Books are probability-priced where documented.
  </Tab>

  <Tab title="Lighter">
    ```bash theme={"theme":"github-dark"}
    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` |

    Lighter L2 matches the same `px`/`sz`/`n` shape. For order-level depth on Lighter, use [L3](/rest-api/order-books-l3). Find symbols on `/v1/lighter/instruments`.
  </Tab>

  <Tab title="Lighter on Robinhood Chain">
    ```bash theme={"theme":"github-dark"}
    curl "https://api.0xarchive.io/v1/rh-lighter/orderbook/BTC?depth=3" \
      -H "X-API-Key: $OXARCHIVE_API_KEY"
    ```

    | Depth | Route |
    | - | - |
    | L2 snapshot or history | `/v1/rh-lighter/orderbook/{symbol}`, `/v1/rh-lighter/orderbook/{symbol}/history` |

    The same `px`/`sz`/`n` shape as Lighter mainnet, with USDG prices and history from 2026-08-22. There is no L3 on this deployment. Find symbols on `/v1/rh-lighter/instruments`.
  </Tab>
</Tabs>

## Native L2 versus full-depth L2

Hyperliquid core and HIP-3 expose two L2 surfaces, and they answer different questions:

| Job | Route |
| - | - |
| Full-depth aggregated L2 | `/v1/hyperliquid/orderbook/{symbol}/l2` or the HIP-3 equivalent. Derived from L4, served from 2026-03-11 01:03 UTC |
| Native core/HIP-3 snapshot or older top-book windows | `/v1/hyperliquid/orderbook/{symbol}` and `/history`, or the HIP-3 equivalents. Two sources, `venue` and `node`; caps at 20 levels per side |

Native Hyperliquid and HIP-3 L2 routes serve two sources, described below, 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 full-depth aggregated L2 on those families, use the `/l2` route family. Spot, HIP-4, and Lighter serve native L2 depth.

## Two sources in native core and HIP-3 history

Native Hyperliquid core and HIP-3 L2 history holds two sources, interleaved in time. Every snapshot names its source in `source`, and `source=venue` or `source=node` on the request returns only that source.

| `source` | What it is, its timestamp, and its cadence |
| - | - |
| `venue` | Hyperliquid's own published book, stored as received. Timestamp: Hyperliquid's time on the message. Cadence: set by Hyperliquid, about every 5 seconds since 2026-06-20, faster before |
| `node` | Built from the order-level event stream of our Hyperliquid node. Timestamp: chain time, the book after every block with a block time at or before the timestamp, and no later block. Cadence: a fixed grid, every 500 ms from 2026-07-25 17:23 UTC, every second before that |

Both sources hold the top 20 levels per side, and at the same instant they show the same book. Use `venue` for the venue's own view and the longest history. Use `node` for a regular grid in chain time, for example to line the book up with trades and [L4](/rest-api/order-books-l4) events, which carry block time.

The `node` source starts on 2026-06-15 08:26 UTC for core and on 2026-06-01 for HIP-3, with some HIP-3 markets from 2026-05-01. Where we could not confirm our record of the order stream against the node's own state, the `node` source has no rows for that stretch, and the `venue` source still covers it.

When you filter history by source, send the same `source` on every page; `meta.next_cursor` continues the filtered series.

## Request parameters

| Parameter | Description |
| - | - |
| `symbol` | Path, required, string. Trading pair symbol, e.g. `BTC` |
| `timestamp` | Query, optional, integer (ms) or string. Snapshot routes only; Unix milliseconds or RFC 3339; omit for the latest snapshot. The Spot native snapshot route also documents its date-time form. |
| `start`, `end` | Query, optional, integer (ms) or string. History and diff routes; Window bounds in Unix milliseconds or RFC 3339. |
| `depth` | Query, optional, integer. Native core/HIP-3/HIP-4 snapshots cap at 20 levels per side; other native routes and full-depth `/l2` snapshots follow their endpoint contract. |
| `source` | Query, optional, string. Native core and HIP-3 snapshot and history routes only: `venue` or `node`. Omit for both. Any other value returns `400` with `error_code` `invalid_parameter`. |
| `limit` | Query, optional, integer. History and diff page size; defaults and ceilings are route-specific. Core/HIP-3 full-depth, HIP-4 native, and Lighter native history default to 100 and cap at 1000; Spot native history defaults to 10 and caps at 10. |
| `cursor` | Query, optional, string/integer. Continuation token from `meta.next_cursor`; its query type is route-specific, so pass the returned value unchanged. |

The full-depth `/l2/history` routes return the stored full depth by default. Pass `depth` to keep only the best levels on each side; `bid_levels` and `ask_levels` still report the full count. Ask for a bounded `start`/`end` window and paginate with `cursor`, and check a long window with [Data quality](/data-quality) before relying on it. Lighter's native history route additionally accepts `granularity=checkpoint|30s|10s|1s|tick`; `checkpoint` returns snapshot items, while `tick` items contain a checkpoint plus its ordered deltas. Use that route-specific shape instead of treating every L2 history item as a plain book snapshot.

## Example response

The L2 snapshot returns the same envelope across venues. Native core and HIP-3 snapshots also carry `source`:

```json theme={"theme":"github-dark"}
{
  "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 }
    ],
    "asks": [
      { "px": "61078.0", "sz": "11.73086", "n": 32 },
      { "px": "61079.0", "sz": "1.45565", "n": 4 }
    ],
    "mid_price": "61077.5",
    "spread": "1",
    "spread_bps": "0.16372641316360362",
    "source": "venue"
  },
  "meta": { "request_id": "23456789-2345-4234-8234-234567890123" }
}
```

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 a level; [L4](/rest-api/order-books-l4) lists each one with its `oid` and `user_address`. The `/l2` routes also return `bid_levels`, `ask_levels`, `total_bid_size`, and `total_ask_size`. Full field meanings live in the [field dictionary](/responses#field-dictionary), the [Reference](/reference) carries the exact types, and [Example responses](/response-examples) has more payload shapes.

## Access

Each venue's start date, WebSocket channels, and page limit come from [`GET /v1/capabilities`](/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](/conventions).

| Venue and data type | Availability |
| - | - |
| Hyperliquid: L2 order book | From 2023-04-15<br />WebSocket `orderbook`: live and replay<br />Up to 1,000 rows a page |
| Hyperliquid: Full-depth L2 | From 2026-03-11 01:03 UTC<br />WebSocket `orderbook_full`: live and replay<br />Up to 100 rows a page<br />Derived from L4. WebSocket replay is bulk (speed is ignored) and single-channel only, anchored at L4 checkpoints. |
| Hyperliquid: Full-depth L2 diffs | From 2026-03-11 01:03 UTC<br />REST only, no WebSocket channel<br />Up to 1,000 rows a page<br />Derived from L4. |
| Hyperliquid Spot: L2 order book | From 2026-05-05 19:56 UTC<br />WebSocket `spot_orderbook`: live only<br />Up to 1,000 rows a page |
| HIP-3: L2 order book | From 2026-02-16 16:57 UTC<br />WebSocket `hip3_orderbook`: live and replay<br />Up to 1,000 rows a page |
| HIP-3: Full-depth L2 | From 2026-03-11 01:03 UTC<br />WebSocket `hip3_orderbook_full`: live and replay<br />Up to 100 rows a page<br />Derived from L4. WebSocket replay is bulk (speed is ignored) and single-channel only, anchored at L4 checkpoints. |
| HIP-3: Full-depth L2 diffs | From 2026-03-11 01:03 UTC<br />REST only, no WebSocket channel<br />Up to 1,000 rows a page<br />Derived from L4. |
| HIP-4: L2 order book | From 2026-05-02 16:51 UTC<br />WebSocket `hip4_orderbook`: replay only<br />Up to 1,000 rows a page<br />WebSocket replay only: the live channel accepts a subscription but does not stream yet. |
| Lighter: L2 order book | From 2026-01-29 02:13 UTC<br />WebSocket `lighter_orderbook`: live and replay<br />Up to 1,000 rows a page<br />History granularity: checkpoint (default), 30s, 10s, 1s or tick. |
| Lighter on Robinhood Chain: L2 order book | From 2026-08-22 18:43 UTC<br />WebSocket `rh_lighter_orderbook`: live and replay<br />Up to 1,000 rows a page<br />History granularity: checkpoint (default), 30s, 10s, 1s or tick. |

| Surface | Names |
| - | - |
| Python SDK | `client.hyperliquid.orderbook.get(symbol)` and `.orderbook.history(...)`; full depth `client.hyperliquid.l2_orderbook.get`, `.history(..., depth=...)`, `.diffs` |
| TypeScript SDK | `client.hyperliquid.orderbook.get(symbol)` and `.orderbook.history(...)`; full depth `client.hyperliquid.l2Orderbook.get`, `.history(..., { depth })`, `.diffs` |
| Rust SDK | `client.hyperliquid.orderbook.get` and `.orderbook.history`; full depth `client.hyperliquid.l2_orderbook.get`, `.history`, `.diffs` |
| CLI | `oxa orderbook get`, `oxa orderbook history`; full depth `oxa l2 get`, `oxa l2 history --depth <n>`, `oxa l2 diffs`; Spot `oxa spot orderbook`; HIP-4 `oxa hip4 orderbook get\|history` |
| MCP tools | `get_orderbook`, `get_orderbook_history`, `get_spot_orderbook`, `get_spot_orderbook_history`, `get_hip3_orderbook`, `get_hip3_orderbook_history`, `get_hip4_orderbook`, `get_hip4_orderbook_history`, `get_lighter_orderbook`, `get_lighter_orderbook_history`, `get_rh_lighter_orderbook`, `get_rh_lighter_orderbook_history`; full depth `get_l2_orderbook`, `get_l2_orderbook_history`, `get_l2_diffs`, `get_hip3_l2_orderbook`, `get_hip3_l2_orderbook_history`, `get_hip3_l2_diffs` |

## Stream or replay it

Hyperliquid core, Spot, HIP-3, and Lighter stream L2 books live. Subscribe to `orderbook` on Hyperliquid core; Spot, HIP-3, and Lighter use `spot_orderbook`, `hip3_orderbook`, and `lighter_orderbook`.

`lighter_orderbook` sends a full top-20 Lighter book at most once per interval: one book per second by default, or the rate set with `interval_ms`. Its live payload differs from the REST response above; see [Lighter WebSocket channels](/websocket/lighter). Current Lighter L2 snapshots are also available through REST, and `lighter_orderbook` supports historical WebSocket replay. Historical data is also available through REST and exports. HIP-4 current order-book reads use REST; stored `hip4_orderbook` history remains replayable.

```javascript theme={"theme":"github-dark"}
ws.send(JSON.stringify({ op: "subscribe", channel: "orderbook", symbol: "BTC" }));
```

The full channel matrix is on [WebSocket channels](/websocket/channels).

## Export in bulk

L2 books export as the `l2_orderbook` schema (`$3/GB`, `$5 minimum`), delivered as Parquet with ZSTD compression. Keep L2, L3, and L4 in separate tables. Build a selection in the [Data Catalog](/data-catalog); columns and coverage keys are on [Export schemas](/export-schemas).

## Next step

When individual resting orders matter, continue to [L4 order book](/rest-api/order-books-l4).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.