Hyperliquid Fills - node_fills_by_block Data
Inspect Hyperliquid node_fills_by_block files, fill fields, sample data, and access methods.
Hyperliquid RPC endpoint: endpoint URLs, plans and pricing.
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 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 | S3 coverage for node_trades: 2025-03-22 to 2025-05-25, stored as .lz4. |
| Archival | S3 Bucket | S3 coverage for node_fills: 2025-05-25 to 2025-07-27, stored as .lz4. |
| Archival | S3 Bucket | S3 coverage for node_fills_by_block: 2025-07-27 to today, stored as hourly .lz4. |
| 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/<YYYYMMDD>/<hour>.lz4Each 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. |
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 when analysing these fields. Preserve account and order identity when deduplicating fills.
Observed fields
[] marks an array element, [0] a tuple position, <name> 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).
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, NetChildVaultPositionsnode_fills
Generated from 261,810 records in node_fills/20250726/14.lz4 (2025-07-26).
[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 numbernode_fills_by_block
Generated from 49,867 records in node_fills_by_block/20261021/14.lz4 (2026-10-21).
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 stringRelated 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.