Cashu

Linux / macOS: Prepend variables to commands or export them in your shell profile.

# 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):

$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

# 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):

# 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:

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

Lightning Network

Pay a Lightning Invoice (melt):

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

Pay a Lightning Address (LNURL):

# Pay an LNURL/Lightning Address (automatically resolves the invoice)
CASHU_DIR=~/.cashu MINT_URL=<url> cashu --yes pay <[email protected]> <amount_sats>
# Example: CASHU_DIR=~/.cashu MINT_URL=<url> cashu --yes pay [email protected] 100

Create a Lightning Invoice (mint):

# 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., [email protected]) to receive payments.

# 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:

# 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

# 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