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 (Alby Hub)	✅ Yes	✅ Yes	Self-custody	Self-hosted + L402
Strike	❌ No	❌ No	Custodial	USD users, direct payments
OpenNode	❌ No	❌ No	Custodial	Direct payments only

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

Setup:

1. Sign up at https://coinos.io
2. Go to Settings → NWC
3. Create a new NWC connection
4. Enable auto-pay for the connection (important for L402!)
5. 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:

1. Deploy Alby Hub: https://albyhub.com
2. Connect to your Lightning node
3. Create NWC connection
4. Use same configuration as CoinOS above

---

Wallets That Do NOT Support L402

Strike

Strike is great for USD management but does not return preimage.

Use for: Direct payments, USD/BTC exchange, balance checks Cannot use for: L402 auto-pay

{
  "env": {
    "STRIKE_API_KEY": "your-strike-api-key"
  }
}

Available Tools:

• pay_invoice ✅
• check_wallet_balance ✅
• get_all_balances ✅
• get_btc_price ✅
• exchange_currency ✅
• send_onchain ✅
• access_l402_resource ❌ (no preimage)

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):

1. LND (if LND_REST_HOST + LND_MACAROON_HEX are set)
2. NWC (if NWC_CONNECTION_STRING is set)
3. Strike (if STRIKE_API_KEY is set)
4. 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..."
      }
    }
  }
}

Then run unlock_l402_features in Claude to enable L402 (one-time 6,000 sats).

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

Then run unlock_l402_features in Claude to enable L402 (one-time 6,000 sats).

Strike for Direct Payments (No L402)

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

---

License Requirements

Tool	Tier	License Required
pay_invoice	FREE	No
check_wallet_balance	FREE	No
get_payment_history	FREE	No
get_budget_status	FREE	No
create_invoice	FREE	No
check_invoice_status	FREE	No
get_all_balances	FREE	No
get_btc_price	FREE (Strike)	No
exchange_currency	FREE (Strike)	No
send_onchain	FREE (Strike/LND)	No
unlock_l402_features	FREE	No
check_l402_license	FREE	No
access_l402_resource	L402 License	Yes (one-time 6,000 sats)
pay_l402_challenge	L402 License	Yes (one-time 6,000 sats)

---

Troubleshooting

"L402 payment succeeded but access failed"

Your wallet doesn't return preimage. Solutions:

1. Best: Switch to LND (run your own node)
2. Easy: Switch to NWC with CoinOS or Alby
3. Strike and 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"

L402 features require a one-time license purchase:

1. Use the unlock_l402_features tool in Claude
2. Pay 6,000 sats (~$6) via Lightning - valid forever
3. License is bound to your wallet pubkey and stored locally

Already Have a License?

If you've purchased before, just run unlock_l402_features again. It will detect your existing license and restore it without charging you.

---

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

---

Next Steps

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