---
title: "Get a trader's realized-PnL time series"
method: GET
path: "/trader-stats/pnl-history/{wallet_address}"
tags: ["Trader Analytics"]
---

# Get a trader's realized-PnL time series

`GET /trader-stats/pnl-history/{wallet_address}`

## Request

- Base URL: `https://data.kairos.trade`
- URL: `https://data.kairos.trade/trader-stats/pnl-history/{wallet_address}`
- Auth: none required

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.

## Path parameters

- `wallet_address` string, required

## Query parameters

- `time_range` '1D' | '1W' | '1M' | 'ALL'
- `provider` string

## Response `200`

PnL time series for the wallet and time range.

- TraderPnlHistoryResponse: Time-series realized-PnL data for a wallet over a requested time range, plus a summary of the change over that range.
  - `wallet_address` string, required
  - `time_range` '1D' | '1W' | '1M' | 'ALL', required
  - `data_points` TraderPnlDataPoint[], required
    - `timestamp` string, date-time, required: UTC timestamp of this data point.
    - `realized_pnl` string, decimal, required: Cumulative realized PnL (USD) at this point in time. Serialized as a decimal string.
  - `start_pnl` string, decimal, required: Realized PnL at the start of the window.
  - `end_pnl` string, decimal, required: Realized PnL at the end of the window.
  - `pnl_change` string, decimal, required: Absolute change in realized PnL over the window (end_pnl - start_pnl).
  - `pnl_change_percent` string, decimal, nullable: Percentage change over the window; null if start_pnl is zero/undefined.
  - `current_realized_pnl` string, decimal, required: Wallet's current total realized PnL (as of now, not bounded to the window).
  - `current_total_pnl` string, decimal, nullable: Current realized + unrealized PnL combined, when available.

## Other responses

- `400`: Malformed wallet address or unrecognized 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 PnL history.

---

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