🎁Public Claimable Rewards

The claimable rewards endpoint lets you display a user's unclaimed reward balances on any frontend — without requiring an API key or SDK initialization.

When to use this vs the SDK

Method	Auth required	Returns	Use case
GET /v1/claimable-rewards	No	Unclaimed balances per currency	Display pending rewards on a landing page, portfolio tracker, or DeFi aggregator
Fuul.getClaimableChecks()	Yes (API key)	Signed vouchers for claiming	Build a claim button that submits an onchain transaction

Use the public endpoint when you just want to show how much a user can claim. Use the SDK method when you need the actual claim checks to execute a transaction.

Fetching claimable rewards

Call GET /v1/claimable-rewards?user_identifier=0x1234...&user_identifier_type=evm_address. The response includes unclaimed reward amounts grouped by currency, with token details (name, address, chain ID, decimals).

Example: show rewards before wallet connect

A common pattern is to display claimable rewards on a landing page using just the user's address from the URL — before they connect a wallet or initialize the SDK:

const params = new URLSearchParams(window.location.search);
const address = params.get('address');

if (address) {
  const res = await fetch(
    `https://api.fuul.xyz/api/v1/claimable-rewards?user_identifier=${address}&user_identifier_type=evm_address`
  );
  const data = await res.json();
  // Display unclaimed balances
}

Example response:

[
  {
    "currency_name": "USDC",
    "currency_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "currency_chain_id": 1,
    "currency_decimals": 6,
    "amount": "500000000"
  }
]

amount is in the token's smallest unit (e.g., 500000000 = 500 USDC with 6 decimals).

This endpoint is public and requires no authentication. It's designed for protocol frontends, portfolio dashboards, and aggregator integrations.

Next steps

Once the user is ready to claim, initialize the SDK and use the full Claim Flow Integration to fetch signed vouchers and submit the onchain transaction.

For full endpoint details, see the API reference.