> ## Documentation Index > Fetch the complete documentation index at: https://goldrush.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # candleSnapshot | Hyperliquid Info API > Hyperliquid candleSnapshot: fetch historical OHLCV candles for a coin and interval over a time window for charting and backtesting. > [card] Credit Cost > > 1 per call > [card] Processing > > Realtime The Hyperliquid info endpoint with `type: "candleSnapshot"` is used to fetch historical OHLCV candles for a coin and interval over a time window for charting and backtesting. > [!TIP] > > Estimate your monthly cost for this API using the [Pricing Calculator](https://goldrush.dev/docs/pricing-calculator.md?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fcandle-snapshot). > [!NOTE] > > * Wire-equal to `POST api.hyperliquid.xyz/info` with `{"type": "candleSnapshot", "req": {...}}`. Note the nested `req` object. > * Each response contains at most 5,000 candles (per-response cap, not a retention limit); page by advancing `startTime` for longer ranges. > * GoldRush serves candles from a dedicated HyperCore historical store, so candles older than the upstream window can extend back to GoldRush’s full HyperCore coverage. Returns an array of OHLCV candles for a single coin and interval, bounded by a `[startTime, endTime]` window. Each candle carries the open/close timestamps, the coin, the interval, open/high/low/close prices, base volume, and trade count. Use it for chart backfills, indicator computation, and backtests. This is a global, non-user-keyed type. **NOT LIMITED TO THE MOST RECENT 5,000 CANDLES**. GoldRush serves it from a dedicated HyperCore historical store so candles older than the upstream window remain available; page through time by advancing `startTime`. ## Endpoint ``` POST https://hypercore.goldrushdata.com/info Authorization: Bearer Content-Type: application/json ``` ## Request The request parameters are nested inside a `req` object. **type** `string` *required* (default: candleSnapshot) Always `"candleSnapshot"`. **req** `object` *required* The candle query parameters. **properties** **coin** `string` *required* The asset symbol, e.g. `"BTC"`. HIP-3 markets use the deployer-prefixed form. **interval** `string` *required* Candle interval. One of `"1m"`, `"3m"`, `"5m"`, `"15m"`, `"30m"`, `"1h"`, `"2h"`, `"4h"`, `"8h"`, `"12h"`, `"1d"`, `"3d"`, `"1w"`, `"1M"`. **startTime** `int` *required* Unix timestamp in milliseconds. Inclusive lower bound for the window. **endTime** `int` Unix timestamp in milliseconds. Inclusive upper bound. Defaults to current server time when omitted. ### Example ```bash cURL theme={null} curl -X POST https://hypercore.goldrushdata.com/info \ -H "Authorization: Bearer $GOLDRUSH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "candleSnapshot", "req": { "coin": "BTC", "interval": "1h", "startTime": 1735689600000, "endTime": 1735776000000 } }' ``` ```typescript TypeScript theme={null} const response = await fetch("https://hypercore.goldrushdata.com/info", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "candleSnapshot", req: { coin: "BTC", interval: "1h", startTime: 1735689600000, endTime: 1735776000000, }, }), }); const candles = await response.json(); ``` ```python Python theme={null} import os, requests response = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "candleSnapshot", "req": { "coin": "BTC", "interval": "1h", "startTime": 1735689600000, "endTime": 1735776000000, }, }, ) candles = response.json() ``` ## Response An array of candle objects, oldest first. ```json theme={null} [ { "t": 1735689600000, "T": 1735693199999, "s": "BTC", "i": "1h", "o": "62739.0", "c": "62960.0", "h": "63118.0", "l": "62711.0", "v": "921.9829", "n": 16396 } ] ``` ### Field descriptions > [!NOTE] > > The price and volume fields (`o`, `c`, `h`, `l`, `v`) are returned as **decimal strings**, preserving upstream precision. Do not parse them as floats. **t** `int` Candle open time, Unix milliseconds. **T** `int` Candle close time, Unix milliseconds. **s** `string` Coin symbol. **i** `string` Candle interval - echoes the request `interval`. **o** `string` Open price. **c** `string` Close price. **h** `string` High price. **l** `string` Low price. **v** `string` Base-asset volume over the candle. **n** `int` Number of trades in the candle. ## Paginating a large backfill Each response returns at most **5,000 candles** - a per-response cap, not a limit on how far back history goes. To backfill a range wider than 5,000 candles, page forward through time: start at your window's `startTime`, then set the next request's `startTime` to the last candle's close time (`T`) plus one millisecond. Repeat until a response returns fewer than 5,000 candles. Because `T` is the inclusive close of a candle and the next candle opens at `T + 1`, advancing to `T + 1` lands exactly on the following candle - no overlap to de-duplicate and no gaps. ```typescript TypeScript theme={null} async function backfillCandles( coin: string, interval: string, startTime: number, endTime: number, ) { const all: any[] = []; let cursor = startTime; while (cursor < endTime) { const res = await fetch("https://hypercore.goldrushdata.com/info", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GOLDRUSH_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ type: "candleSnapshot", req: { coin, interval, startTime: cursor, endTime }, }), }); const page = await res.json(); if (page.length === 0) break; all.push(...page); // Advance to one millisecond past the last candle's close time. cursor = page[page.length - 1].T + 1; // A short page means we've reached the end of the range. if (page.length < 5000) break; } return all; } ``` ```python Python theme={null} import os, requests def backfill_candles(coin, interval, start_time, end_time): all_candles = [] cursor = start_time while cursor < end_time: res = requests.post( "https://hypercore.goldrushdata.com/info", headers={"Authorization": f"Bearer {os.environ['GOLDRUSH_API_KEY']}"}, json={ "type": "candleSnapshot", "req": { "coin": coin, "interval": interval, "startTime": cursor, "endTime": end_time, }, }, ) page = res.json() if not page: break all_candles.extend(page) # Advance to one millisecond past the last candle's close time. cursor = page[-1]["T"] + 1 # A short page means we've reached the end of the range. if len(page) < 5000: break return all_candles ``` > [!TIP] > > Pick the coarsest `interval` that satisfies your use case - larger intervals cover more calendar time per 5,000-candle page, so a multi-year `1d` backfill is a single request while the same range at `1m` pages many times. ## Related endpoints > [card] [l2BookDiffSnapshot](https://goldrush.dev/docs/api-reference/hyperliquid-info/l2-book-diff-snapshot.md) > > fetch a full-depth L2 order book snapshot for one coin, with height, epoch, and seq to bootstrap the l2BookDiff2 stream. > [card] [allMids](https://goldrush.dev/docs/api-reference/hyperliquid-info/all-mids.md) > > fetch the current mid price for every actively traded asset in a single call. > [card] [fundingHistory](https://goldrush.dev/docs/api-reference/hyperliquid-info/funding-history.md) > > fetch a coin’s historical funding rates and premiums over a time window for funding analytics and basis strategies. > [card] [l2Book](https://goldrush.dev/docs/api-reference/hyperliquid-info/l2-book.md) > > fetch an aggregated Level-2 order book snapshot for a single coin - bids and asks as price, size, and order-count levels. See all Hyperliquid endpoints: [Overview hub](https://goldrush.dev/docs/goldrush-hyperliquid/overview.md) · [Info API reference](https://goldrush.dev/docs/goldrush-hyperliquid/info-api/overview.md) *Last reviewed: 2026-07-23* This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.