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.

Overview

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

1. Detects the 402 Payment Required response
2. Pays the Lightning invoice via Nostr Wallet Connect (NWC)
3. Retries the request with the L402 credential
4. Returns the response to the agent

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

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

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:

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

Configuration

Environment Variables

Variable	Required	Default	Description
NWC_CONNECTION_STRING	Yes	-	Nostr Wallet Connect URI
L402_MAX_SATS_PER_REQUEST	No	1000	Max sats per request
L402_MAX_SATS_PER_SESSION	No	10000	Max sats per session

Getting an NWC Connection String

NWC connects the MCP server to your Lightning wallet. Get one from:

Wallet	Setup
Alby	Settings → Connections → Add NWC
Mutiny	Settings → Nostr Wallet Connect
Coinos	Settings → NWC

The connection string format:

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

Claude Desktop Setup

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": "uvx",
      "args": ["lightning-enable-mcp"],
      "env": {
        "NWC_CONNECTION_STRING": "nostr+walletconnect://your-pubkey?relay=wss://relay.getalby.com/v1&secret=your-secret"
      }
    }
  }
}

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

configure_budget

Set spending limits for the session.

Parameter	Type	Default	Description
per_request	int	1000	Max sats per request
per_session	int	10000	Max sats total

User: Set a budget of 500 sats per request, 2000 max

Claude: [Uses configure_budget]

Budget updated:
- Per request: 500 sats
- Per session: 2,000 sats

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

Security Best Practices

Use a Dedicated Wallet

Create a separate Lightning wallet for AI agents with limited funds:

# Set a low session limit
L402_MAX_SATS_PER_SESSION=1000  # Max 1000 sats per session

Review Payment History

Regularly check what payments are being made:

User: Show all payments from today

Claude: [Uses get_payment_history with limit=100]

Set Appropriate Budgets

Start with low limits and increase as needed:

{
  "env": {
    "L402_MAX_SATS_PER_REQUEST": "100",
    "L402_MAX_SATS_PER_SESSION": "1000"
  }
}

Monitor Wallet Balance

Keep your NWC 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

"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

wallet = NwcWallet(connection_string)
client = L402Client(wallet, max_sats=1000)

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

.NET

using LightningEnable.Mcp;

var wallet = new NwcWalletService(connectionString);
var client = new L402HttpClient(wallet, maxSats: 1000);

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

Next Steps

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