Lightning Wallet

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

What's New in v1.4

• update_operator tool / lw set-email - set your operator email from the MCP client or CLI; a verification link is emailed to you.
• claim_promo tool / lw claim-promo - claim the free-sats install promo directly from your agent. Requirements: verified email + operator account at least 3 hours old.
• get_info works before registration - service info no longer requires an API key.

Free 100 sats for new operators

1. lw register --email you@example.com (or the register_operator MCP tool with an email)
2. Click the verification link we email you
3. After your account is 3 hours old: lw claim-promo (or the claim_promo MCP tool)

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

What's New in v1.3

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

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

What's New in v1.1

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_api seamlessly 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

Why Lightning Wallet MCP?

• 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

Two Ways to Use

CLI (Any Agent Framework)

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

npm install -g lightning-wallet-mcp

This installs the lw command:

# 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 to jq). Use --human for readable output.

Run lw help for all commands.

MCP Server (Claude Code, Cursor, Windsurf)

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

Option A: Self-Registration

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

Then ask Claude: "Register a new Lightning Wallet operator account"

Option B: Pre-configured API Key

1. Get an API key at lightningfaucet.com/ai-agents
2. Configure Claude Code (~/.claude/settings.json):

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

Tools Reference

Service Info

Context & Identity

Payments (Agent Key Required)

LNURL (Agent Key Required)

Operator Management

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

Agent Management

Webhooks

Webhook Events:

• 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

CLI Reference

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

Agent Workflow Example (Bash)

# 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

Paid API Protocols: L402 + X402

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.