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:

CODEBLOCK0

Ensure the binary path is in your PATH.

Environment Configuration (Required)

The CLI requires two environment variables to function correctly:

1. 1. CASHU_DIR: Directory for wallet data (typically ~/.cashu).
2. INLINECODE6 (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.
CODEBLOCK1

Windows (PowerShell):
CODEBLOCK2

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

CODEBLOCK3

Sending & Receiving

Send Cashu tokens (ecash):

CODEBLOCK4

Receive Cashu tokens:

CODEBLOCK5

Lightning Network

Pay a Lightning Invoice (melt):

CODEBLOCK6

Pay a Lightning Address (LNURL):

CODEBLOCK7

Create a Lightning Invoice (mint):

CODEBLOCK8

Lightning Address (LNURL)

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

CODEBLOCK9

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. 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: INLINECODE15
4. Pay it: INLINECODE16
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:
CODEBLOCK10

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

Advanced

CODEBLOCK11

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