---
title: "Get a trader's open/closed positions and derived performance stats"
method: GET
path: "/trader-stats/positions/{wallet_address}"
tags: ["Trader Analytics"]
---

# Get a trader's open/closed positions and derived performance stats

`GET /trader-stats/positions/{wallet_address}`

## Request

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

Returns a trader's positions plus performance metrics computed from a full-inventory scan — served independently of the unified profile so the Positions tab and stats panel can load on their own fetch. Positions are filtered by `status` (open/closed/all), sorted by current value (largest first), and paginated via `limit`/`offset`; `has_more` indicates another page exists in the filtered set. Market names/icons are resolved only for the returned page, so wallets holding a very large number of positions don't blow past internal query limits. `performance` (win rate, total PnL, volume, positions_value, etc.) is always computed over the wallet's FULL inventory, not just the returned page. `include_redeemable` additionally includes resolved positions still awaiting on-chain redemption. **Public endpoint — no authentication required** (trader data is public). Rate-limited per client IP at 30 requests/minute. Responses are cacheable at the edge.

## Path parameters

- `wallet_address` string, required

## Query parameters

- `include_redeemable` boolean
- `provider` string
- `limit` integer
- `offset` integer
- `status` 'all' | 'open' | 'closed'

## Response `200`

Positions page plus full-inventory performance stats.

- TraderPositionsResponse: A page of a wallet's positions plus performance stats derived from the full inventory in the same scan.
  - `wallet_address` string, required
  - `performance` TraderPerformance, required: Aggregated trader performance metrics, always computed over the full inventory (not a paginated page).
    - `wallet_address` string, required
    - `total_realized_pnl` string, decimal, required
    - `total_unrealized_pnl` string, decimal, required
    - `total_pnl` string, decimal, required
    - `roi_percent` string, decimal
    - `open_positions` integer, required
    - `closed_positions` integer, required
    - `total_positions` integer, required
    - `positions_value` string, decimal: Cost basis (deployed capital) of OPEN positions, summed over the full inventory.
    - `winning_positions` integer, required
    - `losing_positions` integer, required
    - `win_rate` number, double, required: Win rate over closed, resolved positions.
    - `total_volume` string, decimal, required
    - `markets_traded` integer, required
    - `join_date` string, date-time, nullable: Polymarket account join date, when known.
    - `profile_views` integer
    - `largest_win` string, decimal, nullable
    - `last_updated` string, date-time, required
  - `open_positions` TraderPosition[], required
    - `market_id` string, required
    - `market_name` string, nullable
    - `icon` string, nullable: Market icon/image URL.
    - `token_id` string, required
    - `outcome` string, required: Outcome label — YES/NO or a token symbol.
    - `size` string, decimal, required: Position size (>= 0).
    - `entry_price` string, decimal, required: Average entry price (>= 0), 0-1 scale.
    - `current_price` string, decimal, nullable: Current mark price (>= 0), 0-1 scale.
    - `cost_basis` string, decimal, required: Total USD cost basis for this position (>= 0).
    - `unrealized_pnl` string, decimal, nullable
    - `realized_pnl` string, decimal, required: Realized PnL booked against this position so far.
    - `status` 'OPEN' | 'CLOSED', required
    - `opened_at` string, date-time, nullable
    - `closed_at` string, date-time, nullable
    - `provider` string, required: Venue the position was traded on.
  - `closed_positions` TraderPosition[], required
    - `market_id` string, required
    - `market_name` string, nullable
    - `icon` string, nullable: Market icon/image URL.
    - `token_id` string, required
    - `outcome` string, required: Outcome label — YES/NO or a token symbol.
    - `size` string, decimal, required: Position size (>= 0).
    - `entry_price` string, decimal, required: Average entry price (>= 0), 0-1 scale.
    - `current_price` string, decimal, nullable: Current mark price (>= 0), 0-1 scale.
    - `cost_basis` string, decimal, required: Total USD cost basis for this position (>= 0).
    - `unrealized_pnl` string, decimal, nullable
    - `realized_pnl` string, decimal, required: Realized PnL booked against this position so far.
    - `status` 'OPEN' | 'CLOSED', required
    - `opened_at` string, date-time, nullable
    - `closed_at` string, date-time, nullable
    - `provider` string, required: Venue the position was traded on.
  - `has_more` boolean: True when more positions exist beyond this page (open+closed combined, sorted by value).

## 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 trader positions.

---

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