Retrieve the total points (rewards) earned by a specific user across all activities and conversions.

When to Use This Endpoint

• Display user rewards: Show users their total accumulated points in dashboards or profile pages
• Wallet balance lookups: Get a user's current reward balance before they claim
• Progress tracking: Display how many points a user has earned over time
• Leaderboard context: Show individual user totals alongside leaderboard rankings
• Eligibility checks: Determine if a user has enough points to qualify for certain rewards or tiers

When NOT to Use This Endpoint

• Don't use for claimable amounts: Use GET /v1/claim-checks/totals to get on-chain claimable amounts (this endpoint shows total points, not necessarily claimable tokens)
• Don't use for detailed payout history: Use GET /v1/payouts/leaderboard/payouts for paginated payout records with full details
• Don't use for analytics: Use leaderboard endpoints for aggregate analytics across users
• Don't use for real-time conversion tracking: Use GET /v1/conversions/status to check if specific events triggered conversions

How It Works

Returns a single value: total_points - the cumulative sum of all points/rewards earned by the user identifier across:

• Affiliate commissions (if user is an affiliate)
• Referral rewards (if user referred others)
• Direct user rewards (from their own conversions)
• Bonus points from campaigns or promotions

Note: Points are different from claimable token amounts. Points may need to be converted to on-chain tokens via the claim flow.

Important Constraints

• Required API Key Scope: Standard API key (no special scope required)
• Rate Limit: 100 requests/minute (standard rate)
• User Identifier Format: Must be a valid address, email, or custom identifier matching your project configuration
• Points vs Tokens: Response is in points (unit-less), not token amounts with decimals
• No pagination: Returns a single total value, not a list

Response Details

• total_points: String representation of total points earned (can be a large number)
• Returns "0" if user has no points
• Always returns 200 OK even if user not found (returns total_points: "0")

Common Errors

• 400 Bad Request:

  • Invalid user identifier format
  • Malformed userIdentifier parameter

• 401 Unauthorized:

  • Missing or invalid API key

• 404 Not Found:

  • Project not found (API key references non-existent project)

• 429 Too Many Requests: Rate limit exceeded (100 requests/minute)

Related Endpoints

• GET /v1/claim-checks/totals - Get claimable token amounts (on-chain) for a user
• GET /v1/payouts/leaderboard/payouts - Get detailed payout history with pagination
• GET /v1/payouts/summary - Get aggregate summary across all users
• GET /v1/payouts/leaderboard/users - See user's position in leaderboard rankings

Best Practices

1. Use for display only: This endpoint is optimized for showing user balances, not for financial calculations
2. Cache appropriately: User totals change when new conversions occur, so cache for 10-30 seconds max
3. Handle large numbers: total_points is a string to support arbitrary precision; parse carefully in your application
4. Combine with claim endpoint: Show both total points AND claimable amounts to give users complete picture
5. Don't poll excessively: Only fetch when user views their profile/dashboard, not on every page load

Example Use Case

Scenario: Display user's reward balance in their dashboard:

1. GET /v1/payouts/totals/0x123abc... → {"total_points": "15000"}
2. GET /v1/claim-checks/totals?user_identifier=0x123abc... → Shows claimable tokens
3. Display: "You've earned 15,000 points! Claim 50 USDC now →"

Points vs Claimable Amounts

Total Points (this endpoint):

• All points ever earned by the user
• May include points not yet converted to tokens
• May include points already claimed

Claimable Amounts (GET /v1/claim-checks/totals):

• Only shows unclaimed, on-chain ready tokens
• Denominated in actual token amounts (USDC, ETH, etc.)
• What users can claim right now

Use both endpoints together to provide complete information to users.