> ## Documentation Index > Fetch the complete documentation index at: https://docs.struct.to/llms.txt > Use this file to discover all available pages before exploring further. # Get trader position PnL > Per-position PnL for a trader. `status` is required — every position lookup is scoped to either currently-open positions or closed/resolved ones. `sort_by` and `search` can only be combined with a status; the per-status sort-by whitelists are exposed as `PositionOpenPnlSortBy` and `PositionClosedPnlSortBy`. ## OpenAPI ````yaml https://api.struct.to/openapi.json get /polymarket/trader/pnl/{address}/positions openapi: 3.1.0 info: title: Polymarket API description: >- RESTful API for querying Polymarket prediction markets data including events, markets, traders, holders, and real-time metrics license: name: '' version: 1.0.0 servers: - url: https://api.struct.to/v1 security: [] paths: /polymarket/trader/pnl/{address}/positions: get: tags: - Trader summary: Get trader position PnL description: >- Per-position PnL for a trader. `status` is required — every position lookup is scoped to either currently-open positions or closed/resolved ones. `sort_by` and `search` can only be combined with a status; the per-status sort-by whitelists are exposed as `PositionOpenPnlSortBy` and `PositionClosedPnlSortBy`. operationId: get_trader_position_pnl parameters: - name: address in: path description: Trader wallet address required: true schema: type: string - name: status in: query description: >- Required. `open` for positions still holding shares, `closed` for positions that have been fully exited or resolved. required: true schema: $ref: '#/components/schemas/PositionStatus' - name: won in: query description: >- Only valid with `status=closed`. `true` to include profitable closed positions, `false` for closed positions with zero or negative realized PnL. required: false schema: type: boolean - name: search in: query description: >- Case-insensitive substring match on the market title. Scoped to the chosen `status` — results never cross the open/closed boundary. required: false schema: type: string - name: sort_by in: query description: >- Sort field. Default: total_pnl_usd. status=open accepts: realized_pnl_usd, total_pnl_usd, unrealized_pnl_usd, raw_total_pnl_usd, raw_realized_pnl_usd, raw_unrealized_pnl_usd, raw_total_pnl_pct, raw_realized_pnl_pct, raw_unrealized_pnl_pct, merge_usd, convert_collateral_usd, converted_count, converted_shares_gained, converted_shares_lost, last_traded_price, total_buy_usd, total_sell_usd, total_buys, total_sells, total_shares_bought, total_shares_sold, avg_entry_price, avg_exit_price, avg_price, total_fees, first_trade_at, last_trade_at, current_value, realized_pnl_pct, total_pnl_pct, title, current_price, current_shares_balance, merge_count, split_count, end_date, is_neg_risk, redeemable, mergeable. status=closed accepts: realized_pnl_usd, total_pnl_usd, unrealized_pnl_usd, raw_total_pnl_usd, raw_realized_pnl_usd, raw_unrealized_pnl_usd, raw_total_pnl_pct, raw_realized_pnl_pct, raw_unrealized_pnl_pct, merge_usd, convert_collateral_usd, converted_count, converted_shares_gained, converted_shares_lost, last_traded_price, total_buy_usd, total_sell_usd, redemption_usd, total_buys, total_sells, total_shares_bought, total_shares_sold, avg_entry_price, avg_exit_price, avg_price, total_fees, first_trade_at, last_trade_at, realized_pnl_pct, total_pnl_pct, title, merge_count, split_count, end_date, is_neg_risk. required: false schema: $ref: '#/components/schemas/PositionPnlSortBy' x-open-position-sort-by: - realized_pnl_usd - total_pnl_usd - unrealized_pnl_usd - raw_total_pnl_usd - raw_realized_pnl_usd - raw_unrealized_pnl_usd - raw_total_pnl_pct - raw_realized_pnl_pct - raw_unrealized_pnl_pct - merge_usd - convert_collateral_usd - converted_count - converted_shares_gained - converted_shares_lost - last_traded_price - total_buy_usd - total_sell_usd - total_buys - total_sells - total_shares_bought - total_shares_sold - avg_entry_price - avg_exit_price - avg_price - total_fees - first_trade_at - last_trade_at - current_value - realized_pnl_pct - total_pnl_pct - title - current_price - current_shares_balance - merge_count - split_count - end_date - is_neg_risk - redeemable - mergeable x-closed-position-sort-by: - realized_pnl_usd - total_pnl_usd - unrealized_pnl_usd - raw_total_pnl_usd - raw_realized_pnl_usd - raw_unrealized_pnl_usd - raw_total_pnl_pct - raw_realized_pnl_pct - raw_unrealized_pnl_pct - merge_usd - convert_collateral_usd - converted_count - converted_shares_gained - converted_shares_lost - last_traded_price - total_buy_usd - total_sell_usd - redemption_usd - total_buys - total_sells - total_shares_bought - total_shares_sold - avg_entry_price - avg_exit_price - avg_price - total_fees - first_trade_at - last_trade_at - realized_pnl_pct - total_pnl_pct - title - merge_count - split_count - end_date - is_neg_risk x-open-position-sort-by-schema: '#/components/schemas/PositionOpenPnlSortBy' x-closed-position-sort-by-schema: '#/components/schemas/PositionClosedPnlSortBy' - name: sort_direction in: query description: 'Default: desc' required: false schema: $ref: '#/components/schemas/SortDirection' - name: limit in: query description: Default 10, max 200 required: false schema: type: integer format: int32 - name: offset in: query description: Max 3500. Takes precedence over pagination_key. required: false schema: type: integer format: int32 - name: pagination_key in: query description: Cursor from a previous response required: false schema: type: string - name: condition_id in: query description: Filter to a single market required: false schema: type: string - name: market_slug in: query description: Filter by market slug required: false schema: type: string - name: position_id in: query description: Filter to a single outcome token required: false schema: type: string - name: min_shares in: query description: Minimum shares balance to include required: false schema: type: number format: double - name: category in: query description: >- Filter positions to a single market category. Combinable with `sort_by`. required: false schema: $ref: '#/components/schemas/PolymarketCategory' - name: combo in: query description: >- Filter by combo classification: `true` for any combo position, `false` for standard positions only, or a specific combo type — `binary`, `negrisk`, or `combinatorial` (parlays). Omit for all positions. required: false schema: $ref: '#/components/schemas/ComboFilter' responses: '200': description: Per-position PnL rows content: application/json: schema: type: array items: $ref: '#/components/schemas/PositionPnl' '400': description: >- Invalid params (missing `status`, unrecognised `sort_by`, or a `sort_by` value that's not allowed for the chosen status) components: schemas: PositionStatus: type: string enum: - open - closed PositionPnlSortBy: type: string description: |- Sort field for per-trader position PnL results. Includes fee-excluded (`raw_*`) PnL metrics — see `PositionOpenPnlSortBy` and `PositionClosedPnlSortBy` for the per-status whitelists. enum: - realized_pnl_usd - total_pnl_usd - unrealized_pnl_usd - raw_total_pnl_usd - raw_realized_pnl_usd - raw_unrealized_pnl_usd - raw_total_pnl_pct - raw_realized_pnl_pct - raw_unrealized_pnl_pct - merge_usd - convert_collateral_usd - converted_count - converted_shares_gained - converted_shares_lost - last_traded_price - total_buy_usd - total_sell_usd - redemption_usd - total_buys - total_sells - total_shares_bought - total_shares_sold - avg_entry_price - avg_exit_price - avg_price - total_fees - first_trade_at - last_trade_at - current_value - realized_pnl_pct - total_pnl_pct - current_price - current_shares_balance - merge_count - split_count - title - end_date - is_neg_risk - redeemable - mergeable SortDirection: type: string enum: - asc - desc PolymarketCategory: type: string description: Polymarket UI category. enum: - Politics - Sports - Crypto - Finance - Culture - Mentions - Weather - Economics - Tech ComboFilter: type: string description: Combo market classification filter. enum: - 'true' - 'false' - binary - negrisk - combinatorial PositionPnl: type: object properties: position_id: type: - string - 'null' description: Position ID. condition_id: type: - string - 'null' description: Condition ID. market_slug: type: - string - 'null' description: Market slug. event_slug: type: - string - 'null' description: Event slug. category: type: - string - 'null' description: Category. title: type: - string - 'null' description: Title. question: type: - string - 'null' description: Question. image_url: type: - string - 'null' description: Image URL. trader: oneOf: - type: 'null' - $ref: '#/components/schemas/TraderProfile' description: Trader wallet or profile. outcome: type: - string - 'null' description: Outcome. outcome_index: type: - integer - 'null' format: int32 description: Outcome index. combo_type: type: - string - 'null' description: |- Combo market type: `binary`, `negrisk`, or `combinatorial` (parlay). Omitted for standard positions. won: type: - boolean - 'null' description: Won. total_buys: type: - integer - 'null' format: int64 description: Total buys. total_sells: type: - integer - 'null' format: int64 description: Total sells. converted_count: type: - integer - 'null' format: int64 description: Converted count. converted_shares_gained: type: - number - 'null' format: double description: Converted shares gained. converted_shares_lost: type: - number - 'null' format: double description: Converted shares lost. total_shares_bought: type: - number - 'null' format: double description: Total shares bought. total_shares_sold: type: - number - 'null' format: double description: Total shares sold. total_buy_usd: type: - number - 'null' format: double description: Total buy in USD. total_sell_usd: type: - number - 'null' format: double description: Total sell in USD. redemption_usd: type: - number - 'null' format: double description: Redemption in USD. merge_usd: type: - number - 'null' format: double description: USD value from merge activity. convert_collateral_usd: type: - number - 'null' format: double description: Convert collateral in USD. avg_entry_price: type: - number - 'null' format: double description: Average entry price. avg_exit_price: type: - number - 'null' format: double description: Average exit price. avg_price: type: - number - 'null' format: double description: Volume-weighted average trade price across buys and sells. realized_pnl_usd: type: number format: double description: Realized PnL in USD. total_pnl_usd: type: number format: double description: Total PnL in USD. unrealized_pnl_usd: type: number format: double description: Unrealized PnL in USD. total_fees: type: - number - 'null' format: double description: Total fees. first_trade_at: type: - integer - 'null' format: int64 description: First trade at timestamp. last_trade_at: type: - integer - 'null' format: int64 description: Last trade at timestamp. current_price: type: - number - 'null' format: double description: Current price. last_traded_price: type: - number - 'null' format: double description: Last traded price. current_shares_balance: type: - number - 'null' format: double description: Current shares balance. current_value: type: - number - 'null' format: double description: Current value. realized_pnl_pct: type: - number - 'null' format: double description: Realized PnL percent. total_pnl_pct: type: - number - 'null' format: double description: Total PnL percent. end_date: type: - integer - 'null' format: int64 description: End date timestamp. is_neg_risk: type: - boolean - 'null' description: Whether neg risk is true. redeemable: type: - boolean - 'null' description: Redeemable. mergeable: type: - boolean - 'null' description: Mergeable. TraderProfile: type: object required: - address - verified_badge properties: address: type: string description: Wallet address. name: type: - string - 'null' description: Name. pseudonym: type: - string - 'null' description: Pseudonym. profile_image: type: - string - 'null' description: Profile image. x_username: type: - string - 'null' description: X username. verified_badge: type: boolean description: Verified badge. ````