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

> Fetch top-performing traders on Polymarket based on customizable ranking criteria.

Retrieve a ranked list of traders on Polymarket. You can filter by time window, market category, and performance thresholds like minimum ROI or win rate to identify smart money and successful trading patterns across the platform.

```
GET /v1/analytics/leaderboard
```

<ParamField header="X-PolyEdge-Key" type="string" required>
  Your PolyEdge API key.
</ParamField>

## Parameters

<ParamField query="limit" type="integer" default="50">
  Number of results to return. Maximum: `100`.

  <Note>Demo tier: maximum value is `20`.</Note>
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Pagination offset.

  <Note>Demo tier: must be `0`.</Note>
</ParamField>

<ParamField query="time_frame" type="string" default="30D">
  Time frame for ranking. Options: `1H`, `4H`, `1D`, `3D`, `7D`, `30D`.
</ParamField>

<ParamField query="sort_by" type="string" default="pnl">
  Field to sort results by. Options: `pnl`, `roi`, `win_rate`, `market_count`.
</ParamField>

<ParamField query="tag" type="string" default="all">
  Filter the leaderboard by a specific market tag. Options: `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`.

  <Note>The `sports` tag filters for traditional sports only and does not include `esports` data.</Note>
</ParamField>

<ParamField query="min_win_rate" type="float">
  Minimum win rate (0–100).
</ParamField>

<ParamField query="max_win_rate" type="float">
  Maximum win rate (0–100).
</ParamField>

<ParamField query="min_roi" type="float">
  Minimum ROI percentage.
</ParamField>

<ParamField query="max_roi" type="float">
  Maximum ROI percentage.
</ParamField>

<ParamField query="last_active_hours" type="integer">
  Filter to traders who have been active within the last N hours.
</ParamField>

<ParamField query="min_market_count" type="integer">
  Minimum number of markets traded.
</ParamField>

<ParamField query="max_market_count" type="integer">
  Maximum number of markets traded.
</ParamField>

<ParamField query="min_pnl" type="integer">
  Minimum PnL (USDC).
</ParamField>

## Response

<ResponseField name="traders" type="object[]">
  Array of ranked trader objects.

  <Expandable title="properties">
    <ResponseField name="profile" type="object">
      Trader profile metadata.

      <Expandable title="properties">
        <ResponseField name="address" type="string">
          The trader's EVM wallet address.
        </ResponseField>

        <ResponseField name="name" type="string">
          The trader's display name.
        </ResponseField>

        <ResponseField name="profile_image" type="string">
          URL to the trader's profile image.
        </ResponseField>

        <ResponseField name="x_username" type="string">
          The trader's X (Twitter) username, if set.
        </ResponseField>

        <ResponseField name="profile_created_at" type="string">
          ISO 8601 timestamp of when the trader's profile was created.
        </ResponseField>

        <ResponseField name="last_trade_at" type="string">
          ISO 8601 timestamp of the trader's most recent trade.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="total_pnl" type="string">
      Total profit and loss in the selected time frame, expressed in micro-USDC (6 decimal places).
    </ResponseField>

    <ResponseField name="total_volume" type="string">
      Total trading volume in micro-USDC.
    </ResponseField>

    <ResponseField name="roi" type="float">
      Return on investment as a percentage.
    </ResponseField>

    <ResponseField name="win_rate" type="float">
      Percentage of markets traded where the trader was profitable.
    </ResponseField>

    <ResponseField name="rank" type="integer">
      Trader's position on the leaderboard.
    </ResponseField>

    <ResponseField name="markets_count" type="integer">
      Number of markets traded in the selected time frame.
    </ResponseField>

    <ResponseField name="wins_count" type="integer">
      Number of markets where the trader was profitable.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total_count" type="integer">
  Total number of traders matching the query. Use with `limit` and `offset` for pagination.
</ResponseField>

## Example

```bash theme={null}
curl https://api.polyedge.dev/v1/analytics/leaderboard?time_frame=7D&limit=5 \
  -H "X-PolyEdge-Key: YOUR_API_KEY"
```

```json theme={null}
{
  "traders": [
    {
      "profile": {
        "address": "0x50b1db131a24a9d9450bbd0372a95d32ea88f076",
        "name": "blindStaking",
        "profile_image": "",
        "x_username": "",
        "profile_created_at": "2026-03-12T19:53:36Z",
        "last_trade_at": "2026-04-05T01:00:55Z"
      },
      "total_pnl": "1620149290085",
      "total_volume": "2553211530521",
      "roi": 63.46,
      "win_rate": 50,
      "rank": 1,
      "markets_count": 4,
      "wins_count": 2
    },
    {
      "profile": {
        "address": "0xbddf61af533ff524d27154e589d2d7a81510c684",
        "name": "Countryside",
        "profile_image": "",
        "x_username": "",
        "profile_created_at": "2025-11-06T22:44:56Z",
        "last_trade_at": "2026-04-06T03:29:37Z"
      },
      "total_pnl": "782234111611",
      "total_volume": "3637703116635",
      "roi": 30.39,
      "win_rate": 40.43,
      "rank": 2,
      "markets_count": 47,
      "wins_count": 19
    },
    {
      "profile": {
        "address": "0x9f2fe025f84839ca81dd8e0338892605702d2ca8",
        "name": "surfandturf",
        "profile_image": "",
        "x_username": "",
        "profile_created_at": "2026-04-01T06:03:57Z",
        "last_trade_at": "2026-04-06T02:32:33Z"
      },
      "total_pnl": "639292755514",
      "total_volume": "2190632870982",
      "roi": 46.52,
      "win_rate": 61.54,
      "rank": 3,
      "markets_count": 26,
      "wins_count": 16
    },
    {
      "profile": {
        "address": "0x8a6c6811e8937f9e8afc1b9249fa540262c30b3f",
        "name": "0x8a6C6811e8937F9E8aFc1b9249FA540262c30b3f-1771776258725",
        "profile_image": "",
        "x_username": "",
        "profile_created_at": "2026-02-22T16:04:19Z",
        "last_trade_at": "2026-04-06T02:28:21Z"
      },
      "total_pnl": "607299024186",
      "total_volume": "3430098687485",
      "roi": 48.83,
      "win_rate": 60.87,
      "rank": 4,
      "markets_count": 46,
      "wins_count": 28
    },
    {
      "profile": {
        "address": "0x2b3ff45c91540e46fae1e0c72f61f4b049453446",
        "name": "Mentallyillgambld",
        "profile_image": "",
        "x_username": "",
        "profile_created_at": "2024-11-05T20:15:29Z",
        "last_trade_at": "2026-04-05T19:47:05Z"
      },
      "total_pnl": "421561636018",
      "total_volume": "835908056935",
      "roi": 50.43,
      "win_rate": 85.71,
      "rank": 5,
      "markets_count": 7,
      "wins_count": 6
    }
  ],
  "total_count": 202991
}
```