---
title: "Market Candles"
method: GET
path: "/gateway/v1/hyperliquid/candles"
tags: ["Hyperliquid"]
---

# Market Candles

`GET /gateway/v1/hyperliquid/candles`

Returns market OHLCV candles for charting and trade-review overlays, ordered by open_time ascending. Each row also carries trades, closed, and nullable quote volume (null before quote-volume coverage). symbol, from, and to are required; from/to accept Unix seconds, ISO datetimes, or UTC dates, and candle open_time is bounded to the half-open [from,to) window. The requested window may contain at most 5000 candles, so use a larger interval for long histories. The response is market data and does not require a wallet address.

## Query parameters

- `symbol` string, required — Hyperliquid market id (for example BTC, kPEPE, xyz:GOLD, the canonical PURR/USDC spot pair, or an @index spot market).
- `interval` '1m' | '3m' | '5m' | '15m' | '30m' | '1h' | '2h' | '4h' | '8h' | '12h' | '1d' | '3d' | '1w' | '1M' — Candle granularity.
- `from` string, required — Window start (Unix seconds, an ISO datetime, or a bare UTC date).
- `to` string, required — Window end (Unix seconds, an ISO datetime, or a bare UTC date; a bare date means the end of that day).

## Response `200`

OK

- DataResponseHyperliquidCandle
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `data` HyperliquidCandle[], nullable, required
    - `close` number, double, required — Close price, USD
    - `close_time` integer, required — Candle close (Unix seconds)
    - `closed` boolean, required — true when the candle interval has closed (final)
    - `high` number, double, required — High price, USD
    - `interval` string, required — Candle interval (1m, 1h, 1d, …)
    - `low` number, double, required — Low price, USD
    - `open` number, double, required — Open price, USD
    - `open_time` integer, required — Candle open (Unix seconds)
    - `quote` number, double, nullable, required — Quote-asset volume, USD. null for candles before quote-volume coverage began.
    - `symbol` string, required — Market id
    - `trades` integer, required — Number of trades in the candle
    - `volume` number, double, required — Base-asset volume (token units)
  - `meta` OffsetMeta, required
    - `cached` boolean, required — Whether this response was served from cache
    - `credits_used` integer, required — Credits deducted for this request
    - `empty_reason` string — Hint explaining why the data array is empty, when applicable
    - `has_more` boolean — Whether more items may exist beyond this response. For offset-paged endpoints, continue with a larger offset. For time-series endpoints without offset/cursor controls, true means the requested time range hit an upstream cap; narrow from/to to continue. Omitted when exhaustion cannot be proven.
    - `limit` integer, required — Maximum number of items returned in this response
    - `offset` integer, required — Number of items skipped (pagination offset)
    - `total` integer — Total number of matching items (before pagination). Omitted when total is unknown.
    - `watermark` integer — Warehouse watermark (Unix seconds) this response was computed at, on warehouse-backed endpoints (e.g. Hyperliquid /trades/aggregate) — rows up to this time come from the warehouse, newer rows from the live tail. Omitted elsewhere.

## Other responses

- `default` — Error

---

[API](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api.md) · [All operations](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/asksurf/asksurf-public-rest-api/revisions/4153a9cb5145/schema)