fetch_candle_snapshot

Documentation for eth_defi.hyperliquid.api.fetch_candle_snapshot function.

fetch_candle_snapshot(session, *, coin, interval, start_time, end_time, timeout=30.0)

Fetch up to 5,000 OHLCV candles for a single coin.

Calls the candleSnapshot Info endpoint. The response is capped at HYPERLIQUID_CANDLE_SNAPSHOT_LIMIT candles regardless of window width, so callers needing longer histories must paginate.

Pre-launch candles (before ~April 2023) are returned but have zero volume — these are backfilled price data, not authentic Hyperliquid trades. Filter by volume > 0 for real bars only.

Uses HyperliquidSession.post_info() for automatic proxy rotation on rate-limit or connectivity failures.

Info endpoint docs.

Example:

from datetime import datetime
from eth_defi.hyperliquid.api import fetch_candle_snapshot
from eth_defi.hyperliquid.session import create_hyperliquid_session

session = create_hyperliquid_session()
candles = fetch_candle_snapshot(
    session,
    coin="BTC",
    interval="4h",
    start_time=datetime(2023, 5, 1),
    end_time=datetime(2023, 6, 1),
)
print(f"{len(candles)} candles, first close={candles[0].close}")

Parameters

session (eth_defi.hyperliquid.session.HyperliquidSession) – Session from create_hyperliquid_session().
coin (str) – Base symbol only (e.g. "BTC"), not a CCXT-style pair.
interval (str) – One of "1m", "3m", "5m", "15m", "30m", "1h", "2h", "4h", "8h", "12h", "1d", "3d", "1w", "1M".
start_time (datetime.datetime) – Earliest candle, naive UTC datetime.
end_time (datetime.datetime) – Latest candle, naive UTC datetime.
timeout (float) – HTTP request timeout in seconds.

Returns

Candles in ascending time order. Empty list if no data.

Return type

list[eth_defi.hyperliquid.api.HyperliquidCandle]