> ## 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.

<CardGroup cols={2}>
  <Card title="Credit Cost"> 1 per call</Card>
  <Card title="Processing"> Realtime</Card>
</CardGroup>

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](/docs/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-info%2Fcandle-snapshot).
</Tip>

<Info>
  * 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.
</Info>

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 <GOLDRUSH_API_KEY>
Content-Type: application/json
```

## Request

The request parameters are nested inside a `req` object.

<ParamField body="type" type="string" required default="candleSnapshot">
  Always `"candleSnapshot"`.
</ParamField>

<ParamField body="req" type="object" required>
  The candle query parameters.

  <Expandable title="properties">
    <ParamField body="coin" type="string" required>
      The asset symbol, e.g. `"BTC"`. HIP-3 markets use the deployer-prefixed form.
    </ParamField>

    <ParamField body="interval" type="string" required>
      Candle interval. One of `"1m"`, `"3m"`, `"5m"`, `"15m"`, `"30m"`, `"1h"`, `"2h"`, `"4h"`, `"8h"`, `"12h"`, `"1d"`, `"3d"`, `"1w"`, `"1M"`.
    </ParamField>

    <ParamField body="startTime" type="int" required>
      Unix timestamp in milliseconds. Inclusive lower bound for the window.
    </ParamField>

    <ParamField body="endTime" type="int">
      Unix timestamp in milliseconds. Inclusive upper bound. Defaults to current server time when omitted.
    </ParamField>
  </Expandable>
</ParamField>

### Example

<CodeGroup>
  ```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()
  ```
</CodeGroup>

## 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.
</Note>

<ResponseField name="t" type="int">Candle open time, Unix milliseconds.</ResponseField>
<ResponseField name="T" type="int">Candle close time, Unix milliseconds.</ResponseField>
<ResponseField name="s" type="string">Coin symbol.</ResponseField>
<ResponseField name="i" type="string">Candle interval - echoes the request `interval`.</ResponseField>
<ResponseField name="o" type="string">Open price.</ResponseField>
<ResponseField name="c" type="string">Close price.</ResponseField>
<ResponseField name="h" type="string">High price.</ResponseField>
<ResponseField name="l" type="string">Low price.</ResponseField>
<ResponseField name="v" type="string">Base-asset volume over the candle.</ResponseField>
<ResponseField name="n" type="int">Number of trades in the candle.</ResponseField>

## 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.

<CodeGroup>
  ```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
  ```
</CodeGroup>

<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.
</Tip>

## Related endpoints

<CardGroup cols={2}>
  <Card title="l2BookDiffSnapshot" href="/docs/api-reference/hyperliquid-info/l2-book-diff-snapshot">fetch a full-depth L2 order book snapshot for one coin, with height, epoch, and seq to bootstrap the l2BookDiff2 stream.</Card>
  <Card title="allMids" href="/docs/api-reference/hyperliquid-info/all-mids">fetch the current mid price for every actively traded asset in a single call.</Card>
  <Card title="fundingHistory" href="/docs/api-reference/hyperliquid-info/funding-history">fetch a coin’s historical funding rates and premiums over a time window for funding analytics and basis strategies.</Card>
  <Card title="l2Book" href="/docs/api-reference/hyperliquid-info/l2-book">fetch an aggregated Level-2 order book snapshot for a single coin - bids and asks as price, size, and order-count levels.</Card>
</CardGroup>

See all Hyperliquid endpoints: [Overview hub](/docs/goldrush-hyperliquid/overview) · [Info API reference](/docs/goldrush-hyperliquid/info-api/overview)

*Last reviewed: 2026-06-16*