Create Claimable Balance - Stellar Developer Docs

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:

cookbooktest.ignore

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

Type	Description	Example
`unconditional`	Can be claimed anytime	`"unconditional"`
`before_absolute_time`	Must claim before specific timestamp	`{"before_absolute_time":"1735689599"}`
`before_relative_time`	Must claim within X seconds from creation	`{"before_relative_time":"3600"}`
`not`	Negates another predicate	`{"not":{...}}`
`and`	Both predicates must be true	`{"and":[{...},{...}]}`
`or`	Either 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

​Setup

​Basic Examples

​Unconditional Claimable Balance

​Multiple Claimants

​Time-Based Predicates

​Before Absolute Time

​Before Relative Time

​Logical Predicates

​Not Predicate

​And Predicate

​Or Predicate

​Complex Examples

​Mixed Claimants with Different Predicates

​Escrow-Style Payment

​Custom Asset Claimable Balance

​Understanding Predicates

​Predicate Types

​Time Format Notes

​Common Use Cases

​1. Simple Payment with Deadline

​2. Delayed Payment

​3. Emergency Fund

​Notes