Hyperliquid Historical Data and Market Data APIs: Querying Trades, OHLCV, Funding, and Order Book History

Direct Answer: How to Get Hyperliquid Historical Data

To retrieve Hyperliquid historical market data for analysis and backtesting, you use two complementary surfaces: the native Hyperliquid API (HTTP POST to /info and WebSocket subscriptions) for live and recent state, and the separately published historical data archives (trade, funding, and OHLCV files) for deeper history. The native API provides recent trades, candles, funding, and order book snapshots, but it does not serve full historical order book depth or very old candles; for those, you need the archives or a third-party reseller. This guide walks through each surface, shows concrete request/response examples, and provides a decision checklist.

The primary source for this guide is the official Hyperliquid documentation at hyperliquid.gitbook.io. All endpoint hosts, request fields, and response shapes are documented there; where specific limits or retention windows are not documented, the docs state that they vary, so this guide avoids inventing numbers.

• Native API: POST /info for trades, candles, funding, and order book snapshots; WebSocket for real-time subscriptions.
• Historical archives: Public files for trades, funding, and OHLCV, updated periodically, covering longer history.
• Third-party resellers: Services like HypeRPC and QuickNode offer extended data APIs and SQL access, but are independent references, not official.

Understanding the Hyperliquid Data API Surfaces

Hyperliquid's API is split into two main categories: the native API that talks directly to validators, and the historical data archives that are generated and hosted separately. The native API is further divided into an HTTP endpoint (POST /info) for querying current state and recent history, and WebSocket endpoints (ws2 and others) for real-time subscriptions. The archives are files (often compressed) that contain historical trades, funding rates, and OHLCV data, and are updated on a schedule.

The native API is ideal for applications that need the latest state or data from the last few hours or days. For example, you can get the last 500 trades for a coin, the current funding rate, or the order book top-of-book. However, the native API does not provide full historical order book depth (all levels over time) or candles older than a certain period (the exact retention is not documented; it varies). For deep backtesting, you need the archives.

The archives are published by Hyperliquid and are available for download. They cover trades, funding, and OHLCV for all perpetuals and spot pairs. The exact coverage (start date, update frequency) is documented on the Hyperliquid docs page; checking there for the latest details is recommended. Third-party resellers like HypeRPC and QuickNode also offer historical data APIs, but they are independent and may have different coverage and pricing.

• Native API: POST /info (HTTP) and WebSocket (ws2) for live and recent data.
• Archives: Public files for trades, funding, OHLCV, updated periodically.
• Third-party: HypeRPC, QuickNode, etc., offer extended APIs but are not official.

Using the Native /info API for Recent Market Data

The /info endpoint is an HTTP POST endpoint that accepts a JSON request object. The request type is specified in the 'type' field. For historical market data, the most relevant request types are 'trades', 'candleSnapshot', and 'fundingHistory'. The response is a JSON array of objects.

For example, to get recent trades for BTC, you send a request with type 'trades' and the coin symbol. The response includes fields like 'time', 'px', 'sz', 'side', and 'tid'. For OHLCV, you use 'candleSnapshot' with parameters like 'req' (interval), 'coin', 'startTime', and 'endTime'. The response includes 't', 'o', 'h', 'l', 'c', 'v', and 'n' (number of trades).

The exact request and response shapes are documented in the Hyperliquid API docs. Below is a concrete example for trades and candles.

// Example: Get recent trades for BTC (using Node.js fetch)
const response = await fetch('https://api.hyperliquid.xyz/info', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ type: 'trades', coin: 'BTC' })
});
const trades = await response.json();
console.log(trades);
// Expected output: array of trade objects, e.g.,
// [{"time":1730000000000,"px":"65000.0","sz":"0.1","side":"B","tid":123456,"coin":"BTC"}]

// Example: Get 1h candles for BTC for a specific time range
const candlesResponse = await fetch('https://api.hyperliquid.xyz/info', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    type: 'candleSnapshot',
    req: { coin: 'BTC', interval: '1h', startTime: 1730000000000, endTime: 1730003600000 }
  })
});
const candles = await candlesResponse.json();
console.log(candles);
// Expected output: array of candle objects, e.g.,
// [{"t":1730000000000,"o":"65000.0","h":"65100.0","l":"64900.0","c":"65050.0","v":"100.0","n":123}]

WebSocket Subscriptions for Real-Time and Recent Data

For real-time market data, Hyperliquid provides WebSocket endpoints. The primary endpoint is wss://api.hyperliquid.xyz/ws, and you can subscribe to channels like 'trades', 'candle', 'l2Book', and 'userFills'. These subscriptions push updates as they happen, which is useful for live monitoring but not for historical backtesting.

However, WebSocket subscriptions can also be used to accumulate data over time. For example, you can subscribe to the 'candle' channel to build your own OHLCV history. The subscription message format is documented in the Hyperliquid WebSocket docs. Below is a simple Node.js example using the 'ws' package.

// Node.js WebSocket example (requires 'ws' package: npm install ws)
const WebSocket = require('ws');
const ws = new WebSocket('wss://api.hyperliquid.xyz/ws');

ws.on('open', () => {
  // Subscribe to trades for BTC
  ws.send(JSON.stringify({ method: 'subscribe', subscription: { type: 'trades', coin: 'BTC' } }));
});

ws.on('message', (data) => {
  const msg = JSON.parse(data);
  if (msg.channel === 'trades') {
    console.log('Trade:', msg.data);
    // Each trade has fields like time, px, sz, side, tid
  }
});

ws.on('error', (err) => console.error('WebSocket error:', err));

Accessing Historical Archives for Deep History

When you need data older than what the native API provides, or full order book depth, you must use the historical archives. Hyperliquid publishes these archives on a public URL (documented in the Hyperliquid docs). The archives are typically compressed files (e.g., .csv.gz) that you can download and process locally.

The archives include trade data, funding rates, and OHLCV data. The exact file naming and update schedule are documented on the Hyperliquid docs page. For example, trade archives might be organized by date and coin. To use them, you download the relevant files and parse them.

Third-party resellers like HypeRPC and QuickNode also offer historical data APIs that may provide easier access via SQL or REST. These are independent services and may have different coverage and pricing; always check their documentation.

• Check the official Hyperliquid docs for the archive URL and format.
• Download and parse files locally for backtesting.
• Consider third-party resellers for convenience, but verify their data quality.

Decision Checklist: Which Surface for Your Data Need

To choose the right API surface, consider the type and age of data you need. The table below maps common data needs to the recommended surface.

For recent trades (last few minutes), use the native API or WebSocket. For candles, the native API provides recent candles, but for older candles, use the archives. Funding history is available via the native API for recent periods, but for long-term funding analysis, use the archives. Order book top-of-book is available via the native API, but full depth history is not; use archives or resellers if available.

• Recent trades (last minutes): Native API (type 'trades') or WebSocket.
• Historical trades (days/weeks): Archives.
• Recent OHLCV candles: Native API (type 'candleSnapshot').
• Historical OHLCV: Archives.
• Funding history: Native API (type 'fundingHistory') for recent; archives for long-term.
• Order book top-of-book: Native API (type 'l2Book') or WebSocket.
• Full order book depth history: Not available from native API; check archives or third-party.

Common Failures and Troubleshooting

When working with Hyperliquid data APIs, you may encounter issues such as rate limiting, incorrect request formats, or missing data. Here are common failures and how to fix them.

Rate limiting: The Hyperliquid API has rate limits that vary by endpoint and subscription type. If you receive HTTP 429 or WebSocket disconnects, you are likely exceeding the limit. Refer to the Hyperliquid API rate limits guide for details and best practices.

Invalid request: Ensure your request JSON matches the documented schema. For example, the 'candleSnapshot' request requires a 'req' object with 'coin', 'interval', and optionally 'startTime' and 'endTime'. Missing fields or incorrect types will result in an error.

Data not found: If you request trades for a coin that doesn't exist or a time range with no data, the API may return an empty array. Check the coin symbol and time range.

WebSocket connection issues: If your WebSocket connection drops, implement reconnection logic with exponential backoff. Also, ensure you send the correct subscription message format.

• HTTP 429: Slow down requests and respect rate limits.
• Invalid JSON: Validate your request against the docs.
• Empty responses: Check coin symbol and time range.
• WebSocket disconnects: Implement reconnection logic.

Tradeoffs and Limitations

The native API is fast and easy to use, but it has limitations: it only provides a limited amount of historical data (the exact retention is not documented), and it does not provide full order book depth history. The archives provide deep history but require downloading and processing large files, which can be time-consuming and require significant storage.

Third-party resellers may offer more convenient access, but they are independent and may have different data quality, coverage, and pricing. Always verify data against official sources when possible.

For production applications, consider using a combination: use the native API for real-time data and the archives for historical backtesting. For high-frequency data needs, you may need to build your own data collection system using WebSocket subscriptions.

Next Steps and Further Reading

Now that you understand the Hyperliquid data API surfaces, you can start building your own data pipelines. For more context on Hyperliquid's infrastructure, see the Hyperliquid network overview. If you're interested in RPC endpoints, check the Hyperliquid RPC endpoints (RPC Assistant). For related guides, see Hyperliquid WebSocket subscriptions, Hyperliquid RPC latency, and Hyperliquid API rate limits.

For general API service information, visit the API service page and RPC pricing. Explore the OnFinality Learn hub for more tutorials and guides.

• Explore the official Hyperliquid docs for the latest API details.
• Check third-party resellers like HypeRPC and QuickNode for extended data services.
• Join the Hyperliquid community for support and discussions.