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.
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
The base install works on every platform (including Windows) with no build toolchain. If you connect a Nostr Wallet Connect (NWC) wallet, install the optional extra: pip install lightning-enable-mcp[nwc]. Other wallet types (LND, Strike, OpenNode) don't need it. (.NET is unaffected — it uses managed crypto.)
Quick Start
Claude Code users: register the server with claude mcp add --transport stdio lightning-enable --env STRIKE_API_KEY=your-key -- lightning-enable-mcp (or a project .mcp.json) — see Claude Code Setup. Claude Code does not read claude_desktop_config.json.
Claude Desktop users: 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 | ✅ | ❌ | ✅ (BTC only) | ❌ | ❌ | ❌ |
get_btc_price | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
exchange_currency | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
send_onchain | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
discover_api | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
access_l402_resource | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ |
pay_l402_challenge | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ |
confirm_payment | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
configure_budget | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
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
The table above covers the 15 out-of-the-box tools plus the 2 producer tools (create_l402_challenge, verify_l402_payment). The remaining 6 Agent Service Agreement (ASA) tools also require LIGHTNING_ENABLE_API_KEY and are independent of wallet type — see ASA tools below. 23 tools total.
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 |
max_sats | int | No | 1000 | Maximum payment allowed (Python package; the .NET tool relies on budget-service limits) |
confirmationNonce | string | No | - | Confirmation code from the server console (confirmation_nonce in Python). Required on the retry when the first call returned requiresConfirmation=true — see Out-of-Band Confirmation |
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 — limits can only be raised by editing the config file. (The configure_budget tool can tighten the runtime sats caps, never raise them.)
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 out-of-band confirmation code: above $1.00
- Maximum per payment: $500.00
- Maximum per session: $100.00
Session:
- Spent: $0.45 (4,500 sats)
- Remaining: $99.55
Note: AI cannot RAISE budget limits. configure_budget can only tighten
the runtime sats caps; edit config.json to raise limits.
Invoice Tools (Strike, OpenNode, LND)
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": "Strike",
"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": "Strike",
"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). Works with Strike and LND.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
address | string | Yes | Bitcoin address (bc1q..., 3..., or 1...) |
amountSats | long | Yes | Amount to send in satoshis |
confirmationNonce | string | No | Confirmation code from the server console (confirmation_nonce in Python). Omit on the first call to request one; always required to actually send |
On-chain payments are irreversible, so send_onchain always requires an out-of-band confirmation code — even for small amounts — and fails closed if the budget service is unavailable. See Out-of-Band Confirmation.
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 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 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 |
confirmationNonce | string | No | - | Confirmation code from the server console (confirmation_nonce in Python). Required on the retry when the first call returned requiresConfirmation=true |
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 (or MPP) invoice when you have the invoice — and, for L402, the macaroon — as separate components.
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
invoice | string | Yes | - | BOLT11 Lightning invoice |
macaroon | string | No | - | Base64-encoded macaroon. Optional — omit for MPP mode |
maxSats | int | No | 1000 | Maximum payment allowed |
confirmationNonce | string | No | - | Confirmation code from the server console (confirmation_nonce in Python). Required on the retry when confirmation was requested |
Returns: L402 credential in format macaroon:preimage (L402 mode), or the bare preimage (MPP mode)
MPP support: the macaroon parameter is optional. When you omit it, the tool operates in MPP (Machine Payments Protocol) mode — some paid APIs issue a plain Lightning invoice and accept the payment preimage alone as the access token, with no macaroon involved. Provide the macaroon for standard L402 challenges; omit it when the challenge only gave you an invoice.
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.
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."
}
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.
Agent Service Agreement (ASA) Tools
Agent Service Agreements (ASA) shipped 2026-04-18 and are live at wss://agents.lightningenable.com / nostrwolfe.com. They let agents discover each other, request services, settle via L402 payment over Nostr, and build on-protocol reputation (flow: discover → request → settle → attest). All 6 ASA tools require LIGHTNING_ENABLE_API_KEY (wallet type does not matter).
| Tool | Purpose |
|---|---|
request_agent_service | Entry point. Sends a service request (kind 38401 event) referencing the provider's capability. |
discover_agent_services | Discover agent capabilities on Nostr by category, hashtag, or keyword (kind 38400 events). |
settle_agent_service | Settle an agreement via L402 payment (consumer/requester side) using the same auto-pay flow as access_l402_resource. |
publish_agent_capability | Advertise your agent's service so other agents can discover it (kind 38400 event; optionally auto-creates an L402 proxy). |
publish_agent_attestation | Publish a review (rating 1–5) for an agent after a completed agreement (kind 38403 event) to build its reputation. |
get_agent_reputation | Fetch an agent's reputation score and reviews (queries kind 38403 attestations for a pubkey). |
request_agent_service
Sends a service request (kind 38401 event) referencing the provider's capability. The full ASA flow is discover → request → settle → attest. If the provider has an L402 endpoint, you can skip this step and use settle_agent_service directly.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
capabilityEventId | string | Yes | - | Event ID of the capability to request |
budgetSats | int | Yes | - | Maximum budget in satoshis |
parameters | string | No | - | Additional parameters as JSON |
discover_agent_services
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
category | string | No | - | Filter by service category (e.g., ai, data, translation) |
hashtags | string[] | No | - | Filter by hashtags |
query | string | No | - | Search query |
limit | int | No | 20 | Maximum results to return |
settle_agent_service
Pays the L402 endpoint specified in the agreement, completing the service transaction. If you are the provider (selling a service), use create_l402_challenge to generate an invoice and verify_l402_payment to confirm payment instead.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
l402Endpoint | string | Yes | - | L402 endpoint URL from the service agreement |
method | string | No | GET | HTTP method (GET, POST) |
body | string | No | - | Optional request body for POST requests |
agreementId | string | No | - | Agreement event ID for tracking |
maxSats | int | No | 1000 | Maximum satoshis to pay |
publish_agent_capability
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
serviceId | string | Yes | - | Unique service identifier (used as d-tag) |
categories | string[] | Yes | - | Service categories (e.g., ['ai', 'translation']) |
content | string | Yes | - | Description of the service |
priceSats | int | Yes | - | Price per request in satoshis |
l402Endpoint | string | No | - | L402 endpoint URL for payment settlement |
targetUrl | string | No | - | Target API URL (if auto-creating an L402 proxy via Lightning Enable) |
hashtags | string[] | No | - | Hashtags for discoverability |
publish_agent_attestation
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
subjectPubkey | string | Yes | - | Pubkey of the agent being reviewed |
agreementId | string | Yes | - | Event ID of the agreement this review is for |
rating | int | Yes | - | Rating from 1–5 |
content | string | Yes | - | Free-text review content |
get_agent_reputation
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
pubkey | string | Yes | - | Pubkey of the agent to query reputation for |
limit | int | No | 20 | Maximum number of attestations to return |
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:
- Create account at https://strike.me
- Get API key from https://dashboard.strike.me
- Fund your account with BTC
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:
- Create wallet at https://coinos.io (free, recommended) or https://clink.tools (Nostr)
- Go to Settings → NWC → Create connection
- Enable auto-pay for the connection
- Copy connection string Available Tools: All tools including L402 (CoinOS/CLINK confirmed working)
NWC (Nostr Wallet Connect)
Best when you hold the keys to your own wallet. 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:
- Use a compatible wallet (CoinOS, CLINK, Alby Hub, or Primal)
- Create NWC connection in wallet settings
- Copy connection string
The MCP server uses tuned WebSocket timeouts for NWC: 3 seconds for the NIP-47 INFO encryption auto-detect, then roughly 30 seconds (.NET) or 60 seconds (Python) waiting for a 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 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": 2,
"requireApprovalForFirstPayment": false
}
}
(The session values shown are the defaults: a 2-second cooldown between payments, and no forced confirmation on the first payment of a session — set requireApprovalForFirstPayment to true to opt in.)
Approval Tiers
| Amount (USD) | Behavior |
|---|---|
| ≤ $0.10 | Auto-approved silently |
| $0.10 - $1.00 | Approved but logged |
| $1.00 - $500.00 | Out-of-band confirmation required (see below) |
| > $500.00 | Blocked entirely (maxPerPayment) |
Out-of-Band Confirmation
When a payment exceeds the auto-approve threshold, the server prints a confirmation code to its console/stderr — the channel the human operator sees. The code is never returned in a tool result, so a prompt-injected agent can't read its own code and self-approve.
The flow:
- The agent calls the payment tool (
pay_invoice,access_l402_resource,pay_l402_challenge, orsend_onchain); the response says confirmation is required — without the code. - The server prints the code to its console/stderr, where you read it.
- You give the code to the AI, which re-calls the original payment tool with the
confirmationNonce(.NET) /confirmation_nonce(Python) parameter. The separateconfirm_paymenttool only verifies a code — it never executes a payment.
Codes are bound to the exact amount, tool, and destination (invoice / URL / on-chain address) — a code can't be reused for a different payment or redirected to a different destination (v1.12.13). send_onchain always requires a code (irreversible) and fails closed if the budget service is unavailable.
Why This is AI-Proof
- Config file lives in your home directory, not environment variables
- The only budget tool,
configure_budget, is tighten-only — it can lower the runtime sats caps but can never raise any limit above your config file - Only you can edit the config file
- Payments above the auto-approve threshold require the out-of-band console code that only the human can see
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 |
LND_SKIP_TLS_VERIFY | No | false | Set true to skip LND TLS verification (development only) |
LND_TLS_CERT_PATH | No | - | Path to LND tls.cert for remote connections (.NET package) |
WALLET_PRIORITY | No | lnd > nwc > strike > opennode | Force a specific wallet when several are configured (e.g., nwc) |
LIGHTNING_ENABLE_API_KEY | For producer/ASA tools | - | Lightning Enable API key — unlocks the 8 producer + ASA tools |
LIGHTNING_ENABLE_API_URL | No | https://api.lightningenable.com | API base URL |
L402_REGISTRY_URL | No | falls back to LIGHTNING_ENABLE_API_URL | Registry endpoint used by discover_api |
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
- Use a dedicated wallet - Never use your main wallet or business funds for AI spending
- Configure budget limits - Edit
~/.lightning-enable/config.jsonbefore first use - Review payment history - Check
get_payment_historyafter sessions - Rotate API keys - Monthly rotation recommended
- Never commit keys - Keep API keys out of version control
- 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, NWC_CONNECTION_STRING, LND_REST_HOST+LND_MACAROON_HEX, or OPENNODE_API_KEY
"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" (pre-v1.6.0 only)
This error only occurs on versions before v1.6.0. All L402 consumer tools are free in v1.6.0 and later. 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:
- Browse catalog —
GET /api/store/catalog - Checkout —
POST /api/store/checkout(returns HTTP 402 with invoice + macaroon) - Pay invoice — Use
pay_invoicewith the BOLT11 string - Claim order —
POST /api/store/claimwith 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