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.

Open-Source MCP Server

The MCP server is open-source (MIT) and free to install. 15 of the 23 tools work out of the box with just a wallet — no account or API key required. Producer tools (2) and ASA tools (6) require a Lightning Enable API key.

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 your configured wallet (Strike, LND, or NWC — must return preimage for L402)
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 (Strike, LND, or NWC)

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 - You hold the keys, 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
`confirmation_nonce`	string	No	-	Confirmation code from the server console (`confirmationNonce` in .NET). Required on the retry when the first call returned `requiresConfirmation=true`

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	No	Base64 macaroon. Omit for MPP (Machine Payments Protocol) mode — invoice + preimage only
`max_sats`	int	No	Max payment
`confirmation_nonce`	string	No	Confirmation code from the server console (`confirmationNonce` in .NET). Required on the retry when confirmation was requested

Returns: L402 credential macaroon:preimage (or the bare preimage in MPP mode)

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 raised by editing the config file — an agent can tighten them at runtime via configure_budget, but never raise them.

User: What are my current budget limits?

Claude: [Uses get_budget_status]

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

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

Note: AI cannot RAISE budget limits (the configure_budget tool can only tighten them). Edit config.json to raise limits.

AI-Proof Budget System

Budget limits are configured in ~/.lightning-enable/config.json, which AI agents cannot raise. The only budget tool, configure_budget, can solely tighten limits — never loosen or bypass them. This prevents AI from increasing its own spending authority. 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 (Python package; the .NET tool relies on budget-service limits)
`confirmation_nonce`	string	No	-	Confirmation code from the server console (`confirmationNonce` in .NET). Required on the retry when the first call returned `requiresConfirmation=true`

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

note

Operator budget limits are set by editing ~/.lightning-enable/config.json directly. The configure_budget tool can only tighten (lower) those limits at runtime — an agent can never raise them above your config-file values, so a prompt-injected agent can't loosen its own caps. Set your session limit in the config file before starting.

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

Claude: [Checks budget via get_budget_status]
[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 users with multiple wallets, create a dedicated wallet specifically 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": 1.00,
    "logAndApprove": 5.00,
    "formConfirm": 25.00,
    "urlConfirm": 100.00
  },
  "limits": {
    "maxPerPayment": 500.00,
    "maxPerSession": 100.00
  }
}

Multi-Tier Approval System:

Amount (USD)	Behavior
≤ $1.00	Auto-approved silently
$1.00 - $5.00	Logged but approved
$5.00 - $500.00	Out-of-band confirmation: the server prints a code to its console/stderr; you give the code to the AI, which re-calls the payment tool with it
> $500.00	Blocked entirely (`maxPerPayment`)

How out-of-band confirmation works: the confirmation code is printed to the server's console — never returned in a tool result — so a prompt-injected agent can't read its own code and self-approve. The agent must ask you for the code, then re-call the original payment tool with the confirmationNonce (.NET) / confirmation_nonce (Python) parameter. Codes are bound to the exact amount, tool, and destination. send_onchain always requires a code and fails closed if the budget service is unavailable.

Why this is AI-proof: The config file lives in your home directory. The only budget MCP tool, configure_budget, can solely tighten limits — there is no tool to raise or loosen them. Only you can raise budget limits, by editing the config file.

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" (pre-v1.6.0 only)

This error only occurs on versions before v1.6.0. All L402 tools are free in v1.6.0 and later. 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. Edit ~/.lightning-enable/config.json to adjust your limits.

"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

note

The Python MCP server is invoked as a subprocess by your MCP client (Claude Desktop, etc.) and configured via environment variables. For programmatic use, see the l402-requests Python package.

# pip install l402-requests
from l402_requests import AsyncL402Client

# Wallet auto-detected from environment variables (LND > NWC > Strike):
# LND_REST_HOST + LND_MACAROON_HEX, NWC_CONNECTION_STRING, or STRIKE_API_KEY
async with AsyncL402Client() as client:
    response = await client.get("https://api.example.com/paid-resource")
    print(response.json())

There is also a synchronous L402Client and module-level l402_requests.get(...) / post(...) helpers. See the l402-requests package for budget controls and spending introspection.

.NET

// dotnet add package L402Requests
using L402Requests;

// Wallet auto-detected from environment variables (LND > NWC > Strike),
// or pass one explicitly: new L402HttpClient(new StrikeWallet("your-api-key"))
using var client = new L402HttpClient(new L402Options
{
    MaxSatsPerRequest = 1000
});

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

See the L402Requests NuGet package for budget limits, domain allowlists, and HttpClientFactory integration.

Next Steps

Complete Documentation

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

Wallet Setup

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

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" (pre-v1.6.0 only)​

"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​