Retrieve the total claimed and unclaimed token amounts for a user across all currencies.

When to Use This Endpoint

• Show claimable balances: Display how much a user can claim on-chain in your UI (e.g., "Claim 50 USDC")
• Pre-claim verification: Check claimable amounts before showing the "Claim Rewards" button
• Multi-currency display: Show user's claimable balance across different tokens (USDC, ETH, etc.)
• Claim history: Display what tokens have already been claimed vs what's still pending
• Wallet integration: Show claimable amounts before initiating on-chain claim transaction

When NOT to Use This Endpoint

• Don't use for total points: Use GET /v1/payouts/totals/{userIdentifier} for total points earned (this shows claimable tokens, not points)
• Don't use for claim signature generation: Use POST /v1/claim-checks/claim to generate signatures for on-chain claiming
• Don't use for analytics: Use leaderboard endpoints for aggregate project-wide analytics
• Don't poll frequently: This data doesn't change rapidly; cache for 30-60 seconds

How It Works

Returns two arrays:

1. unclaimed: Tokens that can be claimed on-chain right now
2. claimed: Tokens that have already been claimed by the user

Each entry includes:

• currency_address: Token contract address
• currency_chain_id: Blockchain chain ID
• currency_name: Human-readable token name (e.g., "USDC", "ETH")
• currency_decimals: Token decimals (e.g., 6 for USDC, 18 for ETH)
• amount: Raw amount string (without decimal formatting)

Important Constraints

• Required API Key Scope: Standard API key (no special scope required)
• Rate Limit: 100 requests/minute (standard rate)
• Multi-chain support: Returns amounts across all chains (EVM, Solana, XRPL, Sui)
• Decimal handling: amount is a raw string; you must apply currency_decimals for display
• Zero amounts excluded: If user has no claims, arrays will be empty (not null)

Response Details

Unclaimed Array

Contains tokens ready to be claimed on-chain:

• User can call POST /v1/claim-checks/claim to generate signatures
• These amounts can be claimed via FuulManager.claim() smart contract call
• New conversions add to these totals automatically

Claimed Array

Contains tokens already claimed by the user:

• Historical record of past claims
• These amounts cannot be claimed again
• Useful for showing "Total Claimed: 500 USDC" in UI

Amount Formatting

To display amounts correctly:

// Example: amount = "50000000", decimals = 6
const displayAmount = Number(amount) / Math.pow(10, decimals);
// Result: 50 USDC

Common Errors

• 400 Bad Request:

  • Invalid user_identifier format
  • Invalid user_identifier_type
  • Missing both user_identifier and source_user_identifier
  • Providing both user_identifier and source_user_identifier
  • Invalid source_user_identifier_type (must be email or uuid)

• 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

• POST /v1/claim-checks/claim - Generate claim signatures after checking totals (required for on-chain claiming)
• GET /v1/payouts/totals/{userIdentifier} - Get total points (different from claimable tokens)
• GET /v1/payouts/leaderboard/payouts - Get detailed payout history

Best Practices

1. Always format amounts: Apply currency_decimals before displaying to users
2. Cache responses: Claim totals don't change frequently; cache for 30-60 seconds
3. Handle multiple currencies: Design your UI to display multiple tokens (users may have USDC, ETH, etc.)
4. Show both claimed and unclaimed: Give users visibility into their claim history
5. Pre-check before claim flow: Only show "Claim" button if unclaimed array is non-empty

Example Use Case

Scenario: Show user's claimable balance and initiate claim flow:

1. GET /v1/claim-checks/totals?user_identifier=0x123...&user_identifier_type=address

Response:
{
  "unclaimed": [
    {
      "currency_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "currency_chain_id": "1",
      "currency_name": "USDC",
      "currency_decimals": 6,
      "amount": "50000000"  // = 50 USDC
    }
  ],
  "claimed": [
    {
      "currency_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "currency_chain_id": "1",
      "currency_name": "USDC",
      "currency_decimals": 6,
      "amount": "25000000"  // = 25 USDC (previously claimed)
    }
  ]
}

2. Display: "Claim 50 USDC" button (enabled)
3. User clicks → Call POST /v1/claim-checks/claim to get signatures
4. User approves transaction in wallet
5. Call FuulManager.claim() on-chain with signatures

Multi-Chain Example

Users may have claimable amounts on multiple chains:

{
  "unclaimed": [
    {
      "currency_name": "USDC",
      "currency_chain_id": "1",      // Ethereum
      "amount": "50000000"
    },
    {
      "currency_name": "USDC",
      "currency_chain_id": "137",    // Polygon
      "amount": "25000000"
    }
  ]
}

Design your UI to let users claim on their preferred chain or aggregate across chains.