Running a Hyperliquid Archive Node: History, Storage, and Query Access

Hyperliquid Data Surfaces and Node Roles

Hyperliquid is a purpose-built L1 composed of HyperCore and HyperEVM, and its public data surfaces include a JSON-RPC/REST API for live state, a WebSocket for streaming, and archive/flat-file style exports for bulk history. The Hyperliquid documentation describes nodes, API surfaces, and data access, and it is the authoritative starting point for understanding which surface serves which kind of data.

A full node keeps recent state and is optimized for validating and serving the current chain tip. An archive node retains the full ledger, transaction, and, where applicable, state history needed for deep backtests and point-in-time reads. The distinction matters because a pruned node will return an error or empty result for a historical state query that an archive node answers with a non-null value.

Before choosing an operating model, map your workload to the right surface. Live trading and monitoring belong on the JSON-RPC/REST and WebSocket surfaces, while bulk offline analytics and backtests belong on archive/flat-file exports or an archive node. The Hyperliquid RPC endpoints (RPC Assistant) page lists endpoint options, and the Hyperliquid historical market data API article covers the data API surface for market-specific history.

• JSON-RPC/REST API: live state, transaction submission, and recent block queries.
• WebSocket: streaming updates for real-time applications.
• Archive/flat-file exports: bulk history for offline processing, not live queries.
• Archive node: full ledger and state history served over JSON-RPC for point-in-time reads.

Three Ways to Obtain Deep Hyperliquid History

The first option is to run an archive node yourself for full control and the newest data. This gives you a private endpoint that can serve historical state queries and keeps you independent of third-party rate limits, but it requires significant storage, RAM, CPU, and bandwidth, and it is slower to sync than a full node.

The second option is to consume an archive/flat-file export from object storage for bulk offline processing. This is efficient for large backtests because you read files directly without running a node, but exports are only as fresh as the last export and cannot serve the chain tip or answer live queries.

The third option is to query a provider that exposes historical state over JSON-RPC for point-in-time reads. This avoids operating storage-heavy infrastructure, but the exact archive range and query surface depend on the provider. Compare these models against the tradeoffs in Archive node vs full node and the methods in Accessing historical blockchain data.

• Self-hosted archive node: full control, newest data, highest operational cost.
• Archive/flat-file export: bulk offline processing, no live queries, freshness limited by export cadence.
• Provider-hosted historical JSON-RPC: point-in-time reads without storage operations, range varies by provider.

Resource Dimensions for an Archive Node

Storage grows with retention, so plan from observed ledger growth multiplied by your target window. Measure the growth rate on a full node or from export metadata, then project the storage required for the archive range you need. Do not assume a fixed size; the requirement depends on chain activity and your retention policy.

RAM is consumed by state and indexes, and CPU is consumed by execution and query serving. Bandwidth is consumed by ingest and by client queries. Because these dimensions interact, a node that is adequate for recent state may be undersized for archive serving, especially when many historical queries run concurrently.

A practical planning method is to record storage used at two points in time, compute the delta, and extrapolate. The results table later in this article provides columns for storage used and retention window so you can track this against your own endpoint.

• Storage: retention window x observed ledger growth rate.
• RAM: state and index footprint, which grows with history.
• CPU: execution and query serving under concurrent load.
• Bandwidth: ingest plus client query traffic.

Verifying That an Archive Node Serves History

To verify archive availability, issue a historical state query for a known old block or hash and confirm a non-null result. The Ethereum JSON-RPC specification at ethereum.org documents the archived-state query pattern that an archive node serves, and the JSON-RPC 2.0 specification at jsonrpc.org defines the request shape used to probe archive availability.

Contrast the archive response with a pruned node, which returns an error or empty result for the same query. A non-null historical result is evidence that the node retains the state for that block, while an error such as a missing trie node or an empty result indicates the state is not available.

Because provider-specific behavior varies, treat the probe as a reproducible test rather than a guarantee. Run it against your own endpoint and record the outcome in the results table.

• Archive node: historical state query returns a non-null result.
• Pruned node: same query returns an error or empty result.
• Provider behavior: documented / varies by provider, so verify per endpoint.

Probing Historical Availability with curl

The following curl example sends a JSON-RPC POST for an old block and a point-in-time state read, printing PASS if the archive range is served. Replace the endpoint and block number with values for your target chain and node.

Run it against a known archive endpoint and a known pruned endpoint to observe the difference. The script checks for a non-null result and exits with a clear status.

#!/usr/bin/env bash
set -euo pipefail

ENDPOINT="${1:-http://127.0.0.1:8545}"
BLOCK="${2:-1000000}"

block_resp=$(curl -s -X POST "$ENDPOINT" \
  -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getBlockByNumber\",\"params\":[\"0x$(printf '%x' "$BLOCK")\", false]}")

echo "Block response: $block_resp"

if echo "$block_resp" | grep -q '"result":null'; then
  echo "FAIL: block $BLOCK not available (pruned or out of range)"
  exit 1
fi

state_resp=$(curl -s -X POST "$ENDPOINT" \
  -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"eth_getBalance\",\"params\":[\"0x0000000000000000000000000000000000000000\",\"0x$(printf '%x' "$BLOCK")\"]}")

echo "State response: $state_resp"

if echo "$state_resp" | grep -q '"result":null'; then
  echo "FAIL: historical state at block $BLOCK not available"
  exit 1
fi

echo "PASS: archive range served for block $BLOCK"

Probing Historical Availability with Node.js

This Node.js example performs the same probe using fetch, which is available in modern Node.js runtimes. It checks an old block and a point-in-time state read, then prints PASS or FAIL.

Use it as a repeatable check in your monitoring or CI pipeline. Adjust the block number to the earliest height you expect your archive to serve.

const endpoint = process.env.ENDPOINT || 'http://127.0.0.1:8545';
const blockNumber = Number(process.env.BLOCK || 1000000);
const blockHex = '0x' + blockNumber.toString(16);

async function rpc(method, params) {
  const res = await fetch(endpoint, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params })
  });
  return res.json();
}

(async () => {
  const block = await rpc('eth_getBlockByNumber', [blockHex, false]);
  console.log('Block response:', JSON.stringify(block));
  if (!block.result) {
    console.error(`FAIL: block ${blockNumber} not available`);
    process.exit(1);
  }

  const state = await rpc('eth_getBalance', ['0x0000000000000000000000000000000000000000', blockHex]);
  console.log('State response:', JSON.stringify(state));
  if (!state.result) {
    console.error(`FAIL: historical state at block ${blockNumber} not available`);
    process.exit(1);
  }

  console.log(`PASS: archive range served for block ${blockNumber}`);
})();

Reproducible Results Table for Your Endpoint

Use the table below to record measurements against your own endpoint. Fill it in by running the probes above and noting the outcomes. This keeps your evaluation reproducible and comparable across providers or node configurations.

The columns capture the target block or height, the endpoint, the method used, whether a result was present, the earliest available block, storage used, and the retention window. Because provider-specific behavior varies, your filled table is the authoritative record for your environment.

• Target block/height: the historical point you queried.
• Endpoint: the JSON-RPC URL you tested.
• Method: the JSON-RPC method used, such as eth_getBlockByNumber or eth_getBalance.
• Result present?: yes or no, based on a non-null result.
• Earliest available block: the oldest block the endpoint serves.
• Storage used: disk consumed by your node or dataset.
• Retention window: the time or block range retained.

Limitations and Tradeoffs of Archive Infrastructure

The exact archive range and query surface depend on the provider or your node configuration, so a probe that passes for one block does not guarantee all history is available. Archive nodes are storage-heavy and slower to sync than full nodes, which affects deployment time and cost.

Flat-file exports are only as fresh as the last export and cannot serve the chain tip, so they are unsuitable for live queries. Hyperliquid-specific data such as funding and order book history may live in the market-data API rather than the node itself, which means an archive node alone may not cover every analytical need.

Plan for these constraints by combining surfaces: use an archive node or provider for point-in-time state reads, flat-file exports for bulk offline processing, and the market-data API for market-specific history. The Hyperliquid historical market data API article details that last surface.

• Archive range and query surface: documented / varies by provider.
• Archive nodes: storage-heavy and slower to sync.
• Flat-file exports: freshness limited by export cadence, no chain tip.
• Market-specific history: may require the market-data API, not the node.

Troubleshooting Archive Query Failures

When a historical query fails, first confirm the block number is within the archive range. A result of null or an error such as a missing trie node usually means the node is pruned or the block predates the retained range. Re-run the probe against a known archive endpoint to isolate whether the issue is the endpoint or the query.

If the endpoint is correct but queries are slow, check resource pressure. Storage, RAM, CPU, and bandwidth interact, and concurrent historical queries can saturate a node that handles recent state comfortably. Reduce concurrency or scale resources, then re-measure.

For provider-hosted endpoints, review the documented archive range and any rate limits. Because provider-specific behavior varies, verify with the probe rather than assuming coverage. The Hyperliquid RPC latency article covers latency considerations that affect query performance.

• Null or missing trie node: block outside retained range or node is pruned.
• Slow queries: resource pressure or concurrency saturation.
• Provider endpoints: check documented archive range and rate limits.
• Isolation: test the same query against a known archive endpoint.

Next Steps for Operating Archive Infrastructure

Start by defining your retention window and the historical queries you need, then choose between a self-hosted archive node, flat-file exports, or a provider-hosted historical JSON-RPC endpoint. Use the probes in this article to verify availability and fill the results table for your environment.

If you prefer not to operate storage-heavy infrastructure, review RPC pricing and the API service for managed options, and explore the Hyperliquid network page for network-specific details. The OnFinality Learn hub collects related guides, including Archive node vs full node and Accessing historical blockchain data.

Finally, keep your verification reproducible. Re-run the probes after configuration changes, provider migrations, or retention adjustments, and update the results table so your archive coverage remains documented and testable.

• Define retention window and required historical queries.
• Choose self-hosted, export-based, or provider-hosted history.
• Verify with probes and record results in the table.
• Re-verify after configuration or provider changes.