@quackai/q402-mcp 0.7.2 → 0.7.4

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.2";
+var PACKAGE_VERSION = "0.7.4";
 
 // 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,
@@ -2505,12 +2708,14 @@ async function runAgenticInfo(input = {}) {
       asOf: null,
       erc8004AgentId: null,
       scan8004Url: null,
+      reputation: null,
       dashboardUrl,
       setupHint: "No live Q402 API key configured. Run q402_doctor to set one up, or open your dashboard to create an Agent Wallet."
     };
   }
   let wallet = null;
   let balance = null;
+  let reputation = null;
   let fetchError = null;
   try {
     const res = await fetch(`${base}/wallet/agentic/info-by-key`, {
@@ -2525,6 +2730,7 @@ async function runAgenticInfo(input = {}) {
       const data = await res.json();
       wallet = data.wallet ?? null;
       balance = data.balance ?? null;
+      reputation = data.reputation ?? null;
     } else if (res.status === 404) {
       fetchError = "endpoint_not_deployed";
     } else if (res.status === 410) {
@@ -2546,6 +2752,7 @@ async function runAgenticInfo(input = {}) {
       asOf: null,
       erc8004AgentId: null,
       scan8004Url: null,
+      reputation: null,
       dashboardUrl,
       setupHint: fetchError === "endpoint_not_deployed" ? "Agent Wallet info-by-key endpoint is not live yet. Open the dashboard to view your wallet directly." : fetchError === "wallet_archived" ? "The requested wallet is archived. Restore it from the dashboard before reading." : explicitWalletId ? `Could not fetch Agent Wallet ${explicitWalletId} for this apiKey. Verify the walletId is one of this owner's wallets, or omit it to read the default wallet.` : "Could not fetch Agent Wallet for this apiKey. Verify the key is bound to a wallet via the dashboard, then retry."
     };
@@ -2564,6 +2771,7 @@ async function runAgenticInfo(input = {}) {
     asOf: balance ? new Date(balance.asOf).toISOString() : null,
     erc8004AgentId: wallet.erc8004AgentId,
     scan8004Url: scan8004UrlFor(wallet.erc8004AgentId),
+    reputation,
     dashboardUrl,
     setupHint: wallet.deletedAt ? "This Agent Wallet is archived and pending hard-delete. Restore it from the dashboard before sending." : void 0
   };
@@ -3288,8 +3496,8 @@ async function main() {
           return { content: [jsonText(await runClearDelegation(parsed))] };
         }
         case "q402_agentic_info": {
-          AgenticInfoInputSchema.parse(args ?? {});
-          return { content: [jsonText(await runAgenticInfo())] };
+          const parsed = AgenticInfoInputSchema.parse(args ?? {});
+          return { content: [jsonText(await runAgenticInfo(parsed))] };
         }
         case "q402_recurring_list": {
           const parsed = RecurringListInputSchema.parse(args ?? {});

package/package.json

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