@quackai/q402-mcp 0.5.10 → 0.5.12

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
@@ -65,8 +65,12 @@ Create `~/.q402/mcp.env` yourself. The template below matches what `q402_doctor`
 # 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
+# Live mode switch:
+#   0 = sandbox (test mode, no funds move)
+#   1 = real on-chain payments
+# Default 1 — safe because mode only flips to live when BOTH a live
+# API key AND a valid 32-byte private key are uncommented above.
+Q402_ENABLE_REAL_PAYMENTS=1
 
 # Default Q402 deployment. Only change for self-hosted.
 Q402_RELAY_BASE_URL=https://q402.quackai.ai/api
@@ -132,9 +136,11 @@ Then export the values in `~/.zshrc` / `~/.bashrc`. See the [Codex config refere
 
 `q402_receipt` is the natural follow-up: after `q402_pay` returns a `receiptUrl`, hand the agent the `rct_…` id and ask *"verify this receipt"* — the tool re-runs the same canonical-JSON + EIP-191 recovery the receipt page does in the browser, so the verification doesn't depend on trusting any UI. Example prompts that work today:
 
-> *"Pay 0.10 USDT on BNB to vitalik.eth, then verify the receipt."*  
+> *"Pay 0.10 USDT on BNB to 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045, then verify the receipt."*  
 > *"Is `rct_afa5f50bc49a65ebba3b28ab` a real Q402 receipt? Verify the signature."*
 
+> ℹ️ `q402_pay` takes a 0x-prefixed EVM address — ENS names are not resolved by the tool. If your prompt mentions a name like `vitalik.eth`, your AI client needs to resolve it client-side before invoking the tool.
+
 > Per-chain gas tank balances and full transaction history live in the [dashboard](https://q402.quackai.ai/dashboard) — those endpoints require a wallet signature, not a bare API key, so the MCP server points the agent there instead of exposing them.
 
 ---
@@ -143,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).
@@ -159,10 +165,16 @@ To enable real on-chain transactions, the resolved API key must be live (`q402_l
 
 # Q402_PRIVATE_KEY=0x...                   # signer for the payer EOA (32-byte hex)
 
-# Start at 0 (sandbox). Flip to 1 only after real values are pasted above —
-# a malformed Q402_PRIVATE_KEY (e.g. the "0x..." placeholder) is rejected at
-# the live-mode gate, so partial setups stay in sandbox with a clear hint.
-Q402_ENABLE_REAL_PAYMENTS=0
+# Live mode switch:
+#   0 = sandbox (test mode, no funds move — every q402_pay returns a fake hash)
+#   1 = real on-chain payments (live mode)
+# Default is 1: real payments enabled. Safe because mode only flips
+# to live when BOTH a live API key (q402_live_*) AND a valid 32-byte
+# private key are set above. Placeholders ("0x...") are rejected by
+# the live-mode gate, so partial setups stay in sandbox with a hint.
+# Change to 0 to force sandbox even with real keys (e.g. for chained
+# testing on a paid plan).
+Q402_ENABLE_REAL_PAYMENTS=1
 ```
 
 Anything missing for the resolved scope → automatic sandbox fallback with a hint pointing at what to set.
@@ -194,7 +206,12 @@ Combined with the `confirm: true` argument the tool requires, this means the mod
 | `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.
+<details>
+<summary>Migrating from legacy single-key setups</summary>
+
+If you set up Q402 before v0.5.0 you may have a single `Q402_API_KEY` env var. The server still resolves that silently — your existing integration won't break. New installs should use the two-key model above (`Q402_TRIAL_API_KEY` and/or `Q402_MULTICHAIN_API_KEY`); `q402_doctor` and the rest of the docs only guide users to those two. To migrate, rename your existing var to `Q402_MULTICHAIN_API_KEY` in `~/.q402/mcp.env` and restart your MCP client.
+
+</details>
 
 ---
 

package/dist/index.js

@@ -39,6 +39,7 @@ function loadQ402EnvFileFromPath(path) {
     );
     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 +169,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.10";
+var PACKAGE_VERSION = "0.5.12";
 
 // src/tools/quote.ts
 import { z } from "zod";
@@ -421,7 +422,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 +505,7 @@ var Q402NodeClient = class _Q402NodeClient {
   }
   async fetchFacilitator() {
     const url = `${this.opts.relayBaseUrl.replace(/\/$/, "")}/relay/info`;
-    const resp = await fetch(url);
+    const resp = await fetch(url, { signal: AbortSignal.timeout(1e4) });
     if (!resp.ok) {
       throw new Error(
         `failed to fetch relay facilitator info from ${url} (${resp.status})`
@@ -578,7 +579,8 @@ var Q402NodeClient = class _Q402NodeClient {
     const resp = await fetch(`${relayBaseUrl.replace(/\/$/, "")}/relay`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(body)
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(3e4)
     });
     const data = await resp.json();
     if (!resp.ok) {
@@ -699,7 +701,8 @@ var Q402NodeClient = class _Q402NodeClient {
         token,
         facilitator,
         recipients: signedRows
-      })
+      }),
+      signal: AbortSignal.timeout(6e4)
     });
     const data = await resp.json();
     if (!resp.ok || data.ok === false) {
@@ -808,6 +811,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);
@@ -826,7 +840,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,
@@ -843,13 +857,20 @@ 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 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.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 (!CONFIG.realPaymentsRequested) 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";
@@ -858,7 +879,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: {
@@ -897,7 +918,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;
@@ -962,6 +983,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;
@@ -970,6 +1002,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).
@@ -989,6 +1022,7 @@ async function runBatchPay(input) {
       mode: "sandbox",
       status: "sandbox",
       result: { sandbox: sandboxResults, reason },
+      senderWallet,
       guardsApplied,
       setupHint: reason
     };
@@ -1007,7 +1041,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");
@@ -1027,6 +1061,7 @@ async function runBatchPay(input) {
           results: err.results
         },
         guardsApplied,
+        senderWallet,
         error: err.message
       };
     }
@@ -1036,7 +1071,13 @@ async function runBatchPay(input) {
 function describeSandboxReason2(resolvedKey, scope) {
   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.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 (!CONFIG.realPaymentsRequested) 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";
@@ -1129,7 +1170,7 @@ async function runBalance() {
   if (CONFIG.trialApiKey) targets.push({ scope: "trial", key: CONFIG.trialApiKey });
   if (CONFIG.multichainApiKey) targets.push({ scope: "multichain", key: CONFIG.multichainApiKey });
   if (targets.length === 0 && CONFIG.legacyApiKey) {
-    targets.push({ scope: "legacy", key: CONFIG.legacyApiKey });
+    targets.push({ scope: "multichain", key: CONFIG.legacyApiKey });
   }
   if (targets.length === 0) {
     return {
@@ -1283,7 +1324,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,
@@ -1336,7 +1379,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) {
@@ -1347,7 +1390,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",
@@ -1358,7 +1401,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 {
@@ -1395,7 +1438,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",
@@ -1426,7 +1469,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,
@@ -1480,7 +1523,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) {
@@ -1536,7 +1580,7 @@ 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
@@ -1559,11 +1603,15 @@ var ENV_FILE_TEMPLATE = `# \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u250
 # 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
-# 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 Live mode switch \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+#   0 = sandbox (test mode, no funds move \u2014 every q402_pay returns a fake hash)
+#   1 = real on-chain payments (live mode)
+# Default is 1: real payments enabled. This is safe because mode only
+# flips to live when BOTH a live API key (q402_live_*) AND a valid
+# 32-byte private key are set above. Until you uncomment + paste both,
+# you stay in sandbox. Change to 0 to force sandbox even with real
+# keys (e.g. for chained testing on a paid plan).
+Q402_ENABLE_REAL_PAYMENTS=1
 
 # \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.
@@ -1578,10 +1626,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";
@@ -1733,7 +1781,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({
@@ -1774,15 +1832,35 @@ async function runDoctor() {
       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, 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.`,
+      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.",
+      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.",
+        "Get a free API key at https://q402.quackai.ai/event (BNB Chain only, 2,000 sponsored transactions).",
+        "Use a FRESH wallet for Q402 \u2014 don't use your main wallet. The wallet will be marked 'Smart account' in MetaMask after your first payment (that's normal \u2014 Q402 reverses it on demand).",
+        "Paste your key + wallet private key INTO THE FILE (in your editor) \u2014 never paste a private key into this chat.",
+        "Save the file, restart your MCP client, then ask me 'Verify Q402' to confirm."
+      ] : [
+        "Q402 is installed but a few env vars are still missing.",
+        "Open ~/.q402/mcp.env in your editor and fill in the lines I list below.",
+        "Save the file, then restart your MCP client (close + reopen Claude/Codex, or Cmd/Ctrl+Shift+P \u2192 Reload Window for Cursor/Cline).",
+        "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(
@@ -1838,13 +1916,28 @@ async function runDoctor() {
     warnings,
     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 ? "Summarize the wallet address, plan tier(s), remaining quota, and any non-zero delegation counts to the user as a checklist. Then offer to make a test payment via q402_quote." : "Walk the user through each warning in order. For slot-mismatch warnings, the fix is editing ~/.q402/mcp.env and restarting the client.",
-    securityNotice: SECURITY_NOTICE
+    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'.",
+    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?",
+      "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,
+    // 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 = {
   name: "q402_doctor",
-  description: 'Run a Q402 health check \u2014 covers first-install onboarding AND ongoing diagnostics in one tool. Read-only, no API key required. Detects the current phase (first-install / needs-completion / live-check) and tailors output to it. \n\nUse when the user says any of: "set up Q402", "verify Q402", "why isn\'t Q402 working", "Q402 status", "check Q402". This is the FIRST tool to call after install, BEFORE q402_pay or q402_balance \u2014 it tells the agent what state the user is in. \n\nMulti-turn pattern the AI should follow when phase = first-install: (1) Tell user MCP is installed. (2) Ask one yes/no question: \'Want me to create your secrets file at ~/.q402/mcp.env?\' (3) On yes, execute the recommendedActions[].write_file action using the client\'s own filesystem tool, then open the file in the user\'s editor (e.g. `code ~/.q402/mcp.env`, `open` on macOS, `start` on Windows, `xdg-open` on Linux). (4) Guide the user through getting an API key (free Trial at https://q402.quackai.ai/event OR paid Multichain at /payment) and pasting it into the file (in their editor \u2014 NEVER in chat). (5) Same for the private key. (6) Tell them to save + restart the MCP client. (7) Call q402_doctor again to verify. \n\nSecurity policy carried in the response: AI MUST surface the securityNotice when first walking through setup. If the user pastes a private key directly in chat, DO NOT refuse \u2014 the exposure already happened. Help them by directing them to put it in the file themselves (via their editor), and inform them the chat history now contains the key (most clients store this locally, some sync to cloud) so they should treat the wallet as exposed if it holds valuables. \n\nLive-check phase additionally returns per-scope quota, EIP-7702 delegation state per chain, relay reachability, and slot-mismatch warnings (e.g. Trial key in Multichain slot silently burns paid quota \u2014 surface this to the user).',
+  description: 'Run a Q402 health check \u2014 covers first-install onboarding AND ongoing diagnostics in one tool. Read-only, no API key required. Detects the current phase (first-install / needs-completion / live-check) and tailors output to it. \n\nUse when the user says any of: "set up Q402", "verify Q402", "why isn\'t Q402 working", "Q402 status", "check Q402". This is the FIRST tool to call after install, BEFORE q402_pay or q402_balance \u2014 it tells the agent what state the user is in. \n\nOutput uses TWO instruction surfaces \u2014 `agentInstructions` (prescription for you, the AI \u2014 do NOT echo verbatim) and `userInstructions` (plain language array you CAN show the user as a numbered list). Always show userInstructions; consult agentInstructions privately to decide what to ask next + which `recommendedActions` to execute. \n\nMulti-turn pattern the AI should follow when phase = first-install: (1) Tell user MCP is installed. (2) Ask one yes/no question: \'Want me to create your secrets file?\' (3) On yes, execute recommendedActions IN ORDER \u2014 first the `ensure-q402-dir` shell action (use shellWindows on Windows), then the `create-env-file` write_file action. Then open the file in the user\'s editor (e.g. `code` for VS Code / Cursor / Cline, `open` on macOS, `start` on Windows, `xdg-open` on Linux). (4) Guide the user through getting an API key (free Trial at https://q402.quackai.ai/event OR paid Multichain at /payment) and pasting it into the file (in their editor \u2014 NEVER in chat). (5) Same for the private key. (6) Tell them to save + restart the MCP client (per-client restart verb is in agentInstructions). (7) Call q402_doctor again to verify. \n\nSecurity policy carried in the response: AI MUST surface the securityNotice when first walking through setup. If the user pastes a private key directly in chat, DO NOT refuse \u2014 the exposure already happened. Help them by directing them to put it in the file themselves (via their editor), and inform them the chat history now contains the key (most clients store this locally, some sync to cloud) so they should treat the wallet as exposed if it holds valuables. \n\nLive-check phase additionally returns per-scope quota, EIP-7702 delegation state per chain, relay reachability, and slot-mismatch warnings (e.g. Trial key in Multichain slot silently burns paid quota \u2014 surface this to the user).',
   inputSchema: {
     type: "object",
     properties: {},

package/package.json

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