AI Agent Integration

Lightning Enable provides MCP (Model Context Protocol) servers that enable AI agents like Claude to automatically access L402-protected APIs with Lightning payments.

All Tools Free

All MCP tools are completely free — no license, API key, or subscription required. Just configure a wallet and go.

Overview

When an AI agent encounters an L402-protected resource, the MCP server automatically:

Detects the 402 Payment Required response
Pays the Lightning invoice via OpenNode (returns preimage)
Retries the request with the L402 credential
Returns the response to the agent

The MCP server can also pay Lightning invoices directly using the pay_invoice tool, enabling AI agents to make arbitrary Lightning payments on your behalf.

This enables seamless pay-per-request API access without user intervention.

User → Claude → MCP Server → L402 API
                    ↓
              Lightning Wallet (OpenNode)

L402 Wallet Compatibility

L402 auto-pay requires the payment preimage. These wallets work:

LND (self-hosted) - Best for guaranteed L402, always returns preimage
NWC with CoinOS - Free, easy, returns preimage
NWC with CLINK - Nostr users, returns preimage
Strike - Easy setup, returns preimage via lightning.preImage
Alby Hub - Self-custody, returns preimage

These do NOT work for L402 (no preimage return):

OpenNode - No preimage
Primal - No preimage

Available Implementations

Python MCP Server

Recommended for Claude Desktop on all platforms.

pip install lightning-enable-mcp

Or use uvx (no installation needed):

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

.NET MCP Server

For Windows users or .NET environments:

dotnet tool install -g LightningEnable.Mcp

Configuration (for L402, use LND, Strike, or NWC with CoinOS/CLINK):

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

Configuration

Wallet Options

The MCP server supports multiple wallet providers. Choose one based on your needs:

Wallet	Best For	Setup Complexity	L402 Auto-Pay
LND (self-hosted)	L402 auto-pay (guaranteed)	Hard (run a node)	✅ Yes
NWC (CoinOS/CLINK)	L402 auto-pay (easy)	Medium (wallet setup)	✅ Yes
Alby	L402 auto-pay	Medium (wallet setup)	✅ Yes
Strike	USD users, everyday spending	Easy (API key)	✅ Yes
OpenNode	Direct payments only	Easy (API key)	❌ No*

*OpenNode does not return the payment preimage, which is required for L402 credential verification. Use only for direct pay_invoice calls.

Wallet Priority

If multiple wallets are configured, they are used in this order (optimized for L402):

LND (if LND_REST_HOST + LND_MACAROON_HEX are set)
NWC (if NWC_CONNECTION_STRING is set)
Strike (if STRIKE_API_KEY is set)
OpenNode (if OPENNODE_API_KEY is set)

Override with WALLET_PRIORITY environment variable or config file wallets.priority.

Option 1: Strike (Recommended for USD Users)

Strike is ideal if you prefer managing funds in USD. It provides easy on/off ramps and supports both Bitcoin and USD balances.

Create an account at https://strike.me
Get your API key from https://dashboard.strike.me
Fund your Strike account

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

Variable	Required	Default	Description
`STRIKE_API_KEY`	Yes	-	Strike API key

Strike L402 Support

Strike now returns the payment preimage via lightning.preImage, enabling full L402 support. Strike works for both direct payments (pay_invoice) and L402 auto-pay (access_l402_resource). Ensure your Strike account has BTC balance (payments use BTC, not USD).

Additional Strike features:

get_btc_price - Get current BTC/USD price
get_all_balances - View USD and BTC balances
exchange_currency - Convert between USD and BTC
send_onchain - Send on-chain Bitcoin payments

Option 2: OpenNode (Direct Payments Only)

Use your OpenNode account to pay invoices directly. Note: OpenNode does not return preimages, so it cannot be used for L402 auto-pay.

Get your API key from https://app.opennode.com (or https://dev.opennode.com for testnet)
Ensure the API key has withdrawal permissions
Fund your OpenNode account

{
  "mcpServers": {
    "lightning-enable": {
      "command": "dotnet",
      "args": ["tool", "run", "lightning-enable-mcp"],
      "env": {
        "OPENNODE_API_KEY": "your-opennode-api-key",
        "OPENNODE_ENVIRONMENT": "dev"
      }
    }
  }
}

Variable	Required	Default	Description
`OPENNODE_API_KEY`	Yes	-	OpenNode API key with withdrawal permissions
`OPENNODE_ENVIRONMENT`	No	production	`production` for mainnet, `dev` for testnet

Option 3: Nostr Wallet Connect (NWC)

NWC connects the MCP server to a Lightning wallet via the Nostr protocol. L402 compatibility depends on the wallet.

NWC L402 Compatibility

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

Variable	Required	Default	Description
`NWC_CONNECTION_STRING`	Yes	-	Nostr Wallet Connect URI

Getting an NWC Connection String

Available NWC providers:

Wallet	L402	Setup
CoinOS	✅ Yes	Settings → NWC (Free, recommended)
CLINK	✅ Yes	Nostr-native wallet
Alby Hub	✅ Yes	Dashboard → Connections
Primal	❌ No	Settings → Wallet → NWC (direct payments only)

The connection string format:

nostr+walletconnect://<pubkey>?relay=<relay-url>&secret=<secret>

Claude Desktop Setup (For L402 - Use LND or NWC)

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

Option A: LND (Guaranteed L402)

{
  "mcpServers": {
    "lightning-enable": {
      "command": "dotnet",
      "args": ["tool", "run", "lightning-enable-mcp"],
      "env": {
        "LND_REST_HOST": "localhost:8080",
        "LND_MACAROON_HEX": "your-admin-macaroon-in-hex"
      }
    }
  }
}

Option B: NWC with CoinOS (Free, Easy)

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

Available Tools

access_l402_resource

Fetch a URL with automatic L402 payment handling.

Parameter	Type	Required	Default	Description
`url`	string	Yes	-	URL to fetch
`method`	string	No	GET	HTTP method
`headers`	object	No		Additional headers
`body`	string	No	-	Request body
`max_sats`	int	No	1000	Max payment

Example conversation:

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

Claude: I'll access that L402-protected resource.
[Uses access_l402_resource]

The request required 50 sats which was automatically paid.
Here's the response: {"data": "premium content..."}

pay_l402_challenge

Manually pay an L402 invoice when you have the components.

Parameter	Type	Required	Description
`invoice`	string	Yes	BOLT11 invoice
`macaroon`	string	Yes	Base64 macaroon
`max_sats`	int	No	Max payment

Returns: L402 credential macaroon:preimage

check_wallet_balance

Check connected wallet balance and session spending.

User: Check my wallet balance

Claude: [Uses check_wallet_balance]

Wallet Balance: 50,000 sats
Session Spending: 150 sats
Budget Remaining: 9,850 sats

get_payment_history

List recent L402 payments.

Parameter	Type	Default	Description
`limit`	int	10	Max payments to return

User: Show my payment history

Claude: [Uses get_payment_history]

Recent Payments:
1. api.example.com/data - 50 sats - 2 min ago
2. api.weather.com/forecast - 10 sats - 5 min ago
Total: 60 sats

get_budget_status

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

User: What are my current budget limits?

Claude: [Uses get_budget_status]

Budget Status:
- Config file: ~/.lightning-enable/config.json
- Auto-approve: up to $0.10
- Log & approve: $0.10 - $1.00
- Requires approval: $1.00 - $10.00
- Requires amount verification: $10.00 - $100.00

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

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

AI-Proof Budget System

Budget limits are configured in ~/.lightning-enable/config.json, which AI agents cannot modify. This prevents AI from bypassing spending limits. See AI Spending Security for details.

pay_invoice

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

Parameter	Type	Required	Default	Description
`invoice`	string	Yes	-	BOLT11 Lightning invoice
`max_sats`	int	No	1000	Max payment allowed

Returns: Preimage (proof of payment) or error details

User: Pay this Lightning invoice: lnbc100n1p3...

Claude: [Uses pay_invoice]

Payment successful!
- Amount: 100 sats
- Preimage: 0a1b2c3d...

Security Notice

The pay_invoice tool enables AI to spend your Bitcoin. This is powerful but requires caution:

Use a dedicated wallet with limited funds
Configure budget limits before first use
Review payments after each session

See AI Spending Security for mandatory safeguards.

Usage Examples

Accessing Premium APIs

User: Get the 7-day weather forecast from the Lightning weather API

Claude: I'll fetch that from the L402-protected weather API.
[Uses access_l402_resource with url="https://api.example.com/l402/proxy/weather/forecast/7day"]

The forecast required a payment of 25 sats. Here's your 7-day forecast:
- Monday: Sunny, 72°F
- Tuesday: Partly cloudy, 68°F
...

Research with Multiple Paid APIs

User: Research Bitcoin price predictions from premium sources

Claude: I'll query several L402-protected data sources.
[Uses access_l402_resource multiple times]

I accessed 3 paid APIs (total: 150 sats):
1. BitcoinAnalytics - Bullish, target $100k
2. CryptoResearch - Neutral, consolidation expected
3. ChainMetrics - On-chain data suggests accumulation

Budget-Aware Browsing

User: I have a 500 sat budget. Find the best AI coding assistant APIs.

Claude: [Uses configure_budget with per_session=500]
[Uses access_l402_resource for multiple APIs, stopping when budget depletes]

I evaluated 5 APIs within your 500 sat budget:
1. CodeHelper API (50 sats) - Best for Python
2. AIAssist (100 sats) - Multi-language support
...
Remaining budget: 50 sats

Direct Invoice Payments

The pay_invoice tool allows AI to pay any Lightning invoice, not just L402 challenges:

User: I want to tip this content creator. Pay this invoice: lnbc500n1p3...

Claude: [Uses pay_invoice with invoice="lnbc500n1p3..."]

Payment successful!
- Amount: 500 sats
- Preimage: 7f8a9b2c...
- Recipient received the payment instantly

The preimage proves the payment was completed.

User: Buy access to this premium article by paying: lnbc1000n1...

Claude: Let me check your budget first.
[Uses check_wallet_balance]
Balance: 5,000 sats - sufficient for this 1,000 sat payment.

[Uses pay_invoice with invoice="lnbc1000n1..."]

Payment complete! 1,000 sats paid. Here's your preimage for proof: 3d4e5f...
You can now access the article.

Security Best Practices

Critical: Read Before Using pay_invoice

The pay_invoice tool enables AI to spend real Bitcoin from your wallet. Before first use:

Read AI Spending Security - mandatory safeguards
Review Spending Guidelines - budget recommendations
Understand Legal Considerations - liability and terms

Use a Dedicated Wallet

Never use your main wallet or business funds. Create a separate wallet specifically for AI spending:

Main Wallet (Your Funds)         AI Spending Wallet (Separate)
├── Large balance                ├── Small balance (< $100)
├── Business funds               ├── Only for AI agents
└── NEVER for AI spending        └── Easy to monitor/refill

For OpenNode users, create a separate account for AI spending.

Configure Budget Limits (Mandatory)

Budget limits are configured in ~/.lightning-enable/config.json. This file is 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
  }
}

Multi-Tier Approval System:

Amount (USD)	Behavior
≤ $0.10	Auto-approved silently
$0.10 - $1.00	Logged but approved
$1.00 - $10.00	You must click "Approve" in chat
$10.00 - $100.00	You must type the exact amount to confirm
> $500.00	Blocked entirely

Why this is AI-proof: The config file lives in your home directory. There is no MCP tool to modify it. Only you can change budget limits.

See AI Spending Security for detailed configuration.

Review Payment History

Regularly check what payments are being made:

User: Show all payments from today

Claude: [Uses get_payment_history with limit=100]

Monitor Wallet Balance

Keep your wallet funded with only what you're willing to spend:

User: Check my wallet before we start

Claude: [Uses check_wallet_balance]
Balance: 5,000 sats - sufficient for this session

Troubleshooting

"License required for L402 features"

This error should no longer occur. All L402 tools are now free in v1.6.0+. Update your MCP server:

dotnet tool update -g LightningEnable.Mcp

"NWC wallet not configured"

Ensure NWC_CONNECTION_STRING is set correctly in your config.

"Budget check failed"

Payment exceeds configured limits. Use configure_budget to adjust.

"Payment failed"

Check:

Wallet has sufficient balance
Invoice hasn't expired (usually 10 min)
NWC connection is active

Connection issues

Verify:

Relay URL is accessible
Wallet app is running (for mobile wallets)
NWC connection hasn't been revoked

Building Your Own Integration

Python

from lightning_enable_mcp import L402Client, NwcWallet

# Use NWC with CoinOS/CLINK for L402 (returns preimage)
wallet = NwcWallet(connection_string="nostr+walletconnect://...")
client = L402Client(wallet, max_sats=1000)

response = await client.fetch("https://api.example.com/paid-resource")

.NET

using LightningEnable.Mcp;

// Use LND for L402 (always returns preimage)
var wallet = new LndWalletService(restHost, macaroonHex);
var client = new L402HttpClient(wallet, maxSats: 1000);

var response = await client.GetAsync("https://api.example.com/paid-resource");

Next Steps

Complete Documentation

MCP Complete Guide - Full tool reference, all capabilities, examples

Wallet Setup

Wallet Configuration - Detailed wallet setup for Strike, OpenNode, and NWC

Security (Read First!)

AI Spending Security - Mandatory safeguards for pay_invoice
Spending Guidelines - Budget recommendations by use case
Legal Considerations - Liability and terms

Technical

Proxy Configuration - Create L402 proxies
L402 API Reference - API details
How It Works - Technical overview

Overview​

Available Implementations​

Python MCP Server​

.NET MCP Server​

Configuration​

Wallet Options​

Option 1: Strike (Recommended for USD Users)​

Option 2: OpenNode (Direct Payments Only)​

Option 3: Nostr Wallet Connect (NWC)​

Getting an NWC Connection String​

Claude Desktop Setup (For L402 - Use LND or NWC)​

Available Tools​

access_l402_resource​

pay_l402_challenge​

check_wallet_balance​

get_payment_history​

get_budget_status​

pay_invoice​

Usage Examples​

Accessing Premium APIs​

Research with Multiple Paid APIs​

Budget-Aware Browsing​

Direct Invoice Payments​

Security Best Practices​

Use a Dedicated Wallet​

Configure Budget Limits (Mandatory)​

Review Payment History​

Monitor Wallet Balance​

Troubleshooting​

"License required for L402 features"​

"NWC wallet not configured"​

"Budget check failed"​

"Payment failed"​

Connection issues​

Building Your Own Integration​

Python​

.NET​

Next Steps​

Complete Documentation​

Wallet Setup​

Security (Read First!)​

Technical​