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

# Leaderboard

> Rank all Polymarket wallets by P&L, volume, profit, or win count. Supports one primary market filter dimension per request. All amounts in USD.

Ranks wallets by realized P\&L, total P\&L (realized + unrealized), gross profit, volume, or win count. All monetary values are in USD.

<Note>
  Leaderboard filters are designed around one primary dimension per request. Use one of `category`, `tags`/`tag_slug`, `market`/`market_slug`, `event_slug`, or `condition_id`. For compound analysis, run separate leaderboard calls or filter client-side.
</Note>

## Request

```
GET /v3/leaderboard
```

### Query parameters

| Parameter      | Type    | Default | Description                                                                                                                                     |
| -------------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `sort`         | string  | `total` | Sort by: `total`, `total_pnl`, `realized`, `profit`, `loss`, `volume`, `wins`, `positions`, `unrealized`                                        |
| `category`     | string  | --      | Filter to one market category, case-insensitive                                                                                                 |
| `tags`         | string  | --      | Filter to one tag slug. Comma-separated multi-tag filters may be accepted for specific cases, but one tag is the recommended leaderboard shape. |
| `tag_slug`     | string  | --      | Alias for a single `tags` value                                                                                                                 |
| `market`       | string  | --      | Filter by condition ID or market slug                                                                                                           |
| `market_slug`  | string  | --      | Filter by market slug                                                                                                                           |
| `event_slug`   | string  | --      | Filter by parent event slug                                                                                                                     |
| `condition_id` | string  | --      | Filter by market condition ID                                                                                                                   |
| `limit`        | integer | 100     | Max 300                                                                                                                                         |
| `offset`       | integer | 0       | Pagination offset                                                                                                                               |

## Example

```bash theme={null}
curl https://api.polynode.dev/v3/leaderboard?limit=2&sort=total
```

### Filter by one dimension

```bash theme={null}
curl "https://api.polynode.dev/v3/leaderboard?category=crypto&limit=20"
curl "https://api.polynode.dev/v3/leaderboard?tag_slug=us-election&limit=20"
curl "https://api.polynode.dev/v3/leaderboard?market_slug=will-donald-trump-win-the-popular-vote-in-the-2024-presidential-election&limit=20"
curl "https://api.polynode.dev/v3/leaderboard?event_slug=presidential-election-popular-vote-winner-2024&limit=20"
```

```json theme={null}
{
  "leaderboard": [
    {
      "rank": 1,
      "wallet": "0x56687bf447db6ffa42ffe2204a05edaa20f55839",
      "net_realized_pnl": 22053845.825455,
      "gross_profit": 22057977.181649,
      "gross_loss": -4131.356194,
      "unrealized_pnl": 0.000688755,
      "total_pnl": 22053845.826143753,
      "wins": 18,
      "losses": 4,
      "position_count": 22,
      "open_positions": 1,
      "total_volume": 43013258.515682
    }
  ],
  "rows_returned": 1,
  "has_more": true,
  "offset": 0,
  "limit": 2,
  "elapsed_ms": 1028
}
```

## Response fields

| Field              | Type    | Description                               |
| ------------------ | ------- | ----------------------------------------- |
| `rank`             | integer | Position in the leaderboard               |
| `wallet`           | string  | Wallet address                            |
| `net_realized_pnl` | number  | Net realized P\&L (USD)                   |
| `gross_profit`     | number  | Sum of winning positions (USD)            |
| `gross_loss`       | number  | Sum of losing positions (USD, negative)   |
| `unrealized_pnl`   | number  | Paper P\&L from open positions (USD)      |
| `total_pnl`        | number  | `net_realized_pnl + unrealized_pnl` (USD) |
| `wins`             | integer | Winning position count                    |
| `losses`           | integer | Losing position count                     |
| `position_count`   | integer | Total positions                           |
| `open_positions`   | integer | Currently held positions                  |
| `total_volume`     | number  | Total volume traded (USD)                 |