> ## 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. # Get a trader's realized-PnL time series > Returns a time-series of realized PnL data points for charting a trader's PnL progression over the requested window, bucketed by `time_range`. The wallet address is validated as either an Ethereum (0x...) address (Polymarket/Opinion/predictfun) or a Solana base58 address (Kalshi) and normalized (lower-cased for EVM) before lookup; if it matches neither format the request is rejected with 400. `provider` is optional — if omitted, the provider is auto-detected from the address format; pass it explicitly to disambiguate EVM venues other than Polymarket. Provider values are validated against the live set of active providers rather than a fixed enum, so an inactive/unknown id is rejected with 400. Responses are cacheable at the edge and briefly cached server-side. **Public endpoint — no authentication required.** Rate-limited per client IP (X-Forwarded-For, falling back to the socket peer) at 30 requests/minute, independent of the global 100/minute default. ## OpenAPI ````yaml /openapi/data-api.yaml get /trader-stats/pnl-history/{wallet_address} 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: /trader-stats/pnl-history/{wallet_address}: get: tags: - Trader Analytics summary: Get a trader's realized-PnL time series description: > Returns a time-series of realized PnL data points for charting a trader's PnL progression over the requested window, bucketed by `time_range`. The wallet address is validated as either an Ethereum (0x...) address (Polymarket/Opinion/predictfun) or a Solana base58 address (Kalshi) and normalized (lower-cased for EVM) before lookup; if it matches neither format the request is rejected with 400. `provider` is optional — if omitted, the provider is auto-detected from the address format; pass it explicitly to disambiguate EVM venues other than Polymarket. Provider values are validated against the live set of active providers rather than a fixed enum, so an inactive/unknown id is rejected with 400. Responses are cacheable at the edge and briefly cached server-side. **Public endpoint — no authentication required.** Rate-limited per client IP (X-Forwarded-For, falling back to the socket peer) at 30 requests/minute, independent of the global 100/minute default. operationId: getTraderPnlHistory parameters: - name: wallet_address in: path required: true schema: type: string description: > Ethereum (0x-prefixed, 42 chars) or Solana (base58) wallet address. Normalized (EVM lower-cased) before use. Returns 400 if it matches neither format. example: '0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b' - name: time_range in: query required: false schema: type: string enum: - 1D - 1W - 1M - ALL default: ALL description: Time window for the PnL series. - name: provider in: query required: false schema: type: string description: > Provider override (e.g. polymarket, kalshi, opinion, predictfun). Validated against the live active-provider registry. Auto-detected from address format when omitted. example: polymarket responses: '200': description: PnL time series for the wallet and time range. content: application/json: schema: $ref: '#/components/schemas/TraderPnlHistoryResponse' '400': description: Malformed wallet address or unrecognized provider. '422': $ref: '#/components/responses/DataValidationError' '429': $ref: '#/components/responses/DataRateLimited' '500': description: Unexpected error fetching PnL history. security: [] components: schemas: TraderPnlHistoryResponse: type: object description: > Time-series realized-PnL data for a wallet over a requested time range, plus a summary of the change over that range. required: - wallet_address - time_range - data_points - start_pnl - end_pnl - pnl_change - current_realized_pnl properties: wallet_address: type: string example: '0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b' time_range: type: string enum: - 1D - 1W - 1M - ALL example: 1W data_points: type: array items: $ref: '#/components/schemas/TraderPnlDataPoint' start_pnl: type: string format: decimal description: Realized PnL at the start of the window. example: '800.00' end_pnl: type: string format: decimal description: Realized PnL at the end of the window. example: '1250.4382' pnl_change: type: string format: decimal description: >- Absolute change in realized PnL over the window (end_pnl - start_pnl). example: '450.4382' pnl_change_percent: type: string format: decimal nullable: true description: >- Percentage change over the window; null if start_pnl is zero/undefined. example: '56.30' current_realized_pnl: type: string format: decimal description: >- Wallet's current total realized PnL (as of now, not bounded to the window). example: '1250.4382' current_total_pnl: type: string format: decimal nullable: true description: Current realized + unrealized PnL combined, when available. example: '1875.10' TraderPnlDataPoint: type: object description: Single point on a trader's realized-PnL time series. required: - timestamp - realized_pnl properties: timestamp: type: string format: date-time description: UTC timestamp of this data point. example: '2026-07-15T00:00:00Z' realized_pnl: type: string format: decimal description: >- Cumulative realized PnL (USD) at this point in time. Serialized as a decimal string. example: '1250.4382' 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.