> ## 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. # Live per-market PnL for a (wallet, market) pair > Live "hover" PnL for a single wallet on a single market, sourced from a fast real-time pipeline — quick regardless of how far back the wallet's earliest trade goes. Returns one row per token held on the contract (e.g. YES + NO for a binary market) plus aggregate totals across those tokens. Only providers on this pipeline are supported: `polymarket`, `opinion`, `predictfun`; `kalshi` and `hyperliquid` are rejected with 400 and must use `/pnl/{user_id}`. When the underlying pipeline is disabled (e.g. while a backfill is ramping), the endpoint returns a well-formed zero/empty payload (`tokens: []`, all totals `0.0`) instead of erroring, matching the "no data" state the frontend already renders gracefully. For API-key callers, the requested provider must additionally have its API access enabled. ## OpenAPI ````yaml /openapi/data-api.yaml get /pnl/hover/{provider_id}/{wallet}/{contract_id} 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: /pnl/hover/{provider_id}/{wallet}/{contract_id}: get: tags: - PnL summary: Live per-market PnL for a (wallet, market) pair description: > Live "hover" PnL for a single wallet on a single market, sourced from a fast real-time pipeline — quick regardless of how far back the wallet's earliest trade goes. Returns one row per token held on the contract (e.g. YES + NO for a binary market) plus aggregate totals across those tokens. Only providers on this pipeline are supported: `polymarket`, `opinion`, `predictfun`; `kalshi` and `hyperliquid` are rejected with 400 and must use `/pnl/{user_id}`. When the underlying pipeline is disabled (e.g. while a backfill is ramping), the endpoint returns a well-formed zero/empty payload (`tokens: []`, all totals `0.0`) instead of erroring, matching the "no data" state the frontend already renders gracefully. For API-key callers, the requested provider must additionally have its API access enabled. operationId: getWalletMarketPnl parameters: - name: provider_id in: path required: true schema: type: string maxLength: 32 enum: - polymarket - opinion - predictfun description: >- MV-pipeline provider id. `kalshi`, `hyperliquid`, and any other registered-but-non-MV provider are rejected with 400. example: polymarket - name: wallet in: path required: true schema: type: string maxLength: 128 description: >- Wallet address (opaque string; trimmed, length-checked — not format-validated at this layer). example: '0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b' - name: contract_id in: path required: true schema: type: string maxLength: 128 description: Market/condition (contract) id. example: 0xabc123condition responses: '200': description: > Per-token PnL rows and aggregate totals for the wallet on this market. Returns an empty/zeroed payload (not a 404) when the underlying PnL pipeline is disabled. content: application/json: schema: $ref: '#/components/schemas/PnlWalletMarketPnlResponse' '400': description: >- Missing/oversized `wallet`/`contract_id`, or `provider_id` is not a valid MV-pipeline provider (e.g. kalshi or hyperliquid). '401': $ref: '#/components/responses/DataUnauthorized' '403': description: >- API key missing `position:read` scope, or platform API access disabled for this provider. '422': $ref: '#/components/responses/DataValidationError' '429': $ref: '#/components/responses/DataRateLimited' '500': description: Unexpected error fetching hover PnL. '503': description: Per-venue API-access flag could not be read or validated. content: application/json: schema: $ref: '#/components/schemas/DataError' components: schemas: PnlWalletMarketPnlResponse: type: object description: > Live hover-on-wallet PnL for a single (wallet, market) pair. Returns a zeroed/empty payload (`tokens: []`) instead of erroring when the underlying PnL pipeline is disabled. required: - provider_id - wallet_address - contract_id - tokens - total_unrealized_pnl_usd - total_realized_pnl_usd - total_position_value_usd properties: provider_id: type: string enum: - polymarket - opinion - predictfun example: polymarket wallet_address: type: string example: '0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b' contract_id: type: string example: 0xabc123condition tokens: type: array items: $ref: '#/components/schemas/PnlWalletMarketTokenPnL' total_unrealized_pnl_usd: type: number format: double example: 19.5 total_realized_pnl_usd: type: number format: double example: 0 total_position_value_usd: type: number format: double example: 82.5 DataError: type: object description: Handler error envelope (FastAPI HTTPException). required: - detail properties: detail: type: string description: Human-readable error message. example: Invalid provider PnlWalletMarketTokenPnL: type: object description: Per-token PnL row within a wallet/market hover payload. required: - token_id - outcome - balance - avg_entry_price - cost_basis_usd - realized_pnl_usd - mark_price - position_value_usd - unrealized_pnl_usd properties: token_id: type: string example: 10723948572...4 outcome: type: string example: 'YES' balance: type: number format: double example: 150 avg_entry_price: type: number format: double example: 0.42 cost_basis_usd: type: number format: double example: 63 realized_pnl_usd: type: number format: double example: 0 mark_price: type: number format: double example: 0.55 position_value_usd: type: number format: double example: 82.5 unrealized_pnl_usd: type: number format: double example: 19.5 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.