verify402-mcp 1.0.2 → 1.0.4

package/README.md

@@ -14,7 +14,7 @@ wallet that pays in USDC; the bridge never signs or sends a trade.
 |---|---|---|
 | `preflight_gate` | **free** | "Should I sign this payment request or transaction?" — PASS / CAUTION / BLOCK with reasons, `checked` / `notChecked`, and a short-lived receipt |
 | `verify_arbitrage` | $0.05 | "Is this cross-venue arbitrage opportunity real, right now?" |
-| `check_token_safety` | $0.10 | "Is this token safe to buy?" — TRUST / CAUTION / AVOID with evidence |
+| `check_token_safety` | $0.10 | "Is this token sellable at a realistic size, and what does the round trip cost?" — TRUST / CAUTION / AVOID with evidence; not a code audit |
 | `get_best_route` | $0.03 | "What would the chain actually pay for this swap?" — best route + every quoted venue |
 | `verify_quote_fairness` | $0.05 | "A broker/bot offered me this number — is it honest?" fair / overpaying / too_good_to_be_true |
 | `get_trade_depth` | $0.05 | "How big can I trade here before the round trip eats me?" — per-size impact, round-trip cost, capacity |
@@ -31,23 +31,24 @@ belongs in the executor that signs — verify the receipt, then sign. See
 for a deny-by-default reference that refuses to call the signer without a
 verified receipt.
 
-## Run
+## Distribution & Run
 
-The package is distributed as a versioned GitHub release tarball. No npm
-account is required.
+The package is officially published on npm as **[`verify402-mcp`](https://www.npmjs.com/package/verify402-mcp)** and indexed on the official [Model Context Protocol Registry](https://registry.modelcontextprotocol.io/).
+
+Run directly via `npx` (stdio transport):
 
 ```bash
-npx -y \
-  --package=https://github.com/a32116150-ctrl/verify402/releases/download/mcp-v1.0.2/verify402-mcp-1.0.2.tgz \
-  verify402-mcp --help
+npx -y verify402-mcp --help
 ```
 
-**Warm the cache first.** The first `npx` run installs the MCP SDK and `viem`;
-some clients kill a server that takes more than 30 seconds to start. Run the
-`--help` command once before adding it to an MCP client. After that, startup is
-fast.
+You can also install it globally:
+
+```bash
+npm install -g verify402-mcp
+verify402-mcp --help
+```
 
-From source:
+Or run from source:
 
 ```bash
 git clone https://github.com/a32116150-ctrl/verify402
@@ -56,47 +57,20 @@ npm ci
 node index.mjs --help
 ```
 
-## Free gate only (no key)
+---
 
-Omit `EVM_PRIVATE_KEY`. The server registers only `preflight_gate` and logs
-`free preflight_gate only`. Nothing can be charged.
+## AI Agent Integration (Step-by-Step)
 
-## Paid tools (dedicated hot wallet)
-
-Set a wallet with USDC on the payment network. Use a wallet with only the money
-you are willing to spend — never a main wallet. The key stays in your MCP client
-configuration or environment; the package never contains it.
-
-```
-EVM_PRIVATE_KEY=0x...        # optional; omit for free-only
-VERIFY402_URL=https://verify402.onrender.com
-MAX_PAYMENT_USD=0.25         # hard cap on ONE payment, enforced at signature time
-MAX_DAILY_USD=0.50           # optional cap for the UTC day, persisted
-SPEND_LEDGER_PATH=           # optional ledger path (default .spend-ledger.json)
-VERIFY402_NETWORKS=eip155:8453   # paid calls only; comma-separated EVM networks
-VERIFY402_PAY_TO=0xAeEF086DD4e436c69d6d0F684b4c9F43392df9cb
-# VERIFY402_RESOURCE_PREFIX=https://verify402.onrender.com
-```
-
-The paid client refuses a 402 that names another network or payee, a resource
-outside the configured server, or a non-paid route. It also refuses redirects.
-The amount cap and the USDC-only default-asset allowlist are enforced inside
-the x402 client, before a signature exists.
-
-### Claude Desktop / Cursor
-
-`claude_desktop_config.json`, or `.cursor/mcp.json`:
+### 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. 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
 {
   "mcpServers": {
     "verify402": {
       "command": "npx",
-      "args": [
-        "-y",
-        "--package=https://github.com/a32116150-ctrl/verify402/releases/download/mcp-v1.0.2/verify402-mcp-1.0.2.tgz",
-        "verify402-mcp"
-      ],
+      "args": ["-y", "verify402-mcp"],
       "env": {
         "VERIFY402_URL": "https://verify402.onrender.com"
       }
@@ -105,14 +79,41 @@ the x402 client, before a signature exists.
 }
 ```
 
-For paid tools, add `"EVM_PRIVATE_KEY": "0x..."`, `"MAX_PAYMENT_USD": "0.25"`
-and optionally `"MAX_DAILY_USD": "0.50"` to `env`. The free gate works without
-them.
+### Step 2: Paid Mode (Setting Up the Hot Wallet)
+To enable the 5 deep on-chain truth checks (`verify_arbitrage`, `check_token_safety`, `get_best_route`, `verify_quote_fairness`, `get_trade_depth`), configure a dedicated hot wallet that pays per call in USDC via x402:
 
-### OpenCode V2
+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.
+3. **Configure Environment Variables in Your MCP Client**:
+   - Set `EVM_PRIVATE_KEY` to the 64-character private key of the hot wallet.
+   - Set safety caps `MAX_PAYMENT_USD` (e.g., `"0.25"`) and `MAX_DAILY_USD` (e.g., `"1.00"`).
 
-`opencode.jsonc`, or the global `~/.config/opencode/opencode.jsonc`:
+**Paid Configuration Block (Claude Desktop, Cursor, Cline, Windsurf)**:
+```json
+{
+  "mcpServers": {
+    "verify402": {
+      "command": "npx",
+      "args": ["-y", "verify402-mcp"],
+      "env": {
+        "VERIFY402_URL": "https://verify402.onrender.com",
+        "EVM_PRIVATE_KEY": "0xYOUR_HOT_WALLET_PRIVATE_KEY",
+        "MAX_PAYMENT_USD": "0.25",
+        "MAX_DAILY_USD": "1.00",
+        "VERIFY402_NETWORKS": "eip155:8453",
+        "VERIFY402_PAY_TO": "0xAeEF086DD4e436c69d6d0F684b4c9F43392df9cb"
+      }
+    }
+  }
+}
+```
 
+### OpenCode V2 Configuration
+In `opencode.jsonc` (or `~/.config/opencode/opencode.jsonc`):
 ```jsonc
 {
   "$schema": "https://opencode.ai/config.json",
@@ -120,14 +121,12 @@ them.
     "servers": {
       "verify402": {
         "type": "local",
-        "command": [
-          "npx",
-          "-y",
-          "--package=https://github.com/a32116150-ctrl/verify402/releases/download/mcp-v1.0.2/verify402-mcp-1.0.2.tgz",
-          "verify402-mcp"
-        ],
+        "command": ["npx", "-y", "verify402-mcp"],
         "environment": {
-          "VERIFY402_URL": "https://verify402.onrender.com"
+          "VERIFY402_URL": "https://verify402.onrender.com",
+          "EVM_PRIVATE_KEY": "{env:EVM_PRIVATE_KEY}",
+          "MAX_PAYMENT_USD": "0.25",
+          "MAX_DAILY_USD": "1.00"
         }
       }
     }
@@ -135,13 +134,31 @@ them.
 }
 ```
 
-For paid tools, add `"EVM_PRIVATE_KEY": "{env:EVM_PRIVATE_KEY}"` to
-`environment` and export the key in the environment that starts OpenCode. Keep
-the secret out of the config file.
+---
+
+## How AI Agents Use verify402 (Prompt Examples)
+
+Once configured, your agent automatically sees the tools in its context. You can prompt it directly:
+
+- **Preflight Gate (Free)**:
+  > *"Before signing this transaction, call `preflight_gate` on the payment request / calldata. If it returns BLOCK, abort and explain why."*
+- **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)**:
+  > *"I was offered 0.35 WETH for 1,000 USDC. Run `verify_quote_fairness` to see if this is fair or if I'm overpaying."*
+- **Market Depth & Capacity ($0.05)**:
+  > *"Check `get_trade_depth` for WETH on Uniswap V3 to see how much slippage and impact a $50,000 swap would suffer."*
 
 ## 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
@@ -150,11 +167,13 @@ the secret out of the config file.
   `VERIFY402_NETWORKS`, `VERIFY402_PAY_TO`, and `VERIFY402_RESOURCE_PREFIX`.
   Defaults are Base mainnet and the public verify402 payee.
 - `MAX_PAYMENT_USD` is enforced inside the x402 client, before a signature
-  exists; removing it is a security regression.
+  exists; removing it is a security regression. The caps limit what the bridge
+  can authorize; they do **not** protect a compromised private key.
 - `preflight_gate` is a check, not a guarantee. Read `notChecked`: it does not
   screen recipient reputation or sanctions, audit contracts, simulate full
-  balance deltas, or protect against MEV. It catches the measurable signing
-  mistakes, not every scam.
+  balance deltas, audit the counterparty, scan tool descriptions or responses
+  for prompt injection, or protect against MEV. It catches the measurable
+  signing mistakes, not every scam.
 - Use the [reference executor](https://github.com/a32116150-ctrl/verify402/blob/master/examples/preflight-guard.mjs)
   when you want enforcement rather than advice.
 

package/index.mjs

@@ -29,15 +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";
 
+installConsoleRedaction();
 config();
 
+const VERSION = "1.0.4";
 const EVM_PRIVATE_KEY = process.env.EVM_PRIVATE_KEY;
 const SERVER_URL = process.env.VERIFY402_URL || "https://verify402.onrender.com";
+// 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.
+const CLIENT_HEADERS = {
+  "User-Agent": `verify402-mcp/${VERSION}`,
+  "X-Verify402-Client": `mcp/${VERSION}`,
+};
 // Preflight is free, so it does not go through the paying client. Keeping the
 // two clients separate means a misconfigured 402 on a free route can never
 // turn into a signature.
-const freeApi = axios.create({ baseURL: SERVER_URL, timeout: 30_000, maxRedirects: 0 });
+const freeApi = axios.create({ baseURL: SERVER_URL, timeout: 30_000, maxRedirects: 0, headers: CLIENT_HEADERS });
 // Spend guard: the x402 client refuses to SIGN any payment above this, before
 // a signature exists. Enforced inside x402Client (applySpendControls), not by
 // our own request code - so it cannot be bypassed by a caller.
@@ -73,7 +84,7 @@ The bridge signs x402 payments only; it never signs or sends a trade.
   process.exit(0);
 }
 if (process.argv.includes("--version") || process.argv.includes("-v")) {
-  console.log("1.0.2");
+  console.log(VERSION);
   process.exit(0);
 }
 
@@ -98,12 +109,12 @@ async function createPaidClient() {
     client.register(network, new ExactEvmScheme(account));
   }
   client.onBeforePaymentCreation((context) => policy.checkBeforeSign(context));
-  console.error(
+  logInfo(
     `paid policy: networks=${policy.allowedNetworks.join(",")} ` +
       `payee=${policy.allowedPayTo} resources=${policy.resourcePrefix} ` +
       `{${policy.paidRoutes.join(",")}}`,
   );
-  const axiosInstance = axios.create({ baseURL: SERVER_URL, timeout: 120_000, maxRedirects: 0 });
+  const axiosInstance = axios.create({ baseURL: SERVER_URL, timeout: 120_000, maxRedirects: 0, headers: CLIENT_HEADERS });
   return wrapAxiosWithPayment(axiosInstance, client);
 }
 
@@ -119,7 +130,13 @@ const dailyBudget = createDailyBudget({
 
 async function guardedPaidCall(route, run) {
   if (dailyBudget.enabled) dailyBudget.assert(route);
-  return run();
+  const res = await 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(`${route}: recovery.replayed=true (settled verdict returned without a second charge)`);
+  }
+  return res;
 }
 
 // ------------------------------------------------------------------ tools ---
@@ -130,26 +147,31 @@ 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.",
 };
@@ -157,7 +179,7 @@ const DESCRIPTIONS = {
 async function main() {
   const paidApi = PAID_ENABLED ? await createPaidClient() : null;
 
-  const server = new McpServer({ name: "verify402", version: "1.0.2" });
+  const server = new McpServer({ name: "verify402", version: VERSION });
 
   server.tool(
     "preflight_gate",
@@ -221,7 +243,11 @@ async function main() {
           isError: true,
           content: [{
             type: "text",
-            text: `preflight failed${status ? ` (${status})` : ""}: ${JSON.stringify(body ?? e.message)}. Do not sign without a verifiable receipt.`,
+            text: `preflight failed${status ? ` (${status})` : ""}: ${JSON.stringify(body ?? e.message)}. ${
+              status === 503
+                ? "No receipt was issued; stop and retry later."
+                : "Do not sign without a verifiable receipt."
+            }`,
           }],
         };
       }
@@ -236,13 +262,13 @@ 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,
+      const res = await guardedPaidCall("/verify", () => paidPost(paidApi, "/verify", {
+        chainId: args.chainId,
         target: String(args.target ?? "WETH").toUpperCase(),
         base: String(args.base ?? "USDC").toUpperCase(),
         size: args.size ?? 100000,
@@ -256,13 +282,13 @@ 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,
+      const res = await guardedPaidCall("/safety", () => paidPost(paidApi, "/safety", {
+        chainId: args.chainId,
         tokenAddress: String(args.tokenAddress ?? "").trim(),
         intendedUsd: args.intendedUsd ?? 500,
         offeredPriceUsd: args.offeredPriceUsd ?? null,
@@ -278,11 +304,11 @@ 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,
+      const res = await guardedPaidCall("/route", () => paidPost(paidApi, "/route", {
+        chainId: args.chainId,
         tokenIn: args.tokenIn,
         tokenOut: args.tokenOut,
         amountIn: args.amountIn,
@@ -300,11 +326,11 @@ 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,
+      const res = await guardedPaidCall("/quotecheck", () => paidPost(paidApi, "/quotecheck", {
+        chainId: args.chainId,
         tokenIn: args.tokenIn,
         tokenOut: args.tokenOut,
         amountIn: args.amountIn,
@@ -320,14 +346,14 @@ 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,
+      const res = await guardedPaidCall("/depth", () => paidPost(paidApi, "/depth", {
+        chainId: args.chainId,
         tokenAddress: args.tokenAddress,
         baseSymbol: args.baseSymbol ?? "USDC",
         sizesUsd: args.sizesUsd ?? null,
@@ -340,7 +366,7 @@ 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)`,
@@ -348,6 +374,6 @@ async function main() {
 }
 
 main().catch((e) => {
-  console.error("bridge failed:", e.message);
+  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.2",
+  "version": "1.0.4",
   "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",
@@ -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;
+}