# 🧇 cashu-wallet

A minimal Cashu ecash wallet CLI built for AI agents (OpenClaw, etc.) to send and receive bitcoin.

Built with [@cashu/cashu-ts](https://github.com/cashubtc/cashu-ts) and [Bun](https://bun.sh).

## ⚠️ Caveats (Read These First)

- **This was built by an AI agent in one afternoon.** It works, but it has not been audited, battle-tested, or reviewed by anyone who knows what they're doing with money.
- **Do not use with amounts you can't afford to lose.** Seriously. This is toy money territory. The first 1000 sats ever loaded into this wallet were immediately lost due to a claim bug. Learn from our mistakes.
- **Cashu is custodial.** Your sats live at the mint. If the mint goes down, your ecash goes with it. This is not self-custody.
- **Proofs are bearer instruments.** If someone gets your `wallet.json`, they have your money. Treat it like cash on disk.
- **No backup/recovery.** If you lose your wallet file, your sats are gone. Back it up yourself.
- **No encryption.** The wallet file is plaintext JSON. Your proofs (= your money) are stored in the clear.
- **No fee estimation.** Lightning melt fees are whatever the mint charges. Check your balance after operations.
- **Single mint only.** The wallet talks to one mint at a time (default: minibits). Multi-mint is not supported.
- **No concurrency safety.** Don't run two commands at the same time or you may corrupt state.
- **This is alpha software built for alpha software.** We're agents all the way down.

## Setup

```bash
git clone https://github.com/ArcadeLabsInc/cashu-wallet.git
cd cashu-wallet
bun install
```

## Usage

```bash
# Check balance
bun run cashu-cli.ts balance

# Get a Lightning invoice to fund your wallet
bun run cashu-cli.ts mint <amount>

# After the invoice is paid, claim your tokens
bun run cashu-cli.ts claim <quoteId> <amount>

# Send ecash (outputs a cashu token string)
bun run cashu-cli.ts send <amount>

# Receive a cashu token
bun run cashu-cli.ts receive <token>

# Pay a Lightning invoice
bun run cashu-cli.ts melt <invoice>

# View transaction history
bun run cashu-cli.ts history
```

## Configuration

| Setting | Default | Location |
|---------|---------|----------|
| Mint URL | `https://mint.minibits.cash/Bitcoin` | Hardcoded in `cashu-cli.ts` |
| Wallet state | `~/.openclaw/.cashu-wallet/wallet.json` | Hardcoded in `cashu-cli.ts` |

Change these constants at the top of `cashu-cli.ts` to suit your setup. The wallet dir is auto-created on first run.

## OpenClaw Integration

To make this available to your agent across all sessions, add it to your `TOOLS.md`:

```markdown
## Cashu Wallet (Bitcoin/ecash)

- **Location:** `~/path/to/cashu-wallet/cashu-cli.ts`
- **Run with:** `cd ~/path/to/cashu-wallet && bun run cashu-cli.ts <command>`
- **Mint:** https://mint.minibits.cash/Bitcoin
- **Wallet state:** `~/.openclaw/.cashu-wallet/wallet.json`

### Usage notes
- When someone sends you a cashu token (starts with `cashuA...` or `cashuB...`), use `receive`
- When someone asks you to pay a Lightning invoice, use `melt`
- `send` outputs a token string you can paste to someone
- Always `claim` promptly after someone pays a mint invoice
```

No sidecar needed — Cashu is pull-based. Your agent just calls the CLI when a conversation requires it.

## How It Works

- **Minting:** Creates a Lightning invoice via the mint. After payment, claims ecash proofs.
- **Sending:** Splits proofs via the mint, encodes the send portion as a Cashu token (v4 format).
- **Receiving:** Decodes a Cashu token and swaps the proofs with the mint for fresh ones.
- **Melting:** Pays a Lightning invoice by surrendering proofs to the mint.

Wallet state (proofs + history) is persisted to a local JSON file. Proofs are saved immediately after every operation — we learned the hard way what happens when you don't.

## Dependencies

- [Bun](https://bun.sh) runtime
- [@cashu/cashu-ts](https://github.com/cashubtc/cashu-ts) — Cashu protocol library

## Security

- **wallet.json contains your money.** Keep it safe. `chmod 600` it.
- The wallet file is stored outside the repo directory by default (`~/.openclaw/.cashu-wallet/`).
- No secrets are stored in the source code.
- `.gitignore` excludes `wallet.json`, `node_modules/`, and `bun.lock`.

## License

MIT

## Credits

Built by [Waffle](https://github.com/ArcadeLabsInc) 🧇 — an AI agent running on [OpenClaw](https://openclaw.ai), with guidance from [@futurepaul](https://github.com/futurepaul).

The first mass-market AI agent bitcoin wallet. (Probably. Don't quote us on that.)