Hyperliquid Fills - node_fills_by_block Data
Inspect Hyperliquid node_fills_by_block files, fill fields, sample data, and access methods.
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, and self-trades can place more than one fill for the same account in that match. Group records by (coin, tid) to identify a match. When deduplicating individual fills, add the account or order identity so you do not collapse legitimate participants.
Access
| Availability | Access | Details |
|---|---|---|
| Live / replay | StreamFills and GetFills | 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 | 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 | Provides archival raw fill objects. |
| Historical | Tick data | Provides a processed historical alternative. |
| Historical | Indexed fills | Provides indexed historical queries. |
File layout
Current block-enveloped fills use this relative pattern:
node_fills_by_block/hourly/<date>/<hour>Each file contains JSON block envelopes. Historical fill prefixes have other shapes, so choose a parser from the prefix and record structure.
Sample data
{
"local_time": "2026-01-01T00:00:00.100000000",
"block_time": "2026-01-01T00:00:00.000000000",
"block_number": 12345,
"events": [
[
"<redacted-user>",
{
"coin": "BTC",
"px": "118136.0",
"sz": "0.00009",
"side": "B",
"time": 1704067200000,
"startPosition": "-1.41864",
"dir": "Close Short",
"closedPnl": "-0.003753",
"hash": "<redacted-transaction-hash>",
"oid": 101,
"crossed": false,
"fee": "-0.000212",
"tid": 202,
"cloid": "<redacted-client-order-id>",
"feeToken": "USDC",
"builder": "<redacted-builder>",
"builderFee": "0.005528"
}
]
]
}This is synthetic representative data. Production account, transaction, order, trade, client-order, and builder identifiers are replaced or use visible <redacted-...> markers.
Important fields
| Field | Description |
|---|---|
events[i][0] | Account whose execution record follows. |
coin, tid | Match identity when used together. tid alone is not globally unique. |
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. |
Related pages
- Matched trades — Use a match-level view when per-account fill records are unnecessary.
- Derived fill views — Stream typed all-user, user, builder, and liquidation views.
- Whale tracking guide — Build a real-time workflow around large fills and resting orders.