> ## 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. # Active sports games with urgency scores and cross-provider prices > Returns active game IDs plus, when the provider indexing gate has `predictfun` enabled, open Predict.fun fixtures inside their scheduled start/end window. The gate is re-checked on every request (including cache hits); a gate lookup failure excludes Predict.fun (fail closed) without dropping Polymarket/Kalshi rows. Hydrates current state, drops ended games idle for more than a few minutes, and computes an `urgencyScore`/`stale` flag per game. Enriches each event with cached primary-market data, falling back to a live provider lookup when the cache is cold. Resolves each event's matching Polymarket/Kalshi slug and attaches the corresponding cross-venue match record into `matchingMarkets`. If no matched entry anywhere carries a Kalshi side, synthesizes one from a team-name-matching fallback lookup. Results are sorted by most-recent update, then by `urgencyScore` descending. Served from a shared server cache rebuilt about every 5 seconds while the endpoint is in use and never more than 60 seconds old; the `Age` header gives the seconds since the body was built. ## OpenAPI ````yaml /openapi/data-api.yaml get /sports/live-events 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/live-events: get: tags: - Sports summary: Active sports games with urgency scores and cross-provider prices description: >- Returns active game IDs plus, when the provider indexing gate has `predictfun` enabled, open Predict.fun fixtures inside their scheduled start/end window. The gate is re-checked on every request (including cache hits); a gate lookup failure excludes Predict.fun (fail closed) without dropping Polymarket/Kalshi rows. Hydrates current state, drops ended games idle for more than a few minutes, and computes an `urgencyScore`/`stale` flag per game. Enriches each event with cached primary-market data, falling back to a live provider lookup when the cache is cold. Resolves each event's matching Polymarket/Kalshi slug and attaches the corresponding cross-venue match record into `matchingMarkets`. If no matched entry anywhere carries a Kalshi side, synthesizes one from a team-name-matching fallback lookup. Results are sorted by most-recent update, then by `urgencyScore` descending. Served from a shared server cache rebuilt about every 5 seconds while the endpoint is in use and never more than 60 seconds old; the `Age` header gives the seconds since the body was built. operationId: getSportsLiveEvents parameters: - name: include_markets in: query required: false description: >- When true, includes the full markets list (not just the primary market) for every event. schema: type: boolean default: false example: false responses: '200': description: >- Active games ordered by recency then urgency, plus their matched cross-provider markets. headers: Cache-Control: schema: type: string example: public, max-age=10, s-maxage=10 content: application/json: schema: $ref: '#/components/schemas/SportsLiveEventsResponse' '422': $ref: '#/components/responses/DataValidationError' '429': $ref: '#/components/responses/DataRateLimited' security: [] components: schemas: SportsLiveEventsResponse: type: object required: - events - matchingMarkets properties: events: type: array items: $ref: '#/components/schemas/SportsLiveEvent' matchingMarkets: type: object description: >- Map keyed by matched slug, one entry per event that resolved a matchingSlug. additionalProperties: $ref: '#/components/schemas/SportsMatchingMarketEntry' SportsLiveEvent: type: object required: - gameId - sport - sportFamily - homeTeam - awayTeam - homeScore - awayScore - status - period - elapsed - live - ended - slug - matchingSlug - ts - urgencyScore - stale - primaryMarket - marketsCount - timing properties: timing: $ref: '#/components/schemas/SportsTiming' gameId: type: string example: '12345678' sport: type: string description: Lowercased league abbreviation. example: nba sportFamily: type: string description: Canonical category id from the sports catalog. example: basketball homeTeam: type: string example: Boston Celtics awayTeam: type: string example: Los Angeles Lakers homeScore: type: integer description: Series score if the game has one, else the game score. example: 88 awayScore: type: integer example: 91 status: type: string example: live period: type: - string - 'null' example: Q4 elapsed: description: >- Opaque provider clock string; direction, period resets, and overtime semantics are not verified. nullable: true example: '02:14' live: type: boolean ended: type: boolean slug: type: - string - 'null' example: nba-lal-bos-2026-01-15 matchingSlug: type: - string - 'null' description: Slug used as the key into matchingMarkets. example: nba-lal-bos-2026-01-15 ts: type: string format: date-time description: >- Game-state observation timestamp; source observation time when available, otherwise time received by Kairos. example: '2026-07-22T23:14:05Z' urgencyScore: type: integer description: >- Candidate-ranking heuristic for fresh games explicitly in play. Zero for stale, stopped, ended, unknown-status, and schedule-only games. Not a remaining-time signal. example: 160 stale: type: boolean description: >- True for state older than 120 seconds, invalid or future timestamps, timestamps without a timezone, or absence of a live score feed. Evaluated at timing.evaluatedAt. primaryMarket: oneOf: - $ref: '#/components/schemas/SportsNormalizedMarket' - type: 'null' marketsCount: type: integer example: 6 markets: type: array description: Present only when include_markets=true. items: $ref: '#/components/schemas/SportsNormalizedMarket' SportsMatchingMarketEntry: type: object description: Raw contents of a cached cross-venue sports market match entry. required: - providers properties: title: type: string example: Lakers vs Celtics tokenId: type: string description: Polymarket CLOB token id for the primary market side. example: 10897234... providers: type: array items: $ref: '#/components/schemas/SportsMatchingProvider' SportsTiming: type: object description: >- Conservative timing evidence. Polymarket elapsed is not normalized to remaining time. Predict.fun schedule windows do not establish live score freshness. Consumers must age stateAgeSeconds from evaluatedAt because responses can be cached. required: - source - status - clock - clockDirection - clockRunning - periodRemainingSeconds - gameRemainingSeconds - overtime - stateAgeSeconds - evaluatedAt - staleAfterSeconds - stale - usableForLateGame - unavailableReason properties: source: type: string enum: - polymarket - predictfun status: type: string enum: - scheduled - live - break - overtime - shootout - suspended - delayed - postponed - cancelled - final - unknown clock: type: - string - 'null' clockDirection: type: string enum: - unknown clockRunning: type: - boolean - 'null' description: Currently null; running state is not established. periodRemainingSeconds: type: - number - 'null' description: >- Currently null; do not derive this from elapsed without verified clock semantics. gameRemainingSeconds: type: - number - 'null' description: >- Currently null; overtime and eventual completion cannot be inferred from regulation time. overtime: type: - boolean - 'null' description: >- True for explicit OT or extra-time evidence, false for regulation final FT, otherwise null. Completion after overtime is not active overtime. stateAgeSeconds: type: - number - 'null' minimum: 0 evaluatedAt: type: string format: date-time staleAfterSeconds: type: integer const: 120 stale: type: boolean usableForLateGame: type: boolean const: false description: >- No authoritative countdown is currently available from these sources. unavailableReason: type: string enum: - unknown_clock_semantics - missing_clock - game_not_in_play - stale_state - invalid_timestamp - no_live_score_feed SportsNormalizedMarket: type: object description: >- Upstream market normalized into a common shape used across the live-events, event-markets, and upcoming-events endpoints. required: - id - question - slug - conditionId - tokenId - outcomePrices - outcomes - volumeNum - liquidityNum - acceptingOrders - sportsMarketType - groupItemTitle - bestBid - bestAsk - spread - provider - image - icon properties: id: type: string example: '587234' question: type: string example: Will the Celtics win? slug: type: string example: nba-lal-bos-2026-01-15-bos conditionId: type: string example: 0xabc123... tokenId: type: string description: First clobTokenId for the market. example: 10897234... outcomePrices: type: array items: type: number format: double example: - 0.6 - 0.4 outcomes: type: array items: type: string example: - 'Yes' - 'No' volumeNum: type: number format: double example: 128432.1 liquidityNum: type: number format: double example: 42311 acceptingOrders: type: boolean sportsMarketType: type: - string - 'null' example: moneyline groupItemTitle: type: - string - 'null' example: Celtics gameStartTime: type: - string - 'null' format: date-time description: >- Scheduled fixture kickoff used for cross-provider live-game matching. bestBid: type: - number - 'null' format: double example: 0.59 bestAsk: type: - number - 'null' format: double example: 0.61 spread: type: - number - 'null' format: double example: 0.02 provider: type: string example: polymarket image: type: - string - 'null' icon: type: - string - 'null' outcomeMarketIds: type: array description: >- Only present on 3-way (soccer moneyline) composite markets. Length 3, [home, draw, away]. items: type: - string - 'null' example: - '587234' - '587235' - '587236' outcomeTokenIds: type: array description: Per-outcome token IDs in the same order as outcomes, when available. items: type: - string - 'null' outcomeConditionIds: type: array description: Only present on 3-way composite markets. items: type: - string - 'null' SportsMatchingProvider: type: object required: - provider - marketId - price properties: provider: type: string enum: - polymarket - kalshi - predictfun marketId: type: string example: KXNBAGAME-26JAN15LALBOS-LAL price: type: number format: double nullable: true description: 0-1 scale probability/price. example: 0.6 eventTicker: type: string nullable: true description: Kalshi event ticker. Present only on kalshi provider entries. example: KXNBAGAME-26JAN15LALBOS volume: type: number format: double nullable: true teamPrices: type: array description: Per-team YES markets for providers that split 3-way moneylines. items: type: object required: - name - marketId - price properties: name: type: string marketId: type: string price: type: number format: double nullable: true drawMarketId: type: string nullable: true drawPrice: type: number format: double nullable: true homeMarketId: type: string nullable: true homePrice: type: number format: double nullable: true awayMarketId: type: string nullable: true awayPrice: type: number format: double nullable: true responses: DataValidationError: description: Request failed FastAPI parameter validation. content: application/json: schema: type: object required: - detail properties: detail: type: array description: >- One entry per failed field, with location, message, and error type. items: type: object additionalProperties: true 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.