> 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/market-intelligence/falcon-leaderboard-api.md).

# Falcon Leaderboard API

### Request Body (JSON)

```json
{
    "agent_id": 584,
    "params": {
        "min_win_rate_15d": "0.45",
        "max_win_rate_15d": "0.95",
        "min_roi_15d": "0",
        "min_total_trades_15d": "50",
        "max_total_trades_15d": "100000",
        "min_pnl_15d": "5000",
        "sort_by": "roi"
    },
    "pagination": {
        "limit": 50,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}
```

### Available Filters

| Parameter              | Type   | Description                                                                                       | Example   |
| ---------------------- | ------ | ------------------------------------------------------------------------------------------------- | --------- |
| `min_roi_15d`          | String | Minimum ROI over the last 15 days                                                                 | `"0.2"`   |
| `min_win_rate_15d`     | String | Minimum win rate over the last 15 days (0–1)                                                      | `"0.45"`  |
| `max_win_rate_15d`     | String | Maximum win rate over the last 15 days (0–1)                                                      | `"0.95"`  |
| `min_total_trades_15d` | String | Minimum trades executed in the last 15 days                                                       | `"50"`    |
| `max_total_trades_15d` | String | Maximum trades executed in the last 15 days                                                       | `"20000"` |
| `min_pnl_15d`          | String | Minimum realized PnL over the last 15 days (USD)                                                  | `"50000"` |
| `sort_by`              | String | Sort metric. Default: `h_score`. Options: `h_score`, `roi`, `pnl`, `win_rate`, `trades`, `sharpe` | `"pnl"`   |

<details>

<summary>Example Request (curl)</summary>

```bash
{
    "agent_id": 584,
    "params": {
        "min_win_rate_15d": "0.45",
        "max_win_rate_15d": "0.95",
        "min_roi_15d": "0",
        "min_total_trades_15d": "50",
        "max_total_trades_15d": "100000",
        "min_pnl_15d": "5000",
        "sort_by": "roi"
    },
    "pagination": {
        "limit": 50,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}
```

</details>

***

### Response Fields

| Field                | Type    | Description                               |
| -------------------- | ------- | ----------------------------------------- |
| `leaderboard_rank`   | Integer | Rank based on Falcon Score                |
| `wallet`             | String  | Trader wallet address                     |
| `tier`               | String  | Falcon trader tier classification         |
| `h_score`            | Decimal | Falcon Score                              |
| `roi_pct_15d`        | Decimal | 15-day return on investment               |
| `win_rate_pct_15d`   | Decimal | 15-day win rate                           |
| `sharpe_ratio_15d`   | Decimal | 15-day Sharpe ratio                       |
| `total_trades_15d`   | Integer | Total trades executed in the last 15 days |
| `markets_traded_15d` | Integer | Unique markets traded                     |
| `total_pnl_15d`      | Decimal | Realized PnL over 15 days                 |
| `total_volume_15d`   | Decimal | Total trading volume                      |
| `trajectory`         | String  | Improving, stable, or declining           |

***

### Notes

* Use the default `sort_by: "h_score"` to identify **consistently high-quality traders**, as the H-Score balances profitability, win rate, risk management, and activity.
* Apply `min_total_trades_15d` to filter out **low-activity wallets**, which helps remove traders who appear successful due to a small number of lucky trades.
* Combine `min_roi_15d` with `min_win_rate_15d` to identify traders with both **strong returns and high accuracy**.
* Use `min_pnl_15d` to filter for traders generating **meaningful realized profits**, especially when analyzing top-performing wallets.
* Adjust `sort_by` to analyze different aspects of performance, for example:\
  \- `roi` to rank by highest returns\
  \- `pnl` to rank by total profit\
  \- `win_rate` to find highly accurate traders\
  \- `sharpe` to prioritize risk-adjusted performance
* Monitor the `trajectory` field to quickly identify traders whose performance is **improving, stable, or declining** over the recent period.