🪙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:

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:

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

total_amount is already formatted with the token's decimals.

Add extra fields like tier and volume:

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

await Fuul.getPayoutsLeaderboard({
  currency_address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // required on every call
  user_identifier: '0x1234...',
  identifier_type: 'evm_address',
  fields: 'tier,referred_volume,referred_users',
});

Payouts grouped by conversion

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)

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
getUserPayoutsByConversion	GET /v1/payouts	View
getUserPayoutMovements	GET /v1/payouts/movements	View