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

# Leaderboard

> Find and follow top-performing traders using the PolyEdge leaderboard.

The leaderboard endpoint surfaces the highest-performing Polymarket traders for any rolling time window. Use it to discover "smart money," build watchlists, or seed your own analytics pipeline.

**Endpoint:** `GET /v1/analytics/leaderboard`

## Filters

Combine filters to zero in on the traders that matter to your strategy.

| Parameter                               | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                            |
| --------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `time_frame`                            | string | Rolling window for stats: `1H`, `4H`, `1D`, `3D`, `7D`, `30D`. Default: `30D`.                                                                                                                                                                                                                                                                                                                         |
| `sort_by`                               | string | Rank by `pnl`, `roi`, `win_rate`, or `market_count`. Default: `pnl`.                                                                                                                                                                                                                                                                                                                                   |
| `tag`                                   | string | Market category: `all`, `sports`, `crypto`, `geopolitics`, `politics`, `finance`, `esports`, `pop-culture`, `tech`, `economy`, `weather`, `elections`, `tweets-markets`, `basketball`, `hockey`, `soccer`, `tennis`, `counter-strike-2`, `dota-2`, `league-of-legends`, `5M`, `15M`. Default: `all`. *Note: The `sports` tag filters for traditional sports only and does not include `esports` data.* |
| `min_win_rate` / `max_win_rate`         | float  | Win rate range (0–100).                                                                                                                                                                                                                                                                                                                                                                                |
| `min_roi` / `max_roi`                   | float  | ROI percentage range.                                                                                                                                                                                                                                                                                                                                                                                  |
| `last_active_hours`                     | int    | Only include traders who placed an order in the last N hours.                                                                                                                                                                                                                                                                                                                                          |
| `min_market_count` / `max_market_count` | int    | Filter by number of markets traded in the window.                                                                                                                                                                                                                                                                                                                                                      |
| `min_pnl`                               | int    | Minimum PnL filter in USDC.                                                                                                                                                                                                                                                                                                                                                                            |
| `limit`                                 | int    | Results per page. Default: `50`, max: `100`.                                                                                                                                                                                                                                                                                                                                                           |
| `offset`                                | int    | Pagination offset. Default: `0`.                                                                                                                                                                                                                                                                                                                                                                       |

<Note>
  On the **Demo tier**, `limit` is capped at `20` and `offset` must be `0`. Upgrade your plan to paginate beyond the first page.
</Note>

## Code examples

<CodeGroup>
  ```javascript leaderboard.js theme={null}
  import PolyEdgeClient from './polyedge.js';

  const client = new PolyEdgeClient('YOUR_API_KEY');

  const leaderboard = await client.getLeaderboard({
    time_frame: '7D',
    tag: 'crypto',
    sort_by: 'roi',
    min_win_rate: 55,
    min_market_count: 5,
    limit: 10,
  });

  for (const trader of leaderboard.traders) {
    console.log(`#${trader.rank} ${trader.profile.name}`);
    console.log(`  ROI: ${trader.roi}% | Win rate: ${trader.win_rate}% | Markets: ${trader.markets_count}`);
  }
  ```

  ```python leaderboard.py theme={null}
  from polyedge import PolyEdgeClient

  client = PolyEdgeClient('YOUR_API_KEY')

  leaderboard = client.get_leaderboard({
      'time_frame': '7D',
      'tag': 'crypto',
      'sort_by': 'roi',
      'min_win_rate': 55,
      'min_market_count': 5,
      'limit': 10,
  })

  for trader in leaderboard['traders']:
      print(f"#{trader['rank']} {trader['profile']['name']}")
      print(f"  ROI: {trader['roi']}% | Win rate: {trader['win_rate']}% | Markets: {trader['markets_count']}")
  ```

  ```bash curl theme={null}
  curl -G "https://api.polyedge.dev/v1/analytics/leaderboard" \
    -H "X-PolyEdge-Key: YOUR_API_KEY" \
    --data-urlencode "time_frame=7D" \
    --data-urlencode "tag=crypto" \
    --data-urlencode "sort_by=roi" \
    --data-urlencode "min_win_rate=55" \
    --data-urlencode "min_market_count=5" \
    --data-urlencode "limit=10"
  ```
</CodeGroup>

## Response fields

Each object in the `traders` array contains:

| Field           | Type   | Description                                                                                               |
| --------------- | ------ | --------------------------------------------------------------------------------------------------------- |
| `rank`          | int    | Position on the leaderboard for the requested window.                                                     |
| `profile`       | object | Trader metadata: `address`, `name`, `profile_image`, `x_username`, `profile_created_at`, `last_trade_at`. |
| `total_pnl`     | string | Raw profit and loss in micro-USDC (divide by `1e6` for USDC).                                             |
| `total_volume`  | string | Total volume traded in micro-USDC.                                                                        |
| `roi`           | float  | Return on investment as a percentage.                                                                     |
| `win_rate`      | float  | Percentage of markets that resolved in the trader's favour.                                               |
| `markets_count` | int    | Number of markets traded in the window.                                                                   |
| `wins_count`    | int    | Number of markets won in the window.                                                                      |

### Example response

```json theme={null}
{
  "traders": [
    {
      "profile": {
        "address": "0x96cfcb0c30942cfcd1cdf76c7d408794d66b1acb",
        "name": "mintblade",
        "profile_image": "",
        "x_username": "",
        "profile_created_at": "2026-06-02T14:47:45.193735Z",
        "last_trade_at": "2026-06-16T01:04:03Z"
      },
      "total_pnl": "9109604596452",
      "total_volume": "8522915083091",
      "roi": 106.88,
      "win_rate": 100,
      "rank": 1,
      "markets_count": 4,
      "wins_count": 4
    }
  ],
  "total_count": 229094
}
```

<Tip>
  Combine `min_win_rate`, `min_roi`, and a short `time_frame` (e.g. `1D`) to surface traders who are hot right now rather than those coasting on months-old gains. Then cross-reference with `last_active_hours` to confirm they are still active before you copy a position.
</Tip>