> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kairos.trade/llms.txt
> Use this file to discover all available pages before exploring further.
# API Reference
> Every public Kairos API in one place — REST, streaming, and OpenAPI-generated endpoint references across four services.
**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](/websocket/order-execution).
Kairos exposes several API services. Each has its own base URL, authentication model, pagination style, and error envelope — the only thing genuinely shared is the API-key header triple. This page maps them; the navigation holds the hand-written guides and the OpenAPI-generated endpoint references.
| API | Base URL | Auth | Purpose |
| - | - | - | - |
| **Market Data API** | `https://md.kairos.trade` | None | Free market data: markets, candles, trades, resolutions, perpetuals |
| **Data API** | `https://data.kairos.trade` | API key | Markets, search, sports, trader analytics, PnL, discovery |
| **Execution API** | `https://execution.kairos.trade` | API key | Order entry, cancellation, routing, combos, external signing |
| **Agora Auction API** | `https://agora.kairos.trade` | Session JWT | Private institutional auctions with firm quotes and a WebSocket event stream |
| **RPC API** | `https://rpc.kairos.trade/api/rpc` | API key / JWT | Account-scoped state: positions, balances, copy trading (tRPC) |
| **RFQ Network** | `https://rfq.kairos.trade` | API key / JWT | Cross-venue request-for-quote over REST, WebSocket, and FIX |
The four API groups below the overview are **generated from the OpenAPI specs**, so they always reflect the current wire contract — parameters, request bodies, and responses. The **Guides** beneath them add the caveats that don't fit in a schema: pagination quirks, field casing, price scales, and error handling. Read the generated page for the exact fields, then the matching guide for the gotchas.
## Your first request
The Market Data API needs no credentials — call it right now:
```bash theme={null}
curl "https://md.kairos.trade/v1/markets?provider=polymarket&limit=5"
```
For an authenticated service, send the API-key triple on every request:
```bash theme={null}
curl "https://data.kairos.trade/markets/active?provider=polymarket&limit=5" \
-H "X-Client-Id: $KAIROS_CLIENT_ID" \
-H "X-Api-Key: $KAIROS_API_KEY" \
-H "X-Api-Secret: $KAIROS_API_SECRET"
```
The exact request shape, status semantics, and error codes for the custodial order lane.
Real-time orderbooks, trades, and prices over WebSocket with protobuf encoding.
Platform tiers, per-venue exchange fees, and the live fee-quote endpoint.
API keys, scopes, the session JWT, and how each service reports auth failures.
## Machine-readable specifications
Every public API is described by an OpenAPI 3.1 specification. The copies below power the auto-generated endpoint references; download them to generate clients or feed your own tooling.
| Spec | Service |
| - | - |
| [market-data-api.yaml](/openapi/market-data-api.yaml) | Market Data API (`md.kairos.trade`) |
| [data-api.yaml](/openapi/data-api.yaml) | Data API (`data.kairos.trade`) |
| [execution.yaml](/openapi/execution.yaml) | Execution API (`execution.kairos.trade`) |
| [agora.yaml](/openapi/agora.yaml) | Agora Auction House (`agora.kairos.trade`) |
WebSocket surfaces are described separately with AsyncAPI. See the [WebSocket](/websocket/market-data-websocket) section for the wire contracts and [Protobuf Schema](/websocket/protobuf-reference) for the generated message definitions.
## What trips people up first
These bite almost every first integration. Each links to the guide with the full detail.
* **`price` is required on every order** — including market orders, where it is the limit you are willing to cross, not a sentinel. Omitting it is a `400`. See [Orders](/rest/orders).
* **Tick grids change while a market trades.** Read `ranges` and `min_tick` (and treat them as decimal strings, not floats), not a single cached tick size. See [Markets, Resolutions & Marks](/market-data/markets).
* **Casing is per-service.** `/orders` and most REST is `snake_case`; `/combo/*` is `camelCase`; the RPC API uses `camelCase`. Copy the generated reference for the service you're calling. See [Combos & Parlays](/rest/combo).
* **Price scales differ by surface.** Candles and trades are on a `0–100` scale; marks and resolution payouts are `0–1`; some discovery feeds return `camelCase` with a `24h` suffix. See [Markets & Prices](/rest/markets).
* **A bad credential triple on an execution mutation is `403`, not `401`.** Handle both. See [Orders](/rest/orders#errors).
* **The fastest way to trade is the WebSocket.** Submit and cancel over `/ws` instead of the REST submit/poll pair. See [Order Execution over WebSocket](/websocket/order-execution).
## Conventions
* **Authentication** — the Market Data API is anonymous and free. The Data and Execution APIs accept the API-key triple; Agora requires a first-party session JWT; the RPC API accepts either. Scopes are per-operation. See [API Key Auth](/guides/authentication).
* **Pagination** — mixed. The Market Data API, `/markets/active`, `/trades/kalshi`, and `/matched-markets` are cursor-based (pass the returned `next_cursor` back as `cursor`). Most Data API list endpoints and all RPC list procedures use `limit`/`offset`.
* **Errors** — each service has its own envelope: Execution returns `error_details.code`, the Data API returns `{"detail": ...}`, the Market Data API returns `{"error": {"code", "message"}}`, and the RPC API returns a tRPC error with `error.data.code`. Status codes are standard HTTP.
* **Rate limits** — per-IP on the free tier, per-key on authenticated tiers. Honor `429` with exponential backoff.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.