verify402-mcp 1.0.3 → 1.0.5

package/.env.example

@@ -3,9 +3,9 @@
 # The bridge runs without any of these. With no EVM_PRIVATE_KEY it exposes only
 # the free preflight_gate. Set a key only when you want the five paid checks.
 #
-# EVM_PRIVATE_KEY is a dedicated hot wallet that pays for calls in USDC. Use a
-# wallet with only the money you are willing to spend. NEVER commit the real
-# .env and never use a main wallet.
+# EVM_PRIVATE_KEY is a dedicated hot wallet that pays for calls in testnet
+# USDC on the public demo. Use a wallet with only the money you are willing to
+# spend. NEVER commit the real .env and never use a main wallet.
 EVM_PRIVATE_KEY=           # optional; omit for the free gate only
 VERIFY402_URL=https://verify402.onrender.com
 # spend controls (paid tools only)
@@ -13,8 +13,11 @@ MAX_PAYMENT_USD=0.25      # cap on ONE payment, enforced at signature time
 MAX_DAILY_USD=0.50        # cap on the whole UTC day, survives restarts; omit to disable
 SPEND_LEDGER_PATH=        # optional override for the ledger file (default .spend-ledger.json)
 
-# payment allowlist (paid tools only; these are the defaults)
-VERIFY402_NETWORKS=eip155:8453
+# payment allowlist (paid tools only; these are the public-demo defaults)
+# Base Sepolia testnet: the live demo's EVM payment rail.
+VERIFY402_NETWORKS=eip155:84532
 VERIFY402_PAY_TO=0xAeEF086DD4e436c69d6d0F684b4c9F43392df9cb
 # VERIFY402_RESOURCE_PREFIX=https://verify402.onrender.com
-# For local testnet, set VERIFY402_NETWORKS=eip155:84532 and the payee the local server names.
+# Explicit mainnet is a separate deployment, not a demo setting. Set this only
+# after separate readiness verification, with a mainnet facilitator and host:
+# VERIFY402_NETWORKS=eip155:8453

package/README.md

@@ -5,8 +5,18 @@ agent signs a payment or a chain transaction, plus five paid on-chain checks
 paid per call over x402.
 
 Works with Claude Desktop, Cursor, OpenCode, and any MCP client that speaks
-stdio. The free gate needs **no wallet**. The paid tools use a dedicated hot
-wallet that pays in USDC; the bridge never signs or sends a trade.
+stdio. The free gate needs **no wallet**. The public demo's paid tools use a
+dedicated hot wallet funded with **Base Sepolia testnet USDC** (`eip155:84532`).
+The analysis reads mainnet chain data, but the demo never settles mainnet
+payments. The bridge never signs or sends a trade.
+
+> **Published package note:** npm `verify402-mcp@1.0.4` is immutable and its
+> published README predates this source-tree testnet default. Its built-in
+> runtime default is Base mainnet (`eip155:8453`). The explicit
+> `VERIFY402_NETWORKS=eip155:84532` block below is required with that package
+> for the public demo; a future patch release is needed to update the npm page
+> and change the built-in default. This source tree is `1.0.5` and already
+> defaults to Base Sepolia testnet, but `1.0.5` is not published yet.
 
 ## Tools
 
@@ -62,7 +72,7 @@ node index.mjs --help
 ## AI Agent Integration (Step-by-Step)
 
 ### Step 1: Free Mode (Zero Config, No Wallet)
-To give your AI agent the free **`preflight_gate`** (checks transaction calldata, payment challenges, payee/amount, approvals, and block freshness before signing), paste this into your client configuration. Honeypot/sellability evidence is the paid `check_token_safety` check, not a free-gate guarantee.
+To give your AI agent the free **`preflight_gate`** (checks transaction calldata, payment challenges, payee/amount, approvals, and block freshness before signing), paste this into your client configuration. The paid `check_token_safety` check adds a quote-based sellability check; it does not execute a transfer and is not a honeypot guarantee.
 
 **Claude Desktop** (`claude_desktop_config.json`) or **Cursor** (`.cursor/mcp.json`):
 ```json
@@ -85,11 +95,12 @@ To enable the 5 deep on-chain truth checks (`verify_arbitrage`, `check_token_saf
 1. **Create a Dedicated Hot Wallet**:
    - Create a brand new wallet in MetaMask, Rabby, or via `cast wallet new`.
    - ⚠️ **SECURITY WARNING**: Never use your primary personal wallet, cold storage, or vault.
-2. **Fund the Wallet on Base (EIP-155:8453)**:
-   - **USDC**: Transfer $2 to $10 of USDC on Base (the bridge pays per call: $0.03 to $0.10).
-   - **Gas (ETH on Base)**: Transfer ~$0.50 worth of ETH on Base for minimal gas allowances if needed.
+2. **Fund the Wallet on Base Sepolia testnet (EIP-155:84532)**:
+   - **USDC**: Get Base Sepolia testnet USDC from a faucet (the bridge pays per call: $0.03 to $0.10 in testnet USDC).
+   - **Gas (ETH on Base Sepolia)**: Get a small amount of Base Sepolia testnet ETH for gas if your client needs it. No mainnet funds are required for the public demo.
 3. **Configure Environment Variables in Your MCP Client**:
    - Set `EVM_PRIVATE_KEY` to the 64-character private key of the hot wallet.
+   - Set `VERIFY402_NETWORKS` to `eip155:84532` (Base Sepolia testnet).
    - Set safety caps `MAX_PAYMENT_USD` (e.g., `"0.25"`) and `MAX_DAILY_USD` (e.g., `"1.00"`).
 
 **Paid Configuration Block (Claude Desktop, Cursor, Cline, Windsurf)**:
@@ -104,7 +115,7 @@ To enable the 5 deep on-chain truth checks (`verify_arbitrage`, `check_token_saf
         "EVM_PRIVATE_KEY": "0xYOUR_HOT_WALLET_PRIVATE_KEY",
         "MAX_PAYMENT_USD": "0.25",
         "MAX_DAILY_USD": "1.00",
-        "VERIFY402_NETWORKS": "eip155:8453",
+        "VERIFY402_NETWORKS": "eip155:84532",
         "VERIFY402_PAY_TO": "0xAeEF086DD4e436c69d6d0F684b4c9F43392df9cb"
       }
     }
@@ -125,6 +136,7 @@ In `opencode.jsonc` (or `~/.config/opencode/opencode.jsonc`):
         "environment": {
           "VERIFY402_URL": "https://verify402.onrender.com",
           "EVM_PRIVATE_KEY": "{env:EVM_PRIVATE_KEY}",
+          "VERIFY402_NETWORKS": "eip155:84532",
           "MAX_PAYMENT_USD": "0.25",
           "MAX_DAILY_USD": "1.00"
         }
@@ -142,8 +154,8 @@ Once configured, your agent automatically sees the tools in its context. You can
 
 - **Preflight Gate (Free)**:
   > *"Before signing this transaction, call `preflight_gate` on the payment request / calldata. If it returns BLOCK, abort and explain why."*
-- **Token Safety / Sellability Check ($0.10, not a code audit)**:
-  > *"Analyze token `0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE` using `check_token_safety`. Is it sellable at a realistic size, what is the round-trip cost, and is the result TRUST / CAUTION / AVOID?"*
+- **Token Quote-Based Sellability Check ($0.10, not a code audit)**:
+  > *"Analyze token `0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE` using `check_token_safety`. Can it be sold at a realistic size on the configured venues, what is the round-trip cost, and is the result TRUST / CAUTION / AVOID? Read notChecked for transfer restrictions."*
 - **Arbitrage Verification ($0.05)**:
   > *"Use `verify_arbitrage` to verify if there is an arbitrage opportunity between Uniswap V3 and Sushiswap for WETH/USDC on chain 1 at the current block."*
 - **Quote Fairness Audit ($0.05)**:
@@ -154,13 +166,29 @@ Once configured, your agent automatically sees the tools in its context. You can
 ## Safety
 
 - The bridge signs **x402 payments only**. It never signs or broadcasts a trade.
+- Each paid tool call mints one `crypto.randomUUID()` idempotency key and sends it
+  as `x-idempotency-key`. A timeout or lost response is retried with the **same**
+  key, so the server replays the settled verdict (`recovery.replayed: true`)
+  instead of charging twice. A 402 or 409 is never auto-retried; the error is
+  surfaced to the MCP client. The key is a secret and is never logged or returned.
 - Before signing, the paid client requires the 402 to come from the configured
   server and a known paid route, on an allowlisted EVM network, to the
   verify402 payee. It accepts only recognized default assets (USDC), caps the
   amount at `MAX_PAYMENT_USD`, and refuses redirects.
+- The whole 402 challenge is checked, not just the option the client picks:
+  every offered requirement must use an allowlisted network, the configured
+  payee, the canonical USDC contract **and** the canonical EIP-712 domain for
+  that network, an `extra.assetTransferMethod` of `eip3009`, a
+  `maxTimeoutSeconds` that is a positive integer no greater than `300`, and an
+  amount inside the cap. A challenge that also offers Base mainnet is refused
+  as a whole rather than filtered down to the testnet option. The client also
+  proves that the requirement it signs is the exact object the server sent.
 - The allowlist can be narrowed or pointed at another deployment with
   `VERIFY402_NETWORKS`, `VERIFY402_PAY_TO`, and `VERIFY402_RESOURCE_PREFIX`.
-  Defaults are Base mainnet and the public verify402 payee.
+  The source-tree defaults are Base Sepolia testnet (`eip155:84532`) and the
+  public verify402 payee. `VERIFY402_NETWORKS` is constrained to the supported
+  map (`eip155:84532`, `eip155:8453`); an explicitly empty value fails closed
+  instead of falling back to a default.
 - `MAX_PAYMENT_USD` is enforced inside the x402 client, before a signature
   exists; removing it is a security regression. The caps limit what the bridge
   can authorize; they do **not** protect a compromised private key.
@@ -172,6 +200,23 @@ Once configured, your agent automatically sees the tools in its context. You can
 - Use the [reference executor](https://github.com/a32116150-ctrl/verify402/blob/master/examples/preflight-guard.mjs)
   when you want enforcement rather than advice.
 
+## Explicit mainnet configuration (not the public demo)
+
+Mainnet settlement is a separate deployment choice, not a bridge or demo
+default. Do not point this client at mainnet until the service-side mainnet
+readiness checks, facilitator, always-on host, and wallet funding have been
+verified independently.
+
+```bash
+# Only for a deliberate mainnet deployment, never against the public demo.
+VERIFY402_NETWORKS=eip155:8453
+VERIFY402_PAY_TO=<the payee named by the mainnet 402>
+```
+
+The public demo offers `eip155:84532`; a mainnet-only policy will refuse that
+challenge instead of silently spending mainnet funds. The reverse is also
+enforced: the demo policy refuses a mainnet-only challenge.
+
 ## Development
 
 ```bash

package/index.mjs

@@ -29,12 +29,26 @@ import { ExactEvmScheme } from "@x402/evm/exact/client";
 import { privateKeyToAccount } from "viem/accounts";
 import { config } from "dotenv";
 import { z } from "zod";
+import { installConsoleRedaction, logInfo, logError } from "./log.mjs";
+import { paidPost } from "./paid-call.mjs";
+import { fileURLToPath } from "node:url";
+import { realpathSync } from "node:fs";
+import { AsyncLocalStorage } from "node:async_hooks";
 
-config();
+installConsoleRedaction();
 
-const VERSION = "1.0.3";
+// Only the process entry point loads the operator's `.env`. Importing this
+// module (tests, tooling) must never read the wallet file.
+const IS_MAIN = isMainModule();
+if (IS_MAIN) config();
+
+const VERSION = "1.0.5";
 const EVM_PRIVATE_KEY = process.env.EVM_PRIVATE_KEY;
-const SERVER_URL = process.env.VERIFY402_URL || "https://verify402.onrender.com";
+// Normalise once so the axios base URL, the payment policy prefix, and the
+// per-tool expected resource are all the same string (no trailing slash).
+const SERVER_URL = (process.env.VERIFY402_URL || "https://verify402.onrender.com")
+  .trim()
+  .replace(/\/+$/, "");
 // Tell the server which client made the call. This is a label, not an identity:
 // it helps separate MCP use from generic HTTP probes without collecting keys or
 // wallet addresses.
@@ -56,6 +70,37 @@ const MAX_PAYMENT_USD = Number(process.env.MAX_PAYMENT_USD || 0.25);
 // registered only when a wallet is configured.
 const PAID_ENABLED = Boolean(EVM_PRIVATE_KEY);
 
+// Each paid MCP tool is bound to exactly one paid API route. This map is local,
+// trusted configuration: a 402 challenge can never choose which resource a tool
+// is allowed to pay for. The pre-sign guard compares the challenge's resource
+// against the route of the tool that is currently running.
+export const PAID_TOOL_ROUTES = Object.freeze({
+  verify_arbitrage: "/verify",
+  check_token_safety: "/safety",
+  get_best_route: "/route",
+  verify_quote_fairness: "/quotecheck",
+  get_trade_depth: "/depth",
+});
+
+// Carries the current tool's expected resource from the tool handler to the
+// pre-sign hook. AsyncLocalStorage keeps concurrent tool calls isolated and is
+// the only channel the guard trusts for the expected resource.
+const paymentContext = new AsyncLocalStorage();
+
+function paidCallContext(tool) {
+  const route = PAID_TOOL_ROUTES[tool];
+  if (!route) throw new Error(`unknown paid tool: ${String(tool)}`);
+  return { tool, route, expectedResource: `${SERVER_URL}${route}` };
+}
+
+/**
+ * Run `run` as the given paid tool. Exported so tests can drive the real
+ * binding without starting the MCP transport.
+ */
+export function runWithPaidTool(tool, run) {
+  return paymentContext.run(paidCallContext(tool), run);
+}
+
 if (process.argv.includes("--help") || process.argv.includes("-h")) {
   console.log(`verify402-mcp — MCP server for verify402
 
@@ -70,7 +115,7 @@ Environment:
   MAX_PAYMENT_USD   cap on one x402 payment (default 0.25)
   MAX_DAILY_USD     optional cap for the UTC day, persisted in a small ledger
   SPEND_LEDGER_PATH optional ledger path (default .spend-ledger.json)
-  VERIFY402_NETWORKS  comma-separated EVM networks for paid calls (default eip155:8453)
+  VERIFY402_NETWORKS  comma-separated EVM networks for paid calls (default eip155:84532, Base Sepolia testnet; eip155:8453 only by explicit opt-in)
   VERIFY402_PAY_TO    EVM payee the 402 must name (default the verify402 payee)
   VERIFY402_RESOURCE_PREFIX  resource origin/prefix the 402 must match (default VERIFY402_URL)
 
@@ -86,14 +131,12 @@ if (process.argv.includes("--version") || process.argv.includes("-v")) {
 }
 
 // ---------------------------------------------------------------- payment ---
-async function createPaidClient() {
+export function createBridgeClientFromEnv() {
   if (!Number.isFinite(MAX_PAYMENT_USD) || MAX_PAYMENT_USD <= 0) {
     throw new Error("MAX_PAYMENT_USD must be a positive number");
   }
-  const policy = createPaymentPolicy({
-    networks: process.env.VERIFY402_NETWORKS || DEFAULT_NETWORKS,
-    payTo: process.env.VERIFY402_PAY_TO || DEFAULT_PAY_TO,
-    resourcePrefix: process.env.VERIFY402_RESOURCE_PREFIX || SERVER_URL,
+  const policy = createPaymentPolicyFromEnv({
+    resourcePrefix: SERVER_URL,
     paidRoutes: Object.keys(DEFAULT_PRICES),
   });
   const account = privateKeyToAccount(EVM_PRIVATE_KEY);
@@ -105,12 +148,29 @@ async function createPaidClient() {
   for (const network of policy.allowedNetworks) {
     client.register(network, new ExactEvmScheme(account));
   }
-  client.onBeforePaymentCreation((context) => policy.checkBeforeSign(context));
-  console.error(
+  // Full-challenge guard (version, every EVM offer, canonical asset/domain,
+  // payee, amount cap, timeout, EIP-3009) plus the resource/route layer. It
+  // runs after the SDK has selected a requirement and before the signer.
+  // The expected resource is resolved per invocation from the tool handler
+  // context, never from the 402 challenge.
+  client.onBeforePaymentCreation(
+    createPaymentGuard(policy, {
+      maxAmountUsd: MAX_PAYMENT_USD,
+      expectedResource: () => paymentContext.getStore()?.expectedResource,
+    }),
+  );
+  logInfo(
     `paid policy: networks=${policy.allowedNetworks.join(",")} ` +
       `payee=${policy.allowedPayTo} resources=${policy.resourcePrefix} ` +
       `{${policy.paidRoutes.join(",")}}`,
   );
+  return client;
+}
+
+export async function createBridgePaidClient(client = createBridgeClientFromEnv()) {
+  if (!Number.isFinite(MAX_PAYMENT_USD) || MAX_PAYMENT_USD <= 0) {
+    throw new Error("MAX_PAYMENT_USD must be a positive number");
+  }
   const axiosInstance = axios.create({ baseURL: SERVER_URL, timeout: 120_000, maxRedirects: 0, headers: CLIENT_HEADERS });
   return wrapAxiosWithPayment(axiosInstance, client);
 }
@@ -120,14 +180,36 @@ async function createPaidClient() {
 // (optional) caps the whole UTC day across restarts, persisted in a tiny
 // ledger file. Attempted charges are counted conservatively (before payment).
 import { createDailyBudget, DEFAULT_PRICES } from "./budget.mjs";
-import { createPaymentPolicy, DEFAULT_NETWORKS, DEFAULT_PAY_TO } from "./payment-policy.mjs";
+import { createPaymentGuard, createPaymentPolicyFromEnv } from "./payment-policy.mjs";
 const dailyBudget = createDailyBudget({
   maxDailyUsd: process.env.MAX_DAILY_USD,
 });
 
-async function guardedPaidCall(route, run) {
-  if (dailyBudget.enabled) dailyBudget.assert(route);
-  return run();
+async function guardedPaidCall(tool, run) {
+  const context = paidCallContext(tool);
+  if (dailyBudget.enabled) dailyBudget.assert(context.route);
+  const res = await paymentContext.run(context, run);
+  if (res?.data?.recovery?.replayed) {
+    // Visible to the operator without exposing the bearer key. The same flag
+    // is already in the JSON returned to the MCP client.
+    logInfo(`${context.route}: recovery.replayed=true (settled verdict returned without a second charge)`);
+  }
+  return res;
+}
+
+/**
+ * Run one paid MCP tool. The route is resolved from local tool configuration
+ * (PAID_TOOL_ROUTES), recorded in the async context, and used for both the HTTP
+ * request and the pre-sign expected-resource check, so the 402 challenge can
+ * never redirect a tool to a different paid resource.
+ */
+export async function runPaidTool({ tool, client, body }) {
+  if (!Object.hasOwn(PAID_TOOL_ROUTES, tool)) {
+    throw new Error(`unknown paid tool: ${String(tool)}`);
+  }
+  if (!client) throw new Error(`paid client is not configured for tool ${tool}`);
+  const route = PAID_TOOL_ROUTES[tool];
+  return guardedPaidCall(tool, () => paidPost(client, route, body));
 }
 
 // ------------------------------------------------------------------ tools ---
@@ -138,32 +220,37 @@ const DESCRIPTIONS = {
     "the checks that did not, and a short-lived receipt bound to the exact intent + block. " +
     "If sign_allowed is false, DO NOT SIGN. If requires_ack is true, surface the reasons to the " +
     "operator before signing. The receipt expires (default 90s): call again rather than reuse it. " +
-    "Free. Pass `from` (the wallet that will sign) to enable simulation and balance checks.",
+    "Free. Pass `from` (the wallet that will sign) to enable simulation and balance checks. For " +
+    "kind=transaction, chainId is REQUIRED (400 missing_chain without it). For payment intents " +
+    "with no `from` or no proof, the response is PASS with structural_only:true and names what was not checked.",
   verify_arbitrage:
     "Ask verify402 whether a cross-venue arbitrage opportunity is REAL, right now. " +
     "Quotes come from Uniswap's canonical QuoterV2 and each DEX router at one pinned block. " +
     "The honest answer is usually 'no_edge' - that IS the product. Costs $0.05 per call.",
   check_token_safety:
-    "Ask verify402 whether a token is safe to buy BEFORE the agent risks capital. " +
+    "Ask verify402 for a quote-based sellability check on a token BEFORE the agent risks capital. " +
     "Returns TRUST/CAUTION/AVOID with evidence: live contract facts, market liquidity, " +
-    "a USD-sized sell probe against every venue (honeypot test), round-trip cost at your " +
-    "intended size, and phantom-price detection. Costs $0.10 per call.",
+    "a USD-sized sell QUOTED through the configured venues' own routers (direct and WETH-routed), " +
+    "round-trip cost at your intended size, and phantom-price detection. It does NOT execute or " +
+    "simulate a transfer: transfer tax, blacklist, pause, and max-tx restrictions are listed in " +
+    "notChecked, not tested. Unconfigured venues are also named in notChecked. Costs $0.10 per call.",
   get_best_route:
-    "Ask verify402 what the chain would ACTUALLY pay for a swap: the full execution book " +
-    "(every venue, direct and WETH-routed) at one pinned block, best first. Costs $0.03 per call.",
+    "Ask verify402 what the chain would ACTUALLY pay for a swap: the full book from every " +
+    "configured venue (direct and WETH-routed) at one pinned block, best first. Aggregators and " +
+    "unconfigured DEXs are not included. Costs $0.03 per call.",
   verify_quote_fairness:
     "Audit a swap quote someone else gave you (aggregator, broker, bot) BEFORE signing. " +
-    "Returns fair / overpaying / too_good_to_be_true with the full chain book as evidence. " +
+    "Returns fair / overpaying / too_good_to_be_true with the configured-venue book as evidence. " +
     "Ask this before accepting ANY number you did not produce yourself. Costs $0.05 per call.",
   get_trade_depth:
     "Position sizing: measure how much of a token the chain ACTUALLY lets you trade - " +
-    "entry and exit across every venue at a ladder of USD sizes, per-size impact and " +
+    "entry and exit across every configured venue at a ladder of USD sizes, per-size impact and " +
     "round-trip cost, plus the largest size under your cost tolerance. Ask BEFORE choosing " +
     "a position size. Costs $0.05 per call.",
 };
 
 async function main() {
-  const paidApi = PAID_ENABLED ? await createPaidClient() : null;
+  const paidApi = PAID_ENABLED ? await createBridgePaidClient() : null;
 
   const server = new McpServer({ name: "verify402", version: VERSION });
 
@@ -176,7 +263,7 @@ async function main() {
       from: z.string().optional().describe("The wallet that will sign. Strongly recommended: enables simulation and balance checks."),
       payment: z.object({
         scheme: z.string().optional().describe('x402 scheme, normally "exact"'),
-        network: z.string().describe('CAIP-2 network, e.g. "eip155:8453" or "solana:..."'),
+        network: z.string().describe('CAIP-2 network, e.g. "eip155:84532" for the public demo or "solana:..."'),
         asset: z.string().describe("Token address or mint, e.g. canonical USDC on that network"),
         amount: z.string().describe("RAW amount in the asset's smallest unit, as a string"),
         payTo: z.string().describe("Recipient address from the 402 challenge"),
@@ -248,17 +335,21 @@ async function main() {
     DESCRIPTIONS.verify_arbitrage,
     {
       target: z.string().describe('Token to buy and sell back, e.g. "WETH"'),
-      chainId: z.number().optional().describe("1 Ethereum, 42161 Arbitrum, 8453 Base (default 1)"),
+      chainId: z.number().int().describe("REQUIRED. 1 Ethereum, 42161 Arbitrum, 8453 Base. There is no default; omitting it returns 400 missing_chain."),
       base: z.string().optional().describe('Token to trade from, e.g. "USDC" (default USDC)'),
       size: z.number().optional().describe("Trade size in whole base units, e.g. 100000 (default 100000)"),
     },
     async (args) => {
-      const res = await guardedPaidCall("/verify", () => paidApi.post("/verify", {
-        chainId: args.chainId ?? 1,
-        target: String(args.target ?? "WETH").toUpperCase(),
-        base: String(args.base ?? "USDC").toUpperCase(),
-        size: args.size ?? 100000,
-      }));
+      const res = await runPaidTool({
+        tool: "verify_arbitrage",
+        client: paidApi,
+        body: {
+          chainId: args.chainId,
+          target: String(args.target ?? "WETH").toUpperCase(),
+          base: String(args.base ?? "USDC").toUpperCase(),
+          size: args.size ?? 100000,
+        },
+      });
       return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     },
   );
@@ -268,17 +359,21 @@ async function main() {
     DESCRIPTIONS.check_token_safety,
     {
       tokenAddress: z.string().describe("ERC-20 contract address, or a known symbol like WETH"),
-      chainId: z.number().optional().describe("1 Ethereum, 42161 Arbitrum, 8453 Base (default 1)"),
+      chainId: z.number().int().describe("REQUIRED. 1 Ethereum, 42161 Arbitrum, 8453 Base. There is no default; omitting it returns 400 missing_chain."),
       intendedUsd: z.number().optional().describe("Size the agent plans to buy, in USD (default 500)"),
       offeredPriceUsd: z.number().optional().describe("Optional price per token someone offered you"),
     },
     async (args) => {
-      const res = await guardedPaidCall("/safety", () => paidApi.post("/safety", {
-        chainId: args.chainId ?? 1,
-        tokenAddress: String(args.tokenAddress ?? "").trim(),
-        intendedUsd: args.intendedUsd ?? 500,
-        offeredPriceUsd: args.offeredPriceUsd ?? null,
-      }));
+      const res = await runPaidTool({
+        tool: "check_token_safety",
+        client: paidApi,
+        body: {
+          chainId: args.chainId,
+          tokenAddress: String(args.tokenAddress ?? "").trim(),
+          intendedUsd: args.intendedUsd ?? 500,
+          offeredPriceUsd: args.offeredPriceUsd ?? null,
+        },
+      });
       return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     },
   );
@@ -290,15 +385,19 @@ async function main() {
       tokenIn: z.string().describe("Token symbol (e.g. USDC) or 0x address"),
       tokenOut: z.string().describe("Token symbol (e.g. WETH) or 0x address"),
       amountIn: z.string().describe("RAW base units of tokenIn, wei-scale, as a string"),
-      chainId: z.number().optional().describe("1 Ethereum, 42161 Arbitrum, 8453 Base (default 1)"),
+      chainId: z.number().int().describe("REQUIRED. 1 Ethereum, 42161 Arbitrum, 8453 Base. There is no default; omitting it returns 400 missing_chain."),
     },
     async (args) => {
-      const res = await guardedPaidCall("/route", () => paidApi.post("/route", {
-        chainId: args.chainId ?? 1,
-        tokenIn: args.tokenIn,
-        tokenOut: args.tokenOut,
-        amountIn: args.amountIn,
-      }));
+      const res = await runPaidTool({
+        tool: "get_best_route",
+        client: paidApi,
+        body: {
+          chainId: args.chainId,
+          tokenIn: args.tokenIn,
+          tokenOut: args.tokenOut,
+          amountIn: args.amountIn,
+        },
+      });
       return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     },
   );
@@ -312,17 +411,21 @@ async function main() {
       amountIn: z.string().describe("RAW units of tokenIn, as in the offer"),
       quotedOut: z.string().describe("RAW units of tokenOut you were OFFERED"),
       venueClaimed: z.string().optional().describe("Optional: who gave you the offer"),
-      chainId: z.number().optional().describe("1 Ethereum, 42161 Arbitrum, 8453 Base (default 1)"),
+      chainId: z.number().int().describe("REQUIRED. 1 Ethereum, 42161 Arbitrum, 8453 Base. There is no default; omitting it returns 400 missing_chain."),
     },
     async (args) => {
-      const res = await guardedPaidCall("/quotecheck", () => paidApi.post("/quotecheck", {
-        chainId: args.chainId ?? 1,
-        tokenIn: args.tokenIn,
-        tokenOut: args.tokenOut,
-        amountIn: args.amountIn,
-        quotedOut: args.quotedOut,
-        venueClaimed: args.venueClaimed ?? null,
-      }));
+      const res = await runPaidTool({
+        tool: "verify_quote_fairness",
+        client: paidApi,
+        body: {
+          chainId: args.chainId,
+          tokenIn: args.tokenIn,
+          tokenOut: args.tokenOut,
+          amountIn: args.amountIn,
+          quotedOut: args.quotedOut,
+          venueClaimed: args.venueClaimed ?? null,
+        },
+      });
       return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     },
   );
@@ -332,19 +435,23 @@ async function main() {
     DESCRIPTIONS.get_trade_depth,
     {
       tokenAddress: z.string().describe("Token you plan to buy (symbol or 0x address)"),
-      chainId: z.number().optional().describe("1 Ethereum, 42161 Arbitrum, 8453 Base (default 1)"),
+      chainId: z.number().int().describe("REQUIRED. 1 Ethereum, 42161 Arbitrum, 8453 Base. There is no default; omitting it returns 400 missing_chain."),
       baseSymbol: z.string().optional().describe("What you pay with (default USDC)"),
       sizesUsd: z.array(z.number()).optional().describe("Ladder of sizes in USD, max 6 (default 100, 1000, 10000, 100000)"),
       maxRoundTripPct: z.number().optional().describe("Your round-trip cost tolerance, default 1%"),
     },
     async (args) => {
-      const res = await guardedPaidCall("/depth", () => paidApi.post("/depth", {
-        chainId: args.chainId ?? 1,
-        tokenAddress: args.tokenAddress,
-        baseSymbol: args.baseSymbol ?? "USDC",
-        sizesUsd: args.sizesUsd ?? null,
-        maxRoundTripPct: args.maxRoundTripPct ?? 1.0,
-      }));
+      const res = await runPaidTool({
+        tool: "get_trade_depth",
+        client: paidApi,
+        body: {
+          chainId: args.chainId,
+          tokenAddress: args.tokenAddress,
+          baseSymbol: args.baseSymbol ?? "USDC",
+          sizesUsd: args.sizesUsd ?? null,
+          maxRoundTripPct: args.maxRoundTripPct ?? 1.0,
+        },
+      });
       return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     },
   );
@@ -352,14 +459,30 @@ async function main() {
 
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  console.error(
+  logInfo(
     paidApi
       ? `verify402 MCP bridge connected -> ${SERVER_URL} (paid tools on, max payment $${MAX_PAYMENT_USD})`
       : `verify402 MCP bridge connected -> ${SERVER_URL} (free preflight_gate only; set EVM_PRIVATE_KEY for paid tools)`,
   );
 }
 
-main().catch((e) => {
-  console.error("bridge failed:", e.message);
-  process.exit(1);
-});
+// True only when this file is the process entry point. The published package
+// is installed through a `bin` symlink, so both sides are compared by real
+// path: Node resolves import.meta.url through the symlink but keeps the
+// symlink path in process.argv[1].
+function isMainModule() {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (IS_MAIN) {
+  main().catch((e) => {
+    logError("bridge failed", e);
+    process.exit(1);
+  });
+}

package/log.mjs

@@ -0,0 +1,198 @@
+// Central logging and redaction (MCP bridge copy).
+// Keep in sync with ../src/log.mjs: the MCP bridge is published as a standalone
+// package and cannot import files outside its own package root.
+//
+// Every runtime log line goes through this module. The goal is that an RPC URL
+// path, query string, basic-auth credential, header value, API key, or
+// idempotency key cannot reach stdout/stderr even when the source is a raw
+// viem/HttpRequestError, a stack trace, or request metadata.
+//
+// The public error boundary already keeps these values out of HTTP responses.
+// This module closes the other half: the log sink.
+
+import { createHash } from "node:crypto";
+
+const ORIGINAL = {
+  log: console.log.bind(console),
+  info: console.info.bind(console),
+  warn: console.warn.bind(console),
+  error: console.error.bind(console),
+  debug: console.debug.bind(console),
+};
+
+const SENSITIVE_KEY_RE =
+  /^(?:x-payment|payment-signature|authorization|proxy-authorization|x-api-key|api[-_]?key|apikey|secret|password|passwd|token|access[-_]?token|refresh[-_]?token|credential|private[-_]?key|idempotency[-_]?key|x-idempotency-key)$/i;
+const IDEMPOTENCY_KEY_RE = /^(?:x-)?idempotency[-_]?key$/i;
+const HEADER_OR_PARAM_RE =
+  /(x-payment|payment-signature|authorization|proxy-authorization|x-api-key|api[-_]?key|apikey|secret|password|passwd|access[-_]?token|refresh[-_]?token|private[-_]?key)(\s*[:=]\s*)(?:"[^"]*"|'[^']*'|[^\n\r,;]+)/gi;
+const IDEMPOTENCY_HEADER_RE =
+  /(x-idempotency-key|idempotency-key)(\s*[:=]\s*)("[^"]*"|'[^']*'|[^\s,;]+)/gi;
+
+let installed = false;
+
+function stripQuotes(value) {
+  return String(value ?? "").replace(/^["']|["']$/g, "");
+}
+
+/** Stable 8-character hash prefix for a caller-supplied idempotency key. */
+export function idempotencyPrefix(value) {
+  if (value == null || String(value) === "") return null;
+  return `idem:${createHash("sha256").update(String(value)).digest("hex").slice(0, 8)}`;
+}
+
+function sanitizeUrl(raw) {
+  try {
+    const u = new URL(raw);
+    if (!/^(?:https?|wss?):$/i.test(u.protocol)) return raw;
+    return `${u.protocol}//${u.host}/***`;
+  } catch {
+    // Best effort for malformed URLs: drop userinfo and everything after the
+    // authority, but never echo the original path/query.
+    return String(raw)
+      .replace(/\/\/[^/@\s]+@/, "//")
+      .replace(/^([a-z][a-z0-9+.-]*:\/\/[^/?#\s]+).*$/i, "$1/***");
+  }
+}
+
+/**
+ * Redact a string. `idempotencyKey` is optional context: when the caller's key
+ * is known, any literal occurrence is replaced with its 8-character hash
+ * prefix instead of a generic marker.
+ */
+export function redactText(value, { idempotencyKey = null } = {}) {
+  let s = String(value ?? "");
+  if (idempotencyKey) {
+    const key = String(idempotencyKey);
+    s = s.split(key).join(idempotencyPrefix(key));
+  }
+
+  // Full URLs: keep scheme + host (including port), replace the rest.
+  s = s.replace(/\b(?:https?|wss?):\/\/[^\s"'<>]+/gi, (match) => {
+    const trailing = match.match(/[),.;:!?]+$/)?.[0] ?? "";
+    const core = trailing ? match.slice(0, -trailing.length) : match;
+    return sanitizeUrl(core) + trailing;
+  });
+
+  // Idempotency keys get a stable 8-character hash prefix, not a generic
+  // marker, so a replay can still be correlated without exposing the key.
+  s = s.replace(IDEMPOTENCY_HEADER_RE, (match, key, sep, rawValue) => {
+    const value = stripQuotes(rawValue);
+    if (/^idem:[0-9a-f]{8}$/.test(value)) return match;
+    return `${key}${sep}${idempotencyPrefix(value)}`;
+  });
+
+  // Other headers and key=value query parameters: redact the whole value.
+  // This intentionally over-redacts an inline header line rather than risk
+  // leaving a fragment of "Bearer <token>" or a multi-word credential behind.
+  s = s.replace(HEADER_OR_PARAM_RE, (match, key, sep) => {
+    return `${key}${sep}[REDACTED]`;
+  });
+
+  return s;
+}
+
+function safeStringify(value, depth = 0, seen = new WeakSet()) {
+  if (value == null) return String(value);
+  if (typeof value === "bigint") return value.toString();
+  if (typeof value === "function") return "[Function]";
+  if (typeof value !== "object") return JSON.stringify(value);
+  if (value instanceof Error) return formatError(value);
+  if (depth > 5) return "[MaxDepth]";
+  if (seen.has(value)) return "[Circular]";
+  seen.add(value);
+  if (Array.isArray(value)) {
+    const out = value.slice(0, 50).map((v) => safeStringify(v, depth + 1, seen));
+    if (value.length > 50) out.push(`[+${value.length - 50} more]`);
+    return `[${out.join(",")}]`;
+  }
+  const pairs = [];
+  for (const [key, v] of Object.entries(value)) {
+    if (SENSITIVE_KEY_RE.test(key)) {
+      pairs.push(`${JSON.stringify(key)}:${JSON.stringify(IDEMPOTENCY_KEY_RE.test(key) ? idempotencyPrefix(v) : "[REDACTED]")}`);
+    } else {
+      pairs.push(`${JSON.stringify(key)}:${safeStringify(v, depth + 1, seen)}`);
+    }
+  }
+  return `{${pairs.join(",")}}`;
+}
+
+export function redactValue(value, { idempotencyKey = null } = {}) {
+  if (value instanceof Error) return formatError(value, { idempotencyKey });
+  if (typeof value === "string") return redactText(value, { idempotencyKey });
+  if (value == null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map((v) => redactValue(v, { idempotencyKey }));
+  const out = {};
+  for (const [key, v] of Object.entries(value)) {
+    if (SENSITIVE_KEY_RE.test(key)) {
+      out[key] = IDEMPOTENCY_KEY_RE.test(key)
+        ? idempotencyPrefix(v)
+        : "[REDACTED]";
+    } else {
+      out[key] = redactValue(v, { idempotencyKey });
+    }
+  }
+  return out;
+}
+
+/** Format an Error without ever dumping its raw enumerable properties. */
+export function formatError(error, { idempotencyKey = null } = {}) {
+  if (error == null) return "";
+  if (typeof error === "string") return redactText(error, { idempotencyKey });
+  if (!(error instanceof Error)) {
+    return redactText(safeStringify(error), { idempotencyKey });
+  }
+
+  const head = redactText(`${error.name || "Error"}: ${error.message || ""}`, { idempotencyKey });
+  const cause = error.cause
+    ? `\ncause: ${formatError(error.cause, { idempotencyKey })}`
+    : "";
+  const stack = error.stack
+    ? `\n${redactText(error.stack, { idempotencyKey })}`
+    : "";
+  return `${head}${cause}${stack}`;
+}
+
+function emit(level, message, error = null, context = null) {
+  const parts = [redactText(message)];
+  if (context && typeof context === "object" && Object.keys(context).length) {
+    parts.push(redactText(safeStringify(context)));
+  }
+  const detail = error == null ? "" : formatError(error);
+  const line = `${parts.join(" ")}${detail ? `\n${detail}` : ""}`;
+  // Use the current console method so tests and embedders can still capture
+  // structured events. installConsoleRedaction() makes this idempotent.
+  (console[level] || ORIGINAL[level])(line);
+}
+
+export function logInfo(message, error = null, context = null) {
+  emit("log", message, error, context);
+}
+
+export function logWarn(message, error = null, context = null) {
+  emit("warn", message, error, context);
+}
+
+export function logError(message, error = null, context = null) {
+  emit("error", message, error, context);
+}
+
+/**
+ * Defence in depth: wrap console.* so a future direct console call cannot dump
+ * a raw Error or an unredacted URL. Safe to call more than once.
+ */
+export function installConsoleRedaction() {
+  if (installed) return;
+  installed = true;
+  for (const level of ["log", "info", "warn", "error", "debug"]) {
+    console[level] = (...args) => {
+      const safe = args.map((arg) =>
+        arg instanceof Error
+          ? formatError(arg)
+          : typeof arg === "string"
+            ? redactText(arg)
+            : arg,
+      );
+      ORIGINAL[level](...safe);
+    };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verify402-mcp",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "mcpName": "io.github.a32116150-ctrl/verify402-mcp",
   "description": "MCP server for verify402: a free, fail-closed preflight gate before signing, plus five paid on-chain checks paid per call via x402.",
   "type": "module",
@@ -12,6 +12,8 @@
     "index.mjs",
     "budget.mjs",
     "payment-policy.mjs",
+    "paid-call.mjs",
+    "log.mjs",
     "README.md",
     ".env.example",
     "LICENSE",
@@ -19,7 +21,7 @@
   ],
   "scripts": {
     "start": "node index.mjs",
-    "test": "node --test test/payment-policy.test.mjs"
+    "test": "node --test test/payment-policy.test.mjs test/first-payment.test.mjs test/paid-call.test.mjs test/bridge-client.test.mjs"
   },
   "engines": {
     "node": ">=20"
@@ -52,8 +54,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
-    "@x402/axios": "^2.28.0",
-    "@x402/evm": "^2.28.0",
+    "@x402/axios": "2.28.0",
+    "@x402/evm": "2.28.0",
     "axios": "^1.13.2",
     "dotenv": "^16.4.5",
     "viem": "^2.39.0",

package/paid-call.mjs

@@ -0,0 +1,73 @@
+// One paid operation = one idempotency key, reused on every retry.
+//
+// The key is a bearer credential (see README/recovery docs), so it is never
+// logged or returned to the MCP client. The bridge only needs it to survive a
+// lost response: the server returns the settled verdict with
+// recovery.replayed=true instead of charging a second time.
+//
+// Retry rules:
+//   * network/timeout/5xx-gateway failures: retry with the SAME key
+//   * 402: never retry here (the x402 wrapper owns the payment handshake)
+//   * 409: never retry (a conflicting body will not become valid)
+
+import { randomUUID } from "node:crypto";
+
+export const DEFAULT_RETRIES = 2;
+
+const RETRYABLE_CODES = new Set([
+  "ECONNABORTED",
+  "ECONNRESET",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "EPIPE",
+  "ETIMEDOUT",
+  "EAI_AGAIN",
+  "ERR_NETWORK",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "UND_ERR_HEADERS_TIMEOUT",
+  "UND_ERR_BODY_TIMEOUT",
+  "UND_ERR_SOCKET",
+]);
+
+const RETRYABLE_STATUS = new Set([502, 503, 504]);
+
+export function isRetryable(error) {
+  const status = error?.response?.status;
+  if (status != null) return RETRYABLE_STATUS.has(status);
+  if (RETRYABLE_CODES.has(error?.code)) return true;
+  // Axios tags transport failures as isAxiosError with no response. Anything
+  // else (bad config, programmer error) is not retried.
+  return error?.isAxiosError === true;
+}
+
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * POST a paid operation with one generated idempotency key.
+ *
+ * @param {{post: Function}} paidApi - x402-wrapped axios instance (or a fake)
+ * @param {string} route
+ * @param {object} body
+ * @param {{idempotencyKey?: string, retries?: number, sleep?: Function}} options
+ * @returns {Promise<object>} the final axios response
+ */
+export async function paidPost(paidApi, route, body, {
+  idempotencyKey = randomUUID(),
+  retries = DEFAULT_RETRIES,
+  sleep = delay,
+} = {}) {
+  let lastError;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      return await paidApi.post(route, body, {
+        headers: { "x-idempotency-key": idempotencyKey },
+      });
+    } catch (error) {
+      lastError = error;
+      if (!isRetryable(error) || attempt === retries) throw error;
+      // Keep the same key: a retry after a lost response must replay, not pay.
+      await sleep(250 * (attempt + 1));
+    }
+  }
+  throw lastError;
+}

package/payment-policy.mjs

@@ -3,20 +3,284 @@
 // The bridge is a payer, not a blank cheque for any remote 402. Before a
 // signature exists, the policy requires:
 //
-//   - the network to be explicitly allowlisted (default Base mainnet);
+//   - the network to be explicitly allowlisted (the public demo default is
+//     Base Sepolia testnet, eip155:84532);
 //   - payTo to be the verify402 payee (default the EVM payTo);
 //   - the 402 resource to be on the configured server and a known paid route.
 //
-// The amount cap and the default-asset (USDC) allowlist are enforced by
-// x402Client's spendControls, which run before this policy. Redirects are
-// refused by the axios client in index.mjs.
+// The amount cap and the canonical-USDC allowlist are enforced both by
+// x402Client's spendControls and by validatePaymentChallenge(), which runs
+// before the signing hook in first-payment.mjs and index.mjs. Redirects are
+// refused by the axios clients in index.mjs and first-payment.mjs.
+//
+// Mainnet is available only through an explicit VERIFY402_NETWORKS value. The
+// demo default must never silently select Base mainnet.
 //
 // Free-only mode never imports or constructs this policy.
 
-export const DEFAULT_NETWORKS = ["eip155:8453"];
+export const DEMO_NETWORK = "eip155:84532";
+export const MAINNET_NETWORK = "eip155:8453";
+export const DEFAULT_NETWORKS = [DEMO_NETWORK];
 export const DEFAULT_PAY_TO = "0xAeEF086DD4e436c69d6d0F684b4c9F43392df9cb";
 export const DEFAULT_PAID_ROUTES = ["/verify", "/safety", "/route", "/quotecheck", "/depth"];
 
+// Hard upper bound for a single EIP-3009 authorization. The SDK signs
+// `validBefore = now + maxTimeoutSeconds`; an unbounded value hands the payee a
+// long-lived transferable authorization. 300 seconds is the documented cap and
+// matches the live verify402 challenge.
+export const MAX_TIMEOUT_SECONDS = 300;
+
+// The canonical USDC contract for each network this bridge knows how to pay.
+// A 402 that names a different asset on one of these networks is a different
+// payment, not a cheaper one, so the guard refuses it.
+export const DEMO_USDC = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
+export const MAINNET_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+export const NETWORK_USDC = {
+  [DEMO_NETWORK]: DEMO_USDC,
+  [MAINNET_NETWORK]: MAINNET_USDC,
+};
+
+// EIP-712 domain parameters for the canonical USDC contract on each supported
+// network. These are signing-relevant: a server that supplies a different
+// `extra.name`/`extra.version` asks the wallet to sign a different token
+// domain. Values mirror the installed @x402/evm default-asset table.
+export const NETWORK_USDC_DOMAIN = {
+  [DEMO_NETWORK]: { name: "USDC", version: "2" },
+  [MAINNET_NETWORK]: { name: "USD Coin", version: "2" },
+};
+
+// The only networks the bridge will ever register a signer for. VERIFY402_NETWORKS
+// is constrained to this map; an arbitrary eip155:<chainId> is refused rather
+// than inferred from an asset the SDK happens to recognise.
+export const SUPPORTED_PAYMENT_NETWORKS = new Set(Object.keys(NETWORK_USDC));
+
+const EVM_ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+const CAIP2_RE = /^[a-z0-9][a-z0-9-]*:[A-Za-z0-9._:-]+$/;
+const SUPPORTED_NETWORK_NAMESPACES = new Set(["eip155", "solana"]);
+
+// `extra` fields that do not change how a payload is signed. Everything else on
+// an EVM requirement is a signing-mode extension and is refused until it is
+// explicitly validated here.
+const EVM_EXTRA_ALLOWED_KEYS = new Set(["name", "version", "assetTransferMethod", "paymentFlow"]);
+
+/**
+ * Convert a USD amount to six-decimal atomic units. Returns null when the
+ * value is not a positive finite number, so callers fail closed instead of
+ * rounding a bad cap into zero or Infinity.
+ */
+export function usdToAtomic(value) {
+  const parsed = typeof value === "string" ? Number(value.replace(/^\$/, "").trim()) : Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return null;
+  return BigInt(Math.round(parsed * 1e6));
+}
+
+function normalizeUrl(value) {
+  try {
+    const url = new URL(String(value));
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    return url;
+  } catch {
+    return null;
+  }
+}
+
+// Exact resource identity: origin + path are compared with no trailing-slash
+// normalisation, so `/route/` is not `/route`.
+function resourceKey(url) {
+  return `${url.origin}${url.pathname}`;
+}
+
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Validate `maxTimeoutSeconds` as a positive integer no greater than the
+ * documented cap. Strings, floats, NaN, infinities, zero and negatives are all
+ * refused before any arithmetic happens.
+ */
+function validateTimeoutSeconds(value) {
+  if (typeof value !== "number") return "maxTimeoutSeconds must be a number";
+  if (!Number.isInteger(value)) return "maxTimeoutSeconds must be an integer";
+  if (value <= 0) return "maxTimeoutSeconds must be positive";
+  if (value > MAX_TIMEOUT_SECONDS) {
+    return `maxTimeoutSeconds ${value} exceeds the ${MAX_TIMEOUT_SECONDS}s maximum`;
+  }
+  return null;
+}
+
+/**
+ * Validate the EIP-712 domain and transfer mode of an EVM requirement. The
+ * installed SDK selects EIP-3009 unless `extra.assetTransferMethod === "permit2"`,
+ * so permit2 (and any unvalidated extension key) is refused here.
+ */
+function validateEvmExtra(requirement, index, expectedDomainByNetwork) {
+  const prefix = `402 accepts[${index}]`;
+  const extra = requirement.extra;
+  if (!isPlainObject(extra)) return `${prefix} has no valid extra`;
+  if (extra.assetTransferMethod !== undefined && extra.assetTransferMethod !== "eip3009") {
+    return `${prefix} transfer method ${String(extra.assetTransferMethod)} is not supported`;
+  }
+  if (extra.paymentFlow !== undefined && extra.paymentFlow !== "authorization") {
+    return `${prefix} paymentFlow ${String(extra.paymentFlow)} is not supported`;
+  }
+  for (const key of Object.keys(extra)) {
+    if (!EVM_EXTRA_ALLOWED_KEYS.has(key)) {
+      return `${prefix} extra.${key} is not a supported signing extension`;
+    }
+  }
+  if (typeof extra.name !== "string" || !extra.name.trim()) {
+    return `${prefix} EIP-712 domain name is missing`;
+  }
+  if (typeof extra.version !== "string" || !extra.version.trim()) {
+    return `${prefix} EIP-712 domain version is missing`;
+  }
+  const expectedDomain = expectedDomainByNetwork?.[requirement.network];
+  if (expectedDomain) {
+    if (extra.name !== expectedDomain.name || extra.version !== expectedDomain.version) {
+      return `${prefix} EIP-712 domain ${extra.name}/${extra.version} is not the canonical USDC domain for ${requirement.network}`;
+    }
+  }
+  return null;
+}
+
+/**
+ * Validate a complete x402 v2 challenge before a payer is allowed to sign.
+ *
+ * This is deliberately stricter than "pick an acceptable requirement": every
+ * offered requirement is checked, and every EVM option must be on an
+ * allowlisted network, name the configured payee, use the canonical USDC asset
+ * and EIP-712 domain for that network, pin EIP-3009, and stay under the
+ * per-payment cap. A mixed challenge that also offers Base mainnet is refused
+ * as a whole, not silently filtered down to the testnet option.
+ *
+ * Returns `{ ok: true, requirement }` for the selected EVM requirement, or
+ * `{ ok: false, reason }`. Missing or malformed fields are failures.
+ */
+export function validatePaymentChallenge(challenge, {
+  allowedNetworks = DEFAULT_NETWORKS,
+  allowedPayTo = DEFAULT_PAY_TO,
+  expectedResource,
+  maxAmountUsd,
+  expectedAssetByNetwork = NETWORK_USDC,
+  expectedDomainByNetwork = NETWORK_USDC_DOMAIN,
+} = {}) {
+  const fail = (reason) => ({ ok: false, reason });
+
+  if (!isPlainObject(challenge)) {
+    return fail("402 challenge is not an object");
+  }
+  if (challenge.x402Version !== 2) {
+    return fail("402 challenge is not x402 v2");
+  }
+  if (!Array.isArray(challenge.accepts) || challenge.accepts.length === 0) {
+    return fail("402 challenge has no accepts[]");
+  }
+
+  const resource = normalizeUrl(challenge.resource?.url ?? challenge.resource);
+  if (!resource) {
+    return fail("402 challenge has no valid resource URL");
+  }
+  if (resource.search || resource.hash) {
+    return fail("402 resource must not contain a query or fragment");
+  }
+  if (expectedResource !== undefined) {
+    const expected = normalizeUrl(expectedResource);
+    if (!expected) return fail("expected resource is not a valid http(s) URL");
+    if (resourceKey(resource) !== resourceKey(expected)) {
+      return fail(`402 resource ${resource.href} is not the expected ${expected.href}`);
+    }
+  }
+
+  const networks = new Set(allowedNetworks);
+  const expectedPayTo = String(allowedPayTo ?? "").trim().toLowerCase();
+  if (!EVM_ADDRESS_RE.test(expectedPayTo)) {
+    return fail("no valid expected payee is configured");
+  }
+
+  const maxAtomic = maxAmountUsd === undefined ? null : usdToAtomic(maxAmountUsd);
+  if (maxAmountUsd !== undefined && maxAtomic === null) {
+    return fail("configured maximum payment amount is not a positive USD value");
+  }
+
+  let selected = null;
+  for (const [index, requirement] of challenge.accepts.entries()) {
+    const prefix = `402 accepts[${index}]`;
+
+    if (!isPlainObject(requirement)) {
+      return fail(`${prefix} is not an object`);
+    }
+
+    const network = requirement.network;
+    if (typeof network !== "string" || !CAIP2_RE.test(network)) {
+      return fail(`${prefix} has no valid network`);
+    }
+    const namespace = network.split(":")[0];
+    if (!SUPPORTED_NETWORK_NAMESPACES.has(namespace)) {
+      return fail(`${prefix} network ${network} is unsupported`);
+    }
+
+    const scheme = requirement.scheme;
+    if (scheme !== "exact") {
+      return fail(`${prefix} scheme ${String(scheme)} is not exact`);
+    }
+
+    const timeoutError = validateTimeoutSeconds(requirement.maxTimeoutSeconds);
+    if (timeoutError) {
+      return fail(`${prefix} ${timeoutError}`);
+    }
+
+    const amount = requirement.amount;
+    if (typeof amount !== "string" || !/^\d+$/.test(amount) || BigInt(amount) <= 0n) {
+      return fail(`${prefix} has no valid amount`);
+    }
+
+    const asset = requirement.asset;
+    if (typeof asset !== "string" || !asset.trim()) {
+      return fail(`${prefix} has no asset`);
+    }
+
+    if (namespace !== "eip155") continue;
+
+    if (!networks.has(network)) {
+      return fail(`${prefix} network ${network} is not an allowed EVM network`);
+    }
+    if (!EVM_ADDRESS_RE.test(asset)) {
+      return fail(`${prefix} asset is not an EVM token address`);
+    }
+
+    const expectedAsset = expectedAssetByNetwork?.[network];
+    if (!expectedAsset) {
+      return fail(`no canonical USDC asset is configured for ${network}`);
+    }
+    if (asset.toLowerCase() !== expectedAsset.toLowerCase()) {
+      return fail(`${prefix} asset ${asset} is not the canonical USDC for ${network}`);
+    }
+
+    const payTo = String(requirement.payTo ?? "").trim();
+    if (!EVM_ADDRESS_RE.test(payTo)) {
+      return fail(`${prefix} has no valid payee`);
+    }
+    if (payTo.toLowerCase() !== expectedPayTo) {
+      return fail(`${prefix} payee ${payTo} is not the configured payee`);
+    }
+
+    const extraError = validateEvmExtra(requirement, index, expectedDomainByNetwork);
+    if (extraError) return fail(extraError);
+
+    if (maxAtomic !== null && BigInt(amount) > maxAtomic) {
+      return fail(`${prefix} amount ${amount} exceeds the ${maxAmountUsd} USD cap`);
+    }
+
+    if (!selected) selected = requirement;
+  }
+
+  if (!selected) {
+    return fail("402 challenge offers no allowed EVM payment requirement");
+  }
+  return { ok: true, requirement: selected };
+}
+
 function parseNetworks(raw) {
   const values = Array.isArray(raw) ? raw : String(raw ?? "").split(",");
   const networks = values.map((value) => String(value).trim()).filter(Boolean);
@@ -27,6 +291,12 @@ function parseNetworks(raw) {
     if (!/^eip155:\d+$/.test(network)) {
       throw new Error(`VERIFY402_NETWORKS: ${network} is not an eip155:<chainId> network`);
     }
+    if (!SUPPORTED_PAYMENT_NETWORKS.has(network)) {
+      throw new Error(
+        `VERIFY402_NETWORKS: ${network} is not a supported payment network ` +
+          `(supported: ${[...SUPPORTED_PAYMENT_NETWORKS].join(", ")})`,
+      );
+    }
   }
   return [...new Set(networks)];
 }
@@ -102,6 +372,10 @@ export function createPaymentPolicy({
     /**
      * x402Client onBeforePaymentCreation hook: runs after selection and before
      * the scheme creates a signature. Returning `{ abort: true }` fails closed.
+     *
+     * This is the resource/route layer of the policy. The full challenge and
+     * the selected requirement are validated by createPaymentGuard(), which
+     * wraps this method for both payers.
      */
     checkBeforeSign(context) {
       const rawResource = context?.paymentRequired?.resource;
@@ -117,6 +391,10 @@ export function createPaymentPolicy({
         return { abort: true, reason: `402 resource is not a URL: ${String(resourceUrl)}` };
       }
 
+      if (url.search || url.hash) {
+        return { abort: true, reason: "402 resource must not contain a query or fragment" };
+      }
+
       if (url.origin !== prefix.origin) {
         return {
           abort: true,
@@ -143,7 +421,7 @@ export function createPaymentPolicy({
       }
 
       const requirement = context?.selectedRequirements;
-      if (!requirement) {
+      if (!requirement || typeof requirement !== "object") {
         return { abort: true, reason: "402 selected no payment requirement" };
       }
       if (
@@ -160,3 +438,116 @@ export function createPaymentPolicy({
     },
   };
 }
+
+/**
+ * Build the pre-signature guard shared by every payer. It validates the whole
+ * 402 challenge, proves the SDK's selected requirement is the exact object that
+ * was validated, re-validates that object, and then applies the resource/route
+ * layer in policy.checkBeforeSign().
+ *
+ * `expectedResource` may be a fixed string (the standalone payer and the smoke
+ * preflight, which know their one resource) or a resolver returning the
+ * resource bound to the current invocation (the MCP bridge, where each paid
+ * tool names its own route). A resolver that returns nothing aborts: the guard
+ * never signs a challenge that is not tied to locally known tool configuration.
+ *
+ * Returns a hook `(context) => { abort: true, reason } | undefined` suitable
+ * for x402Client.onBeforePaymentCreation().
+ */
+export function createPaymentGuard(policy, {
+  expectedResource,
+  maxAmountUsd,
+  expectedAssetByNetwork = NETWORK_USDC,
+  expectedDomainByNetwork = NETWORK_USDC_DOMAIN,
+} = {}) {
+  if (!policy || !Array.isArray(policy.allowedNetworks)) {
+    throw new Error("createPaymentGuard requires a payment policy");
+  }
+  if (
+    expectedResource !== undefined &&
+    typeof expectedResource !== "string" &&
+    typeof expectedResource !== "function"
+  ) {
+    throw new Error("expectedResource must be a string or a resolver function");
+  }
+
+  const isResolver = typeof expectedResource === "function";
+  const resolveExpectedResource = (context) => {
+    const value = isResolver ? expectedResource(context) : expectedResource;
+    if (typeof value === "string" && value !== "") return value;
+    return null;
+  };
+
+  const baseOptions = {
+    allowedNetworks: policy.allowedNetworks,
+    allowedPayTo: policy.allowedPayTo,
+    maxAmountUsd,
+    expectedAssetByNetwork,
+    expectedDomainByNetwork,
+  };
+
+  return function guard(context) {
+    const challenge = context?.paymentRequired;
+    const resolvedExpectedResource = resolveExpectedResource(context);
+    if (isResolver && resolvedExpectedResource === null) {
+      return { abort: true, reason: "no expected payment resource is bound to this call" };
+    }
+    if (!isResolver && expectedResource !== undefined && resolvedExpectedResource === null) {
+      return { abort: true, reason: "no expected payment resource for this payment" };
+    }
+    const options = resolvedExpectedResource === null
+      ? baseOptions
+      : { ...baseOptions, expectedResource: resolvedExpectedResource };
+
+    const validation = validatePaymentChallenge(challenge, options);
+    if (!validation.ok) return { abort: true, reason: validation.reason };
+
+    const selected = context?.selectedRequirements;
+    if (!selected || typeof selected !== "object") {
+      return { abort: true, reason: "402 selected no payment requirement" };
+    }
+
+    const selectedValidation = validatePaymentChallenge(
+      { ...challenge, accepts: [selected] },
+      options,
+    );
+    if (!selectedValidation.ok) return { abort: true, reason: selectedValidation.reason };
+    if (selectedValidation.requirement !== selected) {
+      return { abort: true, reason: "selected payment requirement changed after validation" };
+    }
+
+    // Reference identity: the SDK selector returns an element of
+    // paymentRequired.accepts, so a clone/substitution is refused here.
+    if (!Array.isArray(challenge.accepts) || !challenge.accepts.includes(selected)) {
+      return { abort: true, reason: "selected payment requirement is not from the 402 challenge" };
+    }
+
+    if (typeof policy.checkBeforeSign === "function") {
+      const resourceCheck = policy.checkBeforeSign(context);
+      if (resourceCheck?.abort) return resourceCheck;
+    }
+
+    return;
+  };
+}
+
+/**
+ * Build the paid-call policy from the bridge's documented environment.
+ *
+ * The default is deliberately Base Sepolia testnet. Base mainnet is selected
+ * only when VERIFY402_NETWORKS explicitly names eip155:8453. An explicitly
+ * empty network list or payee throws, so a typo cannot widen the policy.
+ */
+export function createPaymentPolicyFromEnv({
+  resourcePrefix,
+  paidRoutes = DEFAULT_PAID_ROUTES,
+  env = process.env,
+} = {}) {
+  return createPaymentPolicy({
+    networks: env.VERIFY402_NETWORKS === undefined ? DEFAULT_NETWORKS : env.VERIFY402_NETWORKS,
+    payTo: env.VERIFY402_PAY_TO === undefined ? DEFAULT_PAY_TO : env.VERIFY402_PAY_TO,
+    resourcePrefix:
+      env.VERIFY402_RESOURCE_PREFIX === undefined ? resourcePrefix : env.VERIFY402_RESOURCE_PREFIX,
+    paidRoutes,
+  });
+}