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

# Polymarket Traders API

> Trader profiles, trade history, volume, and the full PnL suite.

A trader is a wallet address active on Polymarket, identified by its on-chain `address`. The Trader endpoints cover profiles, trade history, volume, and a deep PnL suite (summary, by market, by category, combo/parlay, candles, calendar, exits, and risk), plus the global PnL leaderboard.

Every PnL figure Struct returns is true net PnL: realized and unrealized combined, with trading fees, maker rebates, rewards, and yield all factored in. The leaderboard and a single wallet's summary share the same accounting, so the numbers always agree.

## Profiles and activity

* [Get a trader overview](/api-reference/trader/get-trader-overview) for a single wallet, or [fetch multiple profiles in one call](/api-reference/trader/get-multiple-trader-profiles).
* [Page through a trader's trades](/api-reference/trader/get-trader-trades) and [chart their volume over time](/api-reference/trader/get-trader-volume-chart).

## PnL

* [Fetch open and closed positions with full PnL stats](/api-reference/trader/get-trader-position-pnl), including realized and unrealized returns per position. Position and market rows carry `combo_type` (`combinatorial`) when the market is a combo; filter with the `combo` query param.
* [Read a wallet's PnL summary](/api-reference/trader/get-trader-pnl-summary), then break it down [by market](/api-reference/trader/get-trader-market-pnl) or [by category](/api-reference/trader/get-trader-category-pnl). Summaries include `combo_trade_count`.
* Expand multi-leg parlays with [combo PnL listing](/api-reference/trader/list-combo-positions-with-legs-metadata-and-pnl) and [single-combo breakdown](/api-reference/trader/combo-position-with-legs-metadata-and-pnl) — legs, implied probability, and potential payout. See [Tracking a trader's combo PnL](/guides/trader-combo-pnl).
* Chart performance with [PnL candles](/api-reference/trader/get-trader-pnl-candles), a [PnL calendar heatmap](/api-reference/trader/get-trader-pnl-calendar), and [period-over-period changes](/api-reference/trader/get-trader-pnl-changes).
* Surface [position exits](/api-reference/trader/get-trader-position-exits), [best and worst periods](/api-reference/trader/get-trader-best-and-worst-pnl-periods), and [risk metrics](/api-reference/trader/get-trader-pnl-risk).

## Leaderboards

Struct ranks traders on **true net PnL**, not trade volume or realized gains alone. Each entry combines realized and unrealized PnL and accounts for trading fees, maker rebates, rewards, and yield, so the board reflects what a trader has actually earned.

* [Rank traders by global PnL](/api-reference/trader/get-global-pnl-leaderboard). Scope to any `timeframe` (lifetime by default), order the board with `sort_by` (default `total_pnl_usd`; includes `combo_trade_count`) and `sort_direction`, and page through it with the cursor (`limit` up to 500).
* Narrow the board to a scope: [top traders by category](/api-reference/tags/get-top-traders-for-a-category), [in a single market](/api-reference/market/get-top-traders-for-a-market), [holding a specific position](/api-reference/market/get-top-traders-for-a-position), or [for a builder](/api-reference/builders/top-traders-for-a-builder).
* [Find the top markets across all traders](/api-reference/trader/get-top-markets-across-all-traders) to see where that PnL is being made.

Every leaderboard row carries the full breakdown (realized, unrealized, fees, maker rebates, rewards, and yield) alongside win rate, profit factor, average win and loss, and best and worst trades. It is the same shape returned by the [per-trader PnL summary](/api-reference/trader/get-trader-pnl-summary), so a wallet's standing on the board and its own profile always agree.

## Analytics

* Per-trader [percentage change](/api-reference/trader/trader-analytics-pct-change), [per-bucket candles](/api-reference/trader/trader-analytics-candles-per-bucket-deltas), and [cumulative timeseries](/api-reference/trader/trader-analytics-timeseries-cumulative).

## Example

<CodeGroup>
  ```typescript SDK theme={null}
  import { StructClient } from "@structbuild/sdk";

  const client = new StructClient({ apiKey: "YOUR_API_KEY" });

  const address = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045";

  const { data: profile } = await client.trader.getTraderProfile({ address });

  const { data: pnl } = await client.trader.getTraderPnl({ address });

  const { data: leaderboard } = await client.trader.getGlobalPnl({ limit: 100 });
  ```

  ```bash cURL theme={null}
  curl "https://api.struct.to/v1/polymarket/trader/profile/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" \
    -H "X-API-Key: YOUR_API_KEY"
  ```
</CodeGroup>

## Related

* Guides: [Trader Open and Closed Positions](/guides/trader-open-and-closed-positions), [Combo (parlay) PnL](/guides/trader-combo-pnl), [Live Trader PnL Dashboard](/guides/live-trader-pnl-dashboard), [Trader PnL History Charts](/guides/trader-pnl-history-charts), [Copy Trading](/guides/copy-trading-pending-or-confirmed-trades)
* SDK: [Trader namespace](/sdk/rest-api#trader)
* [Core concepts](/introduction/concepts)