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