Lightning Faucet MCP Server

公式

AIエージェントにLightning Network決済対応のBitcoinウォレットを提供します

ドキュメント

Lightning Wallet

npm version License: MIT Glama MCP Server

あなたのAIエージェントにBitcoinウォレットを。 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を無料プレゼント

  1. lw register --email [email protected] (または register_operator MCPツールをメールアドレスと共に使用)
  2. メールで届いた確認リンクをクリック
  3. アカウント作成から3時間経過後: lw claim-promo (または claim_promo MCPツール)

オペレーター1人につき1回限り、先着100インストール限定、デポジット不要。

v1.3の新機能

v1.3.0 - 最新のLightning Labs仕様に準拠したL402プロトコルv0サポート。

  • L402プロトコルv0 - ヘッダーフォーマットを更新: version="0", token=macaroon= との後方互換性あり
  • エンドポイント検出 - lightningfaucet.com および certvera.com で .well-known/l402.json
  • 後方互換性 - あらゆるサービスからの新旧L402ヘッダーフォーマットに対応

v1.1の新機能

v1.1.0 - L402 (Lightning) に加え、自動フォールバックとしてX402プロトコル (Base上のUSDC) をサポート。

  • X402サポート - L402が利用できない場合にBase上でUSDC支払いを自動実行
  • プロトコル自動検出 - pay_l402_api がL402とX402の両方をシームレスに処理
  • Webhook - 支払いやイベントのリアルタイム通知
  • Keysend - ノード公開鍵を使用してインボイスなしで支払い
  • インボイスデコード - 支払い前にBOLT11インボイスをデコード
  • エージェント分析 - 支出パターンと使用状況の追跡
  • トランザクションエクスポート - JSONまたはCSV形式で履歴をエクスポート
  • 予算管理 - 詳細な予算状況の取得と上限設定
  • エージェントライフサイクル - エージェントの無効化、再有効化、削除
  • アカウント復旧 - アカウントの復旧とAPIキーのローテーション
  • エージェント間転送 - 自分のエージェント間で資金を移動

Lightning Wallet MCPを選ぶ理由

  • 即時支払い - Lightning Networkトランザクションはミリ秒単位で決済
  • L402 + X402プロトコルサポート - 任意の有料APIに自動アクセス (LightningまたはUSDC)
  • オペレーター/エージェント階層 - 支出制限付きで複数のエージェントを管理
  • カストディリスクなし - 各エージェントはオペレーターの監視下で隔離された資金を持つ
  • 本番環境対応 - 実際のトランザクションを支える実戦テスト済みのインフラ
  • Webhook通知 - 支払い受信時に即座に通知
  • 完全な可観測性 - 分析、エクスポート、詳細なステータス追跡

2つの使用方法

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キー

  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"
      }
    }
  }
}

ツールリファレンス

サービス情報

ツール説明
get_infoサービスのステータス、バージョン、サポート機能を取得
decode_invoiceBOLT11インボイスをデコードし、金額、宛先、有効期限を表示

コンテキストとアイデンティティ

ツール説明
whoami現在のコンテキストを取得 - オペレーターまたはエージェントとして動作中かを表示
check_balance現在のLightning残高をsatoshi単位で確認
get_rate_limits現在のレート制限ステータスと残りリクエスト数を確認

支払い (エージェントキーが必要)

ツール説明
pay_l402_api有料APIにアクセス (L402/X402) - プロトコルを自動検出して支払い
pay_invoice任意のBOLT11 Lightningインボイスを支払い
keysendノード公開鍵に直接支払いを送信 (インボイス不要)
pay_lightning_addressLightningアドレス ([email protected]形式) に支払い
create_invoice支払いを受け取るためのインボイスを生成
get_invoice_statusインボイスが支払われたか確認
get_transactionsトランザクション履歴を表示

LNURL (エージェントキーが必要)

ツール説明
lnurl_authLNURL-authプロトコルを使用してサービスに認証
claim_lnurl_withdrawLNURL-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エージェント認証情報に切り替え

Webhook

ツール説明
register_webhookイベント通知を受信するURLを登録
list_webhooks登録済みの全Webhookを一覧表示
delete_webhookWebhookを削除
test_webhookテストイベントを送信してWebhookの接続性を確認

Webhookイベント:

  • invoice_paid - インボイスで支払いを受信
  • payment_completed - 送金が成功
  • payment_failed - 送金が失敗
  • balance_low - 残高がしきい値を下回った
  • budget_warning - 予算の80%を消費
  • test - 手動テストイベント

CLIリファレンス

すべてのコマンドはJSONをstdoutに出力します。エラーは終了コード1でstderrに出力されます。

コマンド説明
lw register [--name "name"]オペレーターアカウントを作成し、APIキーを表示
lw whoami現在のアイデンティティ (オペレーターまたはエージェント)
lw balancesatoshi単位の残高
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は2つのHTTP 402支払いプロトコルをサポートします:

  • L402 (プライマリ) - Lightning Network支払い。オリジナルのペイパーリクエストプロトコル。
  • X402 (フォールバック) - Base上のUSDC (Coinbaseのプロトコル)。L402が利用できない場合に自動検出。

pay_l402_api を呼び出すと、サーバーはAPIが使用するプロトコルを自動検出します。両方のヘッダーが存在する場合、L402が常に優先されます。エージェントはプロトコルに関係なく常にsatsで支払います — X402の金額は市場レートで換算されます。

L402プロトコル

L402プロトコル (旧LSAT) により、APIはLightningを使用してリクエストごとに課金できます。L402で保護されたエンドポイントを呼び出すと:

  1. サーバーがLightningインボイスと共にHTTP 402を返す
  2. Lightning Faucetが自動的にインボイスを支払う
  3. 有料コンテンツと共にリクエストが完了

X402プロトコル (Coinbase)

X402はAPI支払いにBase上のUSDCを使用します。フローはエージェントに対して透過的です:

  1. サーバーが PAYMENT-REQUIRED ヘッダーと共にHTTP 402を返す
  2. Lightning FaucetがUSDC金額をsatsに換算し、エージェント残高から引き落とし
  3. EIP-712認証に署名し、PAYMENT-SIGNATURE ヘッダーで再試行
  4. リクエスト完了 — エージェントには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レスポンスヘッダーから自動検出されます。

パラメータ必須説明
urlstringはいリクエストするURL
methodstringいいえHTTPメソッド (GET, POST, PUT, DELETE)。デフォルト: GET
bodystringいいえPOST/PUTのリクエストボディ
max_payment_satsnumberいいえ最大支払い額。デフォルト: 1000

keysend

インボイスなしでノードに支払いを送信。

パラメータ必須説明
destinationstringはいターゲットノードの公開鍵 (66桁の16進数)
amount_satsnumberはいsatoshi単位の金額
messagestringいいえオプションのメッセージ (最大1000文字)

register_webhook

支払い通知を受信するURLを登録。

パラメータ必須説明
urlstringはいWebhookを受信するHTTPS URL
eventsarrayいいえサブスクライブするイベントタイプ。デフォルト: ["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セキュリティ

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 ヘッダーを確認してください。

支払い前ポリシーフック

オプションのベンダーニュートラルなフックにより、外部ポリシーエンドポイントが支払い実行前に許可または拒否できます。デフォルトでは無効で、PRE_PAYMENT_HOOK_URL が未設定の場合の動作は従来通りです。設定されると、すべての送信支払い(pay_l402_apipay_invoicekeysendpay_lightning_address)が最初にエンドポイントでチェックされ、拒否された場合は資金移動前に支払いが中止されます。

これは、支出ポリシー、承認ワークフロー、コンプライアンスチェック、または任意の外部認可レイヤーに役立ちます。フックプロトコルは汎用的であるため、以下のリクエスト/レスポンス契約を実装する任意のサービスを設定のみで接続できます。

設定

環境変数デフォルト説明
PRE_PAYMENT_HOOK_URL(未設定)各支払い提案をPOSTするポリシーエンドポイント。未設定の場合、フックは完全に無効になります。
PRE_PAYMENT_HOOK_TIMEOUT_MS3000リクエストごとのタイムアウト(ミリ秒)。
PRE_PAYMENT_HOOK_FAIL_MODEclosedclosed はフックがエラーまたはタイムアウトした場合に支払いを拒否し、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"
}

protocoll402x402bolt11keysendlnaddress のいずれかです。amount_sats はフック時に金額が判明している場合の正確な金額です。keysendlnaddress の場合は要求された金額であり、bolt11 の場合はインボイスからローカルでデコードされます(追加のAPI呼び出しなし)。l402/x402 の場合は null です。これは金額が実行時の支払いチャレンジによって設定されるためで、ここではフックが事前に max_payment_sats(エージェントが承認した上限)を強制し、正確な決済額は後でWebhookを通じて利用可能になります。max_payment_sats は該当する場合のエージェント承認上限です。

ウォレットから送信される正確な内容。 上記の8つのフィールドのみがフックエンドポイントに送信されます:proposal_idagent_idprotocoldestination_or_urlamount_satsmax_payment_satsmethodts。ウォレットAPIキーやその他の認証情報は決して含まれません。

対象範囲。 フックはすべてのエージェント開始の支出をゲートします:pay_l402_apipay_invoicekeysendpay_lightning_address、およびNostr Zap。オペレータースコープの資金管理(引き出し、エージェント資金提供、エージェント間転送)は意図的にゲートされません。これらはエージェントの支出ではなく、オペレーターのアクションです。

フックレスポンス(エンドポイントが返すもの)

{ "decision": "allow" }
{ "decision": "deny", "reason": { "code": "over_limit", "message": "Exceeds per-transaction limit" } }
  • allow → 支払いが続行されます。
  • deny → 支払いが中止され、ツールは reason.message を表示する PolicyDenied エラーを返します。
  • オプションの 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%プラットフォーム手数料(ルーティング手数料なし)
  • 同一オペレーターエージェント転送: 無料
  • 入金: 無料
  • 支払い受取: 無料
  • Webhook: 無料

すべての支払いレスポンスには、完全な透明性のために platform_fee_satsrouting_fee_satstotal_cost が含まれます。

変更履歴

v1.1.0 (2026-02-16)

  • CLIインターフェース: CLIファーストエージェント(OpenClaw、Pi、KiloCode、任意のBashエージェント)向けの新しい lw コマンド
  • 同一パッケージ、2つのインターフェース: 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_protocolusdc_amount を含む
  • 為替レート: CoinGecko経由のリアルタイムBTC/USD変換(5分キャッシュ)

v1.0.3 (2026-02-05)

  • プラットフォーム手数料: すべての送信支払いとクロスオペレーター転送に2%手数料(最低1 sat)
  • 手数料の透明性: すべての支払いレスポンスに platform_fee_satsrouting_fee_satstotal_cost を含む
  • 同一オペレーターエージェント転送は引き続き無料

v1.0.0 (2026-02-04)

  • lightning-faucet-mcp から lightning-wallet-mcpリブランド
  • 環境変数名変更: LIGHTNING_FAUCET_API_KEYLIGHTNING_WALLET_API_KEY
  • 37ツールすべて完全テスト済みで本番対応
  • 破壊的API変更なし - パッケージ名のみ

以前のリリース(lightning-faucet-mcpとして)

v1.6.0からv2.0.7の履歴についてはlightning-faucet-mcp変更履歴を参照してください。

  • 基本的な支払いとインボイス

ショーケース: AIエージェントゲーム理論実験

実際のBitcoinをLightningで使用し、16のAIエージェント(Claude 8、GPT-4o 8)で100ラウンドの経済実験を実施しました。エージェントは取引、同盟形成、投資、競争が可能で、すべてこのMCPサーバーによって実現されました。

結果: エージェントは2,839件の実際のLightningトランザクションを完了しました。Claudeエージェントは積極的な早期取引で優位に立ち、GPT-4oエージェントは保守的な戦略を採用しました。

サポート

ライセンス

MITライセンス - 詳細はLICENSEを参照してください。


Built with Bitcoin | Lightning Faucet