@quackai/q402-mcp 0.6.1 → 0.6.3

package/README.md

@@ -57,35 +57,55 @@ The agent calls `q402_doctor`. On first install, the tool tells the agent to:
 
 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**
+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) a signing path — **into the file, not into chat**
 4. Restart the client and run `q402_doctor` again to verify
 
-🔒 **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.
+🔒 **Q402 never asks you to paste your private key into chat.** When you use a local signing mode the MCP server signs payments LOCALLY on your machine — your key never leaves your device. Mode C (server-managed Agent Wallet) requires no private key on the client at all.
+
+### Pick a signing mode
+
+Q402 supports three signing modes — pick ONE:
+
+| Mode | Env you set | Signer | Notes |
+|---|---|---|---|
+| **A** | `Q402_PRIVATE_KEY` | your MetaMask EOA, local | Simplest. After the first payment that EOA shows "Smart account" in MetaMask (EIP-7702 delegation, reversible via `q402_clear_delegation`). |
+| **B** | `Q402_AGENTIC_PRIVATE_KEY` | dedicated Agent Wallet, local | Export the PK from the [dashboard](https://q402.quackai.ai/dashboard) Agent tab → Export. Signs locally just like Mode A, but the signer is your Agent Wallet — MetaMask is never touched. Recommended for AI-agent automation. |
+| **C** | (just the paid API key) | dedicated Agent Wallet, server-managed | The encrypted Agent Wallet key lives on the Q402 server and signs on your behalf. No private key on the client. Optionally set `Q402_AGENT_WALLET_ADDRESS` to pick among multiple wallets (max 10 per owner). Mode C requires a paid Multichain API key — not available on the free Trial. |
+
+When more than one signing mode is set at once, `q402_pay` asks the user which to use rather than picking silently. The picker lives in the `walletMode` argument: `"agentic-server"` (Mode C), `"agentic-local"` (Mode B), `"eoa"` (Mode A).
 
 ### Manual setup (no AI)
 
-Create `~/.q402/mcp.env` yourself. The template below matches what `q402_doctor` writes — the three secret lines (`Q402_TRIAL_API_KEY`, `Q402_MULTICHAIN_API_KEY`, `Q402_PRIVATE_KEY`) ship empty, with `Q402_ENABLE_REAL_PAYMENTS=1`. Paste real values on the right of `=` for the key(s) you have and your wallet key. The server only flips into live mode once both a `q402_live_*` API key AND a valid 32-byte private key are present, so saving the template as-is is safe (empty values fail the gate and stay in sandbox). Change the flag to `0` if you want to force sandbox even with real keys (e.g. for chained testing).
+Create `~/.q402/mcp.env` yourself. The template below matches what `q402_doctor` writes — every secret line ships empty, with `Q402_ENABLE_REAL_PAYMENTS=1`. Fill in (a) at least one API key and (b) the row(s) for the signing mode you picked. The server only flips into live mode once both a `q402_live_*` API key AND a valid signing path are present, so saving the template as-is is safe (empty values fail the gate and stay in sandbox). Change the flag to `0` to force sandbox even with real keys (e.g. for chained testing).
 
 ```bash
 # ~/.q402/mcp.env
 
-# Free Trial — BNB only, 2,000 sponsored TX (from /event)
-Q402_TRIAL_API_KEY=
+# ── API key (pick one or both for auto-routing) ──
+Q402_TRIAL_API_KEY=          # Free Trial, BNB only (from /event)
+Q402_MULTICHAIN_API_KEY=     # Paid Multichain, all 9 chains (from /payment)
 
-# Paid Multichain — all 9 chains (from /payment)
-Q402_MULTICHAIN_API_KEY=
-
-# Hex EVM private key (0x + 64 hex). A separate MetaMask account
-# dedicated to Q402 keeps your existing balances and history tidy.
-# Hardware wallets (Ledger / Trezor) are not supported yet — Q402
+# ── Signing path — pick ONE of Mode A / B / C ──
+# Mode A: your MetaMask EOA's hex private key.
+# Hardware wallets (Ledger / Trezor) are NOT supported here — Q402
 # needs a raw hex key it can sign EIP-7702 type-4 authorizations with.
 Q402_PRIVATE_KEY=
 
+# Mode B: exported Agent Wallet pk from the dashboard. Keeps your
+# MetaMask untouched. Get it at:
+#   https://q402.quackai.ai/dashboard → Agent tab → Export
+Q402_AGENTIC_PRIVATE_KEY=
+
+# Mode C: no PK needed. Set ONLY the paid Multichain key above, leave
+# both PK lines blank. Q402 signs with the server-managed Agent Wallet.
+# Optional: pin one of your Agent Wallets when you have multiple (max 10).
+# Q402_AGENT_WALLET_ADDRESS=0x...
+
 # 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 populated above.
+# Default 1 — safe because mode only flips to live when an API key AND
+# at least one valid signing path (A/B/C) are populated above.
 Q402_ENABLE_REAL_PAYMENTS=1
 
 # Default Q402 deployment. Only change for self-hosted.
@@ -114,6 +134,8 @@ env_vars = [
   "Q402_TRIAL_API_KEY",
   "Q402_MULTICHAIN_API_KEY",
   "Q402_PRIVATE_KEY",
+  "Q402_AGENTIC_PRIVATE_KEY",
+  "Q402_AGENT_WALLET_ADDRESS",
   "Q402_ENABLE_REAL_PAYMENTS",
   "Q402_RELAY_BASE_URL",
 ]
@@ -146,6 +168,7 @@ Then export the values in `~/.zshrc` / `~/.bashrc`. See the [Codex config refere
 | `q402_batch_pay` | API key + private key + flag | Send a gasless payment to **multiple** recipients in one call on a single chain × token. Trial keys: 5 rows max. Paid keys: 20 rows max. **Auto-routing:** same rule as `q402_pay` (BNB + Trial key set ⇒ Trial, else Multichain). **Ambiguity gate:** 6+ recipient BNB batches with Trial set return `status="ambiguous"` instead of executing — the agent asks the user to pick `keyScope="trial"` (first 5), `"multichain"` (all paid), or two calls (5 free + remainder paid). **Supported chains: avax, bnb, eth, mantle, injective, monad, scroll** (default EIP-7702 mode). xlayer + stable are NOT batchable — use `q402_pay` in a loop for those. Same sandbox gating as `q402_pay`. **Rate-limit note:** the inner `/api/relay` budget (30/min per key) is consumed per row, so a paid 20-row batch leaves ~10 inner slots for the next minute. |
 | `q402_receipt` | none | Look up a Trust Receipt by `rct_…` id and locally verify its ECDSA signature against the relayer EOA. Returns the public settlement record + a `verified` boolean. *receiptId-only today; tx-hash lookup reserved for a future release.* |
 | `q402_wallet_status` | private key | Per-chain EIP-7702 delegation status for the EOA derived from `Q402_PRIVATE_KEY`, across all 9 Q402 chains. Read-only — no on-chain action, no quota consumption. Useful as the diagnostic step before `q402_clear_delegation`. |
+| `q402_agentic_info` | API key | Introspect your server-managed Agent Wallets — addresses, per-wallet caps, daily-spend used, ERC-8004 agent id, per-chain sub-balances. Drives Mode C (server-managed) so the agent can see what wallet it's about to pay from without ever holding the private key. Auth is API-key only; no PK needed. Read-only. |
 | `q402_clear_delegation` | private key | Clear the EIP-7702 delegation on a single chain for the configured wallet. Local signing with `Q402_PRIVATE_KEY`; Q402 sponsors the on-chain TX so the user pays $0 gas. After clearing, the next `q402_pay` on that chain recreates a fresh delegation automatically. |
 
 `q402_pay` and `q402_batch_pay` follow a "confirm in chat first" contract: the tool description instructs the model to never call it without explicit user approval of the recipient address(es), amount(s), chain, and token. For batch calls the user must approve the **full batch**, not the individual rows.
@@ -165,30 +188,32 @@ 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` — the three secret lines ship empty (no `#` to remove, just paste the value on the right of `=`) and the live flag defaults to `1`. The live-mode gate only flips once a real key + valid 32-byte PK are populated, so saving the template as-is stays in sandbox automatically. Change the flag to `0` if you want to force sandbox even with real keys (e.g. for chained testing on a paid plan):
+To enable real on-chain transactions you need (a) a live API key (`q402_live_*`), (b) at least one valid signing path — Mode A `Q402_PRIVATE_KEY`, Mode B `Q402_AGENTIC_PRIVATE_KEY`, or Mode C (paid Multichain key alone, server-managed Agent Wallet, no PK on the client) — and (c) `Q402_ENABLE_REAL_PAYMENTS=1`. The block below is the template `q402_doctor` writes to `~/.q402/mcp.env`; every secret line ships empty, the live flag defaults to `1`, and the gate only flips when an API key + a valid signing path are populated. Change the flag to `0` to force sandbox even with real keys (e.g. for chained testing on a paid plan):
 
 ```bash
-# Two-key model — fill ONE (or both for auto-routing).
+# ── API key — fill ONE (or both for auto-routing) ──
 # Auto-routing (same for q402_pay AND q402_batch_pay):
 #   chain="bnb" + Q402_TRIAL_API_KEY set  → Trial (free sponsored)
 #   anything else                          → Multichain (paid 9-chain)
 # Batch ambiguity: 6+ recipient BNB batch with Trial set returns
 #   status="ambiguous" instead of executing — agent asks user to pick.
 # Override per call with keyScope: "auto" | "trial" | "multichain".
-
 Q402_TRIAL_API_KEY=                # BNB-only sponsored Trial key (from /event)
 Q402_MULTICHAIN_API_KEY=           # paid 9-chain key (per-chain Gas Tank)
 
-Q402_PRIVATE_KEY=                  # signer for the payer EOA (0x + 64 hex chars)
+# ── Signing path — pick ONE of Mode A / B / C ──
+Q402_PRIVATE_KEY=                  # Mode A: real EOA pk (0x + 64 hex)
+Q402_AGENTIC_PRIVATE_KEY=          # Mode B: exported Agent Wallet pk (from dashboard)
+# Mode C: leave both PK lines blank, set only the paid Multichain key
+# above. Q402 signs with the server-managed Agent Wallet. Optionally:
+# Q402_AGENT_WALLET_ADDRESS=0x...   # pin one of your wallets when you have multiple
 
 # 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 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 populated above. Empty values fail the 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).
+# Default 1. Safe because the gate only flips to live when an API key AND
+# at least one valid signing path (A/B/C) are populated. Empty values
+# fail the gate, so partial setups stay in sandbox with a hint.
 Q402_ENABLE_REAL_PAYMENTS=1
 ```
 
@@ -214,8 +239,10 @@ Combined with the `confirm: true` argument the tool requires, this means the mod
 | Env var | Required for | Notes |
 |---|---|---|
 | `Q402_TRIAL_API_KEY` | live-pay (BNB) | BNB-only sponsored Trial key. Free at https://q402.quackai.ai/event. Auto-routed for `chain="bnb"` in both `q402_pay` and `q402_batch_pay` (≤5 recipients) when set. 6+ recipient BNB batches return `status="ambiguous"` so the agent can ask the user how to split. |
-| `Q402_MULTICHAIN_API_KEY` | live-pay (9-chain) | Paid 9-chain key. Get one at https://q402.quackai.ai/payment. Auto-routed for non-BNB chains AND for BNB when no Trial key is set. Cap: 20 recipients per batch. |
-| `Q402_PRIVATE_KEY` | live-pay | Signer for the payer EOA. **Never share. Never paste in chat.** |
+| `Q402_MULTICHAIN_API_KEY` | live-pay (9-chain) | Paid 9-chain key. Get one at https://q402.quackai.ai/payment. Auto-routed for non-BNB chains AND for BNB when no Trial key is set. Cap: 20 recipients per batch. Required for Mode C (server-managed Agent Wallet). |
+| `Q402_PRIVATE_KEY` | Mode A | Hex private key of your MetaMask EOA. Signer for local Mode A. **Never share. Never paste in chat.** |
+| `Q402_AGENTIC_PRIVATE_KEY` | Mode B | Exported Agent Wallet hex private key from the dashboard (Agent tab → Export). Signs locally, but the signer is your dedicated Agent Wallet — MetaMask is never touched. **Never share. Never paste in chat.** |
+| `Q402_AGENT_WALLET_ADDRESS` | Mode C (optional) | When you have multiple server-managed Agent Wallets (max 10 per owner), set this to the lowercased 0x… address of the one Q402 should spend from. Omit to use the default wallet. Ignored in Modes A/B. |
 | `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 `200`. Lower for tighter agent blast-radius. |
 | `Q402_ALLOWED_RECIPIENTS` | optional | Comma-separated lowercase addresses. Defaults to no allowlist. |

package/dist/index.js

@@ -211,7 +211,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.6.1";
+var PACKAGE_VERSION = "0.6.3";
 
 // src/tools/quote.ts
 import { z } from "zod";
@@ -663,13 +663,12 @@ var Q402NodeClient = class _Q402NodeClient {
    * delegation), after which the remaining transfers are surfaced in
    * the result array even if individual ones fail.
    *
-   * Signature shape: `{ token, recipients }`. The previous revision took
-   * `PayInput[]` (with token on each row), which read as if rows could
-   * carry different tokens — but the request body only ships one token
-   * field, so the per-row token on rows 1..N was silently ignored. The
-   * new shape surfaces the constraint in the type so consumers can't
-   * accidentally build a "mixed-token batch" that quietly drops the
-   * second token. Same chain + same token across one batch, full stop.
+   * Signature shape: `{ token, recipients }`. The request body only ships
+   * one token field, so a per-row token would be silently ignored. The
+   * shape surfaces the constraint in the type so consumers can't
+   * accidentally build a "mixed-token batch" that would quietly drop
+   * the second token. Same chain + same token across one batch, full
+   * stop.
    */
   async batchPay(input) {
     const { token, recipients: rows } = input;
@@ -1272,9 +1271,10 @@ async function runBatchPay(input) {
     guardsApplied.push(`recipient_allowlist[${CONFIG.allowedRecipients.length}]`);
   }
   let senderWallet;
-  if (CONFIG.privateKey && isValidPrivateKey(CONFIG.privateKey)) {
+  const echoPk = CONFIG.agenticPrivateKey && isValidPrivateKey(CONFIG.agenticPrivateKey) ? CONFIG.agenticPrivateKey : CONFIG.privateKey && isValidPrivateKey(CONFIG.privateKey) ? CONFIG.privateKey : null;
+  if (echoPk) {
     try {
-      const addr = new Wallet3(CONFIG.privateKey).address;
+      const addr = new Wallet3(echoPk).address;
       senderWallet = {
         address: addr,
         addressShort: `${addr.slice(0, 6)}\u2026${addr.slice(-4)}`
@@ -1325,9 +1325,25 @@ async function runBatchPay(input) {
       setupHint: reason
     };
   }
+  const signingPk = CONFIG.agenticPrivateKey ?? CONFIG.privateKey;
+  if (!signingPk) {
+    guardsApplied.push("mode=sandbox");
+    const sandboxResults = input.recipients.map(
+      (r) => sandboxPay(chain, { to: r.to, amount: r.amount, token: input.token })
+    );
+    const reason = "No local signing key configured. Set Q402_AGENTIC_PRIVATE_KEY (Mode B) or Q402_PRIVATE_KEY (Mode A) to sign batch payments locally.";
+    return {
+      mode: "sandbox",
+      status: "sandbox",
+      result: { sandbox: sandboxResults, reason },
+      senderWallet,
+      guardsApplied,
+      setupHint: reason
+    };
+  }
   const client = new Q402NodeClient({
     apiKey: resolved.apiKey,
-    privateKey: CONFIG.privateKey,
+    privateKey: signingPk,
     chain,
     relayBaseUrl: CONFIG.relayBaseUrl
   });
@@ -1928,7 +1944,8 @@ Q402_MULTICHAIN_API_KEY=
 #      Pros: simplest mental model \u2014 same wallet you already use
 #      Cons: after first payment, MetaMask will show this account as
 #            "Smart account" (EIP-7702 delegation, reversible via
-#            q402_clear_delegation but visually alarming on first sight)
+#            q402_clear_delegation \u2014 the visual change can be surprising
+#            the first time you see it)
 #
 #   B. Agent Wallet \u2014 local signing (recommended for AI agents)
 #      Set:  Q402_AGENTIC_PRIVATE_KEY  =  0x... (Agent Wallet pk from dashboard export)
@@ -2032,7 +2049,7 @@ function envSlot(name, purpose) {
 }
 function mask2(key) {
   if (!key || key.length < 12) return key ?? "";
-  return `${key.slice(0, 12)}\u2026${key.slice(-4)}`;
+  return `${key.slice(0, 12)}...${key.slice(-4)}`;
 }
 function detectPhase() {
   const anyKey = !!(CONFIG.trialApiKey || CONFIG.multichainApiKey || CONFIG.legacyApiKey);
@@ -2160,7 +2177,15 @@ async function runDoctor() {
     ),
     Q402_PRIVATE_KEY: envSlot(
       "Q402_PRIVATE_KEY",
-      "Hex EVM private key. Signs LOCALLY on your machine \u2014 never leaves your device."
+      "Mode A signing key \u2014 your real EOA's private key (e.g. MetaMask). EIP-7702 delegates your wallet to Q402 impl. Signs LOCALLY, never leaves your device."
+    ),
+    Q402_AGENTIC_PRIVATE_KEY: envSlot(
+      "Q402_AGENTIC_PRIVATE_KEY",
+      "Mode B signing key \u2014 your Agent Wallet's exported private key from the dashboard. Signs LOCALLY, never leaves your device. Your MetaMask stays untouched."
+    ),
+    Q402_AGENT_WALLET_ADDRESS: envSlot(
+      "Q402_AGENT_WALLET_ADDRESS",
+      "Mode C target \u2014 lowercased Agent Wallet address when you hold multiple. Omit to use the server-default wallet. No PK needed; the server signs."
     ),
     Q402_ENABLE_REAL_PAYMENTS: envSlot(
       "Q402_ENABLE_REAL_PAYMENTS",
@@ -2235,6 +2260,34 @@ async function runDoctor() {
       "You have a legacy Q402_API_KEY set, and Q402_ENABLE_REAL_PAYMENTS wasn't explicitly set by you \u2014 so it's defaulting to 1 (real payments) since v0.5.11. To stay in sandbox while you check this, add `Q402_ENABLE_REAL_PAYMENTS=0` to ~/.q402/mcp.env (or your shell) and restart the MCP client."
     );
   }
+  const walletModePicker = {
+    question: "How would you like Q402 to sign your payments?",
+    helpText: "Pick once \u2014 you can change later by editing ~/.q402/mcp.env. Most users want C (simplest).",
+    recommendedPick: modes.modeC && !modes.modeA && !modes.modeB ? "C" : modes.primary ?? "C",
+    options: [
+      {
+        pick: "C",
+        title: "Q402 server signs for me (recommended, simplest)",
+        description: "Q402 holds an encrypted Agent Wallet for you. You only set an API key \u2014 no private key in your env, no MetaMask popup, no Smart-account marker on your wallet. Best for AI agents, automations, and anyone who just wants payments to work.",
+        env: ["Q402_MULTICHAIN_API_KEY (paid)", "or Q402_TRIAL_API_KEY (free BNB)"],
+        privateKeyRequired: false
+      },
+      {
+        pick: "B",
+        title: "I'll export the Agent Wallet's private key and sign locally",
+        description: "Same Agent Wallet as Mode C, but YOU hold the private key. Export it from the dashboard once. MCP signs locally so the key never leaves your machine. Your MetaMask is never touched.",
+        env: ["Q402_AGENTIC_PRIVATE_KEY (export from dashboard)", "+ Q402_MULTICHAIN_API_KEY or Q402_TRIAL_API_KEY"],
+        privateKeyRequired: true
+      },
+      {
+        pick: "A",
+        title: "Use my own EOA (MetaMask) as the signer",
+        description: "Your existing wallet signs directly. EIP-7702 delegates it to Q402 for the call \u2014 your wallet shows a 'Smart account' marker after first use (normal, reversible). Best for power users who want their MetaMask address to be the on-chain payer. Use a FRESH wallet \u2014 not the one with your main funds.",
+        env: ["Q402_PRIVATE_KEY (your EOA's private key)", "+ Q402_MULTICHAIN_API_KEY or Q402_TRIAL_API_KEY"],
+        privateKeyRequired: true
+      }
+    ]
+  };
   if (phase !== "live-check") {
     return {
       package: PACKAGE_NAME,
@@ -2243,6 +2296,7 @@ async function runDoctor() {
       ready: false,
       envFile,
       envState,
+      walletModePicker,
       missing,
       warnings,
       recommendedActions,
@@ -2275,13 +2329,15 @@ async function runDoctor() {
   }
   let walletAddress;
   let walletError;
-  try {
-    walletAddress = new Wallet6(CONFIG.privateKey).address;
-  } catch (e) {
-    walletError = e instanceof Error ? e.message : String(e);
-    warnings.push(
-      `Q402_PRIVATE_KEY is set but does not parse as a 32-byte hex key: ${walletError}. Open ~/.q402/mcp.env in your editor and paste a real key (0x + 64 hex chars). Live calls will fail until this is fixed.`
-    );
+  if (CONFIG.privateKey) {
+    try {
+      walletAddress = new Wallet6(CONFIG.privateKey).address;
+    } catch (e) {
+      walletError = e instanceof Error ? e.message : String(e);
+      warnings.push(
+        `Q402_PRIVATE_KEY is set but does not parse as a 32-byte hex key: ${walletError}. Open ~/.q402/mcp.env in your editor and paste a real key (0x + 64 hex chars). Live calls will fail until this is fixed.`
+      );
+    }
   }
   const verifyTargets = [];
   if (CONFIG.trialApiKey) verifyTargets.push({ scope: "trial", envVar: "Q402_TRIAL_API_KEY", key: CONFIG.trialApiKey });
@@ -2328,6 +2384,38 @@ async function runDoctor() {
     );
   }
   const ready = warnings.length === 0 && keys.some((k) => k.valid);
+  const activeModes = [];
+  if (modes.modeA) activeModes.push({
+    mode: "A",
+    label: "Real EOA (Q402_PRIVATE_KEY)",
+    rationale: "Your MetaMask wallet signs directly. EIP-7702 delegates it to Q402 for the call."
+  });
+  if (modes.modeB) activeModes.push({
+    mode: "B",
+    label: "Agent Wallet local (Q402_AGENTIC_PRIVATE_KEY)",
+    rationale: "Your exported Agent Wallet PK signs locally. Your MetaMask stays untouched."
+  });
+  if (modes.modeC) activeModes.push({
+    mode: "C",
+    label: "Server-mediated Agent Wallet (apiKey only)",
+    rationale: "No PK in your env. Q402's server holds the encrypted Agent Wallet key and signs for you."
+  });
+  const recommendedMode = modes.primary ?? (CONFIG.apiKey?.startsWith("q402_live_") ? "C" : "none");
+  const walletModes = {
+    available: activeModes,
+    count: modes.count,
+    primary: modes.primary,
+    /** Plain-English picker that the AI should echo when the user asks
+     *  "which mode do I use?" or "do I need a private key?". */
+    recommendation: recommendedMode === "C" ? "You're configured for Mode C \u2014 Q402's server signs with your Agent Wallet. No private key needed. Simplest path; recommended for most users." : recommendedMode === "B" ? "You're configured for Mode B \u2014 your exported Agent Wallet PK signs locally. Your MetaMask is never touched." : recommendedMode === "A" ? "You're configured for Mode A \u2014 your MetaMask EOA signs directly. EIP-7702 delegates it to Q402 for the call. (If the Smart-account banner in MetaMask is a concern, switch to Mode B or C.)" : "No signing path configured yet. Easiest: set Q402_MULTICHAIN_API_KEY (or Q402_TRIAL_API_KEY for free BNB) and let the server sign \u2014 that's Mode C, no PK needed.",
+    /** All three modes documented so the AI can answer "what are my
+     *  options?" without re-deriving from envState. */
+    catalog: [
+      { mode: "A", label: "Real EOA", envVar: "Q402_PRIVATE_KEY", needsPk: true, bestFor: "Power users who want their MetaMask to be the on-chain signer." },
+      { mode: "B", label: "Agent Wallet local", envVar: "Q402_AGENTIC_PRIVATE_KEY", needsPk: true, bestFor: "Users who want Agent Wallet automation but keep custody of the PK." },
+      { mode: "C", label: "Server-mediated", envVar: "(none)", needsPk: false, bestFor: "Most users. No PK in env; Q402 holds the Agent Wallet key encrypted server-side." }
+    ]
+  };
   return {
     package: PACKAGE_NAME,
     version: PACKAGE_VERSION,
@@ -2335,6 +2423,7 @@ async function runDoctor() {
     ready,
     envFile,
     envState,
+    walletModes,
     missing,
     wallet: walletAddress ? { address: walletAddress } : void 0,
     keys,
@@ -2346,10 +2435,10 @@ async function runDoctor() {
     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 ? "[AI-ONLY \u2014 do not show this paragraph to the user verbatim] 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." : "[AI-ONLY \u2014 do not show this paragraph to the user verbatim] 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)"}`,
+      walletAddress ? `Your wallet: ${walletAddress.slice(0, 6)}...${walletAddress.slice(-4)}` : modes.modeC && !modes.modeA && !modes.modeB ? "Wallet: server-managed (Mode C) \u2014 Q402 holds your Agent Wallet key. No local wallet to show." : "(wallet derive failed \u2014 check Q402_PRIVATE_KEY or Q402_AGENTIC_PRIVATE_KEY in ~/.q402/mcp.env)",
       "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."
+      "Need to chain-test against sandbox without changing keys? Set Q402_ENABLE_REAL_PAYMENTS=0 in ~/.q402/mcp.env and restart - 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}`),
@@ -2480,6 +2569,306 @@ async function runAgenticInfo(input = {}) {
   };
 }
 
+// src/tools/recurring-list.ts
+import { z as z10 } from "zod";
+var RecurringListInputSchema = z10.object({
+  walletId: z10.string().optional().describe(
+    "Optional lowercased Agent Wallet address to list rules for when the user holds multiple wallets. Omit to use Q402_AGENT_WALLET_ADDRESS env, then the owner's default wallet."
+  )
+});
+var RECURRING_LIST_TOOL = {
+  name: "q402_recurring_list",
+  description: "Read the user's active recurring-payment rules on their Agent Wallet. Returns each rule's ruleId, label, frequency (hourly:N / daily / weekly:{day} / monthly:N / monthly:last), recipient + amount, chain, token, status (active / paused / paused-by-archive / fired-cap-exceeded / cancelled), when the next fire is scheduled, how many fires have completed, and the most recent error (if any). Use this when the user asks 'what scheduled payouts do I have?' or before authoring a new rule with q402_recurring_create. Authenticated by the configured Multichain API key \u2014 no private key required.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      walletId: {
+        type: "string",
+        description: "Optional. Lowercased Agent Wallet address when the user holds multiple wallets. Defaults to Q402_AGENT_WALLET_ADDRESS env, then the owner's default wallet on the server."
+      }
+    },
+    additionalProperties: false
+  }
+};
+async function runRecurringList(input = {}) {
+  const base = CONFIG.relayBaseUrl;
+  const dashboardUrl = base.replace(/\/api$/, "") + "/dashboard?tab=agent";
+  if (!CONFIG.apiKey || !CONFIG.apiKey.startsWith("q402_live_")) {
+    return {
+      configured: false,
+      walletId: null,
+      rules: [],
+      count: 0,
+      dashboardUrl,
+      setupHint: "No live Q402 API key configured. Run q402_doctor to set one up, or open the dashboard to create rules from the UI."
+    };
+  }
+  const explicitWalletId = typeof input.walletId === "string" && input.walletId.length > 0 ? input.walletId.toLowerCase() : CONFIG.walletId;
+  try {
+    const res = await fetch(`${base}/wallet/agentic/recurring-by-key`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        apiKey: CONFIG.apiKey,
+        action: "list",
+        ...explicitWalletId ? { walletId: explicitWalletId } : {}
+      })
+    });
+    if (!res.ok) {
+      const errBody = await res.json().catch(() => ({}));
+      return {
+        configured: true,
+        walletId: explicitWalletId,
+        rules: [],
+        count: 0,
+        dashboardUrl,
+        setupHint: `recurring-list failed: ${errBody.error ?? `HTTP ${res.status}`}` + (errBody.message ? ` \u2014 ${errBody.message}` : "")
+      };
+    }
+    const data = await res.json();
+    return {
+      configured: true,
+      walletId: data.walletId,
+      rules: data.rules,
+      count: data.count,
+      dashboardUrl
+    };
+  } catch (e) {
+    return {
+      configured: true,
+      walletId: explicitWalletId,
+      rules: [],
+      count: 0,
+      dashboardUrl,
+      setupHint: `recurring-list network error: ${e instanceof Error ? e.message : String(e)}`
+    };
+  }
+}
+
+// src/tools/recurring-create.ts
+import { z as z11 } from "zod";
+var ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+var AMOUNT_RE = /^\d+(\.\d{1,18})?$/;
+var RecurringCreateInputSchema = z11.object({
+  confirm: z11.literal(true).describe(
+    'REQUIRED. Must be literally `true`. Authoring a recurring rule schedules future on-chain payments that the user does not click through one-by-one \u2014 the user has to explicitly say yes BEFORE this is called. Echo back the frequency + recipient + amount + chain + token + cancelWindow you intend to create, get a plain-language confirmation from the user (e.g. "yes, create the schedule"), and ONLY then call this with confirm: true. Mirrors the same guard q402_pay / q402_batch_pay use on one-shot sends.'
+  ),
+  frequency: z11.string().min(1).describe(
+    'Cadence string. One of: "hourly:N" (N=1..23), "daily", "weekly:{mon|tue|wed|thu|fri|sat|sun}", "monthly:N" (N=1..31), "monthly:last". Examples: "hourly:1" fires every hour, "weekly:fri" fires every Friday, "monthly:1" fires on the 1st of each month.'
+  ),
+  recipient: z11.string().regex(ADDRESS_RE).describe("0x-prefixed 20-byte recipient address. Required."),
+  amount: z11.string().regex(AMOUNT_RE).describe(
+    'Amount per fire, as a decimal string (e.g. "1.5", "0.0001"). Counted in the same unit as `token` (USDC or USDT, both 1:1 USD).'
+  ),
+  chain: z11.enum(["bnb", "eth", "avax", "xlayer", "mantle", "injective", "monad", "scroll", "stable"]).default("bnb").describe(
+    "Chain to fire the recurring TX on. Defaults to bnb (the only chain supported on Trial). Non-bnb requires the paid Multichain subscription."
+  ),
+  token: z11.enum(["USDC", "USDT"]).default("USDT").describe("Stablecoin to send. USDC or USDT. Both peg to USD-1."),
+  label: z11.string().max(64).optional().describe("Optional human-readable label (\u226464 chars). Shows up in q402_recurring_list and the dashboard."),
+  cancelWindowHours: z11.number().min(0).optional().describe(
+    "Hours of advance notice before each fire during which the rule can be cancelled. 0 = fire immediately at the next slot, no alert. Capped at the cadence interval (e.g. \u2264 N-0.5h for hourly:N, \u226424 for daily). Defaults to 0."
+  ),
+  walletId: z11.string().optional().describe(
+    "Optional lowercased Agent Wallet address when the user holds multiple wallets. Defaults to Q402_AGENT_WALLET_ADDRESS env, then the owner's default wallet on the server."
+  )
+});
+var RECURRING_CREATE_TOOL = {
+  name: "q402_recurring_create",
+  description: "Author a new recurring-payment rule on the user's Agent Wallet. Single-recipient (use the dashboard for multi-recipient payroll). Pick a cadence \u2014 hourly:N, daily, weekly:{day}, monthly:N, or monthly:last \u2014 and a recipient + amount + chain + token. Authenticated by the configured Multichain API key; no private key required. Non-bnb chains need the paid Multichain subscription. Each fire is bounded by the wallet's perTxMax (configured on the dashboard) \u2014 the dashboard's dailyLimit cap currently applies to manual sends only, NOT recurring fires, so an attacker with the apiKey could schedule N rules at perTxMax and drain the wallet's USDC balance over time. The user can stop a rule any time via q402_recurring_cancel.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      confirm: {
+        type: "boolean",
+        const: true,
+        description: "REQUIRED. Must be literally `true`. Recurring rules schedule future on-chain payments without per-fire user prompts, so the agent must get an explicit user yes BEFORE setting `confirm: true` and calling this. Same guard q402_pay / q402_batch_pay use on one-shot sends."
+      },
+      frequency: {
+        type: "string",
+        description: 'Required. "hourly:N" (N=1..23), "daily", "weekly:{day}", "monthly:N", or "monthly:last".'
+      },
+      recipient: {
+        type: "string",
+        pattern: "^0x[0-9a-fA-F]{40}$",
+        description: "Required. 0x-prefixed 20-byte recipient address."
+      },
+      amount: {
+        type: "string",
+        pattern: "^\\d+(\\.\\d{1,18})?$",
+        description: 'Required. Per-fire amount as decimal string (e.g. "1.5").'
+      },
+      chain: {
+        type: "string",
+        enum: ["bnb", "eth", "avax", "xlayer", "mantle", "injective", "monad", "scroll", "stable"],
+        description: "Default 'bnb'. Non-bnb requires paid Multichain."
+      },
+      token: {
+        type: "string",
+        enum: ["USDC", "USDT"],
+        description: "Default 'USDT'. Both peg USD-1."
+      },
+      label: {
+        type: "string",
+        maxLength: 64,
+        description: "Optional human label (\u226464 chars)."
+      },
+      cancelWindowHours: {
+        type: "number",
+        minimum: 0,
+        description: "Optional advance-notice window in hours. 0 = no alert, fires at the next slot. Defaults to 0."
+      },
+      walletId: {
+        type: "string",
+        description: "Optional. Defaults to default wallet on server."
+      }
+    },
+    required: ["confirm", "frequency", "recipient", "amount"],
+    additionalProperties: false
+  }
+};
+async function runRecurringCreate(input) {
+  const base = CONFIG.relayBaseUrl;
+  const dashboardUrl = base.replace(/\/api$/, "") + "/dashboard?tab=agent";
+  if (!CONFIG.apiKey || !CONFIG.apiKey.startsWith("q402_live_")) {
+    return {
+      ok: false,
+      walletId: null,
+      rule: null,
+      error: "API_KEY_REQUIRED",
+      message: "No live Q402 API key configured. Run q402_doctor to set one up.",
+      dashboardUrl
+    };
+  }
+  const explicitWalletId = typeof input.walletId === "string" && input.walletId.length > 0 ? input.walletId.toLowerCase() : CONFIG.walletId;
+  try {
+    const res = await fetch(`${base}/wallet/agentic/recurring-by-key`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        apiKey: CONFIG.apiKey,
+        action: "create",
+        frequency: input.frequency,
+        recipient: input.recipient.toLowerCase(),
+        amount: input.amount,
+        chain: input.chain ?? "bnb",
+        token: input.token ?? "USDT",
+        ...input.label !== void 0 ? { label: input.label } : {},
+        ...input.cancelWindowHours !== void 0 ? { cancelWindowHours: input.cancelWindowHours } : {},
+        ...explicitWalletId ? { walletId: explicitWalletId } : {}
+      })
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      return {
+        ok: false,
+        walletId: explicitWalletId,
+        rule: null,
+        error: data.error ?? `HTTP_${res.status}`,
+        message: data.message ?? `Create failed with HTTP ${res.status}.`,
+        dashboardUrl
+      };
+    }
+    return {
+      ok: true,
+      walletId: data.walletId ?? explicitWalletId,
+      rule: data.rule ?? null,
+      dashboardUrl
+    };
+  } catch (e) {
+    return {
+      ok: false,
+      walletId: explicitWalletId,
+      rule: null,
+      error: "NETWORK_ERROR",
+      message: e instanceof Error ? e.message : String(e),
+      dashboardUrl
+    };
+  }
+}
+
+// src/tools/recurring-cancel.ts
+import { z as z12 } from "zod";
+var RecurringCancelInputSchema = z12.object({
+  ruleId: z12.string().min(1).describe(
+    "Rule id to cancel. Obtain from q402_recurring_list \u2014 each entry's `ruleId` field. Cancelling is immediate."
+  ),
+  walletId: z12.string().optional().describe(
+    "Optional lowercased Agent Wallet address when the user holds multiple wallets. Defaults to Q402_AGENT_WALLET_ADDRESS env, then the owner's default wallet."
+  )
+});
+var RECURRING_CANCEL_TOOL = {
+  name: "q402_recurring_cancel",
+  description: "Cancel an active recurring-payment rule on the Agent Wallet. Takes a ruleId (from q402_recurring_list). Cancel is immediate \u2014 the rule will not fire again. Authenticated by the configured Multichain API key. Idempotent: cancelling an already-cancelled rule returns 409 with a clear message. Use this whenever the user says 'stop my recurring payment to X' \u2014 call q402_recurring_list first to find the matching ruleId, then call this with that id.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      ruleId: {
+        type: "string",
+        description: "Rule id from q402_recurring_list. Required."
+      },
+      walletId: {
+        type: "string",
+        description: "Optional. Lowercased Agent Wallet address when the user holds multiple wallets. Defaults to Q402_AGENT_WALLET_ADDRESS env, then the owner's default wallet on the server."
+      }
+    },
+    required: ["ruleId"],
+    additionalProperties: false
+  }
+};
+async function runRecurringCancel(input) {
+  const base = CONFIG.relayBaseUrl;
+  const dashboardUrl = base.replace(/\/api$/, "") + "/dashboard?tab=agent";
+  if (!CONFIG.apiKey || !CONFIG.apiKey.startsWith("q402_live_")) {
+    return {
+      ok: false,
+      walletId: null,
+      rule: null,
+      error: "API_KEY_REQUIRED",
+      message: "No live Q402 API key configured. Run q402_doctor to set one up.",
+      dashboardUrl
+    };
+  }
+  const explicitWalletId = typeof input.walletId === "string" && input.walletId.length > 0 ? input.walletId.toLowerCase() : CONFIG.walletId;
+  try {
+    const res = await fetch(`${base}/wallet/agentic/recurring-by-key`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        apiKey: CONFIG.apiKey,
+        action: "cancel",
+        ruleId: input.ruleId,
+        ...explicitWalletId ? { walletId: explicitWalletId } : {}
+      })
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      return {
+        ok: false,
+        walletId: explicitWalletId,
+        rule: null,
+        error: data.error ?? `HTTP_${res.status}`,
+        message: data.message ?? `Cancel failed with HTTP ${res.status}.`,
+        dashboardUrl
+      };
+    }
+    return {
+      ok: true,
+      walletId: data.walletId ?? explicitWalletId,
+      rule: data.rule ?? null,
+      dashboardUrl
+    };
+  } catch (e) {
+    return {
+      ok: false,
+      walletId: explicitWalletId,
+      rule: null,
+      error: "NETWORK_ERROR",
+      message: e instanceof Error ? e.message : String(e),
+      dashboardUrl
+    };
+  }
+}
+
 // src/index.ts
 function jsonText(value) {
   return { type: "text", text: JSON.stringify(value, null, 2) };
@@ -2501,6 +2890,9 @@ async function main() {
       RECEIPT_TOOL,
       WALLET_STATUS_TOOL,
       AGENTIC_INFO_TOOL,
+      RECURRING_LIST_TOOL,
+      RECURRING_CREATE_TOOL,
+      RECURRING_CANCEL_TOOL,
       CLEAR_DELEGATION_TOOL
     ]
   }));
@@ -2544,6 +2936,18 @@ async function main() {
           AgenticInfoInputSchema.parse(args ?? {});
           return { content: [jsonText(await runAgenticInfo())] };
         }
+        case "q402_recurring_list": {
+          const parsed = RecurringListInputSchema.parse(args ?? {});
+          return { content: [jsonText(await runRecurringList(parsed))] };
+        }
+        case "q402_recurring_create": {
+          const parsed = RecurringCreateInputSchema.parse(args ?? {});
+          return { content: [jsonText(await runRecurringCreate(parsed))] };
+        }
+        case "q402_recurring_cancel": {
+          const parsed = RecurringCancelInputSchema.parse(args ?? {});
+          return { content: [jsonText(await runRecurringCancel(parsed))] };
+        }
         default:
           return {
             isError: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quackai/q402-mcp",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "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": [
@@ -68,6 +68,7 @@
     "access": "public"
   },
   "overrides": {
-    "ws": "^8.20.1"
+    "ws": "^8.20.1",
+    "qs": "^6.15.2"
   }
 }