Skip to main content

Claimable balances

Claimable balances were introduced in CAP-0023 and are used to split a payment into two parts.

  • Part 1: sending account creates a payment, or ClaimableBalanceEntry, using the Create Claimable Balance operation
  • Part 2: destination account(s), or claimant(s), accepts the ClaimableBalanceEntry using the Claim Claimable Balance operation

Claimable balances allow an account to send a payment to another account that is not necessarily prepared to receive the payment. They can be used when you send a non-native asset to an account that has not yet established a trustline, which can be useful for anchors onboarding new users. A trustline must be established by the claimant to the asset before it can claim the claimable balance, otherwise, the claim will result in an op_no_trust error.

It is important to note that if a claimable balance isn’t claimed, it sits on the ledger forever, taking up space and ultimately making the network less efficient. For this reason, it is a good idea to put one of your own accounts as a claimant for a claimable balance. Then you can accept your own claimable balance if needed, freeing up space on the network.

Each ClaimableBalanceEntry is a ledger entry, and each claimant in that entry increases the source account’s minimum balance by one base reserve.

Once a ClaimableBalanceEntry has been claimed, it is deleted.

Operations​

Create Claimable Balance​

For basic parameters, see the Create Claimable Balance entry in our List of Operations section.

Additional parameters​

Claim_Predicate_ Claimant — an object that holds both the destination account that can claim the ClaimableBalanceEntry and a ClaimPredicate that must evaluate to true for the claim to succeed.

A ClaimPredicate is a recursive data structure that can be used to construct complex conditionals using different ClaimPredicateTypes. Below are some examples with the Claim_Predicate_ prefix removed for readability. Note that the SDKs expect the Unix timestamps to be expressed in seconds.

  • Can claim at any time - UNCONDITIONAL
  • Can claim if the close time of the ledger, including the claim is before X seconds + the ledger close time in which the ClaimableBalanceEntry was created - BEFORE_RELATIVE_TIME(X)
  • Can claim if the close time of the ledger including the claim is before X (Unix timestamp) - BEFORE_ABSOLUTE_TIME(X)
  • Can claim if the close time of the ledger, including the claim is at or after X seconds + the ledger close time in which the ClaimableBalanceEntry was created - NOT(BEFORE_RELATIVE_TIME(X))
  • Can claim if the close time of the ledger, including the claim is at or after X (Unix timestamp) - NOT(BEFORE_ABSOLUTE_TIME(X))
  • Can claim between X and Y Unix timestamps (given X < Y) - AND(NOT(BEFORE_ABSOLUTE_TIME(X)), BEFORE_ABSOLUTE_TIME(Y))
  • Can claim outside X and Y Unix timestamps (given X < Y) - OR(BEFORE_ABSOLUTE_TIME(X), NOT(BEFORE_ABSOLUTE_TIME(Y))

ClaimableBalanceID ClaimableBalanceID is a union with one possible type (CLAIMABLE_BALANCE_ID_TYPE_V0). It contains an SHA-256 hash of the OperationID for Claimable Balances.

A successful Create Claimable Balance operation will return a Balance ID, which is required when claiming the ClaimableBalanceEntry with the Claim Claimable Balance operation.

Claim Claimable Balance​

For basic parameters, see the Claim Claimable Balance entry in our List of Operations section.

This operation will load the ClaimableBalanceEntry that corresponds to the Balance ID and then search for the source account of this operation in the list of claimants on the entry. If a match on the claimant is found, and the ClaimPredicate evaluates to true, then the ClaimableBalanceEntry can be claimed. The balance on the entry will be moved to the source account if there are no limit or trustline issues (for non-native assets), meaning the claimant must establish a trustline to the asset before claiming it.

Clawback Claimable Balance​

This operation claws back a claimable balance, returning the asset to the issuer account, burning it. You must claw back the entire claimable balance, not just part of it. Once a claimable balance has been claimed, use the regular clawback operation to claw it back.

Clawback claimable balances require the claimable balance ID.

Learn more about clawbacks in our Clawback Guide.

Example​

The below code demonstrates via both the JavaScript and Go SDKs how an account (Account A) creates a ClaimableBalanceEntry with two claimants: Account A (itself) and Account B (another recipient).

Each of these accounts can only claim the balance under unique conditions. Account B has a full minute to claim the balance before Account A can reclaim the balance back for itself.

Note: there is no recovery mechanism for a claimable balance in general — if none of the predicates can be fulfilled, the balance cannot be recovered. The reclaim example below acts as a safety net for this situation.

Click here to see helper functions
func fundAccount(rpcClient *client.Client, address string) error {
	ctx := context.Background()

	// Use GetNetwork method from client
	networkResp, err := rpcClient.GetNetwork(ctx)
	if err != nil {
		return err
	}

	if networkResp.FriendbotURL != "" {
		friendbotURL := networkResp.FriendbotURL + "?addr=" + url.QueryEscape(address)
		resp, err := http.Post(friendbotURL, "application/x-www-form-urlencoded", nil)
		if err != nil {
			return err
		}
		defer resp.Body.Close()

		if resp.StatusCode != 200 {
			return fmt.Errorf("friendbot failed with status: %d", resp.StatusCode)
		}
		return nil
	}

	return fmt.Errorf("friendbot not configured for network - %s", networkResp.Passphrase)
}

func panicIf(err error) {
	if err != nil {
		log.Fatal(err)
	}
}
import * as StellarSdk from "@stellar/stellar-sdk";

/**
 * Creates a claimable balance on Stellar testnet
 * A claimable balance allows splitting a payment into two parts:
 * 1. Sender creates the claimable balance
 * 2. Recipient(s) can claim it later
 */
async function createClaimableBalance() {
  // Connect to Stellar testnet RPC server
  const server = new StellarSdk.rpc.Server(
    "https://soroban-testnet.stellar.org",
  );

  const A = StellarSdk.Keypair.random();
  const B = StellarSdk.Keypair.random();

  console.log(
    `Account A... public key: ${A.publicKey()}, secret: ${A.secret()}`,
  );
  console.log(
    `Account B... public key: ${B.publicKey()}, secret: ${B.secret()}`,
  );

  try {
    // Fund the source account using testnet's built-in airdrop
    await server.requestAirdrop(A.publicKey());

    // Load the funded account to get current sequence number
    const aAccount = await server.getAccount(A.publicKey());
    console.log(`Account sequence: ${aAccount.sequenceNumber()}`);

    // Create a claimable balance with our two above-described conditions.
    let soon = Math.ceil(Date.now() / 1000 + 60); // .now() is in ms
    let bCanClaim = StellarSdk.Claimant.predicateBeforeRelativeTime("60");
    let aCanReclaim = StellarSdk.Claimant.predicateNot(
      StellarSdk.Claimant.predicateBeforeAbsoluteTime(soon.toString()),
    );

    // Create claimable balance operation
    const claimableBalanceOp = StellarSdk.Operation.createClaimableBalance({
      claimants: [
        new StellarSdk.Claimant(B.publicKey(), bCanClaim),
        new StellarSdk.Claimant(A.publicKey(), aCanReclaim),
      ],
      asset: StellarSdk.Asset.native(),
      amount: "420",
    });

    // Build the transaction
    console.log(`Building transaction...`);
    const transaction = new StellarSdk.TransactionBuilder(aAccount, {
      fee: StellarSdk.BASE_FEE,
      networkPassphrase: StellarSdk.Networks.TESTNET,
    })
      .addOperation(claimableBalanceOp)
      .setTimeout(180)
      .build();

    /*
      Claimable BalanceIds are predictable and can be derived from the Sha256 hash of the operation that creates them.
    */
    const predictableBalanceId = transaction.getClaimableBalanceId(0);

    // Sign the transaction with source account
    transaction.sign(A);

    // Submit transaction to the network
    console.log(`Submitting transaction...`);
    const response = await server.sendTransaction(transaction);

    // Poll for transaction completion (RPC is asynchronous)
    console.log(`Polling for result...`);
    const finalResponse = await server.pollTransaction(response.hash);

    if (finalResponse.status === "SUCCESS") {
      // Extract claimable balance ID from transaction result
      const txResult = finalResponse.resultXdr;
      const results = txResult.result().results();
      const operationResult = results[0].value().createClaimableBalanceResult();
      const balanceId = operationResult.balanceId().toXDR("hex");

      console.log(`Balance ID (from txResult): ${balanceId}`);
      console.log(
        `Predictable Balance ID (obtained before txSubmission): ${predictableBalanceId}`,
      );
      if (balanceId === predictableBalanceId) {
        console.log(`Balance ID from txResult matches the predictable ID`);
      } else {
        console.log(
          ` Balance ID from txResult does NOT match the predictable ID`,
        );
      }
    } else {
      console.log(`Transaction failed: ${finalResponse.status}`);
    }
  } catch (error) {
    console.error(`Error: ${error.message}`);
  }
}

// Run the function
createClaimableBalance();

At this point, the ClaimableBalanceEntry exists in the ledger, but we’ll need its Balance ID to claim it. You can call the RPC's getLedgerEntries endpoint to do this.

import * as StellarSdk from "@stellar/stellar-sdk";

// Replace with your actual Claimable Balance ID
// Format: 72 hex characters (includes ClaimableBalanceId type + hash)
const BALANCE_ID =
  "00000000db1108ff108a807150d02b8672d9a8c0e808bff918cdbe5c7605e63a7f565df5";

/**
 * Fetches and displays claimable balance details using Stellar RPC
 */
async function fetchClaimableBalance(balanceId) {
  const server = new StellarSdk.rpc.Server(
    "https://soroban-testnet.stellar.org",
  );

  try {
    console.log(`Looking up balance ID: ${balanceId}`);

    // Parse the claimable balance ID from hex XDR
    const claimableBalanceId = StellarSdk.xdr.ClaimableBalanceId.fromXDR(
      balanceId,
      "hex",
    );

    // Create ledger key for the claimable balance entry
    const ledgerKey = StellarSdk.xdr.LedgerKey.claimableBalance(
      new StellarSdk.xdr.LedgerKeyClaimableBalance({
        balanceId: claimableBalanceId,
      }),
    );

    console.log(`Fetching from RPC server...`);

    // Use SDK's getLedgerEntries method with XDR object array
    const response = await server.getLedgerEntries(ledgerKey);

    if (response.entries && response.entries.length > 0) {
      const claimableBalance = response.entries[0].val.claimableBalance();

      const asset = StellarSdk.Asset.fromOperation(claimableBalance.asset());

      console.log(`Found claimable balance`);
      console.log(`Amount: ${claimableBalance.amount().toString()}`);
      console.log(`Asset: ${asset.toString()} `);
      // Show claimant details
      console.log(`\nClaimants:`);
      claimableBalance.claimants().forEach((claimant, index) => {
        const destination = claimant.v0().destination().ed25519();
        console.log(
          `   ${index + 1}. ${StellarSdk.StrKey.encodeEd25519PublicKey(
            destination,
          )}`,
        );
      });
    } else {
      console.log(`Claimable balance not found`);
    }
  } catch (error) {
    console.error(`Error: ${error.message}`);
  }
}

fetchClaimableBalance(BALANCE_ID);

With the Claimable Balance ID acquired, either Account B or A can actually submit a claim, depending on which predicate is fulfilled. We’ll assume here that a minute has passed, so Account A just reclaims the balance entry.

import * as StellarSdk from "@stellar/stellar-sdk";

// Replace with your claimable balance ID
const BALANCE_ID =
  "0000000067a94da6c5d487fa09fc93c558ca91f6338413d3152d2a17771353f7c4111e11";

// Replace with the secret key of one of the claimants
const CLAIMANT_SECRET =
  "SDJLAUDIHMDO6PAIVVVYH5IFIE5QMZOOBHO37NLF43335ULECK6EURVJ";

/**
 * Claims a claimable balance
 */
async function claimClaimableBalance(balanceId, claimantSecret) {
  const server = new StellarSdk.rpc.Server(
    "https://soroban-testnet.stellar.org",
  );

  try {
    console.log(`Claiming balance ID: ${balanceId}`);
    // Create keypair from claimant's secret key
    const claimantKeypair = StellarSdk.Keypair.fromSecret(claimantSecret);

    // Load the claiming account
    const claimantAccount = await server.getAccount(
      claimantKeypair.publicKey(),
    );

    // Convert balance ID to proper format for the operation
    const claimableBalanceId = StellarSdk.xdr.ClaimableBalanceId.fromXDR(
      balanceId,
      "hex",
    );
    const balanceIdHex = claimableBalanceId.toXDR("hex");

    // Create claim operation
    const claimOperation = StellarSdk.Operation.claimClaimableBalance({
      balanceId: balanceIdHex,
    });

    // Build and sign transaction
    const transaction = new StellarSdk.TransactionBuilder(claimantAccount, {
      fee: StellarSdk.BASE_FEE,
      networkPassphrase: StellarSdk.Networks.TESTNET,
    })
      .addOperation(claimOperation)
      .setTimeout(180)
      .build();

    transaction.sign(claimantKeypair);

    // Submit and poll for completion
    const response = await server.sendTransaction(transaction);
    const finalResponse = await server.pollTransaction(response.hash);

    if (finalResponse.status === "SUCCESS") {
      console.log(`Claimable balance claimed successfully`);
      console.log(`Transaction hash: ${response.hash}`);
    } else {
      console.log(`Transaction failed: ${finalResponse.status}`);
    }
  } catch (error) {
    console.error(`Error: ${error.message}`);
  }
}

claimClaimableBalance(BALANCE_ID, CLAIMANT_SECRET);

And that’s it! Since we opted for the reclaim path, Account A should have the same balance as what it started with (minus fees), and Account B should be unchanged.

Guides in this category: