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

# Paginate active markets for one provider

> Enumerates active markets for a single provider, cursor-paginated. Rate-limit bucket: LIGHT.

The response is ETagged (strong ETag) with a `Cache-Control` header; a matching `If-None-Match` returns 304.

Returns 503 (`cache_cold`) until the active-market listing has been populated for the requested provider at least once.

Cursor page: pass the returned `next_cursor` back as `cursor`, and stop when `has_more` is `false`. This endpoint returns market identity (ids, outcomes, token ids) only — use `/v1/marks` for prices and `/v1/candles` for history.


## OpenAPI

````yaml /openapi/market-data-api.yaml get /v1/markets
openapi: 3.1.0
info:
  title: Kairos Market Data API
  version: 1.2.0
  summary: Read-only prediction and perpetual market data across venues.
  description: >
    The Kairos Market Data API provides read-only access

    to normalized prediction-market data across every venue Kairos integrates:

    OHLCV candles, the trade tape, market metadata, resolution lifecycles, and

    latest mark prices.


    ## No signup required


    Every endpoint works **without credentials** on the anonymous free tier,

    rate-limited per source IP (120 light units/min, 20 heavy units/min). Try
    any

    request from the interactive docs at

    [app.kairos.trade/docs/market-data](https://app.kairos.trade/docs/market-data)

    or straight from curl. For production budgets (1,200 light and 150 heavy

    units/min by default, raisable per credential), request an API key from the

    Kairos team.


    ## Authentication


    Three modes, resolved per request:


    - **Anonymous** — no credential headers at all. Free tier, IP-keyed limits.

    - **API key** — `X-Client-Id` + `X-Api-Key` + `X-Api-Secret` headers
      (all three; partial header sets are rejected with 401 rather than
      degrading to anonymous).
    - **First-party session** — `Authorization: Bearer` JWT (Kairos web app
      sessions only; not offered to API consumers).

    Resolution order is fixed: an `Authorization` header takes the bearer

    path, any of the three API-key headers takes the API-key path, and only

    a request carrying neither is eligible for the anonymous tier.


    On the API-key path, an unreachable credential store surfaces on **any**

    endpoint as `500` with `code: internal` and the message

    `authentication backend unavailable`. A source IP outside a credential's

    whitelist is `403 ip_not_whitelisted`; that is the only 403 this service

    emits.


    ## Rate limiting


    Weighted sliding-window budgets over one minute, in **units**, across two

    independent buckets: light (candles, metadata, resolutions, trade

    metrics) and heavy (trade history, marks, perpetual snapshots). Most

    requests cost 1 unit; larger requests may consume more of your quota —

    each operation's `x-kairos-rate-limit` states its exact cost model.

    Every admitted response carries `X-RateLimit-Bucket`, `X-RateLimit-Tier`,

    `X-RateLimit-Remaining`, and `X-RateLimit-Reset`; 429s add `Retry-After`.


    A separate per-IP admission gate runs *before* authentication to keep a

    flood off shared infrastructure. It also answers 429 `rate_limited`, but

    with `Retry-After: 60` and no `X-RateLimit-*` headers.


    Redis backs the weighted limiter and it fails **closed**: if it is

    unreachable the request is rejected with 503 `rate_limiter_unavailable`

    rather than let through unmetered.


    ## Conventions


    - **Prediction-market prices** are on the 0–100 scale (implied probability
      × 100) in the prediction candle, trade, and mark endpoints. Prediction
      USD notional = `size × price / 100`.
    - **Perpetual prices are direct venue prices**, not probabilities and not
      0–100 values. Perpetual quantities retain their declared native unit
      (`base_asset` or `contracts`). Never divide a perpetual price by 100 or
      compute contract notional without the instrument's authoritative contract
      multiplier; the snapshot does not synthesize a cross-venue notional.
    - **Hyperliquid is two products on one venue.** Its HIP-4 outcome markets
      are prediction markets, read with `provider=hyperliquid` on the
      prediction endpoints; its perpetuals are bare coins read under
      `/v1/perpetuals/hyperliquid/{instrument}/snapshot`, where the instrument
      is the canonical id `hl-mainnet-<symbol>-<quote>` (e.g.
      `hl-mainnet-btc-usdt`). Different id schemes, different price semantics;
      they are never interchangeable.
    - **Errors** all use one envelope:
      `{"error": {"code": "...", "message": "..."}}`.
    - **Providers** are case-insensitive; `kalshi_offchain` aliases `kalshi`,
      `dome` aliases `polymarket`, and `opinion` is resolvable for historic
      reads only.
  contact:
    name: Kairos
    url: https://app.kairos.trade/docs/market-data
  termsOfService: https://kairos.trade/terms
servers:
  - url: https://md.kairos.trade
    description: Production
  - url: https://staging-md.kairos.trade
    description: Staging
security:
  - {}
  - apiKeyClientId: []
    apiKeyKey: []
    apiKeySecret: []
tags:
  - name: Candles
    description: OHLCV candle series (1s → 1d), JSON or compact columnar binary.
  - name: Trades
    description: Trade tape and aggregate volume metrics.
  - name: Markets
    description: Market metadata, batch lookup, identifier resolution, and enumeration.
  - name: Resolutions
    description: Resolution outcomes and UMA-style lifecycle state/timelines.
  - name: Marks
    description: Latest mark (last trade price) per outcome token.
  - name: Perpetuals
    description: Live perpetual books, trades, candles, funding, and market state. Beta.
  - name: Status
    description: Health and readiness probes.
paths:
  /v1/markets:
    get:
      tags:
        - Markets
      summary: Paginate active markets for one provider
      description: >-
        Enumerates active markets for a single provider, cursor-paginated.
        Rate-limit bucket: LIGHT.


        The response is ETagged (strong ETag) with a `Cache-Control` header; a
        matching `If-None-Match` returns 304.


        Returns 503 (`cache_cold`) until the active-market listing has been
        populated for the requested provider at least once.
      operationId: listMarkets
      parameters:
        - name: provider
          in: query
          required: true
          description: >-
            Venue identifier. Case-insensitive; unknown values are rejected with
            400.
          schema:
            type: string
            enum:
              - kalshi
              - polymarket
              - opinion
              - predictfun
              - hyperliquid
              - kalshi_offchain
              - dome
          example: kalshi
        - name: limit
          in: query
          required: false
          description: Page size. Must be an integer in [1, 250].
          schema:
            type: integer
            minimum: 1
            maximum: 250
            default: 100
          example: 100
        - name: cursor
          in: query
          required: false
          description: Opaque pagination cursor from a previous response's `next_cursor`.
          schema:
            type: string
      responses:
        '200':
          description: Page of active markets.
          headers:
            ETag:
              schema:
                type: string
            Cache-Control:
              schema:
                type: string
                example: public, max-age=30
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketListResponse'
              example:
                exchange_id: kalshi
                markets:
                  - exchange_id: kalshi
                    market_id: KXBTC-26JUL
                    condition_id: ''
                    event_id: KXBTC-26JUL-EVT
                    title: Bitcoin price above $120k on July 31?
                    neg_risk: false
                    outcomes:
                      - outcome: 'Yes'
                        normalized_outcome: 'yes'
                        token_id: KXBTC-26JUL-YES
                        outcome_index: 0
                        side: 'yes'
                      - outcome: 'No'
                        normalized_outcome: 'no'
                        token_id: KXBTC-26JUL-NO
                        outcome_index: 1
                        side: 'no'
                    raw: {}
                count: 1
                next_cursor: eyJvZmZzZXQiOjEwMH0=
                has_more: true
        '304':
          description: Not Modified — `If-None-Match` matched the current ETag.
        '400':
          description: Missing/unknown `provider`, or `limit` out of range.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: invalid_request
                  message: limit must be an integer in [1, 250]
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/IPNotWhitelisted'
        '404':
          description: The upstream metadata cache answered the listing request with 404.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: not_found
                  message: market not found
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          description: >-
            `internal` / `authentication backend unavailable` — the API-key path
            could not reach the credential store.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: internal
                  message: authentication backend unavailable
        '502':
          description: >-
            The metadata cache answered with an unexpected status (`upstream` /
            `metadata cache request failed`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: upstream
                  message: metadata cache request failed
        '503':
          description: >-
            `cache_cold` — the provider's active-market listing has not been
            populated yet (`Retry-After: 5`); `unavailable` — not configured for
            this deployment; or `rate_limiter_unavailable`.
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    MarketListResponse:
      type: object
      description: Response body for GET /v1/markets.
      required:
        - exchange_id
        - markets
        - count
        - next_cursor
        - has_more
      properties:
        exchange_id:
          type: string
          example: kalshi
        markets:
          type: array
          items:
            $ref: '#/components/schemas/Market'
        count:
          type: integer
          description: Number of markets in this page (`markets.length`).
          example: 100
        next_cursor:
          type:
            - string
            - 'null'
          description: Opaque cursor for the next page, or null when this is the last page.
        has_more:
          type: boolean
    ErrorResponse:
      type: object
      description: Canonical error envelope emitted by every Market Data API endpoint.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Machine-readable error code.
              example: invalid_request
            message:
              type: string
              description: Human-readable detail.
              example: market_ids exceeds maximum 200
    Market:
      type: object
      description: >-
        Full market metadata document. Resolution-state fields
        (`resolution_status`, `payout_numerators`, `resolved_ts`,
        `proposed_price`, `challenge_window_ends_at`) are present in the payload
        only when set — the overwhelming majority of markets are unresolved and
        omit all five.
      required:
        - exchange_id
        - market_id
        - condition_id
        - event_id
        - title
        - neg_risk
        - outcomes
        - raw
      properties:
        exchange_id:
          type: string
          description: Canonical provider name.
          example: polymarket
        market_id:
          type: string
          example: '1897040'
        condition_id:
          type: string
          description: On-chain condition id for CTF venues; empty string for kalshi.
          example: 0xabc123...
        event_id:
          type: string
          description: Grouping event id (multi-market events); may be empty.
          example: evt-4521
        title:
          type: string
          example: Will BTC close above $120k on July 31?
        neg_risk:
          type: boolean
          description: Whether this market is part of a Polymarket negative-risk group.
          example: false
        tick_size:
          type:
            - number
            - 'null'
          description: Minimum price increment (0, 1) exclusive.
          example: 0.01
        taker_base_fee_bps:
          type:
            - integer
            - 'null'
          example: 200
        fees_enabled:
          type:
            - boolean
            - 'null'
        category:
          type:
            - string
            - 'null'
          example: Crypto
        group_slug:
          type:
            - string
            - 'null'
          example: btc-price-2026
        fee_type:
          type:
            - string
            - 'null'
          example: standard
        status:
          type:
            - string
            - 'null'
          description: >-
            Venue-reported market status, e.g. active/closed. Populated
            inconsistently across providers.
          example: active
        image:
          type:
            - string
            - 'null'
          description: Display image URL.
        icon:
          type:
            - string
            - 'null'
          description: Display icon URL.
        end_date:
          type:
            - string
            - 'null'
          description: ISO8601 UTC market end/close time.
          example: '2026-07-31T23:59:59Z'
        open_time:
          type:
            - string
            - 'null'
          description: ISO8601 UTC market open/listing time.
          example: '2026-01-01T00:00:00Z'
        resolution_status:
          type: string
          description: Present only when the market has resolution state.
          example: resolved
        payout_numerators:
          type: array
          items:
            type: integer
            format: uint64
          description: >-
            Present only when non-empty (i.e. the market has resolved with a
            payout vector).
          example:
            - 1
            - 0
        resolved_ts:
          type: string
          description: ISO8601 UTC. Present only when set.
          example: '2026-07-16T00:00:00Z'
        proposed_price:
          type: number
          description: Present only when set (a resolution price has been proposed).
          example: 1
        challenge_window_ends_at:
          type: string
          description: ISO8601 UTC. Present only when set.
          example: '2026-07-16T02:00:00Z'
        outcomes:
          type: array
          items:
            $ref: '#/components/schemas/MarketOutcome'
        raw:
          type: object
          description: >-
            Full, unmodified provider-specific market document. Shape varies by
            provider. Treat as opaque/pass-through.
    MarketOutcome:
      type: object
      description: One outcome/token entry within a market.
      required:
        - outcome
        - normalized_outcome
        - token_id
      properties:
        outcome:
          type: string
          description: >-
            Display-layer outcome label as provided by the venue. For kalshi,
            this can legitimately be duplicated across YES/NO (it's a
            team/threshold subtitle, not a binary identity) — use
            `outcome_index`/`side` for execution logic on those markets.
          example: 'Yes'
        normalized_outcome:
          type: string
          description: Lowercased/normalized form of `outcome`.
          example: 'yes'
        token_id:
          type: string
          description: Venue-specific outcome/token identifier.
          example: '18812649149814341758733697580460697418474693998558159483117'
        outcome_index:
          type: integer
          description: >-
            Stable binary position (0 or 1). Only present for providers keyed
            directly by market id (e.g. kalshi), and only for the first two
            outcome entries.
          example: 0
        side:
          type: string
          enum:
            - 'yes'
            - 'no'
          description: >-
            Stable binary side matching `outcome_index`. Same provider scope as
            `outcome_index`.
          example: 'yes'
  responses:
    Unauthorized:
      description: >
        No valid credential presented. Every path returns `code: unauthorized`;
        the triggers differ:


        - An `Authorization` header on a deployment where bearer auth is not
        enabled (`bearer authentication is not enabled`).

        - A bearer token that fails verification (`invalid or expired session`),
        or whose token/session has been revoked (`session has been revoked`).

        - An incomplete or wrong API-key header set. Sending *any* of
        `X-Client-Id`, `X-Api-Key`, `X-Api-Secret` commits the request to the
        API-key path, so a partial set is rejected rather than silently
        degrading to anonymous limits (`valid X-Client-Id, X-Api-Key, and
        X-Api-Secret headers are required`).

        - No credential material at all while the anonymous free tier is
        unavailable — switched off for the deployment, forced off through the
        runtime kill switch, or not yet resolvable on a replica that has never
        read the flag (it fails closed).
      headers:
        WWW-Authenticate:
          schema:
            type: string
          description: >-
            `Bearer realm="market-data-api"` on bearer-verification failure,
            `APIKey realm="market-data-api", header="X-Client-Id, X-Api-Key,
            X-Api-Secret"` on missing/invalid API-key credentials. Absent on the
            revoked-session and bearer-disabled paths.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: unauthorized
              message: >-
                valid X-Client-Id, X-Api-Key, and X-Api-Secret headers are
                required
    IPNotWhitelisted:
      description: API key presented from a source IP not in that credential's whitelist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: ip_not_whitelisted
              message: source IP not in credential whitelist
    RateLimited:
      description: >
        Two different gates return this status, both with `code: rate_limited`:


        - **Per-credential (or per-IP, when anonymous) weighted budget
        exhausted.** The message is `rate limit exceeded`, or, for anonymous
        callers, `anonymous rate limit exceeded — request an API key for higher
        limits (…)`. `Retry-After` is the whole number of seconds until the
        current one-minute window rolls over, floored at 1. All four
        `X-RateLimit-*` headers are present.

        - **Per-IP admission gate.** An in-process, pre-authentication guard
        that keeps a flood off the shared credential cache and database. The
        message is `too many requests from this address` and `Retry-After` is a
        flat `60`. Because this fires *before* authentication, the response
        carries **no** `X-RateLimit-*` headers at all.
      headers:
        Retry-After:
          schema:
            type: integer
          description: >-
            Seconds until the caller may retry — window-rollover seconds for the
            weighted limiter, a flat 60 for the IP admission gate.
        X-RateLimit-Bucket:
          schema:
            type: string
            enum:
              - light
              - heavy
        X-RateLimit-Tier:
          schema:
            type: string
            enum:
              - anonymous
              - api-key
              - user
        X-RateLimit-Remaining:
          schema:
            type: integer
        X-RateLimit-Reset:
          schema:
            type: integer
            description: Unix timestamp (seconds) when the current window resets.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: rate_limited
              message: rate limit exceeded
  securitySchemes:
    apiKeyClientId:
      type: apiKey
      in: header
      name: X-Client-Id
      description: >-
        Credential client id (`kairos_ck_...`). Must be sent together with
        X-Api-Key and X-Api-Secret.
    apiKeyKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: >-
        64-char hex API key. Must be sent together with X-Client-Id and
        X-Api-Secret.
    apiKeySecret:
      type: apiKey
      in: header
      name: X-Api-Secret
      description: >-
        64-char hex API secret. Must be sent together with X-Client-Id and
        X-Api-Key.

````

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