@quackai/q402-mcp 0.4.3 → 0.4.5

package/README.md

@@ -76,10 +76,13 @@ command = "npx"
 args = ["-y", "@quackai/q402-mcp"]
 startup_timeout_sec = 20.0
 env = {
-  # Two-key model (v0.4.3+): set whichever applies — both is best.
+  # Two-key model (v0.4.5+): set whichever applies — both is best.
   # The server auto-routes by chain: BNB → trial key, else multichain key.
-  Q402_TRIAL_API_KEY        = "q402_live_trial_...",   # BNB-only sponsored
-  Q402_MULTICHAIN_API_KEY   = "q402_live_...",         # paid 8-chain
+  # Both keys use the same q402_live_ prefix — the env var name is what
+  # carries the scope, not the key string. Get the values from the
+  # dashboard (each key has its own copy button per view).
+  Q402_TRIAL_API_KEY        = "q402_live_...",         # BNB-only sponsored (from /event)
+  Q402_MULTICHAIN_API_KEY   = "q402_live_...",         # paid 8-chain (from /payment)
   # Legacy fallback — used if neither scoped key above is set.
   Q402_API_KEY              = "q402_live_...",
   Q402_PRIVATE_KEY          = "0xabc...",
@@ -130,14 +133,14 @@ By default the MCP server operates in **sandbox mode**: `q402_pay` returns a det
 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 (v0.4.3+) — set whichever applies. Both is best.
+# Two-key model (v0.4.5+) — set whichever applies. Both is best.
 # Auto-routing: chain="bnb" → trial key (if set), otherwise multichain key.
 # Override per call with keyScope: "auto" | "trial" | "multichain".
-Q402_TRIAL_API_KEY=q402_live_trial_...     # BNB-only sponsored Trial key
+Q402_TRIAL_API_KEY=q402_live_...           # BNB-only sponsored Trial key (from /event)
 Q402_MULTICHAIN_API_KEY=q402_live_...      # paid 8-chain key (per-chain Gas Tank)
 
 # Legacy fallback. Used for both scopes when the two above are unset —
-# pre-v0.4.3 users keep working without any config change.
+# pre-v0.4.5 users keep working without any config change.
 Q402_API_KEY=q402_live_...
 
 Q402_PRIVATE_KEY=0xabc...                  # signer for the payer EOA
@@ -146,6 +149,10 @@ Q402_ENABLE_REAL_PAYMENTS=1                # explicit opt-in
 
 Anything missing for the resolved scope → automatic sandbox fallback with a hint pointing at what to set.
 
+> ⚠️ **Sandbox returns a deterministic-looking fake `txHash` and a synthetic success result.** A user who *expected* a live transfer (e.g. forgot to set `Q402_ENABLE_REAL_PAYMENTS=1`, mis-typed a scoped env var, or hit an impossible chain×scope combination like `keyScope: "trial"` + `chain: "monad"`) gets a "success" back and may believe funds actually moved.
+>
+> Two-layer mitigation: every sandbox response carries a `setupHint` field on the tool result describing **exactly why** sandbox was selected, and the `q402_balance` tool's `apiKeyKind: "missing"` makes the same diagnosis explicit. Always check `setupHint` on the first call from a new install. The deterministic `txHash` pattern (`0x` + 64 hex derived from `keccak256(chain, to, amount, token, "sandbox")`) is intentional so the agent can recognise it post-hoc, but the safer habit is to inspect `setupHint` before showing the user a success message.
+
 ### Hard caps
 
 Two additional guards run before every payment regardless of mode:
@@ -165,7 +172,7 @@ 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. Used automatically for `chain="bnb"` when set. |
 | `Q402_MULTICHAIN_API_KEY` | live-pay (8-chain) | Paid 8-chain key. Get one at https://q402.quackai.ai/payment. Used for all non-BNB chains and for BNB when no Trial key is set. |
-| `Q402_API_KEY` | legacy fallback | Pre-v0.4.3 single-env path. Used for both scopes when the two above are unset. Keep set if you only have one key. |
+| `Q402_API_KEY` | legacy fallback | Pre-v0.4.5 single-env 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`. |

package/dist/index.js

@@ -52,31 +52,47 @@ function loadConfig() {
   };
 }
 var CONFIG = loadConfig();
-function resolveApiKey(chain, scope = "auto") {
-  const effectiveScope = scope === "auto" ? chain === "bnb" && CONFIG.trialApiKey ? "trial" : "multichain" : scope;
+function resolveApiKey(chain, scope = "auto", intent = "single") {
+  const effectiveScope = scope === "auto" ? (
+    // Smart routing: batches default to multichain (trial cap=5 would
+    // silently fail any 6+ recipient batch). Single payments default to
+    // trial on BNB when a trial key is set, so the free sponsored
+    // allotment gets used naturally.
+    intent === "batch" ? "multichain" : chain === "bnb" && CONFIG.trialApiKey ? "trial" : "multichain"
+  ) : scope;
   if (effectiveScope === "trial") {
     if (chain !== "bnb") {
-      throw new Error(
-        `Trial API Key supports BNB Chain only \u2014 got "${chain}". Use a Multichain API Key (set Q402_MULTICHAIN_API_KEY) for ${chain} and other paid chains, or omit keyScope to let the server auto-pick.`
-      );
+      return {
+        apiKey: null,
+        scope: "trial",
+        fromLegacyFallback: false,
+        sandboxReason: `keyScope="trial" requested but chain="${chain}" \u2014 Trial keys support BNB Chain only. Drop keyScope (or set keyScope="multichain") to use the paid Multichain key on ${chain}.`
+      };
     }
     const key2 = CONFIG.trialApiKey ?? CONFIG.legacyApiKey;
     if (!key2) {
-      throw new Error(
-        "keyScope='trial' was requested but neither Q402_TRIAL_API_KEY nor Q402_API_KEY is set. Get a Trial key at https://q402.quackai.ai/event."
-      );
+      return {
+        apiKey: null,
+        scope: "trial",
+        fromLegacyFallback: false,
+        sandboxReason: "keyScope='trial' requested but neither Q402_TRIAL_API_KEY nor Q402_API_KEY is set. Get a free Trial key at https://q402.quackai.ai/event."
+      };
     }
     return { apiKey: key2, scope: "trial", fromLegacyFallback: !CONFIG.trialApiKey };
   }
   const key = CONFIG.multichainApiKey ?? CONFIG.legacyApiKey;
   if (!key) {
-    throw new Error(
-      "keyScope='multichain' was requested but neither Q402_MULTICHAIN_API_KEY nor Q402_API_KEY is set. Activate a paid plan at https://q402.quackai.ai/payment to get one."
-    );
+    return {
+      apiKey: null,
+      scope: "multichain",
+      fromLegacyFallback: false,
+      sandboxReason: (scope === "multichain" ? "keyScope='multichain' requested but neither Q402_MULTICHAIN_API_KEY" : `chain="${chain}" routes to the Multichain scope but neither Q402_MULTICHAIN_API_KEY`) + " nor Q402_API_KEY is set. Activate a paid plan at https://q402.quackai.ai/payment to get one."
+    };
   }
   return { apiKey: key, scope: "multichain", fromLegacyFallback: !CONFIG.multichainApiKey };
 }
 function isLiveModeFor(resolved) {
+  if (!resolved.apiKey) return false;
   if (!CONFIG.realPaymentsRequested) return false;
   if (!CONFIG.privateKey) return false;
   return resolved.apiKey.startsWith("q402_live_");
@@ -214,7 +230,7 @@ var CHAIN_CONFIG = {
   }
 };
 var BNB_FOCUS_MODE = false;
-var BNB_FOCUS_REJECTION_MESSAGE = 'BNB-focus sprint: this chain/token is temporarily hidden. Full multi-chain support returns after the sprint window. Pass chain: "bnb" with token "USDC" or "USDT".';
+var BNB_FOCUS_REJECTION_MESSAGE = 'BNB-only mode active: this chain/token is temporarily hidden. Full multi-chain support is the normal state. Pass chain: "bnb" with token "USDC" or "USDT".';
 if (BNB_FOCUS_MODE) {
   for (const key of CHAIN_KEYS) {
     if (key !== "bnb") {
@@ -290,7 +306,7 @@ function runQuote(input) {
 }
 var QUOTE_TOOL = {
   name: "q402_quote",
-  description: "Compare gas costs and supported tokens across the 8 chains Q402 relays for (avax, bnb, eth, xlayer, stable, mantle, injective, monad). Trial-tier API keys see BNB-only quotes (q402_pay enforces the same scope server-side); paid-tier keys see the full matrix including RLUSD on Ethereum and Injective USDT-only. Read-only \u2014 no API key needed, no funds move. Use this before q402_pay so the user sees what's currently routable on their tier.",
+  description: "Compare gas costs and supported tokens across the 8 chains Q402 relays for (avax, bnb, eth, xlayer, stable, mantle, injective, monad). Returns the full chain \xD7 token matrix unconditionally \u2014 this tool does not read any API key, so it can't filter by trial vs multichain scope. When the caller intends to settle with a Trial API Key, treat any non-BNB row as informational only (q402_pay will return 403 TRIAL_BNB_ONLY for those). Includes RLUSD on Ethereum and Injective USDT-only. Read-only \u2014 no API key needed, no funds move. Use this before q402_pay so the user can see what's available and pick a chain.",
   // Plain JSON schema mirroring the Zod schema above; MCP servers receive parameters as JSON.
   inputSchema: {
     type: "object",
@@ -705,7 +721,7 @@ async function runPay(input) {
     guardsApplied.push(`recipient_allowlist[${CONFIG.allowedRecipients.length}]`);
   }
   const scopeRequest = input.keyScope ?? "auto";
-  const resolved = resolveApiKey(input.chain, scopeRequest);
+  const resolved = resolveApiKey(input.chain, scopeRequest, "single");
   guardsApplied.push(`scope=${resolved.scope}${resolved.fromLegacyFallback ? "(legacy)" : ""}`);
   const live = isLiveModeFor(resolved);
   if (!live) {
@@ -715,7 +731,7 @@ async function runPay(input) {
       token: input.token
     });
     guardsApplied.push("mode=sandbox");
-    const setupHint = describeSandboxReason(resolved.apiKey);
+    const setupHint = resolved.sandboxReason ?? describeSandboxReason(resolved.apiKey ?? "");
     return { result: result2, guardsApplied, setupHint };
   }
   const client = new Q402NodeClient({
@@ -823,10 +839,10 @@ function maxAmountGuardBatch(recipients, cap) {
 function recipientAllowlistGuardBatch(recipients, allow) {
   if (allow.length === 0) return;
   for (let i = 0; i < recipients.length; i++) {
-    const to = recipients[i].to.toLowerCase();
-    if (!allow.includes(to)) {
+    const r = recipients[i];
+    if (!allow.includes(r.to.toLowerCase())) {
       throw new Error(
-        `recipients[${i}]: ${recipients[i].to} is not in Q402_ALLOWED_RECIPIENTS. Either add this address to the allowlist or unset the env var to disable the guard.`
+        `recipients[${i}]: ${r.to} is not in Q402_ALLOWED_RECIPIENTS. Either add this address to the allowlist or unset the env var to disable the guard.`
       );
     }
   }
@@ -847,7 +863,7 @@ async function runBatchPay(input) {
     guardsApplied.push(`recipient_allowlist[${CONFIG.allowedRecipients.length}]`);
   }
   const scopeRequest = input.keyScope ?? "auto";
-  const resolved = resolveApiKey(input.chain, scopeRequest);
+  const resolved = resolveApiKey(input.chain, scopeRequest, "batch");
   guardsApplied.push(`scope=${resolved.scope}${resolved.fromLegacyFallback ? "(legacy)" : ""}`);
   const live = isLiveModeFor(resolved);
   if (!live) {
@@ -855,7 +871,7 @@ async function runBatchPay(input) {
       (r) => sandboxPay(chain, { to: r.to, amount: r.amount, token: input.token })
     );
     guardsApplied.push("mode=sandbox");
-    const reason = describeSandboxReason2(resolved.apiKey);
+    const reason = resolved.sandboxReason ?? describeSandboxReason2(resolved.apiKey ?? "");
     return {
       mode: "sandbox",
       status: "sandbox",
@@ -1205,7 +1221,7 @@ var RECEIPT_TOOL = {
 
 // src/index.ts
 var PACKAGE_NAME = "@quackai/q402-mcp";
-var PACKAGE_VERSION = "0.4.2";
+var PACKAGE_VERSION = "0.4.5";
 function jsonText(value) {
   return { type: "text", text: JSON.stringify(value, null, 2) };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quackai/q402-mcp",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "MCP server for Q402 — gasless USDC, USDT, and RLUSD payments across 8 EVM chains, callable from Claude (Desktop / Code), OpenAI Codex CLI, and any other Model Context Protocol client.",
   "mcpName": "io.github.bitgett/q402-mcp",
   "keywords": [
@@ -40,7 +40,8 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
-    "prepublishOnly": "npm run build",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run lint && npm run build",
     "start": "node dist/index.js"
   },
   "dependencies": {
@@ -65,5 +66,8 @@
   "author": "David Lee <davidlee@quackai.ai>",
   "publishConfig": {
     "access": "public"
+  },
+  "overrides": {
+    "ws": "^8.20.1"
   }
 }