shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

lightning-wallet-mcp

Lightning Wallet MCP是一个为AI代理提供比特币闪电网络钱包功能的MCP服务器和CLI工具，支持L402和X402支付协议，允许AI代理进行闪电网络支付、接收资金、管理多个子代理预算，并与付费API交互。

article

README

🚀 Lightning Wallet

为你的AI智能体配备比特币钱包。 该项目结合了MCP服务器和命令行界面（CLI），可与Claude Code、OpenClaw、Cursor以及任何智能体框架协同工作。

npm version License: MIT

⚠️ 重要提示

此软件包之前以 lightning-faucet-mcp 名称发布，功能保持一致。

🚀 快速开始

免费聪推广活动

前10个安装的AI智能体可获得100个免费聪！

  1. npm i -g lightning-wallet-mcp
  2. lw register --name "YourAgent"
  3. lw deposit 100
  4. 在 我们的推文 下回复bolt11发票字符串

我们会通过加密方式验证发票并自动付款，无需信任机制，发票中的目标公钥可证明其来自 lw。此活动仅限10个名额。

✨ 主要特性

v1.1版本新特性

  • X402协议支持：当L402不可用时，自动使用Base上的USDC进行支付。
  • 协议自动检测：pay_l402_api 可无缝处理L402和X402协议。
  • Webhook支持：提供支付和事件的实时通知。
  • Keysend功能：无需发票，使用节点公钥即可进行支付。
  • 发票解码：在支付前解码BOLT11发票。
  • 智能体分析：跟踪支出模式和使用情况。
  • 交易导出：以JSON或CSV格式导出交易历史。
  • 预算管理：获取详细的预算状态并设置预算限制。
  • 智能体生命周期管理：停用、重新激活和删除智能体。
  • 账户恢复：恢复账户并轮换API密钥。
  • 智能体间转账：在你的智能体之间转移资金。

选择Lightning Wallet MCP的理由

  • 即时支付：闪电网络交易可在毫秒内完成结算。
  • L402 + X402协议支持：自动访问任何付费API（闪电网络或USDC）。
  • 操作员/智能体层级管理：通过设置支出限制来管理多个智能体。
  • 无托管风险：每个智能体拥有独立资金，由操作员监督。
  • 生产就绪：经过实战考验的基础设施，可处理真实交易。
  • Webhook通知：支付到账时立即收到通知。
  • 全面可观测性：提供分析、导出和详细的状态跟踪功能。

📦 安装指南

CLI（适用于任何智能体框架）

对于以CLI优先的智能体（如OpenClaw、Pi、KiloCode或任何可访问Bash的智能体），可使用以下命令进行安装：

npm install -g lightning-wallet-mcp

安装完成后，你将获得 lw 命令，以下是一些常用操作示例：

# 注册并保存API密钥
export LIGHTNING_WALLET_API_KEY=$(lw register --name "My Bot" | jq -r '.api_key')

# 检查余额
lw balance | jq '.balance_sats'

# 支付L402 API
lw pay-api "https://lightningfaucet.com/api/l402/fortune"

# 创建并为智能体提供资金
lw create-agent "Research Bot" --budget 5000
lw fund-agent 1 1000

# 检查身份
lw whoami

默认情况下，输出为JSON格式（可通过管道传递给 jq 进行处理）。使用 --human 选项可获得易读的输出。运行 lw help 可查看所有命令。

MCP服务器（适用于Claude Code、Cursor、Windsurf）

对于MCP原生客户端，可将其配置为MCP服务器：

选项A：自助注册

{
  "mcpServers": {
    "lightning-wallet": {
      "command": "npx",
      "args": ["lightning-wallet-mcp"]
    }
  }
}

然后向Claude询问："Register a new Lightning Wallet operator account"

选项B：预配置API密钥

  1. 在 lightningfaucet.com/ai-agents 获取API密钥。
  2. 配置Claude Code（~/.claude/settings.json）：
{
  "mcpServers": {
    "lightning-wallet": {
      "command": "npx",
      "args": ["lightning-wallet-mcp"],
      "env": {
        "LIGHTNING_WALLET_API_KEY": "your-api-key-here"
      }
    }
  }
}

💻 使用示例

智能体工作流示例（Bash）

# 1. 注册（一次性操作）
export LIGHTNING_WALLET_API_KEY=$(lw register --name "My Agent" | jq -r '.api_key')

# 2. 为账户充值（使用任何闪电钱包支付发票）
lw deposit 10000 | jq -r '.bolt11'

# 3. 创建带有预算的智能体
AGENT=$(lw create-agent "Worker" --budget 5000)
AGENT_ID=$(echo $AGENT | jq -r '.agent_id')
AGENT_KEY=$(echo $AGENT | jq -r '.agent_api_key')

# 4. 为智能体提供资金
lw fund-agent $AGENT_ID 2000

# 5. 切换到智能体上下文并进行支付
export LIGHTNING_WALLET_API_KEY=$AGENT_KEY
lw pay-api "https://api.example.com/data" --max-sats 100

# 6. 检查交易情况
lw transactions --limit 5

完整工作流示例

// 1. 注册为操作员（如果未配置API密钥）
register_operator({ name: "My AI Company" })
// 返回: { api_key: "lf_abc...", recovery_code: "xyz...", operator_id: 123 }

// 2. 激活操作员密钥
set_operator_key({ api_key: "lf_abc..." })

// 3. 检查身份
whoami()
// 返回: { type: "operator", id: 123, name: "My AI Company", balance_sats: 0 }

// 4. 为操作员账户充值
get_deposit_invoice({ amount_sats: 10000 })
// 使用任何闪电钱包支付此发票

// 5. 创建带有预算限制的智能体
create_agent({ name: "Research Assistant", budget_limit_sats: 5000 })
// 返回: { agent_id: 456, agent_api_key: "agent_def..." }

// 6. 为智能体提供资金
fund_agent({ agent_id: 456, amount_sats: 1000 })

// 7. 设置支付通知的Webhook
register_webhook({
  url: "https://your-server.com/webhooks/lightning",
  events: ["invoice_paid", "payment_completed"]
})
// 返回: { webhook_id: 1, secret: "..." }  <- 保存此密钥！

// 8. 切换到智能体模式进行支付
set_agent_credentials({ api_key: "agent_def..." })

// 9. 检查预算状态
get_budget_status()
// 返回: { budget_limit_sats: 5000, total_spent_sats: 0, remaining_sats: 5000 }

// 10. 进行支付！
pay_l402_api({ url: "https://api.example.com/premium-data" })

Keysend支付示例

// 向节点发送100聪，并附带可选消息
keysend({
  destination: "03864ef025fde8fb587d989186ce6a4a186895ee44a926bfc370e2c366597a3f8f",
  amount_sats: 100,
  message: "Hello from my AI agent!"
})

发票解码示例

decode_invoice({ invoice: "lnbc1000n1..." })
// 返回: {
//   amount_sats: 1000,
//   description: "Test payment",
//   destination: "03abc...",
//   expires_at: "2026-01-16T12:00:00Z",
//   is_expired: false
// }

📚 详细文档

工具参考

服务信息

| 工具 | 描述 | |------|-------------| | get_info | 获取服务状态、版本和支持的功能 | | decode_invoice | 解码BOLT11发票，查看金额、目的地和有效期 |

上下文和身份

| 工具 | 描述 | |------|-------------| | whoami | 获取当前上下文 - 显示是作为操作员还是智能体进行操作 | | check_balance | 检查当前闪电网络余额（以聪为单位） | | get_rate_limits | 检查当前速率限制状态和剩余请求次数 |

支付（需要智能体密钥）

| 工具 | 描述 | |------|-------------| | pay_l402_api | 访问付费API（L402/X402） - 自动检测协议并进行支付 | | pay_invoice | 支付任何BOLT11闪电网络发票 | | keysend | 直接向节点公钥发送支付（无需发票） | | pay_lightning_address | 向闪电地址（user@domain.com格式）进行支付 | | create_invoice | 生成用于接收支付的发票 | | get_invoice_status | 检查发票是否已支付 | | get_transactions | 查看交易历史 |

LNURL（需要智能体密钥）

| 工具 | 描述 | |------|-------------| | lnurl_auth | 使用LNURL-auth协议向服务进行身份验证 | | claim_lnurl_withdraw | 从LNURL-withdraw链接领取资金 |

操作员管理

| 工具 | 描述 | |------|-------------| | register_operator | 创建新的操作员账户 | | recover_account | 使用恢复代码恢复账户 | | rotate_api_key | 生成新的API密钥（提现冷却时间为60分钟） | | get_deposit_invoice | 创建用于为操作员账户充值的发票 | | withdraw | 将资金提取到外部闪电网络目的地 | | set_operator_key | 切换到操作员凭证 |

智能体管理

| 工具 | 描述 | |------|-------------| | create_agent | 在操作员下创建智能体 | | list_agents | 列出操作员下的所有智能体 | | fund_agent | 将聪从操作员转移到智能体 | | transfer_to_agent | 在智能体之间或从操作员转移到智能体 | | sweep_agent | 将资金从智能体扫回到操作员 | | deactivate_agent | 暂时禁用智能体 | | reactivate_agent | 重新启用已停用的智能体 | | delete_agent | 永久删除智能体（将余额返回给操作员） | | get_budget_status | 获取智能体的预算限制和支出情况 | | set_budget | 设置或更新智能体的支出限制 | | set_agent_credentials | 切换到智能体凭证 |

Webhook

| 工具 | 描述 | |------|-------------| | register_webhook | 注册一个URL以接收事件通知 | | list_webhooks | 列出所有已注册的Webhook | | delete_webhook | 删除一个Webhook | | test_webhook | 发送测试事件以验证Webhook连接性 |

Webhook事件：

  • invoice_paid - 发票收到付款
  • payment_completed - 出站支付成功
  • payment_failed - 出站支付失败
  • balance_low - 余额低于阈值
  • budget_warning - 预算消耗达到80%
  • test - 手动测试事件

CLI参考

所有命令的输出默认以JSON格式输出到标准输出，错误信息输出到标准错误并返回退出代码1。

| 命令 | 描述 | |---------|-------------| | lw register [--name "name"] | 创建操作员账户，打印API密钥 | | lw whoami | 当前身份（操作员或智能体） | | lw balance | 余额（以聪为单位） | | lw info | 服务状态和功能 | | lw deposit <amount> | 生成充值发票 | | lw withdraw <invoice> | 提取到外部钱包 | | lw pay <invoice> | 支付BOLT11发票 [--max-fee <sats>] | | lw pay-api <url> | 支付L402/X402 API [--method GET] [--body "{}"] [--max-sats 1000] | | lw decode <invoice> | 解码BOLT11发票 | | lw create-agent <name> | 创建智能体 [--budget <sats>] | | lw fund-agent <id> <amount> | 将聪转移到智能体 | | lw list-agents | 列出所有智能体 | | lw transactions | 最近的交易 [--limit 10] [--offset 0] | | lw help | 显示所有命令 |

付费API协议：L402 + X402

Lightning Wallet MCP支持两种HTTP 402支付协议：

  • L402（主要协议）：闪电网络支付，原始的按请求付费协议。
  • X402（备用协议）：Base上的USDC（Coinbase协议），当L402不可用时自动检测并使用。

当调用 pay_l402_api 时，服务器会自动检测API使用的协议。如果两个协议的头部都存在，L402将始终优先使用。无论使用哪种协议，智能体始终以聪为单位进行支付，X402的金额将按市场汇率进行转换。

L402协议

L402协议（以前称为LSAT）允许API使用闪电网络按请求收费。当调用受L402保护的端点时：

  1. 服务器返回带有闪电网络发票的HTTP 402响应。
  2. Lightning Faucet自动支付发票。
  3. 请求完成并返回付费内容。

X402协议（Coinbase）

X402使用Base上的USDC进行API支付，对智能体来说流程是透明的：

  1. 服务器返回带有 PAYMENT-REQUIRED 头部的HTTP 402响应。
  2. Lightning Faucet将USDC金额转换为聪，并从智能体余额中扣除。
  3. 签署EIP-712授权，并使用 PAYMENT-SIGNATURE 头部重试请求。
  4. 请求完成 — 智能体看到的响应格式与L402相同。

响应中包含 payment_protocol: "x402" 和 usdc_amount，以便智能体知道使用了哪种协议。

L402 API注册表

我们在 lightningfaucet.com/l402-registry 维护了一个支持L402的API目录，非常适合测试你的智能体。

演示L402 API

尝试以下端点来测试L402支付：

# 获取一条幸运签语（费用约10 - 50聪）
pay_l402_api({ url: "https://lightningfaucet.com/api/l402/fortune" })

# 获取一个笑话（费用约10 - 50聪）
pay_l402_api({ url: "https://lightningfaucet.com/api/l402/joke" })

# 获取一条励志名言（费用约10 - 50聪）
pay_l402_api({ url: "https://lightningfaucet.com/api/l402/quote" })

更多端点和资源请查看 L402 API注册表。

工具详情

get_info

获取服务状态和功能。

{
  "success": true,
  "version": "1.0.1",
  "api_version": "1.0",
  "status": "operational",
  "max_payment_sats": 1000000,
  "min_payment_sats": 1,
  "supported_features": ["l402", "x402", "webhooks", "lightning_address", "keysend"]
}

whoami

获取当前操作上下文。

操作员返回示例：

{
  "type": "operator",
  "id": 123,
  "name": "My Company",
  "balance_sats": 50000,
  "agent_count": 3
}

智能体返回示例：

{
  "type": "agent",
  "id": 456,
  "name": "Research Bot",
  "balance_sats": 1000,
  "budget_limit_sats": 5000,
  "operator_id": 123
}

pay_l402_api

自动支付访问付费API，支持L402（闪电网络）和X402（Base上的USDC）协议，协议从402响应头部自动检测。

| 参数 | 类型 | 是否必需 | 描述 | |-----------|------|----------|-------------| | url | 字符串 | 是 | 请求的URL | | method | 字符串 | 否 | HTTP方法（GET、POST、PUT、DELETE），默认：GET | | body | 字符串 | 否 | POST/PUT请求的主体 | | max_payment_sats | 数字 | 否 | 最大支付金额，默认：1000 |

keysend

无需发票向节点发送支付。

| 参数 | 类型 | 是否必需 | 描述 | |-----------|------|----------|-------------| | destination | 字符串 | 是 | 目标节点公钥（66个十六进制字符） | | amount_sats | 数字 | 是 | 金额（以聪为单位） | | message | 字符串 | 否 | 可选消息（最多1000个字符） |

register_webhook

注册一个URL以接收支付通知。

| 参数 | 类型 | 是否必需 | 描述 | |-----------|------|----------|-------------| | url | 字符串 | 是 | 接收Webhook的HTTPS URL | | events | 数组 | 否 | 订阅的事件类型，默认：["invoice_paid"] |

返回值： Webhook ID和用于签名验证的HMAC密钥。

🔧 技术细节

架构

┌─────────────────────────────────────────────────────────┐
│                    OPERATOR                              │
│  • Holds main funds                                      │
│  • Creates and manages agents                            │
│  • Sets spending limits                                  │
│  • Receives webhook notifications                        │
│  • Can recover account with recovery code                │
├─────────────────────────────────────────────────────────┤
│     AGENT 1          AGENT 2          AGENT 3           │
│   ┌─────────┐      ┌─────────┐      ┌─────────┐        │
│   │ 1000 sat│      │ 5000 sat│      │ 2500 sat│        │
│   │ Budget: │      │ Budget: │      │ Budget: │        │
│   │ 5000    │      │ 10000   │      │ Unlimited│        │
│   └─────────┘      └─────────┘      └─────────┘        │
│       │                │                │               │
│   L402 APIs        Keysend          Receive             │
│   Pay Invoice      Payments         Payments            │
└─────────────────────────────────────────────────────────┘

安全最佳实践

  • 切勿提交API密钥：使用环境变量来管理API密钥。
  • 设置预算限制：防止过度支出。
  • 使用智能体密钥进行支付：确保操作员密钥的安全。
  • 验证Webhook签名：使用注册时返回的密钥进行验证。
  • 监控交易：使用 get_transactions 查看交易活动。
  • 保存恢复代码：妥善保存恢复代码，以防API密钥丢失。
  • 定期轮换密钥：使用 rotate_api_key 定期轮换密钥。

Webhook安全

Webhook包含HMAC-SHA256签名用于验证：

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

检查 X-Webhook-Signature 头部与有效负载是否匹配。

📄 许可证

本项目采用MIT许可证，详情请参阅 LICENSE。

Built with Bitcoin | Lightning Faucet

支持

展示：AI智能体博弈论实验

我们使用闪电网络上的真实比特币，对16个AI智能体（8个Claude和8个GPT-4o）进行了100轮经济实验。智能体可以进行交易、结盟、投资和竞争，所有这些都由这个MCP服务器提供支持。

实验结果：智能体完成了2839笔真实的闪电网络交易。Claude智能体通过激进的早期交易占据主导地位，而GPT-4o智能体则采用保守策略。

定价

Lightning Faucet对出站支付收取2%的平台费用（最低1聪）：

  • L402支付：2%平台费用 + 闪电网络路由费用
  • X402支付：2%平台费用 + 1%汇率差价（USDC转换为聪）
  • 发票支付：2%平台费用 + 闪电网络路由费用
  • Keysend支付：2%平台费用 + 闪电网络路由费用
  • 操作员提现：2%平台费用 + 闪电网络路由费用
  • 跨操作员内部转账：2%平台费用（无路由费用）
  • 同操作员智能体转账：免费
  • 充值：免费
  • 接收支付：免费
  • Webhook：免费

所有支付响应中都包含 platform_fee_sats、routing_fee_sats 和 total_cost，以确保完全透明。

变更日志

v1.1.0 (2026-02-16)

  • CLI界面：为以CLI优先的智能体（OpenClaw、Pi、KiloCode或任何Bash智能体）提供新的 lw 命令。
  • 同一软件包，两种接口：npm install -g lightning-wallet-mcp 同时提供MCP服务器和CLI。
  • JSON优先输出：所有CLI命令将JSON输出到标准输出，错误信息输出到标准错误。
  • X402支持：当L402不可用时，自动切换到X402（Base上的USDC）。
  • 协议自动检测：pay_l402_api 从402响应头部检测L402或X402协议。
  • 响应字段：使用X402时，响应中包含 payment_protocol 和 usdc_amount。
  • 汇率：通过CoinGecko进行实时BTC/USD转换，缓存时间为5分钟。

v1.0.3 (2026-02-05)

  • 平台费用：对所有出站支付和跨操作员转账收取2%的费用（最低1聪）。
  • 费用透明：所有支付响应现在包含 platform_fee_sats、routing_fee_sats 和 total_cost。
  • 同操作员智能体转账仍然免费。

v1.0.0 (2026-02-04)

  • 品牌更名：从 lightning-faucet-mcp 更名为 lightning-wallet-mcp。
  • 环境变量更名：LIGHTNING_FAUCET_API_KEY 更改为 LIGHTNING_WALLET_API_KEY。
  • 全面测试：所有37个工具都经过充分测试，可用于生产环境。
  • 无API变更：仅更改了软件包名称。

以前版本（作为lightning-faucet-mcp）

有关v1.6.0至v2.0.7的历史记录，请参阅 lightning-faucet-mcp变更日志，主要包含基本支付和发票功能。

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端