cashu

# Nutshell (Cashu CLI)

Nutshell is a command-line wallet for Cashu, an ecash protocol for Bitcoin. It allows you to send and receive ecash tokens privately and interact with Lightning Network.

## Installation

This skill requires the `cashu` CLI. Install it via `pipx` (recommended) or `pip`:

```bash
# Recommended (isolated environment)
pipx install cashu

# Alternative (system/user wide)
pip install cashu
```

Ensure the binary path is in your `PATH`.

## Environment Configuration (Required)

The CLI requires two environment variables to function correctly:

1. `CASHU_DIR`: Directory for wallet data (typically `~/.cashu`).
2. `MINT_URL` (or `MINT_HOST`): The URL of the Cashu mint you want to use.

**Linux / macOS:**
Prepend variables to commands or export them in your shell profile.
```bash
# Per-command
CASHU_DIR=~/.cashu MINT_URL=https://mint.example.com cashu balance

# Persistent (add to ~/.bashrc or ~/.zshrc)
export CASHU_DIR=~/.cashu
export MINT_URL=https://mint.example.com
```

**Windows (PowerShell):**
```powershell
$env:CASHU_DIR = "$HOME\.cashu"
$env:MINT_URL = "https://mint.example.com"
cashu balance
```

## CLI Usage

All examples below assume `CASHU_DIR` and `MINT_URL` are set. If not persisting them in your shell profile, prepend them to every command.

**Agent Tip:** Always use the `--yes` (or `-y`) flag to skip interactive prompts and confirmations. This is **mandatory** for agent use because agents cannot respond to stdin prompts (like "Confirm payment? [y/N]"); omitting it will cause the command to hang and time out.

### Balance & Info

```bash
# Check wallet balance
CASHU_DIR=~/.cashu MINT_URL=<url> cashu --yes balance

# Check pending tokens
CASHU_DIR=~/.cashu MINT_URL=<url> cashu --yes pending

# Get wallet info
CASHU_DIR=~/.cashu MINT_URL=<url> cashu --yes info

# List wallets
CASHU_DIR=~/.cashu MINT_URL=<url> cashu --yes wallets
```

### Sending & Receiving

**Send Cashu tokens (ecash):**

```bash
# Send amount (generates a token string to share)
CASHU_DIR=~/.cashu MINT_URL=<url> cashu --yes send <amount>
# Example: CASHU_DIR=~/.cashu MINT_URL=https://8333.space:3338 cashu --yes send 100
```

**Receive Cashu tokens:**

```bash
# Receive a token string
CASHU_DIR=~/.cashu MINT_URL=<url> cashu --yes receive <token_string>
```

### Lightning Network

**Pay a Lightning Invoice (melt):**

```bash
# Pay an invoice
CASHU_DIR=~/.cashu MINT_URL=<url> cashu --yes pay <bolt11_invoice>
```

**Pay a Lightning Address (LNURL):**

```bash
# Pay an LNURL/Lightning Address (automatically resolves the invoice)
CASHU_DIR=~/.cashu MINT_URL=<url> cashu --yes pay <user@domain.com> <amount_sats>
# Example: CASHU_DIR=~/.cashu MINT_URL=<url> cashu --yes pay user@npubx.cash 100
```

**Create a Lightning Invoice (mint):**

```bash
# Create an invoice to receive funds into the wallet
CASHU_DIR=~/.cashu MINT_URL=<url> cashu --yes invoice <amount>
```

### Lightning Address (LNURL)

Manage your Nostr Lightning Address (e.g., `user@npubx.cash`) to receive payments.

```bash
# Create (or display) your static Lightning Address
CASHU_DIR=~/.cashu MINT_URL=<url> cashu --yes lnurl create

# Check for pending payments sent to your address
CASHU_DIR=~/.cashu MINT_URL=<url> cashu --yes lnurl check

# Mint (claim) the pending payments
CASHU_DIR=~/.cashu MINT_URL=<url> cashu --yes lnurl mint
```

### Paying Cashu 402s (Agentic Pattern)

Cashu-enabled APIs may return a **402 Payment Required** error with a payment request in the `X-Cashu` header. This is common for metered APIs or paid endpoints.

**The flow:**
1. Make your HTTP request
2. If you get a 402 with `X-Cashu: creqA...` header, extract the payment request
3. (Optional) Decode it to check accepted mints: `cashu decode <payment_request>`
4. Pay it: `cashu --yes pay <payment_request>`
5. Get the token from the response
6. Retry the original request, including the token in the `X-Cashu` header

**Mint compatibility:** Payment requests may encode specific mints from which ecash is accepted. If you try to pay with a wallet backed by a mint not in the allowed list, it will error. Use `cashu decode <creq>` to see which mints are accepted before attempting payment.

**Example:**
```bash
# 1. Initial request (returns 402)
curl -s -i https://api.example.com/data

# Response includes:
# HTTP/1.1 402 Payment Required
# X-Cashu: creqA1...

# 2. Pay the payment request
CASHU_DIR=~/.cashu MINT_URL=<url> cashu --yes pay "creqA1..."

# Returns a token like: cashuA...

# 3. Retry with token
curl -s -H "X-Cashu: cashuA..." https://api.example.com/data
```

This pattern is agentic-friendly: handle 402 automatically, pay, retry — just like handling rate limits or auth redirects.

### Advanced

```bash
# Burn spent tokens
CASHU_DIR=~/.cashu MINT_URL=<url> cashu --yes burn

# View all invoices
CASHU_DIR=~/.cashu MINT_URL=<url> cashu --yes invoices
```

## Configuration

Nutshell uses a `.env` file inside `CASHU_DIR` for additional configuration.
If `MINT_URL` is not provided, it may default to a public test mint or fail. Always specify your trusted mint.

## Notes

- Tokens are large strings starting with `cashuA...` (V3) or `cashuB...` (V4).
- Ensure you back up your mnemonic if using significant funds (see `cashu info`).

## Contributing

Open issues or contribute at https://github.com/cashubtc/nutshell