@quackai/q402-mcp 0.7.1 → 0.7.3

package/README.md

@@ -9,16 +9,14 @@
 >
 > **Trial-scope policy:** API keys minted under the free-trial program (`plan: "trial"`) are restricted to BNB Chain with USDC/USDT — server-side enforcement, returns `403 TRIAL_BNB_ONLY` otherwise. **Paid API keys see the full 9-chain matrix at all times.**
 
-AI agents — Claude (Desktop / Code), OpenAI Codex CLI, Cursor, Cline, and any other MCP-compatible client — can now reason about stablecoin payments end to end: quote a transfer across 9 chains, pick the cheapest route, and (optionally) settle the transaction over [Q402](https://q402.quackai.ai)'s EIP-7702 relayer infrastructure. The recipient receives the full amount; the sender pays $0 in gas.
+Quote → route → (optional) settle stablecoin payments across 9 EVM chains, from any MCP client. Recipient gets the full amount; sender pays $0 gas via [Q402](https://q402.quackai.ai)'s EIP-7702 relayer.
 
 ---
 
 ## Quick start
 
-Two steps:
-
-1. Register the MCP server with your client (one-line install per client).
-2. Open your client and say: **"Set up Q402"**. The agent calls `q402_doctor` which walks you through creating a single secrets file at `~/.q402/mcp.env` and pasting in your API key + private key. Nothing else.
+1. Register the server with your client (one-line per client).
+2. Say **"Set up Q402"** to your agent. It runs `q402_doctor` → creates `~/.q402/mcp.env` → walks you through pasting keys.
 
 ### 1. Register the server
 
@@ -30,12 +28,12 @@ Two steps:
 | **Cline** | Cline → Settings → MCP Servers → Edit JSON. Same shape as Cursor. |
 | **Any other stdio MCP client** | Point it at `npx -y @quackai/q402-mcp`. No client-specific code. |
 
-That's it — secrets are NOT configured here. The MCP server reads them from `~/.q402/mcp.env` at startup (same pattern as AWS CLI / Stripe CLI / gh CLI), so every client uses the same file with no per-client wiring.
+Secrets are NOT in this config. The server reads them from `~/.q402/mcp.env` (same pattern as AWS / Stripe / gh CLIs).
 
 <details>
 <summary>Windows: <code>codex mcp add</code> returns "Access is denied"</summary>
 
-The bundled `codex.exe` on some Windows setups refuses to write its own config from the `mcp add` subcommand. Add the equivalent stanza to `~/.codex/config.toml` by hand:
+Some Windows setups block `codex.exe` from writing its own config. Add the stanza to `~/.codex/config.toml` by hand:
 
 ```toml
 [mcp_servers.q402]
@@ -49,34 +47,30 @@ Then restart Codex. Same effect as `codex mcp add q402 -- npx -y @quackai/q402-m
 
 ### 2. First-time setup
 
-Restart your client, then ask your agent:
-
-> *"Set up Q402"*
+Restart your client, ask: > *"Set up Q402"*
 
-The agent calls `q402_doctor`. On first install, the tool tells the agent to:
+The agent runs `q402_doctor`. On first install:
 
-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) a signing path — **into the file, not into chat**
-4. Restart the client and run `q402_doctor` again to verify
+1. Creates `~/.q402/mcp.env` (placeholders)
+2. Opens it in your editor
+3. Walks you through pasting an API key + a signing path **into the file, not into chat**
+4. Restart + re-run `q402_doctor` to verify
 
-🔒 **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.
+🔒 **Keys never paste into chat.** Local modes sign on your machine; the key never leaves the device. Mode C (server-managed) needs no PK on the client.
 
 ### Pick a signing mode
 
-Q402 supports three signing modes — pick ONE:
-
-| Mode | Env you set | Signer | Notes |
+| Mode | Env | 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 an 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). **One-shot pays** work with either `Q402_TRIAL_API_KEY` (BNB-only sponsored) or `Q402_MULTICHAIN_API_KEY` (paid, all 9 chains). **Recurring** (`q402_recurring_create`) requires the paid Multichain key on every chain, including BNB. |
+| **A** | `Q402_PRIVATE_KEY` | MetaMask EOA, local | Simplest. Shows "Smart account" after first use (reversible via `q402_clear_delegation`). |
+| **B** | `Q402_AGENTIC_PRIVATE_KEY` | Agent Wallet, local | Export PK from the [dashboard](https://q402.quackai.ai/dashboard) Agent tab. MetaMask untouched. |
+| **C** | (just an API key) | Agent Wallet, server-managed | No PK on the client. One-shot pays accept Trial or Multichain keys; recurring needs Multichain on every chain (BNB included). |
 
-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).
+When more than one mode is set, `q402_pay` asks the user which to use. Picker: `walletMode = "agentic-server" \| "agentic-local" \| "eoa"`.
 
 ### Manual setup (no AI)
 
-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).
+Create `~/.q402/mcp.env` yourself with the template below. Live mode only flips when an API key + a signing path are populated, so saving the template as-is stays in sandbox. `Q402_ENABLE_REAL_PAYMENTS=0` forces sandbox even with real keys.
 
 ```bash
 # ~/.q402/mcp.env
@@ -157,52 +151,43 @@ Then export the values in `~/.zshrc` / `~/.bashrc`. See the [Codex config refere
 
 ---
 
-## Wallet modes — which signing path?
-
-Three signing paths. Pick one when `q402_doctor` asks on first install. You can change later by editing `~/.q402/mcp.env` and restarting your client.
-
-| Mode | Best for | Env to set | Private key in env? |
-|---|---|---|---|
-| **C — Server-managed** (recommended) | Most users. AI agents, automations, anyone who wants payments to "just work". Q402 holds an encrypted Agent Wallet for you; no MetaMask popup, no Smart-account marker. One-shot pays accept either key; **recurring schedules require the paid Multichain key on every chain (BNB included)**. | `Q402_MULTICHAIN_API_KEY` (paid, full surface) **or** `Q402_TRIAL_API_KEY` (free BNB, one-shot only) | **No** |
-| **B — Local Agent Wallet PK** | You want Agent Wallet automation but prefer to hold the PK yourself. Export from the dashboard once. MCP signs locally — key never leaves your machine. Your MetaMask is never touched. | `Q402_AGENTIC_PRIVATE_KEY` + an API key | Yes (Agent Wallet's exported PK) |
-| **A — Your own EOA** | Power users who want their existing MetaMask address to be the on-chain payer. Your EOA signs directly via EIP-7702; the "Smart account" marker after first use is normal + reversible with `q402_clear_delegation`. **Use a fresh wallet.** | `Q402_PRIVATE_KEY` + an API key | Yes (your EOA's PK) |
-
-`q402_doctor` on first install reads your env and recommends one of these based on what's already configured. The default for an empty install is Mode C — simplest path. If multiple modes are configured at once (e.g. both `Q402_PRIVATE_KEY` and `Q402_AGENTIC_PRIVATE_KEY` set), `q402_pay` will ask which one to use before sending so the agent never silently picks the wrong wallet.
-
----
-
 ## Tools exposed
 
+**16 tools** — read-only by default; live mode needs an API key + signing path + `Q402_ENABLE_REAL_PAYMENTS=1`.
+
 | Tool | Auth | Purpose |
 |---|---|---|
-| `q402_doctor` | none | Health check covering BOTH first-install onboarding AND ongoing operational diagnostics. AI calls this when the user says "set up Q402" / "verify Q402" / "why isn't Q402 working". On first install, returns a `recommendedActions[]` payload telling the client to create `~/.q402/mcp.env` and open it in the user's editor. Later phases verify per-scope quota, EIP-7702 delegation state per chain, relay reachability, and surface slot-mismatch warnings (e.g. Trial-tier key sitting in `Q402_MULTICHAIN_API_KEY` would silently burn paid quota). Read-only — no signing, no on-chain action. |
-| `q402_quote` | none | Compare gas cost and supported tokens across chains. Read-only. |
-| `q402_balance` | API key | Verify the API key and report its plan tier + remaining quota credits (live vs sandbox). |
-| `q402_pay` | API key + private key + flag | Send a gasless payment to a single recipient. **Sandbox by default** — see [Sandbox vs live mode](#sandbox-vs-live-mode). |
-| `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.
-
-`q402_receipt` is the natural follow-up: after `q402_pay` returns a `receiptUrl`, hand the agent the `rct_…` id and ask *"verify this receipt"* — the tool re-runs the same canonical-JSON + EIP-191 recovery the receipt page does in the browser, so the verification doesn't depend on trusting any UI. Example prompts that work today:
-
-> *"Pay 0.10 USDT on BNB to 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045, then verify the receipt."*  
-> *"Is `rct_afa5f50bc49a65ebba3b28ab` a real Q402 receipt? Verify the signature."*
-
-> ℹ️ `q402_pay` takes a 0x-prefixed EVM address — ENS names are not resolved by the tool. If your prompt mentions a name like `vitalik.eth`, your AI client needs to resolve it client-side before invoking the tool.
-
-> Per-chain gas tank balances and full transaction history live in the [dashboard](https://q402.quackai.ai/dashboard) — those endpoints require a wallet signature, not a bare API key, so the MCP server points the agent there instead of exposing them.
+| `q402_doctor` | none | First-install onboarding + ongoing health check (per-scope quota, EIP-7702 state, relay reachability, slot-mismatch warnings). |
+| `q402_quote` | none | Compare gas + supported tokens across chains. |
+| `q402_balance` | api key | Verify key + remaining quota. |
+| `q402_pay` | live mode | Single-recipient gasless transfer. Sandbox by default. |
+| `q402_batch_pay` | live mode | Up to 20 recipients per call (trial: 5). Same auto-routing as `q402_pay`. 6+ BNB batches with Trial set return `status="ambiguous"` so the agent asks how to split. xlayer + stable not batchable — use `q402_pay` in a loop. |
+| `q402_receipt` | none | Fetch + locally verify a Trust Receipt (`rct_…` id, ECDSA against the relayer EOA). |
+| `q402_wallet_status` | private key | Per-chain EIP-7702 state for the EOA derived from `Q402_PRIVATE_KEY`. |
+| `q402_clear_delegation` | private key | Clear EIP-7702 delegation; Q402 sponsors the on-chain TX. |
+| `q402_agentic_info` | api key | Agent Wallet info (addresses, per-wallet caps, daily-spend used, ERC-8004 id). Drives Mode C. |
+| `q402_recurring_list` | api key | List scheduled rules. |
+| `q402_recurring_create` | api key | Author a recurring rule. Paid Multichain on EVERY chain (BNB included). |
+| `q402_recurring_fires` | api key | Last 50 fires per rule (timestamp + txHashes + amount). |
+| `q402_recurring_pause` | api key | Pause a rule (reversible). |
+| `q402_recurring_resume` | api key | Resume a paused / stopped rule. |
+| `q402_recurring_skip_next` | api key | Skip only the next scheduled fire. |
+| `q402_recurring_cancel` | api key | Permanently stop a rule. |
+
+`q402_pay` + `q402_batch_pay` require explicit in-chat confirmation. Batch confirmation = full batch, not per-row.
+
+> ℹ️ `q402_pay` expects a 0x address — ENS isn't resolved server-side. Resolve client-side first.
+> Per-chain Gas Tank balances + full TX history live in the [dashboard](https://q402.quackai.ai/dashboard) (wallet-signature only).
 
 ---
 
 ## Sandbox vs live mode
 
-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.
+**Sandbox default**: `q402_pay` returns a fake `txHash` with `success: false` and `sandbox: true`. No funds, no quota.
 
-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):
+**Live** = (a) live API key (`q402_live_*`), (b) a signing path (A / B / C), (c) `Q402_ENABLE_REAL_PAYMENTS=1`. The live flag defaults to `1` — gate only flips when both other conditions are met. Set to `0` to force sandbox even with real keys.
+
+Template `q402_doctor` writes to `~/.q402/mcp.env`:
 
 ```bash
 # ── API key — fill ONE (or both for auto-routing) ──
@@ -233,18 +218,16 @@ Q402_ENABLE_REAL_PAYMENTS=1
 
 Anything missing for the resolved scope → automatic sandbox fallback with a hint pointing at what to set.
 
-> ⚠️ **Sandbox returns a deterministic-looking fake `txHash` but explicitly NOT a success.** Since v0.5.8 every sandbox response carries `success: false` and `sandbox: true` at the top level of the `PayResult` — so a downstream chatbot summary that lifts the `success` field cannot mistakenly tell the user "payment succeeded" when nothing happened. The `txHash` itself is a 32-byte random hex string (visually indistinguishable from a real hash but emitted only when no on-chain TX is broadcast). Combined with the `mode: "sandbox"` and `method: "sandbox"` markers + the `setupHint` field on the wrapping `PaySummary` describing **exactly why** sandbox was selected, you have four independent signals to branch on before showing the user a confirmation message.
+> ⚠️ Sandbox responses carry `success: false`, `sandbox: true`, `mode: "sandbox"`, `method: "sandbox"`, plus a `setupHint` explaining why — four signals so a downstream summary can't claim success.
 
 ### Hard caps
 
-Two additional guards run before every payment regardless of mode:
-
 | Env var | Default | Effect |
 |---|---|---|
-| `Q402_MAX_AMOUNT_PER_CALL` | `200` | Reject any single call where `amount > N` USD-equivalent. |
-| `Q402_ALLOWED_RECIPIENTS` | (empty = off) | Comma-separated address allowlist. When set, all other recipients are rejected. |
+| `Q402_MAX_AMOUNT_PER_CALL` | `200` | Reject calls with `amount > N` USD. |
+| `Q402_ALLOWED_RECIPIENTS` | off | Comma-separated address allowlist. |
 
-Combined with the `confirm: true` argument the tool requires, this means the model needs (a) explicit user OK in chat, (b) amount ≤ cap, (c) recipient on allowlist if one exists, (d) all three live-mode env vars set, before a single wei moves.
+Combined with `confirm: true` + live-mode env, a payment needs: chat OK + amount ≤ cap + recipient allowed + all 3 live envs.
 
 ---
 

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.7.1";
+var PACKAGE_VERSION = "0.7.3";
 
 // src/tools/quote.ts
 import { z } from "zod";
@@ -1226,6 +1226,12 @@ var BatchPayInputSchema = z3.object({
   keyScope: z3.enum(["auto", "trial", "multichain"]).optional().describe(
     'Which API key to use. "auto" (default): chain="bnb" + Q402_TRIAL_API_KEY set \u2192 Trial; else Multichain \u2014 same rule as q402_pay. When auto would land on Trial AND recipients.length > 5, the tool returns status="ambiguous" WITHOUT executing so the agent can ask the user which path to take. Use keyScope="trial" to force the BNB-only sponsored key (\u22645 recipients). keyScope="multichain" forces the paid 9-chain key (\u226420 recipients).'
   ),
+  walletMode: z3.enum(["eoa", "agentic-local", "agentic-server"]).optional().describe(
+    'Which wallet to spend from \u2014 same three modes as q402_pay:\n  "eoa"              \u2014 user MetaMask/OKX EOA, signed locally with Q402_PRIVATE_KEY\n  "agentic-local"    \u2014 Agent Wallet exported key (Q402_AGENTIC_PRIVATE_KEY)\n  "agentic-server"   \u2014 server-managed Agent Wallet (Q402 holds the key; needs Q402_MULTICHAIN_API_KEY)\nWhen MORE THAN ONE wallet is configured, you MUST ask the user which to use before calling \u2014 do NOT guess. Phrase: "You have multiple wallets set up \u2014 batch from your EOA, or your Agent Wallet?" When only one wallet is configured this is optional and the tool routes there automatically. Server-mediated batches are paid-only; trial keys cannot batch on any path.'
+  ),
+  walletId: z3.string().optional().describe(
+    `Server-managed Agent Wallet only (walletMode="agentic-server"). Lowercased Agent Wallet address selecting which of the user's wallets to spend from when they hold more than one. Omit to use the default. Ignored for local-signing modes.`
+  ),
   confirm: z3.literal(true).describe(
     "MUST be true. The user must have explicitly approved this exact set of recipients, amounts, chain, and token in the conversation right before this tool was called. Setting confirm=true on behalf of the user without that approval is a violation of the tool contract."
   )
@@ -1270,9 +1276,71 @@ async function runBatchPay(input) {
   if (CONFIG.allowedRecipients.length > 0) {
     guardsApplied.push(`recipient_allowlist[${CONFIG.allowedRecipients.length}]`);
   }
+  const modes = detectAgenticModes(CONFIG);
+  const available = [];
+  if (modes.modeA && CONFIG.privateKey && isValidPrivateKey(CONFIG.privateKey)) {
+    try {
+      const addr = new Wallet3(CONFIG.privateKey).address;
+      available.push({
+        id: "eoa",
+        label: "Your real MetaMask / OKX EOA",
+        addressShort: `${addr.slice(0, 6)}\u2026${addr.slice(-4)}`,
+        note: "Signs locally with Q402_PRIVATE_KEY. Your wallet becomes EIP-7702-delegated after the first payment on each chain."
+      });
+    } catch {
+    }
+  }
+  if (modes.modeB && CONFIG.agenticPrivateKey && isValidPrivateKey(CONFIG.agenticPrivateKey)) {
+    try {
+      const addr = new Wallet3(CONFIG.agenticPrivateKey).address;
+      available.push({
+        id: "agentic-local",
+        label: "Agent Wallet (local signing with exported key)",
+        addressShort: `${addr.slice(0, 6)}\u2026${addr.slice(-4)}`,
+        note: "Signs locally with Q402_AGENTIC_PRIVATE_KEY. Your MetaMask is never touched."
+      });
+    } catch {
+    }
+  }
+  if (modes.modeC) {
+    available.push({
+      id: "agentic-server",
+      label: "Agent Wallet (server-managed)",
+      note: "Q402 holds the encrypted key; batch fires through /api/wallet/agentic/batch. Caps you set in the dashboard bound the spend."
+    });
+  }
+  const requestedMode = input.walletMode;
+  const requestedAvailable = requestedMode ? available.some((w) => w.id === requestedMode) : false;
+  if (requestedMode && !requestedAvailable) {
+    return {
+      mode: "none",
+      status: "wallet_mode_unavailable",
+      guardsApplied: [
+        ...guardsApplied,
+        `wallet_modes_available=${available.length}`,
+        `requested=${requestedMode}`
+      ],
+      ambiguousWalletChoice: {
+        question: available.length === 0 ? `The "${requestedMode}" wallet isn't configured. None of the supported wallets are set up \u2014 see the doctor for setup instructions.` : `The "${requestedMode}" wallet isn't configured in this environment. Supported wallets here: ${available.map((w) => `"${w.id}"`).join(", ")}. Which would you like to use instead?`,
+        available
+      }
+    };
+  }
+  if (available.length > 1 && !requestedMode) {
+    return {
+      mode: "none",
+      status: "needs_wallet_choice",
+      guardsApplied: [...guardsApplied, `wallet_modes_available=${available.length}`],
+      ambiguousWalletChoice: {
+        question: available.length === 2 ? `You have ${available.length} wallets set up \u2014 which one should I batch-pay from?` : `You have ${available.length} wallets set up. Which one should I batch-pay from?`,
+        available
+      }
+    };
+  }
+  const effectiveMode = requestedMode && requestedAvailable ? requestedMode : available.length === 1 && available[0] ? available[0].id : "eoa";
   let senderWallet;
-  const echoPk = CONFIG.agenticPrivateKey && isValidPrivateKey(CONFIG.agenticPrivateKey) ? CONFIG.agenticPrivateKey : CONFIG.privateKey && isValidPrivateKey(CONFIG.privateKey) ? CONFIG.privateKey : null;
-  if (echoPk) {
+  const echoPk = effectiveMode === "eoa" ? CONFIG.privateKey : effectiveMode === "agentic-local" ? CONFIG.agenticPrivateKey : null;
+  if (echoPk && isValidPrivateKey(echoPk)) {
     try {
       const addr = new Wallet3(echoPk).address;
       senderWallet = {
@@ -1309,12 +1377,134 @@ async function runBatchPay(input) {
   }
   const resolved = resolveApiKey(input.chain, scopeRequest);
   guardsApplied.push(`scope=${resolved.scope}${resolved.fromLegacyFallback ? "(legacy)" : ""}`);
+  if (effectiveMode === "agentic-server") {
+    if (input.token === "RLUSD") {
+      return {
+        mode: "none",
+        status: "sandbox",
+        guardsApplied: [
+          ...guardsApplied,
+          "wallet=agentic-server",
+          "token=RLUSD",
+          "rejected_pre_relay"
+        ],
+        senderWallet,
+        setupHint: 'RLUSD is not yet supported by the server-managed Agent Wallet (walletMode="agentic-server"). Switch to walletMode="eoa" or "agentic-local" (with a private key set), or pick USDC/USDT for this batch.'
+      };
+    }
+    if (!resolved.apiKey || !resolved.apiKey.startsWith("q402_live_")) {
+      const sandboxResults = input.recipients.map(
+        (r) => sandboxPay(chain, { to: r.to, amount: r.amount, token: input.token })
+      );
+      guardsApplied.push("mode=sandbox", "wallet=agentic-server");
+      const reason = resolved.sandboxReason ?? "Server-mediated Agent Wallet needs a live Q402_MULTICHAIN_API_KEY. Visit https://q402.quackai.ai/payment to activate a paid plan.";
+      return {
+        mode: "sandbox",
+        status: "sandbox",
+        result: { sandbox: sandboxResults, reason },
+        senderWallet,
+        guardsApplied,
+        setupHint: reason
+      };
+    }
+    if (!CONFIG.realPaymentsRequested) {
+      const sandboxResults = input.recipients.map(
+        (r) => sandboxPay(chain, { to: r.to, amount: r.amount, token: input.token })
+      );
+      guardsApplied.push("mode=sandbox", "wallet=agentic-server");
+      const reason = "Set Q402_ENABLE_REAL_PAYMENTS=1 to fire a real server-mediated batch.";
+      return {
+        mode: "sandbox",
+        status: "sandbox",
+        result: { sandbox: sandboxResults, reason },
+        senderWallet,
+        guardsApplied,
+        setupHint: reason
+      };
+    }
+    const explicitWalletId = typeof input.walletId === "string" && input.walletId.length > 0 ? input.walletId.toLowerCase() : CONFIG.walletId;
+    let resp;
+    try {
+      resp = await fetch(`${CONFIG.relayBaseUrl}/wallet/agentic/batch`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          apiKey: resolved.apiKey,
+          chain: input.chain,
+          token: input.token,
+          recipients: input.recipients,
+          ...explicitWalletId ? { walletId: explicitWalletId } : {}
+        })
+      });
+    } catch (e) {
+      return {
+        mode: "live",
+        status: "aborted",
+        guardsApplied: [
+          ...guardsApplied,
+          "wallet=agentic-server",
+          "mode=live",
+          "transport=fetch_failed"
+        ],
+        senderWallet,
+        error: e instanceof Error ? e.message : String(e)
+      };
+    }
+    const data = await resp.json().catch(() => ({}));
+    if (!resp.ok) {
+      const errMsg = data && typeof data === "object" && "error" in data ? String(data.error) : `relay_http_${resp.status}`;
+      return {
+        mode: "live",
+        status: "aborted",
+        guardsApplied: [
+          ...guardsApplied,
+          "wallet=agentic-server",
+          "mode=live",
+          `http=${resp.status}`
+        ],
+        senderWallet,
+        error: errMsg,
+        setupHint: resp.status === 402 ? "Server-mediated batch requires a paid Multichain subscription. Activate one at https://q402.quackai.ai/payment." : resp.status === 401 ? "apiKey was rejected by the server (stale or not bound to your owner). Rotate to the current key in your dashboard." : resp.status === 404 ? "No active Agent Wallet found. Create one in your dashboard before retrying." : void 0
+      };
+    }
+    const serverResults = Array.isArray(data.results) ? data.results : [];
+    const settled = serverResults.filter((r) => r.ok === true).length;
+    const failed = serverResults.length - settled;
+    const serverAborted = typeof data.aborted === "boolean" ? data.aborted : null;
+    const isAborted = serverAborted ?? (settled === 0 && failed > 0);
+    const status = failed === 0 ? "success" : isAborted ? "aborted" : "partial_failure";
+    guardsApplied.push(
+      "mode=live",
+      "wallet=agentic-server",
+      "scope=multichain (server enforced)",
+      `batch_size=${serverResults.length}/${RECIPIENT_LIMIT_PAID}`
+    );
+    return {
+      mode: "live",
+      status,
+      result: {
+        ok: failed === 0,
+        scope: "paid",
+        limit: RECIPIENT_LIMIT_PAID,
+        totalSuccess: settled,
+        totalFailed: failed,
+        aborted: isAborted,
+        results: serverResults.map((r) => ({
+          success: r.ok === true,
+          txHash: r.txHash,
+          error: r.error
+        }))
+      },
+      guardsApplied,
+      senderWallet
+    };
+  }
   const live = isLiveModeFor(resolved);
   if (!live) {
     const sandboxResults = input.recipients.map(
       (r) => sandboxPay(chain, { to: r.to, amount: r.amount, token: input.token })
     );
-    guardsApplied.push("mode=sandbox");
+    guardsApplied.push("mode=sandbox", `wallet=${effectiveMode}`);
     const reason = resolved.sandboxReason ?? describeSandboxReason2(resolved.apiKey ?? "", resolved.scope);
     return {
       mode: "sandbox",
@@ -1325,13 +1515,13 @@ async function runBatchPay(input) {
       setupHint: reason
     };
   }
-  const signingPk = CONFIG.agenticPrivateKey ?? CONFIG.privateKey;
+  const signingPk = effectiveMode === "eoa" ? CONFIG.privateKey : effectiveMode === "agentic-local" ? CONFIG.agenticPrivateKey : null;
   if (!signingPk) {
-    guardsApplied.push("mode=sandbox");
+    guardsApplied.push("mode=sandbox", `wallet=${effectiveMode}`);
     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.";
+    const reason = effectiveMode === "agentic-local" ? "Set Q402_AGENTIC_PRIVATE_KEY to your Agent Wallet's exported private key." : "Set Q402_PRIVATE_KEY to your EOA private key.";
     return {
       mode: "sandbox",
       status: "sandbox",
@@ -1352,13 +1542,13 @@ async function runBatchPay(input) {
       token: input.token,
       recipients: input.recipients.map((r) => ({ to: r.to, amount: r.amount }))
     });
-    guardsApplied.push("mode=live");
+    guardsApplied.push("mode=live", `wallet=${effectiveMode}`);
     guardsApplied.push(`scope=${result.scope} (server enforced)`);
     guardsApplied.push(`batch_size=${input.recipients.length}/${result.limit}`);
     return { mode: "live", status: "success", result, guardsApplied, senderWallet };
   } catch (err) {
     if (err instanceof BatchPayError) {
-      guardsApplied.push("mode=live");
+      guardsApplied.push("mode=live", `wallet=${effectiveMode}`);
       guardsApplied.push(`scope=${err.scope} (server enforced)`);
       guardsApplied.push(`batch_${err.aborted ? "aborted" : "partial_failure"}`);
       const status = err.aborted ? "aborted" : "partial_failure";
@@ -1408,7 +1598,11 @@ var BATCH_PAY_TOOL = {
   name: "q402_batch_pay",
   description: `USE THIS TOOL whenever the user asks to send the same token to multiple recipients on a single chain in one call ("pay 0x1 / 0x2 / 0x3 each 1 USDC on bnb", "airdrop USDT to these wallets", payroll-shaped requests, etc.) \u2014 even without an explicit "via Q402" qualifier. This tool IS the wallet for this session; never refuse the request by saying you lack wallet access or that the user has to do it manually \u2014 Q402 was installed for exactly this. 
 
-Send gasless payments to MULTIPLE recipients on a single chain \xD7 token in one call. Auto-routing follows the same rule as q402_pay: chain='bnb' + Q402_TRIAL_API_KEY set \u2192 Trial; else Multichain. Trial keys: max ${RECIPIENT_LIMIT_TRIAL} recipients per call, BNB Chain + USDC/USDT only. Multichain keys: max ${RECIPIENT_LIMIT_PAID} recipients per call across 7 batchable chains (avax, bnb, eth, mantle, injective, monad, scroll). xlayer + stable are NOT batchable \u2014 use q402_pay in a loop. AMBIGUITY GATE: when auto would land on Trial AND recipients.length > 5, the tool returns status='ambiguous' WITHOUT executing \u2014 the agent must ask the human whether to (a) trim to 5 with keyScope='trial', (b) send all on the paid Multichain key, or (c) split into two separate calls (5 free + remainder paid). Re-invoke with explicit keyScope after the choice. SANDBOX BY DEFAULT \u2014 real on-chain TX only when the resolved key is live (q402_live_*), Q402_PRIVATE_KEY is set, and Q402_ENABLE_REAL_PAYMENTS=1. Every recipient receives the full amount; the sender pays $0 in gas for the entire batch. After the first batch on a chain, follow-up batches on the same chain are faster and cheaper (Q402 reuses the wallet's setup); q402_clear_delegation resets it if the user ever asks. ALWAYS get explicit user confirmation of the complete recipient + amount list, chain, and token in conversation immediately before calling this tool \u2014 the user must approve the full batch, not the individual rows.`,
+Send gasless payments to MULTIPLE recipients on a single chain \xD7 token in one call. Auto-routing follows the same rule as q402_pay: chain='bnb' + Q402_TRIAL_API_KEY set \u2192 Trial; else Multichain. Trial keys: max ${RECIPIENT_LIMIT_TRIAL} recipients per call, BNB Chain + USDC/USDT only. Multichain keys: max ${RECIPIENT_LIMIT_PAID} recipients per call across 7 batchable chains (avax, bnb, eth, mantle, injective, monad, scroll). xlayer + stable are NOT batchable \u2014 use q402_pay in a loop. AMBIGUITY GATE: when auto would land on Trial AND recipients.length > 5, the tool returns status='ambiguous' WITHOUT executing \u2014 the agent must ask the human whether to (a) trim to 5 with keyScope='trial', (b) send all on the paid Multichain key, or (c) split into two separate calls (5 free + remainder paid). Re-invoke with explicit keyScope after the choice. SANDBOX BY DEFAULT \u2014 real on-chain TX only when the resolved key is live (q402_live_*), Q402_PRIVATE_KEY is set, and Q402_ENABLE_REAL_PAYMENTS=1. Every recipient receives the full amount; the sender pays $0 in gas for the entire batch. After the first batch on a chain, follow-up batches on the same chain are faster and cheaper (Q402 reuses the wallet's setup); q402_clear_delegation resets it if the user ever asks. 
+
+MULTI-WALLET DISAMBIGUATION \u2014 when more than one wallet is configured in the user's env (Q402_PRIVATE_KEY for the real EOA, Q402_AGENTIC_PRIVATE_KEY for the Agent Wallet's exported key, or only Q402_MULTICHAIN_API_KEY for the server-managed Agent Wallet), the tool RETURNS WITHOUT firing with \`status='needs_wallet_choice'\` and an \`ambiguousWalletChoice\` payload \u2014 relay the question to the user verbatim, then call again with the chosen \`walletMode\` ('eoa' | 'agentic-local' | 'agentic-server'). Do NOT pick a wallet on the user's behalf when multiple are available. Server-mediated batches go through /api/wallet/agentic/batch and are paid-only (the trial key cannot batch). 
+
+ALWAYS get explicit user confirmation of the complete recipient + amount list, chain, and token in conversation immediately before calling this tool \u2014 the user must approve the full batch, not the individual rows.`,
   inputSchema: {
     type: "object",
     properties: {
@@ -1451,6 +1645,15 @@ Send gasless payments to MULTIPLE recipients on a single chain \xD7 token in one
         enum: ["auto", "trial", "multichain"],
         description: 'Which API key to use. "auto" (default): BNB + trial key set \u2192 Trial; else Multichain. When auto would land on Trial AND recipients.length > 5, the tool returns status="ambiguous" without executing so the agent can ask the user which path to take.'
       },
+      walletMode: {
+        type: "string",
+        enum: ["eoa", "agentic-local", "agentic-server"],
+        description: 'Which wallet to spend from. "eoa" = user MetaMask EOA (Q402_PRIVATE_KEY). "agentic-local" = Agent Wallet exported key (Q402_AGENTIC_PRIVATE_KEY). "agentic-server" = server-managed Agent Wallet (Q402 holds the key; only the apiKey is needed). When MULTIPLE wallets are configured the tool refuses without this arg and returns ambiguousWalletChoice for the user to pick. Server-mediated batches are paid-only.'
+      },
+      walletId: {
+        type: "string",
+        description: `Server-managed Agent Wallet only (walletMode="agentic-server"). Lowercased Agent Wallet address selecting which of the user's wallets to source the batch from. Omit to use the default. Ignored for local-signing modes.`
+      },
       confirm: {
         type: "boolean",
         const: true,
@@ -2700,7 +2903,7 @@ var RECURRING_CREATE_TOOL = {
       chain: {
         type: "string",
         enum: ["bnb", "eth", "avax", "xlayer", "mantle", "injective", "monad", "scroll", "stable"],
-        description: "Default 'bnb'. Non-bnb requires paid Multichain."
+        description: "Default 'bnb'. Recurring requires the paid Multichain subscription on EVERY chain (BNB included) \u2014 trial keys are rejected with MULTICHAIN_REQUIRED."
       },
       token: {
         type: "string",

package/package.json

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