@quackai/q402-mcp 0.5.6 → 0.5.8

package/README.md

@@ -49,16 +49,26 @@ The agent calls `q402_doctor`. On first install, the tool tells the agent to:
 
 ### Manual setup (no AI)
 
-Create `~/.q402/mcp.env` yourself:
+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.)
 
 ```bash
 # ~/.q402/mcp.env
-# Pick ONE of these:
-Q402_TRIAL_API_KEY=q402_live_...
+
+# Free Trial — BNB only, 2,000 sponsored TX (from /event)
+# Q402_TRIAL_API_KEY=q402_live_...
+
+# Paid Multichain — all 9 chains (from /payment)
 # Q402_MULTICHAIN_API_KEY=q402_live_...
 
-Q402_PRIVATE_KEY=0x...
-Q402_ENABLE_REAL_PAYMENTS=1
+# Hex EVM private key (0x + 64 hex). Use a FRESH wallet, NOT your main
+# one — Q402 delegates this EOA via EIP-7702 on first payment.
+# Hardware wallets (Ledger / Trezor) are not supported yet.
+# Q402_PRIVATE_KEY=0x...
+
+# Start at 0 (sandbox). Flip to 1 only after real values are pasted above.
+Q402_ENABLE_REAL_PAYMENTS=0
+
+# Default Q402 deployment. Only change for self-hosted.
 Q402_RELAY_BASE_URL=https://q402.quackai.ai/api
 
 # Optional safety guards:
@@ -66,7 +76,7 @@ Q402_RELAY_BASE_URL=https://q402.quackai.ai/api
 # Q402_ALLOWED_RECIPIENTS=0xabc...,0xdef...
 ```
 
-Then `chmod 600 ~/.q402/mcp.env` (Unix) and restart your client. That's the full configuration.
+Then `chmod 600 ~/.q402/mcp.env` (Unix) and restart your client. That's the full configuration. **Heads up on the EIP-7702 side effect:** after your first live payment on a chain, your wallet will show 'Smart account' in MetaMask / OKX — that's the delegation Q402 uses for gasless settlement, reversible anytime via `q402_clear_delegation`.
 
 ### Advanced — explicit env injection
 
@@ -136,7 +146,7 @@ By default the MCP server operates in **sandbox mode**: `q402_pay` returns a ran
 To enable real on-chain transactions, the resolved API key must be live (`q402_live_*`), `Q402_PRIVATE_KEY` must be set, and `Q402_ENABLE_REAL_PAYMENTS=1`:
 
 ```bash
-# Two-key model — set whichever applies. Both is best.
+# Two-key model — set whichever applies (or both for auto-routing).
 # Auto-routing (same for q402_pay AND q402_batch_pay):
 #   chain="bnb" + Q402_TRIAL_API_KEY set  → Trial (free sponsored)
 #   anything else                          → Multichain (paid 9-chain)
@@ -146,10 +156,6 @@ To enable real on-chain transactions, the resolved API key must be live (`q402_l
 Q402_TRIAL_API_KEY=q402_live_...           # BNB-only sponsored Trial key (from /event)
 Q402_MULTICHAIN_API_KEY=q402_live_...      # paid 9-chain key (per-chain Gas Tank)
 
-# Legacy fallback. Used for both scopes when the two above are unset —
-# single-env setups (only Q402_API_KEY set) keep working unchanged.
-Q402_API_KEY=q402_live_...
-
 Q402_PRIVATE_KEY=0xabc...                  # signer for the payer EOA
 Q402_ENABLE_REAL_PAYMENTS=1                # explicit opt-in
 ```
@@ -179,13 +185,14 @@ Combined with the `confirm: true` argument the tool requires, this means the mod
 |---|---|---|
 | `Q402_TRIAL_API_KEY` | live-pay (BNB) | BNB-only sponsored Trial key. Free at https://q402.quackai.ai/event. Auto-routed for `chain="bnb"` in both `q402_pay` and `q402_batch_pay` (≤5 recipients) when set. 6+ recipient BNB batches return `status="ambiguous"` so the agent can ask the user how to split. |
 | `Q402_MULTICHAIN_API_KEY` | live-pay (9-chain) | Paid 9-chain key. Get one at https://q402.quackai.ai/payment. Auto-routed for non-BNB chains AND for BNB when no Trial key is set. Cap: 20 recipients per batch. |
-| `Q402_API_KEY` | legacy fallback | Single-env legacy path. Used for both scopes when the two above are unset. Keep set if you only have one key. |
 | `Q402_PRIVATE_KEY` | live-pay | Signer for the payer EOA. **Never share. Never paste in chat.** |
 | `Q402_ENABLE_REAL_PAYMENTS` | live-pay | Set to `1` to opt in. Any other value (or unset) → sandbox. |
 | `Q402_MAX_AMOUNT_PER_CALL` | optional | USD-equivalent cap. Defaults to `5`. |
 | `Q402_ALLOWED_RECIPIENTS` | optional | Comma-separated lowercase addresses. Defaults to no allowlist. |
 | `Q402_RELAY_BASE_URL` | optional | Defaults to `https://q402.quackai.ai/api`. Override for self-hosted Q402. |
 
+> Older integrations may still set `Q402_API_KEY` as a single-env fallback — that still works silently for back-compat. New setups should use the two-key model above; `q402_doctor` only guides users to those two.
+
 ---
 
 ## Supported chains

package/dist/index.js

@@ -46,8 +46,15 @@ function loadQ402EnvFileFromPath(path) {
     if (eq < 0) continue;
     const k = t.slice(0, eq).trim();
     if (!k.startsWith("Q402_")) continue;
-    const v = t.slice(eq + 1).trim().replace(/^['"](.*)['"]$/, "$1");
-    out[k] = v;
+    let rawVal = t.slice(eq + 1).trim();
+    const quoted = /^(['"])(.*)\1\s*(?:#.*)?$/.exec(rawVal);
+    if (quoted) {
+      rawVal = quoted[2];
+    } else {
+      const hashIdx = rawVal.search(/\s#/);
+      if (hashIdx >= 0) rawVal = rawVal.slice(0, hashIdx).trimEnd();
+    }
+    out[k] = rawVal;
   }
   return out;
 }
@@ -66,6 +73,9 @@ var Q402_ENV_FILE_KEYS = Object.freeze(
     Object.keys(FILE_ENV).filter((k) => process.env[k] === void 0)
   )
 );
+var Q402_ENV_FILE_KEYS_ALL = Object.freeze(
+  new Set(Object.keys(FILE_ENV))
+);
 var DEFAULT_RELAY_BASE = "https://q402.quackai.ai/api";
 var DEFAULT_MAX_AMOUNT = 5;
 function classifyApiKey(k) {
@@ -146,16 +156,19 @@ function resolveApiKey(chain, scope = "auto") {
   }
   return { apiKey: key, scope: "multichain", fromLegacyFallback: !CONFIG.multichainApiKey };
 }
+var PRIVATE_KEY_RE = /^0x[a-fA-F0-9]{64}$/;
 function isLiveModeFor(resolved) {
   if (!resolved.apiKey) return false;
   if (!CONFIG.realPaymentsRequested) return false;
   if (!CONFIG.privateKey) return false;
+  if (!PRIVATE_KEY_RE.test(CONFIG.privateKey)) return false;
   return resolved.apiKey.startsWith("q402_live_");
 }
+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.6";
+var PACKAGE_VERSION = "0.5.8";
 
 // src/tools/quote.ts
 import { z } from "zod";
@@ -737,7 +750,11 @@ function sandboxPay(chain, input) {
   const tokenAmount = toRawAmount(input.amount, tokenCfg.decimals);
   const fakeHash = "0x" + hexlify(randomBytes(32)).slice(2);
   return {
-    success: true,
+    // `success: false` because no funds moved. The `sandbox: true` flag is
+    // the canonical "this was a simulation" marker — downstream callers
+    // should branch on EITHER field to avoid misreporting a settlement.
+    success: false,
+    sandbox: true,
     txHash: fakeHash,
     tokenAmount,
     token: input.token,
@@ -823,7 +840,11 @@ async function runPay(input) {
     token: input.token
   });
   guardsApplied.push("mode=live");
-  return { result, guardsApplied };
+  return {
+    result,
+    guardsApplied,
+    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 missing = [];
@@ -837,7 +858,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, and Q402_ENABLE_REAL_PAYMENTS=1. The recipient receives the full amount; the sender pays $0 in gas. After the first payment on a chain, follow-up payments on the same chain are faster and cheaper (Q402 reuses the wallet's setup); q402_clear_delegation resets it if the user ever asks. ALWAYS 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\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: {
@@ -1116,7 +1137,7 @@ async function runBalance() {
       apiKeyMasked: null,
       scopes: [],
       dashboardUrl: "https://q402.quackai.ai/dashboard",
-      setupHint: "No API key configured. Call q402_doctor for guided setup \u2014 it will offer to create ~/.q402/mcp.env with placeholders that the user can fill in. (Manual path: set Q402_TRIAL_API_KEY for BNB-only sponsored (free at https://q402.quackai.ai/event) and/or Q402_MULTICHAIN_API_KEY for paid 9-chain (https://q402.quackai.ai/payment). Q402_API_KEY is the legacy single-env fallback.)"
+      setupHint: "No API key configured. Call q402_doctor for guided setup \u2014 it will offer to create ~/.q402/mcp.env with placeholders that the user can fill in. (Manual path: set Q402_TRIAL_API_KEY for BNB-only sponsored free trial (https://q402.quackai.ai/event) or Q402_MULTICHAIN_API_KEY for the paid 9-chain plan (https://q402.quackai.ai/payment).)"
     };
   }
   const scopes = await Promise.all(
@@ -1524,24 +1545,25 @@ var ENV_FILE_TEMPLATE = `# \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u250
 # After editing, restart your MCP client (Codex / Claude / Cursor / Cline).
 # \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 pick ONE (uncomment the one you have) \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
 # Free Trial:        BNB Chain only, 2,000 sponsored TX
 # Get one at:        https://q402.quackai.ai/event
-Q402_TRIAL_API_KEY=q402_live_...
+# Q402_TRIAL_API_KEY=q402_live_...
 
 # Paid Multichain:   all 9 chains, per-chain Gas Tank
 # Get one at:        https://q402.quackai.ai/payment
 # Q402_MULTICHAIN_API_KEY=q402_live_...
 
 # \u2500\u2500\u2500 Your wallet \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
-# Hex EVM private key. Signs payments LOCALLY on your machine.
-# Never leaves your device, never sent to any server.
-Q402_PRIVATE_KEY=0x...
+# Hex EVM private key (0x + 64 hex chars). Signs payments LOCALLY on
+# your machine \u2014 never leaves your device, never sent to any server.
+# Q402_PRIVATE_KEY=0x...
 
 # \u2500\u2500\u2500 Live mode flag \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
-# Must be exactly "1" to allow real on-chain transactions.
-# Anything else = test response (fake hash, no funds move).
-Q402_ENABLE_REAL_PAYMENTS=1
+# Default 0 = sandbox (test responses, no funds move). Flip to 1 only
+# AFTER you've pasted real values into the lines above \u2014 otherwise the
+# server will refuse the placeholders.
+Q402_ENABLE_REAL_PAYMENTS=0
 
 # \u2500\u2500\u2500 Q402 relay endpoint \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
 # Default canonical Q402 deployment. Only change for self-hosted.
@@ -1555,6 +1577,12 @@ Q402_RELAY_BASE_URL=https://q402.quackai.ai/api
 # Q402_ALLOWED_RECIPIENTS=0xabc...,0xdef...
 `;
 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."
+];
 function envSource(name) {
   if (process.env[name] !== void 0) return "process";
   if (Q402_ENV_FILE_KEYS.has(name)) return "file";
@@ -1582,8 +1610,18 @@ async function verifyOneKey(scope, envVar, apiKey) {
     const resp = await fetch(url, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ apiKey })
+      body: JSON.stringify({ apiKey }),
+      signal: AbortSignal.timeout(1e4)
     });
+    if (resp.status === 429) {
+      return {
+        scope,
+        envVar,
+        apiKeyMasked: mask2(apiKey),
+        valid: false,
+        error: "rate limited by relay \u2014 wait 60s and re-run q402_doctor"
+      };
+    }
     if (!resp.ok) {
       return { scope, envVar, apiKeyMasked: mask2(apiKey), valid: false, error: `HTTP ${resp.status}` };
     }
@@ -1593,6 +1631,10 @@ async function verifyOneKey(scope, envVar, apiKey) {
       envVar,
       apiKeyMasked: mask2(apiKey),
       valid: body.valid ?? false,
+      // Propagate the relay's specific reason ("API key has been rotated",
+      // "Subscription expired", "Trial expired") so the user gets the
+      // exact failure mode instead of a generic "verified as invalid".
+      error: body.valid === false ? body.error : void 0,
       plan: body.plan,
       remainingCredits: body.remainingCredits,
       isTrial: body.isTrial,
@@ -1616,11 +1658,16 @@ async function verifyOneKey(scope, envVar, apiKey) {
   }
 }
 async function pingRelay() {
-  const url = `${CONFIG.relayBaseUrl}/health`;
+  const url = `${CONFIG.relayBaseUrl}/keys/verify`;
   const t0 = Date.now();
   try {
-    const resp = await fetch(url, { method: "GET" });
-    const reachable = resp.status < 500;
+    const resp = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: "{}",
+      signal: AbortSignal.timeout(1e4)
+    });
+    const reachable = resp.status >= 200 && resp.status < 500;
     return { url, reachable, latencyMs: Date.now() - t0 };
   } catch (e) {
     return {
@@ -1634,7 +1681,7 @@ async function pingRelay() {
 async function fetchDelegation(address) {
   const url = `${CONFIG.relayBaseUrl}/wallet/delegation-status?address=${address}`;
   try {
-    const resp = await fetch(url);
+    const resp = await fetch(url, { signal: AbortSignal.timeout(1e4) });
     if (!resp.ok) {
       return CHAIN_KEYS.map((chain) => ({ chain, delegated: false, error: `HTTP ${resp.status}` }));
     }
@@ -1673,25 +1720,34 @@ async function runDoctor() {
       "Must be '1' to allow real TX. Anything else = test response (fake hash)."
     )
   };
-  let legacyDetected;
-  if (CONFIG.legacyApiKey) {
-    legacyDetected = "Q402_API_KEY is set \u2014 works as a fallback for both scopes, but the newer two-key model (Q402_TRIAL_API_KEY + Q402_MULTICHAIN_API_KEY) gives you auto-routing between free Trial (BNB) and paid Multichain. Rename in ~/.q402/mcp.env when convenient.";
-  }
   const missing = [];
   if (!CONFIG.trialApiKey && !CONFIG.multichainApiKey && !CONFIG.legacyApiKey) {
     missing.push(
       "An API key (Q402_TRIAL_API_KEY for free BNB OR Q402_MULTICHAIN_API_KEY for paid 9-chain)"
     );
   }
-  if (!CONFIG.privateKey) missing.push("Q402_PRIVATE_KEY");
+  if (!CONFIG.privateKey) {
+    missing.push("Q402_PRIVATE_KEY");
+  } else if (!isValidPrivateKey(CONFIG.privateKey)) {
+    missing.push(
+      "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");
   const recommendedActions = [];
   if (!envFile.exists) {
+    recommendedActions.push({
+      id: "ensure-q402-dir",
+      type: "shell",
+      shell: 'mkdir -p "$HOME/.q402"',
+      shellWindows: 'powershell -Command "New-Item -ItemType Directory -Force -Path $env:USERPROFILE\\.q402 | Out-Null"',
+      requiresUserConfirm: false,
+      description: "Ensure the ~/.q402 directory exists before writing the secrets file."
+    });
     recommendedActions.push({
       id: "create-env-file",
       type: "write_file",
       path: Q402_ENV_FILE_PATH,
-      createParentDirs: true,
       content: ENV_FILE_TEMPLATE,
       requiresUserConfirm: true,
       description: "Create ~/.q402/mcp.env with placeholder values, then open it in the user's editor.",
@@ -1699,6 +1755,13 @@ 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)) {
+      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).`
+      );
+    }
+  }
   if (phase !== "live-check") {
     return {
       package: PACKAGE_NAME,
@@ -1708,19 +1771,23 @@ async function runDoctor() {
       envFile,
       envState,
       missing,
-      legacyDetected,
       warnings,
       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" ? "Offer to create ~/.q402/mcp.env. After yes, run the recommendedActions[].write_file action, then open the file in the user's editor (e.g. via `code` / `open` / `start` / `xdg-open`). Then walk through filling in the API key and private key, one at a time. Do NOT accept key values via chat \u2014 direct the user to edit the file in their editor." : `Tell the user which env vars are still missing (from the 'missing' list) and how to add them to ~/.q402/mcp.env. Restart needed after editing.`,
-      securityNotice: SECURITY_NOTICE
+      nextStep: phase === "first-install" ? "Offer to create ~/.q402/mcp.env. After yes, execute recommendedActions in order: first the `ensure-q402-dir` shell action (use bash on macOS/Linux, PowerShell on Windows via the shellWindows variant), then the `create-env-file` write_file action. Then 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. Walk through filling in the API key (from /event for free Trial or /payment for paid Multichain) and private key one at a time. 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: use a fresh wallet (not their main one), heads-up that the wallet will show 'Smart account' in MetaMask after the first payment (that's normal \u2014 EIP-7702 delegation), hardware wallets aren't supported, MetaMask key export path." : `Tell the user which env vars are still missing (from the 'missing' list) and how to add them to ~/.q402/mcp.env. Restart needed after editing. 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.`,
+      securityNotice: SECURITY_NOTICE,
+      advisories: phase === "first-install" ? FIRST_INSTALL_ADVISORY : void 0
     };
   }
   let walletAddress;
+  let walletError;
   try {
     walletAddress = new Wallet4(CONFIG.privateKey).address;
-  } catch {
-    warnings.push("Q402_PRIVATE_KEY is set but does not parse as a 32-byte hex key. Live calls will fail.");
+  } catch (e) {
+    walletError = e instanceof Error ? e.message : String(e);
+    warnings.push(
+      `Q402_PRIVATE_KEY is set but does not parse as a 32-byte hex key: ${walletError}. Open ~/.q402/mcp.env in your editor and paste a real key (0x + 64 hex chars). Live calls will fail until this is fixed.`
+    );
   }
   const verifyTargets = [];
   if (CONFIG.trialApiKey) verifyTargets.push({ scope: "trial", envVar: "Q402_TRIAL_API_KEY", key: CONFIG.trialApiKey });
@@ -1730,7 +1797,7 @@ async function runDoctor() {
   }
   const [keys, delegation, relay] = await Promise.all([
     Promise.all(verifyTargets.map((t) => verifyOneKey(t.scope, t.envVar, t.key))),
-    walletAddress ? fetchDelegation(walletAddress) : Promise.resolve([]),
+    walletAddress ? fetchDelegation(walletAddress) : Promise.resolve(void 0),
     pingRelay()
   ]);
   for (const k of keys) if (k.slotWarning) warnings.push(k.slotWarning);
@@ -1744,8 +1811,10 @@ async function runDoctor() {
         `${k.envVar} has only ${k.remainingCredits} credits left \u2014 top up before you run out.`
       );
     }
-    if (!k.valid && !k.error) {
-      warnings.push(`${k.envVar} verified as invalid by the relay \u2014 check the key value in ~/.q402/mcp.env.`);
+    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.`
+      );
     }
   }
   if (relay && !relay.reachable) {
@@ -1762,7 +1831,6 @@ async function runDoctor() {
     envFile,
     envState,
     missing,
-    legacyDetected,
     wallet: walletAddress ? { address: walletAddress } : void 0,
     keys,
     delegation,

package/package.json

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