Hyperliquid Order Book Diffs Data
Hyperliquid order book diffs carry every mutation to HyperCore's per-order book, one block at a time: a new resting order, a resize, or a removal.
An order book diff on Hyperliquid is one mutation to the per-order book. A node writes every L1 order diff, and one record names the order id, the owner, the market, the side, the price the mutation lands on, and the mutation itself. A mutation is a new resting order with its size, an update carrying the original and the new size, or a removal. Records arrive in a block envelope of block number, block time, local time and the events in that block.
What one record represents
A Hyperliquid node run with --write-raw-book-diffs “writes every L1 order diff”, and --batch-by-block writes those events one block per line under the envelope {local_time, block_time, block_number, events}.
One record is one mutation to the per-order book: oid, the order id being mutated; user, the address it belongs to; coin, the market; side, B for a bid and A for an ask; px, the price the mutation lands on; and raw_book_diff, the mutation itself.
The three diff shapes: new, update and remove
Hyperliquid’s L1 data schemas document the variants.
new, a new resting order, carrying itsszupdate, a resize, carryingorigSzandnewSz, which is a partial fill or a modifyremove, the bare string for an order leaving the book, which covers both a cancel and a full fill
The diff alone does not separate a cancel from a full fill, so the transition recorded in order status updates for the same oid resolves it.
Queue position and insertBefore
A new diff can carry insertBefore, the field that turns a price into a queue position. Hyperliquid’s order_book_server reference implementation defines it as the “Oid of the resting order at the same price level that this order is placed directly in front of (set for priority ALO orders). Absent means the back of the level.”
Diffs, snapshots and order statuses
Replayed in block order on top of an L4 order book snapshot, the diffs rebuild the per-order book exactly, which is Hyperliquid’s own framing of the snapshot: a checkpoint the order stream is applied to. Summing a rebuilt side by price gives the L2 order book, and the executions behind the removals and resizes are Hyperliquid fills.
Delivery
Available history is delivered as files to your own bucket. Fills, funding payments and position snapshots are also available as a Snowflake datashare and real time via Kafka Streaming, and they carry the same block height, so they join to the diffs without a translation layer.
Hyperliquid fields SonarX indexes
| Hyperliquid field | What it is | SonarX indexes it |
|---|---|---|
oid | the order id being mutated | ✓ |
user | the address the order belongs to | ✓ |
coin | the market; a builder-deployed perp carries the dex name as a prefix | ✓ |
side | B for the bid side, A for the ask side | ✓ |
px | the price level the mutation lands on | ✓ |
raw_book_diff | the mutation itself, one of new, update or remove | ✓ |
new | a new resting order, carrying its sz | ✓ |
insertBefore | the oid this order is placed directly in front of at the same price level; absent means the back of the level | ✓ |
update | a resize, carrying origSz and newSz | ✓ |
remove | a removal, the order leaving the book | ✓ |
block_number | the block the mutations belong to | ✓ |
block_time | the block timestamp | ✓ |
events | the list of diffs in that block | ✓ |
Field definitions and mechanics: Hyperliquid's own documentation. Chain overview: indexed Hyperliquid blockchain data.
Frequently asked questions
What is a Hyperliquid order book diff?
A book diff is one mutation to HyperCore's per-order book. A Hyperliquid node run with the write-raw-book-diffs flag writes every L1 order diff, and a diff is a new resting order, an update that resizes a resting order, or a removal that takes the order off the book.
What does one order book diff record represent?
One order book diff record is one mutation in one block. It names the order id, the owner address, the market, the side as B or A, the price the mutation lands on, and the mutation itself. Records arrive in the node's block envelope, which carries the block number, the block time, the local time and the list of events in that block.
What does insertBefore mean in a Hyperliquid book diff?
Hyperliquid's order_book_server reference implementation defines it as the oid of the resting order at the same price level that this order is placed directly in front of, set for priority ALO orders, with absent meaning the back of the level. It records queue position rather than price.
How do you rebuild a Hyperliquid order book from diffs?
Start from an L4 order book snapshot and replay the diffs on top of it in block order. Hyperliquid describes an L4 snapshot as a checkpoint upon which the order stream may be applied, so the snapshot supplies the starting state and the diffs supply every mutation from one snapshot to the next.
Does a remove mean the order was canceled or filled?
The diff alone does not say. A removal records that the order left the book, which covers both a cancel and a full fill. The order status stream carries the transition for that same order id, so joining on oid resolves which of the two happened.
What is the difference between book diffs and L4 snapshots?
A snapshot is the whole book at one height; a diff is one change to it. The snapshot gives a starting state and the diffs carry every mutation between snapshots, so the two together hold the per-order book at any block height without storing a snapshot for every block.
Get started
Query Hyperliquid order book diffs data
Tell us the delivery target and the history depth you need, and we scope the Hyperliquid share against it.
Other Hyperliquid datasets
Hyperliquid L4 Order Book Snapshots Data
Hyperliquid L4 order book data is the whole HyperCore book at one block height as individual resting orders: each order's id, price, size and owning address.
Hyperliquid Order Status Updates Data
Hyperliquid order status data records every transition an order goes through on HyperCore, from placement to fill, cancel or reject, with the full order object.
Hyperliquid L2 Order Book Snapshots Data
Hyperliquid L2 order book data is HyperCore's book collapsed to price levels at one block height: every price on each side, the resting size, the order count.
Hyperliquid Fills Data
Trades executed on HyperCore, per user and per market: price, size, side, direction, the position before the fill, realised PnL on the closed part, and fees.