---
title: "Wallet-wide PnL totals across all markets"
method: GET
path: "/pnl/wallet-totals/{provider_id}/{wallet}"
tags: ["PnL"]
---

# Wallet-wide PnL totals across all markets

`GET /pnl/wallet-totals/{provider_id}/{wallet}`

## Request

- Base URL: `https://data.kairos.trade`
- URL: `https://data.kairos.trade/pnl/wallet-totals/{provider_id}/{wallet}`
- Auth: API key in header `X-Client-Id` and API key in header `X-Api-Key` and API key in header `X-Api-Secret`

Wallet-wide PnL totals aggregated across every market the wallet has touched, refreshed hourly — a fast point lookup rather than a live scan. For real-time per-market freshness on a single active market, use `/pnl/hover/{provider_id}/{wallet}/{contract_id}` instead. Same provider restriction as `/pnl/hover`: only `polymarket`, `opinion`, `predictfun` are accepted; `kalshi` and `hyperliquid` are rejected with 400 and must use `/pnl/{user_id}`. When the underlying pipeline is disabled, returns a well-formed zero payload (`market_count: 0`, `token_count: 0`, all dollar totals `0.0`, `snapshot_ts` set to the current time) instead of erroring. For API-key callers, the requested provider must additionally have its API access enabled.

## Path parameters

- `provider_id` 'polymarket' | 'opinion' | 'predictfun', required
- `wallet` string, required

## Response `200`

Wallet-wide PnL totals as of the last hourly snapshot. Returns a zeroed payload (not a 404) when the underlying PnL pipeline is disabled.

- PnlWalletTotalsResponse: Wallet-wide PnL totals across all markets, refreshed hourly. Returns a zeroed payload (`market_count: 0`, `token_count: 0`) instead of erroring when the underlying PnL pipeline is disabled.
  - `provider_id` 'polymarket' | 'opinion' | 'predictfun', required
  - `wallet_address` string, required
  - `total_unrealized_pnl_usd` number, double, required
  - `total_realized_pnl_usd` number, double, required
  - `total_position_value_usd` number, double, required
  - `total_cost_basis_usd` number, double, required
  - `market_count` integer, required
  - `token_count` integer, required
  - `snapshot_ts` string, date-time, required: ISO-8601 timestamp of the hourly snapshot this data was read from (or the current time when native_pnl_pipeline is disabled).

## Other responses

- `400`: Missing/oversized `wallet`, or `provider_id` is not a valid MV-pipeline provider (e.g. kalshi or hyperliquid).
- `401`: No valid credential presented — missing/invalid API-key headers, or an invalid/expired session token.
- `403`: API key missing `position:read` scope, or platform API access disabled for this provider.
- `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`: Unexpected error fetching wallet totals.
- `503`: Per-venue API-access flag could not be read or validated.

---

[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)