> ## 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. # Season/tournament futures markets across sports > Returns futures-style (non-per-game) sports markets for providers Polymarket and Predict.fun (open/active status only). Per-match/per-game rows are excluded; each event is classified into a (category, league) pair from a large token/phrase table, falling back to an "other" bucket, and titles that look like props/game lines/drafts or, for the "other" bucket only, non-sport mis-tags are dropped. Each event is capped at 30 outcomes (highest-priced first, unpriced sink to the bottom); the "other" bucket is additionally capped at 150 events (richest-first); recognized-sport events are uncapped. Results are sorted by market count descending. Responses are served from a cache kept warm in the background. With no parameters the whole list is returned; `mode`, `category`, `providers` and `q` filter it, and `limit` switches to pages carrying `total` and `nextOffset`. ## OpenAPI ````yaml /openapi/data-api.yaml get /sports/futures openapi: 3.1.0 info: title: Kairos Data API version: 1.0.0 summary: >- The full Kairos data plane — markets, candles, trades, search, discover, sports, trader analytics, and PnL. description: | The Kairos Data API at `data.kairos.trade` is the platform's primary data plane: market metadata and prices, OHLCV candles, live venue trade proxies, normalized trade history, full-text search, discovery feeds, the sports catalog, public trader analytics, and account PnL. ## Authentication Most endpoints accept a Kairos **API key** (`X-Client-Id` + `X-Api-Key` + `X-Api-Secret`, all three) or a first-party session JWT. Endpoints tagged `public` (trader analytics, provider configs, several sports feeds) need no credentials at all. Some endpoints additionally require an API-key **scope** (`trade:read`, `position:read`) — stated per operation. For high-volume market-data consumption (candles/trades/metadata at scale), prefer the dedicated **Market Data API** at `md.kairos.trade` — it has higher budgets, ETag caching, and a binary candle format. ## Rate limits Rate limits use a sliding window keyed on the authenticated user (JWT `sub`) or, for anonymous callers, the trusted client IP. Routes belong to a named **bucket** (`x-kairos-bucket`) whose per-minute budget is shared by every route in it; routes with no bucket run under the service default of 100/minute. `x-kairos-rate-limit` states the bucket's compile-time default — operators can raise or lower a bucket at runtime, so treat the documented number as the baseline, not a contract. 429 responses carry `Retry-After` and `X-RateLimit-*`. ## Conventions - Prices are on the **0–100 cents scale** unless a field says otherwise (trader-analytics position/trade prices use the 0–1 scale; each field's description states its scale). - Errors: `{"detail": ""}` for handler errors; FastAPI's standard validation envelope for 422s. Errors surfaced from a venue adapter instead use `{"error", "provider", "operation", "message"}` — see `DataProviderError`. Unhandled failures always return the generic 500 body; internal details are logged, never returned. - Every request body is capped at 8 MiB service-wide (413). contact: name: Kairos url: https://app.kairos.trade/docs/api-reference termsOfService: https://kairos.trade/terms servers: - url: https://data.kairos.trade description: Production - url: https://staging-data.kairos.trade description: Staging security: - apiKeyClientId: [] apiKeyKey: [] apiKeySecret: [] paths: /sports/futures: get: tags: - Sports summary: Season/tournament futures markets across sports description: >- Returns futures-style (non-per-game) sports markets for providers Polymarket and Predict.fun (open/active status only). Per-match/per-game rows are excluded; each event is classified into a (category, league) pair from a large token/phrase table, falling back to an "other" bucket, and titles that look like props/game lines/drafts or, for the "other" bucket only, non-sport mis-tags are dropped. Each event is capped at 30 outcomes (highest-priced first, unpriced sink to the bottom); the "other" bucket is additionally capped at 150 events (richest-first); recognized-sport events are uncapped. Results are sorted by market count descending. Responses are served from a cache kept warm in the background. With no parameters the whole list is returned; `mode`, `category`, `providers` and `q` filter it, and `limit` switches to pages carrying `total` and `nextOffset`. operationId: getSportsFutures parameters: - name: mode in: query required: false description: >- `sports` leaves out esports and the "other" bucket unless `category` names one; `esports` keeps only esports futures and filters `category` by title. schema: type: string enum: - sports - esports - name: category in: query required: false description: >- `all`, a catalog category id (e.g. `basketball`, `other`), or with `mode=esports` an esports title slug or `__esports_other` for titles outside the catalog. schema: type: string maxLength: 64 default: all - name: providers in: query required: false description: >- Comma-separated provider names to keep (e.g. `polymarket,predictfun`). schema: type: string maxLength: 200 - name: q in: query required: false description: >- Space-separated terms that must all appear in the event title or a contender label. schema: type: string maxLength: 200 - name: offset in: query required: false description: >- Position in the filtered list to start from; use the previous page's `nextOffset`. schema: type: integer minimum: 0 default: 0 - name: limit in: query required: false description: Page size. When set, the response carries `total` and `nextOffset`. schema: type: integer minimum: 1 maximum: 100 responses: '200': description: >- Futures/outright markets grouped by event, each with its priced outcomes. headers: Cache-Control: schema: type: string example: public, max-age=60, s-maxage=300 content: application/json: schema: $ref: '#/components/schemas/SportsFuturesResponse' '429': $ref: '#/components/responses/DataRateLimited' security: [] components: schemas: SportsFuturesResponse: type: object required: - futures properties: futures: type: array items: $ref: '#/components/schemas/SportsFuturesEvent' total: type: integer description: >- Futures matching the filters across every page. Present only when `limit` is set. nextOffset: type: integer nullable: true description: >- `offset` for the next page, or null on the last. Present only when `limit` is set. SportsFuturesEvent: type: object required: - eventId - title - image - sport - sportFamily - league - provider - volume - outcomes - marketsCount properties: eventId: type: string example: '10088234' title: type: string example: Super Bowl LX Winner image: type: - string - 'null' sport: type: string description: >- Sports-catalog category id, or "other" if not classified into a known sport. example: football sportFamily: type: string description: >- Canonical category id from the sports catalog; equal to sport on this route. example: football league: type: - string - 'null' example: nfl provider: type: string enum: - polymarket - predictfun volume: type: number format: double description: >- Sum of contender market volumes. Always 0 for predictfun legs (no volume field upstream). example: 842311 outcomes: type: array description: >- Capped at 30 outcomes per event, highest-priced first with unpriced outcomes sunk to the bottom. items: $ref: '#/components/schemas/SportsFuturesOutcome' marketsCount: type: integer description: Equal to len(outcomes) after capping. example: 32 SportsFuturesOutcome: type: object required: - label - price - marketId - tokenId - conditionId properties: label: type: string example: Kansas City Chiefs price: type: - number - 'null' format: double example: 0.18 marketId: type: string example: '10088235' tokenId: type: - string - 'null' conditionId: type: - string - 'null' responses: DataRateLimited: description: > Rate limit exceeded for this route's sliding window, keyed on the session `sub` when authenticated and on the trusted client IP otherwise. Honor `Retry-After`. A per-API-key data ceiling (set per credential) rejects with `{"detail": "API key data rate limit exceeded"}` instead of the `error` envelope below. headers: Retry-After: schema: type: integer X-RateLimit-Limit: schema: type: integer X-RateLimit-Remaining: schema: type: integer X-RateLimit-Reset: schema: type: integer content: application/json: schema: type: object properties: error: type: string example: 'Rate limit exceeded: 100 per 1 minute' 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. apiKeySecret: type: apiKey in: header name: X-Api-Secret description: 64-char hex API secret. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.