> ## 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. # Batch public wallet identities and market position summaries > Summaries for up to 50 holding wallets on Polymarket or Predict. Names are venue-scoped and enriched asynchronously. Decimal monetary amounts are USD strings; null means unavailable. PnL covers indexed market activity and does not certify completeness. as_of is the oldest position-row write time, not a producer watermark. Exact positive inventory, including dust, remains open. PnL includes realized results from closed positions, and is unavailable for open inventory with missing or older-than-five-minute marks. Size tiers use remaining purchase cost, independently of marked value; their initial thresholds are provisional. Allocator FIFO results include share-denominated buy fees in inventory cost but exclude separately charged collateral fees and gas; they are not net-of-all-costs returns. Token balances are shares and mark_price is USD per share. The existing native PnL pipeline control also applies; when disabled, only identity enrichment is returned. include_details requires one wallet. Transient lookup failures are distinct from anonymous profiles. ## OpenAPI ````yaml /openapi/data-api.yaml post /pnl/market-wallets 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://docs.kairos.trade/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/market-wallets: post: tags: - PnL summary: Batch public wallet identities and market position summaries description: >- Summaries for up to 50 holding wallets on Polymarket or Predict. Names are venue-scoped and enriched asynchronously. Decimal monetary amounts are USD strings; null means unavailable. PnL covers indexed market activity and does not certify completeness. as_of is the oldest position-row write time, not a producer watermark. Exact positive inventory, including dust, remains open. PnL includes realized results from closed positions, and is unavailable for open inventory with missing or older-than-five-minute marks. Size tiers use remaining purchase cost, independently of marked value; their initial thresholds are provisional. Allocator FIFO results include share-denominated buy fees in inventory cost but exclude separately charged collateral fees and gas; they are not net-of-all-costs returns. Token balances are shares and mark_price is USD per share. The existing native PnL pipeline control also applies; when disabled, only identity enrichment is returned. include_details requires one wallet. Transient lookup failures are distinct from anonymous profiles. operationId: getMarketWalletSummaries requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TradeWalletSummaryRequest' responses: '200': description: >- Per-wallet summaries; unavailable data is explicit, never inferred as zero. content: application/json: schema: $ref: '#/components/schemas/TradeWalletSummaryResponse' '400': description: Details requested for more than one wallet. '403': description: API key scope or venue API access denied. '422': $ref: '#/components/responses/DataValidationError' '429': $ref: '#/components/responses/DataRateLimited' '500': description: Position detail query failed. '503': description: Venue access could not be verified. security: [] components: schemas: TradeWalletSummaryRequest: properties: provider: enum: - polymarket - predictfun title: Provider type: string market_id: maxLength: 128 minLength: 1 title: Market Id type: string wallets: items: type: string maxItems: 50 minItems: 1 title: Wallets type: array include_details: default: false title: Include Details type: boolean required: - provider - market_id - wallets title: SummaryRequest type: object TradeWalletSummaryResponse: properties: provider: enum: - polymarket - predictfun title: Provider type: string market_id: title: Market Id type: string wallets: items: $ref: '#/components/schemas/TradeWalletSummary' title: Wallets type: array tokens: items: $ref: '#/components/schemas/TradeWalletTokenDetail' title: Tokens type: array required: - provider - market_id - wallets title: SummaryResponse type: object TradeWalletSummary: properties: wallet: title: Wallet type: string display_name: anyOf: - type: string - type: 'null' default: null title: Display Name profile_status: default: pending enum: - ready - anonymous - pending - unavailable title: Profile Status type: string position_status: default: unknown enum: - open - closed - awaiting_settlement - unknown - unavailable title: Position Status type: string pnl_status: default: unavailable enum: - ready - unavailable title: Pnl Status type: string pnl_color: default: neutral enum: - positive - negative - neutral title: Pnl Color type: string realized_pnl_usd: anyOf: - type: string - type: 'null' default: null title: Realized Pnl Usd unrealized_pnl_usd: anyOf: - type: string - type: 'null' default: null title: Unrealized Pnl Usd total_pnl_usd: anyOf: - type: string - type: 'null' default: null title: Total Pnl Usd open_cost_basis_usd: anyOf: - type: string - type: 'null' default: null title: Open Cost Basis Usd position_value_usd: anyOf: - type: string - type: 'null' default: null title: Position Value Usd tier: anyOf: - enum: - plankton - shrimp - fish - shark - whale type: string - type: 'null' default: null title: Tier as_of: anyOf: - type: string - type: 'null' default: null title: As Of mark_as_of: anyOf: - type: string - type: 'null' default: null title: Mark As Of coverage: default: unknown enum: - indexed - unknown title: Coverage type: string required: - wallet title: WalletSummary type: object TradeWalletTokenDetail: properties: token_id: title: Token Id type: string outcome: default: '' title: Outcome type: string balance: title: Balance type: string cost_basis_usd: title: Cost Basis Usd type: string realized_pnl_usd: title: Realized Pnl Usd type: string mark_price: anyOf: - type: string - type: 'null' title: Mark Price required: - token_id - balance - cost_basis_usd - realized_pnl_usd - mark_price title: TokenDetail type: object 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.