Hyperliquid order book data: L2, L4 and history

Hyperliquid's API serves the current order book and keeps no book history. This page covers the live L2 feeds, what L4 means, the L2 snapshots in Hyperliquid's S3 archive, and the node output that records every order change so you can rebuild any book yourself.

The short version#

• Live L2: the l2Book info request or the l2Book WebSocket subscription. At most 20 levels per side.
• History from the API: none. There is no replay of past WebSocket messages.
• Archived L2: snapshot files per coin and hour in s3://hyperliquid-archive/market_data. Requester pays, uploaded about once a month.
• L4, every order with its owner: only from a node, with --write-raw-book-diffs and an L4 snapshot as the starting point.
• Ironflow API: no order book endpoint. Our nodes write the full diff stream.

1. l2Book over REST#

The info endpoint returns the current book for one coin, at most 20 levels per side. The request has weight 2 against the 1200 per minute IP budget.

curl -s https://api.hyperliquid.xyz/info \
  -H 'Content-Type: application/json' \
  -d '{"type":"l2Book","coin":"BTC","nSigFigs":5}'

{
  "coin": "BTC",
  "time": 1793089563935,
  "levels": [
    [{ "px": "79834.0", "sz": "7.36297", "n": 29 }],
    [{ "px": "79835.0", "sz": "3.79947", "n": 24 }]
  ]
}
# trimmed to the best level on each side; the response had 20 per side

• levels[0] holds bids from the best price down. levels[1] holds asks from the best price up.
• sz is the total size at that price in coins. n is the number of orders resting there.
• nSigFigs groups prices to 2, 3, 4 or 5 significant figures. Omit it for full precision. With nSigFigs: 3, BTC near 79,800 groups into 100 dollar levels.
• mantissa takes 1, 2 or 5 and is allowed only with nSigFigs: 5.
• HIP-3 builder markets use the dex prefix in the coin name, for example xyz:XYZ100.

A read-only node does not serve l2Book on its local info server. Our nodes return 422 for it. Book reads from a node come from its files, covered in section 5.

2. l2Book over WebSocket#

Subscribe on wss://api.hyperliquid.xyz/ws:

{ "method": "subscribe", "subscription": { "type": "l2Book", "coin": "ETH", "nSigFigs": 5 } }

• The server confirms with a subscriptionResponse message that echoes nSigFigs, mantissa and fast.
• Each l2Book message is a full snapshot of up to 20 levels per side with the same levels layout as REST. Each message replaces the previous one.
• Hyperliquid's type notes say a snapshot is pushed on a block at least 0.5 seconds after the previous push.
• fast: true returns 5 levels per side instead of 20.
• The bbo subscription sends only the best bid and ask, and only on blocks where they change.
• One IP can hold 10 connections and 1000 subscriptions. The rate limit docs list the rest.

The WebSocket has no replay. It starts at the moment you subscribe. To build an L2 history from the public API, record each message with its time field and store it yourself.

3. L2 and L4#

• L2 is price levels. Each level has a total size and an order count. It does not show who placed the orders or their place in the queue.
• L4 is Hyperliquid's name for the full order-level book: every resting order with its order id, owner address, side, limit price, size and placement time.

The book lives onchain, so L4 data is public. Any node can produce it. With L4 you can see queue position at a price, which wallets quote a market and how long their orders rest. With order statuses you also see why each order left the book.

4. L2 snapshots in S3#

Hyperliquid's historical data page lists L2 book snapshots in the hyperliquid-archive bucket. The path format is s3://hyperliquid-archive/market_data/[date]/[hour]/l2Book/[coin].lz4. The bucket is requester-pays: you need AWS credentials and you pay the transfer.

aws s3 cp s3://hyperliquid-archive/market_data/20230916/9/l2Book/SOL.lz4 /tmp/SOL.lz4 \
  --request-payer requester
unlz4 --rm /tmp/SOL.lz4
head /tmp/SOL

• Hyperliquid uploads to this bucket about once a month. It gives no guarantee of timely updates and says data may be missing.
• The files hold L2 snapshots only. There are no per-order records and no diffs between snapshots.
• The docs do not state the snapshot interval inside a file or the coverage per coin. List the bucket and read a sample before you build on it.

5. What a node writes#

A non-validator node applies every block and can write each change to disk. The flags are in the node README. The line formats are in the L1 data schemas.

Raw book diffs#

--write-raw-book-diffs writes every change to every resting order to ~/hl/data/node_raw_book_diffs/hourly/[date]/[hour]. With --batch-by-block the folder is node_raw_book_diffs_by_block and each line is one block with an events list. On our node the stream is about 5 GB an hour. Each event is one of three changes:

# new resting order
{"user":"0x7684...9b08","oid":35061046831,"coin":"CHILLGUY","side":"Bid","px":"1.36","raw_book_diff":{"new":{"sz":"186910.0"}}}
# size change on a resting order
{"user":"0x7684...9b08","oid":35061055064,"coin":"BTC","side":"Bid","px":"115323.2","raw_book_diff":{"update":{"origSz":"0.2086","newSz":"0.2076"}}}
# order left the book
{"user":"0xc64c...18d8","oid":35061057543,"coin":"HYPE","side":"Ask","px":"115200.2","raw_book_diff":"remove"}

A remove diff says that an order left the book. It does not say why.

Order statuses#

--write-order-statuses writes every order event with the full order: type, time in force, reduce-only, trigger fields, client order id, original size and filled size. The status field gives the reason. Values include open, filled, canceled, triggered, rejected, marginCanceled, selfTradeCanceled, liquidatedCanceled and badAloPxRejected. The full list is under orderStatus in the info endpoint docs. On our node this output is about 25 GB an hour.

L4 snapshots#

Diffs are a pure delta stream. You need a starting book. The node saves its state every 10,000 blocks to ~/hl/data/periodic_abci_states/[date]/[height].rmp and can turn one into an L4 snapshot:

./hl-node --chain Mainnet compute-l4-snapshots <abci-state-path> <out-path>

A node running --serve-info can write a snapshot of its latest state instead. Send this to localhost:3001/info:

{
  "type": "fileSnapshot",
  "request": { "type": "l4Snapshots", "includeUsers": true, "includeTriggerOrders": false },
  "outPath": "/tmp/l4.json",
  "includeHeightInOutput": true
}

Orders at one price are sorted by time. Trigger orders come last and carry isTrigger.

6. Rebuilding a book#

• Load an L4 snapshot taken at block height H.
• Apply diffs from the blocks after H, in block order. new adds the order. update sets its size to newSz. remove deletes it.
• For L2, sum the size and count the orders at each side and price.
• Sort hour files as numbers. Hour names are not zero-padded, so a string sort puts 10 before 9.

This script rebuilds one coin from one hour file. It starts with an empty book, so orders that rested before the file began stay unknown until an update or remove names them:

# usage: python3 rebuild_book.py ~/hl/data/node_raw_book_diffs_by_block/hourly/20261027/9 BTC
import json, sys
from collections import defaultdict

path, coin = sys.argv[1], sys.argv[2]
orders = {}  # oid -> [side, px, size]
for line in open(path):
    block = json.loads(line)
    for d in block["events"]:
        if d["coin"] != coin:
            continue
        diff = d["raw_book_diff"]
        if diff == "remove":
            orders.pop(d["oid"], None)
        elif "new" in diff:
            orders[d["oid"]] = [d["side"], d["px"], float(diff["new"]["sz"])]
        elif "update" in diff:
            orders[d["oid"]] = [d["side"], d["px"], float(diff["update"]["newSz"])]

# aggregate orders into L2 levels: (side, px) -> [total size, order count]
levels = defaultdict(lambda: [0.0, 0])
for side, px, sz in orders.values():
    levels[(side, px)][0] += sz
    levels[(side, px)][1] += 1
bids = sorted(((float(p), v) for (s, p), v in levels.items() if s == "Bid"), reverse=True)
asks = sorted((float(p), v) for (s, p), v in levels.items() if s == "Ask")
print("block", block["block_number"], "orders", len(orders))
print("best bid", bids[:1], "best ask", asks[:1])

Our nodes build mid prices from this stream without a snapshot. They start at the beginning of the current hour file and trust a book only after checks: both sides present, the book not crossed, the spread inside a limit, and recent trades printing inside the bid and ask. A crossed book means a missed removal. An unusually wide spread means a missing best order.

7. What Ironflow serves#

The Ironflow REST API has no order book endpoint, live or historical. It does not serve book snapshots, order statuses or a WebSocket. It serves fills, trades, candles, funding, liquidations, open interest and mark prices from our own node.

For L2 and L4 data, a dedicated Ironflow node writes the full raw book diff stream to its own disk as blocks arrive. You run the rebuild above on that box, with no public API weight spent.

Questions#

Related guides#

• Hyperliquid historical data: API, S3 archive and Python
• Hyperliquid trades and fills data
• Hyperliquid candles and OHLCV data
• Hyperliquid liquidation data: history, levels and API
• Hyperliquid funding rates: formula, history and API
• Hyperliquid WebSocket API: subscriptions, limits and a Python example
• How to run a Hyperliquid non-validator node

References#

• Hyperliquid docs: Info endpoint. The l2Book request, nSigFigs, mantissa and the order status values.
• Hyperliquid docs: WebSocket subscriptions. The l2Book and bbo subscriptions and the WsBook type.
• Hyperliquid docs: Historical data. The hyperliquid-archive bucket and its L2 snapshot path.
• Hyperliquid docs: L1 data schemas. Raw book diff, order status and L4 snapshot formats.
• hyperliquid-dex/node. The write flags, compute-l4-snapshots and the fileSnapshot request.
• Hyperliquid docs: Rate limits and user limits. Request weights and WebSocket caps.