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

# Tokens

Retrieve onchain token rewards for individual users.

### Rewards for a specific user

Use `getPayoutsLeaderboard` filtered by `user_identifier` to get an individual user's token rewards:

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

await Fuul.getPayoutsLeaderboard({
  currency_address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  user_identifier: '0x1234...',
  identifier_type: 'evm_address',
  from: '2024-01-01',                    // Optional
  to: '2024-12-31',                      // Optional
  user_type: 'affiliate',                // Optional: 'affiliate' | 'end_user'
  conversion_external_ids: [1, 2, 3],    // Optional: filter by conversion IDs
});
```

Example response:

```json
{
  "total_results": 1,
  "page": 1,
  "page_size": 10,
  "results": [
    {
      "address": "0x1234...",
      "total_amount": 200,
      "rank": 1,
      "total_attributions": 10
    }
  ]
}
```

{% hint style="info" %}
`total_amount` is already formatted with the token's decimals.
{% endhint %}

Add extra fields like tier and volume:

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

await Fuul.getPayoutsLeaderboard({
  user_identifier: '0x1234...',
  identifier_type: 'evm_address',
  fields: 'tier,referred_volume,referred_users',
});
```

### Payouts grouped by conversion

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

await Fuul.getUserPayoutsByConversion({
  user_identifier: '0x1234...',
  identifier_type: 'evm_address',
  from: '2024-01-01',
  to: '2024-12-31',
});
```

### Payout history (movements)

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

await Fuul.getUserPayoutMovements({
  user_identifier: '0x1234...',
  identifier_type: 'evm_address',
});
```

Each movement includes a `payout_status` field indicating where the payout is in its lifecycle:

| Status                         | Description                                         |
| ------------------------------ | --------------------------------------------------- |
| `pending_recipient_acceptance` | Waiting for the recipient to accept the reward      |
| `pending_approval`             | Waiting for project admin approval                  |
| `pending_transaction`          | Approved, waiting for the transaction to be sent    |
| `sending_transaction`          | Transaction is being sent to the blockchain         |
| `pending_confirmation`         | Transaction sent, waiting for on-chain confirmation |
| `confirmed`                    | Payout confirmed successfully                       |
| `failed`                       | Transaction failed                                  |
| `rejected`                     | Payout rejected by admin or system                  |
| `deferred`                     | Payout deferred (e.g., below minimum threshold)     |

## API reference

| SDK method                   | API endpoint                          | Reference                                                           |
| ---------------------------- | ------------------------------------- | ------------------------------------------------------------------- |
| `getPayoutsLeaderboard`      | `GET /v1/payouts/leaderboard/payouts` | [View](https://fuul.readme.io/reference/getpayoutsleaderboard)      |
| `getUserPayoutsByConversion` | `GET /v1/payouts`                     | [View](https://fuul.readme.io/reference/getuserpayoutsbyconversion) |
| `getUserPayoutMovements`     | `GET /v1/payouts/movements`           | [View](https://fuul.readme.io/reference/getuserpayoutmovements)     |