verify402-mcp 1.0.3 → 1.0.4

package/README.md

@@ -62,7 +62,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
@@ -142,8 +142,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,6 +154,11 @@ 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

package/index.mjs

@@ -29,10 +29,13 @@ 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.3";
+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:
@@ -106,7 +109,7 @@ 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(",")}}`,
@@ -127,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 ---
@@ -138,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.",
 };
@@ -248,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,
@@ -268,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,
@@ -290,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,
@@ -312,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,
@@ -332,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,
@@ -352,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)`,
@@ -360,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.3",
+  "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;
+}