> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polyedge.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Trader analytics

> Deep-dive into any trader: profile stats, market history, and individual orders.

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.

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

## Workflow overview

<Steps>
  <Step title="Find a trader on the leaderboard">
    Use the [Leaderboard](/guides/leaderboard) endpoint to identify a trader whose stats interest you. Note their wallet `address`.
  </Step>

  <Step title="Fetch their profile">
    Pull multi-timeframe stats and top market categories with `GET /v1/traders/:address`.
  </Step>

  <Step title="Browse their market history">
    List every market they have traded with `GET /v1/traders/:address/markets`.
  </Step>

  <Step title="Inspect orders in a specific market">
    Retrieve individual fills with `GET /v1/traders/:address/markets/:id/orders`.
  </Step>
</Steps>

***

## 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`.

<CodeGroup>
  ```javascript profile.js theme={null}
  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`);
  }
  ```

  ```python profile.py theme={null}
  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")
  ```
</CodeGroup>

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

<CodeGroup>
  ```javascript markets.js theme={null}
  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}`);
  }
  ```

  ```python markets.py theme={null}
  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']}")
  ```
</CodeGroup>

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

<CodeGroup>
  ```javascript orders.js theme={null}
  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}`);
  }
  ```

  ```python orders.py theme={null}
  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}")
  ```
</CodeGroup>

### 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

```json theme={null}
{
  "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"
    }
  ]
}
```