Skip to main content

Run L402 Anywhere: Hermes + NWC

Give an AI agent a tiny Lightning wallet and the Lightning Enable MCP server, and it can pay L402-protected APIs anywhere on the internet — no card, no account, no hosted infrastructure. With Hermes as the host, the same setup reaches you on your phone over Telegram, Signal, WhatsApp, and other chat apps.

Why this setup

Most "agent pays for things" demos have a deployment problem: the agent needs a wallet and a host before it can pay for anything. Hermes runs the MCP locally and bridges to your phone, so you get mobile agent payments without a hosted MCP to run or trust. Your wallet stays yours; Lightning Enable never holds funds.

The beginner stack​

LayerPickWhy
Agent hostHermesLocal MCP client with Telegram/Signal/WhatsApp gateways — mobile access, no hosted layer.
Payment toolsLightning Enable MCPGives the agent access_l402_resource, pay_l402_challenge, wallet + budget tools.
WalletCoinOS via NWCBrowser-based, beginner-friendly, and returns the Lightning preimage that L402 requires.
BudgetA small funded walletThe wallet balance is the hard leash; software limits are defense-in-depth.
Wallet must return a preimage

L402 verification needs the payment preimage. NWC wallets (CoinOS, Alby Hub, CLINK), LND, and Strike return it. OpenNode does not and can't be used to pay L402 resources.

Prerequisites​

  • macOS, Linux, Windows, or WSL
  • The .NET 9 runtime (for the .NET MCP tool) or Python 3.10+ (for the Python one)
  • Hermes installed
  • A CoinOS account with a small amount of sats (1,000–10,000 is plenty to start)

Step 1 — Install Hermes​

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Run the setup wizard (pick your model/provider), then confirm it's healthy:

hermes setup
hermes doctor

Step 2 — Install the Lightning Enable MCP​

# .NET (recommended)
dotnet tool install -g LightningEnable.Mcp

# Or Python — for an NWC wallet, install the optional extra:
pip install "lightning-enable-mcp[nwc]"

Confirm the command is on your PATH:

command -v lightning-enable-mcp
NWC on Python

pip install lightning-enable-mcp works on every platform, but NWC wallets need the extra: pip install "lightning-enable-mcp[nwc]". The .NET tool needs no extra.

Step 3 — Create a CoinOS NWC connection​

  1. Go to coinos.io and create or log in to an account.
  2. Fund it with a small amount (e.g. 1,000–10,000 sats).
  3. Open Nostr Wallet Connect (NWC) in settings and create a new connection for your agent.
  4. Grant the permissions an L402-paying agent needs:
    • pay_invoice
    • get_balance
    • (optional) make_invoice if the agent should also receive payments
  5. If CoinOS offers a per-connection spend limit, set one.
  6. Copy the nostr+walletconnect://… connection string.
Treat the NWC string like a wallet password

Anyone with the connection string can spend within its permissions and limits. Keep it out of chat, screenshots, and shared configs.

Step 4 — Configure the wallet + budget​

Create ~/.lightning-enable/config.json:

{
  "currency": "USD",
  "tiers": {
    "autoApprove": 0.10,
    "logAndApprove": 1.00,
    "formConfirm": 10.00
  },
  "limits": {
    "maxPerPayment": 5.00,
    "maxPerSession": 20.00
  },
  "wallets": {
    "nwcConnectionString": "nostr+walletconnect://PASTE_YOUR_COINOS_STRING_HERE",
    "priority": "nwc"
  }
}

Lock the file down (NWC strings are sensitive):

chmod 600 ~/.lightning-enable/config.json
ThresholdBehavior
Under $0.10Auto-pay silently
$0.10 – $1.00Pay and log
$1.00 – $5.00Confirmation required (server prints a code to its console for you)
Over $5/payment or $20/sessionDenied
Config file vs. environment variable

NWC strings contain characters that are easy to break in shell profiles and GUI launchers, so the config file is the reliable path. (If you prefer env vars, the equivalents are NWC_CONNECTION_STRING and WALLET_PRIORITY=nwc.)

Step 5 — Add the MCP to Hermes​

Because the wallet lives in the config file, adding the server is one line:

hermes mcp add lightning-enable --command lightning-enable-mcp
hermes mcp test lightning-enable

Expected:

✓ Connected
✓ Tools discovered: 15   (23 with a Lightning Enable API key)

Step 6 — Verify for 1 sat​

This is the moment of truth — a real end-to-end L402 payment against the public 1-sat test endpoint. It proves your wallet, the preimage flow, and L402 all work, for one satoshi.

First, check the agent can see the wallet:

Check the Lightning Enable wallet balance.

Then pay the test endpoint:

Access this L402 resource: https://api.lightningenable.com/l402/test/ping

What happens under the hood:

  1. The agent requests the URL and gets 402 Payment Required with a 1-sat Lightning invoice + macaroon.
  2. The MCP pays the invoice through your CoinOS NWC wallet.
  3. CoinOS returns the preimage.
  4. The MCP retries with Authorization: L402 <macaroon>:<preimage>.
  5. The endpoint returns 200 OK.

If you get the 200, your whole stack works. (Prefer the command line? The same endpoint responds to curl https://api.lightningenable.com/l402/test/ping with the 402 challenge so you can inspect the invoice before paying.)

Step 7 — Take it to your phone​

Point Hermes' messaging gateway at Telegram (or Signal, WhatsApp, etc.) and talk to your agent from anywhere:

hermes gateway setup
hermes gateway run

Now you can message your agent "pay the 1-sat test endpoint" or "buy the premium forecast from this API" from your phone, and it pays over Lightning from the bounded wallet — no hosted MCP required.

What the agent can do next​

Once it can pay L402, the same agent handles real tasks. Pair this setup with the open-source pay-l402-anywhere skill (it works in Hermes, Claude Code, and Cursor unmodified) — discover a paid API, check what you can afford, confirm, pay, and report the sats spent.

Key consumer tools the MCP exposes:

  • access_l402_resource — fetch a URL and auto-pay the L402 challenge
  • pay_l402_challenge — pay a challenge you already hold
  • discover_api — search the L402 registry or fetch an API's manifest
  • check_wallet_balance / get_budget_status — know your funds and limits
  • confirm_payment — approve an over-threshold payment with the console code

Security posture​

The safe design isn't "trust the agent" — it's bound what it can spend:

  1. Use a dedicated small wallet for the agent.
  2. Fund only what it's allowed to spend — the balance is the real ceiling.
  3. Set a CoinOS per-connection limit if available.
  4. Keep the MCP budget caps as defense-in-depth.
  5. Keep ~/.lightning-enable/config.json at 600.
  6. Rotate the NWC connection if it leaks or you're done with it.

A 5,000-sat wallet cannot spend 50,000 sats, no matter what any prompt says.

Next steps​