🪙Claim Flow Integration

If your program distributes token rewards, users need a way to claim them. This section covers what to display and how to wire up the claiming flow.

Show claimable balances

Before asking users to submit a transaction, show them what they have available to claim (API reference):

import { Fuul } from '@fuul/sdk';

const totals = await Fuul.getClaimCheckTotals({
  user_identifier: '0x1234...',
  user_identifier_type: 'evm_address',
});

Returns: claimed and unclaimed arrays grouped by currency.

Pending acceptance payouts

Some programs require users to explicitly accept payouts before they become claimable. This is useful for compliance flows or programs where users must agree to terms before receiving rewards.

Endpoint	Description	Reference
GET /v1/payouts/pending-acceptance	Check if a user has payouts waiting for acceptance	View
POST /v1/payouts/pending-acceptance/accept	Accept pending payouts — body: { recipient_address, signature, message }	View

After accepting, the payouts become claimable through the regular claim check flow.

Fetch claim checks

When the user is ready to claim, fetch their signed vouchers (API reference):

const claimChecks = await Fuul.getClaimableChecks({
  user_identifier: '0x1234...',
  user_identifier_type: 'evm_address',
});

Pass these directly to the Fuul contract claim function. See the chain-specific guides for the full transaction:

• EVM Claiming

• SVM Claiming

The Fuul contract charges a small native token fee per claim transaction. Always read the fee dynamically using getFeesInformation().

Show payout status history

Show the lifecycle status of a user's payouts per conversion — when each payout was created, approved, and its current status (API reference):

const movements = await Fuul.getUserPayoutMovements({
  user_identifier: '0x1234...',
  identifier_type: 'evm_address',
  page: 1,
  page_size: 20,
});

Returns: date, currency, conversion_name, payout_status, payout_status_details per movement.

Show onchain claim history

Show a user's completed onchain claim transactions with their transaction hash (API reference):

const history = await Fuul.getClaimHistory({
  user_identifier: '0x1234...',
  user_identifier_type: 'evm_address',
  page: 1,
  page_size: 25,
});

Returns: results (array), total_count, next_page.

amount is a raw integer string — divide by 10 ** currency_decimals before displaying to users.

A single transaction that settled multiple currencies produces multiple consecutive rows sharing the same hash.

Claim on behalf of users

Projects can submit claim transactions on behalf of users — tokens land in the user's wallet with no action required from them. See the EVM Claiming guide for implementation details.

Public claimable rewards

To display unclaimed reward balances without requiring an API key or SDK initialization, use the public claimable rewards endpoint. See Public Claimable Rewards.

Admin: rewards payouts overview

These endpoints are for project dashboards — they return claim check data across all users in the project.

Endpoint	Description	Reference
GET /v1/claim-checks/rewards-payouts	List all claim checks with filtering by status, date range, and user	View
GET /v1/claim-checks/rewards-payouts/totals	Aggregated totals grouped by currency	View

Use status=claimed or status=unclaimed to filter, and from_date/to_date for date ranges. Use source_user_identifier + source_user_identifier_type to filter by email or UUID users (mutually exclusive with deposit-address filters). Filter by payout type with reason: affiliate_payout | end_user_payout | agency_payout.

When require_tax_info is enabled on your project, GET /v1/claim-checks/rewards-payouts applies the tax gate per row: affiliate rows without approved tax info are returned with a restricted payload. The /totals endpoint is not affected by the tax gate.