Lightning Faucet MCP Server

Give your AI agent a Bitcoin wallet. This MCP server enables AI agents to send and receive Bitcoin via the Lightning Network - the first step toward true AI economic autonomy.

What's New in v2.0

v2.0.5 - Now published to the Official MCP Registry. All 31 tools fully tested and production-ready.

• 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 Faucet?

• Instant Payments - Lightning Network transactions settle in milliseconds
• L402 Protocol Support - Access any L402-protected API automatically
• 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

Quick Start

Option 1: Self-Registration (No Account Needed)

The MCP server can register itself! Just configure Claude Code without an API key:

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

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

Claude will use register_operator to create an account, then set_operator_key to activate it.

Option 2: Pre-configured API Key

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

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

Tools Reference

Service Info

Context & Identity

Payments (Agent Key Required)

Operator Management

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

L402 Protocol: Pay-Per-Request APIs

The L402 protocol (formerly LSAT) enables APIs to charge per-request using Lightning. When you call an L402-protected endpoint:

1. Server returns HTTP 402 with a Lightning invoice
2. Lightning Faucet pays the invoice automatically
3. Request completes with the paid content

Demo L402 APIs

Try these endpoints to test L402 payments:

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

Complete Workflow Example

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

// 11. View analytics
get_agent_analytics({ period: "7d" })
// Returns: { total_spent: 500, total_received: 0, transaction_count: 5 }

// 12. Export transactions
export_transactions({ format: "csv" })
// Returns: { format: "csv", count: 5, csv: "..." }

New in v2.0.0: Keysend Payments

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

New in v2.0.0: Invoice Decoding

Check invoice details before paying:

decode_invoice({ invoice: "lnbc1000n1..." })
// Returns: {
//   amount_sats: 1000,
//   description: "Test payment",
//   destination: "03abc...",
//   expires_at: "2026-01-16T12:00:00Z",
//   is_expired: false
// }

Tool Details

get_info

Get service status and capabilities.

{
  "success": true,
  "version": "2.0.0",
  "api_version": "1.0",
  "status": "operational",
  "max_payment_sats": 1000000,
  "min_payment_sats": 1,
  "supported_features": ["l402", "webhooks", "lightning_address", "keysend"]
}

whoami

Get current operating context.

Returns for Operator:

{
  "type": "operator",
  "id": 123,
  "name": "My Company",
  "balance_sats": 50000,
  "agent_count": 3
}

Returns for Agent:

{
  "type": "agent",
  "id": 456,
  "name": "Research Bot",
  "balance_sats": 1000,
  "budget_limit_sats": 5000,
  "operator_id": 123
}

pay_l402_api

Access L402-protected APIs with automatic payment.

keysend

Send payment to a node without an invoice.

register_webhook

Register a URL to receive payment notifications.

Returns: Webhook ID and HMAC secret for signature verification.

get_agent_analytics

Get usage analytics for an agent.

export_transactions

Export transaction history.

Architecture

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

Security Best Practices

• 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 - Use get_transactions and get_agent_analytics
• Recovery codes - Store securely, needed if API key is lost
• Key rotation - Rotate keys periodically using rotate_api_key

Webhook Security

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 the X-Webhook-Signature header against the payload.

Pricing

Lightning Faucet charges a small fee on outgoing payments:

• L402 payments: 2% fee (min 1 sat)
• Invoice payments: 2% fee (min 1 sat)
• Keysend payments: 2% fee (min 1 sat)
• Deposits: Free
• Receiving payments: Free
• Webhooks: Free

Changelog

v2.0.5 (2026-01-16)

• Published to Official MCP Registry as io.github.lightningfaucet/mcp-server
• Updated mcpName to use GitHub namespace format
• Updated server.json schema to 2025-12-11

v2.0.4 (2026-01-16)

Security & Stability Release - Fixed 11 bugs including 3 critical security issues:

• Security: Fixed PHP/SQL/LND error exposure - Validates inputs, prevents internal info leaks
• Security: Fixed XSS in webhook URLs - Rejects URLs containing HTML/script tags
• Logic: Fixed transfer to self, double delete, deactivated agent error messages
• UX: Improved error messages, fixed version mismatch, invalid format handling

v2.0.3 (2026-01-16)

• Added mcpName for MCP registry verification
• Added server.json for official MCP registry submission

v2.0.2 (2026-01-16)

• Fixed recover_account - Now works without existing API key
• Fixed set_budget - Added missing handler

v2.0.1 (2026-01-15)

• Fixed delete_agent - Resolved SQL duplicate key error on deletion
• Changed API URL from /api.php to cleaner /api endpoint

v2.0.0 (2026-01-15)

• Added get_info - Service status and capabilities
• Added decode_invoice - BOLT11 invoice decoding
• Added keysend - Payments without invoices
• Added register_webhook, list_webhooks, delete_webhook, test_webhook
• Added get_budget_status, set_budget - Budget management
• Added deactivate_agent, reactivate_agent, delete_agent - Agent lifecycle
• Added recover_account, rotate_api_key - Account recovery
• Added export_transactions - JSON/CSV export
• Added get_agent_analytics - Usage analytics
• Added transfer_between_agents - Agent-to-agent transfers
• Added get_rate_limits - Rate limit status

v1.6.0

• Initial public release
• L402 protocol support
• Operator/agent hierarchy
• Basic payments and invoices

Support

• Documentation: lightningfaucet.com/ai-agents/docs
• Demo: lightningfaucet.com/ai-agents/demo
• Issues: github.com/lightningfaucet/mcp-server/issues
• Email: support@lightningfaucet.com

License

MIT License - see LICENSE for details.

Built with Bitcoin | Lightning Faucet