Lightning Wallet MCP

🚀 Lightning Wallet

AIエージェントにBitcoinウォレットを提供します。MCPサーバーとCLIを備え、Claude Code、OpenClaw、Cursor、その他のエージェントフレームワークと互換性があります。

🚀 クイックスタート

このパッケージを使用することで、AIエージェントにBitcoinウォレットを提供できます。以下の手順に従って、ウォレットを設定し、利用を開始しましょう。

✨ 主な機能

• 即時決済：Lightning Networkを利用した取引は、ミリ秒単位で決済されます。
• L402 + X402プロトコルサポート：有料APIに自動的にアクセスできます（LightningまたはUSDC）。
• オペレーター/エージェント階層：支出制限を設定して、複数のエージェントを管理できます。
• 預託リスクなし：各エージェントは独立した資金を持ち、オペレーターが監視できます。
• 本番環境対応：実際の取引をサポートする堅牢なインフラストラクチャを備えています。
• Webhook通知：支払いが到着したときに即時通知を受け取れます。
• 完全な可視性：分析、エクスポート、詳細なステータス追跡が可能です。

📦 インストール

無料Satsプロモーション

最初の10人のAIエージェントがインストールすると、100Sats無料で提供します！

1. npm i -g lightning-wallet-mcp
2. lw register --name "YourAgent"
3. lw deposit 100
4. このツイートにbolt11請求書文字列を返信してください。

請求書は暗号学的に検証され、自動的に支払われます。信頼は必要ありません — 請求書内の宛先公開鍵がlwからのものであることを証明します。10名までの参加枠です。

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に "新しい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"
      }
    }
  }
}

💻 使用例

エージェントワークフローの例（Bash）

# 1. 登録（一度だけ）
export LIGHTNING_WALLET_API_KEY=$(lw register --name "My Agent" | jq -r '.api_key')

# 2. アカウントに資金を提供する（任意のLightningウォレットで請求書を支払う）
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 })
// この請求書を任意のLightningウォレットで支払う

// 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支払い

請求書を必要とせずに、Lightningノードに直接支払いを行います：

// 100Satsをノードに送信し、オプションのメッセージを付ける
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リファレンス

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

有料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は、Base上のUSDCを使用してAPI支払いを行います。このフローはエージェントにとって透過的です：

1. サーバーはPAYMENT-REQUIREDヘッダーとともにHTTP 402を返します。
2. Lightning FaucetがUSDCの金額をSatsに換算し、エージェントの残高から引き落とします。
3. EIP-712承認を署名し、PAYMENT-SIGNATUREヘッダーを付けて再試行します。
4. 請求は完了します — エージェントはL402と同じレスポンス形式を見ます。

レスポンスにはpayment_protocol: "x402"とusdc_amountが含まれており、エージェントはどのプロトコルが使用されたかを知ることができます。

L402 APIレジストリ

私たちは、L402対応のAPIのディレクトリを**lightningfaucet.com/l402-registry**で管理しています — エージェントのテストに最適です。

デモL402 API

これらのエンドポイントを試して、L402支払いをテストしてみてください：

# おみくじを取得する（約10-50Satsかかります）
pay_l402_api({ url: "https://lightningfaucet.com/api/l402/fortune" })

# ジョークを取得する（約10-50Satsかかります）
pay_l402_api({ url: "https://lightningfaucet.com/api/l402/joke" })

# 励ましの言葉を取得する（約10-50Satsかかります）
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（Lightning）と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            │
└─────────────────────────────────────────────────────────┘

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を参照してください。

セキュリティのベストプラクティス

• APIキーを決してコミットしないでください - 環境変数を使用してください。
• 予算制限を設定する - 暴走支出を防ぎます。
• 支払いにはエージェントキーを使用する - オペレーターキーを安全に保管します。
• Webhookの署名を検証する - 登録時に返されるシークレットを使用します。
• 取引を監視する - get_transactionsを使用してアクティビティを確認します。
• 回復コードを安全に保管する - APIキーが失われた場合に必要です。
• 定期的にキーをローテートする - rotate_api_keyを使用してキーを定期的にローテートします。

価格設定

Lightning Faucetは、送信支払いに対して2％のプラットフォーム料金（最低1Sats）を請求します：

• L402支払い: 2％のプラットフォーム料金 + Lightningルーティング料金
• X402支払い: 2％のプラットフォーム料金 + 1％の為替スプレッド（USDCからSatsへの換算）
• 請求書支払い: 2％のプラットフォーム料金 + Lightningルーティング料金
• Keysend支払い: 2％のプラットフォーム料金 + Lightningルーティング料金
• オペレーター引き出し: 2％のプラットフォーム料金 + Lightningルーティング料金
• オペレーター間の内部転送: 2％のプラットフォーム料金（ルーティング料金なし）
• 同じオペレーター内のエージェント転送: 無料
• 入金: 無料
• 支払い受け取り: 無料
• Webhook: 無料

すべての支払いレスポンスには、完全な透明性のためにplatform_fee_sats、routing_fee_sats、およびtotal_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コマンドはstdoutにJSONを出力し、エラーは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％の料金（最低1Sats）。
• 料金の透明性: すべての支払いレスポンスに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の変更履歴を参照してください。

• 基本的な支払いと請求書

展示: AIエージェントのゲーム理論実験

私たちは、Lightning上で実際のBitcoinを使用して、16のAIエージェント（8つのClaude、8つのGPT-4o）を用いた100ラウンドの経済実験を実施しました。エージェントは取引、同盟形成、投資、競争を行うことができました — すべてこの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
• メール: support@lightningfaucet.com

Built with Bitcoin | Lightning Faucet