Trades

Fetch normalized, Kairos-ingested trade history for a contract

Returns normalized trade history for a single (provider, contract_id) from Kairos’s own ingested trade store. Unlike /trades/kalshi and /trades/polymarket, this is not a live upstream proxy — it serves from data Kairos has already ingested, so coverage depends on how much history has been backfilled/streamed for that contract.

Auth: requires the trade:read scope (admin/JWT bypass the scope check; API keys need trade:read), plus API access to the requested provider being enabled for API-key callers — 403 if disabled.

Data source / staleness: reads ingested trade rows for the window [before - window_seconds, before] (or ending “now” if before is omitted). If trigger_ingest=true and the data is missing or stale, an ingestion job is kicked off for that contract and reported via the indexing flag in the response — the returned trades may still be incomplete for that call.

GET

trades

history

Fetch normalized, Kairos-ingested trade history for a contract

curl --request GET \
  --url https://data.kairos.trade/trades/history \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Api-Secret: <api-key>' \
  --header 'X-Client-Id: <api-key>'

import requests

url = "https://data.kairos.trade/trades/history"

headers = {
    "X-Client-Id": "<api-key>",
    "X-Api-Key": "<api-key>",
    "X-Api-Secret": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'X-Client-Id': '<api-key>',
    'X-Api-Key': '<api-key>',
    'X-Api-Secret': '<api-key>'
  }
};

fetch('https://data.kairos.trade/trades/history', 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://data.kairos.trade/trades/history",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "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"
	"net/http"
	"io"
)

func main() {

	url := "https://data.kairos.trade/trades/history"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Client-Id", "<api-key>")
	req.Header.Add("X-Api-Key", "<api-key>")
	req.Header.Add("X-Api-Secret", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://data.kairos.trade/trades/history")
  .header("X-Client-Id", "<api-key>")
  .header("X-Api-Key", "<api-key>")
  .header("X-Api-Secret", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://data.kairos.trade/trades/history")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Client-Id"] = '<api-key>'
request["X-Api-Key"] = '<api-key>'
request["X-Api-Secret"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "trades": [
    {
      "trade_id": "kalshi:KXPRESPOLAND-24-DT:9f2a1c",
      "order_id": "0x9f2a1c...7bd4",
      "contract_id": "KXPRESPOLAND-24-DT",
      "size": 50,
      "price": 63,
      "outcome": "yes",
      "timestamp": 1753142400,
      "yes_price": 63,
      "no_price": 37,
      "taker_side": "yes",
      "token_id": "<string>",
      "metadata": "<string>",
      "taker_address": "<string>",
      "maker_address": "<string>",
      "side": "BUY"
    }
  ],
  "has_more": true,
  "source": "<string>",
  "coverage_hours": 24,
  "indexing": false,
  "oldest_available_ts": 1750000000
}

{
  "detail": "Invalid trade history request"
}

{
  "detail": "Not authenticated"
}

{
  "detail": "<string>"
}

{
  "detail": [
    {}
  ]
}

{
  "error": "Rate limit exceeded: 100 per 1 minute"
}

{
  "detail": "Trade history fetch failed"
}

{
  "detail": "Invalid provider"
}

Authorizations

X-Client-Id

string

header

required

Credential client id (kairos_ck_...). Must be sent together with X-Api-Key and X-Api-Secret.

X-Api-Key

string

header

required

64-char hex API key.

X-Api-Secret

string

header

required

64-char hex API secret.

Query Parameters

provider

string

required

Venue identifier, matched case-insensitively against the live provider registry.

contract_id

string

required

Provider-specific contract identifier. Empty or >128 chars returns 400.

Required string length: 1 - 128

window_seconds

integer

default:86400

Lookback window in seconds, ending at before (or now). Clamped to [3600, 86400] (1 hour to 24 hours).

Required range: 3600 <= x <= 86400

before

integer | null

Unix-seconds cursor — return trades at or before this timestamp. Omit to end the window at "now".

limit

integer | null

Max trades returned. If omitted, the service applies its own internal default.

Required range: 1 <= x <= 500

trigger_ingest

boolean

default:false

If true, kicks off ingestion when data for this window is stale or missing, rather than just returning what's already stored.

Response

Normalized trade rows for the window plus pagination/coverage metadata.

trades

object[]

required

Show child attributes

has_more

boolean

required

True if more trades exist before the oldest trade in this response (pagination via before).

source

string

required

Opaque internal marker indicating how the response was served. NOT a stable part of the contract — its value may change without notice; do not depend on or switch on it.

coverage_hours

number

required

Hours of trade history coverage available/considered for this response.

Example:

24

indexing

boolean

required

True if ingestion was triggered/in progress for this window (only meaningful with trigger_ingest=true).

Example:

false

oldest_available_ts

number | null

Unix timestamp (seconds) of the oldest trade Kairos has ingested for this contract, or null if unknown.

Example:

1750000000

Fetch normalized, Kairos-ingested trade history for a contract

curl --request GET \
  --url https://data.kairos.trade/trades/history \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Api-Secret: <api-key>' \
  --header 'X-Client-Id: <api-key>'

import requests

url = "https://data.kairos.trade/trades/history"

headers = {
    "X-Client-Id": "<api-key>",
    "X-Api-Key": "<api-key>",
    "X-Api-Secret": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'X-Client-Id': '<api-key>',
    'X-Api-Key': '<api-key>',
    'X-Api-Secret': '<api-key>'
  }
};

fetch('https://data.kairos.trade/trades/history', 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://data.kairos.trade/trades/history",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "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"
	"net/http"
	"io"
)

func main() {

	url := "https://data.kairos.trade/trades/history"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Client-Id", "<api-key>")
	req.Header.Add("X-Api-Key", "<api-key>")
	req.Header.Add("X-Api-Secret", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://data.kairos.trade/trades/history")
  .header("X-Client-Id", "<api-key>")
  .header("X-Api-Key", "<api-key>")
  .header("X-Api-Secret", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://data.kairos.trade/trades/history")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Client-Id"] = '<api-key>'
request["X-Api-Key"] = '<api-key>'
request["X-Api-Secret"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "trades": [
    {
      "trade_id": "kalshi:KXPRESPOLAND-24-DT:9f2a1c",
      "order_id": "0x9f2a1c...7bd4",
      "contract_id": "KXPRESPOLAND-24-DT",
      "size": 50,
      "price": 63,
      "outcome": "yes",
      "timestamp": 1753142400,
      "yes_price": 63,
      "no_price": 37,
      "taker_side": "yes",
      "token_id": "<string>",
      "metadata": "<string>",
      "taker_address": "<string>",
      "maker_address": "<string>",
      "side": "BUY"
    }
  ],
  "has_more": true,
  "source": "<string>",
  "coverage_hours": 24,
  "indexing": false,
  "oldest_available_ts": 1750000000
}

{
  "detail": "Invalid trade history request"
}

{
  "detail": "Not authenticated"
}

{
  "detail": "<string>"
}

{
  "detail": [
    {}
  ]
}

{
  "error": "Rate limit exceeded: 100 per 1 minute"
}

{
  "detail": "Trade history fetch failed"
}

{
  "detail": "Invalid provider"
}

Overview

Market Data API

Data API

Execution API

Agora Auction API

REST Guides

Market Data Guides

RPC Guides

RFQ Guides

WebSocket Guides

Krisis Guides

Fetch normalized, Kairos-ingested trade history for a contract

Authorizations

Query Parameters

Response