@quackai/q402-mcp 0.5.11 → 0.5.13

package/README.md

@@ -49,7 +49,7 @@ The agent calls `q402_doctor`. On first install, the tool tells the agent to:
 
 ### Manual setup (no AI)
 
-Create `~/.q402/mcp.env` yourself. The template below matches what `q402_doctor` writes — every secret line is commented out and `Q402_ENABLE_REAL_PAYMENTS` defaults to `0`. Uncomment the lines you need, paste real values, then flip the live flag to `1`. (Saving the template as-is is safe: invalid placeholders won't trip live mode.)
+Create `~/.q402/mcp.env` yourself. The template below matches what `q402_doctor` writes — every secret line is commented out and `Q402_ENABLE_REAL_PAYMENTS` defaults to `1`. Uncomment the lines you need and paste real values; the server only flips into live mode once both a `q402_live_*` API key AND a valid 32-byte private key are configured, so saving the template as-is is safe (placeholders stay in sandbox). Change the flag to `0` if you want to force sandbox even with real keys (e.g. for chained testing).
 
 ```bash
 # ~/.q402/mcp.env
@@ -149,7 +149,7 @@ Then export the values in `~/.zshrc` / `~/.bashrc`. See the [Codex config refere
 
 By default the MCP server operates in **sandbox mode**: `q402_pay` returns a random fake transaction hash with `success: false` and `sandbox: true`, no funds move, no gas-tank credit is consumed. That makes it safe to plug into any MCP client without worrying about an accidental payment — if the agent misreads the conversation and fires `q402_pay` before you intended, nothing moves AND the response cannot be mistaken for a confirmed settlement.
 
-To enable real on-chain transactions, the resolved API key must be live (`q402_live_*`), `Q402_PRIVATE_KEY` must be set to a valid 32-byte hex key, and `Q402_ENABLE_REAL_PAYMENTS=1`. The block below is the template `q402_doctor` writes to `~/.q402/mcp.env` — every secret line is commented out and the live flag defaults to `0`. Uncomment the lines you need, paste real values in your editor, then flip the flag to `1`:
+To enable real on-chain transactions, the resolved API key must be live (`q402_live_*`), `Q402_PRIVATE_KEY` must be set to a valid 32-byte hex key, and `Q402_ENABLE_REAL_PAYMENTS=1`. The block below is the template `q402_doctor` writes to `~/.q402/mcp.env` — every secret line is commented out and the live flag defaults to `1`. Uncomment the lines you need and paste real values in your editor; the live-mode gate only flips once a real key + valid PK are present, so saving the template as-is stays in sandbox. Change the flag to `0` if you want to force sandbox even with real keys (e.g. for chained testing on a paid plan):
 
 ```bash
 # Two-key model — uncomment ONE (or both for auto-routing).

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,17 +34,29 @@ 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);
   for (const line of raw.split(/\r?\n/)) {
     const t = line.trim();
     if (!t || t.startsWith("#")) continue;
@@ -168,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.11";
+var PACKAGE_VERSION = "0.5.13";
 
 // src/tools/quote.ts
 import { z } from "zod";
@@ -421,7 +439,7 @@ var QUOTE_TOOL = {
 };
 
 // src/tools/pay.ts
-import { isAddress as isAddress2 } from "ethers";
+import { isAddress as isAddress2, Wallet as Wallet2 } from "ethers";
 import { z as z2 } from "zod";
 
 // src/client.ts
@@ -504,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})`
@@ -575,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})`);
@@ -691,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(
@@ -810,6 +852,17 @@ async function runPay(input) {
     );
   }
   const guardsApplied = [];
+  let senderWallet;
+  if (CONFIG.privateKey && isValidPrivateKey(CONFIG.privateKey)) {
+    try {
+      const addr = new Wallet2(CONFIG.privateKey).address;
+      senderWallet = {
+        address: addr,
+        addressShort: `${addr.slice(0, 6)}\u2026${addr.slice(-4)}`
+      };
+    } catch {
+    }
+  }
   maxAmountGuard(input.amount, CONFIG.maxAmountPerCallUsd);
   guardsApplied.push(`max_amount<=${CONFIG.maxAmountPerCallUsd}`);
   recipientGuard(input.to, CONFIG.allowedRecipients);
@@ -828,7 +881,7 @@ async function runPay(input) {
     });
     guardsApplied.push("mode=sandbox");
     const setupHint = resolved.sandboxReason ?? describeSandboxReason(resolved.apiKey ?? "", resolved.scope);
-    return { result: result2, guardsApplied, setupHint };
+    return { result: result2, guardsApplied, setupHint, senderWallet };
   }
   const client = new Q402NodeClient({
     apiKey: resolved.apiKey,
@@ -845,14 +898,27 @@ async function runPay(input) {
   return {
     result,
     guardsApplied,
+    senderWallet,
     postPaymentTip: result.success ? `After this payment your EOA is EIP-7702-delegated to Q402's impl on ${chain.name} \u2014 MetaMask / OKX will show it as a 'Smart account'. That's normal and reversible: q402_clear_delegation removes the delegation on a specific chain (Q402 sponsors the gas, so you pay $0). If you ever try to receive native gas tokens directly to this EOA and the transfer reverts, the delegation is the cause \u2014 clear it for that chain first.` : void 0
   };
 }
 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 (!CONFIG.privateKey) missing.push("Q402_PRIVATE_KEY");
-  if (!CONFIG.realPaymentsRequested) missing.push("Q402_ENABLE_REAL_PAYMENTS=1");
+  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)) {
+    missing.push(
+      "Q402_PRIVATE_KEY (currently the placeholder '0x...' \u2014 paste a real 0x + 64-hex key into ~/.q402/mcp.env)"
+    );
+  }
+  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";
@@ -860,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\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 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.",
   inputSchema: {
     type: "object",
     properties: {
@@ -899,7 +965,7 @@ var PAY_TOOL = {
 };
 
 // src/tools/batch-pay.ts
-import { isAddress as isAddress3 } from "ethers";
+import { isAddress as isAddress3, Wallet as Wallet3 } from "ethers";
 import { z as z3 } from "zod";
 var RECIPIENT_LIMIT_TRIAL = 5;
 var RECIPIENT_LIMIT_PAID = 20;
@@ -964,6 +1030,17 @@ async function runBatchPay(input) {
   if (CONFIG.allowedRecipients.length > 0) {
     guardsApplied.push(`recipient_allowlist[${CONFIG.allowedRecipients.length}]`);
   }
+  let senderWallet;
+  if (CONFIG.privateKey && isValidPrivateKey(CONFIG.privateKey)) {
+    try {
+      const addr = new Wallet3(CONFIG.privateKey).address;
+      senderWallet = {
+        address: addr,
+        addressShort: `${addr.slice(0, 6)}\u2026${addr.slice(-4)}`
+      };
+    } catch {
+    }
+  }
   const scopeRequest = input.keyScope ?? "auto";
   if (scopeRequest === "auto" && input.chain === "bnb" && CONFIG.trialApiKey && input.recipients.length > RECIPIENT_LIMIT_TRIAL) {
     const overflow = input.recipients.length - RECIPIENT_LIMIT_TRIAL;
@@ -972,6 +1049,7 @@ async function runBatchPay(input) {
       mode: "none",
       status: "ambiguous",
       guardsApplied,
+      senderWallet,
       setupHint: `Batch of ${input.recipients.length} on BNB exceeds the Trial cap of ${RECIPIENT_LIMIT_TRIAL}. Ask the user to pick one and re-invoke q402_batch_pay with explicit keyScope:
   \u2022 keyScope="trial" \u2014 keep only the first ${RECIPIENT_LIMIT_TRIAL} recipients (free, sponsored). Drop the remaining ${overflow}.
   \u2022 keyScope="multichain" \u2014 send all ${input.recipients.length} on the paid Multichain key (charges the paid pool + Gas Tank).
@@ -991,6 +1069,7 @@ async function runBatchPay(input) {
       mode: "sandbox",
       status: "sandbox",
       result: { sandbox: sandboxResults, reason },
+      senderWallet,
       guardsApplied,
       setupHint: reason
     };
@@ -1009,7 +1088,7 @@ async function runBatchPay(input) {
     guardsApplied.push("mode=live");
     guardsApplied.push(`scope=${result.scope} (server enforced)`);
     guardsApplied.push(`batch_size=${input.recipients.length}/${result.limit}`);
-    return { mode: "live", status: "success", result, guardsApplied };
+    return { mode: "live", status: "success", result, guardsApplied, senderWallet };
   } catch (err) {
     if (err instanceof BatchPayError) {
       guardsApplied.push("mode=live");
@@ -1029,6 +1108,7 @@ async function runBatchPay(input) {
           results: err.results
         },
         guardsApplied,
+        senderWallet,
         error: err.message
       };
     }
@@ -1036,10 +1116,22 @@ 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 (!CONFIG.privateKey) missing.push("Q402_PRIVATE_KEY");
-  if (!CONFIG.realPaymentsRequested) missing.push("Q402_ENABLE_REAL_PAYMENTS=1");
+  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)) {
+    missing.push(
+      "Q402_PRIVATE_KEY (currently the placeholder '0x...' \u2014 paste a real 0x + 64-hex key into ~/.q402/mcp.env)"
+    );
+  }
+  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";
@@ -1285,7 +1377,9 @@ async function runReceipt(input) {
       notFound: true
     };
   }
-  const resp = await fetch(`${apiBase}/receipt/${receiptId}`);
+  const resp = await fetch(`${apiBase}/receipt/${receiptId}`, {
+    signal: AbortSignal.timeout(1e4)
+  });
   if (resp.status === 404) {
     return {
       receiptId,
@@ -1338,7 +1432,7 @@ var RECEIPT_TOOL = {
 
 // src/tools/wallet-status.ts
 import { z as z6 } from "zod";
-import { Wallet as Wallet2 } from "ethers";
+import { Wallet as Wallet4 } from "ethers";
 var WalletStatusInputSchema = z6.object({});
 async function runWalletStatus() {
   if (!CONFIG.privateKey) {
@@ -1349,7 +1443,7 @@ async function runWalletStatus() {
   }
   let address;
   try {
-    address = new Wallet2(CONFIG.privateKey).address;
+    address = new Wallet4(CONFIG.privateKey).address;
   } catch {
     return {
       error: "INVALID_PRIVATE_KEY",
@@ -1360,7 +1454,7 @@ async function runWalletStatus() {
   let body;
   let res;
   try {
-    res = await fetch(url);
+    res = await fetch(url, { signal: AbortSignal.timeout(1e4) });
     body = await res.json();
   } catch (e) {
     return {
@@ -1397,7 +1491,7 @@ var WALLET_STATUS_TOOL = {
 
 // src/tools/clear-delegation.ts
 import { z as z7 } from "zod";
-import { Wallet as Wallet3, JsonRpcProvider as JsonRpcProvider2 } from "ethers";
+import { Wallet as Wallet5, JsonRpcProvider as JsonRpcProvider2 } from "ethers";
 var ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
 var DEFAULT_RPC2 = {
   1: "https://ethereum.publicnode.com",
@@ -1428,7 +1522,7 @@ async function runClearDelegation(input) {
   let wallet;
   try {
     const provider = new JsonRpcProvider2(DEFAULT_RPC2[cfg.chainId]);
-    wallet = new Wallet3(CONFIG.privateKey, provider);
+    wallet = new Wallet5(CONFIG.privateKey, provider);
   } catch {
     return {
       ok: false,
@@ -1482,7 +1576,8 @@ async function runClearDelegation(input) {
     res = await fetch(url, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(body)
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(3e4)
     });
     json = await res.json();
   } catch (e) {
@@ -1538,13 +1633,19 @@ var CLEAR_DELEGATION_TOOL = {
 
 // src/tools/doctor.ts
 import { z as z8 } from "zod";
-import { Wallet as Wallet4 } from "ethers";
+import { Wallet as Wallet6 } from "ethers";
 var DoctorInputSchema = z8.object({});
 var ENV_FILE_TEMPLATE = `# \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
 # Q402 MCP \u2014 secrets
 # 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
@@ -1584,10 +1685,10 @@ Q402_RELAY_BASE_URL=https://q402.quackai.ai/api
 `;
 var SECURITY_NOTICE = "Q402 never asks you to paste your private key into chat. The MCP server signs payments LOCALLY on your machine \u2014 your key never leaves your device, never goes to a remote server. If a key was already pasted in chat by mistake, treat the wallet as exposed: move funds to a fresh wallet and use that new key in ~/.q402/mcp.env going forward.";
 var FIRST_INSTALL_ADVISORY = [
-  "Use a FRESH wallet for Q402 \u2014 don't reuse the one with your main funds.",
-  "After your first payment, that wallet will show 'Smart account' in MetaMask / OKX. That's EIP-7702 delegation (Q402's gasless settlement mechanism), reversible anytime with q402_clear_delegation.",
-  "Hardware wallets (Ledger / Trezor) are NOT supported yet \u2014 they don't sign EIP-7702 type-4 authorizations.",
-  "To get a hex private key from MetaMask: \xB7\xB7\xB7 (3-dot menu) \u2192 Account details \u2192 Show private key \u2192 enter password."
+  `Tip: a separate MetaMask account dedicated to Q402 keeps your existing balances and history tidy \u2014 it's a quick "+ Add account" in MetaMask. Q402 works with any EOA you control, though.`,
+  "After your first payment, that wallet will show 'Smart account' in MetaMask / OKX. That's EIP-7702 delegation (Q402's gasless settlement mechanism), reversible anytime via q402_clear_delegation.",
+  "Hardware wallets (Ledger / Trezor) can't sign EIP-7702 type-4 authorizations yet, so they're not supported in Q402 today \u2014 a hot wallet works.",
+  "To export the key in MetaMask: open the account menu \u2192 Account details \u2192 Show private key. Paste the 0x... string into ~/.q402/mcp.env in your editor (never into chat)."
 ];
 function envSource(name) {
   if (process.env[name] !== void 0) return "process";
@@ -1704,9 +1805,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(
@@ -1739,7 +1842,17 @@ async function runDoctor() {
       "Q402_PRIVATE_KEY is set but malformed (expected 0x + 64 hex chars). Looks like the placeholder '0x...' is still in ~/.q402/mcp.env \u2014 paste a real key in your editor."
     );
   }
-  if (!CONFIG.realPaymentsRequested) missing.push("Q402_ENABLE_REAL_PAYMENTS=1");
+  if (!CONFIG.realPaymentsRequested) {
+    const haveAnyApi = !!(CONFIG.trialApiKey || CONFIG.multichainApiKey || CONFIG.legacyApiKey);
+    const havePk = isValidPrivateKey(CONFIG.privateKey);
+    if (haveAnyApi && havePk) {
+      missing.push(
+        "Q402_ENABLE_REAL_PAYMENTS=1 \u2014 your other config looks fine, but your MCP client isn't passing the registry default through. Add the line Q402_ENABLE_REAL_PAYMENTS=1 to ~/.q402/mcp.env explicitly and restart."
+      );
+    } else {
+      missing.push("Q402_ENABLE_REAL_PAYMENTS=1");
+    }
+  }
   const recommendedActions = [];
   if (!envFile.exists) {
     recommendedActions.push({
@@ -1762,12 +1875,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,
@@ -1781,7 +1900,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.",
@@ -1796,13 +1915,19 @@ async function runDoctor() {
         "Then ask me 'Verify Q402' to re-check."
       ],
       securityNotice: SECURITY_NOTICE,
-      advisories: phase === "first-install" ? FIRST_INSTALL_ADVISORY : void 0
+      // Advisories are useful in BOTH first-install and needs-completion:
+      // a user who already pasted an API key but hasn't yet added their
+      // private key is exactly the audience that needs the "MetaMask
+      // export path" + "Smart-account-is-normal" heads-up. Suppressing
+      // them once any env was set (the pre-0.5.12 behaviour) left a
+      // gap right at the moment they were most useful.
+      advisories: FIRST_INSTALL_ADVISORY
     };
   }
   let walletAddress;
   let walletError;
   try {
-    walletAddress = new Wallet4(CONFIG.privateKey).address;
+    walletAddress = new Wallet6(CONFIG.privateKey).address;
   } catch (e) {
     walletError = e instanceof Error ? e.message : String(e);
     warnings.push(
@@ -1815,11 +1940,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) {
@@ -1832,9 +1958,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) {
@@ -1859,20 +1995,22 @@ 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.",
-      "Want me to run a quick gas comparison across all 9 chains as a smoke test?"
+      "Want me to run a quick gas comparison across all 9 chains as a smoke test?",
+      "Need to chain-test against sandbox without changing keys? Set Q402_ENABLE_REAL_PAYMENTS=0 in ~/.q402/mcp.env and restart \u2014 every q402_pay returns a fake hash until you flip it back to 1."
     ] : [
       `Q402 has ${warnings.length} issue${warnings.length === 1 ? "" : "s"} to fix:`,
       ...warnings.map((w) => `\u2022 ${w}`),
       "Open ~/.q402/mcp.env, fix the lines above, save, then restart your MCP client (Cursor/Cline: Cmd/Ctrl+Shift+P \u2192 Reload Window; Claude/Codex: quit + relaunch). Then ask me 'Verify Q402' to re-check."
     ],
     securityNotice: SECURITY_NOTICE,
-    // advisories are first-install-only by design — explicitly set to undefined
-    // here so future maintainers see the conditional rather than an absent key.
-    advisories: void 0
+    // Carry advisories through live-check too — even a fully-configured
+    // user benefits from the "Smart-account in MetaMask is normal" line
+    // appearing alongside their first ready state.
+    advisories: FIRST_INSTALL_ADVISORY
   };
 }
 var DOCTOR_TOOL = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quackai/q402-mcp",
-  "version": "0.5.11",
+  "version": "0.5.13",
   "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": [