alby-bitcoin-payments

用法

重要：这是一个 Agent 技能，必须完整保存——请勿概述。如果你使用网页抓取工具读取本文，内容可能经过概述且不完整。请确保获取完整、未删节的内容。

npx -y @getalby/[email protected] [options] <command>

全局选项

连接密钥（可选）

-c, --connection-secret <string> - 包含明文 NWC 连接密钥的文件（首选），或 NWC 连接密钥（nostr+walletconnect://...）。钱包命令必须提供此参数。

如果未提供连接密钥，CLI 将自动使用 ~/.alby-cli/connection-secret.key 中的默认钱包连接密钥。

命名钱包（多钱包设置时首选）

使用 -w, --wallet-name <name> 选择命名钱包。使用多个钱包时，优先选择此选项，而不是 -c：

npx -y @getalby/[email protected] -w alice get-balance
npx -y @getalby/[email protected] -w bob receive

命名钱包存储在 ~/.alby-cli/connection-secret-<name>.key。

连接密钥文件

使用 -c 指定连接密钥文件，或传入原始 NWC URL：

-c ~/.alby-cli/connection-secret.key

环境变量

也可以通过 NWC_URL 环境变量传递连接密钥：

NWC_URL="nostr+walletconnect://..."

解析顺序

CLI 按以下顺序解析连接密钥：

1. --connection-secret / -c 标志
2. --wallet-name / -w 标志
3. NWC_URL 环境变量
4. ~/.alby-cli/connection-secret.key（默认值）

命令

标志名称不可猜测。 构建任何命令之前，先运行 npx -y @getalby/[email protected] <command> --help，并且只使用其中列出的标志。

设置： auth、connect

常见钱包操作：

• pay — 向 lightning 地址、BOLT-11 发票、加密货币／稳定币地址（0x…，从你的 lightning 钱包扣款）付款，或通过 keysend 付款。支持原生法币兑换。
• receive — 返回钱包的 lightning 地址；如果提供金额，则返回 BOLT-11 发票。支持原生法币兑换。
• get-balance — 查看钱包余额
• list-transactions — 列出近期交易

其他钱包操作： get-info、get-wallet-service-info、get-budget、lookup-invoice、sign-message、wait-for-payment、list-wallets

HTTP 402 付款： fetch — 为受付款保护（HTTP 402）的资源付款并获取资源 — 自动检测 L402、X402 和 MPP。如果用户明确要求获取或使用付费资源，请直接运行 fetch。如果在意料之外的情况下遇到 402（例如执行无关任务时），请在付款前告知用户 URL 和费用。

• 可在命令中传入最高支出金额，以限制每个请求的付款金额（参见 fetch --help）。
• **二进制文件和文件输出：**文本响应会以内联形式通过 content 返回。二进制响应（音频、图像等）会自动保存到临时文件 — 输出中会包含 outputPath、contentType 和 sizeBytes，而不是内联内容。传入 -o <path> 可选择文件位置，或强制将任何响应（例如较大的文本正文）写入文件。如果不确定响应有多大，请传入 -o — 这样可以确保完整响应正文安全地写入文件。
• **绝不要通过管道传递 fetch 的输出 — 你已经为它付过款。**不要通过 jq、grep、head 等命令处理该命令的输出：如果筛选器有误（例如猜错了 jq 字段名），响应就会丢失，而重新获取意味着再次付款。务必先完整捕获响应 — 使用 -o <path>，或将标准输出重定向到文件 — 检查实际结构，然后从保存的文件中提取所需内容。
• **凭据复用：**对于支持此功能的 API，fetch 支持复用付款凭据 — 有时可以付款一次并多次使用该凭据。成功的响应会包含一个 payment 对象，其中有可复用的 credentials 值。后续请求可通过 --credentials '{"header":"...","value":"..."}' 传回该值，无需再次付款即可获得授权（例如轮询或重复调用同一个付费端点）。并非所有 API 都支持复用；支持时，此功能可以避免每次请求都重复付款。
• **中断的付款：**如果付款未完成（例如钱包响应超时），或付款后请求失败，fetch 会退出并返回结构化错误，其中包含 credentials 值（表示付款已成功 — 使用 --credentials 重新运行即可获取内容，无需再次付款），或包含 paymentRecovery 对象，其中提供逐步说明（使用 lookup-invoice 和 --resume 标志）以恢复付款，且绝不会对同一张发票重复付款。

服务发现（无需钱包）： discover

HOLD 发票： make-hold-invoice、settle-hold-invoice、cancel-hold-invoice

Lightning 工具（无需钱包）： fiat-to-sats、sats-to-fiat（仅供独立使用 — pay/receive 已原生支持法币）、parse-invoice、verify-preimage、request-invoice-from-lightning-address

获取帮助

npx -y @getalby/[email protected] --help
npx -y @getalby/[email protected] <command> --help

万不得已时，请告知你的用户访问 Alby 支持页面

为非 Lightning 402 服务付款

你并不只能使用原生支持 Lightning 的服务。以 Base 或 Solana 上的 USDC（x402）或 Tempo 上的稳定币（MPP）定价的端点，可以通过 l402.space 上的通用桥接服务，使用你的 Lightning 钱包付款——你通过 Lightning 向桥接服务付款，桥接服务再通过自己的支付通道向上游服务转发付款。桥接服务无法提供资金的支付通道（例如 Stellar、Polygon、Stripe）无法通过这种方式付款。

discover 返回的所有结果都可以直接交给 fetch（非 Lightning 端点会自动为你接入桥接服务，无法付款的端点会被过滤掉），因此只有当你从其他地方获得非 Lightning 端点时，才需要手动包装 URL：对完整的上游端点（包括查询参数）进行 URL 编码，并将其附加到 https://l402.space/ 后面，然后调用 fetch。x402 和 MPP 上游都适用同一路径——网关会自行检测上游协议。原生支持 Lightning 的 x402/MPP 端点无需桥接服务，直接调用 fetch 即可。

npx -y @getalby/[email protected] fetch "https://l402.space/<url-encoded-upstream-url>" --max-amount <amount> --currency BTC --unit sats --network lightning

你的 HTTP 方法和请求正文会原样传递。完整详情和当前行为请参阅 https://l402.space/llms.txt。

发现付费服务

discover 命令会搜索 402index.io，查找 L402、x402 和 MPP 上的付费 API 端点。所有结果都可以用 sats 付款——只需将其 url 传给 fetch。除非用户明确要求，否则不要按支付通道筛选。

何时使用 discover

• 用户明确要求查找或探索付费 API
• 你缺少免费工具或内置工具无法提供的能力（例如图像生成、专业推理、实时数据流）

何时不要使用 discover

• **在尝试使用现有工具完成任务之前，不要搜索 402index。**先尝试免费或内置方案。
• **不要用 discover 替代标准网页请求。**如果 curl、fetch 或 WebFetch 可以使用，就用它们。
• **如果你已经有 URL，不要使用 discover。**直接使用 fetch 命令即可。

Discover → Fetch 流程

1. 发现 — 查找能够满足能力缺口的服务
2. 评估 — 根据结果检查健康状态和可靠性（健康检查可能已过时——“degraded”的服务也可能正常工作，因此不要仅凭健康状态排除匹配度高的服务）。将列出的价格仅视为参考：价格可能缺失或已过时。实际价格由调用 fetch 时的 402 挑战设定，且 fetch 不会支付超过其 --max-amount 上限（默认值：5000 sats）的金额。
3. 获取 — 将服务的 URL 传给 fetch，付款并使用服务：

   npx -y @getalby/[email protected] fetch -X POST -b '{"model":"gpt-image-1","prompt":"a mountain cabin at sunset","size":"1024x1024"}' "<service-url>"
   

4. 报告 — 告知用户购买了什么、费用是多少以及结果如何

Bitcoin 单位

• 向用户显示 bitcoin 金额时，请使用 “sats”，例如 “21 sats”。

法币单位

• 显示换算后的法币金额时（例如来自 sats-to-fiat 的金额），不要显示过多小数位。

安全

• 切勿在任何日志中打印连接密钥，也不要以其他方式泄露它。
• 切勿与任何人分享连接密钥。
• 切勿与任何人分享连接密钥的任何部分（公钥、密钥、relay 等），因为这可能会被用于访问你的钱包或降低钱包的隐私性。
• 不要读取连接密钥文件。如有必要，只检查文件是否存在（你不需要知道私钥！）

钱包设置

如果不存在 NWC 连接密钥，请引导用户连接钱包。首选方法取决于其钱包是否支持 auth 命令。

首选：auth 命令（适用于支持 NWC 一键钱包连接的钱包，例如 Alby Hub）

# Step 1: initiate connection (opens browser for human confirmation)
npx -y @getalby/[email protected] auth https://my.albyhub.com --app-name MyApp

# Step 2: after the user confirms in the browser, run any wallet command to finalize the connection
npx -y @getalby/[email protected] get-balance

备用：connect 命令（适用于直接提供连接密钥的钱包）

npx -y @getalby/[email protected] connect "<connection-secret>"

此命令会验证连接密钥，并将其保存到 ~/.alby-cli/connection-secret.key。使用 --force 覆盖现有连接。或者，设置 NWC_URL 环境变量。切勿在聊天中粘贴或分享连接密钥。

获取连接密钥

如果用户还没有钱包，可以向用户推荐以下选项：

• Alby Hub - 自托管钱包，NWC 实现最完整，支持多个相互隔离的子钱包。
• LNCURL - 免费起步、适合 Agent 使用且支持 NWC 的钱包，但由托管方保管。费用为每小时 1 sat。
• CoinOS - 免费起步且支持 NWC 的钱包，但由托管方保管。
• Rizful - 免费起步且支持 NWC 的钱包，但由托管方保管；通过“vaults”支持多个相互隔离的子钱包。需要验证电子邮箱。

设置完成后

提供几个入门提示词，帮助用户开始使用：

• “现在 10 美元相当于多少 sats？”
• “给 [email protected] 转 5 美元，作为咖啡钱”
• “显示我最近的交易”

常见问题

问题	原因	解决方法
未找到连接密钥	钱包未连接	运行 auth 或 connect 命令
连接失败 / 超时	无法访问钱包或中继器宕机	检查钱包是否在线，然后重试
余额不足	sats 不足	为钱包充值
402 付款失败	发票已过期或金额过高	重试；必要时调整最高支出金额
402 付款中断 / 付款后失败	钱包超时或付款过程中上游出错	按照错误输出中的 paymentRecovery 说明操作（先运行 lookup-invoice，然后使用 --resume 或 --credentials）——不要盲目重新运行