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

# Tag Leaderboard

> Rank wallets by P&L within a specific market category (tag). Works for niche tags.

Returns a P\&L leaderboard filtered to markets with a specific tag. This direct tag route is best for smaller/niche tags.

<Note>
  For broad tags or categories such as `crypto`, `sports`, or `politics`, use the projected global leaderboard with `?tags=` or `?category=`. It is the preferred route for high-cardinality leaderboard filters.
</Note>

## Request

```
GET /v3/tags/{slug}/leaderboard
```

### Query parameters

| Parameter | Type    | Default   | Description                                                |
| --------- | ------- | --------- | ---------------------------------------------------------- |
| `sort`    | string  | `net_pnl` | Sort by `net_pnl` (default), `volume`, `profit`, or `loss` |
| `limit`   | integer | 100       | Max 300                                                    |
| `offset`  | integer | 0         | Pagination offset                                          |

### Slug handling

The tag slug is matched case-insensitively. URL-style hyphens are also converted to spaces, so `/v3/tags/us-election/leaderboard` resolves to the stored tag `US Election`.

### Broad tag alternative

```bash theme={null}
curl "https://api.polynode.dev/v3/leaderboard?tags=crypto&limit=20"
curl "https://api.polynode.dev/v3/leaderboard?category=crypto&limit=20"
```

Use [`GET /v3/leaderboard`](/data/leaderboard/global) for broad tag/category rankings or pick a more specific tag for this route.

## Example

```bash theme={null}
curl https://api.polynode.dev/v3/tags/taylor-swift/leaderboard?limit=1
```

```json theme={null}
{
  "data": [
    {
      "wallet": "0x4aec3e3c555ecbeec58adba532e8ea8b1c76e9b6",
      "net_pnl": "60212.914000000000",
      "gross_profit": "60212.914000000000",
      "gross_loss": "0.000000000000000000",
      "total_volume": "62721.000000000000",
      "position_count": 3
    }
  ],
  "rows_returned": 1,
  "has_more": true,
  "offset": 0,
  "limit": 1,
  "elapsed_ms": 26
}
```

## Response fields (per row in `data`)

| Field            | Type             | Description                                     |
| ---------------- | ---------------- | ----------------------------------------------- |
| `wallet`         | string           | Wallet address                                  |
| `net_pnl`        | string (decimal) | Net realized P\&L in this tag (USD)             |
| `gross_profit`   | string (decimal) | Sum of winning positions (USD)                  |
| `gross_loss`     | string (decimal) | Sum of losing positions (USD, negative or zero) |
| `total_volume`   | string (decimal) | Total volume traded in this tag (USD)           |
| `position_count` | integer          | Number of positions in markets with this tag    |