{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-developers/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"redocly_category":"Developers","type":"markdown"},"seo":{"title":"Stellar Claimable Balances","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"stellar-claimable-balances","__idx":0},"children":["Stellar Claimable Balances"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Automatically creating"]}," a claimable balance when a classic-asset transfer targets a recipient that has no trustline for that asset."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Claiming"]}," pending claimable balances of which the vault is the recipient."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"_","__idx":1},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Automatic claimable balance on transfer"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Payment"]}," operation would fail. To prevent this, Fordefi automatically checks the recipient's trustlines before building the transaction:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If the recipient ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["has"]}," a trustline, Fordefi builds a standard ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Payment"]}," operation."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If the recipient ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["does not have"]}," a trustline, Fordefi builds a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This behavior is fully automatic — the request body is the same as any other classic-asset transfer. No caller changes are required."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"_-1","__idx":2},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Claiming a claimable balance"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When your vault is the recipient of one or more claimable balances, you can claim them with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stellar_claim_claimable_balance"]}," request. Fordefi resolves which balances to claim based on the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source"]}," you provide, and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["automatically prepends a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ChangeTrust"]}," operation if the vault does not yet have a trustline for the asset"]}," — no separate trustline transaction is required."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are two ways to specify which balances to claim:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"_-2","__idx":3},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Claim by asset"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Claims ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["all"]}," pending claimable balances the vault holds for a specific asset."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"signer_type\": \"api_signer\",\n  \"type\": \"stellar_transaction\",\n  \"details\": {\n    \"type\": \"stellar_claim_claimable_balance\",\n    \"source\": {\n      \"type\": \"by_asset\",\n      \"asset_identifier\": {\n        \"type\": \"stellar\",\n        \"details\": {\n          \"type\": \"classic_asset\",\n          \"code\": \"USDC\",\n          \"issuer\": {\n            \"chain\": \"stellar_mainnet\",\n            \"base32_repr\": \"GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN\"\n          },\n          \"chain\": \"stellar_mainnet\"\n        }\n      }\n    }\n  },\n  \"note\": \"Claim all pending USDC claimable balances\",\n  \"vault_id\": \"your_stellar_vault_id\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"_-3","__idx":4},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Claim by transaction"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Claims the claimable balances created by a specific incoming Fordefi transaction. Use this when an incoming transaction in your vault has ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["claim_status: \"claimable\""]}," and you want to claim only that one."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"signer_type\": \"api_signer\",\n  \"type\": \"stellar_transaction\",\n  \"details\": {\n    \"type\": \"stellar_claim_claimable_balance\",\n    \"source\": {\n      \"type\": \"by_transaction\",\n      \"transaction_id\": \"the_incoming_transaction_id\"\n    }\n  },\n  \"note\": \"Claim the claimable balance from a specific incoming transaction\",\n  \"vault_id\": \"your_stellar_vault_id\"\n}\n","lang":"json"},"children":[]}]},"headings":[{"value":"Stellar Claimable Balances","id":"stellar-claimable-balances","depth":1},{"value":"","id":"_","depth":2},{"value":"","id":"_-1","depth":2},{"value":"","id":"_-2","depth":3},{"value":"","id":"_-3","depth":3}],"frontmatter":{"seo":{"title":"Stellar Claimable Balances"}},"lastModified":"2026-05-03T10:41:08.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/developers/transaction-types/stellar-claimable-balances","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}