> ## 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.

# Order books

> L2 aggregated depth, Hyperliquid L4 order-level data, and Lighter L3 individual-order depth over REST, WebSocket, and export.

Read Hyperliquid and Lighter order books at the depth your job needs: L2 aggregated price levels on every venue, L3 individual orders on Lighter, and L4 resting orders with wallet attribution on Hyperliquid core, Spot, HIP-3, and HIP-4. Pick the venue family first, then the depth; each is a separate dataset with its own routes.

Plans set capacity and how far back a request can reach, not which routes you can call. Whether a market has a given depth, and from when, depends on its venue family and symbol, so check the symbol's coverage before you rely on a route.

## Get an L2 snapshot

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

<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 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 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 |
    | - | - |
    | 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`.
  </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 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 2026-03-11 01:03 UTC onward.
  </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 |
    | - | - |
    | 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.
  </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` |
    | 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`.
  </Tab>
</Tabs>

On Hyperliquid core and HIP-3, choose the route by job:

| Job | Route |
| - | - |
| Full-depth aggregated L2 (request levels via `depth`) | `/v1/hyperliquid/orderbook/{symbol}/l2` or `/v1/hyperliquid/hip3/orderbook/{symbol}/l2`, served from 2026-03-11 01:03 UTC |
| 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 | 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 |
| `start`, `end` | Query, optional, integer (ms) or string. History and diff routes; window bounds in Unix milliseconds or RFC 3339 |
| `depth` | Query, optional, integer. 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. |
| `limit` | Query, optional, integer. Max rows or checkpoints on history/diff routes |
| `cursor` | Query, optional, string/integer. 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. Before a long historical window, check it with [Data quality](/data-quality).

The L2 snapshot returns the same envelope across venues:

```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 },
      { "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": "23456789-2345-4234-8234-234567890123" }
}
```

## Response fields

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

| Field | 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](/responses#field-dictionary), and [Example responses](/response-examples) has more payload shapes.

## Choose a depth

<div className="oxa-depth">
  <div className="oxa-depth-tier">
    <span className="oxa-flow-tag">L2</span>
    <span className="oxa-heading">Aggregated levels</span>

    <div className="oxa-depth-bars oxa-depth--l2">
      <span />

      <span />

      <span />

      <span />

      <span />
    </div>

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

  <div className="oxa-depth-tier">
    <span className="oxa-flow-tag">L3</span>
    <span className="oxa-heading">Individual orders</span>

    <div className="oxa-depth-bars oxa-depth--l3">
      <span />

      <span />

      <span />

      <span />

      <span />
    </div>

    <p>Each order at a level, on Lighter. Order-level detail without full lifecycle.</p>
  </div>

  <div className="oxa-depth-tier">
    <span className="oxa-flow-tag">L4</span>
    <span className="oxa-heading">All served resting-order levels</span>

    <div className="oxa-depth-bars oxa-depth--l4">
      <span />

      <span />

      <span />

      <span />

      <span />
    </div>

    <p>Resting orders with oid and user\_address across all served levels, plus diffs to reconstruct the book.</p>
  </div>
</div>

Each depth has its own page with routes, parameters, an example, and the export schema:

<CardGroup cols={3}>
  <Card title="L2 order book" icon="layers" href="/rest-api/order-books-l2">
    Aggregated price levels (`px`, `sz`, `n`): the shape of the book, spreads, or a light history window. Native venue snapshots everywhere, and full-depth aggregated L2 on Hyperliquid core and HIP-3.
  </Card>

  <Card title="L3 order book" icon="list-ordered" href="/rest-api/order-books-l3">
    Individual orders on Lighter, without full lifecycle: up to 250 resting orders per side with order index and owner account index.
  </Card>

  <Card title="L4 order book" icon="blocks" href="/rest-api/order-books-l4">
    Every resting order on Hyperliquid families with `oid` and `user_address`, plus diffs and reconstruction: microstructure, queue position, or rolling the book forward from a checkpoint.
  </Card>
</CardGroup>

For file exports, use [Export schemas](/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, served from 2026-03-11 01:03 UTC:

| 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: resting orders across all served levels with `oid` and `user_address`, with the fields needed for deterministic order-level reconstruction. The L4 routes are in the venue tabs above (`/orderbook/{symbol}/l4`, `/l4/diffs`, `/l4/history`). For what happened to each order around the book, use [Order history](/rest-api/order-history) and [Order flow](/rest-api/order-flow).

```bash theme={"theme":"github-dark"}
curl "https://api.0xarchive.io/v1/hyperliquid/orderbook/BTC/l4" \
  -H "X-API-Key: $OXARCHIVE_API_KEY"
```

```json theme={"theme":"github-dark"}
{
  "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 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 | 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`. Levels list orders in true queue priority (ALO insertions included). |
| `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. L2 uses `px`/`sz` decimal strings; the Lighter L3 route instead uses numeric `price`, `remaining_size`, `original_size`, `order_index`, and `owner_account_index` fields. 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](/rest-api/order-books-l4)), 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](/websocket/l4-orderbook) and [WebSocket replay](/websocket/replay), or let [SDK reconstruction](/sdks/reconstruction) hold local book state for you.

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 can be reconstructed the same way twice.

## Stream or replay it

Hyperliquid core, Spot, and HIP-3 stream live books. Subscribe to `orderbook` for L2 and `l4_diffs` or `l4_orders` for order-level updates on Hyperliquid core. Spot and HIP-3 use prefixed L2 and L4 variants.

Lighter streams live L2 books on `lighter_orderbook`; see [Lighter WebSocket channels](/websocket/lighter). Current Lighter L3 snapshots use REST, and `lighter_l3_orderbook` supports historical WebSocket replay but not live subscriptions. Both Lighter book channels support historical replay, and historical data is also available through REST and exports. HIP-4 streams `hip4_l4_diffs` and `hip4_l4_orders`; HIP-4 current order-book reads use REST, and stored `hip4_orderbook` history remains replayable. For sequence and gap handling, see [WebSocket L4 order book](/websocket/l4-orderbook) and [WebSocket replay](/websocket/replay).

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

Order books export at three depths, delivered as Parquet with ZSTD compression: `l2_orderbook` (`$3/GB`, `$5 minimum`), `l3_orderbook` (`$3/GB`, `$5 minimum`), and `l4_orderbook` (`$4/GB`, `$12.50 minimum`). 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

For per-order depth, diffs, and reconstruction, 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.