# 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](https://fuul.readme.io/reference/get_v1-claim-checks-totals)):

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

const totals = await Fuul.getClaimCheckTotals({
  user_identifier: '0x1234...',
  user_identifier_type: 'evm_address',
});
// Returns: { claimed: [...], unclaimed: [...] } grouped by currency
```

Display an empty `unclaimed` array as "No rewards available to claim" — it is not an error.

## Fetch claim checks

When the user is ready to claim, fetch their signed vouchers ([API reference](https://fuul.readme.io/reference/post_v1-claim-checks-claim)):

```typescript
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](https://docs.fuul.xyz/developer-guide/claiming-onchain-rewards/evm)
* [SVM Claiming](https://docs.fuul.xyz/developer-guide/claiming-onchain-rewards/svm-solana)

{% hint style="warning" %}
The Fuul contract charges a small native token fee per claim transaction. Always read the fee dynamically using `getFeesInformation()` — never hardcode it.
{% endhint %}

## Show claim history

After claiming, or to display past activity ([API reference](https://fuul.readme.io/reference/get_v1-payouts-movements)):

```typescript
const movements = await Fuul.getUserPayoutMovements({
  user_identifier: '0x1234...',
  identifier_type: 'evm_address',
  page: 1,
  page_size: 20,
});
// Returns: date, currency, amount, status per movement
```

## 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](https://docs.fuul.xyz/developer-guide/claiming-onchain-rewards/evm) for implementation details.

## Claimable rewards (public, no API key)

If you want to show unclaimed rewards on a DeFi frontend without requiring an API key, use the public claimable rewards endpoint. It returns all unclaimed reward amounts for a user ([API reference](https://fuul.readme.io/reference/get_v1-claimable-rewards)):

```typescript
// GET /v1/claimable-rewards?user_identifier=0x1234...&user_identifier_type=evm_address
```

{% hint style="info" %}
This endpoint is public — no authentication required. It's designed for protocol frontends that want to display claimable amounts without managing API keys.
{% endhint %}

## 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.

To check if a user has pending payouts waiting for acceptance ([API reference](https://fuul.readme.io/reference/get_v1-payouts-pending-acceptance-1)):

```typescript
// GET /v1/payouts/pending-acceptance
```

To accept pending payouts, the user signs a message confirming acceptance ([API reference](https://fuul.readme.io/reference/post_v1-payouts-pending-acceptance-accept-1)):

```typescript
// POST /v1/payouts/pending-acceptance/accept
// Body: { recipient_address, signature, message }
```

{% hint style="info" %}
After accepting, the payouts become claimable through the regular [claim check flow](https://docs.fuul.xyz/developer-guide/claiming-onchain-rewards/get-claim-checks).
{% endhint %}

## Admin: rewards payouts overview

These endpoints are for project dashboards — they return claim check data across all users in the project, not just a single user.

List all claim checks with filtering by status, date range, and user ([API reference](https://fuul.readme.io/reference/get_v1-claim-checks-rewards-payouts)):

```typescript
// GET /v1/claim-checks/rewards-payouts?status=unclaimed&page=1&page_size=25
```

Get aggregated totals grouped by currency ([API reference](https://fuul.readme.io/reference/get_v1-claim-checks-rewards-payouts-totals)):

```typescript
// GET /v1/claim-checks/rewards-payouts/totals?status=unclaimed
```

{% hint style="info" %}
Use `status=claimed` or `status=unclaimed` to filter, and `from_date`/`to_date` for date ranges.
{% endhint %}