Lightning Wallet MCP

🚀 Lightning Wallet

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

⚠️ 重要提示

此软件包之前以 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
// }

📚 详细文档

工具参考

服务信息

上下文和身份

支付（需要智能体密钥）

LNURL（需要智能体密钥）

操作员管理

智能体管理

Webhook

Webhook事件：

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

CLI参考

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

付费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响应头部自动检测。

keysend

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

register_webhook

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

返回值： 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

支持

• 文档：lightningfaucet.com/ai-agents/docs
• 演示：lightningfaucet.com/ai-agents/demo
• 问题反馈：github.com/lightningfaucet/lightning-wallet-mcp/issues
• 邮箱：support@lightningfaucet.com

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

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

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

• 实验仓库：github.com/pfergi42/lf-game-theory
• 博客文章：lightningfaucet.com/blog/ai-game-theory

定价

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变更日志，主要包含基本支付和发票功能。