@quackai/q402-mcp 0.6.0 → 0.6.2

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

@@ -121,7 +121,12 @@ function loadConfig() {
   const apiKeyKind = classifyApiKey(apiKey);
   const privateKey = ENV.Q402_PRIVATE_KEY ?? null;
   const agenticPrivateKey = ENV.Q402_AGENTIC_PRIVATE_KEY ?? null;
-  const walletIdRaw = ENV.Q402_WALLET_ID;
+  const walletIdRaw = ENV.Q402_AGENT_WALLET_ADDRESS ?? ENV.Q402_WALLET_ID;
+  if (!ENV.Q402_AGENT_WALLET_ADDRESS && ENV.Q402_WALLET_ID) {
+    process.stderr.write(
+      "[q402-mcp] Q402_WALLET_ID is deprecated \u2014 rename to Q402_AGENT_WALLET_ADDRESS. Old name will be removed in v0.7.0.\n"
+    );
+  }
   const walletId = typeof walletIdRaw === "string" && walletIdRaw.length > 0 ? walletIdRaw.toLowerCase() : null;
   const realPaymentsRequested = ENV.Q402_ENABLE_REAL_PAYMENTS === "1";
   const anyLiveKey = classifyApiKey(trialApiKey) === "live" || classifyApiKey(multichainApiKey) === "live" || classifyApiKey(legacyApiKey) === "live";
@@ -206,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.0";
+var PACKAGE_VERSION = "0.6.2";
 
 // src/tools/quote.ts
 import { z } from "zod";
@@ -658,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;
@@ -1047,6 +1051,32 @@ async function runPay(input) {
     }
     const data = await resp.json().catch(() => ({}));
     const txHash = data.txHash ?? "";
+    const isPending = resp.status === 202 || data.pending === true || data.status === "processing";
+    if (isPending) {
+      const retryAfter = typeof data.retryAfterSec === "number" ? data.retryAfterSec : 5;
+      return {
+        result: {
+          success: false,
+          sandbox: false,
+          txHash: "",
+          tokenAmount: input.amount,
+          token: input.token,
+          chain: chain.key,
+          method: "eip7702",
+          pending: true,
+          retryAfterSec: retryAfter
+        },
+        guardsApplied: [
+          ...guardsApplied,
+          "wallet=agentic-server",
+          "mode=live",
+          "status=pending",
+          `retry_after=${retryAfter}s`
+        ],
+        senderWallet,
+        setupHint: `An identical send for this wallet is still in flight on the server. Wait ${retryAfter}s and retry \u2014 the cached result will come back, no double-spend.`
+      };
+    }
     const success = resp.ok && txHash.length > 0;
     const message = "message" in data ? data.message : "error" in data ? data.error : void 0;
     return {
@@ -1241,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)}`
@@ -1294,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
   });
@@ -1884,13 +1931,77 @@ Q402_MULTICHAIN_API_KEY=
 
 
 # \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
-# WALLET \u2014 paste your private key on the right of \`=\`
+# SIGNING MODE \u2014 pick ONE of A / B / C below
+# \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+# Q402 pays in three ways, depending on which keys you set. Pick the
+# row that matches your situation and fill ONLY that row's variable(s).
+# Setting multiple rows is allowed \u2014 q402_pay will ask you which one to
+# use per call (the AI surfaces the question; you don't pre-pick a
+# default here).
+#
+#   A. Real EOA (your MetaMask wallet)
+#      Set:  Q402_PRIVATE_KEY  =  0x... (your MetaMask account's private 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 \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)
+#      Pros: your MetaMask stays untouched; agent has its own purse with
+#            per-tx + daily caps you set on the dashboard
+#      Cons: requires creating an Agent Wallet on the dashboard first
+#            (https://q402.quackai.ai/dashboard \u2192 Agent tab \u2192 Create)
+#            then exporting its private key
+#
+#   C. Agent Wallet \u2014 server-managed (no private key on your machine)
+#      Set:  (just the api key + optionally Q402_AGENT_WALLET_ADDRESS below)
+#      Pros: zero private-key handling locally; the server holds the
+#            encrypted Agent Wallet pk and signs on your behalf
+#      Cons: requires a paid Multichain API key (Mode C is not available
+#            on the free Trial). The server-side keystore is AES-256-GCM
+#            encrypted but is a custodial path \u2014 pick A or B if that
+#            posture doesn't fit your threat model.
+#
+# A user can have multiple wallets configured simultaneously (e.g. PK
+# for personal pays + apiKey-only for agent pays). When more than one
+# mode is set, q402_pay asks the user which to use rather than picking
+# silently.
+
+
+# \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+# WALLET \u2014 Mode A: real EOA private key
 # \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
 # Hex EVM private key (0x + 64 hex chars). Signs payments LOCALLY on
 # your machine \u2014 never leaves your device, never sent to any server.
+# Leave blank if you're using Mode B or Mode C.
 Q402_PRIVATE_KEY=
 
 
+# \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+# WALLET \u2014 Mode B: exported Agent Wallet private key
+# \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+# Hex EVM private key (0x + 64 hex chars) exported from your Agent
+# Wallet on the dashboard. Signs payments LOCALLY just like Mode A,
+# but the wallet is your dedicated Agent Wallet \u2014 your MetaMask EOA
+# is never touched. Get the key at:
+#   https://q402.quackai.ai/dashboard \u2192 Agent tab \u2192 Export
+# Leave blank if you're using Mode A or Mode C.
+Q402_AGENTIC_PRIVATE_KEY=
+
+
+# \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+# WALLET \u2014 Mode C: server-managed Agent Wallet picker (optional)
+# \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+# Only set this when you're running Mode C (api key only, no private
+# keys above) AND you have more than one Agent Wallet on the account
+# (max 10). Pin which one Q402 should spend from. Format: lowercase
+# 0x... address of the Agent Wallet (visible on the dashboard's Agent
+# tab). Omit entirely to use your default Agent Wallet.
+# Q402_AGENT_WALLET_ADDRESS=0x...
+
+
 # \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
 # Live mode switch (safe even at 1 \u2014 see SAFE-BY-DEFAULT note at top)
 # \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
@@ -1943,13 +2054,16 @@ function mask2(key) {
 function detectPhase() {
   const anyKey = !!(CONFIG.trialApiKey || CONFIG.multichainApiKey || CONFIG.legacyApiKey);
   const anyLiveKey = classifyApiKey(CONFIG.trialApiKey) === "live" || classifyApiKey(CONFIG.multichainApiKey) === "live" || classifyApiKey(CONFIG.legacyApiKey) === "live";
-  const hasValidPrivateKey = isValidPrivateKey(CONFIG.privateKey);
-  if (!Q402_ENV_FILE_PRESENT && !anyKey && !CONFIG.privateKey) {
+  const modes = detectAgenticModes();
+  const hasAnyValidSigningPath = modes.count > 0;
+  if (!Q402_ENV_FILE_PRESENT && !anyKey && !CONFIG.privateKey && !CONFIG.agenticPrivateKey) {
     return "first-install";
   }
-  const allEssentials = anyKey && hasValidPrivateKey && CONFIG.realPaymentsRequested && anyLiveKey;
+  const allEssentials = anyKey && hasAnyValidSigningPath && CONFIG.realPaymentsRequested && anyLiveKey;
   if (allEssentials) return "live-check";
-  if (anyKey || CONFIG.privateKey || Q402_ENV_FILE_PRESENT) return "needs-completion";
+  if (anyKey || CONFIG.privateKey || CONFIG.agenticPrivateKey || Q402_ENV_FILE_PRESENT) {
+    return "needs-completion";
+  }
   return "first-install";
 }
 async function verifyOneKey(scope, envVar, apiKey) {
@@ -2063,30 +2177,48 @@ 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",
       "Must be '1' to allow real TX. Anything else = test response (fake hash)."
     )
   };
+  const modes = detectAgenticModes();
   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");
-  } else if (!isValidPrivateKey(CONFIG.privateKey)) {
-    missing.push(
-      "Q402_PRIVATE_KEY is set but malformed (expected 0x + 64 hex chars). Looks like the placeholder '0x...' is still in ~/.q402/mcp.env \u2014 paste a real key in your editor."
-    );
+  if (modes.count === 0) {
+    const pkAPlaceholder = !!CONFIG.privateKey && !isValidPrivateKey(CONFIG.privateKey);
+    const pkBPlaceholder = !!CONFIG.agenticPrivateKey && !isValidPrivateKey(CONFIG.agenticPrivateKey);
+    if (pkAPlaceholder) {
+      missing.push(
+        "Q402_PRIVATE_KEY is set but malformed (expected 0x + 64 hex chars). Looks like the placeholder '0x...' is still in ~/.q402/mcp.env \u2014 paste a real key in your editor."
+      );
+    } else if (pkBPlaceholder) {
+      missing.push(
+        "Q402_AGENTIC_PRIVATE_KEY is set but malformed (expected 0x + 64 hex chars). Paste your exported Agent Wallet private key (https://q402.quackai.ai/dashboard \u2192 Agent tab \u2192 Export)."
+      );
+    } else {
+      missing.push(
+        "A signing path. Pick ONE: (A) Q402_PRIVATE_KEY = your MetaMask EOA's private key; (B) Q402_AGENTIC_PRIVATE_KEY = your exported Agent Wallet private key from the dashboard (Mode B keeps your MetaMask untouched); or (C) just use a live paid Q402_MULTICHAIN_API_KEY and let Q402 sign with your server-managed Agent Wallet (no PK on your machine)."
+      );
+    }
   }
   if (!CONFIG.realPaymentsRequested) {
     const haveAnyApi = !!(CONFIG.trialApiKey || CONFIG.multichainApiKey || CONFIG.legacyApiKey);
-    const havePk = isValidPrivateKey(CONFIG.privateKey);
-    if (haveAnyApi && havePk) {
+    if (haveAnyApi && modes.count > 0) {
       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."
       );
@@ -2128,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,
@@ -2136,17 +2296,19 @@ async function runDoctor() {
       ready: false,
       envFile,
       envState,
+      walletModePicker,
       missing,
       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" ? "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" ? "[AI-ONLY \u2014 do not show this paragraph to the user verbatim] 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." : "[AI-ONLY \u2014 do not show this paragraph to the user verbatim] 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.",
+      agentInstructions: phase === "first-install" ? "[AI-ONLY \u2014 do not show this paragraph to the user verbatim] 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) Help the user pick a wallet mode (A=Q402_PRIVATE_KEY real EOA, B=Q402_AGENTIC_PRIVATE_KEY exported Agent Wallet PK, C=API key only with server-managed Agent Wallet). If they're an AI agent / automation user, gently default to B or C; if they're a power user who wants their existing EOA to be the signer, A is fine. Walk through filling in the chosen mode's variable + the API 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 any private key (Mode A OR Mode B), surface the `advisories` array: fresh wallet, Smart-account-in-MetaMask heads-up (Mode A only), hardware wallets unsupported, MetaMask key-export path (Mode A) or dashboard Export button (Mode B). (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." : "[AI-ONLY \u2014 do not show this paragraph to the user verbatim] 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.",
+        "Q402 is installed. To start sending payments you need (1) an API key and (2) a wallet to sign with.",
         "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).",
+        "There are 3 wallet modes \u2014 pick one: (A) your MetaMask EOA's private key (simplest, but your account will be marked 'Smart account' after first payment); (B) export an Agent Wallet's private key from the dashboard (keeps your MetaMask untouched, recommended for AI agents); (C) on a paid plan, use the server-managed Agent Wallet \u2014 just set the API key, no private key needed.",
+        "Use a FRESH wallet for Mode A \u2014 don't use the one holding your main funds. The 'Smart account' marker is normal (EIP-7702 delegation, reversible via q402_clear_delegation).",
         "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."
       ] : [
@@ -2167,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 });
@@ -2220,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,
@@ -2227,6 +2423,7 @@ async function runDoctor() {
     ready,
     envFile,
     envState,
+    walletModes,
     missing,
     wallet: walletAddress ? { address: walletAddress } : void 0,
     keys,
@@ -2268,7 +2465,7 @@ var DOCTOR_TOOL = {
 import { z as z9 } from "zod";
 var AgenticInfoInputSchema = z9.object({
   walletId: z9.string().optional().describe(
-    "Optional lowercased Agent Wallet address to introspect when the user holds multiple (max 10 per owner). Omit to use Q402_WALLET_ID env, then the owner's default wallet."
+    "Optional lowercased Agent Wallet address to introspect when the user holds multiple (max 10 per owner). Omit to use Q402_AGENT_WALLET_ADDRESS env, then the owner's default wallet."
   )
 });
 var AGENTIC_INFO_TOOL = {
@@ -2279,7 +2476,7 @@ var AGENTIC_INFO_TOOL = {
     properties: {
       walletId: {
         type: "string",
-        description: "Optional. Lowercased Agent Wallet address when the user holds multiple wallets. Defaults to Q402_WALLET_ID env, then the owner's default wallet on the server."
+        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
@@ -2372,6 +2569,298 @@ 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({
+  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: {
+      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: ["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) };
@@ -2393,6 +2882,9 @@ async function main() {
       RECEIPT_TOOL,
       WALLET_STATUS_TOOL,
       AGENTIC_INFO_TOOL,
+      RECURRING_LIST_TOOL,
+      RECURRING_CREATE_TOOL,
+      RECURRING_CANCEL_TOOL,
       CLEAR_DELEGATION_TOOL
     ]
   }));
@@ -2436,6 +2928,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.0",
+  "version": "0.6.2",
   "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": [