✨Stellar
This guide shows how to claim onchain token rewards from the Fuul protocol on Stellar using the @fuul/sdk-stellar package. The flow is: get claim checks from the API, initialize the Stellar SDK, build the claim with the authorization Fuul pre-signed, and have the user's wallet sign and submit the transaction.
Prerequisites
Node.js
>= 22.12
Required by @fuul/sdk-stellar
@fuul/sdk-stellar
0.3.0
ESM and CommonJS builds
@stellar/stellar-sdk
17.2.1
Use the same version the Fuul SDK is built on for transaction and XDR objects
Stellar wallet
Any
This guide uses Freighter (@stellar/freighter-api)
npm install @fuul/sdk-stellar@0.3.0 @stellar/stellar-sdk@17.2.1 @stellar/freighter-api1. Understand the Stellar claim check
Claim checks for a Stellar user come back in the same shape as on other chains, with three differences:
currency_type
0 (Stellar asset)
signatures
Base64 XDR SorobanAuthorizationEntry values, pre-signed by Fuul
signers
Extra array with the signer G… addresses, one per signature
project_address, to, and currency are Stellar StrKeys (C… for the project and the asset, G… for the recipient). They are case-sensitive: pass them exactly as returned.
import type { ClaimResponse } from '@fuul/sdk';
// `signers` is only present on Stellar claim checks
type StellarClaimCheck = ClaimResponse & { signers: string[] };2. Initialize the SDK
Use the Manager and Factory addresses for your network from Stellar Contracts.
3. Skip checks that were already claimed
Each claim check carries a unique proof. Read the project contract to skip checks that were already redeemed:
4. Build the claim transaction
Build the claim check, simulate the Manager's claim, then swap in the authorization entries Fuul signed:
5. Sign and submit
The user's wallet signs the transaction and pays the network fee plus the claim fee:
6. Complete example
Good to know
Claim fee
A small native fee per claim, always paid in XLM by the wallet submitting the transaction, whatever the reward currency
Amounts
amount is a string in base units. Stellar assets use 7 decimals
Trustlines
The recipient needs a trustline for classic assets such as USDC before claiming. XLM needs none
Deadline
Each check carries a deadline (Unix seconds). Claim before it passes
Networks
Stellar Mainnet and Stellar Testnet are both supported. Use testnet to try the full flow before launch
Troubleshooting
ProofAlreadyClaimed (contract error 6102)
The check was already redeemed
Check claimed_proofs before submitting (step 3)
Wallet refuses to sign, or the transaction fails on the network
Wallet set to a different network than the SDK
Match the wallet network, RPC endpoint, and networkPassphrase
Simulation fails for a USDC claim
The recipient has no USDC trustline
Add the trustline from the wallet, then retry
Claim check has no signers
Claim checks fetched for a non-Stellar identifier
Fetch with user_identifier_type: 'stellar_address'
Signature or authorization errors at simulation
Authorization entries built locally or copied from a simulation
Use the signatures returned by the Fuul API (step 4)
Claim rejected after the deadline
The check expired
Fetch fresh claim checks
Last updated