How to run a Hyperliquid non-validator node

A setup guide for engineers who want to run their own Hyperliquid non-validator node. It covers hardware, install, peers, output flags, first sync, disk, monitoring and gaps. We run these nodes in production.

What the node does#

A non-validator node follows the chain without voting on it. It applies every block and keeps the full exchange state in memory. It can write every fill, every order book change and every funding or ledger event to disk as JSON lines, which means one JSON object per line. The Hyperliquid node docs and the node repository are the primary sources.

With --serve-info it also answers part of the info API locally. These request types work: clearinghouseState, spotClearinghouseState, openOrders, frontendOpenOrders, meta, userAbstraction. These return 422: allMids, l2Book, userFills, portfolio. A 422 is an HTTP error that means the server does not support the request. Local reads do not count against the public API rate limits. The node does not take orders. Orders still go to Hyperliquid's API, for example through the official Python SDK.

Terms#

Validator / non-validator

Validators vote on new blocks. A non-validator node receives the same blocks and keeps the same state, but does not vote.

Gossip

The peer-to-peer network nodes use to pass blocks and state to each other.

Root peers

Entry points Hyperliquid publishes. Your node connects to them first and finds other peers through them.

hl-visor

The supervisor program. It downloads the node binary, verifies it, runs it and restarts or upgrades it.

Node (child process)

The program hl-visor starts. It does the actual work of applying blocks and writing data.

State snapshot (ABCI state)

A copy of the full exchange state at a recent block. A new node loads it so it does not have to replay the whole chain.

Pointer file

hyperliquid_data/visor_abci_state.json. It tells the visor which saved state to load on restart.

replica_cmds

The raw block data the node receives. It is the largest thing on disk.

Fills and book diffs

A fill is one executed trade. A book diff is one change to an order book: an order added, changed or removed.

Info API

Hyperliquid's read-only HTTP API for account and market data. The node can answer part of it locally.

1. Hardware#

• RAM: 128 GB. The node uses about 40 GB in normal operation. During network stress it buffers blocks it has not applied yet and memory climbs fast. 64 GB is not enough headroom.
• CPU: 8 cores / 16 threads, high clock speed. Applying blocks is mostly single-threaded. More cores do not help much.
• Disk: 2 TB NVMe. The node writes about 700 GB a day before cleanup. Most of it is replica_cmds (raw block data) and the hourly event files.
• Network: gossip traffic from other nodes is about 2 MB/s inbound, around 5 TB a month. Open TCP 4001 and 4002 so peers can reach you.
• Bare metal. Shared or burstable instances fall behind under load.

nproc && free -g | sed -n 2p && df -h /

2. Install hl-visor#

hl-visor is the supervisor. It downloads the node binary, checks its signature and runs it. Install it on Ubuntu 24.04:

curl -L https://binaries.hyperliquid.xyz/Mainnet/hl-visor -o /usr/local/bin/hl-visor
chmod +x /usr/local/bin/hl-visor

# the visor checks node binaries against Hyperliquid's key
apt install -y gnupg
curl -s https://raw.githubusercontent.com/hyperliquid-dex/node/main/pub_key.asc | gpg --import

# the visor will not start without this file
echo '{"is_validator": false, "chain": "Mainnet"}' > /usr/local/bin/visor.json

• curl -L ... -o downloads the file and follows redirects. chmod +x makes it executable.
• gpg --import adds Hyperliquid's public signing key. The visor uses it to verify every node binary it downloads.
• visor.json tells the visor to run as a non-validator on mainnet.

The visor can fail to start when the host resolves its own address to IPv6. This line tells the system to prefer IPv4 addresses when a name has both:

echo 'precedence ::ffff:0:0/96 100' >> /etc/gai.conf

If it still says it cannot determine its public IP on a host with both IPv4 and IPv6, turn IPv6 off.

ls -l /usr/local/bin/hl-visor /usr/local/bin/visor.json && gpg --list-keys

3. Gossip peers#

The node needs root peers to join gossip. It will not start without them. Ask the public API for the current list. The gossipRootIps request returns a JSON array of IP addresses:

curl -s -X POST https://api.hyperliquid.xyz/info \
  -H 'Content-Type: application/json' -d '{"type":"gossipRootIps"}'

Put the addresses in ~/hl/override_gossip_config.json, the node's working directory:

{
  "root_node_ips": [{"Ip": "<ip-1>"}, {"Ip": "<ip-2>"}, {"Ip": "<ip-3>"}],
  "try_new_peers": true,
  "chain": "Mainnet"
}

• root_node_ips: the peers the node connects to first.
• try_new_peers: lets the node connect to other peers it learns about.
• chain: the network, Mainnet or Testnet.

Peer quality matters more than CPU. A node with one slow or distant upstream peer falls behind while the server sits idle. Keep several root peers. Prefer peers close to you. Refresh the list regularly. n_gossip_peers is an optional setting in the same file. It sets how many peers the node keeps connected.

Root peers right now#

The map and the radar show a TCP connect to port 4001 of each root peer, made from one server location at the time shown. Peer regions come from the cloud providers' published IP ranges. Peers outside those ranges show as "other". This does not tell you which peer is a good upstream for your node. Latency from your server will differ. A peer that does not answer this probe may still serve other nodes. Run the same check from your own server. jq -r '.[]' prints each address on its own line. nc -z -w2 tries a TCP connection without sending data and gives up after 2 seconds:

for ip in $(curl -s -X POST https://api.hyperliquid.xyz/info \
  -H 'Content-Type: application/json' -d '{"type":"gossipRootIps"}' | jq -r '.[]'); do
  nc -z -w2 "$ip" 4001 && echo "$ip up" || echo "$ip no answer"; done

python3 -m json.tool ~/hl/override_gossip_config.json

4. Run the node#

You never start the node binary yourself. You start hl-visor. It downloads the node binary, verifies its signature with the key you imported, starts the node as a child process and restarts it if it exits. It also upgrades the node when Hyperliquid publishes a new version.

Run the visor as a systemd service so it starts on boot and restarts after a crash. Save this as /etc/systemd/system/hlnode.service. The unit is named hlnode on purpose, so no command you type contains the program names. Step 7 explains why that matters.

[Unit]
Description=Hyperliquid non-validator node
After=network-online.target

[Service]
WorkingDirectory=/root/hl
ExecStart=/usr/local/bin/hl-visor run-non-validator \
  --write-fills \
  --write-raw-book-diffs \
  --write-misc-events \
  --batch-by-block \
  --disable-output-file-buffering \
  --serve-info
Restart=always
RestartSec=10
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

What each line does:

• After=network-online.target: start only once the network is up.
• WorkingDirectory=/root/hl: the folder the node uses. The peer config and the data folder live here.
• The unit runs as root to keep the guide short. A separate user with no sudo rights is safer; hyperliquid-node-kit sets that up.
• ExecStart=... run-non-validator: the command systemd runs. It starts the visor in non-validator mode with the flags below.
• Restart=always and RestartSec=10: if the visor exits for any reason, start it again after 10 seconds.
• LimitNOFILE=65536: lets the process keep many files and connections open at once.
• WantedBy=multi-user.target: start the service on boot.

The flags choose what the node writes and serves. Every output costs disk. Turn on only the ones you read:

• --write-fills: writes every fill, both sides, with builder and liquidation fields.
• --write-raw-book-diffs: writes every order book change. About 5 GB an hour. You can rebuild the full book from it.
• --write-misc-events: writes funding, deposits, withdrawals, vault and ledger events.
• --batch-by-block: writes one line per block that holds all of that block's events. This is the same format as the public S3 archive. You cannot combine it with --stream-with-block-info, which is a different output layout.
• --disable-output-file-buffering: writes each line to disk as soon as it exists. Without it, lines wait in memory and your readers see them late.
• --serve-info: starts the local info API on port 3001.
• --write-order-statuses (not in the unit above): writes every order status change. About 25 GB an hour. Leave it off unless you need it.

Output goes under ~/hl/data/ in hourly files, for example node_fills_by_block/hourly/20260918/9. The L1 data schemas page documents the line formats. The hour names are not zero-padded: 0, 1, ... 9, 10, ... 23. Sort them as numbers. A string sort puts 9 after 10.

Create the folder and start the service:

mkdir -p /root/hl
systemctl daemon-reload
systemctl enable --now hlnode

• systemctl daemon-reload: makes systemd read the new unit file.
• systemctl enable --now hlnode: starts the service now and on every boot.

Follow the logs:

journalctl -u hlnode -f

journalctl -u hlnode -fshows the service's log and keeps printing new lines. On a healthy first start you see three phases. First the visor downloads and verifies the node binary. Then the node downloads a state snapshot from a peer and prints its progress in bytes. Then it applies blocks and the hourly files appear under ~/hl/data/. Step 5 covers the wait.

A flag change applies at the next restart. A forced restart can make the node download the state snapshot again. Change flags when you can wait for a natural restart.

systemctl is-active hlnode

5. First sync#

On first start the node downloads a state snapshot of about 940 MB from a peer. The snapshot is a copy of the full exchange state at a recent block. The node then applies the blocks that came after it. It takes 10 to 30 minutes. Output files only appear once it has caught up. Restart once at most, then leave it. Every restart starts the download again.

The node also saves its own state to data/periodic_abci_states/ about every 12 minutes. On restart the visor loads the newest saved state instead of downloading one. It finds that state through a small pointer file, hyperliquid_data/visor_abci_state.json. Loading local state takes seconds. An unclean crash can lose the pointer file, and then the visor downloads the snapshot from peers again. Back up the pointer file and restore it before a restart.

ls ~/hl/data/node_fills_by_block/hourly/$(date -u +%Y%m%d)/

curl -s localhost:3001/info -H 'Content-Type: application/json' \
  -d '{"type":"meta"}' | head -c 200

6. Disk cleanup#

Without cleanup a 2 TB disk fills in two to three days. A full disk crashes the node. Run a cleanup job every hour:

• Delete hourly output older than your retention window. 24 hours is a reasonable default.
• Delete old replica_cmds date directories.
• Check with lsof before deleting. lsof lists the files that running processes have open, so you can skip a file the node is still writing.
• In bash, force base 10 when you compare hour numbers. Bash reads a number with a leading zero as octal (base 8), so 08 and 09 are invalid. 10# in front of the variable forces base 10.

h=$((10#$hour))

df -h ~/hl && du -sh ~/hl/data/* | sort -h | tail -5

7. Watchdog#

• Measure freshness from the data. The process can be running and still be hours behind the chain. Every line the node writes carries a block_time, the time the block was produced. Read it from the last line of the newest fills file and compare it to the clock.
• Keep the program names out of command lines. Every running process has a command line: the program name plus the arguments it was started with. When the supervisor starts, it lists all running processes. If another process has hl-visor or hl-node anywhere in its command line, the supervisor thinks a second copy is running and stops with a panic.
• How this happens in practice. A monitoring script runs pgrep hl-node, which searches the process list for that name and has the name in its own command line. An alert sends a message that contains the name. Someone runs an ssh command with the name in it. Any of these running at the moment the supervisor starts is enough.
• What to do instead. To check whether the node runs, read the process names from /proc/*/comm. Every process has a small file there that holds only its name, and reading it puts no name in your own command line. In scripts and alerts, build the name from parts, for example n="hl-"; n="$n"node, so the full name never appears as one argument.
• Restart with a cooldown and a limit. Use systemctl restart --no-block hlnode. --no-block makes the command return at once instead of waiting until the service has restarted. Your script then exits before the supervisor starts and lists processes, so your script's own command line is not in that list. Wait between attempts. Do not restart while the node is still downloading state. After a few failed restarts, stop and page a person.

f=$(ls -d ~/hl/data/node_fills_by_block/hourly/*/* | sort -V | tail -1)
tail -n 1 "$f" | grep -o '"block_time":"[^"]*"'
date -u +%Y-%m-%dT%H:%M:%S

8. Gaps#

Under load or around a restart the node sometimes skips writing a range of blocks. You cannot get those back from the node. Every hour, check that block numbers in your data run in order with no missing ranges. Do it in whatever database you load the files into.

Many blocks have no fills. Short runs of missing block numbers are normal. Set your gap threshold high enough to ignore them, or you will get false alarms.

Fill gaps from Hyperliquid's public archive, s3://hl-mainnet-node-data. It is an Amazon S3 bucket. It is requester-pays, which means your AWS account pays the download cost, so you need AWS credentials. The files are compressed with LZ4. Decompress them with lz4 -d. The format matches --batch-by-block. The hour file shows up about an hour after the hour closes.

aws s3 cp s3://hl-mainnet-node-data/node_fills_by_block/hourly/20260918/9.lz4 . \
  --request-payer requester

aws s3 ls s3://hl-mainnet-node-data/node_fills_by_block/hourly/$(date -u -d yesterday +%Y%m%d)/ \
  --request-payer requester

9. Where to host it#

Hyperliquid's validators are in Tokyo. Distance to Tokyo sets two things: how fast your orders reach Hyperliquid's API, and how close your gossip peers are. From a Tokyo server an order reaches the API in about 4.5 ms and the nearest peer is about 2 ms away. From other continents both take several hundred milliseconds.

A node far from Tokyo still works for data collection. It falls behind more often because its peers are far away. Host in or near Tokyo if anything downstream cares about latency.

Health check#

One script checks the usual failure points in a few seconds. It is read-only, needs no root, and keeps the program names out of every command line it runs, so it cannot trip the supervisor panic described in the watchdog step. Read it before you run it.

curl -fsSL https://ironflow.sh/node-check.sh -o node-check.sh
less node-check.sh
bash node-check.sh                 # HL_HOME=/root/hl bash node-check.sh if the node runs as root

• The supervisor and the node are both running.
• Your supervisor binary matches the published one. It never updates itself, and an old one crash-looped nodes at the 25 October 2026 hardfork.
• How many seconds since the node last wrote fills: behind after a minute, stalled after ten.
• Disk use and the number of EVM checkpoints kept, and how much memory is free.
• Gossip ports 4001 and 4002 listen, and the info server on 3001 is not open on every interface.
• The gossip peers file exists.

It exits 0 when everything passes, 1 on warnings and 2 on a failure, so a cron line can alert on it: */5 * * * * bash /opt/node-check.sh > /var/log/node-check.log || your-alert-command.

Troubleshooting#

Common errors#

Log lines people hit when they run a node, with the cause and the fix. Addresses and byte counts in your log will differ. Crash logs from the node process are in ~/hl/data/visor_child_stderr/.

Questions#

Related guides#

• Hyperliquid node crash after the October 2026 hardfork: missing node_metadata.json
• Hyperliquid node disk filling up: EVM checkpoints and how to prune them
• Hyperliquid API rate limits explained
• Hyperliquid historical data: API, S3 archive and Python

References#

• hyperliquid-dex/node. Official node README: install, flags, ports, hardware.
• ironflowsh/hyperliquid-node-kit. Scripts for this guide: installer, cleanup, watchdog and peer refresh timers, and a read-only MCP server for the local node.
• Hyperliquid docs: Nodes. Overview of validator and non-validator nodes.
• Hyperliquid docs: L1 data schemas. Format of the files the node writes.
• Hyperliquid docs: Info endpoint. Request types the local info server mirrors.
• Hyperliquid docs: Rate limits and user limits. The public API limits a local node avoids for reads.
• Hyperliquid docs: Historical data. The public S3 archive used to fill gaps.
• hyperliquid-python-sdk. Official SDK for placing orders from the same server.