@quackai/q402-mcp 0.5.12 → 0.5.14

package/dist/index.js

@@ -14,7 +14,13 @@ import { homedir } from "os";
 import { join } from "path";
 import { isAddress } from "ethers";
 var Q402_ENV_FILE = join(homedir(), ".q402", "mcp.env");
+var lastReadError = null;
+function getQ402EnvFileReadError() {
+  return lastReadError;
+}
+var MAX_ENV_FILE_BYTES = 64 * 1024;
 function loadQ402EnvFileFromPath(path) {
+  lastReadError = null;
   if (!existsSync(path)) return {};
   if (process.platform !== "win32") {
     try {
@@ -28,15 +34,26 @@ function loadQ402EnvFileFromPath(path) {
     } catch {
     }
   }
+  try {
+    const size = statSync(path).size;
+    if (size > MAX_ENV_FILE_BYTES) {
+      const msg = `file is ${size} bytes (max ${MAX_ENV_FILE_BYTES}); refusing to load. Check ~/.q402/mcp.env \u2014 is it a misdirected log file or symlink?`;
+      lastReadError = msg;
+      process.stderr.write(`[q402-mcp] warning: ${msg}
+`);
+      return {};
+    }
+  } catch {
+  }
   const out = {};
   let raw;
   try {
     raw = readFileSync(path, "utf-8");
   } catch (e) {
-    process.stderr.write(
-      `[q402-mcp] warning: could not read ${path}: ${e instanceof Error ? e.message : String(e)}
-`
-    );
+    const msg = `could not read ${path}: ${e instanceof Error ? e.message : String(e)}`;
+    lastReadError = msg;
+    process.stderr.write(`[q402-mcp] warning: ${msg}
+`);
     return {};
   }
   if (raw.charCodeAt(0) === 65279) raw = raw.slice(1);
@@ -169,7 +186,7 @@ var isValidPrivateKey = (s) => typeof s === "string" && PRIVATE_KEY_RE.test(s);
 
 // src/version.ts
 var PACKAGE_NAME = "@quackai/q402-mcp";
-var PACKAGE_VERSION = "0.5.12";
+var PACKAGE_VERSION = "0.5.14";
 
 // src/tools/quote.ts
 import { z } from "zod";
@@ -505,7 +522,15 @@ var Q402NodeClient = class _Q402NodeClient {
   }
   async fetchFacilitator() {
     const url = `${this.opts.relayBaseUrl.replace(/\/$/, "")}/relay/info`;
-    const resp = await fetch(url, { signal: AbortSignal.timeout(1e4) });
+    let resp;
+    try {
+      resp = await fetch(url, { signal: AbortSignal.timeout(1e4) });
+    } catch (e) {
+      if (e instanceof Error && (e.name === "TimeoutError" || /aborted/i.test(e.message))) {
+        throw new Error("Q402 relay didn't respond within 10s while reading facilitator info \u2014 the relay may be temporarily degraded. Safe to retry.");
+      }
+      throw e;
+    }
     if (!resp.ok) {
       throw new Error(
         `failed to fetch relay facilitator info from ${url} (${resp.status})`
@@ -576,12 +601,20 @@ var Q402NodeClient = class _Q402NodeClient {
       facilitator
     };
     const body = chain.key === "xlayer" ? { ...baseBody, xlayerNonce: paymentNonce.toString() } : chain.key === "stable" ? { ...baseBody, stableNonce: paymentNonce.toString() } : { ...baseBody, nonce: paymentNonce.toString() };
-    const resp = await fetch(`${relayBaseUrl.replace(/\/$/, "")}/relay`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(body),
-      signal: AbortSignal.timeout(3e4)
-    });
+    let resp;
+    try {
+      resp = await fetch(`${relayBaseUrl.replace(/\/$/, "")}/relay`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(3e4)
+      });
+    } catch (e) {
+      if (e instanceof Error && (e.name === "TimeoutError" || /aborted/i.test(e.message))) {
+        throw new Error("Q402 relay didn't respond within 30s \u2014 the relay may be temporarily degraded. Safe to retry.");
+      }
+      throw e;
+    }
     const data = await resp.json();
     if (!resp.ok) {
       throw new Error(data.error ?? `relay failed (HTTP ${resp.status})`);
@@ -692,18 +725,26 @@ var Q402NodeClient = class _Q402NodeClient {
         authorization
       });
     }
-    const resp = await fetch(`${relayBaseUrl.replace(/\/$/, "")}/relay/batch`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        apiKey,
-        chain: chain.key,
-        token,
-        facilitator,
-        recipients: signedRows
-      }),
-      signal: AbortSignal.timeout(6e4)
-    });
+    let resp;
+    try {
+      resp = await fetch(`${relayBaseUrl.replace(/\/$/, "")}/relay/batch`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          apiKey,
+          chain: chain.key,
+          token,
+          facilitator,
+          recipients: signedRows
+        }),
+        signal: AbortSignal.timeout(6e4)
+      });
+    } catch (e) {
+      if (e instanceof Error && (e.name === "TimeoutError" || /aborted/i.test(e.message))) {
+        throw new Error("Q402 relay didn't respond within 60s on the batch path \u2014 the relay may be temporarily degraded. Safe to retry.");
+      }
+      throw e;
+    }
     const data = await resp.json();
     if (!resp.ok || data.ok === false) {
       const err = new BatchPayError(
@@ -862,8 +903,14 @@ async function runPay(input) {
   };
 }
 function describeSandboxReason(resolvedKey, scope) {
+  const noApiKey = !resolvedKey.startsWith("q402_live_");
+  const noPk = !CONFIG.privateKey;
+  const noEnable = !CONFIG.realPaymentsRequested;
+  if (noApiKey && noPk && noEnable) {
+    return `You haven't configured Q402 yet. Say "Set up Q402" and I'll walk you through it (creates a settings file in your editor, you paste an API key from https://q402.quackai.ai/event, done).`;
+  }
   const missing = [];
-  if (!resolvedKey.startsWith("q402_live_")) missing.push("a live API key (must start with q402_live_)");
+  if (noApiKey) missing.push("a live API key (must start with q402_live_)");
   if (!CONFIG.privateKey) {
     missing.push("Q402_PRIVATE_KEY");
   } else if (!isValidPrivateKey(CONFIG.privateKey)) {
@@ -871,7 +918,7 @@ function describeSandboxReason(resolvedKey, scope) {
       "Q402_PRIVATE_KEY (currently the placeholder '0x...' \u2014 paste a real 0x + 64-hex key into ~/.q402/mcp.env)"
     );
   }
-  if (!CONFIG.realPaymentsRequested) missing.push("Q402_ENABLE_REAL_PAYMENTS=1");
+  if (noEnable) missing.push("Q402_ENABLE_REAL_PAYMENTS=1");
   if (missing.length === 0) return "Sandbox mode active (no env state change needed).";
   const tier = scope === "trial" ? "Free Trial" : "Multichain";
   const url = scope === "trial" ? "https://q402.quackai.ai/event" : "https://q402.quackai.ai/payment";
@@ -879,7 +926,7 @@ function describeSandboxReason(resolvedKey, scope) {
 }
 var PAY_TOOL = {
   name: "q402_pay",
-  description: "Send a gasless USDC, USDT, or RLUSD payment via Q402. Auto-routing: chain='bnb' + Q402_TRIAL_API_KEY set \u2192 Trial (free sponsored); anything else \u2192 Multichain (paid 9-chain). Same rule for q402_batch_pay. Set keyScope='trial' or 'multichain' to force one explicitly. Trial keys reject any non-BNB chain server-side with TRIAL_BNB_ONLY. Multichain keys cover avax, bnb, eth, xlayer, stable, mantle, injective, monad, scroll \u2014 USDC/USDT on most chains, RLUSD on Ethereum only, Injective USDT-only. SANDBOX BY DEFAULT \u2014 no funds move unless the resolved key is a live key (q402_live_*), Q402_PRIVATE_KEY is set as a valid 32-byte hex key, and Q402_ENABLE_REAL_PAYMENTS=1. Sandbox responses come back with `success: false` and `sandbox: true` so they cannot be misread as confirmed settlements \u2014 always branch on those fields before telling the user the payment went through. The recipient receives the full amount; the sender pays $0 in gas. \n\nSENDER ECHO \u2014 every response includes a `senderWallet` field with the address derived from the configured `Q402_PRIVATE_KEY`. Show this alongside the recipient/amount when you confirm the payment with the user (e.g. 'Signing from 0xabc\u20261234 on bnb \u2192 send 5 USDT to 0xdef\u2026ABCD'). Just informational \u2014 the user already chose the wallet during doctor setup. \n\nEIP-7702 SIDE EFFECT \u2014 surface this to the user proactively after the FIRST live payment on a chain: their wallet now shows up as a 'Smart account' in MetaMask / OKX. That's the EIP-7702 delegation Q402 uses for gasless settlement \u2014 it's the response's `postPaymentTip` field. Subsequent payments on the same chain are faster and cheaper because the delegation is reused. \n\nIf the user EVER reports that native gas tokens (BNB / ETH / AVAX / etc.) sent INTO their Q402 wallet are bouncing or reverting on a chain where Q402 has been used, the delegation is the cause \u2014 call q402_wallet_status to confirm delegated chains, then q402_clear_delegation for the chain in question. Q402 sponsors the gas for the clear, so the user pays $0. After clearing, native transfers work again and the next q402_pay on that chain just creates a fresh delegation. \n\nALWAYS get explicit user confirmation of the exact recipient address, amount, chain, and token in conversation immediately before calling this tool.",
+  description: "Send a gasless USDC, USDT, or RLUSD payment via Q402. Auto-routing: chain='bnb' + Q402_TRIAL_API_KEY set \u2192 Trial (free sponsored); anything else \u2192 Multichain (paid 9-chain). Same rule for q402_batch_pay. Set keyScope='trial' or 'multichain' to force one explicitly. Trial keys reject any non-BNB chain server-side with TRIAL_BNB_ONLY. Multichain keys cover avax, bnb, eth, xlayer, stable, mantle, injective, monad, scroll \u2014 USDC/USDT on most chains, RLUSD on Ethereum only, Injective USDT-only. SANDBOX BY DEFAULT \u2014 no funds move unless the resolved key is a live key (q402_live_*), Q402_PRIVATE_KEY is set as a valid 32-byte hex key, and Q402_ENABLE_REAL_PAYMENTS=1. Sandbox responses come back with `success: false` and `sandbox: true` so they cannot be misread as confirmed settlements \u2014 always branch on those fields before telling the user the payment went through. The recipient receives the full amount; the sender pays $0 in gas. \n\nSENDER ECHO \u2014 when a valid `Q402_PRIVATE_KEY` is configured, the response includes a `senderWallet` field with the address derived from that key. Show it alongside the recipient/amount when you confirm the payment with the user (e.g. 'Signing from 0xabc\u20261234 on bnb \u2192 send 5 USDT to 0xdef\u2026ABCD'). Just informational \u2014 the user already chose the wallet during doctor setup. Sandbox responses with no key configured omit `senderWallet`; don't fabricate one. \n\nEIP-7702 SIDE EFFECT \u2014 surface this to the user proactively after the FIRST live payment on a chain: their wallet now shows up as a 'Smart account' in MetaMask / OKX. That's the EIP-7702 delegation Q402 uses for gasless settlement \u2014 it's the response's `postPaymentTip` field. Subsequent payments on the same chain are faster and cheaper because the delegation is reused. \n\nIf the user EVER reports that native gas tokens (BNB / ETH / AVAX / etc.) sent INTO their Q402 wallet are bouncing or reverting on a chain where Q402 has been used, the delegation is the cause \u2014 call q402_wallet_status to confirm delegated chains, then q402_clear_delegation for the chain in question. Q402 sponsors the gas for the clear, so the user pays $0. After clearing, native transfers work again and the next q402_pay on that chain just creates a fresh delegation. \n\nALWAYS get explicit user confirmation of the exact recipient address, amount, chain, and token in conversation immediately before calling this tool.",
   inputSchema: {
     type: "object",
     properties: {
@@ -1069,8 +1116,14 @@ async function runBatchPay(input) {
   }
 }
 function describeSandboxReason2(resolvedKey, scope) {
+  const noApiKey = !resolvedKey.startsWith("q402_live_");
+  const noPk = !CONFIG.privateKey;
+  const noEnable = !CONFIG.realPaymentsRequested;
+  if (noApiKey && noPk && noEnable) {
+    return `You haven't configured Q402 yet. Say "Set up Q402" and I'll walk you through it (creates a settings file in your editor, you paste an API key from https://q402.quackai.ai/event, done).`;
+  }
   const missing = [];
-  if (!resolvedKey.startsWith("q402_live_")) missing.push("a live API key (must start with q402_live_)");
+  if (noApiKey) missing.push("a live API key (must start with q402_live_)");
   if (!CONFIG.privateKey) {
     missing.push("Q402_PRIVATE_KEY");
   } else if (!isValidPrivateKey(CONFIG.privateKey)) {
@@ -1078,7 +1131,7 @@ function describeSandboxReason2(resolvedKey, scope) {
       "Q402_PRIVATE_KEY (currently the placeholder '0x...' \u2014 paste a real 0x + 64-hex key into ~/.q402/mcp.env)"
     );
   }
-  if (!CONFIG.realPaymentsRequested) missing.push("Q402_ENABLE_REAL_PAYMENTS=1");
+  if (noEnable) missing.push("Q402_ENABLE_REAL_PAYMENTS=1");
   if (missing.length === 0) return "Sandbox mode active (no env state change needed).";
   const tier = scope === "trial" ? "Free Trial" : "Multichain";
   const url = scope === "trial" ? "https://q402.quackai.ai/event" : "https://q402.quackai.ai/payment";
@@ -1587,6 +1640,12 @@ var ENV_FILE_TEMPLATE = `# \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u250
 # Read automatically by @quackai/q402-mcp on startup.
 # Edit this file in your editor. NEVER paste your private key into chat.
 # After editing, restart your MCP client (Codex / Claude / Cursor / Cline).
+#
+# SAFE-BY-DEFAULT: this template ships with both api-key + private-key
+# lines COMMENTED OUT. Even though Q402_ENABLE_REAL_PAYMENTS defaults
+# to 1, the live-mode gate refuses to settle until BOTH a real api key
+# AND a valid 32-byte private key are configured. Saving this template
+# as-is and restarting your client just leaves you in sandbox.
 # \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
 
 # \u2500\u2500\u2500 API key \u2014 uncomment ONE (or both for auto-routing) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
@@ -1647,9 +1706,13 @@ function mask2(key) {
 }
 function detectPhase() {
   const anyKey = !!(CONFIG.trialApiKey || CONFIG.multichainApiKey || CONFIG.legacyApiKey);
-  const allEssentials = anyKey && !!CONFIG.privateKey && CONFIG.realPaymentsRequested && CONFIG.apiKeyKind === "live";
+  const hasValidPrivateKey = isValidPrivateKey(CONFIG.privateKey);
+  if (!Q402_ENV_FILE_PRESENT && !anyKey && !CONFIG.privateKey) {
+    return "first-install";
+  }
+  const allEssentials = anyKey && hasValidPrivateKey && CONFIG.realPaymentsRequested && CONFIG.apiKeyKind === "live";
   if (allEssentials) return "live-check";
-  if (anyKey || CONFIG.privateKey || CONFIG.realPaymentsRequested) return "needs-completion";
+  if (anyKey || CONFIG.privateKey || Q402_ENV_FILE_PRESENT) return "needs-completion";
   return "first-install";
 }
 async function verifyOneKey(scope, envVar, apiKey) {
@@ -1746,9 +1809,11 @@ async function fetchDelegation(address) {
 }
 async function runDoctor() {
   const phase = detectPhase();
+  const envFileReadError = getQ402EnvFileReadError();
   const envFile = {
     path: Q402_ENV_FILE_PATH,
-    exists: Q402_ENV_FILE_PRESENT
+    exists: Q402_ENV_FILE_PRESENT,
+    warning: envFileReadError ?? void 0
   };
   const envState = {
     Q402_TRIAL_API_KEY: envSlot(
@@ -1814,12 +1879,18 @@ async function runDoctor() {
   }
   const warnings = [];
   for (const name of Q402_ENV_FILE_KEYS_ALL) {
-    if (process.env[name] !== void 0 && Q402_ENV_FILE_KEYS_ALL.has(name) && !Q402_ENV_FILE_KEYS.has(name)) {
+    if (process.env[name] !== void 0 && !Q402_ENV_FILE_KEYS.has(name)) {
       warnings.push(
         `${name} is set in both your shell (process.env) AND ~/.q402/mcp.env \u2014 the shell value wins. Editing the file will have NO effect until you \`unset ${name}\` in your shell (or update the shell value to match).`
       );
     }
   }
+  const enableExplicit = process.env.Q402_ENABLE_REAL_PAYMENTS !== void 0 || Q402_ENV_FILE_KEYS_ALL.has("Q402_ENABLE_REAL_PAYMENTS");
+  if (CONFIG.legacyApiKey && CONFIG.realPaymentsRequested && !enableExplicit) {
+    warnings.push(
+      "You have a legacy Q402_API_KEY set, and Q402_ENABLE_REAL_PAYMENTS wasn't explicitly set by you \u2014 so it's defaulting to 1 (real payments) since v0.5.11. To stay in sandbox while you check this, add `Q402_ENABLE_REAL_PAYMENTS=0` to ~/.q402/mcp.env (or your shell) and restart the MCP client."
+    );
+  }
   if (phase !== "live-check") {
     return {
       package: PACKAGE_NAME,
@@ -1833,7 +1904,7 @@ async function runDoctor() {
       recommendedActions,
       greeting: phase === "first-install" ? `Q402 MCP is installed (v${PACKAGE_VERSION}).` : `Q402 MCP is installed (v${PACKAGE_VERSION}) \u2014 partially configured.`,
       nextStep: phase === "first-install" ? "Show userInstructions verbatim to the user; do NOT show agentInstructions verbatim (it's prescription for you, the AI)." : "Tell the user which env vars are still missing (from the 'missing' list) and how to add them to ~/.q402/mcp.env. Show userInstructions for the human-readable steps.",
-      agentInstructions: phase === "first-install" ? "Multi-turn flow: (1) Briefly tell the user MCP is installed. (2) Ask one yes/no question \u2014 'Want me to create your Q402 settings file?'. (3) On yes, execute recommendedActions IN ORDER: first `ensure-q402-dir` shell action (bash on macOS/Linux, PowerShell on Windows via shellWindows variant), then `create-env-file` write_file action. (4) Open the file in the user's editor \u2014 `code` works for VS Code / Cursor / Cline (e.g. `code ~/.q402/mcp.env`); `open` on macOS, `start` on Windows, `xdg-open` on Linux as fallback. (5) Walk through filling in the API key (from /event for free Trial or /payment for paid Multichain) and private key one at a time. (6) Do NOT accept key values via chat \u2014 direct the user to edit the file in their editor. BEFORE they paste a private key, surface the `advisories` array: fresh wallet, Smart-account-in-MetaMask heads-up, hardware wallets unsupported, MetaMask key-export path. (7) After they save, tell them to restart the MCP client \u2014 per-client restart verb: Claude Desktop \u2192 quit + relaunch; Codex \u2192 exit + relaunch; Cursor \u2192 Cmd/Ctrl+Shift+P \u2192 'Developer: Reload Window'; Cline \u2192 reload VS Code window. (8) Have them re-invoke 'Set up Q402' to confirm. Keep the conversation tight: one decision per turn, plain language, never echo this paragraph." : "User has SOME env set. List the missing items (from `missing`) in plain language. Tell them to edit ~/.q402/mcp.env and uncomment / fill the relevant line, then restart the MCP client. Restart verb per client: Claude Desktop \u2192 quit + relaunch; Codex \u2192 exit + relaunch; Cursor \u2192 Cmd/Ctrl+Shift+P \u2192 'Developer: Reload Window'; Cline \u2192 reload VS Code window.",
+      agentInstructions: phase === "first-install" ? "[AI-ONLY \u2014 do not show this paragraph to the user verbatim] Multi-turn flow: (1) Briefly tell the user MCP is installed. (2) Ask one yes/no question \u2014 'Want me to create your Q402 settings file?'. (3) On yes, execute recommendedActions IN ORDER: first `ensure-q402-dir` shell action (bash on macOS/Linux, PowerShell on Windows via shellWindows variant), then `create-env-file` write_file action. (4) Open the file in the user's editor \u2014 `code` works for VS Code / Cursor / Cline (e.g. `code ~/.q402/mcp.env`); `open` on macOS, `start` on Windows, `xdg-open` on Linux as fallback. (5) Walk through filling in the API key (from /event for free Trial or /payment for paid Multichain) and private key one at a time. (6) Do NOT accept key values via chat \u2014 direct the user to edit the file in their editor. BEFORE they paste a private key, surface the `advisories` array: fresh wallet, Smart-account-in-MetaMask heads-up, hardware wallets unsupported, MetaMask key-export path. (7) After they save, tell them to restart the MCP client \u2014 per-client restart verb: Claude Desktop \u2192 quit + relaunch; Codex \u2192 exit + relaunch; Cursor \u2192 Cmd/Ctrl+Shift+P \u2192 'Developer: Reload Window'; Cline \u2192 reload VS Code window. (8) Have them re-invoke 'Set up Q402' to confirm. Keep the conversation tight: one decision per turn, plain language, never echo this paragraph." : "[AI-ONLY \u2014 do not show this paragraph to the user verbatim] User has SOME env set. List the missing items (from `missing`) in plain language. Tell them to edit ~/.q402/mcp.env and uncomment / fill the relevant line, then restart the MCP client. Restart verb per client: Claude Desktop \u2192 quit + relaunch; Codex \u2192 exit + relaunch; Cursor \u2192 Cmd/Ctrl+Shift+P \u2192 'Developer: Reload Window'; Cline \u2192 reload VS Code window.",
       userInstructions: phase === "first-install" ? [
         "Q402 is installed. To start sending payments you need an API key and a wallet.",
         "I'll create a settings file for you \u2014 say yes and I'll set it up + open it in your editor.",
@@ -1873,11 +1944,12 @@ async function runDoctor() {
   if (verifyTargets.length === 0 && CONFIG.legacyApiKey) {
     verifyTargets.push({ scope: "legacy", envVar: "Q402_API_KEY", key: CONFIG.legacyApiKey });
   }
-  const [keys, delegation, relay] = await Promise.all([
+  const [keys, delegation] = await Promise.all([
     Promise.all(verifyTargets.map((t) => verifyOneKey(t.scope, t.envVar, t.key))),
-    walletAddress ? fetchDelegation(walletAddress) : Promise.resolve(void 0),
-    pingRelay()
+    walletAddress ? fetchDelegation(walletAddress) : Promise.resolve(void 0)
   ]);
+  const anyResponse = keys.some((k) => !k.error || !/timeout|unreachable|ENOTFOUND|ECONN/i.test(k.error));
+  const relay = anyResponse && keys.length > 0 ? { url: `${CONFIG.relayBaseUrl}/keys/verify`, reachable: true } : await pingRelay();
   for (const k of keys) if (k.slotWarning) warnings.push(k.slotWarning);
   for (const k of keys) {
     if (typeof k.remainingCredits === "number" && k.remainingCredits === 0) {
@@ -1890,9 +1962,19 @@ async function runDoctor() {
       );
     }
     if (!k.valid) {
-      warnings.push(
-        k.error ? `${k.envVar}: ${k.error}.` : `${k.envVar} verified as invalid by the relay \u2014 check the key value in ~/.q402/mcp.env.`
-      );
+      const isTrialExpired = (k.error ?? "").toLowerCase().includes("trial expired");
+      if (isTrialExpired && k.trialExpiresAt) {
+        const exp = new Date(k.trialExpiresAt);
+        const days = Math.floor((Date.now() - exp.getTime()) / 864e5);
+        const ago = days > 0 ? ` (${days} day${days === 1 ? "" : "s"} ago)` : "";
+        warnings.push(
+          `${k.envVar}: Trial expired on ${exp.toISOString().slice(0, 10)}${ago}. Upgrade to a Multichain plan at https://q402.quackai.ai/payment.`
+        );
+      } else {
+        warnings.push(
+          k.error ? `${k.envVar}: ${k.error}.` : `${k.envVar} verified as invalid by the relay \u2014 check the key value in ~/.q402/mcp.env.`
+        );
+      }
     }
   }
   if (relay && !relay.reachable) {
@@ -1917,7 +1999,7 @@ async function runDoctor() {
     recommendedActions,
     greeting: ready ? `Q402 MCP is ready (v${PACKAGE_VERSION}).` : `Q402 MCP is installed but has ${warnings.length} issue${warnings.length === 1 ? "" : "s"} to address.`,
     nextStep: ready ? "Show userInstructions verbatim. Then offer to make a small test quote (q402_quote) to confirm everything works end-to-end." : "Walk the user through each warning in order. Show userInstructions verbatim for the cleanup steps.",
-    agentInstructions: ready ? "Live mode is fully configured. Summarize the wallet address (mask middle), plan tier(s), remaining quota, and any non-zero delegation counts to the user as a checklist. Offer a tiny test (q402_quote, not q402_pay) to confirm. Don't echo the full keys array verbatim \u2014 pick the most useful 2-3 fields per scope." : "Walk the user through each warning IN ORDER, plain language. For slot-mismatch warnings, the fix is editing ~/.q402/mcp.env and restarting the client (Cursor / Cline: reload window; Claude / Codex: quit + relaunch). Surface body.error strings from any verify failure as the user-visible reason (e.g. 'your Trial expired 3 days ago', 'API key has been rotated') \u2014 don't generic-out to 'check the key value'.",
+    agentInstructions: ready ? "[AI-ONLY \u2014 do not show this paragraph to the user verbatim] Live mode is fully configured. Summarize the wallet address (mask middle), plan tier(s), remaining quota, and any non-zero delegation counts to the user as a checklist. Offer a tiny test (q402_quote, not q402_pay) to confirm. Don't echo the full keys array verbatim \u2014 pick the most useful 2-3 fields per scope." : "[AI-ONLY \u2014 do not show this paragraph to the user verbatim] Walk the user through each warning IN ORDER, plain language. For slot-mismatch warnings, the fix is editing ~/.q402/mcp.env and restarting the client (Cursor / Cline: reload window; Claude / Codex: quit + relaunch). Surface body.error strings from any verify failure as the user-visible reason (e.g. 'your Trial expired 3 days ago', 'API key has been rotated') \u2014 don't generic-out to 'check the key value'.",
     userInstructions: ready ? [
       `Your wallet: ${walletAddress ? walletAddress.slice(0, 6) + "\u2026" + walletAddress.slice(-4) : "(derive failed \u2014 check Q402_PRIVATE_KEY)"}`,
       "Q402 is live. You can now ask me to quote, pay, batch-pay, or check Trust Receipts.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quackai/q402-mcp",
-  "version": "0.5.12",
+  "version": "0.5.14",
   "description": "MCP server for Q402 — gasless USDC, USDT, and RLUSD payments across 9 EVM chains, callable from Claude (Desktop / Code), OpenAI Codex CLI, and any other Model Context Protocol client.",
   "mcpName": "io.github.bitgett/q402-mcp",
   "keywords": [