Skip to main content
GET
/
polymarket
/
trader
/
pnl
/
{address}
Get trader PnL summary
curl --request GET \
  --url https://api.struct.to/v1/polymarket/trader/pnl/{address}
{
  "trader": {
    "address": "<string>",
    "verified_badge": true,
    "name": "<string>",
    "pseudonym": "<string>",
    "profile_image": "<string>",
    "x_username": "<string>"
  },
  "realized_pnl_usd": 123,
  "open_positions_value": 123,
  "events_traded": 1,
  "categories_traded": 1,
  "markets_traded": 1,
  "markets_won": 1,
  "markets_lost": 1,
  "market_win_rate_pct": 123,
  "avg_win_usd": 123,
  "avg_loss_usd": 123,
  "profit_factor": 123,
  "total_buys": 1,
  "total_sells": 1,
  "total_redemptions": 1,
  "total_merges": 1,
  "converted_count": 1,
  "converted_shares_gained": 123,
  "converted_shares_lost": 123,
  "total_volume_usd": 123,
  "buy_volume_usd": 123,
  "sell_volume_usd": 123,
  "redemption_volume_usd": 123,
  "merge_volume_usd": 123,
  "total_fees": 123,
  "total_wins_usd": 123,
  "total_losses_usd": 123,
  "avg_hold_time_seconds": 123,
  "maker_rebate_count": 1,
  "maker_rebate_usd": 123,
  "reward_count": 1,
  "reward_usd": 123,
  "yield_count": 1,
  "yield_usd": 123,
  "open_position_count": 1,
  "total_pnl_usd": 123,
  "unrealized_pnl_usd": 123,
  "usd_balance": 123,
  "realized_pnl_pct": 123,
  "total_pnl_pct": 123,
  "total_splits": 1,
  "convert_collateral_usd": 123,
  "split_volume_usd": 123,
  "best_trade_pnl_usd": 123,
  "best_trade_condition_id": "<string>",
  "worst_trade_pnl_usd": 123,
  "worst_trade_condition_id": "<string>",
  "best_trade_metadata": {
    "condition_id": "<string>",
    "market_slug": "<string>",
    "title": "<string>",
    "question": "<string>",
    "image_url": "<string>",
    "event_slug": "<string>"
  },
  "worst_trade_metadata": {
    "condition_id": "<string>",
    "market_slug": "<string>",
    "title": "<string>",
    "question": "<string>",
    "image_url": "<string>",
    "event_slug": "<string>"
  },
  "first_trade_at": 123,
  "last_trade_at": 123
}

Path Parameters

address
string
required

Trader wallet address

Query Parameters

timeframe
enum<string>

Default: lifetime

Available options:
1d,
7d,
30d,
lifetime

Response

Trader PnL summary

trader
object
required

Trader wallet or profile.

realized_pnl_usd
number<double>
required

Realized PnL in USD.

open_positions_value
number<double>
required

Open positions value.

events_traded
integer<int64>
required

Events traded.

Required range: x >= 0
categories_traded
integer<int64>
required

Categories traded.

Required range: x >= 0
markets_traded
integer<int64>
required

Markets traded.

Required range: x >= 0
markets_won
integer<int64>
required

Markets won.

Required range: x >= 0
markets_lost
integer<int64>
required

Markets lost.

Required range: x >= 0
market_win_rate_pct
number<double>
required

Market win rate percent.

avg_win_usd
number<double>
required

Average win in USD.

avg_loss_usd
number<double>
required

Average loss in USD.

profit_factor
number<double>
required

Profit factor.

total_buys
integer<int64>
required

Total buys.

Required range: x >= 0
total_sells
integer<int64>
required

Total sells.

Required range: x >= 0
total_redemptions
integer<int64>
required

Total redemptions.

Required range: x >= 0
total_merges
integer<int64>
required

Total merges.

Required range: x >= 0
converted_count
integer<int64>
required

Converted count.

Required range: x >= 0
converted_shares_gained
number<double>
required

Converted shares gained.

converted_shares_lost
number<double>
required

Converted shares lost.

total_volume_usd
number<double>
required

Total volume in USD.

buy_volume_usd
number<double>
required

Buy volume in USD.

sell_volume_usd
number<double>
required

Sell volume in USD.

redemption_volume_usd
number<double>
required

Redemption volume in USD.

merge_volume_usd
number<double>
required

Merge volume in USD.

total_fees
number<double>
required

Total fees.

total_wins_usd
number<double>
required

Total wins in USD.

total_losses_usd
number<double>
required

Total losses in USD.

avg_hold_time_seconds
number<double>
required

Average hold time seconds.

maker_rebate_count
integer<int64>
required

Maker rebate count.

Required range: x >= 0
maker_rebate_usd
number<double>
required

Maker rebate in USD.

reward_count
integer<int64>
required

Reward count.

Required range: x >= 0
reward_usd
number<double>
required

Reward in USD.

yield_count
integer<int64>
required

Yield count.

Required range: x >= 0
yield_usd
number<double>
required

Yield in USD.

open_position_count
integer<int64>
required

Open position count.

Required range: x >= 0
total_pnl_usd
number<double>

Total PnL in USD.

unrealized_pnl_usd
number<double>

Unrealized PnL in USD.

usd_balance
number<double>

Wallet cash held in pUSD + USDC at this point in time. Stable per block.

realized_pnl_pct
number<double> | null

Realized PnL percent.

total_pnl_pct
number<double> | null

Total PnL percent.

total_splits
integer<int64>

Number of split transactions in the selected timeframe.

Required range: x >= 0
convert_collateral_usd
number<double>

Convert collateral in USD.

split_volume_usd
number<double>

USD collateral split into outcome tokens in the selected timeframe.

best_trade_pnl_usd
number<double> | null

Best trade PnL in USD.

best_trade_condition_id
string | null

Best trade condition ID.

worst_trade_pnl_usd
number<double> | null

Worst trade PnL in USD.

worst_trade_condition_id
string | null

Worst trade condition ID.

best_trade_metadata
object

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
object

Market metadata for the market behind the worst PnL trade.

first_trade_at
integer<int64> | null

First trade at timestamp.

last_trade_at
integer<int64> | null

Last trade at timestamp.

Last modified on June 17, 2026