lightning-wallet-mcp

# 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.** 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):

```bash
npm install -g lightning-wallet-mcp
```

This installs the `lw` command:

```bash
# 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**

```json
{
  "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](https://lightningfaucet.com/ai-agents/)
2. Configure Claude Code (`~/.claude/settings.json`):

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

## Tools Reference

### Service Info

| Tool | Description |
|------|-------------|
| `get_info` | Get service status, version, and supported features |
| `decode_invoice` | Decode a BOLT11 invoice to see amount, destination, and expiry |

### Context & Identity

| Tool | Description |
|------|-------------|
| `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 |

### Payments (Agent Key Required)

| Tool | Description |
|------|-------------|
| `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 (Agent Key Required)

| Tool | Description |
|------|-------------|
| `lnurl_auth` | Authenticate to a service using LNURL-auth protocol |
| `claim_lnurl_withdraw` | Claim funds from an LNURL-withdraw link |

### Operator Management

| Tool | Description |
|------|-------------|
| `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 |

- `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

| Tool | Description |
|------|-------------|
| `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 |

### Webhooks

| Tool | Description |
|------|-------------|
| `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 |

**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.

| Command | Description |
|---------|-------------|
| `lw register [--name "name"]` | Create operator account, prints API key |
| `lw whoami` | Current identity (operator or agent) |
| `lw balance` | Balance in satoshis |
| `lw info` | Service status and capabilities |
| `lw deposit <amount>` | Generate deposit invoice |
| `lw withdraw <invoice>` | Withdraw to external wallet |
| `lw pay <invoice>` | Pay BOLT11 invoice `[--max-fee <sats>]` |
| `lw pay-api <url>` | Pay L402/X402 API `[--method GET] [--body "{}"] [--max-sats 1000]` |
| `lw decode <invoice>` | Decode BOLT11 invoice |
| `lw create-agent <name>` | Create agent `[--budget <sats>]` |
| `lw fund-agent <id> <amount>` | Transfer sats to agent |
| `lw list-agents` | List all agents |
| `lw transactions` | Recent transactions `[--limit 10] [--offset 0]` |
| `lw help` | Show all commands |

### Agent Workflow Example (Bash)

```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.

When you call `pay_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 conve