Batched form of GET /candles. Accepts up to 200 per-contract requests and returns results in the same order, index-tagged.

Auth: same as GET /candles — require_auth_or_admin_or_apikey, no scope required.

Cache / data source: each item is checked against the cache in parallel first; only uncached items are fetched fresh. Items with rebuild: true always skip the cache regardless of a hit.

Fail-fast, partial-failure semantics: an empty series for an item is returned as "candles": [] (not an error) — the client renders an empty chart and expects later bars via the live WebSocket feed; there is no server-side ingestion retry. If fetching fails for some items but others were already served from cache, those cached items are still returned; every failed item instead gets "candles": [], "error": "<message>" so the client can distinguish a genuine failure from a legitimately empty window. Only if no item could be served at all does the whole request fail with 500.

Validation (all 400): body must contain a JSON array under requests (or the legacy alias items); the array must be non-empty and at most 200 items; each item must be an object with provider, contract_id, timeframe_seconds, start, and end present; the same per-field checks as GET /candles apply per item (unknown provider, invalid contract_id, disallowed timeframe, unparseable/out-of-order timestamps, negative or non-integer outcome).

{
  "requests": [
    {
      "provider": "kalshi",
      "contract_id": "KXPRESPOLAND-24-DT",
      "timeframe_seconds": 60,
      "start": "2026-07-21T00:00:00Z",
      "end": "2026-07-22T00:00:00Z"
    }
  ]
}

{
  "results": [
    {
      "candles": [
        {
          "contract_id": "KXPRESPOLAND-24-DT",
          "timeframe_seconds": 60,
          "bucket_start": "2026-07-21T14:32:00+00:00",
          "open": 63.5,
          "high": 64,
          "low": 63,
          "close": 63.8,
          "volume": 1250,
          "token_id": "71321045679252212594626385532706912750332728571942532289631379312455583992563"
        }
      ],
      "error": "Candle batch fetch failed"
    }
  ]
}