@quackai/q402-mcp 0.5.17 → 0.6.1

package/dist/index.js

@@ -120,9 +120,18 @@ 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_AGENT_WALLET_ADDRESS ?? ENV.Q402_WALLET_ID;
+  if (!ENV.Q402_AGENT_WALLET_ADDRESS && ENV.Q402_WALLET_ID) {
+    process.stderr.write(
+      "[q402-mcp] Q402_WALLET_ID is deprecated \u2014 rename to Q402_AGENT_WALLET_ADDRESS. Old name will be removed in v0.7.0.\n"
+    );
+  }
+  const walletId = typeof walletIdRaw === "string" && walletIdRaw.length > 0 ? walletIdRaw.toLowerCase() : null;
   const realPaymentsRequested = ENV.Q402_ENABLE_REAL_PAYMENTS === "1";
   const anyLiveKey = classifyApiKey(trialApiKey) === "live" || classifyApiKey(multichainApiKey) === "live" || classifyApiKey(legacyApiKey) === "live";
-  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 +139,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 +148,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 +202,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.17";
+var PACKAGE_VERSION = "0.6.1";
 
 // src/tools/quote.ts
 import { z } from "zod";
@@ -822,6 +845,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 +887,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 +979,127 @@ 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 isPending = resp.status === 202 || data.pending === true || data.status === "processing";
+    if (isPending) {
+      const retryAfter = typeof data.retryAfterSec === "number" ? data.retryAfterSec : 5;
+      return {
+        result: {
+          success: false,
+          sandbox: false,
+          txHash: "",
+          tokenAmount: input.amount,
+          token: input.token,
+          chain: chain.key,
+          method: "eip7702",
+          pending: true,
+          retryAfterSec: retryAfter
+        },
+        guardsApplied: [
+          ...guardsApplied,
+          "wallet=agentic-server",
+          "mode=live",
+          "status=pending",
+          `retry_after=${retryAfter}s`
+        ],
+        senderWallet,
+        setupHint: `An identical send for this wallet is still in flight on the server. Wait ${retryAfter}s and retry \u2014 the cached result will come back, no double-spend.`
+      };
+    }
+    const success = resp.ok && txHash.length > 0;
+    const message = "message" in data ? data.message : "error" in data ? data.error : void 0;
+    return {
+      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 +1107,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 +1130,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 +1162,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 +1189,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,
@@ -1676,13 +1915,76 @@ Q402_MULTICHAIN_API_KEY=
 
 
 # \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
-# WALLET \u2014 paste your private key on the right of \`=\`
+# SIGNING MODE \u2014 pick ONE of A / B / C below
+# \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+# Q402 pays in three ways, depending on which keys you set. Pick the
+# row that matches your situation and fill ONLY that row's variable(s).
+# Setting multiple rows is allowed \u2014 q402_pay will ask you which one to
+# use per call (the AI surfaces the question; you don't pre-pick a
+# default here).
+#
+#   A. Real EOA (your MetaMask wallet)
+#      Set:  Q402_PRIVATE_KEY  =  0x... (your MetaMask account's private key)
+#      Pros: simplest mental model \u2014 same wallet you already use
+#      Cons: after first payment, MetaMask will show this account as
+#            "Smart account" (EIP-7702 delegation, reversible via
+#            q402_clear_delegation but visually alarming on first sight)
+#
+#   B. Agent Wallet \u2014 local signing (recommended for AI agents)
+#      Set:  Q402_AGENTIC_PRIVATE_KEY  =  0x... (Agent Wallet pk from dashboard export)
+#      Pros: your MetaMask stays untouched; agent has its own purse with
+#            per-tx + daily caps you set on the dashboard
+#      Cons: requires creating an Agent Wallet on the dashboard first
+#            (https://q402.quackai.ai/dashboard \u2192 Agent tab \u2192 Create)
+#            then exporting its private key
+#
+#   C. Agent Wallet \u2014 server-managed (no private key on your machine)
+#      Set:  (just the api key + optionally Q402_AGENT_WALLET_ADDRESS below)
+#      Pros: zero private-key handling locally; the server holds the
+#            encrypted Agent Wallet pk and signs on your behalf
+#      Cons: requires a paid Multichain API key (Mode C is not available
+#            on the free Trial). The server-side keystore is AES-256-GCM
+#            encrypted but is a custodial path \u2014 pick A or B if that
+#            posture doesn't fit your threat model.
+#
+# A user can have multiple wallets configured simultaneously (e.g. PK
+# for personal pays + apiKey-only for agent pays). When more than one
+# mode is set, q402_pay asks the user which to use rather than picking
+# silently.
+
+
+# \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+# WALLET \u2014 Mode A: real EOA private key
 # \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
 # Hex EVM private key (0x + 64 hex chars). Signs payments LOCALLY on
 # your machine \u2014 never leaves your device, never sent to any server.
+# Leave blank if you're using Mode B or Mode C.
 Q402_PRIVATE_KEY=
 
 
+# \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+# WALLET \u2014 Mode B: exported Agent Wallet private key
+# \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+# Hex EVM private key (0x + 64 hex chars) exported from your Agent
+# Wallet on the dashboard. Signs payments LOCALLY just like Mode A,
+# but the wallet is your dedicated Agent Wallet \u2014 your MetaMask EOA
+# is never touched. Get the key at:
+#   https://q402.quackai.ai/dashboard \u2192 Agent tab \u2192 Export
+# Leave blank if you're using Mode A or Mode C.
+Q402_AGENTIC_PRIVATE_KEY=
+
+
+# \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+# WALLET \u2014 Mode C: server-managed Agent Wallet picker (optional)
+# \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+# Only set this when you're running Mode C (api key only, no private
+# keys above) AND you have more than one Agent Wallet on the account
+# (max 10). Pin which one Q402 should spend from. Format: lowercase
+# 0x... address of the Agent Wallet (visible on the dashboard's Agent
+# tab). Omit entirely to use your default Agent Wallet.
+# Q402_AGENT_WALLET_ADDRESS=0x...
+
+
 # \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
 # Live mode switch (safe even at 1 \u2014 see SAFE-BY-DEFAULT note at top)
 # \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
@@ -1735,13 +2037,16 @@ function mask2(key) {
 function detectPhase() {
   const anyKey = !!(CONFIG.trialApiKey || CONFIG.multichainApiKey || CONFIG.legacyApiKey);
   const anyLiveKey = classifyApiKey(CONFIG.trialApiKey) === "live" || classifyApiKey(CONFIG.multichainApiKey) === "live" || classifyApiKey(CONFIG.legacyApiKey) === "live";
-  const hasValidPrivateKey = isValidPrivateKey(CONFIG.privateKey);
-  if (!Q402_ENV_FILE_PRESENT && !anyKey && !CONFIG.privateKey) {
+  const modes = detectAgenticModes();
+  const hasAnyValidSigningPath = modes.count > 0;
+  if (!Q402_ENV_FILE_PRESENT && !anyKey && !CONFIG.privateKey && !CONFIG.agenticPrivateKey) {
     return "first-install";
   }
-  const allEssentials = anyKey && hasValidPrivateKey && CONFIG.realPaymentsRequested && anyLiveKey;
+  const allEssentials = anyKey && hasAnyValidSigningPath && CONFIG.realPaymentsRequested && anyLiveKey;
   if (allEssentials) return "live-check";
-  if (anyKey || CONFIG.privateKey || Q402_ENV_FILE_PRESENT) return "needs-completion";
+  if (anyKey || CONFIG.privateKey || CONFIG.agenticPrivateKey || Q402_ENV_FILE_PRESENT) {
+    return "needs-completion";
+  }
   return "first-install";
 }
 async function verifyOneKey(scope, envVar, apiKey) {
@@ -1862,23 +2167,33 @@ async function runDoctor() {
       "Must be '1' to allow real TX. Anything else = test response (fake hash)."
     )
   };
+  const modes = detectAgenticModes();
   const missing = [];
   if (!CONFIG.trialApiKey && !CONFIG.multichainApiKey && !CONFIG.legacyApiKey) {
     missing.push(
       "An API key (Q402_TRIAL_API_KEY for free BNB OR Q402_MULTICHAIN_API_KEY for paid 9-chain)"
     );
   }
-  if (!CONFIG.privateKey) {
-    missing.push("Q402_PRIVATE_KEY");
-  } else if (!isValidPrivateKey(CONFIG.privateKey)) {
-    missing.push(
-      "Q402_PRIVATE_KEY is set but malformed (expected 0x + 64 hex chars). Looks like the placeholder '0x...' is still in ~/.q402/mcp.env \u2014 paste a real key in your editor."
-    );
+  if (modes.count === 0) {
+    const pkAPlaceholder = !!CONFIG.privateKey && !isValidPrivateKey(CONFIG.privateKey);
+    const pkBPlaceholder = !!CONFIG.agenticPrivateKey && !isValidPrivateKey(CONFIG.agenticPrivateKey);
+    if (pkAPlaceholder) {
+      missing.push(
+        "Q402_PRIVATE_KEY is set but malformed (expected 0x + 64 hex chars). Looks like the placeholder '0x...' is still in ~/.q402/mcp.env \u2014 paste a real key in your editor."
+      );
+    } else if (pkBPlaceholder) {
+      missing.push(
+        "Q402_AGENTIC_PRIVATE_KEY is set but malformed (expected 0x + 64 hex chars). Paste your exported Agent Wallet private key (https://q402.quackai.ai/dashboard \u2192 Agent tab \u2192 Export)."
+      );
+    } else {
+      missing.push(
+        "A signing path. Pick ONE: (A) Q402_PRIVATE_KEY = your MetaMask EOA's private key; (B) Q402_AGENTIC_PRIVATE_KEY = your exported Agent Wallet private key from the dashboard (Mode B keeps your MetaMask untouched); or (C) just use a live paid Q402_MULTICHAIN_API_KEY and let Q402 sign with your server-managed Agent Wallet (no PK on your machine)."
+      );
+    }
   }
   if (!CONFIG.realPaymentsRequested) {
     const haveAnyApi = !!(CONFIG.trialApiKey || CONFIG.multichainApiKey || CONFIG.legacyApiKey);
-    const havePk = isValidPrivateKey(CONFIG.privateKey);
-    if (haveAnyApi && havePk) {
+    if (haveAnyApi && modes.count > 0) {
       missing.push(
         "Q402_ENABLE_REAL_PAYMENTS=1 \u2014 your other config looks fine, but your MCP client isn't passing the registry default through. Add the line Q402_ENABLE_REAL_PAYMENTS=1 to ~/.q402/mcp.env explicitly and restart."
       );
@@ -1933,12 +2248,13 @@ async function runDoctor() {
       recommendedActions,
       greeting: phase === "first-install" ? `Q402 MCP is installed (v${PACKAGE_VERSION}).` : `Q402 MCP is installed (v${PACKAGE_VERSION}) \u2014 partially configured.`,
       nextStep: phase === "first-install" ? "Show userInstructions verbatim to the user; do NOT show agentInstructions verbatim (it's prescription for you, the AI)." : "Tell the user which env vars are still missing (from the 'missing' list) and how to add them to ~/.q402/mcp.env. Show userInstructions for the human-readable steps.",
-      agentInstructions: phase === "first-install" ? "[AI-ONLY \u2014 do not show this paragraph to the user verbatim] Multi-turn flow: (1) Briefly tell the user MCP is installed. (2) Ask one yes/no question \u2014 'Want me to create your Q402 settings file?'. (3) On yes, execute recommendedActions IN ORDER: first `ensure-q402-dir` shell action (bash on macOS/Linux, PowerShell on Windows via shellWindows variant), then `create-env-file` write_file action. (4) Open the file in the user's editor \u2014 `code` works for VS Code / Cursor / Cline (e.g. `code ~/.q402/mcp.env`); `open` on macOS, `start` on Windows, `xdg-open` on Linux as fallback. (5) Walk through filling in the API key (from /event for free Trial or /payment for paid Multichain) and private key one at a time. (6) Do NOT accept key values via chat \u2014 direct the user to edit the file in their editor. BEFORE they paste a private key, surface the `advisories` array: fresh wallet, Smart-account-in-MetaMask heads-up, hardware wallets unsupported, MetaMask key-export path. (7) After they save, tell them to restart the MCP client \u2014 per-client restart verb: Claude Desktop \u2192 quit + relaunch; Codex \u2192 exit + relaunch; Cursor \u2192 Cmd/Ctrl+Shift+P \u2192 'Developer: Reload Window'; Cline \u2192 reload VS Code window. (8) Have them re-invoke 'Set up Q402' to confirm. Keep the conversation tight: one decision per turn, plain language, never echo this paragraph." : "[AI-ONLY \u2014 do not show this paragraph to the user verbatim] User has SOME env set. List the missing items (from `missing`) in plain language. Tell them to edit ~/.q402/mcp.env and uncomment / fill the relevant line, then restart the MCP client. Restart verb per client: Claude Desktop \u2192 quit + relaunch; Codex \u2192 exit + relaunch; Cursor \u2192 Cmd/Ctrl+Shift+P \u2192 'Developer: Reload Window'; Cline \u2192 reload VS Code window.",
+      agentInstructions: phase === "first-install" ? "[AI-ONLY \u2014 do not show this paragraph to the user verbatim] Multi-turn flow: (1) Briefly tell the user MCP is installed. (2) Ask one yes/no question \u2014 'Want me to create your Q402 settings file?'. (3) On yes, execute recommendedActions IN ORDER: first `ensure-q402-dir` shell action (bash on macOS/Linux, PowerShell on Windows via shellWindows variant), then `create-env-file` write_file action. (4) Open the file in the user's editor \u2014 `code` works for VS Code / Cursor / Cline (e.g. `code ~/.q402/mcp.env`); `open` on macOS, `start` on Windows, `xdg-open` on Linux as fallback. (5) Help the user pick a wallet mode (A=Q402_PRIVATE_KEY real EOA, B=Q402_AGENTIC_PRIVATE_KEY exported Agent Wallet PK, C=API key only with server-managed Agent Wallet). If they're an AI agent / automation user, gently default to B or C; if they're a power user who wants their existing EOA to be the signer, A is fine. Walk through filling in the chosen mode's variable + the API key one at a time. (6) Do NOT accept key values via chat \u2014 direct the user to edit the file in their editor. BEFORE they paste any private key (Mode A OR Mode B), surface the `advisories` array: fresh wallet, Smart-account-in-MetaMask heads-up (Mode A only), hardware wallets unsupported, MetaMask key-export path (Mode A) or dashboard Export button (Mode B). (7) After they save, tell them to restart the MCP client \u2014 per-client restart verb: Claude Desktop \u2192 quit + relaunch; Codex \u2192 exit + relaunch; Cursor \u2192 Cmd/Ctrl+Shift+P \u2192 'Developer: Reload Window'; Cline \u2192 reload VS Code window. (8) Have them re-invoke 'Set up Q402' to confirm. Keep the conversation tight: one decision per turn, plain language, never echo this paragraph." : "[AI-ONLY \u2014 do not show this paragraph to the user verbatim] User has SOME env set. List the missing items (from `missing`) in plain language. Tell them to edit ~/.q402/mcp.env and uncomment / fill the relevant line, then restart the MCP client. Restart verb per client: Claude Desktop \u2192 quit + relaunch; Codex \u2192 exit + relaunch; Cursor \u2192 Cmd/Ctrl+Shift+P \u2192 'Developer: Reload Window'; Cline \u2192 reload VS Code window.",
       userInstructions: phase === "first-install" ? [
-        "Q402 is installed. To start sending payments you need an API key and a wallet.",
+        "Q402 is installed. To start sending payments you need (1) an API key and (2) a wallet to sign with.",
         "I'll create a settings file for you \u2014 say yes and I'll set it up + open it in your editor.",
         "Get a free API key at https://q402.quackai.ai/event (BNB Chain only, 2,000 sponsored transactions).",
-        "Use a FRESH wallet for Q402 \u2014 don't use your main wallet. The wallet will be marked 'Smart account' in MetaMask after your first payment (that's normal \u2014 Q402 reverses it on demand).",
+        "There are 3 wallet modes \u2014 pick one: (A) your MetaMask EOA's private key (simplest, but your account will be marked 'Smart account' after first payment); (B) export an Agent Wallet's private key from the dashboard (keeps your MetaMask untouched, recommended for AI agents); (C) on a paid plan, use the server-managed Agent Wallet \u2014 just set the API key, no private key needed.",
+        "Use a FRESH wallet for Mode A \u2014 don't use the one holding your main funds. The 'Smart account' marker is normal (EIP-7702 delegation, reversible via q402_clear_delegation).",
         "Paste your key + wallet private key INTO THE FILE (in your editor) \u2014 never paste a private key into this chat.",
         "Save the file, restart your MCP client, then ask me 'Verify Q402' to confirm."
       ] : [
@@ -2056,6 +2372,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_AGENT_WALLET_ADDRESS 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_AGENT_WALLET_ADDRESS 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) };
@@ -2076,6 +2500,7 @@ async function main() {
       BATCH_PAY_TOOL,
       RECEIPT_TOOL,
       WALLET_STATUS_TOOL,
+      AGENTIC_INFO_TOOL,
       CLEAR_DELEGATION_TOOL
     ]
   }));
@@ -2115,6 +2540,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.17",
-  "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.1",
+  "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"
+  }
+}