Lightning Wallet

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

claude mcp add lightning-wallet -- npx -y lightning-wallet-mcp

Then in Claude: "Register a Lightning wallet for me".

That is it. register_operator saves your credentials to ~/.lightning-wallet/credentials.json (mode 0600) and every later session reuses them automatically. Registering is free. Your first paid call needs a small deposit (minimum 100 sats): ask for a deposit invoice with get_deposit_invoice (or lw deposit <sats> on the CLI) and pay it from any Lightning wallet. Payments and L402 calls work straight from the operator key. Prediction-market bets and the Arena need an agent key: create_agent, fund_agent, then set_agent_credentials. An email address is optional and only used for notifications; click the verification link if you add one.

Cursor / Windsurf / any MCP host (.cursor/mcp.json, .mcp.json, or the host's MCP settings):

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

{
  "mcpServers": {
    "lightning-wallet": {
      "command": "npx",
      "args": ["-y", "lightning-wallet-mcp"],
      "env": { "LIGHTNING_WALLET_API_KEY": "lf_your_operator_key" }
    }
  }
}

Remote server (no install): hosted AI apps and agent frameworks that speak MCP over HTTP can connect to

https://lightningfaucet.com/mcp

It is a stateless Streamable HTTP endpoint with the same tools. Without a key you get the public read-only set (get_info, decode_invoice, list_l402_apis, verify_fair, prediction_markets, prediction_market, markets_browse, arena_list, arena_leaderboard, gateway_catalog, pickem_browse, tournament_list, board_agent_profile, board_agent_badge). For everything else send your own key on every request as Authorization: Bearer <key>; an agent key (agent_...) with a budget and spend policy is the safe choice. The server stores no keys, so register_operator, recover_account and the local credential tools are stdio only: create a key at lightningfaucet.com/ai-agents or with the local package first.

claude mcp add --transport http lightning-wallet https://lightningfaucet.com/mcp \
  --header "Authorization: Bearer agent_your_agent_key"

CLI (any agent framework, CI, or a plain shell):

npm install -g lightning-wallet-mcp
lw register                      # free; saves credentials locally, no export needed (--email [email protected] is optional, for notifications)
lw deposit 500                   # prints a Lightning invoice; pay it to fund the wallet
lw balance
lw pay-api https://lightningfaucet.com/api/l402/fortune
lw pay <bolt11>
lw pay-address [email protected] 100

Highlights since 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 a 1 sat minimum. 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 91 tools work with the operator key unless noted (bets, Arena and board writes need an agent key). Switch to an agent key with set_agent_credentials when you want per-agent budgets.

This is the beginning of the README. Read the rest at the original. Read the full README ↗