Get the total aggregate payouts across all users in your project.

When to Use This Endpoint

• Project analytics: Display total rewards distributed across your entire project
• Dashboard metrics: Show aggregate statistics like "Total Rewards: 1M points"
• Campaign performance: Track total points distributed during a specific campaign period
• Growth metrics: Monitor reward distribution growth over time
• Admin dashboards: Provide project-level overview of reward activity

When NOT to Use This Endpoint

• Don't use for individual user data: Use GET /v1/payouts/totals/{userIdentifier} for specific user totals
• Don't use for detailed breakdowns: This returns only a single total; use leaderboard endpoints for detailed per-user analytics
• Don't use for on-chain claimable amounts: This shows points, not claimable tokens (use GET /v1/claim-checks/totals for claimable tokens)
• Don't use for user-facing displays: This is project-wide data, typically only shown to admins/project owners

How It Works

Returns a single value: total_payouts - the sum of ALL points distributed to ALL users across:

• Affiliate commissions
• Referral rewards
• Direct user rewards
• Bonus points from campaigns

Important: This endpoint only supports currency=point (the platform's internal point system).

Important Constraints

• Required API Key Scope: Standard API key (no special scope required)
• Rate Limit: 100 requests/minute (standard rate)
• Currency Parameter Required: Must specify currency=point (only supported value)
• Points Only: Returns points, not token amounts or USD values
• No Time Filtering: Returns all-time total (no date range filtering available)

Response Details

• total_payouts: String representation of total points distributed across all users
• Large number support: Returned as string to handle arbitrarily large totals
• Always returns 200 OK even if project has no payouts (returns total_payouts: "0")

Common Errors

• 400 Bad Request:

  • Missing currency parameter
  • Invalid currency value (only "point" is supported)

• 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/payouts/totals/{userIdentifier} - Get total points for a specific user
• GET /v1/payouts/leaderboard/payouts - Get detailed payout records with pagination
• GET /v1/payouts/leaderboard/users - Get ranked user list by points earned

Best Practices

1. Cache aggressively: This total changes infrequently; cache for 5-10 minutes
2. Use for admin views only: This is project-level data, not typically shown to end users
3. Combine with other metrics: Pair with user count, conversion count, etc. for complete analytics
4. Format large numbers: Parse string and format with commas/abbreviations (e.g., "1.5M points")
5. Track over time: Store historical snapshots to visualize growth trends

Example Use Case

Scenario: Display project-wide metrics on admin dashboard:

1. GET /v1/payouts/summary?currency=point

Response:
{
  "total_payouts": "1234567890"  // ~1.23B points distributed
}

2. Format for display: "Total Rewards Distributed: 1.23B points"
3. Combine with other endpoints:
   - GET /v1/payouts/leaderboard/users → "Across 10,523 users"
   - GET /v1/claim-checks/totals (aggregated) → "500K USDC claimed"

Use in Analytics

This endpoint is useful for tracking:

• Growth rate: Compare totals week-over-week
• Campaign impact: Check total before/after campaigns
• Reward distribution health: Ensure rewards are flowing to users
• Budget tracking: Monitor total points distributed vs budget

Currency Parameter

Currently only supports currency=point:

• "point": Platform's internal point system
• Other currencies (USDC, ETH, etc.) are NOT supported by this endpoint

For token-specific totals, aggregate data from GET /v1/claim-checks/totals across all users.