Retrieve a user's claim check totals across all currencies, broken down by state: claimed, plus the unclaimed umbrella split into open and closed rows.

Claim Check States (read this first)

• open: Still accumulating rewards; must be closed before it can be claimed. NOT claimable yet.
• closed: Closed and signed; ready to claim on-chain right now.
• claimed: Already claimed on-chain.

Unclaimed is the umbrella for open + closed: the response's unclaimed array contains BOTH, one row per currency per state, each labeled with a status field. A "ready to claim" figure must only sum rows with status: 'closed'.

Naming trap: other endpoints (e.g. rewards-payouts) and the stored data model use the status value unclaimed to mean what this endpoint labels closed (closed, not yet claimed on-chain). On THIS endpoint, unclaimed always refers to the umbrella — both as the response key and as a status filter value.

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") — sum unclaimed rows with status: 'closed', or call with status=closed
• Show pending balances: Display rewards still accumulating (status: 'open') separately from what is claimable
• Pre-claim verification: Check for closed rows before showing the "Claim Rewards" button
• Multi-currency display: Show user's balances 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: The unclaimed umbrella — one row per currency per state (open or closed). Only rows with status: 'closed' can be claimed on-chain right now
2. claimed: Tokens that have already been claimed by the user (status: 'claimed')

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)
• status: The state of this row (open, closed, or claimed)

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
• Expired checks excluded: open and closed rows never include checks past their claim deadline, so closed sums are always claimable right now
• Zero amounts excluded: If user has no claims, arrays will be empty (not null); a status filter leaves the filtered-out arrays empty as well

Response Details

Unclaimed Array

The umbrella of not-yet-claimed tokens, one row per currency per state:

• Rows with status: 'closed' are ready: call POST /v1/claim-checks/claim to generate signatures and claim via FuulManager.claim()
• Rows with status: 'open' are still accumulating and must be closed (POST /v1/claim-checks/close) before they can be claimed
• 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)
  • Invalid status value (must be one of claimed, unclaimed, open, closed; the error message lists them)

• 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 there are rows with status: 'closed' (call with status=closed and check the 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, ready to claim
      "status": "closed"
    },
    {
      "currency_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "currency_chain_id": "1",
      "currency_name": "USDC",
      "currency_decimals": 6,
      "amount": "10000000",  // = 10 USDC, still accumulating
      "status": "open"
    }
  ],
  "claimed": [
    {
      "currency_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "currency_chain_id": "1",
      "currency_name": "USDC",
      "currency_decimals": 6,
      "amount": "25000000",  // = 25 USDC (previously claimed)
      "status": "claimed"
    }
  ]
}

2. Display: "Claim 50 USDC" button (enabled, from the "closed" row) and "10 USDC pending" (from the "open" row)
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",
      "status": "closed"
    },
    {
      "currency_name": "USDC",
      "currency_chain_id": "137",    // Polygon
      "amount": "25000000",
      "status": "closed"
    }
  ]
}

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