> ## 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.

# Kairos Quickstart: Live Markets and Your First Order

> Two paths in one guide: a no-signup Market Data API call, then an authenticated order on the Execution API.

<Note>
  **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).
</Note>

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.

<Steps>
  <Step title="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.

    <Tabs>
      <Tab title="curl">
        ```bash theme={null}
        curl "https://md.kairos.trade/v1/markets?provider=polymarket&limit=5"
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        import requests

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

      <Tab title="JavaScript">
        ```javascript theme={null}
        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());
        ```
      </Tab>
    </Tabs>

    You should receive a cursor page of active markets:

    ```json theme={null}
    {
      "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
    }
    ```

    <Tip>
      `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](/market-data/markets) for marks and metadata.
    </Tip>
  </Step>

  <Step title="Get your API key">
    The Data API and Execution API require authentication. To get a key:

    1. Go to [app.kairos.trade](https://app.kairos.trade) and create an account.
    2. Navigate to **Settings → API Keys**.
    3. Click **Create API Key**, give it a name, and select the scopes you need.
    4. 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>
    ```

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

    <Note>
      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](/guides/authentication).
    </Note>
  </Step>

  <Step title="Make an authenticated Data API call">
    With your credentials in hand, confirm they work by listing active markets from the authenticated Data API.

    <Tabs>
      <Tab title="curl">
        ```bash theme={null}
        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"
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        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())
        ```
      </Tab>

      <Tab title="JavaScript">
        ```javascript theme={null}
        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());
        ```
      </Tab>
    </Tabs>

    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.
  </Step>

  <Step title="Submit your first order">
    Before you can trade, enable trading on the venue once — this provisions credentials and sets on-chain approvals.

    <Tabs>
      <Tab title="curl">
        ```bash theme={null}
        # 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"
          }'
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        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())
        ```
      </Tab>

      <Tab title="JavaScript">
        ```javascript theme={null}
        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());
        ```
      </Tab>
    </Tabs>

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

    ```json theme={null}
    {
      "order_id": "0f8c2b7a-6e1d-4c3a-9b2f-2d6f0a1c9e44",
      "status": "queued"
    }
    ```

    <Note>
      `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](/guides/order-types) for time-in-force and per-venue rules.
    </Note>
  </Step>
</Steps>

## What's next?

<CardGroup cols={2}>
  <Card title="Order Execution over WebSocket" icon="bolt" href="/websocket/order-execution">
    The lowest-latency way to place and cancel orders, with pushed fills instead of polling.
  </Card>

  <Card title="Authentication" icon="key" href="/guides/authentication">
    API key scopes, the session JWT, rate limits, and auth error handling.
  </Card>

  <Card title="Market Data API" icon="chart-column" href="/market-data/overview">
    All 15 free endpoints for markets, candles, trades, and perpetuals.
  </Card>

  <Card title="Placing Orders" icon="list-check" href="/guides/order-types">
    Required fields, order kinds, time-in-force, statuses, and cancellation.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.