{
"markdown": "# 402-mcp\n\n**Nostr:** [`npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2`](https://njump.me/npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2)\n\n[](./LICENSE)\n[](https://www.typescriptlang.org/)\n[](https://nodejs.org/)\n[](./docs/security.md)\n[](https://primal.net/p/npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2)\n[](https://github.com/sponsors/TheCryptoDonkey)\n\nL402 + x402 client MCP that gives AI agents economic agency. Discover, pay for, and consume any payment-gated API — no human registration, no API keys, no middlemen.\n\n- **Discover** paid APIs on Nostr — no URLs needed upfront\n- **Auto-pay** with Lightning (NWC), Cashu ecash, LNURLcash bearer notes, or human QR fallback\n- **Credentials cached and encrypted** at rest (AES-256-GCM)\n- **Works with any L402 server** — toll-booth, Aperture, or any future implementation\n\n## Quick start\n\n**1. Install**\n\n```bash\nnpx 402-mcp\n```\n\n**2. Connect to Claude Code**\n\n```bash\nclaude mcp add 402-mcp -- npx 402-mcp\n```\n\n**3. Try it**\n\nAsk Claude: *\"Search for paid joke APIs using l402-search\"* — no wallet needed, just discovery.\n\nReady to make paid calls? See the [full quickstart guide](./docs/quickstart.md) to set up a wallet and watch your agent pay for its first API call.\n\nRequires Node.js 22 or newer.\n\n## How it works\n\n```mermaid\ngraph LR\n A[\"1. l402-config()\"] --> B[\"2. l402-discover(url)\"]\n B --> C[\"3. Agent reasons
about pricing\"]\n C --> D[\"4. l402-buy-credits()
or l402-fetch()\"]\n D --> E[\"5. l402-fetch(url)
with credentials\"]\n E --> F[\"6. Data returned
+ balance cached\"]\n```\n\n**Example session:**\n\n```\nAgent: \"I need routing data from routing.trotters.cc\"\n\n1. l402-config()\n -> nwcConfigured: true, maxAutoPaySats: 1000\n\n2. l402-discover(\"https://routing.trotters.cc/api/route\")\n -> 10 sats/request, toll-booth detected, tiers available\n\n3. Agent reasons: \"I need ~20 requests. The 500-sat tier\n gives 555 credits. Better value.\"\n\n4. l402-buy-credits(url, amountSats=500)\n -> Paid 500 sats, received 555 credits\n\n5. l402-fetch(\"https://routing.trotters.cc/api/route?from=...&to=...\")\n -> 200 OK, route data, 545 credits remaining\n```\n\nFor detailed architecture and payment flow diagrams, see [docs/architecture.md](./docs/architecture.md).\n\n## Configuration\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `NWC_URI_FILE` | - | Path to a private `0600` file containing the NWC bearer URI |\n| `CASHU_TOKENS` | - | Path to Cashu token store file |\n| `LNURLCASH_NOTES` | - | Path to LNURLcash bearer note store file (LUD-25) |\n| `MAX_AUTO_PAY_SATS` | 1000 | Safety cap; payments above this require human confirmation |\n| `CREDENTIAL_STORE` | `~/.402-mcp/credentials.json` | Persistent macaroon/credential storage |\n| `TRANSPORT` | `stdio` | Transport mode: `stdio` or `http` |\n| `PORT` | 3402 | HTTP server port (when `TRANSPORT=http`) |\n| `TRANSPORT_PREFERENCE` | `onion,hns,https,http` | Preferred transport order for multi-URL services (comma-separated) |\n| `TOR_PROXY` | - | SOCKS5 proxy for `.onion` addresses (e.g. `socks5h://127.0.0.1:9050`) |\n| `SOCKS_PROXY` | - | Generic SOCKS5 proxy for all requests when set |\n| `HNS_GATEWAY_URL` | - | HTTP gateway for Handshake (`.hns`) domains (e.g. `https://hns.to`) |\n\n### Transport selection and fallback\n\nWhen a kind 31402 event advertises multiple URLs (one per transport), 402-mcp selects the best one based on your configuration:\n\n1. **Preference first** — if `TRANSPORT_PREFERENCE=tor` and a `.onion` URL is available, it is tried first.\n2. **Availability fallback** — if the preferred transport is unreachable (proxy not configured, timeout), the client falls back to the next URL in the list.\n3. **Clearnet default** — if no preference is set, clearnet URLs are tried before `.onion` or HNS entries.\n\nServices 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.\n\n## Tools\n\n### Core L402 (any server)\n\n| Tool | Description |\n|------|-------------|\n| `l402-config` | Introspect payment capabilities (wallets, limits, credential count) |\n| `l402-discover` | Probe an endpoint to discover pricing without paying |\n| `l402-fetch` | HTTP request with L402 support; auto-pays if within budget |\n| `l402-pay` | Pay a specific invoice (NWC, Cashu, or human-in-the-loop) |\n| `l402-credentials` | List stored credentials and cached balances |\n| `l402-balance` | Check cached credit balance for a server |\n| `l402-search` | Discover L402 services on Nostr relays (kind 31402 announcements) |\n| `l402-store-token` | Store an L402 token obtained from a payment page |\n\n### toll-booth extensions\n\n| Tool | Description |\n|------|-------------|\n| `l402-buy-credits` | Browse and purchase volume discount tiers |\n| `l402-redeem-cashu` | Redeem Cashu tokens directly (avoids Lightning round-trip) |\n\n## Payment methods\n\nFour payer methods, tried in priority order:\n\n1. **NWC** (Nostr Wallet Connect) — fully autonomous; pays from your connected wallet\n2. **Cashu** — fully autonomous; melts ecash tokens to pay invoices\n3. **LNURLcash**: fully autonomous; melts LUD-25 bearer notes to pay invoices\n4. **Human-in-the-loop** — presents QR code, polls for settlement\n\nThe agent can override the method per-call, or you can configure only the methods you want.\n\n`l402-fetch` handles five HTTP 402 challenge variants transparently:\n\n| Protocol | Challenge header | Payment |\n|----------|-----------------|---------|\n| **L402** | `WWW-Authenticate: L402` | Lightning invoice via wallet stack |\n| **IETF Payment** (`draft-ryan-httpauth-payment-01`) | `WWW-Authenticate: Payment` | Lightning invoice via wallet stack |\n| **LNURLcash** (LUD-25) | `X-LNURLcash: lnurlcashreq1…` | Bearer note handed over directly (requires a note store) |\n| **xCashu** (NUT-18) | `X-Cashu: creqA…` | Ecash token sent directly (requires Cashu wallet) |\n| **x402** | `X-Payment-Required: x402` | On-chain EVM transfer; surfaced to human with EIP-681 deeplink |\n\nAn LNURLcash challenge is tried first. A bearer note is already money in hand,\nso paying one costs no Lightning hop and no swap at the mint: the note goes\nstraight into the retry header and the server settles it. When the price does\nnot match a note exactly, one is split at the mint and the change stays in the\nstore. If no note covers it, the other rails are tried as usual.\n\n## Safety\n\n`MAX_AUTO_PAY_SATS` caps any single autonomous payment. Above this limit, the agent must ask the human for approval. The agent can read this limit via `l402-config` and factor it into purchasing decisions.\n\n## Privacy\n\n402-mcp stores credentials locally on your machine only (`~/.402-mcp/credentials.json`, encrypted at rest). No data is sent to any third party. No accounts, no tracking, no analytics. Payments use Lightning or Cashu — pseudonymous by design.\n\n## Ecosystem\n\nBrowse live L402 services at [402.pub](https://402.pub) — the decentralised marketplace for payment-gated APIs.\n\n| Project | Role |\n|---------|------|\n| [toll-booth](https://github.com/forgesworn/toll-booth) | Payment-backend agnostic HTTP 402 middleware |\n| [satgate](https://github.com/forgesworn/satgate) | Pay-per-token AI inference proxy (built on toll-booth) |\n| **[402-mcp](https://github.com/forgesworn/402-mcp)** | **MCP client — AI agents discover, pay, and consume L402 + x402 APIs** |\n| [402-announce](https://github.com/forgesworn/402-announce) | Publish L402 services on Nostr for decentralised discovery |\n\n402-mcp is the **wallet-provider agnostic** alternative to Lightning Labs' [lightning-agent-tools](https://github.com/lightninglabs/lightning-agent-tools) and Coinbase's x402 — no Lightning node required, multiple wallets, encrypted credentials.\n\n\nFull comparison
\n\n| | 402-mcp | Lightning Labs agent tools |\n|---|---|---|\n| **Payer methods** | NWC + Cashu + human fallback | Lightning only |\n| **Node required?** | No — connects to any NWC wallet | Yes — runs LND |\n| **Server compatibility** | Any L402 server | Aperture-focused |\n| **Spend safety** | Per-payment cap + rolling 60s window | Per-call max-cost |\n| **Credential storage** | Encrypted at rest (AES-256-GCM) | File permissions |\n| **Privacy** | No PII, SSRF protection, error sanitisation | Standard |\n\nUse Lightning Labs' tools if you want agents that **run their own Lightning node**. Use 402-mcp if you want agents that **pay from any wallet without infrastructure**.\n\n \n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and guidelines.\n\n---\n\nBuilt by [@forgesworn](https://github.com/forgesworn).\n\n- Lightning tips: `profusemeat89@walletofsatoshi.com`\n- Nostr: `npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2`\n\n---\n\n## Part of the ForgeSworn Toolkit\n\n[ForgeSworn](https://forgesworn.dev) builds open-source cryptographic identity, payments, and coordination tools for Nostr.\n\n| Library | What it does |\n|---------|-------------|\n| [nsec-tree](https://github.com/forgesworn/nsec-tree) | Deterministic sub-identity derivation |\n| [ring-sig](https://github.com/forgesworn/ring-sig) | SAG/LSAG ring signatures on secp256k1 |\n| [range-proof](https://github.com/forgesworn/range-proof) | Pedersen commitment range proofs |\n| [canary-kit](https://github.com/forgesworn/canary-kit) | Coercion-resistant spoken verification |\n| [spoken-token](https://github.com/forgesworn/spoken-token) | Human-speakable verification tokens |\n| [toll-booth](https://github.com/forgesworn/toll-booth) | L402 payment middleware |\n| [geohash-kit](https://github.com/forgesworn/geohash-kit) | Geohash toolkit with polygon coverage |\n| [nostr-attestations](https://github.com/forgesworn/nostr-attestations) | NIP-VA verifiable attestations |\n| [dominion](https://github.com/forgesworn/dominion) | Epoch-based encrypted access control |\n| [nostr-veil](https://github.com/forgesworn/nostr-veil) | Privacy-preserving Web of Trust |\n\n## Licence\n\n[MIT](LICENSE)\n",
"bytes": 10601,
"sha": "4c2dfddce92d799790497d6aee97f53fae8ee0371afcf71f9a890ffbb89a02b4",
"repo_slug": "forgesworn/402-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_dev_forgesworn_402_mcp_c767cd62/readme"
}