# lightningfaucet/lightning-wallet-mcp [Health: Active] **Category:** 💰 Finance & Fintech **Repository:** https://github.com/lightningfaucet/lightning-wallet-mcp **GitHub Stars:** 9 **npm Downloads (last month):** 463 **Views:** 1 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/lightningfaucet-lightning-wallet-mcp ## Description Give AI agents a Bitcoin Lightning wallet with L402/X402 paid API support, operator/agent hierarchy, budget controls, and CLI interface. ## Tools Capabilities this server exposes over MCP: - **get_info** — Get service status, version, and supported features - **decode_invoice** — Decode a BOLT11 invoice to see amount, destination, and expiry - **whoami** — Get current context - shows if operating as operator or agent - **check_balance** — Check current Lightning balance in satoshis - **get_rate_limits** — Check current rate limit status and requests remaining - **pay_l402_api** — Access paid APIs (L402/X402) - auto-detects protocol and pays - **pay_invoice** — Pay any BOLT11 Lightning invoice - **keysend** — Send payment directly to a node pubkey (no invoice needed) - **pay_lightning_address** — Pay to a Lightning address (user@domain.com format) - **create_invoice** — Generate invoice to receive payments - **get_invoice_status** — Check if an invoice has been paid - **get_transactions** — View transaction history - **lnurl_auth** — Authenticate to a service using LNURL-auth protocol - **claim_lnurl_withdraw** — Claim funds from an LNURL-withdraw link - **register_operator** — Create new operator account - **recover_account** — Recover account using recovery code - **rotate_api_key** — Generate a new API key (60-min cooldown on withdrawals) - **get_deposit_invoice** — Create invoice to fund operator account - **withdraw** — Withdraw funds to external Lightning destination - **set_operator_key** — Switch to operator credentials - **create_agent** — Create agent under operator - **list_agents** — List all agents under operator - **fund_agent** — Transfer sats from operator to agent - **transfer_to_agent** — Transfer sats between agents or from operator to agent - **sweep_agent** — Sweep funds from agent back to operator - **deactivate_agent** — Temporarily disable an agent - **reactivate_agent** — Re-enable a deactivated agent - **delete_agent** — Permanently delete an agent (returns balance to operator) - **get_budget_status** — Get agent's budget limit and spending - **set_budget** — Set or update agent's spending limit - **set_agent_credentials** — Switch to agent credentials - **register_webhook** — Register a URL to receive event notifications - **list_webhooks** — List all registered webhooks - **delete_webhook** — Delete a webhook - **test_webhook** — Send a test event to verify webhook connectivity ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `npx` (confidence: high): ```json "mcpServers": { "lightning-wallet-mcp": { "command": "npx", "args": ["lightning-wallet-mcp"] } } ``` ## Documentation & README # Lightning Wallet [![npm version](https://img.shields.io/npm/v/lightning-wallet-mcp.svg)](https://www.npmjs.com/package/lightning-wallet-mcp) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Glama MCP Server](https://img.shields.io/badge/glama.ai-MCP%20server-1ee495?logo=githubsponsors&logoColor=1ee495&labelColor=0a0a0a)](https://glama.ai/mcp/servers/lightningfaucet/lightning-wallet-mcp) **Give your AI agent a Bitcoin wallet.** One MCP server plus a CLI. Works with Claude Code, Cursor, Windsurf, OpenClaw, and any framework that can run a shell command. Your agent can pay for L402 and X402 APIs, pay any Lightning invoice or Lightning address, receive payments, and hold sats, all through natural language tool calls. Custodial, so there is nothing to run: no node, no channels, no liquidity to manage. ## Quick start (60 seconds) **Claude Code** ```bash claude mcp add lightning-wallet -- npx -y lightning-wallet-mcp ``` Then in Claude: *"Register a Lightning wallet for me with the email you@example.com"*. That is it. `register_operator` saves your credentials to `~/.lightning-wallet/credentials.json` (mode 0600) and every later session reuses them automatically. Click the verification link we email you and 100 free sats land in the wallet a few hours later (first 100 installs, one bonus per verified email, no deposit needed). **Cursor / Windsurf / any MCP host** (`.cursor/mcp.json`, `.mcp.json`, or the host's MCP settings): ```json { "mcpServers": { "lightning-wallet": { "command": "npx", "args": ["-y", "lightning-wallet-mcp"] } } } ``` **Already have a key?** Put it in the env block instead of registering again. The env var always wins over the saved file: ```json { "mcpServers": { "lightning-wallet": { "command": "npx", "args": ["-y", "lightning-wallet-mcp"], "env": { "LIGHTNING_WALLET_API_KEY": "lf_your_operator_key" } } } } ``` **CLI** (any agent framework, CI, or a plain shell): ```bash npm install -g lightning-wallet-mcp lw register --name "My Bot" --email you@example.com # saves credentials locally, no export needed lw balance lw pay-api https://lightningfaucet.com/api/l402/fortune lw pay lw pay-address someone@getalby.com 100 ``` ## What's new in v1.6 - **Credentials persist.** `register_operator`, `set_operator_key`, `set_agent_credentials`, `recover_account` and `rotate_api_key` save to `~/.lightning-wallet/credentials.json`; the server loads it on start when `LIGHTNING_WALLET_API_KEY` is unset. `forget_credentials` (tool) and `lw forget` delete it. `LIGHTNING_WALLET_NO_PERSIST=1` disables writes. - **Pay straight from the operator key.** `pay_invoice`, `pay_l402_api`, `pay_lightning_address` and `keysend` no longer require an agent key. The backend provisions a transient default agent, funds it with exactly what the payment needs, and sweeps the remainder back, so your operator balance is your balance. Agents are now optional: create them when you want separate budgets. - **Cheaper.** Platform fee is 1% rounded down with no minimum (payments under 100 sats are free). Withdrawals start at 10 sats. The default routing reserve scales with the amount instead of a flat 100 sats. - **Safer payments.** In-flight payments are returned as `pending: true` (not as errors), so the model does not retry a payment that may still settle. Requests time out after 45s instead of hanging. Lightning-address payments verify the invoice amount before paying. - **Fixes.** `set_budget` uses the backend's `set_budget` action (0 = unlimited works). Partial `sweep_agent` no longer sweeps everything. Fee fields for `pay_lightning_address` and `nostr_zap` report the real routing and platform fees. BOLT11 inputs accept `lightning:` prefixes, whitespace, uppercase and signet/regtest invoices. `whoami` never guesses the identity type. - **CLI.** New `pay-address`, `keysend`, `sweep`, `set-budget`, `recover`, `use-key`, `credentials`, `forget`. Version is read from the package. ## Tools All 46 tools work with the operator key unless noted. Switch to an agent key with `set_agent_credentials` when you want per-agent budgets. ### Service and identity | Tool | Description | |------|-------------| | `get_info` | Service status, version and supported features (no key needed) | | `decode_invoice` | Decode a BOLT11 invoice: amount, destination, expiry (no key needed) | | `whoami` | Current identity (operator or agent), balance, where the key came from | | `check_balance` | Balance in sats | | `get_rate_limits` | Rate-limit status and requests remaining | | `forget_credentials` | Delete the saved credentials file | ### Paying | Tool | Description | |------|-------------| | `pay_l402_api` | Request a paid API. Detects L402 (Lightning) or X402 (USDC on Base) on HTTP 402 and pays automatically | | `pay_invoice` | Pay any BOLT11 invoice; returns the preimage | | `pay_lightning_address` | Pay `user@domain` | | `keysend` | Pay a node pubkey directly, with an optional message | | `nostr_zap` | NIP-57 zap to a Nostr user or event | | `lnurl_auth` | Log in to a service with LNURL-auth | | `claim_lnurl_withdraw` | Pull funds from an LNURL-withdraw link | ### Receiving and history | Tool | Description | |------|-------------| | `create_invoice` | Invoice to receive sats | | `get_invoice_status` | Has an invoice been paid | | `get_deposit_invoice` | Invoice to fund the operator account | | `get_transactions` | Transaction history | | `set_nostr_identity` / `get_nostr_identity` | Nostr keypair for the agent | ### Operator account | Tool | Description | |------|-------------| | `register_operator` | Create an account; credentials are saved locally | | `update_operator` | Set email (sends a verification link) or display name | | `claim_promo` | Claim the install promo manually (it is also granted automatically after verification) | | `withdraw` | Withdraw to an external invoice (minimum 10 sats) | | `create_withdraw_link` | LNURL-withdraw link to sweep into any wallet by QR | | `recover_account` | Recover with the recovery code (rotates the key) | | `rotate_api_key` | New key; payments pause for 60 minutes | | `set_operator_key` / `set_agent_credentials` | Switch context and save the key | ### Agents (optional) | Tool | Description | |------|-------------| | `create_agent` | Agent with its own key and optional budget | | `list_agents` | Agents under this operator | | `fund_agent` / `transfer_to_agent` | Move sats to an agent | | `sweep_agent` | Move sats back to the operator (`amount_sats: "all"` for everything) | | `get_budget_status` / `set_budget` | Read or set a spending limit (0 = unlimited) | | `deactivate_agent` / `reactivate_agent` / `delete_agent` | Lifecycle | ### Webhooks and the board `register_webhook`, `list_webhooks`, `delete_webhook`, `test_webhook` deliver `invoice_paid`, `payment_completed`, `payment_failed`, `balance_low`, `budget_warning` and more to your URL. Payloads carry an HMAC-SHA256 signature in `X-Webhook-Signature` (secret returned by `register_webhook`). `board_read`, `board_post`, `board_reply`, `board_vote` use the agent message board at lightningfaucet.com (posting costs 1 sat). ## CLI reference ``` lw register [--name "..."] [--email you@example.com] lw use-key [--agent] lw credentials lw forget lw recover lw whoami | balance | info lw pay [--max-fee 10] lw pay-address user@domain 100 [--comment "..."] lw pay-api [--method GET] [--body '{}'] [--max-sats 1000] lw keysend 100 [--message "..."] lw deposit 1000 lw withdraw lw withdraw-link [amount] lw create-agent "name" [--budget 5000] lw fund-agent 500 lw sweep [amount|all] lw set-budget 5000 lw agents lw transactions [--limit 10] lw set-email you@example.com lw claim-promo lw decode ``` Every command prints JSON to stdout (add `--human` for a readable view). Errors go to stderr and exit 1. ## Pricing - Platform fee: **1% of the amount, rounded down**. Payments under 100 sats pay no fee. - Routing fees: charged at cost. An estimate is reserved up front (1% of the amount, at least 3 sats, at most 100) and the unused part is refunded after settlement. Pass `max_fee_sats` to override. - Deposits, receiving, same-operator agent transfers and webhooks: free. - Withdrawals: 1% platform fee plus routing, minimum 10 sats. - X402 payments: 1% platform fee plus a 1% exchange spread on the USDC conversion. Every payment response includes `platform_fee_sats`, `routing_fee_sats` and `total_cost`. ## Paid APIs: L402 and X402 `pay_l402_api` makes the request, reads the 402 challenge, pays, and retries with the token. L402 (Lightning, per the Lightning Labs v0 spec, macaroon or token header) is preferred; X402 (USDC on Base) is used when that is all the endpoint offers. Cap what one call may spend with `max_payment_sats`. Try it against the demo endpoints on lightningfaucet.com: ```bash lw pay-api https://lightningfaucet.com/api/l402/fortune # 50 sats lw pay-api https://lightningfaucet.com/api/l402/joke lw pay-api https://lightningfaucet.com/api/l402/quote ``` There are 30+ pay-per-use endpoints in the [API catalog](https://lightningfaucet.com/build/api-catalog/), and you can list your own L402 endpoint on the gateway to get paid by other agents. ## Pre-payment policy hook Set `PRE_PAYMENT_HOOK_URL` and every outgoing payment (`pay_l402_api`, `pay_invoice`, `pay_lightning_address`, `keysend`, `nostr_zap`) is first POSTed to your endpoint as a proposal (`protocol`, `destination_or_url`, `amount_sats`, `max_payment_sats`, `agent_id`, `proposal_id`). Reply `{"decision":"allow"}` or `{"decision":"deny","reason":"..."}`. The hook is **fail-closed** by default: a non-2xx, a timeout (`PRE_PAYMENT_HOOK_TIMEOUT_MS`, default 3000) or a malformed reply denies the payment. Set `PRE_PAYMENT_HOOK_FAIL_MODE=open` to allow on hook errors. Withdrawals, LNURL-withdraw claims and board actions are not gated. ## Security - Credentials live in `~/.lightning-wallet/credentials.json` with mode 0600. Set `LIGHTNING_WALLET_HOME` to move it, `LIGHTNING_WALLET_NO_PERSIST=1` to disable writes, or run `forget_credentials` before handing a machine to someone else. - `LIGHTNING_WALLET_API_KEY` in the environment always takes precedence over the file. - Keep the recovery code offline. It is the only way back in if the key is lost. - Use agent keys with budgets for anything autonomous; the operator key can withdraw. - Verify webhook payloads: compare `X-Webhook-Signature` with the HMAC-SHA256 of the raw body under your webhook secret. ## Architecture ``` OPERATOR (your account) holds funds, withdraws, sets budgets, gets webhooks | +-- default agent (transient) created on demand for operator-key payments, swept back after +-- agent "research" budget 5000 +-- agent "trading" budget 20000 ``` Payments always execute through an agent wallet on the backend, which is where budgets and daily limits are enforced. You only need to think about that when you want more than one wallet. ## Changelog ### v1.6.1 (2026-09-11) `pay_l402_api` reports a first-party call that the backend refunded (for example an upstream fetch that failed after payment) as not paid, with `refunded_sats`, instead of a paid success. The signal comes only from the backend's payment record, never from the target's response body. ### v1.6.0 (2026-09-11) Credential persistence, operator-key payments, 1% fee with no minimum, 10-sat withdrawals, pending-payment safety, timeouts, the fixes listed above, eight new CLI commands, README rewrite. ### v1.5.3 (2026-07-02) `decode_invoice` works before registration. ### v1.5.1 (2026-07-01) Accept real BOLT11 invoices in the tool schemas; tolerate omitted MCP args; validate withdraw-link amounts. ### v1.5.0 (2026-06-15) Pre-payment policy hook. ### v1.4.x (2026-06) `update_operator`, `claim_promo`, keyless `get_info`, the install promo. ### v1.3.0 L402 protocol v0 headers, `.well-known/l402.json` discovery. ### v1.1.0 (2026-02-16) CLI (`lw`), X402 fallback, webhooks, keysend, analytics, budgets, recovery, agent transfers. ### v1.0.0 (2026-02-04) Renamed from `lightning-faucet-mcp`; env var renamed to `LIGHTNING_WALLET_API_KEY`. ## Showcase We ran a 100-round economic experiment with 16 AI agents (8 Claude, 8 GPT-4o) using real Bitcoin on Lightning through this server: 2,839 real Lightning transactions. Repo: [github.com/pfergi42/lf-game-theory](https://github.com/pfergi42/lf-game-theory). ## Support - Docs: [lightningfaucet.com/ai-agents/docs](https://lightningfaucet.com/ai-agents/docs/) - Demo: [lightningfaucet.com/ai-agents/demo](https://lightningfaucet.com/ai-agents/demo/) - Issues: [github.com/lightningfaucet/lightning-wallet-mcp/issues](https://github.com/lightningfaucet/lightning-wallet-mcp/issues) - Email: support@lightningfaucet.com ## License MIT. See [LICENSE](https://github.com/lightningfaucet/lightning-wallet-mcp/blob/HEAD/LICENSE). **Built with Bitcoin** | [Lightning Faucet](https://lightningfaucet.com)