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

# Crypto Candles API: OHLCV for Hyperliquid and Lighter

> OHLCV candles API for Hyperliquid, Lighter, Spot, HIP-3, and HIP-4 markets with interval and coverage guidance.

Candles are OHLCV bars at a chosen interval, served for Hyperliquid core, Spot, HIP-3, HIP-4, Lighter, and Lighter on Robinhood Chain. 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>

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

    `/v1/rh-lighter/candles/{symbol}`, covering the deployment from its first trade at 2026-06-26 20:10 UTC. Find symbols on `/v1/rh-lighter/instruments`.
  </Tab>
</Tabs>

## Request parameters

| Parameter | Description |
| - | - |
| `symbol` | Path, required, string. Trading pair symbol, e.g. `BTC` |
| `interval` | Query, optional, string. Candle interval. Default `1h`. One of `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `1d`, `1w` |
| `start` | Query, optional, integer (ms) or string. Start time, Unix ms or RFC 3339. Defaults to 24h ago |
| `end` | Query, optional, integer (ms) or string. End time, Unix ms or RFC 3339. Defaults to now |
| `limit` | Query, optional, integer. Max results. Default 100, max 10000 |
| `cursor` | Query, optional, string. Pagination cursor from `meta.next_cursor` |

## Example response

```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": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb" }
}
```

## Response fields

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

| Field | 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 |

## How candles are built

A Hyperliquid, HIP-3, HIP-4, or Spot candle covers every trade that filled against the order book during its interval. `open` and `close` are the first and last of those trades, `high` and `low` the highest and lowest prices, `volume` and `quote_volume` their sums, and `trade_count` their number. A trade counts once, however many fills it produced.

Liquidations are included. When an account is liquidated, Hyperliquid first closes the position with market orders sent to the order book, where they fill resting orders like any other trade. A resting order filled by a liquidation was filled at that price, so the candle shows it.

Fills that did not trade against the order book are not counted. Each changes hands at a price that no resting order could take:

| Kind | `direction` on the trade, and what happens |
| - | - |
| Backstop liquidation | `Liquidated Cross Long`, `Liquidated Isolated Short`, and the other two combinations. The liquidator vault takes the position over when market orders could not close it |
| Auto-deleveraging | `Auto-Deleveraging`. Positions are closed against profitable traders |
| Vault netting | `Net Child Vaults`. Positions are netted between Hyperliquidity Provider vaults |
| Settlement | `Settlement`. A delisted market or a resolved HIP-4 outcome settles open positions |
| Spot dust conversion | `Spot Dust Conversion`. Small Spot balances are converted once a day |
| Spot backstop borrow liquidation | `Backstop Borrow Liquidation`. A Spot borrow position is taken over by the backstop |
| Spot partial borrow liquidation | `Partial Borrow Liquidation`. Part of a Spot borrow position is taken over by the backstop |

[Trades](/rest-api/trades) returns these fills with the `direction` shown, so candles aggregated from trades match these bars once those rows are left out.

### Compared with Hyperliquid's candles

Hyperliquid publishes its own candles through its info API, which serves the most recent 5,000 bars of each interval. Hyperliquid does not document how they are built; the comparison below is what its published bars show.

* `volume` and `trade_count` match: both count every trade that filled against the order book, liquidations included, and leave the fills in the table above out.
* `open`, `high`, `low`, and `close` differ only in bars that contain liquidations. Hyperliquid leaves liquidation prices out of those four fields, and when a bar's first trade is a liquidation it opens the bar at the previous bar's close. In those bars this API's high and low show the prices at which the liquidation filled resting orders, which can lie beyond Hyperliquid's.
* Hyperliquid returns a bar for an interval with no trades; this API does not (see below).

Measured over every hourly bar of every Hyperliquid perpetual market from 2026-03-09 to 2026-10-03 (about 900,000 bars), `volume` and `trade_count` matched on every bar. 0.7% of bars differed in `open`, `high`, `low`, or `close`, all but 12 of them for this reason. HIP-3 markets over the same period (about 556,000 bars) matched on `volume` and `trade_count` on every bar, and 1.4% differed in `open`, `high`, `low`, or `close`, all but 11 of them for this reason. Spot pairs have no liquidations, and over the same period (about 241,000 bars) every Spot bar matched Hyperliquid's on `open`, `high`, `low`, `close`, `volume`, and `trade_count`.

Lighter and Lighter on Robinhood Chain candles count every trade, including liquidation and deleverage trades.

### Intervals without trades

An interval without a trade has no bar, so a `1h` series skips any hour in which nothing traded. Hyperliquid's own candles return a bar with zero volume and zero trades, priced at the previous close. To build the same continuous series, carry the previous `close` forward into each missing interval.

### Bar times and coverage

`timestamp` is the start of the interval in UTC. A bar holds the trades at or after its start and before the start of the next bar.

| Family | First bar |
| - | - |
| Hyperliquid perps | 2025-03-22 12:00 UTC |
| Hyperliquid Spot | 2025-03-22 10:50 UTC |
| HIP-3 | 2025-12-22 00:00 UTC |
| HIP-4 | 2026-05-02 08:00 UTC |
| Lighter | 2025-08-01 00:00 UTC |
| Lighter on Robinhood Chain | 2026-06-26 20:10 UTC |

A market listed later starts at its first trade. Before 2025-03-22, Hyperliquid did not publish a record of every trade; the only source is per-account fill history capped at 10,000 fills per account, which leaves most trades out, so earlier Hyperliquid perp bars are not served. A Hyperliquid perp request whose window ends before 2025-03-22 12:00 UTC returns `400` with `range_before_coverage`. For the other families, a window that ends before the first bar returns `200` with empty `data` plus `meta.coverage_from` and `meta.notice`.

## Gaps and intervals

Pick the largest interval that still answers the question; finer candles return more rows and more requests. Inside coverage, a missing bar means nothing traded in that interval. Before a long historical pull, confirm the window on [Data quality](/data-quality). `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. For positioning alongside price, pair candles with [Open interest](/rest-api/open-interest).

## Access

Each venue's start date, WebSocket channels, and page limit come from [`GET /v1/capabilities`](/capabilities), followed by the SDK, CLI, and MCP names for the same data. The start date is the first served row on that venue; exact starts vary by market, so check `/v1/symbols` for a single symbol. Send `0xArchive-Version: 2026-10-01` for the current response contract; see [API conventions](/conventions).

| Venue | Availability |
| - | - |
| Hyperliquid | From 2025-03-22 12:00 UTC<br />WebSocket `candles`: replay only<br />Up to 10,000 rows a page<br />Older rows exist but are not served; available\_from is a policy floor. |
| Hyperliquid Spot | From 2025-03-22 10:50 UTC<br />REST only, no WebSocket channel<br />Up to 10,000 rows a page |
| HIP-3 | From 2025-12-22<br />WebSocket `hip3_candles`: replay only<br />Up to 10,000 rows a page |
| HIP-4 | From 2026-05-02 08:00 UTC<br />REST only, no WebSocket channel<br />Up to 10,000 rows a page<br />Prices are implied probabilities (0 to 1); quote volume is in USDH. |
| Lighter | From 2025-08-01<br />WebSocket `lighter_candles`: replay only<br />Up to 10,000 rows a page |
| Lighter on Robinhood Chain | From 2026-06-26 20:10 UTC<br />WebSocket `rh_lighter_candles`: replay only<br />Up to 10,000 rows a page |

| Surface | Names |
| - | - |
| Python SDK | `client.hyperliquid.candles.history(symbol, ..., interval="1h")` |
| TypeScript SDK | `client.hyperliquid.candles.history(symbol, { ..., interval: "1h" })` |
| Rust SDK | `client.hyperliquid.candles.history` |
| CLI | `oxa candles`; Spot `oxa spot candles`; HIP-4 `oxa hip4 candles` |
| MCP tools | `get_candles`, `get_spot_candles`, `get_hip3_candles`, `get_hip4_candles`, `get_lighter_candles`, `get_rh_lighter_candles` |

## Replay it over WebSocket

Candle channels are replay-only: `candles` (Hyperliquid core), `hip3_candles`, `lighter_candles`, and `rh_lighter_candles` support historical WebSocket replay but not live subscriptions. Current candles use REST; historical candle data is available through REST or WebSocket replay. For bulk file workflows, use the Trades export and aggregate to candles downstream. Spot and HIP-4 have no candle channel; HIP-4 candles are available through the REST route above as probability-history series.

```javascript theme={"theme":"github-dark"}
ws.send(JSON.stringify({
  op: "replay",
  channel: "lighter_candles",
  symbol: "BTC",
  start: 1785193200000,
  end: 1785196800000,
  speed: 10
}));
```

This example window is from July 2026, so it needs a paid plan; Free replays reach the most recent 30 days. 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, leaving out the fills listed in [How candles are built](#how-candles-are-built), or keep candle pulls on REST. Export schema details are on [Export schemas](/export-schemas).

## Next step

To keep a candle pull reproducible, continue to [Prepare data for a reproducible backtest](/guides/point-in-time-backtesting).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.