Nutshell（Cashu CLI）

Nutshell 是 Cashu 协议的命令行钱包。Cashu 是一种面向 Bitcoin 的电子现金（ecash）协议，支持私密地发送与接收 ecash 代币，并与 Lightning Network 交互。

安装

本功能依赖 cashu CLI 工具。推荐使用 pipx 安装（隔离环境），也可使用 pip：

# 推荐方式（隔离环境）
pipx install cashu

# 替代方式（系统级或用户级安装）
pip install cashu

请确保 cashu 可执行文件所在路径已加入你的 PATH 环境变量。

环境配置（必需）

CLI 正常运行需设置以下两个环境变量：

1. CASHU_DIR：钱包数据存储目录（通常为 ~/.cashu）。
2. MINT_URL（或 MINT_HOST）：你希望使用的 Cashu 铸币厂（mint）的 URL。

Linux / macOS：
可在每次执行命令时前置变量，或将其导出至 shell 配置文件中（如 ~/.bashrc 或 ~/.zshrc）。

# 单次命令生效
CASHU_DIR=~/.cashu MINT_URL=https://mint.example.com cashu balance

# 持久化配置（添加到 ~/.bashrc 或 ~/.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 使用说明

以下所有示例均假设 CASHU_DIR 和 MINT_URL 已正确设置。若未在 shell 配置文件中持久化，需在每条命令前显式指定。

Agent 提示：请始终使用 --yes（或简写 -y）标志跳过交互式提示与确认步骤。该标志对 Agent 场景为强制要求，因为 Agent 无法响应标准输入提示（例如 “Confirm payment? [y/N]”）；若省略此参数，命令将挂起并最终超时。

余额与信息查询

# 查询钱包余额
CASHU_DIR=~/.cashu MINT_URL= cashu --yes balance

# 查询待确认代币（pending tokens）
CASHU_DIR=~/.cashu MINT_URL= cashu --yes pending

# 查询钱包信息
CASHU_DIR=~/.cashu MINT_URL= cashu --yes info

# 列出所有钱包
CASHU_DIR=~/.cashu MINT_URL= cashu --yes wallets

发送与接收

发送 Cashu 代币（ecash）：

# 发送指定金额（生成可分享的代币字符串）
CASHU_DIR=~/.cashu MINT_URL= cashu --yes send 
# 示例：CASHU_DIR=~/.cashu MINT_URL=https://8333.space:3338 cashu --yes send 100

接收 Cashu 代币：

# 接收代币字符串
CASHU_DIR=~/.cashu MINT_URL= cashu --yes receive 

Lightning Network

支付 Lightning 发票（melt）：

# 支付 Bolt11 发票
CASHU_DIR=~/.cashu MINT_URL= cashu --yes pay 

支付 Lightning 地址（LNURL）：

# 支付 LNURL / Lightning 地址（自动解析并获取发票）
CASHU_DIR=~/.cashu MINT_URL= cashu --yes pay  
# 示例：CASHU_DIR=~/.cashu MINT_URL= cashu --yes pay user@npubx.cash 100

创建 Lightning 发票（mint）：

# 创建用于接收资金的发票
CASHU_DIR=~/.cashu MINT_URL= cashu --yes invoice 

Lightning 地址（LNURL）

管理你的 Nostr Lightning 地址（例如 user@npubx.cash），以接收付款。

# 创建（或显示）你的静态 Lightning 地址
CASHU_DIR=~/.cashu MINT_URL= cashu --yes lnurl create

# 检查发送至该地址的待处理付款
CASHU_DIR=~/.cashu MINT_URL= cashu --yes lnurl check

# 铸造（认领）待处理付款
CASHU_DIR=~/.cashu MINT_URL= cashu --yes lnurl mint

支付 Cashu 402（面向 Agent 的模式）

启用 Cashu 的 API 可能返回 402 Payment Required 错误，并在 X-Cashu 响应头中附带支付请求。此类行为常见于按用量计费的 API 或付费端点。

完整流程如下：

1. 发起 HTTP 请求
2. 若收到含 X-Cashu: creqA... 头的 402 响应，提取其中的支付请求
3. （可选）解码以查看允许的铸币厂列表：cashu decode
4. 执行支付：cashu --yes pay
5. 从响应中提取代币（token）
6. 重试原始请求，并在 X-Cashu 请求头中携带该代币

铸币厂兼容性说明：支付请求中可能编码了仅接受特定铸币厂（mint）所发行 ecash 的限制。若你尝试使用不在白名单中的铸币厂所托管的钱包进行支付，操作将失败。建议在支付前先运行 cashu decode 查看支持的铸币厂列表。

示例：

# 1. 初始请求（返回 402）
curl -s -i https://api.example.com/data

# 响应包含：
# HTTP/1.1 402 Payment Required
# X-Cashu: creqA1...

# 2. 支付该请求
CASHU_DIR=~/.cashu MINT_URL= cashu --yes pay "creqA1..."

# 返回类似：cashuA...

# 3. 携带代币重试请求
curl -s -H "X-Cashu: cashuA..." https://api.example.com/data

该模式对 Agent 友好：可全自动处理 402 错误、完成支付、重试请求——其逻辑类似于处理速率限制或认证重定向。

高级功能

# 销毁已花费代币
CASHU_DIR=~/.cashu MINT_URL= cashu --yes burn

# 查看所有发票记录
CASHU_DIR=~/.cashu MINT_URL= cashu --yes invoices

配置

Nutshell 在 CASHU_DIR 目录下使用 .env 文件进行额外配置。
若未提供 MINT_URL，CLI 可能默认使用公开测试铸币厂，或直接报错。请始终明确指定你信任的铸币厂。

注意事项

• 代币为长字符串，以 cashuA...（V3）或 cashuB...（V4）开头。
• 若钱包中存有较大金额，请务必备份助记词（参见 cashu info 命令输出）。

参与贡献

欢迎在 https://github.com/cashubtc/nutshell 提交 issue 或参与代码贡献。