# Hyperliquid Fills - node_fills_by_block Data `node_fills_by_block` records per-account execution details such as price, size, direction, realized PnL, fees, and optional builder attribution. A single match can include one taker and multiple makers. Self-trades can place more than one fill for the same account in that match. Within one block, group records by `(coin, tid)` to identify a match. Across blocks, include `block_number` or `block_time` in the match key. When deduplicating individual fills, retain account and order identity, such as `oid`. This preserves separate fills from one account in a self-trade. ## Access | Availability | Access | Details | | ------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Live / replay | [StreamFills](https://www.dwellir.com/docs/hyperliquid/stream_fills) and [GetFills](https://www.dwellir.com/docs/hyperliquid/get_fills) | V3 selects with `position.block_number` or `position.timestamp`; `Record.block_number` and `Record.timestamp` are transport cursors. V3 supports the documented `users` and `coins` filters, with fields combined using AND and values within a field using OR. V2 selects with `block_height` or `timestamp_ms` and returns source JSON bytes in `BlockFills.data`; it does not use the V3 record fields or filter contract. | | Live / replay | [hl\_getBatchBlocks](https://www.dwellir.com/docs/hyperliquid/hl_getBatchBlocks) | Returns `trades` fill blocks in an inclusive `[from, to]` range within retained data; older ranges are pruned and the newest block can briefly be unavailable. | | Archival | [S3 Bucket](https://www.dwellir.com/docs/hyperliquid/historical-data) | S3 coverage for `node_trades`: `2025-03-22` to `2025-05-25`, stored as `.lz4`. | | Archival | [S3 Bucket](https://www.dwellir.com/docs/hyperliquid/historical-data) | S3 coverage for `node_fills`: `2025-05-25` to `2025-07-27`, stored as `.lz4`. | | Archival | [S3 Bucket](https://www.dwellir.com/docs/hyperliquid/historical-data) | S3 coverage for `node_fills_by_block`: `2025-07-27` to today, stored as `hourly .lz4`. | | Historical | [Tick data](https://www.dwellir.com/docs/hyperliquid/tick-data) | Provides a processed historical alternative. | | Historical | [Indexed fills](https://www.dwellir.com/docs/hyperliquid/hyperliquid-index/fills) | Provides indexed historical queries. | ## File layout Current block-enveloped fills use this relative pattern: ```text node_fills_by_block//.lz4 ``` Each file contains JSON block envelopes. Historical fill prefixes have other shapes, so choose a parser from the prefix and record structure. ## Sample data ```json { "local_time": "2026-01-01T00:00:00.100000000", "block_time": "2026-01-01T00:00:00.000000000", "block_number": 12345, "events": [ [ "", { "coin": "BTC", "px": "118136.0", "sz": "0.00009", "side": "B", "time": 1704067200000, "startPosition": "-1.41864", "dir": "Close Short", "closedPnl": "-0.003753", "hash": "", "oid": 101, "crossed": false, "fee": "-0.000212", "tid": 202, "cloid": "", "feeToken": "USDC", "builder": "", "builderFee": "0.005528" } ] ] } ``` This is synthetic representative data. Production account, transaction, order, trade, client-order, and builder identifiers are replaced or use visible `` markers. ## Important fields | Field | Description | | ----------------------------------- | ----------------------------------------------------------------------------------------------------- | | `events[i][0]` | Account whose execution record follows. | | `block_number`, `coin`, `tid` | Match identity across blocks. Within one block, `(coin, tid)` identifies the match. | | `px`, `sz`, `side` | Execution price, size, and buy or ask side. Numeric values are strings. | | `startPosition`, `dir`, `closedPnl` | Position and realized-PnL context for the account. | | `oid`, `cloid`, `hash` | Order, client-order, and transaction identifiers. | | `crossed` | `true` for a taker fill and `false` for a maker fill. | | `fee`, `feeToken` | Fee or rebate and its token. | | `builder`, `builderFee` | Optional builder attribution. | | `twapId` | Optional parent TWAP identifier. Join to lifecycle `twap_id`; `oid` identifies the child order. | | `liquidation` | Optional metadata with `liquidatedUser`, `markPx`, and `method`. Counterparty fills can carry it too. | Use [TWAP join and liquidation validation rules](https://www.dwellir.com/docs/hyperliquid/research) when analysing these fields. Preserve account and order identity when deduplicating fills. ## Related pages - [Matched trades](https://www.dwellir.com/docs/hyperliquid/data-catalog/derived/trades) — Use a match-level view when per-account fill records are unnecessary. - [Derived fill views](https://www.dwellir.com/docs/hyperliquid/data-catalog/derived/fill-views) — Stream typed all-user, user, builder, and liquidation views. - [Whale tracking guide](https://www.dwellir.com/guides/hyperliquid-whale-tracking) — Build a real-time workflow around large fills and resting orders.