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

# Hyperliquid L4 Order Book API

> Hyperliquid L4 order-book API for resting orders, diffs, history, and reconstruction across core, Spot, HIP-3, and HIP-4.

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](/rest-api/order-books-l2) is enough when aggregated levels answer the question, and Lighter exposes individual orders through [L3](/rest-api/order-books-l3) instead of L4. Order lifecycle, flow, fills, and TP/SL have their own routes: [Order history](/rest-api/order-history), [Order flow](/rest-api/order-flow), [Trades](/rest-api/trades), and [Take profits and stop losses](/rest-api/tpsl). Each symbol's L4 start date is on [Venue coverage](/venue-coverage), and the exact operations are in [OpenAPI](/openapi).

## Get an L4 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/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`.
  </Tab>

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

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

  <Tab title="HIP-4">
    ```bash theme={"theme":"github-dark"}
    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).
  </Tab>
</Tabs>

## 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](/data-quality) before relying on it.

## Example response

```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 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](/reference) carries the exact types, and full field meanings live in the [field dictionary](/responses#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. Null or absent means tail append. To reproduce queue order when rolling a checkpoint forward, insert the new order directly before that `oid` instead of appending. The field is populated on data from 2026-07-21 onward. 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. If your application keeps a continuously updated local book, apply ordered diffs/replay after that checkpoint; a snapshot-only consumer can use the returned state directly. 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 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`](/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: L4 order book | From 2026-03-11 01:03 UTC<br />REST only, no WebSocket channel<br />Up to 10 rows a page<br />A live or replayed L4 diff stream opens with a full L4 snapshot. |
| Hyperliquid: L4 diffs | From 2026-03-11 01:03 UTC<br />WebSocket `l4_diffs`: live and replay<br />Up to 10,000 rows a page<br />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<br />REST only, no WebSocket channel<br />Up to 10 rows a page<br />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<br />WebSocket `spot_l4_diffs`: live and replay<br />Up to 10,000 rows a page<br />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<br />REST only, no WebSocket channel<br />Up to 10 rows a page<br />A live or replayed L4 diff stream opens with a full L4 snapshot. |
| HIP-3: L4 diffs | From 2026-03-11 01:03 UTC<br />WebSocket `hip3_l4_diffs`: live and replay<br />Up to 10,000 rows a page<br />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<br />REST only, no WebSocket channel<br />Up to 10 rows a page<br />A live or replayed L4 diff stream opens with a full L4 snapshot. |
| HIP-4: L4 diffs | From 2026-05-02 07:47 UTC<br />WebSocket `hip4_l4_diffs`: live and replay<br />Up to 10,000 rows a page<br />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](/websocket/l4-orderbook) and [WebSocket replay](/websocket/replay).

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

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

## Export in bulk

L4 books export as the `l4_orderbook` schema (`$4/GB`, `$12.50 minimum`), and order-level events export as `l4_orders` (`$4/GB`, `$12.50 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

To see what happened to each order around the book, continue to [Order history](/rest-api/order-history).


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