> ## 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. # Batch trader PnL summaries > PnL summaries for many wallets across many timeframes in one call, keyed by wallet then timeframe (a wallet/timeframe with no data is omitted). ## OpenAPI ````yaml https://api.struct.to/openapi.json post /polymarket/trader/pnl/batch 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/batch: post: tags: - Trader summary: Batch trader PnL summaries description: >- PnL summaries for many wallets across many timeframes in one call, keyed by wallet then timeframe (a wallet/timeframe with no data is omitted). operationId: get_trader_pnl_batch requestBody: content: application/json: schema: $ref: '#/components/schemas/BatchPnlRequest' required: true responses: '200': description: PnL summaries keyed by wallet and timeframe content: application/json: schema: type: object additionalProperties: type: object additionalProperties: $ref: '#/components/schemas/TraderPnl' propertyNames: type: string enum: - 1d - 7d - 30d - lifetime propertyNames: type: string example: '0x96cfcb0c30942cfcd1cdf76c7d408794d66b1acb': lifetime: trader: address: '0x96cfcb0c30942cfcd1cdf76c7d408794d66b1acb' name: mintblade pseudonym: Golden-Reclamation verified_badge: false realized_pnl_usd: 1878816.203922 total_pnl_usd: 9094807.981258 unrealized_pnl_usd: 7215991.777336 usd_balance: 3367872.058961 realized_pnl_pct: 21.719621 total_pnl_pct: 105.13843 open_positions_value: 14351553.789366 events_traded: 4 categories_traded: 1 markets_traded: 5 markets_won: 4 markets_lost: 0 market_win_rate_pct: 100 avg_win_usd: 469704.050981 avg_loss_usd: 0 profit_factor: 0 total_buys: 727 total_sells: 0 total_redemptions: 4 total_volume_usd: 11916491.517144 buy_volume_usd: 8522919.883091 total_fees: 127397.55907 total_wins_usd: 1878816.203922 total_losses_usd: 0 best_trade_pnl_usd: 1351658.511818 best_trade_condition_id: >- 0xbc54d73527785bdc7b443cfdf3b0d59558c5ac2bbffca23425ecfbd161b07317 best_trade_metadata: market_slug: fifwc-ksa-ury-2026-06-15-ury event_slug: fifwc-ksa-ury-2026-06-15 question: Will Uruguay win on 2026-06-15? title: Uruguay avg_hold_time_seconds: 518864 first_trade_at: 1780521522 last_trade_at: 1781580031 open_position_count: 1 '400': description: >- Invalid request (bad address, unknown timeframe, too many wallets, or malformed body) components: schemas: BatchPnlRequest: type: object description: Request body for the batch PnL endpoint. required: - wallets properties: wallets: type: array items: type: string description: >- Trader wallet addresses. Deduplicated and lower-cased before billing. timeframes: type: - array - 'null' items: type: string description: >- Timeframes to fetch for every wallet. Defaults to `["lifetime"]` when omitted. Valid values: `1d`, `7d`, `30d`, `lifetime`. TraderPnl: type: object required: - trader - realized_pnl_usd - open_positions_value - events_traded - categories_traded - markets_traded - markets_won - markets_lost - market_win_rate_pct - avg_win_usd - avg_loss_usd - profit_factor - total_buys - total_sells - total_redemptions - total_merges - converted_count - converted_shares_gained - converted_shares_lost - total_volume_usd - buy_volume_usd - sell_volume_usd - redemption_volume_usd - merge_volume_usd - total_fees - total_wins_usd - total_losses_usd - avg_hold_time_seconds - maker_rebate_count - maker_rebate_usd - reward_count - reward_usd - yield_count - yield_usd - open_position_count properties: trader: $ref: '#/components/schemas/TraderProfile' description: Trader wallet or profile. 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. usd_balance: type: number format: double description: >- Wallet cash held in pUSD + USDC at this point in time. Stable per block. realized_pnl_pct: type: - number - 'null' format: double description: Realized PnL percent. total_pnl_pct: type: - number - 'null' format: double description: Total PnL percent. open_positions_value: type: number format: double description: Open positions value. events_traded: type: integer format: int64 description: Events traded. minimum: 0 categories_traded: type: integer format: int64 description: Categories traded. minimum: 0 markets_traded: type: integer format: int64 description: |- Distinct markets (condition_ids) with at least one buy or sell by this trader. NOTE: `markets_won + markets_lost` uses a DIFFERENT denominator (decided markets — see those fields) and can exceed this count: positions acquired without a trade (e.g. NegRisk conversions, transfers) never increment `markets_traded` but can still produce a win/loss verdict once closed or resolved. These fields are not subsets of each other and do not reconcile. minimum: 0 markets_won: type: integer format: int64 description: |- Markets with a DECIDED winning verdict: the market's position was fully closed (sold/redeemed to zero) or resolved, and the summed realized PnL for that market is positive. Open/undecided markets are not counted; re-entering a market reverses its verdict until it is decided again. Denominator differs from `markets_traded` (see that field). minimum: 0 markets_lost: type: integer format: int64 description: |- Markets with a DECIDED losing verdict (summed realized PnL negative at close/resolution). See `markets_won` for the decided-market semantics. minimum: 0 market_win_rate_pct: type: number format: double description: |- `100 × markets_won / (markets_won + markets_lost)` — the denominator is DECIDED markets only (won + lost), not `markets_traded`. 0 when no market is decided yet. avg_win_usd: type: number format: double description: Average win in USD. avg_loss_usd: type: number format: double description: Average loss in USD. profit_factor: type: number format: double description: Profit factor. total_buys: type: integer format: int64 description: Total buys. minimum: 0 total_sells: type: integer format: int64 description: Total sells. minimum: 0 total_redemptions: type: integer format: int64 description: Total redemptions. minimum: 0 total_merges: type: integer format: int64 description: Total merges. minimum: 0 total_splits: type: integer format: int64 description: Number of split transactions in the selected timeframe. minimum: 0 converted_count: type: integer format: int64 description: Converted count. minimum: 0 converted_shares_gained: type: number format: double description: Converted shares gained. converted_shares_lost: type: number format: double description: Converted shares lost. total_volume_usd: type: number format: double description: Total volume in USD. buy_volume_usd: type: number format: double description: Buy volume in USD. sell_volume_usd: type: number format: double description: Sell volume in USD. redemption_volume_usd: type: number format: double description: Redemption volume in USD. merge_volume_usd: type: number format: double description: Merge volume in USD. convert_collateral_usd: type: number format: double description: Convert collateral in USD. split_volume_usd: type: number format: double description: USD collateral split into outcome tokens in the selected timeframe. total_fees: type: number format: double description: Total fees. total_wins_usd: type: number format: double description: Total wins in USD. total_losses_usd: type: number format: double description: Total losses in USD. best_trade_pnl_usd: type: - number - 'null' format: double description: Best trade PnL in USD. best_trade_condition_id: type: - string - 'null' description: Best trade condition ID. worst_trade_pnl_usd: type: - number - 'null' format: double description: Worst trade PnL in USD. worst_trade_condition_id: type: - string - 'null' description: Worst trade condition ID. best_trade_metadata: oneOf: - type: 'null' - $ref: '#/components/schemas/TradeMarketRef' description: |- Market metadata (condition_id, slug, title, question, image_url, event_slug) for the market behind the best PnL trade in this summary at this timeframe. `null` when no trade qualifies. worst_trade_metadata: oneOf: - type: 'null' - $ref: '#/components/schemas/TradeMarketRef' description: Market metadata for the market behind the worst PnL trade. avg_hold_time_seconds: type: number format: double description: Average hold time seconds. 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. maker_rebate_count: type: integer format: int64 description: Maker rebate count. minimum: 0 maker_rebate_usd: type: number format: double description: Maker rebate in USD. reward_count: type: integer format: int64 description: Reward count. minimum: 0 reward_usd: type: number format: double description: Reward in USD. yield_count: type: integer format: int64 description: Yield count. minimum: 0 yield_usd: type: number format: double description: Yield in USD. open_position_count: type: integer format: int64 description: Open position count. minimum: 0 combo_trade_count: type: integer format: int64 description: Number of combo trades executed by this trader. minimum: 0 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. TradeMarketRef: type: object description: >- Market metadata for the market a trader's best / worst trade landed in. Accompanies the existing flat `best_trade_pnl_usd` / `worst_trade_pnl_usd` numerics on trader / event / category PnL summaries. properties: condition_id: type: - string - 'null' description: Condition ID. market_slug: type: - string - 'null' description: Market slug. title: type: - string - 'null' description: Title. question: type: - string - 'null' description: Question. image_url: type: - string - 'null' description: Image URL. event_slug: type: - string - 'null' description: Event slug. ````