Candles and History

Pick the Right Series

Ranges and Intervals

• interval is one of 1m, 5m, 10m, 15m, 30m, 1h (the default), 4h, 1d, 7d or 1w, aligned to UTC.
• time_start is inclusive and time_end exclusive, both RFC 3339. Without them a request covers the 24 hours up to now.
• One request spans at most 31 days, and your plan's history depth bounds how far back it may start. The public candle sources retain 31 days.
• Results are newest first. An interval with no data is left out, not filled: a gap in the series is a period with nothing to report.

Asset Candles

curl -s "https://api.cantoncap.cc/v1/assets/ohlcv/historical?ids=ast_515c3eaa72bd4a8b9403297879d78ef6&convert=USD&interval=1h&time_start=2026-10-10T00:00:00Z&time_end=2026-10-11T00:00:00Z" \
  -H "X-API-Key: $CANTONCAP_API_KEY"

{
  "last_updated_at": "2026-10-11T00:01:12.000Z",
  "asset_id": "ast_515c3eaa72bd4a8b9403297879d78ef6",
  "convert": "USD",
  "interval": "1h",
  "open_time": "2026-10-10T23:00:00.000Z",
  "close_time": "2026-10-11T00:00:00.000Z",
  "open": "0.1561",
  "high": "0.1602",
  "low": "0.1549",
  "close": "0.1584",
  "volume": "61240.18",
  "volume_usd": "61240.18",
  "volume_coverage": "complete",
  "trade_count": 212,
  "volume_method": "observed_trades",
  "complete": true
}

• complete becomes true once the period has ended. A complete candle can still be corrected later, so re-read recent periods rather than caching them forever.
• Asset candle volume is the USD value of the asset's observed public trades across its markets, whatever convert is. volume_coverage separates a verified zero (complete) from a partial subtotal or an unavailable measurement.
• Asset candles are built ahead of time and served from storage. While a range is not yet published the endpoint answers a retryable 503 source_unavailable; retry with backoff.

Market Candles

Market candles are the venue's own candles where the venue publishes them, including its forming bar, and otherwise CantonCap rollups built from the market's trades. Prices are in the market's quote asset, and volumes come as volume_base and volume_quote. Find a market's ID with Venues, markets and pairs.

curl -s "https://api.cantoncap.cc/v1/markets/mkt_4c2e9a7f1b3d4e5a9c8b7d6e5f4a3b21/ohlcv?interval=15m&limit=96" \
  -H "X-API-Key: $CANTONCAP_API_KEY"

Price and FDV History

The historical quotes are sampled reference prices: one point per interval, the latest quote calculated in it, with the FDV valued at that same instant and never revalued later. Several assets can be read in one request; limit counts points across all of them.

curl -s "https://api.cantoncap.cc/v1/assets/quotes/historical?ids=ast_515c3eaa72bd4a8b9403297879d78ef6,ast_7a1f0c9e3d5b4e2a8c6f1b0d9e7a3c54&convert=USD&interval=1d&time_start=2026-09-12T00:00:00Z" \
  -H "X-API-Key: $CANTONCAP_API_KEY"

Note that volume_24h on a point is the rolling 24-hour volume at that instant, not the volume within the interval. For interval volume use candles.

Page Through a Long Range

When a range holds more points than one page, follow pagination.next_cursor with the same parameters. The cursor pins the range and the data retained before the first page, so the traversal never duplicates or skips points.

async function allCandles(params) {
  const out = [];
  let cursor = null;
  do {
    const url = new URL("https://api.cantoncap.cc/v1/assets/ohlcv/historical");
    for (const [k, v] of Object.entries({ ...params, ...(cursor ? { cursor } : {}) })) {
      url.searchParams.set(k, v);
    }
    const response = await fetch(url, { headers: { "X-API-Key": process.env.CANTONCAP_API_KEY } });
    const body = await response.json();
    if (!response.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
    out.push(...body.data);
    cursor = body.pagination?.next_cursor ?? null;
  } while (cursor);
  return out;
}

const month = await allCandles({
  ids: "ast_515c3eaa72bd4a8b9403297879d78ef6", convert: "USD", interval: "1h",
  time_start: "2026-09-12T00:00:00Z", time_end: "2026-10-12T00:00:00Z", limit: "100",
});