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

# Get Candles Batch

`GET /api/v1/hyperliquid/candles/batch`

## Request

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

Trailing OHLCV candles for up to 25 coins in ONE call — the same bars
``/hyperliquid/candles`` serves per coin, keyed by coin under ``series``.

Trailing ``limit`` only; for an explicit ``start``/``end`` range use the
single-coin route. Every coin must be in HL's universe (400 ``unknown_coin``
otherwise — nothing is silently dropped). On a cold cache a series that has
not arrived within ~8s is listed in ``pending`` instead of holding the
whole response, and ``retry_after_s`` says how long to wait (scaled to how many
are still fetching): their fetches keep running and are cached, so retry just
the ``pending`` coins after that. A cold coin costs Hyperliquid rate limit
(~20 weight, whatever ``limit`` is), so a first pull of many coins takes a
while and repeat pulls are instant; for a whole-universe scan that needs no
candles at all, use ``/indicators/heatmap``. ``atr`` and
``forming_bar_timestamp`` behave as on ``/hyperliquid/candles``.

The contract: ``complete`` is true iff every requested coin is in ``series``; a
coin is never in both ``series`` and ``pending``. ``wait`` (0-25s, default 8)
holds longer for a caller that prefers one call over a poll. ``closed_only=true``
returns the last ``limit`` COMPLETED bars — the read for a strategy that acts on a
closed bar — and is served from any series fetched since the latest close, so the
liquid coins pre-warmed just after each 4h close stay instant for the whole bar.
Fees for sizing are on ``/hyperliquid/meta`` (``fees``); funding + OI on the same
bar grid are ``/backtesting/hl-funding-bars`` (join on ``timestamp``).

## Query parameters

- `coins` string, nullable: Comma list of HL coin names, e.g. ETH,SOL,BNB (up to 25)
- `symbols` string, nullable: Alias for `coins`. Send one or the other.
- `interval` string
- `limit` integer
- `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.
- `closed_only` boolean: true = COMPLETED bars only: the last `limit` closed bars, no forming bar. Served from any series fetched since the latest bar close, so it stays warm for the whole bar (the default trailing window is re-fetched every few minutes).
- `wait` number, nullable: Seconds to hold for cold series before answering with `pending` (0-25, default 8).

## Response `200`

Successful Response

- HLCandleBatchResponse: Trailing candles for several coins, keyed by HL coin name.
  - `interval` string, required
  - `limit` integer, required
  - `series` object, required
  - `count` integer, required
  - `pending` string[]
  - `complete` boolean
  - `retry_after_s` integer, nullable
  - `closed_only` boolean
  - `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)