lightning-faucet-mcp

v2.0.7

Published

8 days ago

MCP server for Lightning Faucet AI Agent Wallet - enables AI agents to send and receive Bitcoin via Lightning Network

Downloads

1,600

0High
0Medium
0Low

lightning-faucet

mcp lightning bitcoin ai-agent l402 payments

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

Get an API key at lightningfaucet.com/ai-agents
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

| 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 L402-protected APIs - automatically pays Lightning invoice | | pay_invoice | Pay any BOLT11 Lightning invoice | | keysend | Send payment directly to a node pubkey (no invoice needed) | | create_invoice | Generate invoice to receive payments | | get_invoice_status | Check if an invoice has been paid | | get_transactions | View transaction history | | export_transactions | Export transactions in JSON or CSV format |

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 |

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 funds to an agent | | transfer_between_agents | Transfer funds between two agents | | withdraw_from_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 | | get_agent_analytics | Get agent usage analytics (24h, 7d, 30d, all) | | 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

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:

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

L402 API Registry

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

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

See the L402 API Registry for more endpoints and resources.

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.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | url | string | Yes | The URL to request | | method | string | No | HTTP method (GET, POST, PUT, DELETE). Default: GET | | body | string | No | Request body for POST/PUT | | max_payment_sats | number | No | Maximum payment amount. Default: 1000 |

keysend

Send payment to a node without an invoice.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | destination | string | Yes | Target node public key (66 hex chars) | | amount_sats | number | Yes | Amount in satoshis | | message | string | No | Optional message (max 1000 chars) |

register_webhook

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | url | string | Yes | HTTPS URL to receive webhooks | | events | array | No | Event types to subscribe to. Default: ["invoice_paid"] |

Returns: Webhook ID and HMAC secret for signature verification.

get_agent_analytics

Get usage analytics for an agent.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | period | string | No | Time period: "24h", "7d", "30d", or "all". Default: "30d" |

export_transactions

Export transaction history.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | format | string | No | Export format: "json" or "csv". Default: "json" | | start_date | string | No | Start date filter (ISO 8601) | | end_date | string | No | End date filter (ISO 8601) |

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: [email protected]

License

MIT License - see LICENSE for details.

Built with Bitcoin | Lightning Faucet