Candles
Get up to 200 candle series in one request
Batched form of GET /v1/candles: fetches up to 200 independent
(provider, contract_id, timeframe_seconds, start, end, outcome)
series concurrently and returns them in request order, with
per-index partial failure — one item’s validation or fetch
error does not fail the others.
Each item is validated and aligned exactly as in GET /v1/candles
(same clamping, rollup, and inversion rules). Body accepts either a
requests array or a legacy items alias; if requests is
non-empty it is used, otherwise items is used.
timeframe_seconds and outcome in each item may be a JSON number
or a numeric string. The request body is capped at 4 MiB.
Rate limiting / cost. Admitted at the base cost of 1
light-bucket unit. Larger batches — more items, wider windows,
finer timeframes — consume more of your quota; any excess is
charged as a deferred extra charge against your next request.
Caching. Batch responses are always Cache-Control: no-store
and never carry an ETag.
Binary format. Pass ?fmt=binary or
Accept: application/x-kairos-candles to receive a single
multi-result binary frame (num_results = len(requests)) — one
columnar result section per request index, in input order. An item
that failed sets the high bit (0x80000000) of its section’s
count, so it stays distinguishable from a genuinely empty window;
mask the bit off to read the (always zero) count. Per-item error
messages are only available in the JSON response.
Failure semantics. Returns 500 only when every item in the
batch failed. Otherwise 200 with a mix of populated and
empty/errored entries.
POST
/
v1
/
candles
/
batch
Get up to 200 candle series in one request
curl --request POST \
--url https://md.kairos.trade/v1/candles/batch \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--header 'X-Api-Secret: <api-key>' \
--header 'X-Client-Id: <api-key>' \
--data '
{
"requests": [
{
"provider": "polymarket",
"contract_id": "21742633143463906290569050155826241533067272736897614950488156847949938836455",
"timeframe_seconds": 3600,
"start": "2026-07-15T00:00:00Z",
"end": "2026-07-16T00:00:00Z",
"outcome": 0
},
{
"provider": "kalshi",
"contract_id": "KXHIGHNY-26JUL15-T50",
"timeframe_seconds": 60,
"start": "2026-07-15T12:00:00Z",
"end": "2026-07-15T13:00:00Z"
}
]
}
'import requests
url = "https://md.kairos.trade/v1/candles/batch"
payload = { "requests": [
{
"provider": "polymarket",
"contract_id": "21742633143463906290569050155826241533067272736897614950488156847949938836455",
"timeframe_seconds": 3600,
"start": "2026-07-15T00:00:00Z",
"end": "2026-07-16T00:00:00Z",
"outcome": 0
},
{
"provider": "kalshi",
"contract_id": "KXHIGHNY-26JUL15-T50",
"timeframe_seconds": 60,
"start": "2026-07-15T12:00:00Z",
"end": "2026-07-15T13:00:00Z"
}
] }
headers = {
"X-Client-Id": "<api-key>",
"X-Api-Key": "<api-key>",
"X-Api-Secret": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Client-Id': '<api-key>',
'X-Api-Key': '<api-key>',
'X-Api-Secret': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
requests: [
{
provider: 'polymarket',
contract_id: '21742633143463906290569050155826241533067272736897614950488156847949938836455',
timeframe_seconds: 3600,
start: '2026-07-15T00:00:00Z',
end: '2026-07-16T00:00:00Z',
outcome: 0
},
{
provider: 'kalshi',
contract_id: 'KXHIGHNY-26JUL15-T50',
timeframe_seconds: 60,
start: '2026-07-15T12:00:00Z',
end: '2026-07-15T13:00:00Z'
}
]
})
};
fetch('https://md.kairos.trade/v1/candles/batch', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://md.kairos.trade/v1/candles/batch",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'requests' => [
[
'provider' => 'polymarket',
'contract_id' => '21742633143463906290569050155826241533067272736897614950488156847949938836455',
'timeframe_seconds' => 3600,
'start' => '2026-07-15T00:00:00Z',
'end' => '2026-07-16T00:00:00Z',
'outcome' => 0
],
[
'provider' => 'kalshi',
'contract_id' => 'KXHIGHNY-26JUL15-T50',
'timeframe_seconds' => 60,
'start' => '2026-07-15T12:00:00Z',
'end' => '2026-07-15T13:00:00Z'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Api-Key: <api-key>",
"X-Api-Secret: <api-key>",
"X-Client-Id: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://md.kairos.trade/v1/candles/batch"
payload := strings.NewReader("{\n \"requests\": [\n {\n \"provider\": \"polymarket\",\n \"contract_id\": \"21742633143463906290569050155826241533067272736897614950488156847949938836455\",\n \"timeframe_seconds\": 3600,\n \"start\": \"2026-07-15T00:00:00Z\",\n \"end\": \"2026-07-16T00:00:00Z\",\n \"outcome\": 0\n },\n {\n \"provider\": \"kalshi\",\n \"contract_id\": \"KXHIGHNY-26JUL15-T50\",\n \"timeframe_seconds\": 60,\n \"start\": \"2026-07-15T12:00:00Z\",\n \"end\": \"2026-07-15T13:00:00Z\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Client-Id", "<api-key>")
req.Header.Add("X-Api-Key", "<api-key>")
req.Header.Add("X-Api-Secret", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://md.kairos.trade/v1/candles/batch")
.header("X-Client-Id", "<api-key>")
.header("X-Api-Key", "<api-key>")
.header("X-Api-Secret", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"requests\": [\n {\n \"provider\": \"polymarket\",\n \"contract_id\": \"21742633143463906290569050155826241533067272736897614950488156847949938836455\",\n \"timeframe_seconds\": 3600,\n \"start\": \"2026-07-15T00:00:00Z\",\n \"end\": \"2026-07-16T00:00:00Z\",\n \"outcome\": 0\n },\n {\n \"provider\": \"kalshi\",\n \"contract_id\": \"KXHIGHNY-26JUL15-T50\",\n \"timeframe_seconds\": 60,\n \"start\": \"2026-07-15T12:00:00Z\",\n \"end\": \"2026-07-15T13:00:00Z\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://md.kairos.trade/v1/candles/batch")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Client-Id"] = '<api-key>'
request["X-Api-Key"] = '<api-key>'
request["X-Api-Secret"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"requests\": [\n {\n \"provider\": \"polymarket\",\n \"contract_id\": \"21742633143463906290569050155826241533067272736897614950488156847949938836455\",\n \"timeframe_seconds\": 3600,\n \"start\": \"2026-07-15T00:00:00Z\",\n \"end\": \"2026-07-16T00:00:00Z\",\n \"outcome\": 0\n },\n {\n \"provider\": \"kalshi\",\n \"contract_id\": \"KXHIGHNY-26JUL15-T50\",\n \"timeframe_seconds\": 60,\n \"start\": \"2026-07-15T12:00:00Z\",\n \"end\": \"2026-07-15T13:00:00Z\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"results": [
{
"index": 0,
"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
}
]
},
{
"index": 1,
"candles": [],
"error": "unknown provider \"acme\""
}
]
}Authorizations
Credential client id (kairos_ck_...). Must be sent together with X-Api-Key and X-Api-Secret.
64-char hex API key. Must be sent together with X-Client-Id and X-Api-Secret.
64-char hex API secret. Must be sent together with X-Client-Id and X-Api-Key.
Body
application/json
Request body of POST /v1/candles/batch. Provide either requests or the legacy items alias — if requests is non-empty it takes precedence, otherwise items is used. At least one entry is required across the two fields, and the effective array may not exceed 200 entries.
Response
Per-index results (populated, empty, or errored). Order matches the request array.
Response body of POST /v1/candles/batch in JSON mode.
Show child attributes
Show child attributes
Was this page helpful?
⌘I
Get up to 200 candle series in one request
curl --request POST \
--url https://md.kairos.trade/v1/candles/batch \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--header 'X-Api-Secret: <api-key>' \
--header 'X-Client-Id: <api-key>' \
--data '
{
"requests": [
{
"provider": "polymarket",
"contract_id": "21742633143463906290569050155826241533067272736897614950488156847949938836455",
"timeframe_seconds": 3600,
"start": "2026-07-15T00:00:00Z",
"end": "2026-07-16T00:00:00Z",
"outcome": 0
},
{
"provider": "kalshi",
"contract_id": "KXHIGHNY-26JUL15-T50",
"timeframe_seconds": 60,
"start": "2026-07-15T12:00:00Z",
"end": "2026-07-15T13:00:00Z"
}
]
}
'import requests
url = "https://md.kairos.trade/v1/candles/batch"
payload = { "requests": [
{
"provider": "polymarket",
"contract_id": "21742633143463906290569050155826241533067272736897614950488156847949938836455",
"timeframe_seconds": 3600,
"start": "2026-07-15T00:00:00Z",
"end": "2026-07-16T00:00:00Z",
"outcome": 0
},
{
"provider": "kalshi",
"contract_id": "KXHIGHNY-26JUL15-T50",
"timeframe_seconds": 60,
"start": "2026-07-15T12:00:00Z",
"end": "2026-07-15T13:00:00Z"
}
] }
headers = {
"X-Client-Id": "<api-key>",
"X-Api-Key": "<api-key>",
"X-Api-Secret": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Client-Id': '<api-key>',
'X-Api-Key': '<api-key>',
'X-Api-Secret': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
requests: [
{
provider: 'polymarket',
contract_id: '21742633143463906290569050155826241533067272736897614950488156847949938836455',
timeframe_seconds: 3600,
start: '2026-07-15T00:00:00Z',
end: '2026-07-16T00:00:00Z',
outcome: 0
},
{
provider: 'kalshi',
contract_id: 'KXHIGHNY-26JUL15-T50',
timeframe_seconds: 60,
start: '2026-07-15T12:00:00Z',
end: '2026-07-15T13:00:00Z'
}
]
})
};
fetch('https://md.kairos.trade/v1/candles/batch', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://md.kairos.trade/v1/candles/batch",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'requests' => [
[
'provider' => 'polymarket',
'contract_id' => '21742633143463906290569050155826241533067272736897614950488156847949938836455',
'timeframe_seconds' => 3600,
'start' => '2026-07-15T00:00:00Z',
'end' => '2026-07-16T00:00:00Z',
'outcome' => 0
],
[
'provider' => 'kalshi',
'contract_id' => 'KXHIGHNY-26JUL15-T50',
'timeframe_seconds' => 60,
'start' => '2026-07-15T12:00:00Z',
'end' => '2026-07-15T13:00:00Z'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Api-Key: <api-key>",
"X-Api-Secret: <api-key>",
"X-Client-Id: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://md.kairos.trade/v1/candles/batch"
payload := strings.NewReader("{\n \"requests\": [\n {\n \"provider\": \"polymarket\",\n \"contract_id\": \"21742633143463906290569050155826241533067272736897614950488156847949938836455\",\n \"timeframe_seconds\": 3600,\n \"start\": \"2026-07-15T00:00:00Z\",\n \"end\": \"2026-07-16T00:00:00Z\",\n \"outcome\": 0\n },\n {\n \"provider\": \"kalshi\",\n \"contract_id\": \"KXHIGHNY-26JUL15-T50\",\n \"timeframe_seconds\": 60,\n \"start\": \"2026-07-15T12:00:00Z\",\n \"end\": \"2026-07-15T13:00:00Z\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Client-Id", "<api-key>")
req.Header.Add("X-Api-Key", "<api-key>")
req.Header.Add("X-Api-Secret", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://md.kairos.trade/v1/candles/batch")
.header("X-Client-Id", "<api-key>")
.header("X-Api-Key", "<api-key>")
.header("X-Api-Secret", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"requests\": [\n {\n \"provider\": \"polymarket\",\n \"contract_id\": \"21742633143463906290569050155826241533067272736897614950488156847949938836455\",\n \"timeframe_seconds\": 3600,\n \"start\": \"2026-07-15T00:00:00Z\",\n \"end\": \"2026-07-16T00:00:00Z\",\n \"outcome\": 0\n },\n {\n \"provider\": \"kalshi\",\n \"contract_id\": \"KXHIGHNY-26JUL15-T50\",\n \"timeframe_seconds\": 60,\n \"start\": \"2026-07-15T12:00:00Z\",\n \"end\": \"2026-07-15T13:00:00Z\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://md.kairos.trade/v1/candles/batch")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Client-Id"] = '<api-key>'
request["X-Api-Key"] = '<api-key>'
request["X-Api-Secret"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"requests\": [\n {\n \"provider\": \"polymarket\",\n \"contract_id\": \"21742633143463906290569050155826241533067272736897614950488156847949938836455\",\n \"timeframe_seconds\": 3600,\n \"start\": \"2026-07-15T00:00:00Z\",\n \"end\": \"2026-07-16T00:00:00Z\",\n \"outcome\": 0\n },\n {\n \"provider\": \"kalshi\",\n \"contract_id\": \"KXHIGHNY-26JUL15-T50\",\n \"timeframe_seconds\": 60,\n \"start\": \"2026-07-15T12:00:00Z\",\n \"end\": \"2026-07-15T13:00:00Z\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"results": [
{
"index": 0,
"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
}
]
},
{
"index": 1,
"candles": [],
"error": "unknown provider \"acme\""
}
]
}