Lightning Enable MCP - Complete Guide

The Lightning Enable MCP (Model Context Protocol) server enables AI agents to interact with the Lightning Network. It's free and open source with comprehensive Lightning wallet capabilities.

Open Source

The MCP server is fully open source: github.com/refined-element/lightning-enable-mcp. Available on NuGet, PyPI, and Docker.

Overview

┌──────────────────────────────────────────────────────────────────────────┐
│                         Lightning Enable MCP                             │
├──────────────────────────────────────────────────────────────────────────┤
│  AI Agent (Claude, etc.)                                                 │
│       ↓                                                                  │
│  MCP Server (wallet priority: LND > NWC > Strike > OpenNode)             │
│       ↓                                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐                 │
│  │   LND    │  │   NWC    │  │  Strike  │  │ OpenNode │                 │
│  │  Wallet  │  │  Wallet  │  │  Wallet  │  │  Wallet  │                 │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘                 │
│       ↓              ↓             ↓              ↓                      │
│  Lightning Network                                                       │
└──────────────────────────────────────────────────────────────────────────┘

Wallet Priority: When multiple wallets are configured, the MCP server selects them in order: LND > NWC > Strike > OpenNode. This order is optimized for L402 compatibility (LND and NWC always return preimages). Override with the WALLET_PRIORITY environment variable or the priority field in your config file.

Installation

.NET (Windows, Linux, macOS)

dotnet tool install -g LightningEnable.Mcp

Python (All Platforms)

pip install lightning-enable-mcp

Or use uvx for no-install execution:

uvx lightning-enable-mcp

Quick Start

Add to your Claude Desktop config:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "lightning-enable": {
      "command": "dotnet",
      "args": ["tool", "run", "lightning-enable-mcp"],
      "env": {
        "STRIKE_API_KEY": "your-strike-api-key"
      }
    }
  }
}

---

All Available Tools

Tool Availability by Wallet

Tool	Strike	OpenNode	LND	NWC (CoinOS/CLINK)	NWC (Alby)	NWC (Primal)
pay_invoice	✅	✅	✅	✅	✅	✅
check_wallet_balance	✅	✅	✅	✅	✅	✅
get_payment_history	✅	✅	✅	✅	✅	✅
get_budget_status	✅	✅	✅	✅	✅	✅
create_invoice	✅	✅	✅	✅*	✅*	✅*
check_invoice_status	✅	✅	✅	❌	❌	❌
get_all_balances	✅	✅	✅	✅	✅	✅
get_btc_price	✅	❌	❌	❌	❌	❌
exchange_currency	✅	❌	❌	❌	❌	❌
send_onchain	✅	❌	✅	❌	❌	❌
discover_api	✅	✅	✅	✅	✅	✅
access_l402_resource	✅	❌	✅	✅	✅	❌
pay_l402_challenge	✅	❌	✅	✅	✅	❌
create_l402_challenge	✅*	✅*	✅*	✅*	✅*	✅*
verify_l402_payment	✅*	✅*	✅*	✅*	✅*	✅*

*NWC invoice creation depends on wallet support create_l402_challenge and verify_l402_payment require LIGHTNING_ENABLE_API_KEY (Agentic Commerce subscription) — wallet type does not matter for these tools L402 requires preimage return: LND always works, Strike works, CoinOS/CLINK work, Alby works, OpenNode/Primal don't return preimage

---

Core Tools (All Wallets)

pay_invoice

Pay any Lightning invoice and get the preimage as proof of payment.

Parameters:

Parameter	Type	Required	Default	Description
invoice	string	Yes	-	BOLT11 Lightning invoice
maxSats	int	No	1000	Maximum payment allowed

Example:

User: Pay this invoice: lnbc500n1p3...

Claude: [Uses pay_invoice]

Payment successful!
- Amount: 500 sats
- Preimage: 7f8a9b2c3d4e5f...
- Provider: Strike

Response:

{
  "success": true,
  "provider": "Strike",
  "payment": {
    "preimage": "7f8a9b2c3d4e5f...",
    "amountSats": 500
  },
  "message": "Payment successful! Paid 500 sats."
}

---

check_wallet_balance

Check your connected wallet balance.

Parameters: None required

Example:

User: What's my wallet balance?

Claude: [Uses check_wallet_balance]

Wallet Balance: 50,000 sats (~$50 USD)
Provider: Strike

Response:

{
  "success": true,
  "provider": "Strike",
  "balance": {
    "sats": 50000,
    "btc": 0.0005
  },
  "message": "Balance: 50,000 sats"
}

---

get_payment_history

View recent Lightning payments made through the MCP.

Parameters:

Parameter	Type	Required	Default	Description
limit	int	No	10	Maximum payments to return

Example:

User: Show my recent payments

Claude: [Uses get_payment_history]

Recent Payments:
1. 500 sats - lnbc500n1... - 5 min ago
2. 100 sats - lnbc100n1... - 1 hour ago
3. 1000 sats - lnbc1u1... - 2 hours ago

Total: 1,600 sats across 3 payments

---

get_budget_status

View current budget configuration and session spending. This is read-only - budget limits can only be changed by editing the config file.

Parameters: None required

Example:

User: What are my spending limits?

Claude: [Uses get_budget_status]

Budget Configuration (READ-ONLY):
- Config file: ~/.lightning-enable/config.json
- Auto-approve: up to $0.10
- Log & approve: $0.10 - $1.00
- Requires click approval: $1.00 - $10.00
- Requires amount typing: $10.00 - $100.00
- Maximum per payment: $500.00
- Maximum per session: $100.00

Session:
- Spent: $0.45 (4,500 sats)
- Remaining: $99.55

Note: AI cannot modify budget limits. Edit config.json to change.

---

Invoice Tools (Strike, OpenNode)

create_invoice

Create a Lightning invoice to receive payments. Returns a BOLT11 string to share with the payer.

Parameters:

Parameter	Type	Required	Default	Description
amountSats	long	Yes	-	Amount to receive in satoshis
memo	string	No	null	Description for the invoice
expirySecs	int	No	3600	Invoice expiry (default 1 hour)

Example:

User: Create an invoice for 1000 sats for "Coffee payment"

Claude: [Uses create_invoice]

Invoice Created!
- Amount: 1,000 sats
- Memo: Coffee payment
- Expires: 1 hour
- Invoice ID: inv_abc123...

BOLT11 Invoice (share with payer):
lnbc10u1p3xyza...

Share this invoice with the payer, or display as a QR code.

Response:

{
  "success": true,
  "provider": "OpenNode",
  "invoice": {
    "id": "inv_abc123",
    "bolt11": "lnbc10u1p3xyza...",
    "amountSats": 1000,
    "expiresAt": "2024-01-15T14:30:00Z"
  },
  "message": "Invoice created for 1000 sats. Share the bolt11 string with the payer."
}

---

check_invoice_status

Check if a previously created invoice has been paid.

Parameters:

Parameter	Type	Required	Description
invoiceId	string	Yes	Invoice ID from create_invoice

Example:

User: Has the coffee invoice been paid?

Claude: [Uses check_invoice_status with invoiceId="inv_abc123"]

Invoice Status: PAID! ✅
- Amount: 1,000 sats
- Paid at: 2024-01-15 13:45:22 UTC

Response:

{
  "success": true,
  "provider": "OpenNode",
  "invoice": {
    "id": "inv_abc123",
    "state": "paid",
    "isPaid": true,
    "isPending": false,
    "amountSats": 1000,
    "paidAt": "2024-01-15T13:45:22Z"
  },
  "message": "Invoice inv_abc123 has been PAID!"
}

---

Strike-Only Tools

These tools are only available when using Strike as your wallet provider.

get_btc_price

Get the current Bitcoin price in USD.

Parameters: None required

Example:

User: What's the current Bitcoin price?

Claude: [Uses get_btc_price]

Current BTC Price: $97,500.00 USD
Source: Strike
Timestamp: 2024-01-15 13:30:00 UTC

Response:

{
  "success": true,
  "provider": "Strike",
  "ticker": {
    "btcUsd": 97500.00,
    "timestamp": "2024-01-15T13:30:00Z"
  },
  "message": "Current BTC price: $97,500.00 USD"
}

---

get_all_balances

Get all currency balances (USD and BTC) from your Strike wallet.

Parameters: None required

Example:

User: Show all my Strike balances

Claude: [Uses get_all_balances]

Strike Balances:
- USD: $127.45 (available)
- BTC: 0.00045000 BTC (45,000 sats, ~$45)

Total Value: ~$172.45 USD

Response:

{
  "success": true,
  "provider": "Strike",
  "balances": [
    {
      "currency": "USD",
      "available": 127.45,
      "total": 127.45,
      "pending": 0,
      "formatted": "127.45 USD"
    },
    {
      "currency": "BTC",
      "available": 0.00045000,
      "total": 0.00045000,
      "pending": 0,
      "formatted": "0.00045000 BTC (45,000 sats)"
    }
  ],
  "message": "Retrieved 2 currency balance(s) from Strike"
}

---

exchange_currency

Convert between USD and BTC within your Strike wallet.

Parameters:

Parameter	Type	Required	Description
sourceCurrency	string	Yes	Currency to convert from: USD or BTC
targetCurrency	string	Yes	Currency to convert to: BTC or USD
amount	decimal	Yes	Amount in source currency

Example - Buy Bitcoin:

User: Convert $50 to Bitcoin

Claude: [Uses exchange_currency with sourceCurrency=USD, targetCurrency=BTC, amount=50]

Exchange Complete!
- Converted: $50.00 USD
- Received: 0.00051282 BTC (51,282 sats)
- Rate: $97,500/BTC
- Fee: $0.25

Example - Sell Bitcoin:

User: Sell 0.001 BTC for dollars

Claude: [Uses exchange_currency with sourceCurrency=BTC, targetCurrency=USD, amount=0.001]

Exchange Complete!
- Converted: 0.001 BTC (100,000 sats)
- Received: $97.00 USD
- Rate: $97,500/BTC
- Fee: $0.50

---

send_onchain

Send an on-chain Bitcoin payment to a Bitcoin address (not Lightning).

Parameters:

Parameter	Type	Required	Description
address	string	Yes	Bitcoin address (bc1q..., 3..., or 1...)
amountSats	long	Yes	Amount to send in satoshis

Example:

User: Send 50000 sats to bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh

Claude: [Uses send_onchain]

On-Chain Payment Sent!
- Amount: 50,000 sats (0.0005 BTC)
- Address: bc1qxy2kg...
- Network Fee: 500 sats
- Status: COMPLETED
- Transaction ID: abc123def456...

On-Chain vs Lightning

On-chain payments are slower (10+ minutes) and have higher fees than Lightning. Use Lightning (pay_invoice) when possible.

---

L402 Tools (Free)

These tools are included for free with the MCP server. No license purchase or subscription required.

L402-Compatible Wallets Required

L402 requires a wallet that returns the payment preimage:

• LND (self-hosted) - Always works, guaranteed L402
• CoinOS - Free, easy, works for L402
• CLINK - Nostr-native, works for L402
• Strike - Returns preimage, works for L402
• Alby - ✅ Works

OpenNode and Primal don't return preimages and cannot be used for L402.

access_l402_resource

Fetch a URL with automatic L402 payment handling. When the API returns 402 Payment Required, the MCP automatically pays the invoice and retries with the L402 credential.

Parameters:

Parameter	Type	Required	Default	Description
url	string	Yes	-	URL to fetch
method	string	No	GET	HTTP method
headers	string	No	null	JSON object of headers
body	string	No	null	Request body
maxSats	int	No	1000	Maximum payment allowed

Example:

User: Fetch premium data from https://api.example.com/l402/data

Claude: [Uses access_l402_resource]

The API required a 50 sat payment which was automatically paid.

Response:
{
  "premium": "data...",
  "analysis": "..."
}

Payment Details:
- Amount: 50 sats ($0.05)
- L402 token cached for future requests

---

pay_l402_challenge

Manually pay an L402 invoice when you have the macaroon and invoice components separately.

Parameters:

Parameter	Type	Required	Default	Description
invoice	string	Yes	-	BOLT11 Lightning invoice
macaroon	string	Yes	-	Base64-encoded macaroon
maxSats	int	No	1000	Maximum payment allowed

Returns: L402 credential in format macaroon:preimage

---

discover_api

Search the L402 API registry to find available paid APIs by keyword or category, or fetch a specific API's manifest for full endpoint details and pricing.

Parameters:

Parameter	Type	Required	Default	Description
query	string	No	-	Search the registry by keyword (e.g., "weather", "ai")
category	string	No	-	Filter registry results by category
url	string	No	-	Fetch a specific API's manifest directly
budgetAware	bool	No	true	Annotate results with affordable call counts

Example — Search the registry:

User: Find me some weather APIs I can pay for

Claude: [Uses discover_api with query="weather"]

Found 3 weather APIs in the L402 registry:

1. Weather Data API — 5 sats/request (1,600 calls affordable)
2. Storm Tracker Pro — 25 sats/request (320 calls affordable)
3. Climate Analytics — 100 sats/request (80 calls affordable)

Want me to get full details on any of these?

Example — Get full manifest:

User: Show me the full details for Weather Data API

Claude: [Uses discover_api with url="https://api.lightningenable.com/l402/proxy/weather-api/.well-known/l402-manifest.json"]

Weather Data API — 3 endpoints:
- GET /v1/current — Current weather (5 sats)
- GET /v1/forecast — 7-day forecast (10 sats)
- GET /v1/historical — Historical data (25 sats)

Registry URL: Defaults to https://api.lightningenable.com. Override with L402_REGISTRY_URL or LIGHTNING_ENABLE_API_URL environment variable.

---

L402 Producer Tools (Agentic Commerce)

These tools enable your agent to charge other agents and users for access to resources. This is the producer side of L402 — your agent creates payment challenges and verifies payments. Requires LIGHTNING_ENABLE_API_KEY with an Agentic Commerce subscription.

Agents That Earn

The consumer tools above let agents spend. The producer tools below let agents earn. Together, they enable true agent-to-agent commerce — AI agents that autonomously buy and sell services using Lightning payments.

create_l402_challenge

Create an L402 payment challenge (Lightning invoice + macaroon) to charge another agent or user.

Parameters:

Parameter	Type	Required	Default	Description
resource	string	Yes	-	Resource identifier (URL, service name, or description)
priceSats	long	Yes	-	Price in satoshis to charge
description	string	No	null	Description shown on the Lightning invoice

Example:

User: Charge 50 sats for access to the forecast data

Claude: [Uses create_l402_challenge]

L402 challenge created!
- Invoice: lnbc500n1p3xyza...
- Price: 50 sats
- Resource: /api/weather/forecast

Share the invoice with the payer. After they pay,
use verify_l402_payment to confirm before granting access.

Response:

{
  "success": true,
  "challenge": {
    "invoice": "lnbc500n1p3xyza...",
    "macaroon": "AgELbGlnaHRuaW5n...",
    "paymentHash": "abc123def456...",
    "expiresAt": "2026-03-13T14:30:00Z"
  },
  "resource": "/api/weather/forecast",
  "priceSats": 50,
  "message": "L402 challenge created for 50 sats. Share the invoice with the payer."
}

---

verify_l402_payment

Verify an L402 token (macaroon + preimage) to confirm payment was made before granting access.

Parameters:

Parameter	Type	Required	Default	Description
macaroon	string	Yes	-	Base64-encoded macaroon from the L402 token
preimage	string	Yes	-	Hex-encoded preimage (proof of payment)

Example:

User: The agent sent this L402 token — verify it

Claude: [Uses verify_l402_payment]

Payment verified! The payer paid 50 sats for /api/weather/forecast.
Granting access now.

Response (valid):

{
  "success": true,
  "valid": true,
  "resource": "/api/weather/forecast",
  "message": "Payment verified. The payer has paid — you can now grant access to the resource."
}

Response (invalid):

{
  "success": true,
  "valid": false,
  "message": "Payment verification failed. The token is invalid or the invoice has not been paid. Do NOT grant access."
}

Always Verify

Never grant access based on a payer claiming they paid. Always call verify_l402_payment to cryptographically confirm payment before granting access.

See L402 Producer API for the complete producer guide with end-to-end examples.

---

Wallet Configuration

Strike (Recommended for USD Users)

Best for users who want USD balance management, BTC price tracking, and easy on/off ramps.

{
  "mcpServers": {
    "lightning-enable": {
      "command": "dotnet",
      "args": ["tool", "run", "lightning-enable-mcp"],
      "env": {
        "STRIKE_API_KEY": "your-strike-api-key"
      }
    }
  }
}

Setup:

1. Create account at https://strike.me
2. Get API key from https://dashboard.strike.me
3. Fund your account with BTC

Strike Payment Polling

Strike payments are polled with exponential backoff (1s, 1s, 1s, 2s, 2s, 2s, 4s cap) to minimize API calls while detecting completion quickly.

Available Tools: All tools including L402 (Strike returns preimage via lightning.preImage)

---

NWC - CoinOS or CLINK (Easy L402)

Good for L402 auto-pay. CoinOS, CLINK, and Alby Hub return preimage which is required for L402.

{
  "mcpServers": {
    "lightning-enable": {
      "command": "dotnet",
      "args": ["tool", "run", "lightning-enable-mcp"],
      "env": {
        "NWC_CONNECTION_STRING": "nostr+walletconnect://..."
      }
    }
  }
}

Setup:

1. Create wallet at https://coinos.io (free, recommended) or https://clink.tools (Nostr)
2. Go to Settings → NWC → Create connection
3. Enable auto-pay for the connection
4. Copy connection string Available Tools: All tools including L402 (CoinOS/CLINK confirmed working)

---

NWC (Nostr Wallet Connect)

Best for self-custody wallets. L402 support depends on wallet.

{
  "mcpServers": {
    "lightning-enable": {
      "command": "dotnet",
      "args": ["tool", "run", "lightning-enable-mcp"],
      "env": {
        "NWC_CONNECTION_STRING": "nostr+walletconnect://pubkey?relay=wss://relay.example.com&secret=xxx"
      }
    }
  }
}

Setup:

1. Use a compatible wallet (CoinOS, CLINK, Alby Hub, or Primal)
2. Create NWC connection in wallet settings
3. Copy connection string

NWC Connection Timeouts

The MCP server uses tuned WebSocket timeouts for NWC: 15 seconds for the initial connection and 5 seconds per message (payment response). If your relay is slow or unreachable, the connection fails gracefully rather than hanging.

L402 Compatibility:

Wallet	L402 Works	Cost
CoinOS	✅ Yes	Free
CLINK	✅ Yes	Free (Nostr users)
Alby Hub	✅ Yes	Self-host or paid cloud
Primal	❌ No	Free (no preimage)

CoinOS or CLINK for Free L402

CoinOS and CLINK are completely free and return preimages, so L402 works! Strike also returns preimages. OpenNode and Primal don't return preimages.

---

Budget Configuration

Spending limits are configured in ~/.lightning-enable/config.json (created automatically on first run):

{
  "currency": "USD",
  "tiers": {
    "autoApprove": 0.10,
    "logAndApprove": 1.00,
    "formConfirm": 10.00,
    "urlConfirm": 100.00
  },
  "limits": {
    "maxPerPayment": 500.00,
    "maxPerSession": 100.00
  },
  "session": {
    "cooldownSeconds": 1,
    "requireApprovalForFirstPayment": true
  }
}

Approval Tiers

Amount (USD)	Behavior
≤ $0.10	Auto-approved silently
$0.10 - $1.00	Approved but logged
$1.00 - $10.00	Click "Approve" in chat
$10.00 - $100.00	Type exact amount to confirm
> $500.00	Blocked entirely

Why This is AI-Proof

• Config file lives in your home directory, not environment variables
• No MCP tool can modify budget limits
• Only you can edit the config file
• Large payments require human verification (typing amount)

---

Environment Variables Reference

Variable	Required	Default	Description
STRIKE_API_KEY	If using Strike	-	Strike API key
OPENNODE_API_KEY	If using OpenNode	-	OpenNode API key
OPENNODE_ENVIRONMENT	No	production	production or dev
NWC_CONNECTION_STRING	If using NWC	-	Nostr Wallet Connect URI
LND_REST_HOST	If using LND	-	LND REST API host
LND_MACAROON_HEX	If using LND	-	LND admin macaroon in hex
LIGHTNING_ENABLE_API_URL	No	https://api.lightningenable.com	API base URL

L402 Tools

L402 tools are free and don't require an API key or license purchase. Just configure a compatible wallet and all L402 tools are available immediately.

---

Security Best Practices

1. Use a dedicated wallet - Never use your main wallet or business funds for AI spending
2. Configure budget limits - Edit ~/.lightning-enable/config.json before first use
3. Review payment history - Check get_payment_history after sessions
4. Rotate API keys - Monthly rotation recommended
5. Never commit keys - Keep API keys out of version control
6. Preimage log safety - Preimage values are automatically truncated in logs (first 8 characters only), preventing full preimage exposure in log files or debug output

See AI Spending Security for detailed security guidance.

---

Troubleshooting

"Wallet not configured"

Set one of: STRIKE_API_KEY, OPENNODE_API_KEY, or NWC_CONNECTION_STRING

"Budget limit exceeded"

Payment exceeds your limits. Use get_budget_status to see current limits, edit config file to adjust.

"License required for L402 features"

This error should no longer occur. All L402 tools are now free. If you see this error, update your MCP server to the latest version.

"Feature not supported"

Some features are wallet-specific (e.g., BTC price is Strike-only). Check the compatibility table above.

"L402 payment succeeded but access failed"

Your wallet doesn't return preimage. Use LND, CoinOS, CLINK, Alby Hub, or Strike. OpenNode and Primal don't work for L402 (no preimage return).

---

Try It: Lightning Enable Store

The Lightning Enable Store is a live L402-powered web store where AI agents can purchase physical merchandise using Bitcoin Lightning payments.

Ask Claude: "Buy me a Lightning Enable t-shirt from store.lightningenable.com"

This demonstrates the full L402 flow:

1. Browse catalog — GET /api/store/catalog
2. Checkout — POST /api/store/checkout (returns HTTP 402 with invoice + macaroon)
3. Pay invoice — Use pay_invoice with the BOLT11 string
4. Claim order — POST /api/store/claim with L402 credential

---

Next Steps

• L402 Producer API - Make your agents earn with L402 challenges
• MCP Wallet Setup - Detailed wallet configuration
• AI Spending Security - Budget configuration
• AI Agent Integration - Advanced usage