> For the complete documentation index, see [llms.txt](https://falcon-bot.gitbook.io/falcon-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://falcon-bot.gitbook.io/falcon-api/traders/top-traders.md).

# Top Traders

### Request Body (JSON)

```json
{
    "agent_id": 579,
    "params": {
        "wallet_address": "ALL",
        "leaderboard_period": "1d"
    },
    "pagination": {
        "limit": 50,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}
```

***

### Available Filters

| Parameter            | Type   | Description                                               | Example         |
| -------------------- | ------ | --------------------------------------------------------- | --------------- |
| `wallet_address`     | String | Wallet address filter. Use `"ALL"` to return all traders. | `"0xabc123..."` |
| `leaderboard_period` | String | Ranking window. Allowed values: `1d`, `3d`, `7d`, `30d`   | `"7d"`          |
| `min_total_pnl`      | String | Minimum total PnL filter (inclusive).                     | `"100"`         |
| `max_total_pnl`      | String | Maximum total PnL filter (inclusive).                     | `"1000"`        |
| `min_win_rate`       | String | Minimum win rate (0–1).                                   | `"0.5"`         |
| `max_win_rate`       | String | Maximum win rate (0–1).                                   | `"0.9"`         |
| `min_sharpe_ratio`   | String | Minimum Sharpe ratio.                                     | `"1.0"`         |
| `max_sharpe_ratio`   | String | Maximum Sharpe ratio.                                     | `"2.0"`         |

<details>

<summary>Example Request <strong>(cURL)</strong></summary>

```bash
curl --location 'https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
    "agent_id": 579,
    "params": {
        "wallet_address": "ALL",
        "leaderboard_period": "1d"
    },
    "pagination": {
        "limit": 50,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}'
```

</details>

***

### Example Use Cases

#### 1. Full 7 Day Leaderboard

Retrieve the top performing traders across the entire platform over the past 7 days.

```
{
  "agent_id": 579,
  "params": {
    "wallet_address": "ALL",
    "leaderboard_period": "7d"
  }
}
```

#### 2. High Performance Traders

Retrieve traders with strong performance metrics such as high PnL, win rate, and Sharpe ratio.

```
{
  "agent_id": 579,
  "params": {
    "wallet_address": "ALL",
    "leaderboard_period": "30d",
    "min_total_pnl": "1000",
    "min_win_rate": "0.5",
    "min_sharpe_ratio": "1.5"
  }
}
```

#### 3. Single Wallet Lookup

Retrieve leaderboard metrics for a specific wallet.

```
{
  "agent_id": 579,
  "params": {
    "wallet_address": "0x123...",
    "leaderboard_period": "1d"
  }
}
```

***

### Response Fields

| Field            | Type             | Description                               |
| ---------------- | ---------------- | ----------------------------------------- |
| `rank`           | Integer          | Trader ranking within the selected period |
| `address`        | String           | Wallet address                            |
| `total_pnl`      | String (Decimal) | Total profit and loss                     |
| `roi`            | String (Decimal) | Return on investment                      |
| `win_rate`       | String (Decimal) | Win percentage                            |
| `sharpe_ratio`   | String (Decimal) | Risk-adjusted return metric               |
| `total_volume`   | String (Decimal) | Total trading volume                      |
| `markets_traded` | Integer          | Number of unique markets traded           |
| `total_trades`   | Integer          | Total number of executed trades           |

<details>

<summary>Example Response</summary>

```bash
{
  "timestamp": "",
  "params": {
    "leaderboard_period": "1d",
    "max_sharpe_ratio": "-1.0",
    "max_total_pnl": "-1.0",
    "max_win_rate": "-1.0",
    "min_sharpe_ratio": "-1.0",
    "min_total_pnl": "-1.0",
    "min_win_rate": "-1.0",
    "wallet_address": "ALL"
  },
  "pagination": {
    "limit": 50,
    "offset": 0,
    "has_more": true
  },
  "data": {
    "results": [
      {
        "address": "0x0720803c7cb0d0c5a928787b3b7ea148c6831cdb",
        "markets_traded": 1,
        "rank": 1,
        "roi": "0.414952",
        "sharpe_ratio": null,
        "total_pnl": "1494121.7168",
        "total_trades": 69,
        "total_volume": "3600711.99",
        "win_rate": "1.0000"
      },
      {
        "address": "0xe90bec87d9ef430f27f9dcfe72c34b76967d5da2",
        "markets_traded": 50,
        "rank": 2,
        "roi": "0.355880",
        "sharpe_ratio": "0.2847",
        "total_pnl": "1092294.3287",
        "total_trades": 1829,
        "total_volume": "3069274.68",
        "win_rate": "0.6290"
      },
      {
        "address": "0xdc876e6873772d38716fda7f2452a78d426d7ab6",
        "markets_traded": 78,
        "rank": 3,
        "roi": "0.793496",
        "sharpe_ratio": "0.1526",
        "total_pnl": "425301.6430",
        "total_trades": 1662,
        "total_volume": "535984.74",
        "win_rate": "0.5275"
      },
      {
        "address": "0x07b8e44b90cc3e91b8d5fe60ea810d2534638e25",
        "markets_traded": 12,
        "rank": 4,
        "roi": "0.806624",
        "sharpe_ratio": "0.2070",
        "total_pnl": "418635.9796",
        "total_trades": 386,
        "total_volume": "518997.59",
        "win_rate": "0.6875"
      },
      {
        "address": "0xe20a1538293903b746ffe6c4ce2d5c3c0300e469",
        "markets_traded": 11,
        "rank": 5,
        "roi": "0.810739",
        "sharpe_ratio": "0.4343",
        "total_pnl": "390127.1799",
        "total_trades": 132,
        "total_volume": "481199.58",
        "win_rate": "0.5294"
      },
      {
        "address": "0xead152b855effa6b5b5837f53b24c0756830c76a",
        "markets_traded": 252,
        "rank": 6,
        "roi": "0.212866",
        "sharpe_ratio": "0.0548",
        "total_pnl": "297035.2810",
        "total_trades": 11394,
        "total_volume": "1395408.27",
        "win_rate": "0.5000"
      },
      {
        "address": "0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd",
        "markets_traded": 27,
        "rank": 7,
        "roi": "0.172945",
        "sharpe_ratio": "0.0856",
        "total_pnl": "235485.7051",
        "total_trades": 1905,
        "total_volume": "1361619.99",
        "win_rate": "0.6667"
      },
      {
        "address": "0xc29e1cef4256f423e5a3e713d886bd25f98da2ca",
        "markets_traded": 7,
        "rank": 8,
        "roi": "9.010307",
        "sharpe_ratio": "0.3114",
        "total_pnl": "216247.3168",
        "total_trades": 42,
        "total_volume": "23999.99",
        "win_rate": "0.5000"
      },
      {
        "address": "0x507e52ef684ca2dd91f90a9d26d149dd3288beae",
        "markets_traded": 661,
        "rank": 9,
        "roi": "0.148986",
        "sharpe_ratio": "0.0488",
        "total_pnl": "215344.9641",
        "total_trades": 10517,
        "total_volume": "1445402.83",
        "win_rate": "0.6104"
      },
      {
        "address": "0x02227b8f5a9636e895607edd3185ed6ee5598ff7",
        "markets_traded": 2,
        "rank": 10,
        "roi": "0.920197",
        "sharpe_ratio": "0.8352",
        "total_pnl": "204722.6511",
        "total_trades": 115,
        "total_volume": "222476.93",
        "win_rate": "1.0000"
      },
      {
        "address": "0xc6b6ffce6c52b6fdf4bad57de303939f19ab13ac",
        "markets_traded": 3,
        "rank": 11,
        "roi": "0.898256",
        "sharpe_ratio": "0.3935",
        "total_pnl": "175596.6445",
        "total_trades": 7,
        "total_volume": "195486.27",
        "win_rate": "0.3333"
      },
      {
        "address": "0x036c159d5a348058a81066a76b89f35926d4178d",
        "markets_traded": 11,
        "rank": 12,
        "roi": "0.688563",
        "sharpe_ratio": "0.3490",
        "total_pnl": "164119.9660",
        "total_trades": 330,
        "total_volume": "238351.52",
        "win_rate": "0.5000"
      },
      {
        "address": "0x72b40c0012682ef52228ad53ef955f9e4f177d67",
        "markets_traded": 15,
        "rank": 13,
        "roi": "0.467228",
        "sharpe_ratio": "0.4330",
        "total_pnl": "154761.7835",
        "total_trades": 611,
        "total_volume": "331233.75",
        "win_rate": "0.5248"
      },
      {
        "address": "0x84dbb7103982e3617704a2ed7d5b39691952aeeb",
        "markets_traded": 34,
        "rank": 14,
        "roi": "0.253102",
        "sharpe_ratio": "0.1606",
        "total_pnl": "140282.5504",
        "total_trades": 1354,
        "total_volume": "554253.25",
        "win_rate": "0.7130"
      },
      {
        "address": "0xd008786fad743d0d5c60f99bff5d90ebc212135d",
        "markets_traded": 6,
        "rank": 15,
        "roi": "4.102874",
        "sharpe_ratio": "0.4307",
        "total_pnl": "123274.8510",
        "total_trades": 13,
        "total_volume": "30045.97",
        "win_rate": "1.0000"
      },
      {
        "address": "0x0b9cae2b0dfe7a71c413e0604eaac1c352f87e44",
        "markets_traded": 11,
        "rank": 16,
        "roi": "0.055427",
        "sharpe_ratio": "0.1032",
        "total_pnl": "120654.3619",
        "total_trades": 1438,
        "total_volume": "2176834.17",
        "win_rate": "0.7143"
      },
      {
        "address": "0x916f7165c2c836aba22edb6453cdbb5f3ea253ba",
        "markets_traded": 8,
        "rank": 17,
        "roi": "0.264655",
        "sharpe_ratio": "0.1728",
        "total_pnl": "114438.2631",
        "total_trades": 1305,
        "total_volume": "432405.58",
        "win_rate": "0.6000"
      },
      {
        "address": "0xada56a3f1a9d7d3fe7ec8cbcaa0865109c57db70",
        "markets_traded": 340,
        "rank": 18,
        "roi": "0.160821",
        "sharpe_ratio": "0.0381",
        "total_pnl": "107071.3693",
        "total_trades": 8866,
        "total_volume": "665778.32",
        "win_rate": "0.4641"
      },
      {
        "address": "0xae8758cf74d46eb0c9d889e50f1a089b1e3bc735",
        "markets_traded": 1,
        "rank": 19,
        "roi": "1.200635",
        "sharpe_ratio": "0.7071",
        "total_pnl": "102582.7799",
        "total_trades": 138,
        "total_volume": "85440.46",
        "win_rate": "1.0000"
      },
      {
        "address": "0x08c59894c5e32f0e5406799e49a9a33f4b7643ed",
        "markets_traded": 32,
        "rank": 20,
        "roi": "0.394849",
        "sharpe_ratio": "0.2245",
        "total_pnl": "100362.4198",
        "total_trades": 206,
        "total_volume": "254178.93",
        "win_rate": "0.7778"
      },
      {
        "address": "0x336151559e8c8b048de5231dc8313e196b314363",
        "markets_traded": 136,
        "rank": 21,
        "roi": "0.171249",
        "sharpe_ratio": "0.1032",
        "total_pnl": "98854.9563",
        "total_trades": 1412,
        "total_volume": "577258.58",
        "win_rate": "1.0000"
      },
      {
        "address": "0x6a72f61820b26b1fe4d956e17b6dc2a1ea3033ee",
        "markets_traded": 3,
        "rank": 22,
        "roi": "1.127635",
        "sharpe_ratio": "0.4472",
        "total_pnl": "95399.3301",
        "total_trades": 872,
        "total_volume": "84601.27",
        "win_rate": "0.6667"
      },
      {
        "address": "0x1979ae6b7e6534de9c4539d0c205e582ca637c9d",
        "markets_traded": 2357,
        "rank": 23,
        "roi": "0.014165",
        "sharpe_ratio": "0.0093",
        "total_pnl": "72119.3651",
        "total_trades": 254504,
        "total_volume": "5091261.32",
        "win_rate": "0.5038"
      },
      {
        "address": "0x53757615de1c42b83f893b79d4241a009dc2aeea",
        "markets_traded": 8,
        "rank": 24,
        "roi": "4.945936",
        "sharpe_ratio": "0.3879",
        "total_pnl": "69435.9842",
        "total_trades": 66,
        "total_volume": "14039.00",
        "win_rate": "0.7500"
      },
      {
        "address": "0x37e4728b3c4607fb2b3b205386bb1d1fb1a8c991",
        "markets_traded": 10,
        "rank": 25,
        "roi": "0.213899",
        "sharpe_ratio": "0.0870",
        "total_pnl": "65064.9751",
        "total_trades": 18,
        "total_volume": "304184.99",
        "win_rate": "0.6000"
      },
      {
        "address": "0xc660ae71765d0d9eaf5fa8328c1c959841d2bd28",
        "markets_traded": 24,
        "rank": 26,
        "roi": "0.150323",
        "sharpe_ratio": "0.0641",
        "total_pnl": "61167.3382",
        "total_trades": 372,
        "total_volume": "406905.14",
        "win_rate": "0.4722"
      },
      {
        "address": "0xcbed92a9dc14802a2957de4a7d81d3c6a038bbb9",
        "markets_traded": 8,
        "rank": 27,
        "roi": "0.592361",
        "sharpe_ratio": "0.5551",
        "total_pnl": "58665.9621",
        "total_trades": 232,
        "total_volume": "99037.46",
        "win_rate": "1.0000"
      },
      {
        "address": "0xc408cf3d54aedccbb5c604fc887a1a8a8d93c1ef",
        "markets_traded": 3,
        "rank": 28,
        "roi": "0.891955",
        "sharpe_ratio": "8.8599",
        "total_pnl": "56096.2558",
        "total_trades": 7,
        "total_volume": "62891.35",
        "win_rate": "1.0000"
      },
      {
        "address": "0x0ea574f3204c5c9c0cdead90392ea0990f4d17e4",
        "markets_traded": 516,
        "rank": 29,
        "roi": "0.035407",
        "sharpe_ratio": "0.0399",
        "total_pnl": "56018.1475",
        "total_trades": 85709,
        "total_volume": "1582119.34",
        "win_rate": "0.5030"
      },
      {
        "address": "0xfc5bc3aa227d4c175f9099c813ec668aaab68ef3",
        "markets_traded": 2,
        "rank": 30,
        "roi": "3.672570",
        "sharpe_ratio": "7.1967",
        "total_pnl": "54721.2949",
        "total_trades": 1,
        "total_volume": "14900.00",
        "win_rate": "1.0000"
      },
      {
        "address": "0xf6963d4cdbb6f26d753bda303e9513132afb1b7d",
        "markets_traded": 1251,
        "rank": 31,
        "roi": "0.060217",
        "sharpe_ratio": "0.0434",
        "total_pnl": "51095.7492",
        "total_trades": 74742,
        "total_volume": "848521.37",
        "win_rate": "0.5088"
      },
      {
        "address": "0xe734d5a008576905ec700019e530a7cc8da88f6a",
        "markets_traded": 2,
        "rank": 32,
        "roi": null,
        "sharpe_ratio": "43.2865",
        "total_pnl": "46682.5820",
        "total_trades": 0,
        "total_volume": "0.00",
        "win_rate": "1.0000"
      },
      {
        "address": "0xa6a856a8c8a7f14fd9be6ae11c367c7cbb755009",
        "markets_traded": 92,
        "rank": 33,
        "roi": "0.168147",
        "sharpe_ratio": "0.1028",
        "total_pnl": "44662.4544",
        "total_trades": 791,
        "total_volume": "265615.68",
        "win_rate": "0.5517"
      },
      {
        "address": "0x7e3a1f95c558f39a51ff334d789e3e039b553246",
        "markets_traded": 7,
        "rank": 34,
        "roi": "0.431479",
        "sharpe_ratio": "0.4358",
        "total_pnl": "44026.7779",
        "total_trades": 10,
        "total_volume": "102036.79",
        "win_rate": "0.7143"
      },
      {
        "address": "0xee613b3fc183ee44f9da9c05f53e2da107e3debf",
        "markets_traded": 549,
        "rank": 35,
        "roi": "0.015356",
        "sharpe_ratio": "0.0057",
        "total_pnl": "42537.8556",
        "total_trades": 16310,
        "total_volume": "2770031.47",
        "win_rate": "0.5060"
      },
      {
        "address": "0xfbf3d501e88815464642d0e913f15379c3eeb218",
        "markets_traded": 4,
        "rank": 36,
        "roi": "1.383533",
        "sharpe_ratio": "0.4498",
        "total_pnl": "41905.0778",
        "total_trades": 60,
        "total_volume": "30288.46",
        "win_rate": "0.6667"
      },
      {
        "address": "0x99e42eb9038705165b22f821e27659c1dc41e4c4",
        "markets_traded": 14,
        "rank": 37,
        "roi": "0.773635",
        "sharpe_ratio": "0.2906",
        "total_pnl": "41766.9105",
        "total_trades": 176,
        "total_volume": "53987.85",
        "win_rate": "0.6000"
      },
      {
        "address": "0x34f62ce5beaf9b3b325726ec4b6c733df8534535",
        "markets_traded": 4,
        "rank": 38,
        "roi": "0.763330",
        "sharpe_ratio": "0.9011",
        "total_pnl": "40636.8824",
        "total_trades": 13,
        "total_volume": "53236.32",
        "win_rate": "1.0000"
      },
      {
        "address": "0xbd7d453564deca2bd3b3d51091105e94270dd7d1",
        "markets_traded": 599,
        "rank": 39,
        "roi": "0.033344",
        "sharpe_ratio": "0.0281",
        "total_pnl": "38120.8555",
        "total_trades": 46122,
        "total_volume": "1143274.26",
        "win_rate": "0.5017"
      },
      {
        "address": "0x1461cc6e1a05e20710c416307db62c28f1d122d8",
        "markets_traded": 156,
        "rank": 40,
        "roi": "0.024629",
        "sharpe_ratio": "0.0127",
        "total_pnl": "36862.5173",
        "total_trades": 6472,
        "total_volume": "1496723.27",
        "win_rate": "0.5610"
      },
      {
        "address": "0x66fbe4344c1a9f6029a4e40ffd5ca7848e189f72",
        "markets_traded": 15,
        "rank": 41,
        "roi": "0.420287",
        "sharpe_ratio": "0.2985",
        "total_pnl": "35730.2579",
        "total_trades": 75,
        "total_volume": "85013.98",
        "win_rate": "0.6250"
      },
      {
        "address": "0x571c285a83eba5322b5f916ba681669dc368a61f",
        "markets_traded": 860,
        "rank": 42,
        "roi": "0.077012",
        "sharpe_ratio": "0.0578",
        "total_pnl": "34843.6081",
        "total_trades": 50799,
        "total_volume": "452445.94",
        "win_rate": "0.5118"
      },
      {
        "address": "0xb7844f423abd31bdd70a4664c958762d291b61d0",
        "markets_traded": 16,
        "rank": 43,
        "roi": "0.259345",
        "sharpe_ratio": "0.1640",
        "total_pnl": "34574.0611",
        "total_trades": 238,
        "total_volume": "133312.77",
        "win_rate": "0.1452"
      },
      {
        "address": "0xfa21179f2cef2f61cb78e8340ae62b17f9271438",
        "markets_traded": 36,
        "rank": 44,
        "roi": "0.280238",
        "sharpe_ratio": "0.1264",
        "total_pnl": "33877.3353",
        "total_trades": 133,
        "total_volume": "120887.88",
        "win_rate": "0.7732"
      },
      {
        "address": "0x8a3ab8120807bd64a3de48695110e390fa2ceb9a",
        "markets_traded": 2,
        "rank": 45,
        "roi": null,
        "sharpe_ratio": "6.1861",
        "total_pnl": "33347.8215",
        "total_trades": 0,
        "total_volume": "0.00",
        "win_rate": "1.0000"
      },
      {
        "address": "0x1d0034134e339a309700ff2d34e99fa2d48b0313",
        "markets_traded": 2190,
        "rank": 46,
        "roi": "0.009423",
        "sharpe_ratio": "0.0074",
        "total_pnl": "33119.7173",
        "total_trades": 246678,
        "total_volume": "3514906.29",
        "win_rate": "0.4999"
      },
      {
        "address": "0x2005d16a84ceefa912d4e380cd32e7ff827875ea",
        "markets_traded": 360,
        "rank": 47,
        "roi": "0.046575",
        "sharpe_ratio": "0.0141",
        "total_pnl": "32984.9438",
        "total_trades": 4883,
        "total_volume": "708215.91",
        "win_rate": "0.5044"
      },
      {
        "address": "0x14ac84b66a27fc30e56ed620ebfa61cd8105cb21",
        "markets_traded": 33,
        "rank": 48,
        "roi": "0.185266",
        "sharpe_ratio": "0.1729",
        "total_pnl": "32488.4525",
        "total_trades": 500,
        "total_volume": "175361.53",
        "win_rate": "0.2143"
      },
      {
        "address": "0xd0d6053c3c37e727402d84c14069780d360993aa",
        "markets_traded": 1850,
        "rank": 49,
        "roi": "0.013672",
        "sharpe_ratio": "0.0084",
        "total_pnl": "31681.1986",
        "total_trades": 265115,
        "total_volume": "2317160.25",
        "win_rate": "0.2005"
      },
      {
        "address": "0x88d17ad6bf91ca0935f6e70b37ebe3db92b618da",
        "markets_traded": 15,
        "rank": 50,
        "roi": "0.287019",
        "sharpe_ratio": "0.7203",
        "total_pnl": "31676.5981",
        "total_trades": 110,
        "total_volume": "110363.98",
        "win_rate": "0.8824"
      }
    ]
  }
}
```

</details>

***

### Notes

* Use `leaderboard_period` to control the **time window for rankings**. Shorter periods (e.g. `1d`, `3d`) highlight recent performance, while longer periods (e.g. `7d`, `30d`) provide a broader view of trading consistency.
* Apply `min_total_pnl` and `max_total_pnl` to **filter traders by profitability**, which helps isolate top performers or remove low-activity wallets.
* Use `min_win_rate` and `max_win_rate` to **analyze trader accuracy**, especially when evaluating wallets for copy trading strategies.
* Combine `min_sharpe_ratio` with profit filters to identify **traders with strong risk-adjusted performance**, not just high returns.
* Set `wallet_address` to `"ALL"` to retrieve the **full leaderboard**, or provide a specific wallet to quickly check its ranking and performance metrics.
* Compare `roi`, `total_pnl`, and `sharpe_ratio` together to better understand **profitability versus risk efficiency**.