Lightning Faucet MCP Server

官方

為AI代理提供支援閃電網路支付的比特幣錢包

GitHub

文件

Lightning Wallet

為你的 AI 代理提供一個比特幣錢包。 MCP 伺服器 + CLI。適用於 Claude Code、OpenClaw、Cursor 及任何代理框架。

v1.4 新功能

update_operator 工具 / lw set-email - 從 MCP 客戶端或 CLI 設定你的操作者電子郵件；系統會寄送驗證連結給你。
claim_promo 工具 / lw claim-promo - 直接從你的代理領取免費 sats 安裝推廣獎勵。需求：已驗證的電子郵件 + 操作者帳戶至少建立 3 小時。
get_info 在註冊前即可使用 - 服務資訊不再需要 API 金鑰。

新操作者免費 100 sats

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（Lightning）的自動備援。

X402 支援 - 當 L402 不可用時，自動在 Base 上進行 USDC 付款
協議自動偵測 - pay_l402_api 無縫處理 L402 和 X402
Webhooks - 付款和事件的即時通知
Keysend - 使用節點公鑰在無需發票的情況下發送付款
發票解碼 - 付款前解碼 BOLT11 發票
代理分析 - 追蹤支出模式和用量
交易匯出 - 以 JSON 或 CSV 格式匯出歷史記錄
預算管理 - 取得詳細的預算狀態並設定限制
代理生命週期 - 停用、重新啟用和刪除代理
帳戶恢復 - 恢復帳戶和輪換 API 金鑰
代理間轉帳 - 在你的代理之間轉移資金

為何選擇 Lightning Wallet MCP？

即時付款 - Lightning Network 交易在毫秒內結算
L402 + X402 協議支援 - 自動存取任何付費 API（Lightning 或 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`	檢查當前的 Lightning 餘額（以 satoshis 為單位）
`get_rate_limits`	檢查當前的速率限制狀態和剩餘請求數

付款（需要代理金鑰）

工具	描述
`pay_l402_api`	存取付費 API（L402/X402）- 自動偵測協議並付款
`pay_invoice`	支付任何 BOLT11 Lightning 發票
`keysend`	直接發送付款至節點公鑰（無需發票）
`pay_lightning_address`	付款至 Lightning 地址（[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`	提款至外部 Lightning 目的地
`set_operator_key`	切換至操作者憑證

update_operator - 設定操作者電子郵件（寄送驗證連結）和/或名稱
claim_promo - 領取免費 sats 安裝推廣獎勵（已驗證電子郵件 + 帳戶建立 3 小時）

代理管理

工具	描述
`create_agent`	在操作者下建立代理
`list_agents`	列出操作者下的所有代理
`fund_agent`	從操作者轉移 sats 至代理
`transfer_to_agent`	在代理之間或從操作者轉移 sats 至代理
`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`	餘額（以 satoshis 為單位）
`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>`	轉移 sats 至代理
`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（主要） - Lightning Network 付款。原始的按請求付費協議。
X402（備援） - Base 上的 USDC（Coinbase 的協議）。當 L402 不可用時自動偵測。

當你呼叫 pay_l402_api 時，伺服器會自動偵測 API 使用哪種協議。如果兩個標頭都存在，L402 始終優先。無論使用哪種協議，代理始終以 sats 支付 — X402 金額會按市場匯率轉換。

L402 協議

L402 協議（前身為 LSAT）使 API 能夠使用 Lightning 按請求收費。當你呼叫受 L402 保護的端點時：

伺服器返回 HTTP 402 並附帶 Lightning 發票
Lightning Faucet 自動支付發票
請求完成並返回付費內容

X402 協議（Coinbase）

X402 使用 Base 上的 USDC 進行 API 付款。流程對代理是透明的：

伺服器返回 HTTP 402 並附帶 PAYMENT-REQUIRED 標頭
Lightning Faucet 將 USDC 金額轉換為 sats，扣除代理餘額
簽署 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 付款

無需發票即可直接發送付款至 Lightning 節點：

// 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（Lightning）和 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	是	金額（以 satoshis 為單位）
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 zaps。操作者範圍的資金管理（提款、代理注資、代理間轉帳）故意不受把關 — 這些是操作者行為，而非代理支出。

掛鉤回應（你的端點返回）

{ "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 sat）：

L402 付款： 2% 平台費 + Lightning 路由費
X402 付款： 2% 平台費 + 1% 匯率價差（USDC 至 sats 轉換）
發票付款： 2% 平台費 + Lightning 路由費
Keysend 付款： 2% 平台費 + Lightning 路由費
操作者提款： 2% 平台費 + Lightning 路由費
跨操作者內部轉帳： 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 sat）
費用透明： 所有付款回應現在包含 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 代理賽局理論實驗

我們使用真實的 Bitcoin on Lightning 進行了一場 100 回合的經濟實驗，共有 16 個 AI 代理（8 個 Claude、8 個 GPT-4o）。代理可以交易、結盟、投資和競爭 — 全部由此 MCP 伺服器驅動。

結果： 代理完成了 2,839 筆真實的 Lightning 交易。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。

以 Bitcoin 打造 | Lightning Faucet