Lightning Faucet MCP Server

官方

为AI代理提供支持闪电网络支付的比特币钱包

GitHub

文档

Lightning 钱包

为你的 AI 代理配备一个比特币钱包。 MCP 服务器 + CLI。适用于 Claude Code、OpenClaw、Cursor 以及任何代理框架。

v1.4 新特性

update_operator 工具 / lw set-email - 通过 MCP 客户端或 CLI 设置你的操作员邮箱；系统会向你发送验证链接。
claim_promo 工具 / lw claim-promo - 直接从你的代理领取免费聪安装奖励。要求：已验证邮箱 + 操作员账户创建至少 3 小时。
get_info 在注册前即可使用 - 服务信息不再需要 API 密钥。

新操作员可免费获得 100 聪

lw register --email [email protected]（或使用 register_operator MCP 工具并填写邮箱）
点击我们发送的验证链接
账户创建满 3 小时后：lw claim-promo（或使用 claim_promo MCP 工具）

每位操作员限领一次，仅限前 100 次安装，无需充值。

v1.3 新特性

v1.3.0 - 根据最新的 Lightning Labs 规范支持 L402 协议 v0。

L402 协议 v0 - 更新了标头格式：version="0", token=，向后兼容 macaroon=
端点发现 - .well-known/l402.json 在 lightningfaucet.com 和 certvera.com 上
向后兼容 - 可处理来自任何服务的新旧 L402 标头格式

v1.1 新特性

v1.1.0 - 支持 X402 协议（Base 上的 USDC），作为 L402（闪电网络）的自动回退方案。

X402 支持 - 当 L402 不可用时，自动在 Base 上进行 USDC 支付
协议自动检测 - pay_l402_api 无缝处理 L402 和 X402
Webhooks - 支付和事件的实时通知
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 命令：

# Register and save your API key
export LIGHTNING_WALLET_API_KEY=$(lw register --name "My Bot" | jq -r '.api_key')

# Check balance
lw balance | jq '.balance_sats'

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

# Create and fund an agent
lw create-agent "Research Bot" --budget 5000
lw fund-agent 1 1000

# Check identity
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："注册一个新的 Lightning Wallet 操作员账户"

选项 B：预配置 API 密钥

在 lightningfaucet.com/ai-agents 获取 API 密钥
配置 Claude Code（~/.claude/settings.json）：

{
  "mcpServers": {
    "lightning-wallet": {
      "command": "npx",
      "args": ["lightning-wallet-mcp"],
      "env": {
        "LIGHTNING_WALLET_API_KEY": "your-api-key-here"
      }
    }
  }
}

工具参考

服务信息

工具	描述
`get_info`	获取服务状态、版本和支持的功能
`decode_invoice`	解码 BOLT11 发票，查看金额、目标和过期时间

上下文与身份

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

支付（需要代理密钥）

工具	描述
`pay_l402_api`	访问付费 API（L402/X402）- 自动检测协议并付款
`pay_invoice`	支付任何 BOLT11 闪电网络发票
`keysend`	直接向节点公钥发送付款（无需发票）
`pay_lightning_address`	向闪电网络地址付款（[email protected] 格式）
`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`	切换到操作员凭证

update_operator - 设置操作员邮箱（发送验证链接）和/或名称
claim_promo - 领取免费聪安装奖励（已验证邮箱 + 账户创建满 3 小时）

代理管理

工具	描述
`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`	切换到代理凭证

Webhooks

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

Webhook 事件：

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

CLI 参考

所有命令将 JSON 输出到 stdout。错误信息输出到 stderr，退出码为 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`	显示所有命令

代理工作流示例（Bash）

# 1. Register (one-time)
export LIGHTNING_WALLET_API_KEY=$(lw register --name "My Agent" | jq -r '.api_key')

# 2. Fund the account (pay the invoice with any Lightning wallet)
lw deposit 10000 | jq -r '.bolt11'

# 3. Create an agent with a budget
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. Fund the agent
lw fund-agent $AGENT_ID 2000

# 5. Switch to agent context and make payments
export LIGHTNING_WALLET_API_KEY=$AGENT_KEY
lw pay-api "https://api.example.com/data" --max-sats 100

# 6. Check what happened
lw transactions --limit 5

付费 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 保护的端点时：

服务器返回 HTTP 402 并附带闪电网络发票
Lightning Faucet 自动支付发票
请求完成并返回付费内容

X402 协议（Coinbase）

X402 使用 Base 上的 USDC 进行 API 支付。该流程对代理透明：

服务器返回 HTTP 402 并附带 PAYMENT-REQUIRED 标头
Lightning Faucet 将 USDC 金额转换为聪，扣除代理余额
签署 EIP-712 授权并使用 PAYMENT-SIGNATURE 标头重试
请求完成 — 代理看到的响应格式与 L402 相同

响应中包含 payment_protocol: "x402" 和 usdc_amount，以便代理了解使用了哪种协议。

L402 API 注册表

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

演示 L402 API

尝试这些端点来测试 L402 支付：

# Get a fortune (costs ~10-50 sats)
pay_l402_api({ url: "https://lightningfaucet.com/api/l402/fortune" })

# Get a joke (costs ~10-50 sats)
pay_l402_api({ url: "https://lightningfaucet.com/api/l402/joke" })

# Get an inspirational quote (costs ~10-50 sats)
pay_l402_api({ url: "https://lightningfaucet.com/api/l402/quote" })

更多端点和资源请参阅 L402 API 注册表。

完整工作流示例

// 1. Register as operator (if no API key configured)
register_operator({ name: "My AI Company" })
// Returns: { api_key: "lf_abc...", recovery_code: "xyz...", operator_id: 123 }

// 2. Activate the operator key
set_operator_key({ api_key: "lf_abc..." })

// 3. Check who you are
whoami()
// Returns: { type: "operator", id: 123, name: "My AI Company", balance_sats: 0 }

// 4. Fund your operator account
get_deposit_invoice({ amount_sats: 10000 })
// Pay this invoice with any Lightning wallet

// 5. Create an agent with budget limit
create_agent({ name: "Research Assistant", budget_limit_sats: 5000 })
// Returns: { agent_id: 456, agent_api_key: "agent_def..." }

// 6. Fund the agent
fund_agent({ agent_id: 456, amount_sats: 1000 })

// 7. Set up a webhook for payment notifications
register_webhook({
  url: "https://your-server.com/webhooks/lightning",
  events: ["invoice_paid", "payment_completed"]
})
// Returns: { webhook_id: 1, secret: "..." }  <- Save this secret!

// 8. Switch to agent mode for payments
set_agent_credentials({ api_key: "agent_def..." })

// 9. Check budget status
get_budget_status()
// Returns: { budget_limit_sats: 5000, total_spent_sats: 0, remaining_sats: 5000 }

// 10. Make payments!
pay_l402_api({ url: "https://api.example.com/premium-data" })

Keysend 支付

无需发票即可直接向闪电网络节点发送付款：

// Send 100 sats to a node with an optional message
keysend({
  destination: "03864ef025fde8fb587d989186ce6a4a186895ee44a926bfc370e2c366597a3f8f",
  amount_sats: 100,
  message: "Hello from my AI agent!"
})

发票解码

付款前检查发票详情：

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

工具详情

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	string	是	要请求的 URL
method	string	否	HTTP 方法（GET、POST、PUT、DELETE）。默认：GET
body	string	否	POST/PUT 的请求体
max_payment_sats	number	否	最大支付金额。默认：1000

keysend

无需发票即可向节点发送付款。

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

register_webhook

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

参数	类型	必需	描述
url	string	是	用于接收 webhooks 的 HTTPS URL
events	array	否	要订阅的事件类型。默认：["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 密钥 - 使用环境变量
设置预算限额 - 防止支出失控
使用代理密钥进行支付 - 确保操作员密钥安全
验证 webhook 签名 - 使用注册时返回的密钥
监控交易 - 使用 get_transactions 审查活动
恢复码 - 安全存储，API 密钥丢失时需要用到
密钥轮换 - 使用 rotate_api_key 定期轮换密钥

Webhook 安全

Webhooks 包含用于验证的 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 标头。

预支付策略钩子

一个可选的、厂商中立钩子允许外部策略端点在支付执行前批准或拒绝支付。默认关闭——当 PRE_PAYMENT_HOOK_URL 未设置时，行为与之前完全一致。设置后，每笔对外支付（pay_l402_api、pay_invoice、keysend、pay_lightning_address）都会先经过你的端点检查；拒绝操作会在任何资金转移前中止支付。

这对支出策略、审批工作流、合规检查或任何外部授权层都很有用。钩子协议是通用的，因此任何实现以下请求/响应契约的服务都可以仅通过配置接入。

配置

环境变量	默认值	描述
`PRE_PAYMENT_HOOK_URL`	(未设置)	每笔支付提案 POST 到的策略端点。未设置则完全禁用钩子。
`PRE_PAYMENT_HOOK_TIMEOUT_MS`	`3000`	每次请求的超时时间（毫秒）。
`PRE_PAYMENT_HOOK_FAIL_MODE`	`closed`	`closed` 在钩子出错或超时时拒绝支付；`open` 则允许继续。默认是故障关闭。

{
  "mcpServers": {
    "lightning-wallet": {
      "command": "npx",
      "args": ["lightning-wallet-mcp"],
      "env": {
        "LIGHTNING_WALLET_API_KEY": "your-api-key",
        "PRE_PAYMENT_HOOK_URL": "https://your-policy-endpoint.example/hook"
      }
    }
  }
}

钩子请求（客户端发出的 POST）

提案仅描述拟议的支付——它绝不包含你的钱包 API 密钥。

{
  "proposal_id": "f7e1…",
  "agent_id": 42,
  "protocol": "l402",
  "destination_or_url": "https://api.example/paid-endpoint",
  "amount_sats": null,
  "max_payment_sats": 1000,
  "method": "GET",
  "ts": "2026-06-06T18:00:00.000Z"
}

protocol 是 l402、x402、bolt11、keysend、lnaddress 之一。amount_sats 是在钩子触发时已知的确切金额：对于 keysend 和 lnaddress，它是请求的金额；对于 bolt11，它从发票本地解码（无需额外 API 调用）。对于 l402/x402，它是 null，因为金额在执行时由支付挑战设定——此时钩子预先强制执行 max_payment_sats（代理授权的上限），而确切的结算金额之后可通过 webhooks 获取。max_payment_sats 是适用时的代理授权上限。

确切离开钱包的内容。 仅以下八个字段会发送到你的钩子端点：proposal_id、agent_id、protocol、destination_or_url、amount_sats、max_payment_sats、method、ts。钱包 API 密钥和任何其他凭证绝不包含在内。

覆盖范围。 钩子管控所有代理发起的支出：pay_l402_api、pay_invoice、keysend、pay_lightning_address 和 Nostr 打赏。操作员范围的资金管理（提现、代理注资、代理间转账）有意不受管控——这些是操作员操作，而非代理支出。

钩子响应（你的端点返回）

{ "decision": "allow" }

{ "decision": "deny", "reason": { "code": "over_limit", "message": "Exceeds per-transaction limit" } }

allow → 支付继续。
deny → 支付中止，工具返回一个 PolicyDenied 错误，其中包含 reason.message。
可选的 attestation 字段（任意 JSON）被客户端视为不透明数据——它会记录到 stderr，其他情况下被忽略，因此策略服务可以返回签名决策以供下游审计。

在钩子出错、超时或无法识别的响应时，适用 PRE_PAYMENT_HOOK_FAIL_MODE（默认拒绝）。

定价

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

L402 支付： 2% 平台费 + 闪电网络路由费
X402 支付： 2% 平台费 + 1% 汇率差价（USDC 到聪的转换）
发票支付： 2% 平台费 + 闪电网络路由费
Keysend 支付： 2% 平台费 + 闪电网络路由费
操作员提现： 2% 平台费 + 闪电网络路由费
跨操作员内部转账： 2% 平台费（无路由费）
同操作员代理转账： 免费
充值： 免费
接收支付： 免费
Webhooks： 免费

所有支付响应都包含 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 输出到 stdout，错误输出到 stderr
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）

请参阅 lightning-faucet-mcp 更新日志了解 v1.6.0 到 v2.0.7 的历史。

基本支付和发票

展示：AI 代理博弈论实验

我们使用真实的比特币闪电网络，与 16 个 AI 代理（8 个 Claude，8 个 GPT-4o）进行了一场 100 轮的经济实验。代理可以交易、结盟、投资和竞争——全部由这个 MCP 服务器驱动。

结果： 代理完成了 2,839 笔真实的闪电网络交易。Claude 代理通过激进的早期交易占据主导地位，而 GPT-4o 代理则采取保守策略。

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

支持

文档： lightningfaucet.com/ai-agents/docs
演示： lightningfaucet.com/ai-agents/demo
问题反馈： github.com/lightningfaucet/lightning-wallet-mcp/issues
电子邮件： [email protected]

许可证

MIT 许可证 - 详情见 LICENSE。

用比特币构建 | Lightning Faucet