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

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

Before following this guide, make sure you've fetched your claim checks using @fuul/sdk with user_identifier_type: 'stellar_address'.

Prerequisites

Requirement
Version
Notes

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-api

1. Understand the Stellar claim check

Claim checks for a Stellar user come back in the same shape as on other chains, with three differences:

Field
Stellar value

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:

Never build the authorization entries yourself or copy them from a simulation response. Only the entries returned by the Fuul API carry Fuul's signature.

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

Topic
Detail

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

Symptom
Cause
Fix

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