For the complete documentation index, see llms.txt. This page is also available as Markdown.

πŸͺ™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,
});

Returns: claimed and unclaimed arrays grouped by currency. Each row carries a status (claimed, open or closed); only closed rows can be claimed right now. Optional status and reason filters let you show ready-to-claim balances or split commission from rebate. See Get claim totals.

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

POST /v1/payouts/pending-acceptance/accept

Accept pending payouts β€” body: { recipient_address, signature, message }

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):

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:

If your project has claim check aggregation enabled, checks start as open and must be finalized with Fuul.closeClaimChecks before getClaimableChecks returns them. See Get Claim Checks.

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:

Field
Description

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

referrer_identifier, enduser_address, and dedup_id let you join a movement back to the event that caused it. Useful when reconciling Fuul payouts against your own records.

Show onchain claim history

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

Returns: results (array), total_count, next_page.

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

GET /v1/claim-checks/rewards-payouts/totals

Aggregated totals grouped by currency

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.

Last updated