POST
/
info
Candle snapshot
curl --request POST \
  --url https://api.hyperliquid.xyz/info \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "candleSnapshot",
  "req": {
    "coin": "BTC",
    "interval": "1h",
    "startTime": 1754300000000,
    "endTime": 1754400000000
  }
}'
[
  {
    "T": 1681924499999,
    "c": "29258.0",
    "h": "29309.0",
    "i": "15m",
    "l": "29250.0",
    "n": 189,
    "o": "29295.0",
    "s": "BTC",
    "t": 1681923600000,
    "v": "0.98639"
  }
]
You can only use this endpoint on the official Hyperliquid public API. It is not available through Chainstack, as the open-source node implementation does not support it yet.
Retrieves historical candlestick (OHLCV) data for a specific asset within a time range. Only the most recent 5000 candles are available.
Get your own node endpoint todayStart for free and get your app to production levels immediately. No credit card required.You can sign up with your GitHub, X, Google, or Microsoft account.

Parameters

  • type (string, required) — Must be "candleSnapshot"
  • req (object, required) — Request parameters:
    • coin (string, required) — Asset identifier (“BTC”, “ETH” for perpetuals; “@107” for spot)
    • interval (string, required) — Candle interval (see supported intervals below)
    • startTime (integer, required) — Start time in milliseconds (epoch timestamp)
    • endTime (integer, required) — End time in milliseconds (epoch timestamp)

Returns

Returns an array of candlestick objects with OHLCV data:
  • t — Open time timestamp (milliseconds)
  • T — Close time timestamp (milliseconds)
  • o — Open price (string)
  • h — High price (string)
  • l — Low price (string)
  • c — Close price (string)
  • v — Volume traded (string)
  • n — Number of trades (integer)
  • i — Interval (string)
  • s — Symbol (string)
Only the most recent 5000 candles are available. Older data beyond this limit is not accessible.

Supported intervals

"1m", "3m", "5m", "15m", "30m", "1h", "2h", "4h", "8h", "12h", "1d", "3d", "1w", "1M"

JavaScript example

const getCandleData = async (coin, interval, startTime, endTime) => {
  const response = await fetch('https://hyperliquid-mainnet.core.chainstack.com/YOUR_API_KEY/info', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      type: 'candleSnapshot',
      req: {
        coin: coin,
        interval: interval,
        startTime: startTime,
        endTime: endTime
      }
    })
  });
  
  const data = await response.json();
  return data;
};

// Usage - Get last 24 hours of 1h candles
const endTime = Date.now();
const startTime = endTime - (24 * 60 * 60 * 1000); // 24 hours ago

const candles = await getCandleData('BTC', '1h', startTime, endTime);
console.log('Candle data:', candles);

// Process candle data
candles.forEach(candle => {
  console.log(`${new Date(candle.t).toISOString()}: O:${candle.o} H:${candle.h} L:${candle.l} C:${candle.c} V:${candle.v}`);
});

Price analysis

const analyzePriceData = (candles) => {
  if (candles.length === 0) return null;
  
  const prices = candles.map(c => parseFloat(c.c));
  const volumes = candles.map(c => parseFloat(c.v));
  
  return {
    firstPrice: parseFloat(candles[0].o),
    lastPrice: parseFloat(candles[candles.length - 1].c),
    highestPrice: Math.max(...candles.map(c => parseFloat(c.h))),
    lowestPrice: Math.min(...candles.map(c => parseFloat(c.l))),
    totalVolume: volumes.reduce((sum, vol) => sum + vol, 0),
    averageVolume: volumes.reduce((sum, vol) => sum + vol, 0) / volumes.length,
    priceChange: parseFloat(candles[candles.length - 1].c) - parseFloat(candles[0].o),
    candleCount: candles.length
  };
};

// Usage
const analysis = analyzePriceData(candles);
console.log('Price analysis:', analysis);

Time range calculation

const calculateTimeRange = (interval, candleCount = 100) => {
  const intervals = {
    '1m': 60 * 1000,
    '5m': 5 * 60 * 1000,
    '15m': 15 * 60 * 1000,
    '1h': 60 * 60 * 1000,
    '4h': 4 * 60 * 60 * 1000,
    '1d': 24 * 60 * 60 * 1000
  };
  
  const intervalMs = intervals[interval];
  if (!intervalMs) throw new Error('Unsupported interval');
  
  const endTime = Date.now();
  const startTime = endTime - (candleCount * intervalMs);
  
  return { startTime, endTime };
};

// Usage - Get last 100 candles of any interval
const { startTime, endTime } = calculateTimeRange('4h', 100);
const recentCandles = await getCandleData('ETH', '4h', startTime, endTime);

Use cases

  • Technical analysis — Analyze price patterns and calculate technical indicators
  • Charting applications — Display candlestick charts with OHLCV data
  • Trading algorithms — Backtest strategies using historical price data
  • Market research — Study price movements and volatility patterns

Body

application/json

Response

200 - application/json

Successful response with candlestick data

The response is of type object[].