Skip to main content

Create Claimable Balance

Claimable balances allow you to send payments that can be claimed by the recipient based on specific conditions. This is useful for escrow-like functionality, conditional payments, or time-locked transfers.

Setup​

For the following examples we will use these accounts:

stellar network use testnet
stellar keys generate --fund alice
stellar keys generate bob --fund
stellar keys generate charlie --fund

Basic Examples​

Unconditional Claimable Balance​

Create a claimable balance that can be claimed immediately by the recipient:

stellar tx new create-claimable-balance \
  --source alice \
  --amount 50_000_000 \
  --asset native \
  --claimant bob

You can also explicitly specify unconditional:

stellar tx new create-claimable-balance \
  --source alice \
  --amount 50_000_000 \
  --asset native \
  --claimant 'bob:"unconditional"'

Multiple Claimants​

Create a claimable balance that can be claimed by any of multiple recipients:

stellar tx new create-claimable-balance \
  --source alice \
  --amount 75_000_000 \
  --asset native \
  --claimant bob \
  --claimant charlie

Time-Based Predicates​

Before Absolute Time​

Create a claimable balance that must be claimed before a specific date:

stellar tx new create-claimable-balance \
  --source alice \
  --amount 30_000_000 \
  --asset native \
  --claimant 'bob:{"before_absolute_time":"1735689599"}'

Before Relative Time​

Create a claimable balance that must be claimed within 1 hour (3600 seconds) from creation:

stellar tx new create-claimable-balance \
  --source alice \
  --amount 25_000_000 \
  --asset native \
  --claimant 'bob:{"before_relative_time":"3600"}'

Logical Predicates​

Not Predicate​

Create a claimable balance that can be claimed after a certain time (NOT before relative time):

stellar tx new create-claimable-balance \
  --source alice \
  --amount 40_000_000 \
  --asset native \
  --claimant 'bob:{"not":{"before_relative_time":"7200"}}'

This means: "Can be claimed, but NOT before 2 hours have passed" (effectively: can be claimed after 2 hours).

And Predicate​

Create a claimable balance with multiple conditions that must ALL be true:

stellar tx new create-claimable-balance \
  --source alice \
  --amount 60_000_000 \
  --asset native \
  --claimant 'bob:{"and":[{"before_absolute_time":"1735689599"},{"not":{"before_relative_time":"86400"}}]}'

This means: "Can be claimed before Dec 31, 2024 AND after 1 day has passed".

Or Predicate​

Create a claimable balance where either condition can be true:

stellar tx new create-claimable-balance \
  --source alice \
  --amount 35_000_000 \
  --asset native \
  --claimant 'bob:{"or":[{"before_relative_time":"3600"},{"not":{"before_absolute_time":"1717200000"}}]}'

This means: "Can be claimed within 1 hour OR after June 1, 2024".

Complex Examples​

Mixed Claimants with Different Predicates​

Create a claimable balance with multiple claimants having different claim conditions:

stellar tx new create-claimable-balance \
  --source alice \
  --amount 100_000_000 \
  --asset native \
  --claimant 'bob:{"before_relative_time":"3600"}' \
  --claimant 'charlie:{"not":{"before_relative_time":"86400"}}'

This creates a balance where:

  • Bob can claim within 1 hour
  • Charlie can claim after 1 day has passed

Escrow-Style Payment​

Create an escrow where the recipient has 30 days to claim, otherwise it returns to sender:

stellar tx new create-claimable-balance \
  --source alice \
  --amount 200_000_000 \
  --asset native \
  --claimant 'bob:{"before_relative_time":"2592000"}' \
  --claimant 'alice:{"not":{"before_relative_time":"2592000"}}'

This means:

  • Bob can claim within 30 days
  • Alice can reclaim after 30 days if Bob hasn't claimed

Custom Asset Claimable Balance​

Create a claimable balance for a custom asset:

stellar tx new create-claimable-balance \
  --source alice \
  --amount 1000_000_000 \
  --asset USDC:GBUG7QTBTT47XVDVE6RZYWRUZBPLOIO57INE6LYZDMIXMMDCREQRUQKI \
  --claimant 'bob:{"before_absolute_time":"1735689599"}'

Understanding Predicates​

Note: Predicates must be valid JSON, so you must use proper quoting and escaping.

Predicate Types​

TypeDescriptionExample
unconditionalCan be claimed anytime"unconditional"
before_absolute_timeMust claim before specific timestamp{"before_absolute_time":"1735689599"}
before_relative_timeMust claim within X seconds from creation{"before_relative_time":"3600"}
notNegates another predicate{"not":{...}}
andBoth predicates must be true{"and":[{...},{...}]}
orEither predicate can be true{"or":[{...},{...}]}

Time Format Notes​

  • Absolute times: Use Unix timestamps (seconds since epoch)
  • Relative times: Seconds from claimable balance creation time
  • Timestamps: Must be in the future when creating the balance

Common Use Cases​

1. Simple Payment with Deadline​

# Bob has 7 days to claim
stellar tx new create-claimable-balance \
  --source alice \
  --amount 50_000_000 \
  --claimant 'bob:{"before_relative_time":"604800"}'

2. Delayed Payment​

# Bob can only claim after 1 day
stellar tx new create-claimable-balance \
  --source alice \
  --amount 100_000_000 \
  --claimant 'bob:{"not":{"before_relative_time":"86400"}}'

3. Emergency Fund​

# Bob can claim immediately, but if he doesn't claim within 48 hours, Alice can reclaim
stellar tx new create-claimable-balance \
  --source alice \
  --amount 500_000_000 \
  --claimant 'bob:{"before_relative_time":"172800"}' \
  --claimant 'alice:{"not":{"before_relative_time":"172800"}}'

Notes​

  • --amount: Amount in stroops (1 XLM = 10,000,000 stroops)
  • --asset: Use "native" for XLM or "CODE:ISSUER" format for other assets
  • --claimant: Account with optional predicate (can be specified multiple times)
  • Predicates are evaluated when the claimable balance is claimed, not when created
  • And and Or predicates must have exactly 2 sub-predicates
  • Complex predicates can be nested to create sophisticated claim conditions

Guides in this category: