💯Leaderboard Data

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

Leaderboard	SDK method	What it ranks
Tokens	getPayoutsLeaderboard	Onchain token rewards earned
Points	getPointsLeaderboard	Point rewards earned
Volume	getVolumeLeaderboard	Trading/transaction volume generated
Revenue	getRevenueLeaderboard	Revenue generated, e.g. fees
Referred users	getReferredUsersLeaderboard	Number of users referred (GET /v1/leaderboard/referred)

getReferredUsersLeaderboard is the one leaderboard that does not sit under /v1/payouts. Its endpoint is GET /v1/leaderboard/referred.

Leaderboard data is updated hourly. Recent conversions and payouts will appear within a maximum of one hour.

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

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.

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.