How Stellar Claimable Balances Work: Protocol Airdrops Explained

Stellar's Claimable Balance is one of the most powerful — and underappreciated — primitives in the blockchain ecosystem. For protocol operators distributing tokens to large numbers of users, it solves a critical problem: how do you distribute assets non-custodially, efficiently, and verifiably?

What Is a Claimable Balance?

A Claimable Balance is an on-chain object on the Stellar network that holds assets in escrow until one or more specified accounts claim them. The key distinction from a simple transfer: the recipient does not need to be online or watching the network when the balance is created. They can claim it at any time.

• Created by a protocol or distributor account
• Locked to one or more eligible wallet addresses (claimants)
• Can include time-based conditions (claim before/after a certain date)
• Claimed by the recipient signing a ClaimClaimableBalance transaction
• Non-custodial: once created, the distributor cannot claw back the balance without a defined revocation condition

Why XamanProtocol Uses Claimable Balances

For ecosystem airdrops, Claimable Balances provide several advantages over traditional transfer methods:

• Trustless: Once created, the balance is locked and verifiable on-chain
• Non-custodial for recipients: Users claim directly to their own wallet — XamanProtocol never holds the airdrop assets
• Verifiable: Anyone can check the Stellar ledger to confirm a Claimable Balance exists for a given address
• Controlled distribution: Conditions can enforce claim windows or eligibility periods
• Gas efficient: Batch creation is possible from a single distributor account

The Claiming Process

Claiming a Claimable Balance on Stellar is a straightforward on-chain action:

• XamanProtocol creates the Claimable Balance on-chain with your Stellar address as the claimant
• You see the pending airdrop in your XamanProtocol dashboard
• You click 'Claim' — this constructs a ClaimClaimableBalance transaction
• You sign the transaction with your Stellar wallet (locally on your device)
• The transaction broadcasts to the Stellar network
• Upon confirmation (~5 seconds), the assets appear in your Stellar account

const claimOp = Operation.claimClaimableBalance({
  balanceId: claimableBalanceId,
});

const tx = new TransactionBuilder(sourceAccount, {
  fee: BASE_FEE,
  networkPassphrase: Networks.PUBLIC,
})
  .addOperation(claimOp)
  .setTimeout(30)
  .build();

// Transaction signed locally on user's device
tx.sign(userKeypair);
await server.submitTransaction(tx);

Trustline Requirements

To receive certain Stellar assets (non-XLM tokens), your Stellar account must have an established trustline with the asset issuer. XamanProtocol displays trustline requirements before airdrop campaigns and provides guidance on establishing them. This is a one-time setup per asset.