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


## **Automatic claimable balance on transfer**

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.

## **Claiming a claimable balance**

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:

### **Claim by asset**

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


```json
{
  "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"
}
```

### **Claim by transaction**

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.


```json
{
  "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"
}
```