> ## Documentation Index
> Fetch the complete documentation index at: https://developers.stellar.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Claimable Balance

> Create claimable balances with various claim predicates using the Stellar CLI

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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
stellar network use testnet
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
stellar keys generate --fund alice
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
stellar keys generate bob --fund
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
stellar keys generate charlie --fund
```

## Basic Examples

### Unconditional Claimable Balance

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
stellar tx new create-claimable-balance \
  --source alice \
  --amount 50_000_000 \
  --asset native \
  --claimant bob
```

You can also explicitly specify unconditional:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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):

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash cookbooktest.ignore theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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