402-mcp 4.2.2 → 4.3.0

package/llms-full.txt

@@ -4,7 +4,7 @@
 
 ## What is 402-mcp?
 
-402-mcp is an MCP (Model Context Protocol) server that gives AI agents economic agency — the ability to discover, pay for, and consume any L402 or x402 payment-gated API without human registration, API keys, or middlemen.
+402-mcp is an MCP (Model Context Protocol) server that gives AI agents economic agency: the ability to discover, pay for, and consume L402 and other Lightning or ecash payment-gated APIs without human registration, API keys, or middlemen.
 
 It implements the client side of the L402 protocol: when an API responds with HTTP 402 (Payment Required), 402-mcp automatically parses the challenge, pays the Lightning invoice, stores the credential, and retries the request — all within a single tool call from the agent's perspective.
 
@@ -80,7 +80,7 @@ src/
     bolt11.ts              # Decode BOLT11 invoices (amount extraction)
     challenge-cache.ts     # Cache parsed challenges for l402-pay
   x402/
-    parse.ts               # Detect X-Payment-Required: x402 header; parse EVM challenge
+    parse.ts               # Experimental custom x402 format: X-Payment-Required: x402 header, EVM challenge body
     payment.ts             # Format payment request with EIP-681 deeplink for human payment
   xcashu/
     parse.ts               # Detect X-Cashu header; parse NUT-18 payment request
@@ -151,18 +151,23 @@ tests/                     # Mirrors src/ structure
 
 **Parameters:**
 - `url` (string, required) — the endpoint to fetch
+- `urls` (string[], optional): all transport URLs from `l402-search`, tried in preference order
+- `pubkey` (string, optional): service pubkey from `l402-search`, used to share a credential across the service's transports
 - `method` (string, optional) — HTTP method (default: GET)
 - `headers` (object, optional) — additional headers
 - `body` (string, optional) — request body
-- `paymentMethod` (string, optional) — force a specific payer method
+- `autoPay` (boolean, optional, default false): pay a challenge within the limits
+- `maxCostSats` (number, optional): most this call may pay; lowers `MAX_AUTO_PAY_SATS`, never raises it
+- `txHash` (string, optional): transaction hash for the experimental x402 format
 
 **Behaviour:**
-1. Checks for existing credential for the origin
+1. Uses a stored credential only if it is bound to every origin the request may reach
 2. Makes the HTTP request (with credential if available)
-3. If 402 received: parses challenge, checks amount against `MAX_AUTO_PAY_SATS` and rolling spend cap
-4. If within budget: pays invoice, stores credential, retries request
-5. If over budget: returns the price and asks for human approval
-6. Returns response body, status, headers, and remaining credit balance
+3. If 402 received and `autoPay` is set: refuses if an earlier payment to the service is unresolved, then checks the price against `MAX_AUTO_PAY_SATS`, `maxCostSats` and the rolling spend caps
+4. If within the limits: pays, stores the credential bound to the request's origins, retries
+5. Otherwise: returns the price and `paymentHash` unpaid, and caches the challenge for `l402-pay`
+6. A payment whose outcome is unknown is reported as an error and recorded for `l402-reconcile`; it never falls through to another rail
+7. Returns response body (in UNTRUSTED CONTENT markers), status, headers, and remaining credit balance
 
 **When to use:** Primary tool for consuming L402 APIs. Handles the entire flow.
 
@@ -170,19 +175,44 @@ tests/                     # Mirrors src/ structure
 
 ### l402-pay
 
-**Purpose:** Pay a specific Lightning invoice.
+**Purpose:** Pay a challenge that `l402-fetch` or `l402-discover` returned.
 
 **Parameters:**
-- `invoice` (string, required) — BOLT11 invoice to pay
-- `paymentMethod` (string, optional) — force a specific payer method
-- `challengeId` (string, optional) — ID from a previous `l402-discover` to associate the payment
+- `paymentHash` (string): payment hash of the cached challenge
+- `invoice`, `macaroon` (string, optional): only for an invoice that did not come from a challenge; the human must approve it through MCP elicitation, or it is refused
+- `method` (string, optional): `nwc`, `cashu`, `lnurlcash` or `human`
 
 **Returns:**
-- `paid` (boolean)
-- `preimage` (string) — payment proof
+- `paid` (boolean) and `paymentState` (`paid`, `failed`, `unknown` or `blocked`)
+- `credentialsStored` (boolean)
 - `method` (string) — which wallet paid
 
-**When to use:** When you have an invoice from a non-L402 source, or want explicit control.
+For human wallets with a toll-booth payment page, polls for settlement for up to 120 seconds.
+
+---
+
+### l402-reconcile
+
+**Purpose:** Resolve payments whose outcome is unknown.
+
+**Parameters:**
+- `paymentHash` (string, optional): omit to list unresolved payments
+- `preimage` (string, optional): settles the payment if it hashes to `paymentHash`
+- `abandon` (boolean, optional): stop tracking it; requires the human's approval through MCP elicitation
+
+**Behaviour:** Asks the wallet that made the payment (NWC `lookup_invoice`, the Cashu mint for a reserved melt, or the LNURLcash verify URL). Settled with a matching preimage clears it and stores the L402 credential; definitely failed clears it and releases reserved Cashu proofs. While any is unresolved for a service, auto-pay to it is paused.
+
+---
+
+### l402-fetch-preview
+
+**Purpose:** Show what an endpoint costs without paying. Its dependencies include no wallet or spend tracker, so it cannot spend. Widget hosts render the result as a payment confirmation dialog.
+
+---
+
+### Widget tools
+
+`l402-service-directory` (searchable service directory) and `l402-wallet-dashboard` (wallet status, limits, credentials) are MCP Apps widgets for hosts that support them.
 
 ---
 
@@ -235,6 +265,8 @@ tests/                     # Mirrors src/ structure
 - `topics` — topic tags
 - `capabilities` — array of `{ name, description }`
 
+Names, descriptions and capability text are wrapped in UNTRUSTED CONTENT markers. Topic and payment-method filters are sent to the relays; the query text is matched locally.
+
 **When to use:** When the agent needs a paid API but doesn't know the URL. Searches the decentralised Nostr network for kind 31402 service announcements. Services may advertise multiple transport URLs (clearnet, .onion, Handshake); pass the `urls` array and `pubkey` to `l402-fetch` for automatic transport selection and fallback.
 
 ---
@@ -246,7 +278,7 @@ tests/                     # Mirrors src/ structure
 **Parameters:**
 - `url` (string, required) — toll-booth server URL
 - `amountSats` (number, optional) — specific tier to purchase
-- `paymentMethod` (string, optional) — force a specific payer method
+- `method` (string, optional): `nwc`, `cashu` or `human`
 
 **Behaviour:** Fetches available tiers, purchases the specified tier, stores the credential with the credit balance.
 
@@ -282,7 +314,7 @@ The L402 protocol is an extension of HTTP 402 (Payment Required):
 
 ## Supported 402 Protocol Variants
 
-`l402-fetch` detects and handles five HTTP 402 challenge variants. Detection order in source: LNURLcash, x402, IETF Payment, L402, with xCashu tried immediately after LNURLcash.
+`l402-fetch` detects and handles four HTTP 402 challenge variants, plus an experimental x402 format. Detection order in source: LNURLcash, x402, IETF Payment, L402, with xCashu tried immediately after LNURLcash.
 
 | Protocol | Detection | Credential sent | Autonomous? |
 |----------|-----------|----------------|-------------|
@@ -290,7 +322,7 @@ The L402 protocol is an extension of HTTP 402 (Payment Required):
 | **IETF Payment** (`draft-ryan-httpauth-payment-01`) | `WWW-Authenticate: Payment id=… method=lightning …` | `Authorization: Payment <base64url-json>` | Yes (NWC or Cashu) |
 | **LNURLcash** (LUD-25) | `X-LNURLcash: lnurlcashreq1<base64url>` | `X-LNURLcash: <bearer note URL>` | Yes (note store only) |
 | **xCashu** (NUT-18) | `X-Cashu: creqA<base64url>` | `X-Cashu: <cashuB-token>` | Yes (Cashu wallet only) |
-| **x402** | `X-Payment-Required: x402` + JSON body | Human presents EIP-681 deeplink | No — on-chain EVM; surfaced to human |
+| **x402** (experimental, custom format) | `X-Payment-Required: x402` + JSON body | `X-Payment: <tx hash>` after the human pays | No: payment details shown to the human. Not the x402 specification, whose servers send a base64 `PAYMENT-REQUIRED` header |
 
 LNURLcash is tried before the others because a bearer note is already money in hand: the note URL goes straight into the retry header and the server settles it by rotating the note. A note worth exactly the price is used as it is; otherwise one is split at the mint and the change stays in the store. The chosen note is held pending until the outcome is known, so nothing else can spend it in the meantime. xCashu uses coin selection via `wallet.send(amount, proofs, { includeFees: true })` and restores change proofs to the token store. IETF Payment decodes the base64url charge request to extract the BOLT11 invoice, then pays it through the normal wallet stack and wraps the preimage in a JSON credential.
 
@@ -305,20 +337,17 @@ Wallets are tried in order: NWC → Cashu → LNURLcash → Human. The first wal
 | LNURLcash | Fully autonomous | `LNURLCASH_NOTES` file with LUD-25 bearer notes | ~2-6 seconds |
 | Human | Requires human | None — always available as fallback | Minutes |
 
-The agent can force a specific method per-call using the `paymentMethod` parameter.
+The agent can force a specific method on `l402-pay` and `l402-buy-credits` with the `method` parameter.
 
 ## Safety and Spend Limits
 
 ### Per-payment cap
 
-`MAX_AUTO_PAY_SATS` (default: 1000) caps any single payment. If an invoice exceeds this:
-- The agent is told the price and asked to seek human approval
-- The human wallet (QR code) is used for the actual payment
-- The credential is stored normally after payment
+`MAX_AUTO_PAY_SATS` (default: 1000) caps any single payment. A dearer challenge is not paid from any configured wallet, and the human wallet does not take over: the price and invoice go back to the agent, and whether it asks the human is up to the agent. `maxCostSats` on `l402-fetch` lowers the cap for one call. `0` disables auto-pay.
 
 ### Rolling spend cap
 
-`MAX_SPEND_PER_MINUTE_SATS` (default: 10000) caps total spend in any 60-second window. This prevents:
+`MAX_SPEND_PER_MINUTE_SATS` (default: 10000) caps total spend in any 60-second window, and `MAX_SPEND_PER_DAY_SATS` (default: 5000) in any 24 hours; the daily window is kept in `~/.402-mcp/spend-ledger.json` so a restart does not reset it. `0` in either blocks auto-pay. The budget set on the NWC connection is the real hard limit. These prevent:
 - Rapid successive small payments exceeding a total budget
 - Runaway loops where the agent keeps buying credits
 - Both caps use atomic `tryRecord()` to prevent TOCTOU race conditions
@@ -333,7 +362,7 @@ All outbound HTTP requests pass through an SSRF guard:
 ### Credential Security
 
 - Credentials encrypted with AES-256-GCM
-- Encryption key stored in OS keychain (macOS Keychain, Windows Credential Vault, Linux Secret Service) when available
+- Encryption key stored in the OS keychain when available (macOS through the `security` command-line tool; elsewhere through the optional `keytar` module)
 - Falls back to file-based key at `~/.402-mcp/encryption.key` with a console warning
 - NWC capability and response events authenticated with NIP-44 v2 and signatures
 - Returned NWC preimages verified against the challenged BOLT11 payment hash
@@ -352,13 +381,16 @@ npx 402-mcp
 
 ### HTTP
 
-StreamableHTTP transport for network access. Useful for remote agents, multi-client setups, or deployment behind a reverse proxy.
+StreamableHTTP transport, stateless. Prefer stdio wherever the client can start a local process: the HTTP transport can spend from the wallet.
 
 ```bash
-TRANSPORT=http PORT=3402 npx 402-mcp
+openssl rand -hex 32 > ~/.402-mcp/http.token && chmod 600 ~/.402-mcp/http.token
+TRANSPORT=http HTTP_AUTH_TOKEN_FILE=~/.402-mcp/http.token PORT=3402 npx 402-mcp
 ```
 
 HTTP transport includes:
+- Bearer token required on every request (`HTTP_AUTH_TOKEN_FILE`, a private 0600 file); the server refuses to start in http mode without one
+- DNS rebinding protection: only requests whose `Host` header is a loopback name with the port, the bound address, or listed in `HTTP_ALLOWED_HOSTS` are answered
 - Rate limiting: 100 requests per 60 seconds per IP
 - Security headers: CSP, X-Frame-Options, X-Content-Type-Options, Cache-Control
 - Loopback-only binding by default (`BIND_ADDRESS=127.0.0.1`)
@@ -372,11 +404,14 @@ HTTP transport includes:
 | `NWC_URI_FILE` | — | Path to a private 0600 file containing the NWC bearer URI. Raw NWC_URI is refused. |
 | `CASHU_TOKENS` | — | Path to Cashu token store file. Must be within home directory. |
 | `MAX_AUTO_PAY_SATS` | 1000 | Per-payment safety cap (satoshis). 0 disables autonomous payments. |
-| `MAX_SPEND_PER_MINUTE_SATS` | 10000 | Rolling 60-second spend cap (satoshis). |
+| `MAX_SPEND_PER_MINUTE_SATS` | 10000 | Rolling 60-second spend cap (satoshis). 0 blocks auto-pay. |
+| `MAX_SPEND_PER_DAY_SATS` | 5000 | Rolling 24-hour spend cap (satoshis), persisted across restarts. 0 blocks auto-pay. |
 | `CREDENTIAL_STORE` | `~/.402-mcp/credentials.json` | Path to encrypted credential store. Must be within home directory. |
 | `TRANSPORT` | `stdio` | Transport mode: `stdio` or `http`. |
 | `PORT` | 3402 | HTTP server port (when `TRANSPORT=http`). |
 | `BIND_ADDRESS` | `127.0.0.1` | HTTP bind address. Warning emitted for non-loopback addresses. |
+| `HTTP_AUTH_TOKEN_FILE` | - | Private 0600 file holding the bearer token (32+ characters). Required when `TRANSPORT=http`. Raw HTTP_AUTH_TOKEN is refused. |
+| `HTTP_ALLOWED_HOSTS` | - | Extra `Host` header values to accept (comma-separated), e.g. a reverse proxy's name. |
 | `CORS_ORIGIN` | disabled | CORS origin for HTTP transport. |
 | `FETCH_TIMEOUT_MS` | 30000 | HTTP request timeout in milliseconds. |
 | `FETCH_MAX_RETRIES` | 2 | Maximum retry attempts for failed requests. Money-mutating POSTs use 0. |
@@ -388,7 +423,7 @@ HTTP transport includes:
 | `TRANSPORT_PREFERENCE` | `onion,hns,https,http` | Preferred transport order for multi-URL services. |
 | `TOR_PROXY` | — | SOCKS5 proxy for .onion requests only (e.g. `socks5h://127.0.0.1:9050`). |
 | `SOCKS_PROXY` | — | SOCKS5 proxy for every paid-API request, names resolved by the proxy. Set this or `TOR_PROXY`, not both. Wallet and relay traffic is not proxied. |
-| `HNS_GATEWAY_URL` | `https://query.hdns.io/` | DNS-over-HTTPS gateway for Handshake (HNS) name resolution. |
+| `HNS_GATEWAY_URL` | `https://query.hdns.io/` | DNS-over-HTTPS resolver for Handshake (HNS) names. Any host name ordinary DNS cannot find is sent here. |
 
 ## Multi-Transport Endpoints
 
@@ -416,7 +451,7 @@ Handshake names are resolved via DNS-over-HTTPS (RFC 8484 wire format) through t
 
 ### Credential Portability
 
-Credentials are keyed by service **pubkey** (from the kind 31402 event), not by URL origin. A macaroon obtained via a Tor hidden service works over clearnet, and vice versa. This is essential for transport fallback — the agent doesn't need to re-authenticate when switching transports.
+Credentials are keyed by service **pubkey** (from the kind 31402 event) and bound to the transport origins they were bought through. A macaroon obtained via a Tor hidden service works over the service's clearnet URL, and vice versa, when both were in the `urls` list at purchase. A credential is never sent to an origin it is not bound to, whatever pubkey the request names.
 
 ## Ecosystem
 
@@ -468,7 +503,10 @@ Credentials are keyed by service **pubkey** (from the kind 31402 event), not by
 ### Agent with no wallet (human-in-the-loop)
 
 ```
-1. l402-fetch(url)                  → 402 received, amount shown
-2. Agent presents QR code to user   → Human pays via wallet app
-3. Poll detects payment             → Credential stored, data returned
+1. l402-fetch(url, autoPay)        → 402 received; payment page URL or QR shown
+2. Human pays via wallet app
+3. l402-pay(paymentHash)            → polls the toll-booth payment page, stores the credential
+4. l402-fetch(url)                  → data returned
+
+Settlement can only be confirmed where the server reports it (toll-booth).
 ```

package/llms.txt

@@ -1,8 +1,8 @@
 # 402-mcp
 
-> 402-mcp is an MCP server that gives AI agents economic agency — the ability to discover, pay for, and consume any L402 or x402 payment-gated API without human registration, API keys, or middlemen. It speaks the L402 protocol natively, carries its own payment methods, and makes autonomous purchasing decisions within human-set safety limits.
+> 402-mcp is an MCP server that gives AI agents economic agency: the ability to discover, pay for, and consume L402 and other Lightning or ecash payment-gated APIs without human registration, API keys, or middlemen. It speaks the L402 protocol natively, carries its own payment methods, and makes autonomous purchasing decisions within human-set safety limits.
 
-402-mcp is protocol-loyal: it works with any L402-compliant server (toll-booth, Aperture, or any conforming implementation), not just a specific vendor's stack. Bonus features activate automatically when talking to a toll-booth server. Three payer methods are supported — NWC (Nostr Wallet Connect), Cashu ecash, and human-in-the-loop — tried in that priority order so the agent picks the most autonomous option available.
+402-mcp is protocol-loyal: it works with any L402-compliant server (toll-booth, Aperture, or any conforming implementation), not just a specific vendor's stack. Bonus features activate automatically when talking to a toll-booth server. Four payer methods are supported (NWC (Nostr Wallet Connect), Cashu ecash, LNURLcash bearer notes, and human-in-the-loop), tried in that priority order so the agent picks the most autonomous option available.
 
 Agents can also discover paid APIs without knowing URLs upfront. The `l402-search` tool queries Nostr relays for kind 31402 service announcements — a decentralised registry of L402-enabled services. Discovered services may advertise multiple transport endpoints (clearnet HTTPS, Tor .onion, Handshake HNS domains). The agent automatically selects the best available transport and falls back through alternatives on connection failure — .onion endpoints need `TOR_PROXY` or `SOCKS_PROXY`; clearnet and HNS need no configuration.
 
@@ -14,12 +14,15 @@ Run instantly with no configuration required:
 npx 402-mcp
 ```
 
-For HTTP transport (useful for remote agents or multi-client setups):
+Use stdio wherever the client can start a local process. The HTTP transport can spend from your wallet, so it refuses to start without a bearer token, and only answers requests whose `Host` header it recognises:
 
 ```bash
-TRANSPORT=http npx 402-mcp
+openssl rand -hex 32 > ~/.402-mcp/http.token && chmod 600 ~/.402-mcp/http.token
+TRANSPORT=http HTTP_AUTH_TOKEN_FILE=~/.402-mcp/http.token npx 402-mcp
 ```
 
+Clients send `Authorization: Bearer <token>`. It listens on `127.0.0.1` only by default. To reach it from another machine, put it behind a TLS reverse proxy and add the proxy's host name to `HTTP_ALLOWED_HOSTS`; never expose it directly.
+
 ### Claude Desktop / Cursor
 
 Add to your MCP configuration:
@@ -45,25 +48,29 @@ Add to your MCP configuration:
 |----------|---------|-------------|
 | `NWC_URI_FILE` | — | Private 0600 file containing the Nostr Wallet Connect bearer URI |
 | `CASHU_TOKENS` | — | Path to Cashu token store file |
-| `MAX_AUTO_PAY_SATS` | 1000 | Safety cap; payments above this require human confirmation |
-| `MAX_SPEND_PER_MINUTE_SATS` | 10000 | Rolling 60-second spend cap across all payments |
+| `LNURLCASH_NOTES` | - | Path to LNURLcash (LUD-25) bearer note store file |
+| `MAX_AUTO_PAY_SATS` | 1000 | Most a single automatic payment may cost. Dearer challenges are not paid; they go back to the agent. `0` disables auto-pay |
+| `MAX_SPEND_PER_MINUTE_SATS` | 10000 | Automatic spend allowed in any rolling 60 seconds. `0` blocks all auto-pay |
+| `MAX_SPEND_PER_DAY_SATS` | 5000 | Automatic spend allowed in any rolling 24 hours, persisted across restarts. `0` blocks all auto-pay |
 | `CREDENTIAL_STORE` | `~/.402-mcp/credentials.json` | Persistent macaroon/credential storage |
 | `TRANSPORT` | `stdio` | Transport mode: `stdio` or `http` |
 | `PORT` | 3402 | HTTP server port (when `TRANSPORT=http`) |
+| `HTTP_AUTH_TOKEN_FILE` | - | Private 0600 file holding the bearer token; required when `TRANSPORT=http` |
+| `HTTP_ALLOWED_HOSTS` | - | Extra `Host` header values the HTTP transport accepts (comma-separated) |
 | `TRANSPORT_PREFERENCE` | `onion,hns,https,http` | Preferred transport order for multi-URL services |
 | `TOR_PROXY` | — | SOCKS5 proxy for .onion requests only (e.g. `socks5h://127.0.0.1:9050`) |
 | `SOCKS_PROXY` | — | SOCKS5 proxy for every paid-API request, names resolved by the proxy. Set this or `TOR_PROXY`, not both |
-| `HNS_GATEWAY_URL` | `https://query.hdns.io/` | DNS-over-HTTPS gateway for Handshake name resolution |
+| `HNS_GATEWAY_URL` | `https://query.hdns.io/` | DNS-over-HTTPS resolver for Handshake names; any host name ordinary DNS cannot find is looked up here |
 
 ## Key Concepts
 
 - **L402** — an HTTP payment protocol where a server responds to unauthenticated requests with HTTP 402, a Lightning invoice, and a macaroon. The client pays the invoice, then sends `Authorization: L402 <macaroon>:<preimage>` to access the API.
 - **Economic agency** — the agent discovers a service, reads the price, pays the invoice, and retrieves the data, all within a single tool call. No human registration required.
-- **Safety cap** — `MAX_AUTO_PAY_SATS` sets the maximum any single autonomous payment can be. Above this limit, the agent asks for human approval. A rolling 60-second spend cap (`MAX_SPEND_PER_MINUTE_SATS`) prevents runaway spending.
+- **Spending limits**: `MAX_AUTO_PAY_SATS` is the most any single automatic payment can be; a dearer challenge is returned to the agent unpaid. Rolling 60-second and persisted 24-hour caps (`MAX_SPEND_PER_MINUTE_SATS`, `MAX_SPEND_PER_DAY_SATS`) stop runaway spending. The budget on the NWC connection itself is the real hard limit.
 - **Credential store** — paid macaroons are persisted locally and encrypted with AES-256-GCM. Subsequent requests to the same server reuse credentials rather than paying again.
 - **Credit balance** — many L402 servers (including toll-booth) grant a credit balance after payment. 402-mcp tracks and caches that balance so the agent can reason about remaining capacity.
 - **Service discovery** — agents can search for L402 services on Nostr relays by querying kind 31402 announcements, finding paid APIs by topic, capability, or payment method.
-- **Multi-transport** — discovered services may advertise multiple endpoints (HTTPS, Tor .onion, Handshake HNS). The agent selects the best transport by preference (default: onion > hns > https > http), filters by capability (e.g. .onion requires a Tor proxy), and falls back automatically on connection failure. Credentials are keyed by service pubkey, not URL origin, so a macaroon obtained via one transport works on any other.
+- **Multi-transport**: discovered services may advertise multiple endpoints (HTTPS, Tor .onion, Handshake HNS). The agent selects the best transport by preference (default: onion > hns > https > http), filters by capability (e.g. .onion requires a Tor proxy), and falls back automatically on connection failure. Credentials are keyed by service pubkey and bound to the transport origins they were bought through, so a macaroon obtained via one advertised transport works on the others, and is never sent to an origin it was not bought from.
 
 ## Core L402 Tools
 
@@ -77,13 +84,21 @@ Introspect the agent's payment capabilities and current configuration. Returns w
 
 Probe an endpoint to discover its pricing without making a payment. Returns the invoice amount in satoshis, the macaroon challenge, and whether the server is a toll-booth instance (which enables extension tools). Use this before committing to a purchase so the agent can reason about value.
 
+### `l402-fetch-preview`
+
+Show what an endpoint (or each of a service's transport URLs) costs without paying: protocol, price and which wallet would pay. Cannot spend by construction. Widget hosts render it as a payment confirmation dialog.
+
 ### `l402-fetch`
 
-Make an HTTP request to an L402-protected endpoint. Handles the full payment flow automatically: detects 402 responses, pays the invoice if the amount is within the `MAX_AUTO_PAY_SATS` budget and the rolling spend cap, stores the credential, and retries the request. Returns the response body on success. This is the primary tool for consuming L402 APIs.
+Make an HTTP request to an L402-protected endpoint. With `autoPay: true` it detects the 402, pays if the price is within `MAX_AUTO_PAY_SATS`, the optional per-call `maxCostSats` and the rolling spend caps, stores the credential, and retries. Without `autoPay` the challenge comes back with its price and `paymentHash`. Response bodies are wrapped in UNTRUSTED CONTENT markers. This is the primary tool for consuming L402 APIs.
 
 ### `l402-pay`
 
-Pay a specific Lightning invoice directly. Tries payment methods in priority order: NWC, Cashu, human-in-the-loop. Use this when you have an invoice from a source other than `l402-fetch`, or when you want explicit control over the payment step.
+Pay a challenge that `l402-fetch` or `l402-discover` returned, by its `paymentHash`, using the wallet priority NWC, Cashu, LNURLcash, human. An invoice that did not come from such a challenge is paid only if the human approves it in the client (MCP elicitation); otherwise it is refused.
+
+### `l402-reconcile`
+
+List payments whose outcome is unknown, or resolve one by asking the wallet that made it (NWC `lookup_invoice`, the Cashu mint, or the LNURLcash verify URL). While any is unresolved for a service, auto-pay to that service is paused.
 
 ### `l402-credentials`
 
@@ -95,7 +110,11 @@ Check the cached credit balance for a specific server URL. Returns the number of
 
 ### `l402-search`
 
-Search for L402 services on Nostr relays. Queries kind 31402 announcement events and returns matching services with their names, URLs, pricing, capabilities, and supported payment methods. Filter by query text, topics (e.g. "ai", "data"), or payment method. Services may advertise multiple transport URLs (clearnet, .onion, HNS); pass the returned URLs array to `l402-fetch` for automatic transport selection and fallback. This enables agents to find paid APIs without knowing URLs upfront — a decentralised alternative to API directories.
+Search for L402 services on Nostr relays. Queries kind 31402 announcement events (topic and payment-method filters are sent to the relays; query text is matched locally) and returns matching services with their names, URLs, pricing, capabilities, and supported payment methods. Filter by query text, topics (e.g. "ai", "data"), or payment method. Services may advertise multiple transport URLs (clearnet, .onion, HNS); pass the returned URLs array to `l402-fetch` for automatic transport selection and fallback. This enables agents to find paid APIs without knowing URLs upfront: a decentralised alternative to API directories. Announcement text is wrapped in UNTRUSTED CONTENT markers.
+
+## Widget Tools
+
+For hosts that support MCP Apps: `l402-service-directory` opens a searchable directory of services from `l402-search`, and `l402-wallet-dashboard` shows wallet status, limits and stored credentials. `l402-fetch-preview` has a payment confirmation widget.
 
 ## toll-booth Extension Tools
 
@@ -111,30 +130,36 @@ Redeem Cashu ecash tokens directly with the toll-booth server, bypassing the Lig
 
 ## Payment Methods
 
-Three payer methods are tried in priority order:
+Four payer methods are tried in priority order:
 
 1. **NWC (Nostr Wallet Connect)** — fully autonomous. The agent pays invoices directly from a connected Lightning wallet via the NWC protocol. Configure with `NWC_URI_FILE`; raw bearer values are refused. No human interaction required.
 
 2. **Cashu** — fully autonomous. The agent melts ecash tokens to pay invoices. Configure with `CASHU_TOKENS` pointing to a token store file. No Lightning node required on the agent side.
 
-3. **Human-in-the-loop** — fallback when no autonomous payment method is configured or when a payment exceeds the `MAX_AUTO_PAY_SATS` cap. The agent presents a payment QR code and polls for settlement. Control returns to the agent once the human has paid.
+3. **LNURLcash**: fully autonomous. The agent melts LUD-25 bearer notes to pay invoices. Configure with `LNURLCASH_NOTES`.
+
+4. **Human-in-the-loop**: used when no autonomous payment method is configured. The agent presents a payment QR code or payment page, and `l402-pay` confirms settlement where the server reports it (toll-booth does). It does not take over above `MAX_AUTO_PAY_SATS`: a dearer challenge is simply returned to the agent unpaid.
 
 The agent can override the payment method per-call, or you can configure only the methods you want available.
 
-`l402-fetch` handles five HTTP 402 challenge variants transparently:
+`l402-fetch` handles four HTTP 402 challenge variants, plus an experimental x402 format:
 
 - **L402** (`WWW-Authenticate: L402`) — the primary protocol; Lightning invoice paid via the wallet stack.
 - **IETF Payment** (`WWW-Authenticate: Payment`, `draft-ryan-httpauth-payment-01`) — alternative Lightning path; builds a base64url credential after payment.
 - **LNURLcash** (`X-LNURLcash: lnurlcashreq1…`, LUD-25): autonomous bearer-note payment; hands over a note worth exactly the price, splitting one at the mint if needed. Tried first: no Lightning hop and no swap at the mint.
 - **xCashu** (`X-Cashu: creqA…`, NUT-18) — autonomous ecash payment; selects and sends the exact token amount without a Lightning round-trip.
-- **x402** (`X-Payment-Required: x402`) — on-chain EVM payment; surfaces an EIP-681 deeplink to the human (no autonomous settlement).
+- **x402** (`X-Payment-Required: x402`), experimental: a custom format, not the x402 specification (whose servers send a base64 `PAYMENT-REQUIRED` header), so real x402 services are not supported. Payment details are shown to the human, who pays from their own wallet; nothing is paid autonomously.
 
 ## Safety Model
 
-Two safety primitives protect against runaway spending:
+These limits apply to every automatic payment:
+
+1. **`MAX_AUTO_PAY_SATS`** caps any single payment. A dearer challenge is returned to the agent unpaid; whether the agent then asks the human is up to the agent.
+2. **`maxCostSats`** on `l402-fetch` lowers that cap for one call, so a price shown in a preview is binding.
+3. **`MAX_SPEND_PER_MINUTE_SATS`** and **`MAX_SPEND_PER_DAY_SATS`** cap total spend over rolling 60-second and 24-hour windows; the daily window survives restarts. `0` blocks auto-pay.
+4. **Unknown outcomes** pause auto-pay to that service until `l402-reconcile` resolves them.
 
-1. **`MAX_AUTO_PAY_SATS`** — caps any single autonomous payment. Above this threshold, the agent must ask for human approval.
-2. **`MAX_SPEND_PER_MINUTE_SATS`** — rolling 60-second window cap across all payments. Prevents rapid successive payments from exceeding a total budget even if each individual payment is below the per-payment cap.
+All of these are enforced in software by this process. The budget set on the NWC connection in the wallet is the real hard limit.
 
 The human stays in control of three things: the safety caps, which payment methods are available, and credential visibility. The agent operates within those boundaries, not around them.
 
@@ -142,9 +167,11 @@ The human stays in control of three things: the safety caps, which payment metho
 
 - **SSRF protection** — all outbound requests pass through an SSRF guard that blocks private/internal IP ranges by default. Handshake names are resolved via DNS-over-HTTPS with the resolved IP validated against blocked ranges. .onion addresses bypass DNS and route through the configured SOCKS proxy. With `SOCKS_PROXY`, no host name is resolved locally; IP literals and local names are still refused. Wallet and relay traffic is not proxied. Set `SSRF_ALLOW_PRIVATE=true` only for local development.
 - **Credential encryption** — stored credentials are encrypted with AES-256-GCM. The encryption key is stored in the OS keychain when available, falling back to a file-based key with a warning.
-- **Settlement proof** — NWC responses are authenticated with NIP-44 v2 and signed events, then the returned preimage is verified against the challenged BOLT-11 payment hash before storage.
+- **Settlement proof**: NWC responses are authenticated with NIP-44 v2 and signed events. NWC and Cashu preimages are verified against the invoice's payment hash; a payment reported without a matching preimage is treated as an unknown outcome, not as unpaid.
+- **Prompt-injection hardening**: third-party text is marked as untrusted, and `l402-pay` only pays invoices from challenges this process received unless the human approves.
+- **Credential binding**: stored credentials are sent only to the origins they were obtained from.
 - **Spend tracking** — atomic `tryRecord()` prevents TOCTOU race conditions in concurrent spend checks.
-- **HTTP transport hardening** — rate limiting (100 req/60s per IP), security headers (CSP, X-Frame-Options, nosniff), and loopback-only binding by default.
+- **HTTP transport hardening**: bearer token required (`HTTP_AUTH_TOKEN_FILE`), DNS rebinding protection through a `Host` allowlist, rate limiting (100 req/60s per IP), security headers (CSP, X-Frame-Options, nosniff), and loopback-only binding by default.
 
 ## Ecosystem
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "402-mcp",
-  "version": "4.2.2",
+  "version": "4.3.0",
   "mcpName": "dev.forgesworn/402-mcp",
-  "description": "L402 + x402 client MCP - AI agents discover, pay for, and consume any payment-gated API",
+  "description": "L402 client MCP: AI agents discover, pay for and consume Lightning and ecash payment-gated APIs (x402 support is experimental)",
   "type": "module",
   "bin": {
     "402-mcp": "./build/index.js"
@@ -37,7 +37,7 @@
   },
   "dependencies": {
     "@cashu/cashu-ts": "^3.6.1",
-    "@forgesworn/nwc-kit": "0.1.7",
+    "@forgesworn/nwc-kit": "0.1.8",
     "@modelcontextprotocol/ext-apps": "^1.3.1",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "@scure/base": "^2.0.0",

package/src/widgets/dist/service-directory.html

@@ -161,6 +161,15 @@ function el(tag, attrs, ...children) {
     root.replaceChildren(el("div", { className: "status-text" }, text));
   }
 
+  // l402-search delimits announcement text as untrusted for the agent. The
+  // card shows the text itself; it is rendered as text, never as markup.
+  function plain(value) {
+    const m = typeof value === "string"
+      ? /^\[UNTRUSTED CONTENT from [^\]\n]*\]\n([\s\S]*)\n\[END UNTRUSTED CONTENT\]$/.exec(value)
+      : null;
+    return m ? m[1] : value;
+  }
+
   function renderServices(services, query) {
     const searchInput = el("input", {
       className: "search-box",
@@ -205,8 +214,8 @@ function el(tag, attrs, ...children) {
           });
         },
       },
-        el("div", { className: "service-name" }, svc.name || "Unnamed Service"),
-        svc.about ? el("div", { className: "service-desc" }, svc.about) : null,
+        el("div", { className: "service-name" }, plain(svc.name) || "Unnamed Service"),
+        svc.about ? el("div", { className: "service-desc" }, plain(svc.about)) : null,
         chips,
       );
       list.appendChild(card);