> ## 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. # Proxy Polymarket's public trade-history API for one market > Thin proxy over Polymarket's `GET https://data-api.polymarket.com/trades`, with a short-lived cache and Kairos-computed metrics appended. **Auth**: identical model to `/trades/kalshi` — requires the `trade:read` scope (admin/JWT bypass the scope check; API keys need `trade:read`), plus API access to the `polymarket` platform being enabled for API-key callers (403 if disabled). **Market resolution**: `market` may be a `0x`-prefixed condition ID (used as-is) or a market/token identifier that is resolved to a condition ID via a cached metadata lookup, then a direct database lookup, and finally a live Polymarket API lookup as a last resort. If resolution never yields a value starting with `0x`, the endpoint short-circuits and returns `{"trades": [], "metrics": {}}` **without** calling the upstream trades API. **Cache / data source**: responses are cached briefly to de-duplicate bursts of identical requests. On a miss, calls the Polymarket Data API with the resolved `condition_id` as `market`. A non-2xx/network error returns 502. **Response shape**: `trades` is the raw upstream trade array (client-side re-filtered by `after` against each trade's `timestamp` as a safety net). `metrics` is computed over the filtered trades with a metrics window fixed at 24 hours; it groups trade value by outcome identifier (`asset_id`/`outcome`/`token_id`) and keeps only the top 2 outcomes by volume as an approximate outcome_0/outcome_1 split — this is an approximation, not a guaranteed yes/no mapping. ## OpenAPI ````yaml /openapi/data-api.yaml get /trades/polymarket 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: /trades/polymarket: get: tags: - Trades summary: Proxy Polymarket's public trade-history API for one market description: > Thin proxy over Polymarket's `GET https://data-api.polymarket.com/trades`, with a short-lived cache and Kairos-computed metrics appended. **Auth**: identical model to `/trades/kalshi` — requires the `trade:read` scope (admin/JWT bypass the scope check; API keys need `trade:read`), plus API access to the `polymarket` platform being enabled for API-key callers (403 if disabled). **Market resolution**: `market` may be a `0x`-prefixed condition ID (used as-is) or a market/token identifier that is resolved to a condition ID via a cached metadata lookup, then a direct database lookup, and finally a live Polymarket API lookup as a last resort. If resolution never yields a value starting with `0x`, the endpoint short-circuits and returns `{"trades": [], "metrics": {}}` **without** calling the upstream trades API. **Cache / data source**: responses are cached briefly to de-duplicate bursts of identical requests. On a miss, calls the Polymarket Data API with the resolved `condition_id` as `market`. A non-2xx/network error returns 502. **Response shape**: `trades` is the raw upstream trade array (client-side re-filtered by `after` against each trade's `timestamp` as a safety net). `metrics` is computed over the filtered trades with a metrics window fixed at 24 hours; it groups trade value by outcome identifier (`asset_id`/`outcome`/`token_id`) and keeps only the top 2 outcomes by volume as an approximate outcome_0/outcome_1 split — this is an approximation, not a guaranteed yes/no mapping. operationId: getPolymarketTrades parameters: - name: market in: query required: true schema: type: string minLength: 1 maxLength: 128 description: > Polymarket condition ID (`0x...`), market ID, or token ID. Non-`0x` values are resolved to a condition ID before querying upstream. Empty or >128 chars returns 400. example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd' - name: after in: query required: false schema: type: integer nullable: true description: >- Inclusive lower bound, Unix seconds. Passed to upstream and re-applied client-side against each trade's `timestamp`. - name: before in: query required: false schema: type: integer nullable: true description: Inclusive upper bound, Unix seconds, passed to the upstream API. - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 500 default: 100 description: Max trades returned, passed through to the upstream Polymarket API. responses: '200': description: > Raw Polymarket trades plus computed `metrics`. `metrics` is `{}` when the `market` value could not be resolved to a condition ID (no upstream call was made). content: application/json: schema: $ref: '#/components/schemas/TradesPolymarketResponse' '400': description: Missing/empty `market`. content: application/json: schema: type: object properties: detail: type: string '401': $ref: '#/components/responses/DataUnauthorized' '403': description: >- API-key credential lacks the `trade:read` scope, or API access to the `polymarket` platform is currently disabled. content: application/json: schema: type: object properties: detail: type: string '422': $ref: '#/components/responses/DataValidationError' '429': $ref: '#/components/responses/DataRateLimited' '502': description: >- Polymarket's upstream trade-history API returned an error or was unreachable. content: application/json: schema: type: object properties: detail: type: string example: Polymarket API error '503': description: Per-venue API-access flag could not be read or validated. content: application/json: schema: $ref: '#/components/schemas/DataError' components: schemas: TradesPolymarketResponse: type: object required: - trades - metrics properties: trades: type: array items: $ref: '#/components/schemas/TradesPolymarketRawTrade' metrics: type: object additionalProperties: true description: > A `TradesMetrics` object in the normal case. When `market` could not be resolved to a condition ID, this is a literal empty object `{}` and `trades` is `[]` — no upstream call was made. DataError: type: object description: Handler error envelope (FastAPI HTTPException). required: - detail properties: detail: type: string description: Human-readable error message. example: Invalid provider TradesPolymarketRawTrade: type: object description: > Raw trade object as returned by Polymarket's `GET https://data-api.polymarket.com/trades`, passed through unmodified. additionalProperties: true properties: proxyWallet: type: string side: type: string enum: - BUY - SELL asset: type: string description: Outcome token id. conditionId: type: string size: type: number price: type: number description: >- Upstream price, 0-1 decimal scale (not the 0-100 scale Kairos normalizes to elsewhere). timestamp: type: integer description: Unix seconds. transactionHash: type: string outcome: type: string responses: DataUnauthorized: description: > No valid credential presented — missing/invalid API-key headers, or an invalid/expired session token. content: application/json: schema: $ref: '#/components/schemas/DataError' example: detail: Not authenticated 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.