OHLCV Candlesticks

GET/gateway/v1/exchange/klines

Returns OHLCV candlestick data with period summary stats (high, low, total volume).

Intervals: 15 options from `1m` to `1M`.

Pagination: use `from` to set the start time and `limit` to control candle count. For longer ranges, pass the last returned candle's timestamp as the next `from` value. Exchange-side limits vary (200–1000 per request).

Set `type=swap` to query perpetual contract candles instead of spot.

Query Parameters

pairstringrequired

Trading pair (e.g. BTC/USDT)

Example: BTC/USDT

typeenum<string>

Market type: spot for spot trading, swap/perpetual/perp for perpetual contracts

Available options:spotswapperpetualperp

Example: spot

intervalenum<string>

Candle size — bucket duration for each returned OHLCV row. This endpoint uses `interval` only; it does NOT accept `time_range`. Use `from` + `limit` to control the window.

Available options:1m3m5m15m30m1h2h4h6h8h12h1d3d1w1M

Example: 1h

fromstring

Start of time range. Accepts Unix seconds or date string (YYYY-MM-DD, ISO8601)

Example: 2026-03-01

limitinteger

Max number of candles to return. Exchange may cap lower (e.g. 200-1000). For longer ranges, paginate using the last returned timestamp as the next from value.

Example: 100

exchangeenum<string>

Exchange identifier. Note: hyperliquid uses USDC-settled perps (e.g. BTC/USDC:USDC); pass USDC-quoted pairs when querying hyperliquid.

Available options:binanceokxbybitbitgetcoinbasekrakengatehtxkucoinmexcupbitbitfinexbitstampderibitbitmexbithumbhyperliquid

Example: binance

OHLCV Candlesticks

const options = {method: 'GET'};

fetch('https://api.asksurf.ai/gateway/v1/exchange/klines?pair=BTC/USDT&type=spot&interval=1h&from=2026-03-01&limit=100&exchange=binance', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "$schema": "https://example.com/schemas/SimpleListResponseExchangeKlineResponse.json",
  "data": [
    {
      "candles": [
        {
          "close": 123,
          "high": 123,
          "low": 123,
          "open": 123,
          "timestamp": 123,
          "volume": 123
        }
      ],
      "count": 123,
      "exchange": "<string>",
      "interval": "<string>",
      "pair": "<string>",
      "period_end": "<string>",
      "period_high": 123,
      "period_low": 123,
      "period_start": "<string>",
      "period_volume": 123
    }
  ],
  "meta": {
    "cached": true,
    "credits_used": 123,
    "empty_reason": "<string>"
  }
}