Retrieves a paginated leaderboard of users ranked by total payout amounts for a specific currency.

When to Use This Endpoint

• Displaying top earners in your affiliate/referral program
• Building leaderboard UI components showing user rankings
• Analyzing payout distribution across users
• Identifying high-performing affiliates or users
• Filtering leaderboards by user type (affiliates vs end-users)

When NOT to Use This Endpoint

• Getting a single user's payout data (use GET /v1/payouts/totals/{userIdentifier})
• Fetching all payouts without ranking (use GET /v1/payouts)
• Real-time leaderboard updates (this endpoint is cached)

Important Constraints

• Rate Limit: 60 requests/minute
• Caching: Results cached for 1 minute for performance
• Currency Required: Must specify currency_address to filter results
• Pagination: Default page size is 25, max is 100
• Ranking: Users ranked by total payout amount in descending order

Optional Features

• User Filtering: Filter by specific user with user_identifier
• User Type: Filter by affiliate or end_user
• Extra Fields: Include tier, referred_volume, or referred_users data

Caching Behavior

Results are cached for 60 seconds:

• Multiple requests within 60s return same data
• Real-time accuracy: ±1 minute
• Cache applies per unique parameter combination

Common Errors

• 400 Bad Request: Missing currency_address parameter or invalid format
• 403 Forbidden: API key lacks required permissions
• 404 Not Found: Currency address not found in project

Related Endpoints

• GET /v1/payouts/leaderboard/points - Points-based leaderboard
• GET /v1/payouts/leaderboard/volume - Volume-based leaderboard
• GET /v1/payouts/leaderboard/revenue - Revenue-based leaderboard
• GET /v1/payouts/totals/{userIdentifier} - Individual user payouts