Get trader PnL summary

curl --request GET \
  --url https://api.struct.to/v1/polymarket/trader/pnl/{address}

const options = {method: 'GET'};

fetch('https://api.struct.to/v1/polymarket/trader/pnl/{address}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.struct.to/v1/polymarket/trader/pnl/{address}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.struct.to/v1/polymarket/trader/pnl/{address}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.struct.to/v1/polymarket/trader/pnl/{address}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "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,
  "combo_trade_count": 1
}

GET

polymarket

trader

pnl

{address}

Get trader PnL summary

curl --request GET \
  --url https://api.struct.to/v1/polymarket/trader/pnl/{address}

const options = {method: 'GET'};

fetch('https://api.struct.to/v1/polymarket/trader/pnl/{address}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.struct.to/v1/polymarket/trader/pnl/{address}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.struct.to/v1/polymarket/trader/pnl/{address}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.struct.to/v1/polymarket/trader/pnl/{address}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "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,
  "combo_trade_count": 1
}

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.

Show child attributes

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

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.

Required range: x >= 0

markets_won

integer<int64>

required

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

Required range: x >= 0

markets_lost

integer<int64>

required

Markets with a DECIDED losing verdict (summed realized PnL negative at close/resolution). See markets_won for the decided-market semantics.

Required range: x >= 0

market_win_rate_pct

number<double>

required

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

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

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

Show child attributes

worst_trade_metadata

null | object

Market metadata for the market behind the worst PnL trade.

Show child attributes

first_trade_at

integer<int64> | null

First trade at timestamp.

last_trade_at

integer<int64> | null

Last trade at timestamp.

combo_trade_count

integer<int64>

Number of combo trades executed by this trader.

Required range: x >= 0

Last modified on August 7, 2026

Introduction

Market

Events

Series

Trader

Combos

Holders

Order Book

Builders

Tags

Analytics

Assets

Bonds

Search

Get trader PnL summary

Path Parameters

Query Parameters

Response