Running a node

A node gives you the full record; the public API gives you a view of it. API servers follow a node and serve filtered shapes, rate limited per IP address. Your own node trusts only consensus and is limited only by your hardware.

It is also your history. Precompiles answer only at the latest block (any explicit block number fails, even the current head), and the docs give no guarantee of timely updates to the public market-data archive.

Plan disk first: at default settings a node writes about 100 GB of logs a day, so 30 days takes about 3 TB. Archive or delete old files.

Where your node sits in the network

Running a non-validating node is permissionless; instructions are in the node repository. Validators never open their ports to the public; non-validating nodes peer with them and each other:

• any public peer, since the peer-to-peer network is public;
• the Foundation non-validating node in AWS apne1-az1, with fewer hops to validators and eligibility rules (see the numbers);
• infrastructure providers’ peering services listed in the docs, admitted only with open, non-discriminatory access and no preference for clients such as market makers.

A local API server pointed at your node serves the usual API shapes in real time.

What it writes to disk

Some outputs need command-line flags, documented in the node repository.

Path under ~/hl/data	Contents
replica_cmds/{start_time}/{date}/{height}	committed blocks, parsed as transactions
periodic_abci_states/{date}/{height}.rmp	full state snapshot, every 10,000 blocks
node_trades/hourly/{date}/{hour}	trades, with buyer and seller, starting positions, order ids and client ids
node_order_statuses/hourly/{date}/{hour}	every order status change, with the user’s address
node_raw_book_diffs/hourly/{date}/{hour}	per-order book changes: new, update, remove
misc_events/hourly/{date}/{hour}	staking deposits, delegations, withdrawals, validator rewards, funding and ledger updates
evm_block_and_receipts	HyperEVM blocks and receipts
dex_user_account_summaries/<dexIndex>/<date>/<hour>/<timestamp>.json	account values for one HIP-3 dex, written on each oracle update, with --write-user-account-summaries <dex>

Fills in API format need --write-fills; the public archive used --write-fills --batch-by-block. user_fills files carry priorityGas, the IOC priority fee each fill paid; replica_cmds also shows priority fees, worth order_price * order_sz * grouping_priority_rate in USDC.

Reading as fast as possible

The docs’ read-latency guide, in order:

1. Peer with a reliable, low-latency node, such as the Foundation’s.
2. Run with --disable-output-file-buffering, so outputs are written as each block executes.
3. Use the machine in the numbers below; more cores execute blocks faster.
4. Build the book and other state locally from node outputs, which beat the API on speed and granularity.
5. Drop --batch-by-block, which waits for each block’s end, and infer block boundaries yourself.
6. Set split_client_blocks: true for transactions about to be committed: inputs only, whose results the docs call feasible to predict for simple actions such as orders.
7. Buy gossip priority: two Dutch auctions on a shared 3-minute schedule rank IP addresses.

Rebuilding the full book

From any state snapshot a node can compute an L4 snapshot: every order at every level in time order, trigger orders last and marked isTrigger. Apply the order status stream for a real-time L4 book; insertBefore on new orders in raw book diffs keeps queues right once ALO priority fees reorder them. The docs’ example order book server does this but is unmaintained: fork it or write your own, handling priority fees.

HyperEVM data and backfill

• evm_block_and_receipts is written only after the node verifies committed blocks, so it needs no more trust than an RPC on the same node. Merge it, local first, with the requester-pays s3://hl-mainnet-evm-blocks/ (s3://hl-testnet-evm-blocks/) for a JSON-RPC server with your own rate limits, an explorer or indexers.
• Older data: requester-pays buckets hold L1 transactions (s3://hl-mainnet-node-data/replica_cmds), explorer blocks, fills and non-trade events; hyperliquid-archive holds L2 book snapshots and asset contexts, uploaded about monthly with no guarantee (data).

The numbers

Parameter	Value
Log output, default settings	about 100 GB per day
State snapshot interval	every 10,000 blocks
Machine for low-latency reads	at least 32 logical cores, 128 GB RAM, 500 MB/s disk
Split client blocks	inputs 70 to 150 ms earlier
Gossip priority	2 auctions, 3-minute schedule, about 25 ms per slot, minimum 0.1 HYPE, restarts at 10x the last winning price
Foundation node location	AWS apne1-az1
Foundation node access	10,000 HYPE staked; maker rebate tier 1 or above (over 0.5% of 14-day weighted maker volume); 98% time-weighted uptime as a public peer
Provider peering criteria	1 year of operation; at least 100 clients across 5 networks; 99.9% uptime; benchmark price under $1,000 a month
Validator programme	at least 2 non-validator nodes at 95% uptime
Measured peer round trip	about 70 ms from APAC to 252 ms from eastern Europe, TCP connect to gossip ports 4001 and 4002

A node as a trading tool

The Foundation node’s access rules target automated traders running one against it, buffering off, with a local API server on top. Linked trading and staking accounts may be combined to qualify.

Others see the same data: your resting orders, sizes and cancels are in every operator’s files, under your address.

Parsing what the node writes

A trade record, abridged from the docs: both sides in side_info, buyer first.

{
  "coin": "COMP",
  "side": "B",
  "time": "2024-07-26T08:26:25.899",
  "px": "51.367",
  "sz": "0.31",
  "hash": "0xad8e0566e813bdf98176040e6d51bd011100efa789e89430cdf17964235f55d8",
  "side_info": [
    { "user": "0xc64cc00b46101bd40aa1c3121195e85c0b0918d8", "start_pos": "996.67", "oid": 12212201265 },
    { "user": "0x768484f7e2ebb675c57838366c02ae99ba2a9b08", "start_pos": "-996.7", "oid": 12212198275 }
  ]
}

• misc_events entries are typed: CDeposit, Delegation, CWithdrawal (with is_finalized), ValidatorRewards, Funding and LedgerUpdate, whose variants include deposits, withdrawals, vault flows, liquidations, spot transfers, rewards claims and account activation gas.

Caveats in the node docs

• The Foundation node is best effort: no guaranteed availability, latency or completeness, not a sole or authoritative trading source, and access can be rate-limited or withdrawn without notice.
• Gossip priority is per hop. It helps only if the IP registered on chain exactly matches the one the sending peer sees, and each node may or may not respect it.
• Two trade formats. node_trades does not match the API; node_fills does.
• Check sz in order statuses. The docs call sz filled size and origSz original, yet show a cancelled order with sz equal to origSz.
• The docs disagree on public ports. The delegation programme page says not to open non-validator ports until mainnet non-validators are announced open; the Foundation node page requires public peers with them open.

For what sits between a node and the API, see API servers and how state reaches you. For a node in a trading stack, see Latency, priority and infrastructure.