Polymarket Traders API

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, 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 for a single wallet, or fetch multiple profiles in one call.
Page through a trader’s trades and chart their volume over time.

PnL

Fetch open and closed positions with full PnL stats, including realized and unrealized returns per position.
Read a wallet’s PnL summary, then break it down by market or by category.
Chart performance with PnL candles, a PnL calendar heatmap, and period-over-period changes.
Surface position exits, best and worst periods, and risk metrics.

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. Scope to any timeframe (lifetime by default), order the board with sort_by (default total_pnl_usd) and sort_direction, and page through it with the cursor (limit up to 500).
Narrow the board to a scope: top traders by category, in a single market, holding a specific position, or for a builder.
Find the 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, so a wallet’s standing on the board and its own profile always agree.

Analytics

Per-trader percentage change, per-bucket candles, and cumulative timeseries.

Example

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 });

Guides: Trader Open and Closed Positions, Live Trader PnL Dashboard, Trader PnL History Charts, Copy Trading
SDK: Trader namespace
Core concepts

​Profiles and activity

​PnL

​Leaderboards

​Analytics

​Example

​Related

Profiles and activity

PnL

Leaderboards

Analytics

Example

Related