πͺ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, UserIdentifierType } from '@fuul/sdk';
const totals = await Fuul.getClaimCheckTotals({
user_identifier: '0x1234...',
user_identifier_type: UserIdentifierType.EvmAddress,
});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.
Fetch claim checks
When the user is ready to claim, fetch their signed vouchers (API reference):
Each check comes back with its own id (a uuid) alongside the voucher fields, so you can correlate a signed voucher with a specific reward row.
Pass these directly to the Fuul contract claim function. See the chain-specific guides for the full transaction:
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):
Each movement in results:
date
When the movement was created
payout_id
Identifier of the payout this movement belongs to
currency_address
Reward token address. There is no currency field
chain_id
Chain of the reward token, as a string
is_referrer
true when the user earned this as a referrer rather than as an end user
conversion_id / conversion_name
The conversion that produced the payout
total_amount
Amount as a raw string in the token's smallest unit
volume_usd
USD volume of the underlying conversion
project_name
Project the payout belongs to
payout_status
Lifecycle status β see Tokens for the full list
payout_status_details
Reason text when the status needs one, null otherwise
enduser_address
Address of the end user whose action generated the payout
user_identifier
Recipient of the movement
referrer_identifier
The referrer credited, or null
dedup_id
Deduplication key of the source event, or null
Show onchain claim history
Show a user's completed onchain claim transactions with their transaction hash (API reference):
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.
Last updated