---
title: "Batch public wallet identities and market position summaries"
method: POST
path: "/pnl/market-wallets"
tags: ["PnL"]
---

# Batch public wallet identities and market position summaries

`POST /pnl/market-wallets`

## Request

- Base URL: `https://data.kairos.trade`
- URL: `https://data.kairos.trade/pnl/market-wallets`
- Auth: none required

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.

## Request body

- TradeWalletSummaryRequest
  - `provider` 'polymarket' | 'predictfun', required
  - `market_id` string, required
  - `wallets` string[], required
  - `include_details` boolean

## Response `200`

Per-wallet summaries; unavailable data is explicit, never inferred as zero.

- TradeWalletSummaryResponse
  - `provider` 'polymarket' | 'predictfun', required
  - `market_id` string, required
  - `wallets` TradeWalletSummary[], required
    - `wallet` string, required
    - `display_name` string, nullable
    - `profile_status` 'ready' | 'anonymous' | 'pending' | 'unavailable'
    - `position_status` 'open' | 'closed' | 'awaiting_settlement' | 'unknown' | 'unavailable'
    - `pnl_status` 'ready' | 'unavailable'
    - `pnl_color` 'positive' | 'negative' | 'neutral'
    - `realized_pnl_usd` string, nullable
    - `unrealized_pnl_usd` string, nullable
    - `total_pnl_usd` string, nullable
    - `open_cost_basis_usd` string, nullable
    - `position_value_usd` string, nullable
    - `tier` 'plankton' | 'shrimp' | 'fish' | 'shark' | 'whale', nullable
    - `as_of` string, nullable
    - `mark_as_of` string, nullable
    - `coverage` 'indexed' | 'unknown'
  - `tokens` TradeWalletTokenDetail[]
    - `token_id` string, required
    - `outcome` string
    - `balance` string, required
    - `cost_basis_usd` string, required
    - `realized_pnl_usd` string, required
    - `mark_price` string, nullable, required

## Other responses

- `400`: Details requested for more than one wallet.
- `403`: API key scope or venue API access denied.
- `422`: Request failed FastAPI parameter validation.
- `429`: 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.
- `500`: Position detail query failed.
- `503`: Venue access could not be verified.

---

[API](https://skmtc.dev/kairos/apis/kairos-data-api.md) - [All operations](https://skmtc.dev/kairos/apis/kairos-data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/kairos/apis/kairos-data-api/revisions/cf6b76079e38?raw)