Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Verified HyperLiquid examples

Largest recent fills

The query reads the current raw fill table and retains wallet, fee, builder, TWAP and liquidation context through the underlying row.

SELECT
    utc_fill_dttm,
    fill_id,
    wallet_address,
    coin,
    side,
    price,
    size,
    price * size AS notional,
    closed_pnl,
    fee,
    liquidation_user
FROM hyperliquid.raw_node_fills_by_block
PREWHERE utc_fill_dt >= today() - 1
ORDER BY notional DESC
LIMIT 100

Source: examples/hyperliquid/largest_recent_fills.sql.

Raw order-book archive

The example supports a local directory or a configurable HTTP archive listing:

HYPERLIQUID_ORDER_BOOKS=https://captures.example.com/hyperliquid/

1. Scan the raw filesystem

python3 examples/orderbooks/hyperliquid.py scan

The recursive listing includes MessagePack ABCI checkpoints under abci/ and compressed hourly JSON streams under book_diffs/, order_statuses/, and fills/.

2. Download a checkpoint and its hourly diffs

Choose paths returned by the scanner. Nested paths are allowed, but traversal outside the configured archive is rejected.

python3 examples/orderbooks/hyperliquid.py download \
  abci/CHECKPOINT.rmp /tmp/checkpoint.rmp
python3 examples/orderbooks/hyperliquid.py download \
  book_diffs/YYYYMMDD/HOUR.zst /tmp/book-diffs.zst

The same-origin, traversal and 64 MiB bounds used by the Polymarket downloader also apply here.

3. Reconstruct directly from the raw formats

python3 examples/orderbooks/hyperliquid.py reconstruct-raw \
  /tmp/checkpoint.rmp BTC ACTION_ASSET SIZE_DECIMALS \
  /tmp/book-diffs.zst

ACTION_ASSET and SIZE_DECIMALS are the historical numeric asset encoding and size precision from that checkpoint's metadata. The replay reader seeks directly to the selected spot or perpetual book inside the MessagePack checkpoint rather than loading the entire checkpoint into memory. It then streams the zstd hourly envelopes and applies matching raw_book_diff records by order ID. Each diff:

  • inserts a new order with its order ID, side, price and size;
  • changes the remaining size of an existing order; or
  • removes the order ID.

Only after replay are live orders aggregated into price levels. This preserves correctness for partial fills and cancellation of one order among several at the same price. The output reports timestamp, best bid, best ask and live order count.

The strict build executes scan, bounded download and reconstruction against both a deterministic JSONL recovery sequence and a generated MessagePack checkpoint plus raw hourly diff stream. It also recursively scans the configured live HyperLiquid archive, so storage-layout drift fails the docs build.

Strict 24-hour cross-venue build check

Inside the Docker checker stage, the verifier selects a captured Polymarket Bitcoin five-minute interval near UTC now - 24 hours and reads checkpoint timestamps from the live archive. It downloads the newest ABCI MessagePack checkpoint at or before that interval plus every required hourly diff file. For the BTC perpetual book it then:

  1. loads the order-level checkpoint state for action asset 0;
  2. ignores diff blocks already represented by the checkpoint;
  3. applies raw diffs across the exact market window;
  4. samples bid, ask, midpoint, spread and ten-basis-point depth each second; and
  5. requires live orders and a non-crossed best_bid < best_ask result.

The raw inputs are held in a temporary directory and removed before the checker layer is committed. The generated chart continues to the static-site builder. This is intentionally a large, slow integrity check.

python3 examples/orderbooks/hyperliquid.py reconstruct-raw-at \
  /tmp/checkpoint.rmp BTC 0 5 TARGET_UTC \
  /tmp/book-diffs-1.zst /tmp/book-diffs-2.zst