> For the complete documentation index, see [llms.txt](https://docs.fuul.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fuul.xyz/developer-guide/getting-leaderboard-data.md).

# Leaderboard Data

Retrieve and display leaderboard rankings for your incentive programs. Fuul provides five leaderboard types:

| Leaderboard                                                                      | SDK method                    | What it ranks                                             |
| -------------------------------------------------------------------------------- | ----------------------------- | --------------------------------------------------------- |
| [Tokens](/developer-guide/getting-leaderboard-data/tokens.md)                    | `getPayoutsLeaderboard`       | Onchain token rewards earned                              |
| [Points](/developer-guide/getting-leaderboard-data/points.md)                    | `getPointsLeaderboard`        | Point rewards earned                                      |
| [Volume](/developer-guide/getting-leaderboard-data/volume.md)                    | `getVolumeLeaderboard`        | Trading/transaction volume generated                      |
| [Revenue](/developer-guide/getting-leaderboard-data/volume.md#volume-vs-revenue) | `getRevenueLeaderboard`       | Revenue generated, e.g. fees                              |
| Referred users                                                                   | `getReferredUsersLeaderboard` | Number of users referred (`GET /v1/leaderboard/referred`) |

{% hint style="warning" %}
`getReferredUsersLeaderboard` is the one leaderboard that does not sit under `/v1/payouts`. Its endpoint is `GET /v1/leaderboard/referred`.
{% endhint %}

{% hint style="info" %}
Leaderboard data is updated hourly. Recent conversions and payouts will appear within a maximum of one hour.
{% endhint %}

### Common parameters

Filters are not uniform across the five methods. Check the "Supported by" column before passing one:

| Parameter                 | Type      | Supported by                                         | Description                                                                                            |
| ------------------------- | --------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `currency_address`        | string    | **Required** on Tokens · optional on Volume, Revenue | Token contract address on the payout chain                                                             |
| `user_identifier`         | string    | Tokens, Points, Volume, Revenue                      | Filter to a specific user (for individual rewards)                                                     |
| `identifier_type`         | string    | Tokens, Points, Volume, Revenue                      | `'evm_address'`, `'solana_address'`, `'sui_address'`, `'xrpl_address'`, `'stellar_address'`, `'email'` |
| `user_type`               | string    | Tokens, Volume, Revenue                              | `'affiliate'` or `'end_user'` (omit for all)                                                           |
| `fields`                  | string    | Tokens, Points                                       | Comma-separated extra fields: `'tier,referred_volume,enduser_volume,enduser_revenue,referred_users'`   |
| `conversion_external_ids` | number\[] | Tokens                                               | Array of conversion IDs to filter by                                                                   |
| `page` / `page_size`      | number    | All                                                  | Pagination, `page_size` max 100                                                                        |

{% hint style="warning" %}
Two exceptions worth knowing before you write the call:

* `getPayoutsLeaderboard` **requires** `currency_address`. Omitting it is a TypeScript error.
* `getPointsLeaderboard` does not accept `user_type`, `from`, `to`, `currency_address`, or `conversion_external_ids`. Points are ranked across the whole program.
* `getReferredUsersLeaderboard` accepts `page` and `page_size` only — no user or conversion filters.
  {% endhint %}

{% hint style="info" %}
Leaderboard responses are paginated. Use `page` and `page_size` (max 100 per page) to retrieve the full leaderboard — e.g., page 1 returns ranks 1–100, page 2 returns ranks 101–200, and so on.
{% endhint %}