> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xarchive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Candles

> OHLCV candle payloads by venue family and interval, returned as numbers, with field notes for backtests and dashboards.

Candles are OHLCV bars at a chosen interval. Every venue family serves them. Unlike funding and open interest, candle values come back as numbers, not decimal strings.

## Get candles

<Tabs>
  <Tab title="Hyperliquid">
    ```bash theme={"theme":"github-dark"}
    curl "https://api.0xarchive.io/v1/hyperliquid/candles/BTC?interval=1h" \
      -H "X-API-Key: $OXARCHIVE_API_KEY"
    ```

    `/v1/hyperliquid/candles/{symbol}`. Plain perp symbols such as `BTC`.
  </Tab>

  <Tab title="Spot">
    ```bash theme={"theme":"github-dark"}
    curl "https://api.0xarchive.io/v1/hyperliquid/spot/candles/HYPE-USDC?interval=1h" \
      -H "X-API-Key: $OXARCHIVE_API_KEY"
    ```

    `/v1/hyperliquid/spot/candles/{symbol}`. Pair symbols such as `HYPE-USDC`.
  </Tab>

  <Tab title="HIP-3">
    ```bash theme={"theme":"github-dark"}
    curl "https://api.0xarchive.io/v1/hyperliquid/hip3/candles/km:US500?interval=1h" \
      -H "X-API-Key: $OXARCHIVE_API_KEY"
    ```

    `/v1/hyperliquid/hip3/candles/{symbol}`. Namespaced builder symbols, case-sensitive.
  </Tab>

  <Tab title="HIP-4">
    ```bash theme={"theme":"github-dark"}
    curl "https://api.0xarchive.io/v1/hyperliquid/hip4/candles/%230?interval=1h" \
      -H "X-API-Key: $OXARCHIVE_API_KEY"
    ```

    `/v1/hyperliquid/hip4/candles/{symbol}`. Outcome side ids such as `%230`; HIP-4 candles are a probability-history series.
  </Tab>

  <Tab title="Lighter">
    ```bash theme={"theme":"github-dark"}
    curl "https://api.0xarchive.io/v1/lighter/candles/{symbol}?interval=1h" \
      -H "X-API-Key: $OXARCHIVE_API_KEY"
    ```

    `/v1/lighter/candles/{symbol}`. Find symbols on `/v1/lighter/instruments`.
  </Tab>
</Tabs>

## Request parameters

| Parameter  | In    | Type         | Required | Description                                                                            |
| ---------- | ----- | ------------ | -------- | -------------------------------------------------------------------------------------- |
| `symbol`   | path  | string       | Yes      | Trading pair symbol, e.g. `BTC`                                                        |
| `interval` | query | string       | No       | Candle interval. Default `1h`. One of `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `1d`, `1w` |
| `start`    | query | integer (ms) | No       | Start time, Unix ms. Defaults to 24h ago                                               |
| `end`      | query | integer (ms) | No       | End time, Unix ms. Defaults to now                                                     |
| `limit`    | query | integer      | No       | Max results. Default 100, max 10000                                                    |
| `cursor`   | query | string       | No       | Pagination cursor from `meta.next_cursor`                                              |

```json theme={"theme":"github-dark"}
{
  "success": true,
  "data": [
    { "timestamp": "2026-06-04T18:00:00Z", "open": 63513, "high": 64117, "low": 63108, "close": 63788, "volume": 3507.95321, "quote_volume": 223506651.65, "trade_count": 44543 }
  ],
  "meta": { "count": 1, "next_cursor": "1780596000000", "request_id": "req_8b0d2f63c1a94e57" }
}
```

## Response fields

Candle values are **numbers**, not decimal strings.

| Field          | Type    | Description                      |
| -------------- | ------- | -------------------------------- |
| `timestamp`    | string  | Candle start time (ISO 8601 UTC) |
| `open`         | number  | Opening price                    |
| `high`         | number  | Highest price in the interval    |
| `low`          | number  | Lowest price in the interval     |
| `close`        | number  | Closing price                    |
| `volume`       | number  | Volume in the base asset         |
| `quote_volume` | number  | Volume in the quote asset (USD)  |
| `trade_count`  | integer | Number of trades in the interval |

## Gaps and intervals

Pick the largest interval that still answers the question; finer candles return more rows and more requests. A missing bar is not a zero bar, so confirm coverage on [Data quality](/data-quality) before a long historical pull, and treat a gap as a window to narrow or rebuild rather than fill. `volume` is in the base asset and `quote_volume` is in USD, so use `quote_volume` when comparing activity across symbols that trade at very different prices.

## Stream it live

Only Lighter streams candles, on `lighter_candles`. Hyperliquid core, Spot, HIP-3, and HIP-4 have no candle channel: stream [Trades](/rest-api/trades) and aggregate to your interval, or poll the REST route above.

```javascript theme={"theme":"github-dark"}
ws.send(JSON.stringify({ op: "subscribe", channel: "lighter_candles", symbol: "BTC" }));
```

Connection and reconnect handling live in the [WebSocket](/websocket) tab; see [WebSocket channels](/websocket/channels) for the family matrix.

## Export in bulk

Candles have no standalone export schema. For file-based history, export [Trades](/rest-api/trades) with the `trades` schema and aggregate to candles downstream, or keep candle pulls on REST. Export schema details are on [Export schemas](/export-schemas).

## Next

Use [Trades](/rest-api/trades) for the raw tape, [Open interest](/rest-api/open-interest) for positioning, or [Point-in-time backtesting](/guides/point-in-time-backtesting) to keep a candle pull reproducible.