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

# Get Candles

`GET /api/v1/hyperliquid/candles`

## Request

- Base URL: `https://cryptodataapi.com`
- URL: `https://cryptodataapi.com/api/v1/hyperliquid/candles`
- Auth: API key in header `X-API-Key`

OHLCV candles for a coin — trailing ``limit`` bars, or an explicit range.

**These are Hyperliquid's own bars** (``candleSnapshot``) — the execution
truth for an HL book: signal, size and mark a Hyperliquid position from this
series. ``/api/v1/backtesting/klines`` is our archive of the same venue's 1m
bars for deep history, not a second price source. For several coins at once
use ``/hyperliquid/candles/batch``.

``coin`` is HL's own name, matched case-insensitively (``symbol`` is accepted
as an alias, and a ``USDT`` / ``-PERP`` suffix is tolerated). A name HL does
not list is a 400 ``unknown_coin`` and an unrecognised query parameter a 400
``unknown_parameter`` — never a silent default-coin reply.

``atr=14`` adds a Wilder ATR to every bar (``atr``; null for the first
``atr`` bars) computed on this exact series, so every agent uses the same
number. The LAST bar is usually still forming: ``forming_bar_timestamp``
names it (null when the last bar has closed) — drop it, and its ``atr``,
for completed-bar signals.

Pass ``start`` (and optionally ``end``) as epoch milliseconds or ISO-8601
to fetch a fixed window instead of the trailing ``limit``; ranges longer
than one candleSnapshot page are paginated, up to **15,000 bars** per call
(400 above that — narrow the window or step the interval up). Explicit
ranges bypass the 60s response cache and spend live HL weight (20 per
1,500-bar page), so poll them sparingly.

**Retention is Hyperliquid's, not ours:** HL keeps only its most recent
~5,000 bars of each interval (about 3.5 days of 1m, 17 days of 5m, 7 months
of 1h); the part of a range older than that returns no bars. For multi-month
1m history use ``/api/v1/backtesting/klines?exchange=hyperliquid&start=&end=``
(our own archive, local from 2026-05-09).

``start`` / ``end`` in the response echo the resolved window (ms) for a
range request and are null for a trailing pull.

## Query parameters

- `coin` string, nullable: HL coin name, e.g. BTC, SOL, kPEPE (default BTC)
- `symbol` string, nullable: Alias for `coin` (the rest of the API says `symbol`). Send one or the other.
- `interval` string
- `limit` integer
- `start` string, nullable: Range start — epoch ms or ISO-8601. With `start`/`end` the trailing `limit` is ignored; the range is capped at 15,000 bars.
- `end` string, nullable: Range end — epoch ms or ISO-8601 (default: now)
- `atr` integer, nullable: Add a Wilder ATR of this period to every bar as `atr` (e.g. 14). Null for the first `atr` bars of the window; pull at least ~10x the period for a converged value.

## Response `200`

Successful Response

- HLCandleResponse: Hyperliquid OHLCV candles.
  - `coin` string, required
  - `interval` string, required
  - `candles` object[], required
  - `count` integer, required
  - `start` integer, nullable
  - `end` integer, nullable
  - `atr_period` integer, nullable
  - `forming_bar_timestamp` integer, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/cryptodataapi/apis/crypto-data-api.md) · [All operations](https://skmtc.dev/cryptodataapi/apis/crypto-data-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cryptodataapi/apis/crypto-data-api/revisions/8628b754ca81?raw)