MCP Wallet Setup

This guide covers all wallet options for the Lightning Enable MCP server. The critical factor for L402 is whether the wallet returns preimage - without it, L402 authentication fails.

L402 Compatibility Matrix

Wallet	Returns Preimage	L402 Works	Custody	Best For
LND (Your Node)	✅ Always	✅ Yes	You control	Power users, guaranteed L402
NWC (CoinOS)	✅ Yes	✅ Yes	Custodial	Free, easy, L402 works
NWC (CLINK)	✅ Yes	✅ Yes	Custodial	Nostr users, L402 works
Alby	✅ Yes	✅ Yes	Self-custody	NWC compatible
Strike	✅ Yes	✅ Yes	Custodial	USD users, easy setup, L402 works
Primal	❌ No	❌ No	Custodial	Direct payments only
OpenNode	❌ No	❌ No	Custodial	Direct payments only

Building on L402?

Wallet preimage return is critical. If your wallet doesn't return preimages, L402 authentication breaks - payment succeeds but API access fails.

Why Preimage Matters

L402 authentication requires the preimage (proof of payment) to create credentials. If your wallet doesn't return it, payment succeeds but API access fails.

Recommended Setup for L402

Option 1: LND (Best for Guaranteed L402)

Why LND?

You run your own Lightning node
LND always returns preimage - L402 is guaranteed to work
No third-party dependency
True self-custody

Requirements:

Running LND node (local or remote)
REST API enabled
Admin macaroon

Configuration:

{
  "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"
      }
    }
  }
}

Getting Your Macaroon in Hex:

# Linux/Mac:
xxd -ps -c 1000 ~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon

# Windows PowerShell:
[System.BitConverter]::ToString([System.IO.File]::ReadAllBytes("$env:LOCALAPPDATA\Lnd\data\chain\bitcoin\mainnet\admin.macaroon")) -replace '-',''

Or use config file (~/.lightning-enable/config.json):

{
  "wallets": {
    "lndRestHost": "localhost:8080",
    "lndMacaroonHex": "0201036c6e6402f801...",
    "priority": "lnd"
  }
}

Option 2: NWC with CoinOS (Free, Easy)

Why CoinOS?

Completely free
Browser-based, no install
Returns preimage - L402 works
Easy to set up

NWC Connection Timeouts

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

Setup:

Sign up at https://coinos.io
Go to Settings → NWC
Create a new NWC connection
Enable auto-pay for the connection (important for L402!)
Copy the connection string

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

Windows Users

If the connection string contains special characters that don't work in environment variables, use the config file instead:

{
  "wallets": {
    "nwcConnectionString": "nostr+walletconnect://...",
    "priority": "nwc"
  }
}

Option 3: NWC with Alby Hub (Self-Custody)

Why Alby Hub?

Self-custody (you control the keys)
Returns preimage - L402 works
Connect to your own node

Setup:

Deploy Alby Hub: https://albyhub.com?ref=magma
Connect to your Lightning node
Create NWC connection
Use same configuration as CoinOS above

Option 4: Strike (Easy Setup, L402 Works)

Why Strike?

Easy API key setup
USD and BTC balance management
Returns preimage via lightning.preImage - L402 works
Built-in currency exchange

Setup:

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

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

Strike BTC Balance

Strike payments use your BTC balance by default. Make sure you have BTC funded (not just USD) for Lightning payments.

Strike Payment Polling

When paying an invoice through Strike, the MCP server polls for payment completion using exponential backoff: 1s, 1s, 1s, 2s, 2s, 2s, then capped at 4s intervals. This reduces unnecessary API calls while still detecting payment completion quickly.

Available Tools (all work):

pay_invoice ✅
check_wallet_balance ✅
get_all_balances ✅
get_btc_price ✅
exchange_currency ✅
send_onchain ✅
access_l402_resource ✅ (preimage returned)

Wallets That Do NOT Support L402

OpenNode

OpenNode is a payment software provider but does not return preimage.

Use for: Direct payments, creating invoices Cannot use for: L402 auto-pay

{
  "env": {
    "OPENNODE_API_KEY": "your-opennode-api-key",
    "OPENNODE_ENVIRONMENT": "production"
  }
}

Wallet Priority

If multiple wallets are configured, they're 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": "nwc"
  }
}

Using Config File for Credentials

Environment variables can be tricky (especially on Windows with special characters). The config file at ~/.lightning-enable/config.json is often easier:

{
  "currency": "USD",
  "tiers": {
    "autoApprove": 0.10,
    "logAndApprove": 1.00,
    "formConfirm": 10.00,
    "urlConfirm": 100.00
  },
  "limits": {
    "maxPerPayment": 500.00,
    "maxPerSession": 100.00
  },
  "session": {
    "requireApprovalForFirstPayment": false,
    "cooldownSeconds": 2
  },
  "wallets": {
    "lndRestHost": "localhost:8080",
    "lndMacaroonHex": "0201036c6e64...",
    "nwcConnectionString": "nostr+walletconnect://...",
    "strikeApiKey": "your-strike-key",
    "openNodeApiKey": "your-opennode-key",
    "priority": "lnd"
  }
}

Complete Examples

LND + Full L402 Support

{
  "mcpServers": {
    "lightning-enable": {
      "command": "dotnet",
      "args": ["tool", "run", "lightning-enable-mcp"],
      "env": {
        "LND_REST_HOST": "localhost:8080",
        "LND_MACAROON_HEX": "0201036c6e6402f801..."
      }
    }
  }
}

L402 tools are available immediately - no license purchase needed.

CoinOS NWC + L402 Support

{
  "mcpServers": {
    "lightning-enable": {
      "command": "dotnet",
      "args": ["tool", "run", "lightning-enable-mcp"],
      "env": {
        "NWC_CONNECTION_STRING": "nostr+walletconnect://abc...?relay=wss://relay.coinos.io&secret=xyz..."
      }
    }
  }
}

L402 tools are available immediately - no license purchase needed.

Strike + Full L402 Support

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

L402 tools are available immediately - no license purchase needed.

Tool Availability

All MCP tools are free. No license purchase or subscription required.

Tool	Availability	Notes
`pay_invoice`	FREE	All wallets
`check_wallet_balance`	FREE	All wallets
`get_payment_history`	FREE	All wallets
`get_budget_status`	FREE	All wallets
`create_invoice`	FREE	All wallets
`check_invoice_status`	FREE	Strike, OpenNode, LND
`get_all_balances`	FREE	All wallets
`get_btc_price`	FREE	Strike only
`exchange_currency`	FREE	Strike only
`send_onchain`	FREE	Strike, LND
`discover_api`	FREE	All wallets — search registry or fetch manifest
`access_l402_resource`	FREE	Requires preimage-compatible wallet
`pay_l402_challenge`	FREE	Requires preimage-compatible wallet

Troubleshooting

"L402 payment succeeded but access failed"

Your wallet doesn't return preimage. Solutions:

Best: Switch to LND (run your own node)
Easy: Switch to NWC with CoinOS or Alby
Also works: Strike (returns preimage)
OpenNode will NOT work for L402

"temporary_channel_failure" or routing errors

Lightning network routing issue. Try:

Wait a few minutes and retry
Ensure your wallet has sufficient balance
Check if the destination node is online

"Wallet not configured"

No wallet credentials found. Set one of:

LND_REST_HOST + LND_MACAROON_HEX
NWC_CONNECTION_STRING
STRIKE_API_KEY
OPENNODE_API_KEY

Or use the config file at ~/.lightning-enable/config.json

NWC "Payment cancelled by user"

Enable auto-pay in your NWC wallet:

CoinOS: Settings → NWC → Edit connection → Enable auto-pay
Alby: Check connection permissions

Also set in config:

{
  "session": {
    "requireApprovalForFirstPayment": false
  }
}

"License required for L402 features"

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

dotnet tool update -g LightningEnable.Mcp

Security Notes

Config file cannot be modified by AI - your spending limits are protected
Macaroons should be kept secret - treat them like passwords
Use read-only macaroons if you only need balance checks
Preimage values are truncated in logs - only the first 8 characters are logged for debugging purposes, preventing full preimage exposure in log files

Next Steps

AI Agent Integration - Full MCP tool reference
AI Spending Security - Budget configuration
How It Works - L402 protocol details

L402 Compatibility Matrix​

Recommended Setup for L402​

Option 1: LND (Best for Guaranteed L402)​

Option 2: NWC with CoinOS (Free, Easy)​

Option 3: NWC with Alby Hub (Self-Custody)​

Option 4: Strike (Easy Setup, L402 Works)​

Wallets That Do NOT Support L402​

OpenNode​

Wallet Priority​

Using Config File for Credentials​

Complete Examples​

LND + Full L402 Support​

CoinOS NWC + L402 Support​

Strike + Full L402 Support​

Tool Availability​

Troubleshooting​

"L402 payment succeeded but access failed"​

"temporary_channel_failure" or routing errors​

"Wallet not configured"​

NWC "Payment cancelled by user"​

"License required for L402 features"​

Security Notes​

Next Steps​

L402 Compatibility Matrix

Recommended Setup for L402

Option 1: LND (Best for Guaranteed L402)

Option 2: NWC with CoinOS (Free, Easy)

Option 3: NWC with Alby Hub (Self-Custody)

Option 4: Strike (Easy Setup, L402 Works)

Wallets That Do NOT Support L402

OpenNode

Wallet Priority

Using Config File for Credentials

Complete Examples

LND + Full L402 Support

CoinOS NWC + L402 Support

Strike + Full L402 Support

Tool Availability

Troubleshooting

"L402 payment succeeded but access failed"

"temporary_channel_failure" or routing errors

"Wallet not configured"

NWC "Payment cancelled by user"

"License required for L402 features"

Security Notes

Next Steps