Trader analytics

PolyEdge exposes three layered endpoints for analyzing a single trader. Start with a high-level profile, drill into their market history, then inspect individual orders — all the way down to price, size, and maker/taker status.

All PnL metrics on PolyEdge are net of trading fees (fees are automatically subtracted). Only Polymarket v2 data is tracked (v1 data is excluded).

Workflow overview

Find a trader on the leaderboard

Use the Leaderboard endpoint to identify a trader whose stats interest you. Note their wallet address.

Fetch their profile

Pull multi-timeframe stats and top market categories with GET /v1/traders/:address.

Browse their market history

List every market they have traded with GET /v1/traders/:address/markets.

Inspect orders in a specific market

Retrieve individual fills with GET /v1/traders/:address/markets/:id/orders.

1. Trader profile

GET /v1/traders/:address Returns the trader’s metadata, their strongest market categories (top_tags), and aggregate performance stats across six time windows: t_1h, t_4h, t_1d, t_3d, t_7d, t_30d.

import PolyEdgeClient from './polyedge.js';

const client = new PolyEdgeClient('YOUR_API_KEY');

const address = '0x8a6c6811e8937f9e8afc1b9249fa540262c30b3f';
const { profile, top_tags, stats } = await client.getTraderProfile(address);

console.log(`Name: ${profile.name}`);
console.log(`Last trade: ${profile.last_trade_at}`);

// Multi-timeframe stats
console.log(`1h  ROI: ${stats.t_1h.roi}%  |  Win rate: ${stats.t_1h.win_rate}%`);
console.log(`7d  ROI: ${stats.t_7d.roi}%  |  Win rate: ${stats.t_7d.win_rate}%`);
console.log(`30d ROI: ${stats.t_30d.roi}% |  Win rate: ${stats.t_30d.win_rate}%`);

// Top categories by PNL
for (const tag of top_tags.slice(0, 3)) {
  const pnl = (Number(tag.pnl) / 1e6).toFixed(2);
  console.log(`  ${tag.slug}: $${pnl} PNL @ ${tag.roi}% ROI`);
}

from polyedge import PolyEdgeClient

client = PolyEdgeClient('YOUR_API_KEY')

address = '0x8a6c6811e8937f9e8afc1b9249fa540262c30b3f'
response = client.get_trader_profile(address)

profile = response['profile']
stats   = response['stats']
top_tags = response['top_tags']

print(f"Name: {profile['name']}")
print(f"Last trade: {profile['last_trade_at']}")

# Multi-timeframe stats
print(f"1h  ROI: {stats['t_1h']['roi']}%  |  Win rate: {stats['t_1h']['win_rate']}%")
print(f"7d  ROI: {stats['t_7d']['roi']}%  |  Win rate: {stats['t_7d']['win_rate']}%")
print(f"30d ROI: {stats['t_30d']['roi']}% |  Win rate: {stats['t_30d']['win_rate']}%")

# Top categories by PNL
for tag in top_tags[:3]:
    pnl = float(tag['pnl']) / 1e6
    print(f"  {tag['slug']}: ${pnl:,.2f} PNL @ {tag['roi']}% ROI")

Profile response fields

Field	Description
`profile.address`	EVM wallet address.
`profile.name`	Display name on Polymarket.
`profile.last_trade_at`	Timestamp of the trader’s most recent order.
`top_tags`	Array of market categories ranked by PNL, each with `slug`, `pnl`, `roi`, `win_rate`, `markets_count`, `maker_volume`, `taker_volume`.
`stats.t_1h` … `stats.t_30d`	Performance snapshot for each window: `pnl`, `volume`, `roi`, `win_rate`, `markets_count`, `wins_count`, `maker_volume`, `taker_volume`.

2. Trader markets

GET /v1/traders/:address/markets Lists every market the trader has been active in, with per-market PNL, ROI, and volume. Use the is_active filter to focus on open positions.

Parameter	Description
`limit`	Markets per page. Default: `20`, max: `100`.
`offset`	Pagination offset.
`is_active`	`true` returns only unresolved markets; omit to include both active and resolved.

import PolyEdgeClient from './polyedge.js';

const client = new PolyEdgeClient('YOUR_API_KEY');

const address = '0x8a6c6811e8937f9e8afc1b9249fa540262c30b3f';

// Fetch the 20 most recent markets (active + resolved)
const { history, total_count } = await client.getTraderMarkets(address, { limit: 20 });

console.log(`Total markets traded: ${total_count}`);

for (const entry of history) {
  const pnl   = (Number(entry.pnl) / 1e6).toFixed(2);
  const vol   = (Number(entry.volume) / 1e6).toFixed(2);
  const status = entry.market.resolved_at ? 'resolved' : 'active';
  console.log(`[${status}] ${entry.market.question}`);
  console.log(`  PNL: $${pnl} | ROI: ${entry.roi.toFixed(2)}% | Volume: $${vol}`);
}

from polyedge import PolyEdgeClient

client = PolyEdgeClient('YOUR_API_KEY')

address = '0x8a6c6811e8937f9e8afc1b9249fa540262c30b3f'

# Fetch only active (unresolved) markets
response = client.get_trader_markets(address, {'limit': 20, 'is_active': True})
history     = response['history']
total_count = response['total_count']

print(f"Active markets: {total_count}")

for entry in history:
    pnl = float(entry['pnl']) / 1e6
    vol = float(entry['volume']) / 1e6
    print(f"{entry['market']['question']}")
    print(f"  PNL: ${pnl:,.2f} | ROI: {entry['roi']:.2f}% | Volume: ${vol:,.2f}")
    print(f"  Market ID: {entry['market']['id']} | Last trade: {entry['last_trade_at']}")

Market history fields

Each entry in history contains:

Field	Description
`market.id`	Numeric market ID — use this to fetch orders.
`market.question`	Human-readable market title.
`market.tags`	Category tags (e.g. `["sports", "basketball"]`).
`market.resolved_at`	ISO timestamp when the market resolved, or empty string if still active.
`market.winning_outcome`	Winning side once resolved; empty string otherwise.
`pnl`	Trader’s profit/loss in micro-USDC for this market.
`roi`	Return on investment for this market as a percentage.
`volume`	Total USDC traded by this trader in this market (micro-USDC).
`last_trade_at`	Timestamp of the trader’s last order in this market.

3. Trader market orders

GET /v1/traders/:address/markets/:id/orders Returns every individual fill for the trader in the specified market. This is where you can see exactly what price they paid, how many shares they bought or sold, and whether they were taking or making liquidity.

import PolyEdgeClient from './polyedge.js';

const client = new PolyEdgeClient('YOUR_API_KEY');

const address  = '0x8a6c6811e8937f9e8afc1b9249fa540262c30b3f';
const marketId = 1858809;

const { orders } = await client.getTraderMarketOrders(address, marketId);

for (const order of orders) {
  const price  = (Number(order.price) / 1e6).toFixed(4);
  const shares = (Number(order.shares) / 1e6).toFixed(2);
  const usdc   = (Number(order.usdc) / 1e6).toFixed(2);
  const role   = order.is_taker ? 'taker' : 'maker';
  console.log(`[${order.time}] ${order.side} ${order.outcome} — ${role}`);
  console.log(`  Price: $${price} | Shares: ${shares} | USDC: $${usdc}`);
}

from polyedge import PolyEdgeClient

client = PolyEdgeClient('YOUR_API_KEY')

address   = '0x8a6c6811e8937f9e8afc1b9249fa540262c30b3f'
market_id = 1858809

response = client.get_trader_market_orders(address, market_id)

for order in response['orders']:
    price  = float(order['price'])  / 1e6
    shares = float(order['shares']) / 1e6
    usdc   = float(order['usdc'])   / 1e6
    role   = 'taker' if order['is_taker'] else 'maker'
    print(f"[{order['time']}] {order['side']} {order['outcome']} — {role}")
    print(f"  Price: ${price:.4f} | Shares: {shares:.2f} | USDC: ${usdc:.2f}")

Order fields

Field	Type	Description
`time`	string	ISO timestamp of the fill.
`side`	string	`BUY` or `SELL`.
`outcome`	string	Which outcome was traded (e.g. `"Rockets"`).
`price`	string	Execution price in micro-USDC (divide by `1e6`; range 0–1).
`shares`	string	Number of outcome shares in micro-shares (divide by `1e6`).
`usdc`	string	USDC value of the fill in micro-USDC (divide by `1e6`).
`is_taker`	bool	`true` if the trader initiated the fill (market order); `false` if their limit order was filled.
`fee`	string	Fee paid in micro-USDC (divide by `1e6`).
`order_hash`	string	On-chain order hash for cross-referencing.
`token_id`	string	ERC-1155 token ID representing the outcome share.

Example response

{
  "orders": [
    {
      "time": "2026-06-18T01:53:41Z",
      "outcome": "Yes",
      "side": "BUY",
      "price": "70000",
      "shares": "11348494064",
      "usdc": "794394585",
      "order_hash": "",
      "is_taker": false,
      "token_id": "423759085869325981528714200340893689298833619490218143057207864882252703229",
      "fee": "0"
    }
  ]
}

Get Started

Guides

SDKs

Workflow overview

1. Trader profile

Profile response fields

2. Trader markets

Market history fields

3. Trader market orders

Order fields

Example response

​Workflow overview

​1. Trader profile

​Profile response fields

​2. Trader markets

​Market history fields

​3. Trader market orders

​Order fields

​Example response

Workflow overview

1. Trader profile

Profile response fields

2. Trader markets

Market history fields

3. Trader market orders

Order fields

Example response