Returns OHLCV candles for one (provider, contract_id, timeframe_seconds, outcome) series over [start, end).

Alignment. start is floored and end is ceiled to the nearest timeframe_seconds bucket boundary; end is additionally clamped to now + 1 bucket. Degenerate windows (end <= start after alignment) are extended by exactly one bucket. The requested window is silently clamped (not rejected) to the per-timeframe retention ceiling: 1s=1 day, 1m=30 days, 5m=90 days, 15m=180 days, 1h=365 days, 4h=365 days, 1d=730 days. For timeframe_seconds=1, if the aligned window falls entirely before now - 24h (the retention window for 1-second candles) the endpoint short-circuits to {"candles":[]} without querying upstream.

Timeframes. Only 1s and 1m candles are stored directly; every other timeframe (5m, 15m, 1h, 4h, 1d) is rolled up server-side from the 1m base. When the first read comes back empty, 60, 3600, 14400 and 86400 retry as a rollup of the 1s base (brand-new contracts whose only history is 1-second candles); 300 and 900 have no such fallback and return an empty series instead. Prices are on a 0-100 scale. For providers that are not natively per-token (i.e. not kalshi, polymarket, dome, opinion, predictfun, hyperliquid), requesting outcome > 0 inverts prices (price = 100 - price, high/low swapped) rather than resolving a distinct token. The check is on the provider string exactly as submitted, so the kalshi_offchain alias takes the inverting path even though kalshi does not — send kalshi for Kalshi candles.

Rate limiting / cost. This route is in the light rate-limit bucket. Larger requests — wider windows, finer timeframes — consume more of your quota; a typical chart paint (a few hundred bars) costs 1 unit.

Caching. Cache-Control depends on how the aligned window relates to now: a window still in progress (end >= now) is no-store; a window entirely in the recent past is cached briefly; anything older is cached for longer. Cacheable responses carry a strong ETag and honor If-None-Match, returning 304 on a match. Responses ≥1KB are gzip-encoded when the client sends Accept-Encoding: gzip.

Binary format. Pass ?fmt=binary or send Accept: application/x-kairos-candles to receive a compact columnar binary frame instead of JSON. Layout: u8 magic=0xCA, u8 version=1, u16 num_results, then per result u32 index, u32 count, followed by the columnar arrays u32[count] t (epoch seconds), u16[count] o,h,l,c (price ×100), i64[count] vol (×100). A single-series GET response always has num_results=1.

{
  "candles": [
    {
      "contract_id": "21742633143463906290569050155826241533067272736897614950488156847949938836455",
      "timeframe_seconds": 3600,
      "bucket_start": "2026-07-15T00:00:00+00:00",
      "open": 61.5,
      "high": 63,
      "low": 60.8,
      "close": 62.4,
      "volume": 184230,
      "token_id": "704721957297303853272349184"
    }
  ]
}