@quackai/q402-mcp 0.5.4 → 0.5.6

package/README.md

@@ -9,101 +9,95 @@
 >
 > **Trial-scope policy:** API keys minted under the free-trial program (`plan: "trial"`) are restricted to BNB Chain with USDC/USDT — server-side enforcement, returns `403 TRIAL_BNB_ONLY` otherwise. **Paid API keys see the full 9-chain matrix at all times.**
 
-Claude can now reason about stablecoin payments end to end — quote a transfer across 9 chains, pick the cheapest route, and (optionally) settle the transaction over [Q402](https://q402.quackai.ai)'s EIP-7702 relayer infrastructure. The recipient receives the full amount; the sender pays $0 in gas.
+AI agents — Claude (Desktop / Code), OpenAI Codex CLI, Cursor, Cline, and any other MCP-compatible client — can now reason about stablecoin payments end to end: quote a transfer across 9 chains, pick the cheapest route, and (optionally) settle the transaction over [Q402](https://q402.quackai.ai)'s EIP-7702 relayer infrastructure. The recipient receives the full amount; the sender pays $0 in gas.
 
 ---
 
 ## Quick start
 
-The server speaks stdio MCP, so any MCP-compatible client can use it. The two paths verified end-to-end today are **Claude (Desktop / Code)** and **OpenAI Codex CLI**.
+Two steps:
 
-### Claude Desktop / Claude Code
+1. Register the MCP server with your client (one-line install per client).
+2. Open your client and say: **"Set up Q402"**. The agent calls `q402_doctor` which walks you through creating a single secrets file at `~/.q402/mcp.env` and pasting in your API key + private key. Nothing else.
 
-```bash
-claude mcp add q402 -- npx -y @quackai/q402-mcp
-```
+### 1. Register the server
 
-Or edit `claude_desktop_config.json` directly:
-
-```json
-{
-  "mcpServers": {
-    "q402": {
-      "command": "npx",
-      "args": ["-y", "@quackai/q402-mcp"]
-    }
-  }
-}
-```
+| Client | Command / config |
+|---|---|
+| **Claude Desktop / Claude Code** | `claude mcp add q402 -- npx -y @quackai/q402-mcp` |
+| **OpenAI Codex CLI** | `codex mcp add q402 -- npx -y @quackai/q402-mcp` |
+| **Cursor** | Add to `~/.cursor/mcp.json`: `{ "mcpServers": { "q402": { "command": "npx", "args": ["-y", "@quackai/q402-mcp"] } } }` |
+| **Cline** | Cline → Settings → MCP Servers → Edit JSON. Same shape as Cursor. |
+| **Any other stdio MCP client** | Point it at `npx -y @quackai/q402-mcp`. No client-specific code. |
 
-Restart Claude Desktop and ask:
+That's it — secrets are NOT configured here. The MCP server reads them from `~/.q402/mcp.env` at startup (same pattern as AWS CLI / Stripe CLI / gh CLI), so every client uses the same file with no per-client wiring.
 
-> *"Compare gas costs to send 50 USDC to vitalik.eth across all 9 Q402 chains."*
+### 2. First-time setup
 
-### OpenAI Codex CLI
+Restart your client, then ask your agent:
 
-Three install paths — pick the one that matches your workflow.
+> *"Set up Q402"*
 
-**(a) Codex plugin marketplace** (recommended — bundles the MCP config so users don't write TOML):
+The agent calls `q402_doctor`. On first install, the tool tells the agent to:
 
-```bash
-codex plugin marketplace add bitgett/q402-mcp
-codex /plugins        # browse and install "q402"
-```
+1. Offer to create `~/.q402/mcp.env` (placeholder values only)
+2. Open the file in your editor (`code` / `open` / `start` / `xdg-open`)
+3. Walk you through pasting in (a) your API key from <https://q402.quackai.ai/event> (free Trial) or <https://q402.quackai.ai/payment> (paid Multichain), and (b) your wallet private key — **into the file, not into chat**
+4. Restart the client and run `q402_doctor` again to verify
 
-This repo carries a Codex plugin manifest at [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json) and a marketplace catalog at [`.agents/plugins/marketplace.json`](./.agents/plugins/marketplace.json), so any signed-in Codex user can register it as a marketplace source and install with one click.
+🔒 **Q402 never asks you to paste your private key into chat.** The MCP server signs payments LOCALLY on your machine — your key never leaves your device.
 
-**(b) Single MCP server via `codex mcp add`** (no plugin wrapper — just register the stdio server):
+### Manual setup (no AI)
+
+Create `~/.q402/mcp.env` yourself:
 
 ```bash
-codex mcp add q402 -- npx -y @quackai/q402-mcp
+# ~/.q402/mcp.env
+# Pick ONE of these:
+Q402_TRIAL_API_KEY=q402_live_...
+# Q402_MULTICHAIN_API_KEY=q402_live_...
+
+Q402_PRIVATE_KEY=0x...
+Q402_ENABLE_REAL_PAYMENTS=1
+Q402_RELAY_BASE_URL=https://q402.quackai.ai/api
+
+# Optional safety guards:
+# Q402_MAX_AMOUNT_PER_CALL=5
+# Q402_ALLOWED_RECIPIENTS=0xabc...,0xdef...
 ```
 
-**(c) Direct `~/.codex/config.toml` edit** (`.codex/config.toml` for per-project scope):
+Then `chmod 600 ~/.q402/mcp.env` (Unix) and restart your client. That's the full configuration.
 
-```toml
-[mcp_servers.q402]
-command = "npx"
-args = ["-y", "@quackai/q402-mcp"]
-startup_timeout_sec = 20.0
-```
+### Advanced — explicit env injection
+
+If you'd rather skip the file and inject env vars yourself (e.g. via Codex `env_vars` allow-list, a secrets manager, or shell exports), the server falls through to `process.env` — and `process.env` wins over file values on conflicts. So existing shell-export setups keep working unchanged.
 
-To enable real on-chain payments, pass the three live-mode env vars **explicitly** under `env` — Codex does **not** forward host env vars by default:
+<details>
+<summary>Codex <code>env_vars</code> allow-list example</summary>
 
 ```toml
 [mcp_servers.q402]
 command = "npx"
 args = ["-y", "@quackai/q402-mcp"]
 startup_timeout_sec = 20.0
-env = {
-  # Two-key model: set whichever applies — both is best.
-  # Auto-routing rule (same for q402_pay AND q402_batch_pay):
-  #   chain="bnb" + Q402_TRIAL_API_KEY set  → Trial (free sponsored)
-  #   anything else                          → Multichain (paid 9-chain)
-  # Batch ambiguity: when auto would land on Trial AND recipients.length > 5,
-  # q402_batch_pay returns status="ambiguous" WITHOUT executing so the agent
-  # can ask the user — pass keyScope="trial" (first 5), "multichain" (all
-  # paid), or call twice (5 free + remainder paid).
-  # 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 9-chain (from /payment)
-  # Legacy fallback — used if neither scoped key above is set.
-  Q402_API_KEY              = "q402_live_...",
-  Q402_PRIVATE_KEY          = "0xabc...",
-  Q402_ENABLE_REAL_PAYMENTS = "1",
-  Q402_MAX_AMOUNT_PER_CALL  = "5",
-}
+env_vars = [
+  "Q402_TRIAL_API_KEY",
+  "Q402_MULTICHAIN_API_KEY",
+  "Q402_PRIVATE_KEY",
+  "Q402_ENABLE_REAL_PAYMENTS",
+  "Q402_RELAY_BASE_URL",
+]
 ```
 
-> If you'd rather not inline secrets in `config.toml`, use the `env_vars` allow-list form to forward specific names from your shell environment instead — see the [Codex config reference](https://developers.openai.com/codex/config-reference) for the full schema.
+Then export the values in `~/.zshrc` / `~/.bashrc`. See the [Codex config reference](https://developers.openai.com/codex/config-reference) for the full schema.
 
-Then run `codex` and ask the same kind of question. The first call may take a few seconds while `npx` warms its cache; subsequent calls are instant.
+</details>
 
-### Any other MCP client
+### Try it without any setup
 
-The server has no client-specific code. If your client speaks stdio MCP, point it at `npx -y @quackai/q402-mcp` and the seven tools listed below will appear.
+`q402_quote` works with zero configuration — no API key, no private key, no env file. Ask:
+
+> *"Compare gas costs to send 50 USDC to vitalik.eth across all 9 Q402 chains."*
 
 ---
 
@@ -115,6 +109,7 @@ The server has no client-specific code. If your client speaks stdio MCP, point i
 
 | Tool | Auth | Purpose |
 |---|---|---|
+| `q402_doctor` | none | Health check covering BOTH first-install onboarding AND ongoing operational diagnostics. AI calls this when the user says "set up Q402" / "verify Q402" / "why isn't Q402 working". On first install, returns a `recommendedActions[]` payload telling the client to create `~/.q402/mcp.env` and open it in the user's editor. Later phases verify per-scope quota, EIP-7702 delegation state per chain, relay reachability, and surface slot-mismatch warnings (e.g. Trial-tier key sitting in `Q402_MULTICHAIN_API_KEY` would silently burn paid quota). Read-only — no signing, no on-chain action. |
 | `q402_quote` | none | Compare gas cost and supported tokens across chains. Read-only. |
 | `q402_balance` | API key | Verify the API key and report its plan tier + remaining quota credits (live vs sandbox). |
 | `q402_pay` | API key + private key + flag | Send a gasless payment to a single recipient. **Sandbox by default** — see [Sandbox vs live mode](#sandbox-vs-live-mode). |
@@ -136,7 +131,7 @@ The server has no client-specific code. If your client speaks stdio MCP, point i
 
 ## Sandbox vs live mode
 
-By default the MCP server operates in **sandbox mode**: `q402_pay` returns a random fake transaction hash (32-byte hex, no on-chain broadcast), no funds move, no gas-tank credit is consumed. That makes it safe to plug into any MCP client without worrying about an LLM hallucinating a payment.
+By default the MCP server operates in **sandbox mode**: `q402_pay` returns a random fake transaction hash (32-byte hex, no on-chain broadcast), 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.
 
 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`:
 
@@ -211,11 +206,11 @@ Combined with the `confirm: true` argument the tool requires, this means the mod
 
 ## Why this exists
 
-x402 standardised "402 Payment Required" semantics for AI agents but the official Coinbase facilitator only covers a few chains and assumes ERC-3009 token support — which excludes BNB USDT, Mantle USDT0, Injective USDT, and the chains where most stablecoin volume actually lives.
+AI agents are becoming the default interface for software, but the moment they need to move money the stack breaks: holding gas tokens, signing every transaction, managing wallets across many chains. None of that scales when the agent is supposed to act on its own.
 
-Q402 implements the same payer experience (single signature, $0 gas, instant settlement) on all 9 of those chains using EIP-7702 delegated execution, which works with any ERC-20. This MCP server makes that infrastructure addressable from Claude itself.
+Q402 is the payment layer for that gap. A single signing primitive (EIP-712 + EIP-7702) settles gasless stablecoin payments across 9 EVM chains, with an ECDSA-signed Trust Receipt for every transaction. The MCP package exposes that surface inside Claude, Codex, Cursor, and Cline — your agent can quote, send, batch, and audit payments from a natural-language prompt.
 
-If you want to dig into how the wire protocol differs from x402, see [Q402 docs](https://q402.quackai.ai/docs).
+Single transfers and multi-recipient batches ship today. The next layer — recurring payouts, conditional execution, and policy-gated treasury automation — is the same primitive composed differently. We're building toward agents that operate real budgets, settle among themselves, and move value through workflows no human triggers manually.
 
 ---
 

package/dist/index.js

@@ -9,7 +9,63 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 
 // src/config.ts
+import { existsSync, readFileSync, statSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
 import { isAddress } from "ethers";
+var Q402_ENV_FILE = join(homedir(), ".q402", "mcp.env");
+function loadQ402EnvFileFromPath(path) {
+  if (!existsSync(path)) return {};
+  if (process.platform !== "win32") {
+    try {
+      const mode = statSync(path).mode & 511;
+      if (mode & 63) {
+        process.stderr.write(
+          `[q402-mcp] warning: ${path} is readable by group/other (mode ${mode.toString(8)}). Run: chmod 600 ${path}
+`
+        );
+      }
+    } catch {
+    }
+  }
+  const out = {};
+  let raw;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch (e) {
+    process.stderr.write(
+      `[q402-mcp] warning: could not read ${path}: ${e instanceof Error ? e.message : String(e)}
+`
+    );
+    return {};
+  }
+  for (const line of raw.split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t || t.startsWith("#")) continue;
+    const eq = t.indexOf("=");
+    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;
+  }
+  return out;
+}
+function loadQ402EnvFile() {
+  return loadQ402EnvFileFromPath(Q402_ENV_FILE);
+}
+var FILE_ENV = loadQ402EnvFile();
+var ENV = Object.freeze({
+  ...FILE_ENV,
+  ...process.env
+});
+var Q402_ENV_FILE_PATH = Q402_ENV_FILE;
+var Q402_ENV_FILE_PRESENT = existsSync(Q402_ENV_FILE);
+var Q402_ENV_FILE_KEYS = Object.freeze(
+  new Set(
+    Object.keys(FILE_ENV).filter((k) => process.env[k] === void 0)
+  )
+);
 var DEFAULT_RELAY_BASE = "https://q402.quackai.ai/api";
 var DEFAULT_MAX_AMOUNT = 5;
 function classifyApiKey(k) {
@@ -29,13 +85,13 @@ function parseMaxAmount(raw) {
   return n;
 }
 function loadConfig() {
-  const trialApiKey = process.env.Q402_TRIAL_API_KEY ?? null;
-  const multichainApiKey = process.env.Q402_MULTICHAIN_API_KEY ?? null;
-  const legacyApiKey = process.env.Q402_API_KEY ?? null;
+  const trialApiKey = ENV.Q402_TRIAL_API_KEY ?? null;
+  const multichainApiKey = ENV.Q402_MULTICHAIN_API_KEY ?? null;
+  const legacyApiKey = ENV.Q402_API_KEY ?? null;
   const apiKey = multichainApiKey ?? trialApiKey ?? legacyApiKey;
   const apiKeyKind = classifyApiKey(apiKey);
-  const privateKey = process.env.Q402_PRIVATE_KEY ?? null;
-  const realPaymentsRequested = process.env.Q402_ENABLE_REAL_PAYMENTS === "1";
+  const privateKey = ENV.Q402_PRIVATE_KEY ?? null;
+  const realPaymentsRequested = ENV.Q402_ENABLE_REAL_PAYMENTS === "1";
   const live = realPaymentsRequested && apiKeyKind === "live" && typeof privateKey === "string" && privateKey.length > 0;
   return {
     trialApiKey,
@@ -46,9 +102,9 @@ function loadConfig() {
     privateKey,
     realPaymentsRequested,
     mode: live ? "live" : "sandbox",
-    relayBaseUrl: (process.env.Q402_RELAY_BASE_URL ?? DEFAULT_RELAY_BASE).replace(/\/$/, ""),
-    maxAmountPerCallUsd: parseMaxAmount(process.env.Q402_MAX_AMOUNT_PER_CALL),
-    allowedRecipients: parseAllowedRecipients(process.env.Q402_ALLOWED_RECIPIENTS)
+    relayBaseUrl: (ENV.Q402_RELAY_BASE_URL ?? DEFAULT_RELAY_BASE).replace(/\/$/, ""),
+    maxAmountPerCallUsd: parseMaxAmount(ENV.Q402_MAX_AMOUNT_PER_CALL),
+    allowedRecipients: parseAllowedRecipients(ENV.Q402_ALLOWED_RECIPIENTS)
   };
 }
 var CONFIG = loadConfig();
@@ -97,6 +153,10 @@ function isLiveModeFor(resolved) {
   return resolved.apiKey.startsWith("q402_live_");
 }
 
+// src/version.ts
+var PACKAGE_NAME = "@quackai/q402-mcp";
+var PACKAGE_VERSION = "0.5.6";
+
 // src/tools/quote.ts
 import { z } from "zod";
 
@@ -748,7 +808,7 @@ async function runPay(input) {
       token: input.token
     });
     guardsApplied.push("mode=sandbox");
-    const setupHint = resolved.sandboxReason ?? describeSandboxReason(resolved.apiKey ?? "");
+    const setupHint = resolved.sandboxReason ?? describeSandboxReason(resolved.apiKey ?? "", resolved.scope);
     return { result: result2, guardsApplied, setupHint };
   }
   const client = new Q402NodeClient({
@@ -765,17 +825,19 @@ async function runPay(input) {
   guardsApplied.push("mode=live");
   return { result, guardsApplied };
 }
-function describeSandboxReason(resolvedKey) {
+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.realPaymentsRequested) missing.push("Q402_ENABLE_REAL_PAYMENTS=1");
   if (missing.length === 0) return "Sandbox mode active (no env state change needed).";
-  return "Sandbox mode is active because the following env vars are missing or not yet set: " + missing.join(", ") + ". Get a live API key at https://q402.quackai.ai/dashboard.";
+  const tier = scope === "trial" ? "Free Trial" : "Multichain";
+  const url = scope === "trial" ? "https://q402.quackai.ai/event" : "https://q402.quackai.ai/payment";
+  return "Sandbox mode is active because the following env vars are missing or not yet set: " + missing.join(", ") + `. Get a live ${tier} key at ${url}, then call q402_doctor \u2014 it will walk the user through creating ~/.q402/mcp.env and pasting the key into the right slot.`;
 }
 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. Note: the first q402_pay on a chain creates a persistent EIP-7702 delegation on the sender's EOA (set-code TX, Pectra). Subsequent payments on the same chain reuse it (gas-efficient). To remove the delegation later, call q402_clear_delegation. 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, 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.",
   inputSchema: {
     type: "object",
     properties: {
@@ -901,7 +963,7 @@ async function runBatchPay(input) {
       (r) => sandboxPay(chain, { to: r.to, amount: r.amount, token: input.token })
     );
     guardsApplied.push("mode=sandbox");
-    const reason = resolved.sandboxReason ?? describeSandboxReason2(resolved.apiKey ?? "");
+    const reason = resolved.sandboxReason ?? describeSandboxReason2(resolved.apiKey ?? "", resolved.scope);
     return {
       mode: "sandbox",
       status: "sandbox",
@@ -950,17 +1012,19 @@ async function runBatchPay(input) {
     throw err;
   }
 }
-function describeSandboxReason2(resolvedKey) {
+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.realPaymentsRequested) missing.push("Q402_ENABLE_REAL_PAYMENTS=1");
   if (missing.length === 0) return "Sandbox mode active (no env state change needed).";
-  return "Sandbox mode is active because the following env vars are missing or not yet set: " + missing.join(", ") + ". Get a live API key at https://q402.quackai.ai/dashboard.";
+  const tier = scope === "trial" ? "Free Trial" : "Multichain";
+  const url = scope === "trial" ? "https://q402.quackai.ai/event" : "https://q402.quackai.ai/payment";
+  return "Sandbox mode is active because the following env vars are missing or not yet set: " + missing.join(", ") + `. Get a live ${tier} key at ${url}, then call q402_doctor \u2014 it will walk the user through creating ~/.q402/mcp.env and pasting the key into the right slot.`;
 }
 var BATCH_PAY_TOOL = {
   name: "q402_batch_pay",
-  description: `Send gasless payments to MULTIPLE recipients on a single chain \xD7 token in one call. Auto-routing follows the same rule as q402_pay: chain='bnb' + Q402_TRIAL_API_KEY set \u2192 Trial; else Multichain. Trial keys: max ${RECIPIENT_LIMIT_TRIAL} recipients per call, BNB Chain + USDC/USDT only. Multichain keys: max ${RECIPIENT_LIMIT_PAID} recipients per call across 7 EIP-7702 default chains (avax, bnb, eth, mantle, injective, monad, scroll). xlayer + stable are NOT batchable \u2014 use q402_pay in a loop. AMBIGUITY GATE: when auto would land on Trial AND recipients.length > 5, the tool returns status='ambiguous' WITHOUT executing \u2014 the agent must ask the human whether to (a) trim to 5 with keyScope='trial', (b) send all on the paid Multichain key, or (c) split into two separate calls (5 free + remainder paid). Re-invoke with explicit keyScope after the choice. SANDBOX BY DEFAULT \u2014 real on-chain TX only when the resolved key is live (q402_live_*), Q402_PRIVATE_KEY is set, and Q402_ENABLE_REAL_PAYMENTS=1. Every recipient receives the full amount; the sender pays $0 in gas for the entire batch. Note: same EIP-7702 delegation behaviour as q402_pay \u2014 the first call on a chain creates a persistent set-code delegation on the sender's EOA, reused by subsequent calls. Use q402_clear_delegation to remove. ALWAYS get explicit user confirmation of the complete recipient + amount list, chain, and token in conversation immediately before calling this tool \u2014 the user must approve the full batch, not the individual rows.`,
+  description: `Send gasless payments to MULTIPLE recipients on a single chain \xD7 token in one call. Auto-routing follows the same rule as q402_pay: chain='bnb' + Q402_TRIAL_API_KEY set \u2192 Trial; else Multichain. Trial keys: max ${RECIPIENT_LIMIT_TRIAL} recipients per call, BNB Chain + USDC/USDT only. Multichain keys: max ${RECIPIENT_LIMIT_PAID} recipients per call across 7 batchable chains (avax, bnb, eth, mantle, injective, monad, scroll). xlayer + stable are NOT batchable \u2014 use q402_pay in a loop. AMBIGUITY GATE: when auto would land on Trial AND recipients.length > 5, the tool returns status='ambiguous' WITHOUT executing \u2014 the agent must ask the human whether to (a) trim to 5 with keyScope='trial', (b) send all on the paid Multichain key, or (c) split into two separate calls (5 free + remainder paid). Re-invoke with explicit keyScope after the choice. SANDBOX BY DEFAULT \u2014 real on-chain TX only when the resolved key is live (q402_live_*), Q402_PRIVATE_KEY is set, and Q402_ENABLE_REAL_PAYMENTS=1. Every recipient receives the full amount; the sender pays $0 in gas for the entire batch. After the first batch on a chain, follow-up batches 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 complete recipient + amount list, chain, and token in conversation immediately before calling this tool \u2014 the user must approve the full batch, not the individual rows.`,
   inputSchema: {
     type: "object",
     properties: {
@@ -1052,7 +1116,7 @@ async function runBalance() {
       apiKeyMasked: null,
       scopes: [],
       dashboardUrl: "https://q402.quackai.ai/dashboard",
-      setupHint: "Set Q402_TRIAL_API_KEY (BNB-only sponsored, free at /event) and/or Q402_MULTICHAIN_API_KEY (paid 9-chain from /dashboard). Single-env legacy: Q402_API_KEY also works."
+      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.)"
     };
   }
   const scopes = await Promise.all(
@@ -1271,19 +1335,24 @@ async function runWalletStatus() {
   }
   const url = `${CONFIG.relayBaseUrl.replace(/\/$/, "")}/wallet/delegation-status?address=${address}`;
   let body;
+  let res;
   try {
-    const res = await fetch(url);
+    res = await fetch(url);
     body = await res.json();
-    if (!res.ok) {
-      return {
-        address,
-        error: typeof body === "object" && body && "error" in body ? String(body.error) : `HTTP ${res.status}`
-      };
-    }
   } catch (e) {
     return {
       address,
-      error: e instanceof Error ? e.message : String(e)
+      error: "RELAY_UNREACHABLE",
+      hint: `Could not reach Q402 at ${url}: ${e instanceof Error ? e.message : String(e)}`
+    };
+  }
+  if (!res.ok) {
+    const errBody = body;
+    return {
+      address,
+      error: errBody.error ?? `HTTP ${res.status}`,
+      hint: errBody.hint ?? errBody.reason,
+      retryAfterSec: errBody.retryAfterSec
     };
   }
   const parsed = body;
@@ -1444,9 +1513,278 @@ var CLEAR_DELEGATION_TOOL = {
   }
 };
 
+// src/tools/doctor.ts
+import { z as z8 } from "zod";
+import { Wallet as Wallet4 } from "ethers";
+var DoctorInputSchema = z8.object({});
+var ENV_FILE_TEMPLATE = `# \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+# Q402 MCP \u2014 secrets
+# Read automatically by @quackai/q402-mcp on startup.
+# Edit this file in your editor. NEVER paste your private key into chat.
+# After editing, restart your MCP client (Codex / Claude / Cursor / Cline).
+# \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\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
+# Free Trial:        BNB Chain only, 2,000 sponsored TX
+# Get one at:        https://q402.quackai.ai/event
+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...
+
+# \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
+
+# \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.
+Q402_RELAY_BASE_URL=https://q402.quackai.ai/api
+
+# \u2500\u2500\u2500 Optional safety guards \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+# Max USD per single q402_pay call (default: 5)
+# Q402_MAX_AMOUNT_PER_CALL=5
+#
+# Comma-separated lowercase recipient allowlist (unset = any address OK)
+# 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.";
+function envSource(name) {
+  if (process.env[name] !== void 0) return "process";
+  if (Q402_ENV_FILE_KEYS.has(name)) return "file";
+  if (ENV[name] !== void 0) return "file";
+  return "unset";
+}
+function envSlot(name, purpose) {
+  const source = envSource(name);
+  return { set: source !== "unset", source, purpose };
+}
+function mask2(key) {
+  if (!key || key.length < 12) return key ?? "";
+  return `${key.slice(0, 12)}\u2026${key.slice(-4)}`;
+}
+function detectPhase() {
+  const anyKey = !!(CONFIG.trialApiKey || CONFIG.multichainApiKey || CONFIG.legacyApiKey);
+  const allEssentials = anyKey && !!CONFIG.privateKey && CONFIG.realPaymentsRequested && CONFIG.apiKeyKind === "live";
+  if (allEssentials) return "live-check";
+  if (anyKey || CONFIG.privateKey || CONFIG.realPaymentsRequested) return "needs-completion";
+  return "first-install";
+}
+async function verifyOneKey(scope, envVar, apiKey) {
+  const url = `${CONFIG.relayBaseUrl}/keys/verify`;
+  try {
+    const resp = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ apiKey })
+    });
+    if (!resp.ok) {
+      return { scope, envVar, apiKeyMasked: mask2(apiKey), valid: false, error: `HTTP ${resp.status}` };
+    }
+    const body = await resp.json();
+    const result = {
+      scope,
+      envVar,
+      apiKeyMasked: mask2(apiKey),
+      valid: body.valid ?? false,
+      plan: body.plan,
+      remainingCredits: body.remainingCredits,
+      isTrial: body.isTrial,
+      trialExpiresAt: body.trialExpiresAt,
+      trialDaysLeft: body.trialDaysLeft
+    };
+    if (scope === "multichain" && body.isTrial) {
+      result.slotWarning = "Trial-tier key found in Q402_MULTICHAIN_API_KEY slot. This works but you'll lose the auto-routing benefit (BNB free via Trial). Move the key to Q402_TRIAL_API_KEY in ~/.q402/mcp.env.";
+    } else if (scope === "trial" && body.isTrial === false && body.plan && body.plan !== "trial") {
+      result.slotWarning = "Paid Multichain-tier key found in Q402_TRIAL_API_KEY slot. BNB payments will burn your paid quota instead of using free Trial sponsorship. Move the key to Q402_MULTICHAIN_API_KEY in ~/.q402/mcp.env.";
+    }
+    return result;
+  } catch (e) {
+    return {
+      scope,
+      envVar,
+      apiKeyMasked: mask2(apiKey),
+      valid: false,
+      error: e instanceof Error ? e.message : String(e)
+    };
+  }
+}
+async function pingRelay() {
+  const url = `${CONFIG.relayBaseUrl}/health`;
+  const t0 = Date.now();
+  try {
+    const resp = await fetch(url, { method: "GET" });
+    const reachable = resp.status < 500;
+    return { url, reachable, latencyMs: Date.now() - t0 };
+  } catch (e) {
+    return {
+      url,
+      reachable: false,
+      latencyMs: Date.now() - t0,
+      error: e instanceof Error ? e.message : String(e)
+    };
+  }
+}
+async function fetchDelegation(address) {
+  const url = `${CONFIG.relayBaseUrl}/wallet/delegation-status?address=${address}`;
+  try {
+    const resp = await fetch(url);
+    if (!resp.ok) {
+      return CHAIN_KEYS.map((chain) => ({ chain, delegated: false, error: `HTTP ${resp.status}` }));
+    }
+    const body = await resp.json();
+    return CHAIN_KEYS.map((chain) => {
+      const s = body.chains?.[chain];
+      if (!s) return { chain, delegated: false, error: "missing from response" };
+      return { chain, delegated: s.delegated, impl: s.impl, error: s.error };
+    });
+  } catch (e) {
+    const error = e instanceof Error ? e.message : String(e);
+    return CHAIN_KEYS.map((chain) => ({ chain, delegated: false, error }));
+  }
+}
+async function runDoctor() {
+  const phase = detectPhase();
+  const envFile = {
+    path: Q402_ENV_FILE_PATH,
+    exists: Q402_ENV_FILE_PRESENT
+  };
+  const envState = {
+    Q402_TRIAL_API_KEY: envSlot(
+      "Q402_TRIAL_API_KEY",
+      "Free Trial \u2014 BNB only, 2,000 sponsored TX. Get at https://q402.quackai.ai/event"
+    ),
+    Q402_MULTICHAIN_API_KEY: envSlot(
+      "Q402_MULTICHAIN_API_KEY",
+      "Paid Multichain \u2014 all 9 chains, per-chain Gas Tank. Get at https://q402.quackai.ai/payment"
+    ),
+    Q402_PRIVATE_KEY: envSlot(
+      "Q402_PRIVATE_KEY",
+      "Hex EVM private key. Signs LOCALLY on your machine \u2014 never leaves your device."
+    ),
+    Q402_ENABLE_REAL_PAYMENTS: envSlot(
+      "Q402_ENABLE_REAL_PAYMENTS",
+      "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.realPaymentsRequested) missing.push("Q402_ENABLE_REAL_PAYMENTS=1");
+  const recommendedActions = [];
+  if (!envFile.exists) {
+    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.",
+      ifExists: "skip"
+    });
+  }
+  const warnings = [];
+  if (phase !== "live-check") {
+    return {
+      package: PACKAGE_NAME,
+      version: PACKAGE_VERSION,
+      phase,
+      ready: false,
+      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
+    };
+  }
+  let walletAddress;
+  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.");
+  }
+  const verifyTargets = [];
+  if (CONFIG.trialApiKey) verifyTargets.push({ scope: "trial", envVar: "Q402_TRIAL_API_KEY", key: CONFIG.trialApiKey });
+  if (CONFIG.multichainApiKey) verifyTargets.push({ scope: "multichain", envVar: "Q402_MULTICHAIN_API_KEY", key: CONFIG.multichainApiKey });
+  if (verifyTargets.length === 0 && CONFIG.legacyApiKey) {
+    verifyTargets.push({ scope: "legacy", envVar: "Q402_API_KEY", key: CONFIG.legacyApiKey });
+  }
+  const [keys, delegation, relay] = await Promise.all([
+    Promise.all(verifyTargets.map((t) => verifyOneKey(t.scope, t.envVar, t.key))),
+    walletAddress ? fetchDelegation(walletAddress) : Promise.resolve([]),
+    pingRelay()
+  ]);
+  for (const k of keys) if (k.slotWarning) warnings.push(k.slotWarning);
+  for (const k of keys) {
+    if (typeof k.remainingCredits === "number" && k.remainingCredits === 0) {
+      warnings.push(
+        `${k.envVar} has 0 credits remaining. ` + (k.isTrial ? "Trial allotment exhausted \u2014 upgrade to a Multichain plan at https://q402.quackai.ai/payment." : "Paid plan quota exhausted \u2014 top up at https://q402.quackai.ai/dashboard?tab=billing.")
+      );
+    } else if (typeof k.remainingCredits === "number" && k.remainingCredits > 0 && k.remainingCredits < 50) {
+      warnings.push(
+        `${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 (relay && !relay.reachable) {
+    warnings.push(
+      `Q402 relay at ${relay.url} is unreachable. Check your network or override with Q402_RELAY_BASE_URL if you self-host.`
+    );
+  }
+  const ready = warnings.length === 0 && keys.some((k) => k.valid);
+  return {
+    package: PACKAGE_NAME,
+    version: PACKAGE_VERSION,
+    phase,
+    ready,
+    envFile,
+    envState,
+    missing,
+    legacyDetected,
+    wallet: walletAddress ? { address: walletAddress } : void 0,
+    keys,
+    delegation,
+    relay,
+    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
+  };
+}
+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).',
+  inputSchema: {
+    type: "object",
+    properties: {},
+    additionalProperties: false
+  }
+};
+
 // src/index.ts
-var PACKAGE_NAME = "@quackai/q402-mcp";
-var PACKAGE_VERSION = "0.5.4";
 function jsonText(value) {
   return { type: "text", text: JSON.stringify(value, null, 2) };
 }
@@ -1457,6 +1795,9 @@ async function main() {
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
+      // doctor first — it's the bootstrap tool: any "set up Q402" / "is Q402
+      // working" prompt should land here before quote/balance/pay are tried.
+      DOCTOR_TOOL,
       QUOTE_TOOL,
       BALANCE_TOOL,
       PAY_TOOL,
@@ -1470,6 +1811,10 @@ async function main() {
     const { name, arguments: args } = req.params;
     try {
       switch (name) {
+        case "q402_doctor": {
+          DoctorInputSchema.parse(args ?? {});
+          return { content: [jsonText(await runDoctor())] };
+        }
         case "q402_quote": {
           const parsed = QuoteInputSchema.parse(args ?? {});
           return { content: [jsonText(runQuote(parsed))] };

package/package.json

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