@quackai/q402-mcp 0.5.6 → 0.5.7

package/README.md

@@ -136,7 +136,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 +146,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 +175,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.7";
 
 // src/tools/quote.ts
 import { z } from "zod";
@@ -1116,7 +1129,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 +1537,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.
@@ -1582,8 +1596,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 +1617,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 +1644,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 +1667,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,17 +1706,19 @@ 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) {
@@ -1699,6 +1734,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,7 +1750,6 @@ 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.`,
@@ -1717,10 +1758,14 @@ async function runDoctor() {
     };
   }
   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 +1775,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 +1789,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 +1809,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.7",
   "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": [