402-mcp

Nostr: npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2

L402 client MCP that gives AI agents economic agency. Discover, pay for, and consume Lightning and ecash payment-gated APIs within limits you set: no human registration, no API keys, no middlemen.

• Discover paid APIs on Nostr — no URLs needed upfront
• Auto-pay with Lightning (NWC), Cashu ecash, LNURLcash bearer notes, or human QR fallback
• Credentials cached and encrypted at rest (AES-256-GCM)
• Works with any L402 server — toll-booth, Aperture, or any future implementation

Quick start

1. Install

npx 402-mcp

2. Connect to Claude Code

claude mcp add 402-mcp -- npx 402-mcp

3. Try it

Ask Claude: "Search for paid joke APIs using l402-search" — no wallet needed, just discovery.

Ready to make paid calls? See the full quickstart guide to set up a wallet and watch your agent pay for its first API call.

Requires Node.js 22 or newer.

How it works

graph LR
    A["1. l402-config()"] --> B["2. l402-discover(url)"]
    B --> C["3. Agent reasons<br/>about pricing"]
    C --> D["4. l402-buy-credits()<br/>or l402-fetch()"]
    D --> E["5. l402-fetch(url)<br/>with credentials"]
    E --> F["6. Data returned<br/>+ balance cached"]

Example session:

Agent: "I need routing data from routing.example.com"

1. l402-config()
   -> nwcConfigured: true, maxAutoPaySats: 1000

2. l402-discover("https://routing.example.com/api/route")
   -> 10 sats/request, toll-booth detected, tiers available

3. Agent reasons: "I need ~20 requests. The 500-sat tier
   gives 555 credits. Better value."

4. l402-buy-credits(url, amountSats=500)
   -> Paid 500 sats, received 555 credits

5. l402-fetch("https://routing.example.com/api/route?from=...&to=...")
   -> 200 OK, route data, 545 credits remaining

For detailed architecture and payment flow diagrams, see docs/architecture.md.

Configuration

Transport selection and fallback

When a kind 31402 event advertises multiple URLs (one per transport), 402-mcp selects the best one based on your configuration:

1. Preference first: URLs are tried in TRANSPORT_PREFERENCE order, onion,hns,https,http by default. Use onion, hns, https and http as the values. A URL counts as hns when its TLD is .hns. One whose TLD is merely unfamiliar (.pub, .fyi) is more likely an ICANN name, so it is tried just after https.
2. Capability filter: .onion URLs are skipped unless TOR_PROXY or SOCKS_PROXY is set, so without a proxy the default order starts at HNS and clearnet.
3. Availability fallback: if a transport is unreachable (connection refused, timeout), the next URL is tried.

Services can announce multiple endpoints for the same service (same pricing, same macaroon key) on different transports. This is purely for censorship resistance; you do not need to re-authenticate when switching transports. To reach Tor or HNS endpoints you must configure the corresponding proxy/gateway env vars above.

Tor and SOCKS5

• TOR_PROXY sends .onion requests through the proxy. Everything else connects directly.
• SOCKS_PROXY sends every request to a paid API through the proxy, including redirects. Host names are resolved by the proxy, never by this machine, so a Tor proxy hides both your IP and the names you look up. The SSRF guard still refuses private IP literals and local names such as localhost; it cannot see what a name resolves to on the far side, which Tor exits refuse for private ranges anyway.

Neither setting covers wallet or discovery traffic: NWC relays, Cashu and LNURLcash mints, and the Nostr relays l402-search queries still connect directly. Handshake lookups are switched off under SOCKS_PROXY, because the DNS-over-HTTPS query would go around the proxy.

SOCKS5 support comes from undici's Socks5ProxyAgent, which Node marks experimental; expect one ExperimentalWarning on stderr when a proxy is configured.

Tools

Core L402 (any server)

Widgets (MCP Apps hosts)

l402-fetch-preview also has a payment confirmation widget.

toll-booth extensions

Payment methods

Four payer methods, tried in priority order:

1. NWC (Nostr Wallet Connect) — fully autonomous; pays from your connected wallet
2. Cashu — fully autonomous; melts ecash tokens to pay invoices
3. LNURLcash: fully autonomous; melts LUD-25 bearer notes to pay invoices
4. Human-in-the-loop — presents QR code, polls for settlement

The agent can override the method per-call, or you can configure only the methods you want.

l402-fetch handles four HTTP 402 challenge variants, plus an experimental x402 format:

An LNURLcash challenge is tried first. A bearer note is already money in hand, so paying one costs no Lightning hop and no swap at the mint: the note goes straight into the retry header and the server settles it. When the price does not match a note exactly, one is split at the mint and the change stays in the store. If no note covers it, the other rails are tried as usual.

Spending limits