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**
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):
**Already have a key?** Put it in the env block instead of registering again. The env var always wins over the saved file:
**CLI** (any agent framework, CI, or a plain shell):
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 |