# 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. ## Observed fields `[]` marks an array element, `[0]` a tuple position, `` an object whose `type` is that name, and `{key}` a map keyed by user, asset, or ID. Values after a colon are every distinct value seen for a short enum field. A field missing here can still appear in record types the sample did not contain. ### `node_trades` Generated from 73,746 records in `node_trades/20250524/14.lz4` (2025-05-24). ```text coin string hash string px string side string: A, B side_info array side_info[] object cloid null | string oid number start_pos string twap_id null | number user string sz string time string trade_dir_override string: LiquidatedMarket, Na, NetChildVaultPositions ``` ### `node_fills` Generated from 261,810 records in `node_fills/20250726/14.lz4` (2025-07-26). ```text [0] string [1] object builder string builderFee string cloid string closedPnl string coin string crossed bool dir string: Buy, Close Long, Close Short, Long > Short, Net Child Vaults, Open Long, Open Short, Sell, Short > Long fee string feeToken string hash string liquidation object liquidatedUser string markPx string method string: market oid number px string side string: A, B startPosition string sz string tid number time number ``` ### `node_fills_by_block` Generated from 49,867 records in `node_fills_by_block/20261021/14.lz4` (2026-10-21). ```text block_number number block_time string events array events[] array events[][0] string events[][1] object builder string builderFee string cloid string closedPnl string coin string crossed bool deployerFee string dir string fee string feeToken string hash string liquidation object liquidatedUser string markPx string method string: market oid number priorityGas string px string side string: A, B startPosition string sz string tid number time number twapId null | number local_time string ``` ## 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.