Get Candles

GET/v1/cryptodata/hyperliquid/candles

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.

# 1. No key, no payment: the gateway answers 402 with the price
curl -i "https://api.realtimeapi.ai/v1/cryptodata/hyperliquid/candles"

# 2. Pay: retry with a signed x402 payment (any x402 client builds this header)
curl "https://api.realtimeapi.ai/v1/cryptodata/hyperliquid/candles" -H "PAYMENT-SIGNATURE: $X402_PAYMENT"

// npm i @x402/fetch @x402/core @x402/evm viem
import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const client = x402Client.fromConfig({ schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(privateKeyToAccount(PRIVATE_KEY)) }] });
const pay = wrapFetchWithPayment(fetch, client);
const data = await (await pay("https://api.realtimeapi.ai/v1/cryptodata/hyperliquid/candles")).json();
console.log(data);

# pip install x402 eth-account requests
from eth_account import Account
from x402.clients.requests import x402_requests

session = x402_requests(Account.from_key(PRIVATE_KEY))
print(session.get("https://api.realtimeapi.ai/v1/cryptodata/hyperliquid/candles").json())

curl "https://api.realtimeapi.ai/v1/cryptodata/hyperliquid/candles" -H "X-API-Key: $RTAPI_KEY"