Stellar Claimable Balances

A claimable balance is a Stellar primitive that lets a sender lock up assets for a specific recipient to claim later. Fordefi works with claimable balances in two scenarios:

1. Automatically creating a claimable balance when a classic-asset transfer targets a recipient that has no trustline for that asset.
2. Claiming pending claimable balances of which the vault is the recipient.

When you send a Stellar classic asset (any non-XLM, issuer-based asset) to a recipient that has not yet established a trustline for that asset, a normal Payment operation would fail. To prevent this, Fordefi automatically checks the recipient's trustlines before building the transaction:

• If the recipient has a trustline, Fordefi builds a standard Payment operation.
• If the recipient does not have a trustline, Fordefi builds a CreateClaimableBalance operation instead, with the recipient as the sole claimant. The funds remain locked in a claimable balance until the recipient establishes a trustline and claims them.

This behavior is fully automatic — the request body is the same as any other classic-asset transfer. No caller changes are required.

When your vault is the recipient of one or more claimable balances, you can claim them with a stellar_claim_claimable_balance request. Fordefi resolves which balances to claim based on the source you provide, and automatically prepends a ChangeTrust operation if the vault does not yet have a trustline for the asset — no separate trustline transaction is required.

There are two ways to specify which balances to claim:

Claims all pending claimable balances the vault holds for a specific asset.

{
  "signer_type": "api_signer",
  "type": "stellar_transaction",
  "details": {
    "type": "stellar_claim_claimable_balance",
    "source": {
      "type": "by_asset",
      "asset_identifier": {
        "type": "stellar",
        "details": {
          "type": "classic_asset",
          "code": "USDC",
          "issuer": {
            "chain": "stellar_mainnet",
            "base32_repr": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
          },
          "chain": "stellar_mainnet"
        }
      }
    }
  },
  "note": "Claim all pending USDC claimable balances",
  "vault_id": "your_stellar_vault_id"
}

Claims the claimable balances created by a specific incoming Fordefi transaction. Use this when an incoming transaction in your vault has claim_status: "claimable" and you want to claim only that one.

{
  "signer_type": "api_signer",
  "type": "stellar_transaction",
  "details": {
    "type": "stellar_claim_claimable_balance",
    "source": {
      "type": "by_transaction",
      "transaction_id": "the_incoming_transaction_id"
    }
  },
  "note": "Claim the claimable balance from a specific incoming transaction",
  "vault_id": "your_stellar_vault_id"
}