> ## 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](/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.
  * For live, push-based candles, including HIP-3 and HIP-4 markets, use the <a href="https://goldrush.dev/docs/api-reference/streaming-api/subscriptions/ohlcv-pairs-stream" target="_blank" rel="noopener noreferrer">Streaming API OHLCV streams</a> instead of polling.
</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>

*Last reviewed: 2026-06-16*