> 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/tokens.md).

# Tokens

Retrieve the onchain token payouts leaderboard using the `getPayoutsLeaderboard` method.

```typescript
import { Fuul } from '@fuul/sdk';

await Fuul.getPayoutsLeaderboard({
  currency_address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  user_type: 'affiliate',
});
```

Example response:

```json
{
  "total_results": 156,
  "page": 1,
  "page_size": 10,
  "results": [
    {
      "address": "0x1234...",
      "total_amount": 5200.50,
      "rank": 1,
      "total_attributions": 48
    },
    {
      "address": "0x5678...",
      "total_amount": 3100.25,
      "rank": 2,
      "total_attributions": 31
    }
  ]
}
```

| Parameter          | Required | Description                                                           |
| ------------------ | -------- | --------------------------------------------------------------------- |
| `currency_address` | Yes      | Token contract address on the payout chain                            |
| `user_type`        | No       | `'affiliate'` or `'end_user'`                                         |
| `fields`           | No       | Extra fields: `'tier,referred_volume,enduser_volume,enduser_revenue'` |

{% hint style="info" %}
Projects can pay out different tokens for different conversions. Use the `currency_address` of the specific token you want to query.
{% endhint %}

{% hint style="info" %}
No `chain_id` is required — the SDK automatically uses the chain where the program is hosted.
{% endhint %}

### With extra fields

```typescript
import { Fuul } from '@fuul/sdk';

await Fuul.getPayoutsLeaderboard({
  currency_address: '0xA0b86...',
  fields: 'tier,referred_volume,enduser_volume,enduser_revenue',
});
```

{% hint style="info" %}
The `referred_volume` values are returned in USD.
{% endhint %}

{% hint style="info" %}
Leaderboard responses are paginated. Use `page` and `page_size` (max 100 per page) to retrieve the full leaderboard.
{% endhint %}

For full endpoint details, see the [API reference](https://fuul.readme.io/reference/getpayoutsleaderboard).