# 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/getclaimabletotals)):

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

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

{% hint style="info" %}
Returns: claimed and unclaimed arrays grouped by currency.
{% 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.

| Endpoint                                     | Description                                                                | Reference                                            |
| -------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------- |
| `GET /v1/payouts/pending-acceptance`         | Check if a user has payouts waiting for acceptance                         | [View](https://docs.fuul.xyz/for-devs/api-endpoints) |
| `POST /v1/payouts/pending-acceptance/accept` | Accept pending payouts — body: `{ recipient_address, signature, message }` | [View](https://docs.fuul.xyz/for-devs/api-endpoints) |

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

## Fetch claim checks

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

```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](/developer-guide/claiming-onchain-rewards/evm.md)
* [SVM Claiming](/developer-guide/claiming-onchain-rewards/svm-solana.md)

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

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

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

{% hint style="info" %}
Returns: date, currency, conversion\_name, payout\_status, payout\_status\_details per movement.
{% endhint %}

## Show onchain claim history

Show a user's completed onchain claim transactions with their transaction hash ([API reference](https://fuul.readme.io/reference/get_v1-claim-checks-claim-history)):

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

{% hint style="info" %}
Returns: results (array), total\_count, next\_page.
{% endhint %}

{% hint style="warning" %}
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.
{% endhint %}

## 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](/developer-guide/claiming-onchain-rewards/evm.md) 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](/developer-guide/claimable-rewards.md).

## 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](https://fuul.readme.io/reference/get_v1-claim-checks-rewards-payouts)        |
| `GET /v1/claim-checks/rewards-payouts/totals` | Aggregated totals grouped by currency                                | [View](https://fuul.readme.io/reference/get_v1-claim-checks-rewards-payouts-totals) |

{% hint style="info" %}
Use status=claimed or status=unclaimed to filter, and from\_date/to\_date for date ranges.
{% endhint %}

{% hint style="warning" %}
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.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fuul.xyz/developer-guide/claim-frontend.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.