Skip to main content
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.

​
Workflow overview

1

Find a trader on the leaderboard

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

Fetch their profile

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

Browse their market history

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

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

​
Profile response fields

FieldDescription
profile.addressEVM wallet address.
profile.nameDisplay name on Polymarket.
profile.last_trade_atTimestamp of the trader’s most recent order.
top_tagsArray of market categories ranked by PNL, each with slug, pnl, roi, win_rate, markets_count, maker_volume, taker_volume.
stats.t_1h … stats.t_30dPerformance 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.
ParameterDescription
limitMarkets per page. Default: 20, max: 100.
offsetPagination offset.
is_activetrue 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}`);
}

​
Market history fields

Each entry in history contains:
FieldDescription
market.idNumeric market ID — use this to fetch orders.
market.questionHuman-readable market title.
market.tagsCategory tags (e.g. ["sports", "basketball"]).
market.resolved_atISO timestamp when the market resolved, or empty string if still active.
market.winning_outcomeWinning side once resolved; empty string otherwise.
pnlTrader’s profit/loss in micro-USDC for this market.
roiReturn on investment for this market as a percentage.
volumeTotal USDC traded by this trader in this market (micro-USDC).
last_trade_atTimestamp 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}`);
}

​
Order fields

FieldTypeDescription
timestringISO timestamp of the fill.
sidestringBUY or SELL.
outcomestringWhich outcome was traded (e.g. "Rockets").
pricestringExecution price in micro-USDC (divide by 1e6; range 0–1).
sharesstringNumber of outcome shares in micro-shares (divide by 1e6).
usdcstringUSDC value of the fill in micro-USDC (divide by 1e6).
is_takerbooltrue if the trader initiated the fill (market order); false if their limit order was filled.
fill_countintNumber of counter-orders matched in this fill.
order_hashstringOn-chain order hash for cross-referencing.
token_idstringERC-1155 token ID representing the outcome share.

​
Example response

{
  "orders": [
    {
      "time": "2026-04-06T02:25:29Z",
      "outcome": "Rockets",
      "side": "BUY",
      "price": "478541",
      "shares": "10448408978",
      "usdc": "4999999999",
      "order_hash": "0x25150adb61c78c2fe4bf9a025ad1b9fac0bf9cbb3a8904c74430905cb2a008ce",
      "is_taker": true,
      "fill_count": 1,
      "token_id": "78907585036215681443680219168838316352537740030793428756821532285400412083533"
    }
  ]
}