Kairos Quickstart: Live Markets and Your First Order

Prefer WebSocket for order submission. Placing and cancelling orders over the persistent /ws socket is lower-latency (one round trip instead of the REST submit/poll pair) and simpler to build: one connection, one auth handshake, and pushed order_update/fill events instead of polling. See Order Execution over WebSocket.

Kairos gives you two tiers of access: a completely free, unauthenticated Market Data API you can call right now, and authenticated Data and Execution APIs that unlock trading, analytics, and auctions. This guide walks you through both — from your first unauthenticated request all the way to placing your first order.

Fetch live markets — no signup needed

The Market Data API (md.kairos.trade) requires no API key. Call it directly from your terminal, browser, or code. The example below fetches one page of active Polymarket markets.

curl
Python
JavaScript

curl "https://md.kairos.trade/v1/markets?provider=polymarket&limit=5"

import requests

response = requests.get(
    "https://md.kairos.trade/v1/markets",
    params={"provider": "polymarket", "limit": 5},
)
response.raise_for_status()
print(response.json())

const response = await fetch(
  "https://md.kairos.trade/v1/markets?provider=polymarket&limit=5"
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());

You should receive a cursor page of active markets:

{
  "exchange_id": "polymarket",
  "markets": [
    {
      "exchange_id": "polymarket",
      "market_id": "0x1234abcd...",
      "title": "Will the Fed cut rates in September?",
      "neg_risk": false,
      "outcomes": [
        { "outcome": "Yes", "normalized_outcome": "yes", "token_id": "0x...", "outcome_index": 0, "side": "yes" },
        { "outcome": "No", "normalized_outcome": "no", "token_id": "0x...", "outcome_index": 1, "side": "no" }
      ]
    }
  ],
  "count": 1,
  "next_cursor": "eyJvZmZzZXQiOjV9",
  "has_more": true
}

provider accepts polymarket, kalshi, or predictfun. Pass the returned next_cursor back as the cursor query parameter to page through results, and stop when has_more is false. Prices in this response are not included — see Markets, Resolutions & Marks for marks and metadata.

Get your API key

The Data API and Execution API require authentication. To get a key:

Go to app.kairos.trade and create an account.
Navigate to Settings → API Keys.
Click Create API Key, give it a name, and select the scopes you need.
Copy the three values immediately — the secret is only shown once.

A Kairos API key is a triple of headers, sent together on every authenticated request:

X-Client-Id: kairos_ck_...
X-Api-Key: <64 hex chars>
X-Api-Secret: <64 hex chars>

Store the triple in an environment variable or secrets manager. Never hardcode it in source files or commit it to version control.

The web app also accepts a first-party session JWT as Authorization: Bearer <jwt>, but JWTs are not issued to API consumers — use the header triple for integrations. Full detail: Authentication.

Make an authenticated Data API call

With your credentials in hand, confirm they work by listing active markets from the authenticated Data API.

curl
Python
JavaScript

curl -G "https://data.kairos.trade/markets/active" \
  --data-urlencode "provider=polymarket" \
  --data-urlencode "limit=1" \
  -H "X-Client-Id: $KAIROS_CLIENT_ID" \
  -H "X-Api-Key: $KAIROS_API_KEY" \
  -H "X-Api-Secret: $KAIROS_API_SECRET"

import os
import requests

response = requests.get(
    "https://data.kairos.trade/markets/active",
    params={"provider": "polymarket", "limit": 1},
    headers={
        "X-Client-Id": os.environ["KAIROS_CLIENT_ID"],
        "X-Api-Key": os.environ["KAIROS_API_KEY"],
        "X-Api-Secret": os.environ["KAIROS_API_SECRET"],
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch(
  "https://data.kairos.trade/markets/active?provider=polymarket&limit=1",
  {
    headers: {
      "X-Client-Id": process.env.KAIROS_CLIENT_ID,
      "X-Api-Key": process.env.KAIROS_API_KEY,
      "X-Api-Secret": process.env.KAIROS_API_SECRET,
    },
  }
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());

A 200 with a markets array means your credentials are working. A 401 means a missing or invalid header triple; a 403 means the key lacks the required scope for that route.

Submit your first order

Before you can trade, enable trading on the venue once — this provisions credentials and sets on-chain approvals.

curl
Python
JavaScript

# One-time setup: enable trading on Polymarket
curl -X POST "https://execution.kairos.trade/exchanges/polymarket/enable-trading" \
  -H "X-Client-Id: $KAIROS_CLIENT_ID" \
  -H "X-Api-Key: $KAIROS_API_KEY" \
  -H "X-Api-Secret: $KAIROS_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{}'

# Submit a limit order
curl -X POST "https://execution.kairos.trade/orders" \
  -H "X-Client-Id: $KAIROS_CLIENT_ID" \
  -H "X-Api-Key: $KAIROS_API_KEY" \
  -H "X-Api-Secret: $KAIROS_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "exchange_id": "polymarket",
    "market_id": "0x1234abcd...",
    "token_id": "0x...",
    "outcome": "Yes",
    "side": "buy",
    "kind": "limit",
    "quantity": 10,
    "price": 0.60,
    "time_in_force": "GTC"
  }'

import os
import requests

base = "https://execution.kairos.trade"
headers = {
    "X-Client-Id": os.environ["KAIROS_CLIENT_ID"],
    "X-Api-Key": os.environ["KAIROS_API_KEY"],
    "X-Api-Secret": os.environ["KAIROS_API_SECRET"],
    "Content-Type": "application/json",
}

# One-time setup
requests.post(f"{base}/exchanges/polymarket/enable-trading",
              headers=headers, json={}).raise_for_status()

order = {
    "exchange_id": "polymarket",
    "market_id": "0x1234abcd...",
    "token_id": "0x...",
    "outcome": "Yes",
    "side": "buy",
    "kind": "limit",
    "quantity": 10,
    "price": 0.60,
    "time_in_force": "GTC",
}
response = requests.post(f"{base}/orders", headers=headers, json=order)
response.raise_for_status()
print(response.json())

const base = "https://execution.kairos.trade";
const headers = {
  "X-Client-Id": process.env.KAIROS_CLIENT_ID,
  "X-Api-Key": process.env.KAIROS_API_KEY,
  "X-Api-Secret": process.env.KAIROS_API_SECRET,
  "Content-Type": "application/json",
};

await fetch(`${base}/exchanges/polymarket/enable-trading`, {
  method: "POST",
  headers,
  body: JSON.stringify({}),
});

const response = await fetch(`${base}/orders`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    exchange_id: "polymarket",
    market_id: "0x1234abcd...",
    token_id: "0x...",
    outcome: "Yes",
    side: "buy",
    kind: "limit",
    quantity: 10,
    price: 0.60,
    time_in_force: "GTC",
  }),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());

A successful submission returns the internal order id and its initial status:

{
  "order_id": "0f8c2b7a-6e1d-4c3a-9b2f-2d6f0a1c9e44",
  "status": "queued"
}

queued means the order is accepted and in flight — not live on the venue yet. Track it with GET /orders/{order_id}, or (lower latency) subscribe to the /ws socket’s order_update and fill events. price is required on every order, including market orders, where it is the limit you are willing to cross. See Placing Orders for time-in-force and per-venue rules.

What’s next?

Order Execution over WebSocket

The lowest-latency way to place and cancel orders, with pushed fills instead of polling.

Authentication

API key scopes, the session JWT, rate limits, and auth error handling.

Market Data API

All 15 free endpoints for markets, candles, trades, and perpetuals.

Placing Orders

Required fields, order kinds, time-in-force, statuses, and cancellation.

Get Started

Core Concepts

Learn Trading

Guides

Perpetual Futures

External Execution

Trading

Compliance

Updates

Kairos Quickstart: Live Markets and Your First Order

What’s next?

Order Execution over WebSocket

Authentication

Market Data API

Placing Orders

​What’s next?

Order Execution over WebSocket

Authentication

Market Data API

Placing Orders

What’s next?