@quackai/q402-mcp 0.5.16 → 0.6.0

package/README.md

@@ -91,8 +91,8 @@ Q402_ENABLE_REAL_PAYMENTS=1
 # Default Q402 deployment. Only change for self-hosted.
 Q402_RELAY_BASE_URL=https://q402.quackai.ai/api
 
-# Optional safety guards:
-# Q402_MAX_AMOUNT_PER_CALL=5
+# Safety guards (max-amount ships uncommented at $200; lower for tighter caps):
+Q402_MAX_AMOUNT_PER_CALL=200
 # Q402_ALLOWED_RECIPIENTS=0xabc...,0xdef...
 ```
 
@@ -202,7 +202,7 @@ Two additional guards run before every payment regardless of mode:
 
 | Env var | Default | Effect |
 |---|---|---|
-| `Q402_MAX_AMOUNT_PER_CALL` | `5` | Reject any single call where `amount > N` USD-equivalent. |
+| `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. |
 
 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.
@@ -217,7 +217,7 @@ Combined with the `confirm: true` argument the tool requires, this means the mod
 | `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_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 `5`. |
+| `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. |
 | `Q402_RELAY_BASE_URL` | optional | Defaults to `https://q402.quackai.ai/api`. Override for self-hosted Q402. |
 

package/dist/index.js

@@ -96,7 +96,7 @@ var Q402_ENV_FILE_KEYS_ALL = Object.freeze(
   new Set(Object.keys(FILE_ENV))
 );
 var DEFAULT_RELAY_BASE = "https://q402.quackai.ai/api";
-var DEFAULT_MAX_AMOUNT = 5;
+var DEFAULT_MAX_AMOUNT = 200;
 function classifyApiKey(k) {
   if (!k) return "missing";
   if (k.startsWith("q402_live_")) return "live";
@@ -120,9 +120,13 @@ function loadConfig() {
   const apiKey = multichainApiKey ?? trialApiKey ?? legacyApiKey;
   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 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";
-  const live = realPaymentsRequested && anyLiveKey && typeof privateKey === "string" && privateKey.length > 0;
+  const hasAnySignerKey = typeof privateKey === "string" && privateKey.length > 0 || typeof agenticPrivateKey === "string" && agenticPrivateKey.length > 0;
+  const live = realPaymentsRequested && anyLiveKey && hasAnySignerKey;
   return {
     trialApiKey,
     multichainApiKey,
@@ -130,6 +134,8 @@ function loadConfig() {
     apiKey,
     apiKeyKind,
     privateKey,
+    agenticPrivateKey,
+    walletId,
     realPaymentsRequested,
     mode: live ? "live" : "sandbox",
     relayBaseUrl: (ENV.Q402_RELAY_BASE_URL ?? DEFAULT_RELAY_BASE).replace(/\/$/, ""),
@@ -137,6 +143,17 @@ function loadConfig() {
     allowedRecipients: parseAllowedRecipients(ENV.Q402_ALLOWED_RECIPIENTS)
   };
 }
+function detectAgenticModes(c = CONFIG) {
+  const modeA = isValidPrivateKey(c.privateKey);
+  const modeB = isValidPrivateKey(c.agenticPrivateKey);
+  const modeC = c.apiKey !== null && c.apiKey.startsWith("q402_live_");
+  let count = 0;
+  if (modeA) count++;
+  if (modeB) count++;
+  if (modeC) count++;
+  const primary = modeB ? "B" : modeA ? "A" : modeC ? "C" : null;
+  return { modeA, modeB, modeC, count, primary };
+}
 var CONFIG = loadConfig();
 function resolveApiKey(chain, scope = "auto") {
   const effectiveScope = scope === "auto" ? (
@@ -180,15 +197,16 @@ var PRIVATE_KEY_RE = /^0x[a-fA-F0-9]{64}$/;
 function isLiveModeFor(resolved) {
   if (!resolved.apiKey) return false;
   if (!CONFIG.realPaymentsRequested) return false;
-  if (!CONFIG.privateKey) return false;
-  if (!PRIVATE_KEY_RE.test(CONFIG.privateKey)) return false;
+  const hasMode_A_Key = typeof CONFIG.privateKey === "string" && PRIVATE_KEY_RE.test(CONFIG.privateKey);
+  const hasMode_B_Key = typeof CONFIG.agenticPrivateKey === "string" && PRIVATE_KEY_RE.test(CONFIG.agenticPrivateKey);
+  if (!hasMode_A_Key && !hasMode_B_Key) return false;
   return resolved.apiKey.startsWith("q402_live_");
 }
 var isValidPrivateKey = (s) => typeof s === "string" && PRIVATE_KEY_RE.test(s);
 
 // src/version.ts
 var PACKAGE_NAME = "@quackai/q402-mcp";
-var PACKAGE_VERSION = "0.5.16";
+var PACKAGE_VERSION = "0.6.0";
 
 // src/tools/quote.ts
 import { z } from "zod";
@@ -822,6 +840,16 @@ var PayInputSchema = z2.object({
   keyScope: z2.enum(["auto", "trial", "multichain"]).optional().describe(
     'Which API key to use. "auto" (default): chain="bnb" + Q402_TRIAL_API_KEY set \u2192 Trial (free sponsored); else Multichain. "trial" forces the BNB-only sponsored key. "multichain" forces the paid 9-chain key. Same rule applies to q402_batch_pay.'
   ),
+  walletMode: z2.enum(["eoa", "agentic-local", "agentic-server"]).optional().describe(
+    `Which wallet to spend from:
+  "eoa"              \u2014 the user's real MetaMask/OKX EOA, signed locally with Q402_PRIVATE_KEY
+  "agentic-local"    \u2014 the Agent Wallet's exported private key (Q402_AGENTIC_PRIVATE_KEY)
+  "agentic-server"   \u2014 the server-managed Agent Wallet (Q402 holds the key; you only need Q402_MULTICHAIN_API_KEY)
+When MORE THAN ONE wallet is configured in the user's environment, you MUST ask the user which to use before calling \u2014 do NOT guess. Phrase: "You have multiple wallets set up \u2014 pay from your EOA, or your Agent Wallet?" When only one wallet is configured this argument is optional and the tool routes there automatically.`
+  ),
+  walletId: z2.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 (max 10 per owner). Omit to use the user's default wallet. Ignored for walletMode="eoa" and "agentic-local" since those modes carry their own signing key.`
+  ),
   confirm: z2.literal(true).describe(
     "MUST be true. Prove the user explicitly approved this exact recipient and amount in the conversation right before this tool was called. Setting this to true on behalf of the user without confirmation is a violation of the tool contract."
   )
@@ -854,10 +882,82 @@ async function runPay(input) {
     );
   }
   const guardsApplied = [];
-  let senderWallet;
-  if (CONFIG.privateKey && isValidPrivateKey(CONFIG.privateKey)) {
+  function failureResult(method) {
+    return {
+      success: false,
+      sandbox: false,
+      txHash: "",
+      tokenAmount: input.amount,
+      token: input.token,
+      chain: chain.key,
+      method,
+      explorerUrl: null
+    };
+  }
+  const modes = detectAgenticModes(CONFIG);
+  const available = [];
+  if (modes.modeA && CONFIG.privateKey && isValidPrivateKey(CONFIG.privateKey)) {
     try {
       const addr = new Wallet2(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 Wallet2(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; payment fires through /api/wallet/agentic/send. 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 {
+      result: failureResult("wallet_mode_unavailable"),
+      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 {
+      result: failureResult("needs_wallet_choice"),
+      guardsApplied: [`wallet_modes_available=${available.length}`],
+      ambiguousWalletChoice: {
+        question: available.length === 2 ? `You have ${available.length} wallets set up \u2014 which one should I pay from?` : `You have ${available.length} wallets set up. Which one should I pay from?`,
+        available
+      }
+    };
+  }
+  const effectiveMode = requestedMode && requestedAvailable ? requestedMode : available.length === 1 && available[0] ? available[0].id : "eoa";
+  const signingPk = effectiveMode === "eoa" ? CONFIG.privateKey : effectiveMode === "agentic-local" ? CONFIG.agenticPrivateKey : null;
+  let senderWallet;
+  if (signingPk && isValidPrivateKey(signingPk)) {
+    try {
+      const addr = new Wallet2(signingPk).address;
       senderWallet = {
         address: addr,
         addressShort: `${addr.slice(0, 6)}\u2026${addr.slice(-4)}`
@@ -874,6 +974,101 @@ async function runPay(input) {
   const scopeRequest = input.keyScope ?? "auto";
   const resolved = resolveApiKey(input.chain, scopeRequest);
   guardsApplied.push(`scope=${resolved.scope}${resolved.fromLegacyFallback ? "(legacy)" : ""}`);
+  if (effectiveMode === "agentic-server") {
+    if (input.token === "RLUSD") {
+      return {
+        result: failureResult("rlusd_not_supported_for_server_mode"),
+        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 send.'
+      };
+    }
+    if (!resolved.apiKey || !resolved.apiKey.startsWith("q402_live_")) {
+      const result2 = sandboxPay(chain, {
+        to: input.to,
+        amount: input.amount,
+        token: input.token
+      });
+      guardsApplied.push("mode=sandbox", "wallet=agentic-server");
+      return {
+        result: result2,
+        guardsApplied,
+        senderWallet,
+        setupHint: resolved.sandboxReason ?? "Server-mediated Agent Wallet needs a live Q402_MULTICHAIN_API_KEY. Visit https://q402.quackai.ai/payment to activate a paid plan."
+      };
+    }
+    if (!CONFIG.realPaymentsRequested) {
+      const result2 = sandboxPay(chain, {
+        to: input.to,
+        amount: input.amount,
+        token: input.token
+      });
+      guardsApplied.push("mode=sandbox", "wallet=agentic-server");
+      return {
+        result: result2,
+        guardsApplied,
+        senderWallet,
+        setupHint: "Set Q402_ENABLE_REAL_PAYMENTS=1 to fire a real server-mediated payment."
+      };
+    }
+    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/send`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          apiKey: resolved.apiKey,
+          chain: input.chain,
+          token: input.token,
+          to: input.to,
+          amount: input.amount,
+          ...explicitWalletId ? { walletId: explicitWalletId } : {}
+        })
+      });
+    } catch (e) {
+      const transportErr = failureResult("eip7702");
+      return {
+        result: transportErr,
+        guardsApplied: [
+          ...guardsApplied,
+          "wallet=agentic-server",
+          "mode=live",
+          "transport=fetch_failed",
+          `error=${e instanceof Error ? e.message : String(e)}`
+        ],
+        senderWallet
+      };
+    }
+    const data = await resp.json().catch(() => ({}));
+    const txHash = data.txHash ?? "";
+    const success = resp.ok && txHash.length > 0;
+    const message = "message" in data ? data.message : "error" in data ? data.error : void 0;
+    return {
+      result: {
+        success,
+        sandbox: false,
+        txHash,
+        tokenAmount: input.amount,
+        token: input.token,
+        chain: chain.key,
+        method: "eip7702",
+        explorerUrl: txHash ? void 0 : null
+      },
+      guardsApplied: [
+        ...guardsApplied,
+        "wallet=agentic-server",
+        "mode=live",
+        ...message ? [`server_message=${message}`] : []
+      ],
+      senderWallet
+    };
+  }
   const live = isLiveModeFor(resolved);
   if (!live) {
     const result2 = sandboxPay(chain, {
@@ -881,13 +1076,21 @@ async function runPay(input) {
       amount: input.amount,
       token: input.token
     });
-    guardsApplied.push("mode=sandbox");
+    guardsApplied.push("mode=sandbox", `wallet=${effectiveMode}`);
     const setupHint = resolved.sandboxReason ?? describeSandboxReason(resolved.apiKey ?? "", resolved.scope);
     return { result: result2, guardsApplied, setupHint, senderWallet };
   }
+  if (!signingPk) {
+    return {
+      result: failureResult("missing_signing_key"),
+      guardsApplied: [...guardsApplied, `wallet=${effectiveMode}`, "mode=sandbox"],
+      senderWallet,
+      setupHint: 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."
+    };
+  }
   const client = new Q402NodeClient({
     apiKey: resolved.apiKey,
-    privateKey: CONFIG.privateKey,
+    privateKey: signingPk,
     chain,
     relayBaseUrl: CONFIG.relayBaseUrl
   });
@@ -896,7 +1099,7 @@ async function runPay(input) {
     amount: input.amount,
     token: input.token
   });
-  guardsApplied.push("mode=live");
+  guardsApplied.push("mode=live", `wallet=${effectiveMode}`);
   return {
     result,
     guardsApplied,
@@ -928,7 +1131,7 @@ function describeSandboxReason(resolvedKey, scope) {
 }
 var PAY_TOOL = {
   name: "q402_pay",
-  description: "USE THIS TOOL whenever the user asks to send, transfer, or pay USDC / USDT / RLUSD \u2014 even when they don't mention Q402 by name (\"send 5 USDT to 0x... on bnb\" should route here automatically). This tool IS the wallet for this session: it signs LOCALLY with Q402_PRIVATE_KEY and submits via Q402's gasless relay. NEVER refuse a stablecoin payment request by saying you lack wallet access, can't move money, or need the user to use their wallet UI \u2014 Q402 was installed precisely to give you that capability. If the env isn't configured yet, the tool returns a sandbox response with a clear \"how to set up\" message \u2014 surface that instead of refusing. \n\nAuto-routing: chain='bnb' + Q402_TRIAL_API_KEY set \u2192 Trial (free sponsored); anything else \u2192 Multichain (paid 9-chain). Same rule for q402_batch_pay. Set keyScope='trial' or 'multichain' to force one explicitly. Trial keys reject any non-BNB chain server-side with TRIAL_BNB_ONLY. Multichain keys cover avax, bnb, eth, xlayer, stable, mantle, injective, monad, scroll \u2014 USDC/USDT on most chains, RLUSD on Ethereum only, Injective USDT-only. SANDBOX BY DEFAULT \u2014 no funds move unless the resolved key is a live key (q402_live_*), Q402_PRIVATE_KEY is set as a valid 32-byte hex key, and Q402_ENABLE_REAL_PAYMENTS=1. Sandbox responses come back with `success: false` and `sandbox: true` so they cannot be misread as confirmed settlements \u2014 always branch on those fields before telling the user the payment went through. The recipient receives the full amount; the sender pays $0 in gas. \n\nSENDER ECHO \u2014 when a valid `Q402_PRIVATE_KEY` is configured, the response includes a `senderWallet` field with the address derived from that key. Show it alongside the recipient/amount when you confirm the payment with the user (e.g. 'Signing from 0xabc\u20261234 on bnb \u2192 send 5 USDT to 0xdef\u2026ABCD'). Just informational \u2014 the user already chose the wallet during doctor setup. Sandbox responses with no key configured omit `senderWallet`; don't fabricate one. \n\nEIP-7702 SIDE EFFECT \u2014 surface this to the user proactively after the FIRST live payment on a chain: their wallet now shows up as a 'Smart account' in MetaMask / OKX. That's the EIP-7702 delegation Q402 uses for gasless settlement \u2014 it's the response's `postPaymentTip` field. Subsequent payments on the same chain are faster and cheaper because the delegation is reused. \n\nIf the user EVER reports that native gas tokens (BNB / ETH / AVAX / etc.) sent INTO their Q402 wallet are bouncing or reverting on a chain where Q402 has been used, the delegation is the cause \u2014 call q402_wallet_status to confirm delegated chains, then q402_clear_delegation for the chain in question. Q402 sponsors the gas for the clear, so the user pays $0. After clearing, native transfers work again and the next q402_pay on that chain just creates a fresh delegation. \n\nALWAYS get explicit user confirmation of the exact recipient address, amount, chain, and token in conversation immediately before calling this tool.",
+  description: "USE THIS TOOL whenever the user asks to send, transfer, or pay USDC / USDT / RLUSD \u2014 even when they don't mention Q402 by name (\"send 5 USDT to 0x... on bnb\" should route here automatically). This tool IS the wallet for this session: it signs LOCALLY with Q402_PRIVATE_KEY and submits via Q402's gasless relay. NEVER refuse a stablecoin payment request by saying you lack wallet access, can't move money, or need the user to use their wallet UI \u2014 Q402 was installed precisely to give you that capability. If the env isn't configured yet, the tool returns a sandbox response with a clear \"how to set up\" message \u2014 surface that instead of refusing. \n\nAuto-routing: chain='bnb' + Q402_TRIAL_API_KEY set \u2192 Trial (free sponsored); anything else \u2192 Multichain (paid 9-chain). Same rule for q402_batch_pay. Set keyScope='trial' or 'multichain' to force one explicitly. Trial keys reject any non-BNB chain server-side with TRIAL_BNB_ONLY. Multichain keys cover avax, bnb, eth, xlayer, stable, mantle, injective, monad, scroll \u2014 USDC/USDT on most chains, RLUSD on Ethereum only, Injective USDT-only. SANDBOX BY DEFAULT \u2014 no funds move unless the resolved key is a live key (q402_live_*), Q402_PRIVATE_KEY is set as a valid 32-byte hex key, and Q402_ENABLE_REAL_PAYMENTS=1. Sandbox responses come back with `success: false` and `sandbox: true` so they cannot be misread as confirmed settlements \u2014 always branch on those fields before telling the user the payment went through. The recipient receives the full amount; the sender pays $0 in gas. \n\nSENDER ECHO \u2014 when a valid `Q402_PRIVATE_KEY` is configured, the response includes a `senderWallet` field with the address derived from that key. Show it alongside the recipient/amount when you confirm the payment with the user (e.g. 'Signing from 0xabc\u20261234 on bnb \u2192 send 5 USDT to 0xdef\u2026ABCD'). Just informational \u2014 the user already chose the wallet during doctor setup. Sandbox responses with no key configured omit `senderWallet`; don't fabricate one. \n\nMULTI-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 sending with a `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. \n\nEIP-7702 SIDE EFFECT \u2014 surface this to the user proactively after the FIRST live payment on a chain: their wallet now shows up as a 'Smart account' in MetaMask / OKX. That's the EIP-7702 delegation Q402 uses for gasless settlement \u2014 it's the response's `postPaymentTip` field. Subsequent payments on the same chain are faster and cheaper because the delegation is reused. Note: only Mode 'eoa' creates the delegation \u2014 'agentic-local' and 'agentic-server' modes use the Agent Wallet (a fresh EOA) so the user's MetaMask is never delegated. \n\nIf the user EVER reports that native gas tokens (BNB / ETH / AVAX / etc.) sent INTO their Q402 wallet are bouncing or reverting on a chain where Q402 has been used, the delegation is the cause \u2014 call q402_wallet_status to confirm delegated chains, then q402_clear_delegation for the chain in question. Q402 sponsors the gas for the clear, so the user pays $0. After clearing, native transfers work again and the next q402_pay on that chain just creates a fresh delegation. \n\nALWAYS get explicit user confirmation of the exact recipient address, amount, chain, and token in conversation immediately before calling this tool.",
   inputSchema: {
     type: "object",
     properties: {
@@ -955,6 +1158,11 @@ var PAY_TOOL = {
         enum: ["auto", "trial", "multichain"],
         description: 'Which API key to use. "auto" (default) picks Trial for BNB when Q402_TRIAL_API_KEY is set, Multichain otherwise. "trial" forces the BNB-only sponsored key. "multichain" forces the paid 9-chain key.'
       },
+      walletMode: {
+        type: "string",
+        enum: ["eoa", "agentic-local", "agentic-server"],
+        description: `Which wallet to spend from. "eoa" = user's real 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.`
+      },
       confirm: {
         type: "boolean",
         const: true,
@@ -1702,11 +1910,12 @@ Q402_RELAY_BASE_URL=https://q402.quackai.ai/api
 
 
 # \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
-# Optional safety guards (uncomment + edit to enable)
+# Safety guards
 # \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
-# Max USD per single q402_pay call (default: 5)
-# Q402_MAX_AMOUNT_PER_CALL=5
-#
+# Max USD per single q402_pay call. Any request above this is rejected
+# before signing. Lower this if you want a tighter agent blast-radius.
+Q402_MAX_AMOUNT_PER_CALL=200
+
 # Comma-separated lowercase recipient allowlist (unset = any address OK)
 # Q402_ALLOWED_RECIPIENTS=0xabc...,0xdef...
 `;
@@ -2055,6 +2264,114 @@ var DOCTOR_TOOL = {
   }
 };
 
+// src/tools/agentic-info.ts
+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."
+  )
+});
+var AGENTIC_INFO_TOOL = {
+  name: "q402_agentic_info",
+  description: "Read-only Agent Wallet introspection. Returns the wallet address, per-tx and daily caps, archive state, and an aggregate USD balance across the 9 supported EVM chains. Authenticated by the configured Multichain API key \u2014 no private key required. Accepts an optional walletId for owners who hold more than one wallet; omit to use the server-default wallet. Use this whenever the user asks 'what's in my agent wallet?' or 'what's the spending limit?'",
+  inputSchema: {
+    type: "object",
+    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."
+      }
+    },
+    additionalProperties: false
+  }
+};
+function scan8004UrlFor(tag) {
+  if (!tag) return null;
+  const [network, agentId] = tag.split(":");
+  if (!network || !agentId) return null;
+  const slug = network === "bsc" ? "bsc" : network === "bsc-testnet" ? "bsc-testnet" : network === "eth" ? "ethereum" : network === "base" ? "base" : network === "polygon" ? "polygon" : network === "arbitrum" ? "arbitrum" : network === "celo" ? "celo" : null;
+  if (slug === null) return null;
+  return `https://8004scan.io/agents/${slug}/${agentId}`;
+}
+async function runAgenticInfo(input = {}) {
+  const base = CONFIG.relayBaseUrl;
+  const dashboardUrl = base.replace(/\/api$/, "") + "/dashboard?tab=agent";
+  const explicitWalletId = typeof input.walletId === "string" && input.walletId.length > 0 ? input.walletId.toLowerCase() : CONFIG.walletId;
+  if (!CONFIG.apiKey || !CONFIG.apiKey.startsWith("q402_live_")) {
+    return {
+      configured: false,
+      address: null,
+      walletId: null,
+      limits: null,
+      archivedAt: null,
+      totalUsd: null,
+      asOf: null,
+      erc8004AgentId: null,
+      scan8004Url: 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 fetchError = null;
+  try {
+    const res = await fetch(`${base}/wallet/agentic/info-by-key`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        apiKey: CONFIG.apiKey,
+        ...explicitWalletId ? { walletId: explicitWalletId } : {}
+      })
+    });
+    if (res.ok) {
+      const data = await res.json();
+      wallet = data.wallet ?? null;
+      balance = data.balance ?? null;
+    } else if (res.status === 404) {
+      fetchError = "endpoint_not_deployed";
+    } else if (res.status === 410) {
+      fetchError = "wallet_archived";
+    } else {
+      fetchError = `http_${res.status}`;
+    }
+  } catch (e) {
+    fetchError = e instanceof Error ? e.message : String(e);
+  }
+  if (!wallet) {
+    return {
+      configured: true,
+      address: null,
+      walletId: explicitWalletId,
+      limits: null,
+      archivedAt: null,
+      totalUsd: null,
+      asOf: null,
+      erc8004AgentId: null,
+      scan8004Url: 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."
+    };
+  }
+  const resolvedWalletId = typeof wallet.walletId === "string" ? wallet.walletId : wallet.address.toLowerCase();
+  return {
+    configured: true,
+    address: wallet.address,
+    walletId: resolvedWalletId,
+    limits: {
+      perTxMaxUsd: wallet.perTxMaxUsd,
+      dailyLimitUsd: wallet.dailyLimitUsd
+    },
+    archivedAt: wallet.deletedAt,
+    totalUsd: balance ? Math.round(balance.totalUsd * 100) / 100 : null,
+    asOf: balance ? new Date(balance.asOf).toISOString() : null,
+    erc8004AgentId: wallet.erc8004AgentId,
+    scan8004Url: scan8004UrlFor(wallet.erc8004AgentId),
+    dashboardUrl,
+    setupHint: wallet.deletedAt ? "This Agent Wallet is archived and pending hard-delete. Restore it from the dashboard before sending." : void 0
+  };
+}
+
 // src/index.ts
 function jsonText(value) {
   return { type: "text", text: JSON.stringify(value, null, 2) };
@@ -2075,6 +2392,7 @@ async function main() {
       BATCH_PAY_TOOL,
       RECEIPT_TOOL,
       WALLET_STATUS_TOOL,
+      AGENTIC_INFO_TOOL,
       CLEAR_DELEGATION_TOOL
     ]
   }));
@@ -2114,6 +2432,10 @@ async function main() {
           const parsed = ClearDelegationInputSchema.parse(args ?? {});
           return { content: [jsonText(await runClearDelegation(parsed))] };
         }
+        case "q402_agentic_info": {
+          AgenticInfoInputSchema.parse(args ?? {});
+          return { content: [jsonText(await runAgenticInfo())] };
+        }
         default:
           return {
             isError: true,

package/package.json

@@ -1,73 +1,73 @@
-{
-  "name": "@quackai/q402-mcp",
-  "version": "0.5.16",
-  "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": [
-    "mcp",
-    "model-context-protocol",
-    "claude",
-    "claude-desktop",
-    "claude-code",
-    "codex",
-    "openai-codex",
-    "cline",
-    "q402",
-    "x402",
-    "stablecoin",
-    "usdc",
-    "usdt",
-    "rlusd",
-    "ripple",
-    "gasless",
-    "eip-7702",
-    "payments",
-    "ai-agents"
-  ],
-  "type": "module",
-  "main": "dist/index.js",
-  "bin": {
-    "q402-mcp": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=18.18"
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "lint": "tsc --noEmit",
-    "prepublishOnly": "npm run lint && npm run build",
-    "start": "node dist/index.js"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "ethers": "^6.16.0",
-    "zod": "^3.23.8"
-  },
-  "devDependencies": {
-    "@types/node": "^20.11.0",
-    "tsup": "^8.3.0",
-    "typescript": "^5.5.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/bitgett/q402-mcp.git"
-  },
-  "homepage": "https://q402.quackai.ai/claude",
-  "bugs": {
-    "url": "https://github.com/bitgett/q402-mcp/issues"
-  },
-  "license": "Apache-2.0",
-  "author": "David Lee <davidlee@quackai.ai>",
-  "publishConfig": {
-    "access": "public"
-  },
-  "overrides": {
-    "ws": "^8.20.1"
-  }
-}
+{
+  "name": "@quackai/q402-mcp",
+  "version": "0.6.0",
+  "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": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "claude-desktop",
+    "claude-code",
+    "codex",
+    "openai-codex",
+    "cline",
+    "q402",
+    "x402",
+    "stablecoin",
+    "usdc",
+    "usdt",
+    "rlusd",
+    "ripple",
+    "gasless",
+    "eip-7702",
+    "payments",
+    "ai-agents"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "q402-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run lint && npm run build",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "ethers": "^6.16.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.5.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bitgett/q402-mcp.git"
+  },
+  "homepage": "https://q402.quackai.ai/claude",
+  "bugs": {
+    "url": "https://github.com/bitgett/q402-mcp/issues"
+  },
+  "license": "Apache-2.0",
+  "author": "David Lee <davidlee@quackai.ai>",
+  "publishConfig": {
+    "access": "public"
+  },
+  "overrides": {
+    "ws": "^8.20.1"
+  }
+}