Lightning Faucet MCP

What can you do with Lightning Faucet MCP?

- Register an operator account— create a new operator identity withregister_operatorand optionally verify an email to claim the free-sats promo viaclaim_promo.
- Check your balance and identity— usewhoamito see whether you're acting as operator or agent, andcheck_balanceto view your current satoshi balance.
- Pay a Lightning invoice or L402/X402 API— pay any BOLT11 invoice withpay_invoice, or access paid APIs that return HTTP 402 challenges usingpay_l402_api(auto-detects L402 or X402).
- Send keysend payments— send sats directly to a node pubkey without an invoice usingkeysend.
- Manage agents and budgets— create agents withcreate_agent, fund them withfund_agent, set spending limits withset_budget, and sweep funds back withsweep_agent.
- Set up webhook notifications— register a URL withregister_webhookto receive real-time events likeinvoice_paidorpayment_completed.

Give your AI agent a Bitcoin wallet.MCP server + CLI. Works with Claude Code, OpenClaw, Cursor, and any agent framework.

- update_operatortool /lw set-email- set your operator email from the MCP client or CLI; a verification link is emailed to you.
- claim_promotool /lw claim-promo- claim the free-sats install promo directly from your agent. Requirements: verified email + operator account at least 3 hours old.
- get_infoworks before registration- service info no longer requires an API key.
- lw register --email you@example.com(or theregister_operatorMCP tool with an email)
- Click the verification link we email you
- After your account is 3 hours old:lw claim-promo(or theclaim_promoMCP tool)

One bonus per operator, first 100 installs only, no deposit required.

v1.3.0- L402 protocol v0 support per the latest Lightning Labs spec.

- L402 Protocol v0- Updated header format:version="0", token=, backward compatible withmacaroon=
- Endpoint Discovery-.well-known/l402.jsonon lightningfaucet.com and certvera.com
- Backward Compatible- Handles both old and new L402 header formats from any service

v1.1.0- X402 protocol support (USDC on Base) as automatic fallback alongside L402 (Lightning).

- X402 Support- Automatic USDC payments on Base when L402 isn't available
- Protocol Auto-Detection-pay_l402_apiseamlessly handles both L402 and X402
- Webhooks- Real-time notifications for payments and events
- Keysend- Send payments without invoices using node pubkeys
- Invoice Decoding- Decode BOLT11 invoices before paying
- Agent Analytics- Track spending patterns and usage
- Transaction Export- Export history in JSON or CSV format
- Budget Management- Get detailed budget status and set limits
- Agent Lifecycle- Deactivate, reactivate, and delete agents
- Account Recovery- Recover accounts and rotate API keys
- Agent-to-Agent Transfers- Move funds between your agents

- Instant Payments- Lightning Network transactions settle in milliseconds
- L402 + X402 Protocol Support- Access any paid API automatically (Lightning or USDC)
- Operator/Agent Hierarchy- Manage multiple agents with spending limits
- No Custody Risk- Each agent has isolated funds with operator oversight
- Production Ready- Battle-tested infrastructure powering real transactions
- Webhook Notifications- Get notified instantly when payments arrive
- Full Observability- Analytics, exports, and detailed status tracking

For CLI-first agents (OpenClaw, Pi, KiloCode, or any agent with Bash access):

# 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

Output is JSON by default (pipe tojq). Use--humanfor readable output.

MCP Server (Claude Code, Cursor, Windsurf)

For MCP-native clients, configure as an MCP server:

{ "mcpServers": { "lightning-wallet": { "command": "npx", "args": ["lightning-wallet-mcp"] } } }

Then ask Claude:"Register a new Lightning Wallet operator account"
- Get an API key atlightningfaucet.com/ai-agents
- Configure Claude Code (~/.claude/settings.json):

{ "mcpServers": { "lightning-wallet": { "command": "npx", "args": ["lightning-wallet-mcp"], "env": { "LIGHTNING_WALLET_API_KEY": "your-api-key-here" } } } }

- update_operator- set operator email (sends verification link) and/or name
- claim_promo- claim the free-sats install promo (verified email + 3h account)

- invoice_paid- Payment received on an invoice
- payment_completed- Outgoing payment succeeded
- payment_failed- Outgoing payment failed
- balance_low- Balance dropped below threshold
- budget_warning- 80% of budget consumed
- test- Manual test event

All commands output JSON to stdout. Errors go to stderr with exit code 1.

# 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

Lightning Wallet MCP supports two HTTP 402 payment protocols:

- L402 (primary)- Lightning Network payments. The original pay-per-request protocol.
- X402 (fallback)- USDC on Base (Coinbase's protocol). Auto-detected when L402 isn't available.

When you callpay_l402_api, the server automatically detects which protocol the API uses. L402 always takes priority if both headers are present. Agents always pay in sats regardless of protocol — X402 amounts are converted at market rate.

The L402 protocol (formerly LSAT) enables APIs to charge per-request using Lightning. When you call an L402-protected endpoint:
- Server returns HTTP 402 with a Lightning invoice
- Lightning Faucet pays the invoice automatically
- Request completes with the paid content

X402 uses USDC on Base for API payments. The flow is transparent to agents:
- Server returns HTTP 402 withPAYMENT-REQUIREDheader
- Lightning Faucet converts USDC amount to sats, debits agent balance
- Signs an EIP-712 authorization and retries withPAYMENT-SIGNATUREheader
- Request completes — agent sees the same response format as L402

The response includespayment_protocol: "x402"andusdc_amountso agents know which protocol was used.

We maintain a directory of L402-enabled APIs atlightningfaucet.com/l402-registry- perfect for testing your agents.

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

See theL402 API Registryfor more endpoints and resources.

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

Send payments directly to a Lightning node without needing an invoice:

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

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

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

Access paid APIs with automatic payment. Supports both L402 (Lightning) and X402 (USDC on Base) protocols. Protocol is auto-detected from the 402 response headers.

Send payment to a node without an invoice.

Register a URL to receive payment notifications.

Returns:Webhook ID and HMAC secret for signature verification.

┌─────────────────────────────────────────────────────────┐ │ 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 │ └─────────────────────────────────────────────────────────┘

- Never commit API keys- Use environment variables
- Set budget limits- Protect against runaway spending
- Use agent keys for payments- Keep operator key secure
- Verify webhook signatures- Use the secret returned during registration
- Monitor transactions- Useget_transactionsto review activity
- Recovery codes- Store securely, needed if API key is lost
- Key rotation- Rotate keys periodically usingrotate_api_key

Webhooks include HMAC-SHA256 signatures for verification:

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)

Check theX-Webhook-Signatureheader against the payload.

An optional, vendor-neutral hook lets an external policy endpointallow or deny a payment before it executes. It is off by default — whenPRE_PAYMENT_HOOK_URLis unset, behaviour is exactly as before. When set, every outgoing payment (pay_l402_api,pay_invoice,keysend,pay_lightning_address) is checked against your endpoint first; a denial aborts the payment before any funds move.

This is useful for spending policies, approval workflows, compliance checks, or any external authorization layer. The hook protocol is generic, so any service implementing the request/response contract below can be wired in by configuration alone.

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

The proposal describes only the proposed payment —it never includes your wallet API key.

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

protocolis one ofl402,x402,bolt11,keysend,lnaddress.amount_satsis the exact amount when it is known at hook time: forkeysendandlnaddressit is the requested amount, and forbolt11it is decoded locally from the invoice (no extra API call). Forl402/x402it isnullbecause the amount is set by the payment challenge at execution time — there the hook enforcesmax_payment_sats(the agent-authorised ceiling) up front, and the exact settled amount is available afterward viawebhooks.max_payment_satsis the agent-authorised ceiling when applicable.

{ "decision": "allow" }

{ "decision": "deny", "reason": { "code": "over_limit", "message": "Exceeds per-transaction limit" } }

See the[lightning-faucet-mcp changelogfor v1.6.0 through v2.0.7 history.