@quackai/q402-mcp 0.8.17 → 0.8.19

package/README.md

@@ -156,7 +156,7 @@ Then export the values in `~/.zshrc` / `~/.bashrc`. See the [Codex config refere
 
 ## Tools exposed
 
-**20 tools** — read-only by default; live mode needs an API key + signing path + `Q402_ENABLE_REAL_PAYMENTS=1`.
+**24 tools** — read-only by default; live mode needs an API key + signing path + `Q402_ENABLE_REAL_PAYMENTS=1`.
 
 | Tool | Auth | Purpose |
 |---|---|---|
@@ -180,8 +180,12 @@ Then export the values in `~/.zshrc` / `~/.bashrc`. See the [Codex config refere
 | `q402_bridge_send` | live mode | Execute a CCIP bridge from the user's Agent Wallet. Mode C only (server-managed). Sandbox-by-default; `sandbox: false` + live Multichain key + `Q402_ENABLE_REAL_PAYMENTS=1` fires a real on-chain bridge. |
 | `q402_bridge_history` | not yet wired | Pointer to the dashboard. Returns `{ implemented: false, dashboardUrl, dashboardPath }` — read-only guidance until owner-sig auth lands in MCP. |
 | `q402_bridge_gas_tank` | not yet wired | Static guidance + dashboard pointer for the Bridge Gas Tank top-up flow. Live balance lookup needs owner-sig auth (dashboard for now). |
+| `q402_yield_reserves` | none | List Q402 Yield (Aave V3) lending markets — protocol, chain, asset, market address, supply APY. BNB Chain only today. |
+| `q402_yield_positions` | api key | Show the Agent Wallet's open Q402 Yield positions (balance, principal, accrued interest, APY) + total supplied in USD. Mode C. |
+| `q402_yield_deposit` | live mode | Supply the Agent Wallet's USDC/USDT into Aave V3 (Q402 Yield) to earn supply APY. Mode C, BNB-only. Requires `confirm: true`; sandbox-by-default. |
+| `q402_yield_withdraw` | live mode | Withdraw supplied USDC/USDT out of Aave V3 back to the Agent Wallet (`amount: "max"` = full position). Mode C, BNB-only. Requires `confirm: true`; sandbox-by-default. |
 
-`q402_pay` + `q402_batch_pay` + `q402_bridge_send` require explicit in-chat confirmation. Batch confirmation = full batch, not per-row.
+`q402_pay` + `q402_batch_pay` + `q402_bridge_send` + `q402_yield_deposit` + `q402_yield_withdraw` require explicit in-chat confirmation. Batch confirmation = full batch, not per-row.
 
 > ℹ️ `q402_pay` expects a 0x address — ENS isn't resolved server-side. Resolve client-side first.
 > Per-chain Gas Tank balances + full TX history live in the [dashboard](https://q402.quackai.ai/dashboard) (wallet-signature only).

package/dist/index.js

@@ -212,7 +212,7 @@ var isValidPrivateKey = (s) => typeof s === "string" && PRIVATE_KEY_RE.test(s);
 // package.json
 var package_default = {
   name: "@quackai/q402-mcp",
-  version: "0.8.17",
+  version: "0.8.19",
   description: "MCP server for Q402 \u2014 gasless USDC/USDT/RLUSD payments on 10 EVM chains + Chainlink CCIP USDC bridge on the eth/avax/arbitrum triangle, callable from Claude (Desktop / Code), OpenAI Codex CLI, and any other Model Context Protocol client.",
   mcpName: "io.github.bitgett/q402-mcp",
   keywords: [
@@ -3335,10 +3335,481 @@ async function runBridgeGasTank(_input) {
   };
 }
 
-// src/tools/recurring-list.ts
+// src/tools/yield-reserves.ts
 import { z as z14 } from "zod";
-var RecurringListInputSchema = z14.object({
-  walletId: z14.string().optional().describe(
+var YieldReservesInputSchema = z14.object({
+  chain: z14.enum(["bnb"]).optional().describe("Optional chain filter. Q402 Yield is BNB-only today \u2014 only 'bnb' is accepted. Omit to list all supported chains.")
+});
+var YIELD_RESERVES_TOOL = {
+  name: "q402_yield_reserves",
+  description: "READ-ONLY \u2014 list the Q402 Yield (Aave) lending markets the Agent Wallet can supply into. Returns each market's protocol, chain, asset, asset address, position token, market address, and current supply APY (shown as a %). No auth required and no funds move \u2014 this is purely a preview of available yield. BNB CHAIN ONLY \u2014 Q402 Yield supports BNB Chain today. Pass an optional `chain` to filter; omit it to see every supported chain. Use this whenever the user asks 'where can I earn yield?' or 'what's the lending APY on <asset>?' before supplying.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      chain: {
+        type: "string",
+        enum: ["bnb"],
+        description: "Optional chain filter. Q402 Yield is BNB-only today \u2014 only 'bnb' is accepted. Omit for all supported chains."
+      }
+    },
+    additionalProperties: false
+  }
+};
+async function runYieldReserves(input) {
+  const url = new URL(`${CONFIG.relayBaseUrl}/wallet/agentic/yield/reserves`);
+  if (input.chain) url.searchParams.set("chain", input.chain);
+  let res;
+  try {
+    res = await fetch(url, {
+      method: "GET",
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(15e3)
+    });
+  } catch (e) {
+    return {
+      content: [{
+        type: "text",
+        text: `Yield reserves fetch failed: ${e instanceof Error ? e.message : String(e)}. Retry in a moment.`
+      }],
+      isError: true
+    };
+  }
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    return {
+      content: [{
+        type: "text",
+        text: `Yield reserves failed (HTTP ${res.status}): ${JSON.stringify(data)}`
+      }],
+      isError: true
+    };
+  }
+  const markets = data.markets ?? [];
+  const summary = markets.length ? markets.map((m) => `${m.label} (${m.chain}): ${(m.supplyApy * 100).toFixed(2)}% APY`).join("\n") : "No yield markets returned for the requested filter.";
+  return {
+    content: [
+      { type: "text", text: summary },
+      {
+        type: "text",
+        text: JSON.stringify({
+          supportedChains: data.supportedChains ?? [],
+          markets: markets.map((m) => ({
+            ...m,
+            supplyApyPct: Math.round(m.supplyApy * 100 * 100) / 100
+          })),
+          asOf: data.asOf ?? null
+        }, null, 2)
+      }
+    ]
+  };
+}
+
+// src/tools/yield-positions.ts
+import { z as z15 } from "zod";
+var YieldPositionsInputSchema = z15.object({
+  walletId: z15.string().optional().describe(
+    "Optional Agent Wallet address whose positions to read (max 10 per owner). Omit and the server defaults to the owner's default wallet (resolved from the API key); Q402_AGENT_WALLET_ADDRESS env fills it in when set."
+  ),
+  chain: z15.enum(["bnb"]).optional().describe("Optional chain filter. Q402 Yield is BNB-only today \u2014 only 'bnb' is accepted. Omit for all supported chains.")
+});
+var YIELD_POSITIONS_TOOL = {
+  name: "q402_yield_positions",
+  description: "READ-ONLY \u2014 show the Agent Wallet's current Q402 Yield (Aave) lending positions. Returns each position's protocol, chain, asset, market address, balance, principal, accrued interest, and supply APY, plus the aggregate total supplied in USD. Authenticated by the configured live Multichain API key \u2014 no private key required and no funds move. BNB CHAIN ONLY \u2014 Q402 Yield supports BNB Chain today. walletId is OPTIONAL: omit it and the server reads the owner's default Agent Wallet (resolved from the API key); pass one only when the owner holds more than one wallet. An optional chain filter is also accepted. Use this whenever the user asks 'how much am I earning?' or 'what are my open lending positions?'",
+  inputSchema: {
+    type: "object",
+    properties: {
+      walletId: {
+        type: "string",
+        description: "Optional Agent Wallet address. Omit to read the owner's default wallet (the server resolves it from the API key); pass one only when the owner holds multiple wallets. Q402_AGENT_WALLET_ADDRESS env fills it in when set."
+      },
+      chain: {
+        type: "string",
+        enum: ["bnb"],
+        description: "Optional chain filter. Q402 Yield is BNB-only today \u2014 only 'bnb' is accepted. Omit for all supported chains."
+      }
+    },
+    additionalProperties: false
+  }
+};
+async function runYieldPositions(input) {
+  const resolved = resolveApiKey("eth", "multichain");
+  if (!resolved.apiKey || !resolved.apiKey.startsWith("q402_live_")) {
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          configured: false,
+          positions: null,
+          setupHint: resolved.sandboxReason ?? "No live Q402 Multichain API key configured. Set Q402_MULTICHAIN_API_KEY to a q402_live_\u2026 key from https://q402.quackai.ai/payment, or run q402_doctor."
+        }, null, 2)
+      }],
+      isError: true
+    };
+  }
+  const walletId = typeof input.walletId === "string" && input.walletId.length > 0 ? input.walletId.toLowerCase() : CONFIG.walletId ?? void 0;
+  const url = new URL(`${CONFIG.relayBaseUrl}/wallet/agentic/yield/positions`);
+  if (walletId) url.searchParams.set("walletId", walletId);
+  if (input.chain) url.searchParams.set("chain", input.chain);
+  let res;
+  try {
+    res = await fetch(url, {
+      method: "GET",
+      headers: {
+        Accept: "application/json",
+        "x-api-key": resolved.apiKey
+      },
+      signal: AbortSignal.timeout(15e3)
+    });
+  } catch (e) {
+    return {
+      content: [{
+        type: "text",
+        text: `Yield positions fetch failed: ${e instanceof Error ? e.message : String(e)}. Retry in a moment.`
+      }],
+      isError: true
+    };
+  }
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    return {
+      content: [{
+        type: "text",
+        text: `Yield positions failed (HTTP ${res.status}): ${JSON.stringify(data)}`
+      }],
+      isError: true
+    };
+  }
+  const positions = data.positions ?? [];
+  const unavailableChains = Array.isArray(data.unavailableChains) ? data.unavailableChains : [];
+  const hasUnavailable = data.unavailable === true || unavailableChains.length > 0;
+  const unavailableNote = hasUnavailable ? ` Some chains could not be read this cycle${unavailableChains.length ? ` (${unavailableChains.join(", ")})` : ""} \u2014 this snapshot may be incomplete; retry before treating a balance as zero.` : "";
+  const summary = positions.length ? `Total supplied: $${(data.totalSuppliedUsd ?? 0).toFixed(2)} across ${positions.length} position(s).${unavailableNote}` : hasUnavailable ? `No positions returned, but a read failure occurred${unavailableChains.length ? ` on ${unavailableChains.join(", ")}` : ""} \u2014 this is NOT a confirmed empty position; retry.` : "No open Q402 Yield positions for this wallet.";
+  return {
+    content: [
+      { type: "text", text: summary },
+      {
+        type: "text",
+        text: JSON.stringify({
+          walletId: data.walletId ?? walletId ?? null,
+          positions: positions.map((p) => ({
+            ...p,
+            supplyApyPct: Math.round(p.supplyApy * 100 * 100) / 100
+          })),
+          totalSuppliedUsd: data.totalSuppliedUsd ?? null,
+          asOf: data.asOf ?? null,
+          unavailable: hasUnavailable,
+          unavailableChains
+        }, null, 2)
+      }
+    ]
+  };
+}
+
+// src/tools/yield-deposit.ts
+import { hexlify as hexlify2, randomBytes as randomBytes2 } from "ethers";
+import { z as z16 } from "zod";
+var YieldDepositInputSchema = z16.object({
+  chain: z16.enum(["bnb"]).default("bnb").describe("Chain the Aave market lives on. Q402 Yield is BNB-only today \u2014 only 'bnb' is accepted."),
+  token: z16.enum(["USDC", "USDT"]).describe("Stablecoin to supply into Aave. USDC or USDT."),
+  amount: z16.string().regex(/^\d+(\.\d+)?$/, "amount must be a positive decimal string").describe('Human-readable decimal amount to supply, e.g. "100.00".'),
+  walletId: z16.string().optional().describe(
+    "Optional Agent Wallet address to supply from (max 10 per owner). Omit to use Q402_AGENT_WALLET_ADDRESS env, then the owner's default wallet (resolved server-side from the API key)."
+  ),
+  idempotencyKey: z16.string().optional().describe(
+    "Optional durable idempotency key for this logical deposit. When omitted the tool generates a FRESH random key per invocation, so each call executes a distinct deposit (two intentional same-amount deposits both run, and a re-deposit after a withdrawal is NOT replayed). Pass your own STABLE key only when you want retry-safety: re-calling with the same key replays the first result instead of double-supplying."
+  ),
+  confirm: z16.boolean().optional().describe(
+    "MUST be true to actually supply funds. Set this only after the user has explicitly approved this exact deposit (amount, token, chain, wallet) in the conversation. When omitted or false the tool previews the action and does NOT move any funds."
+  )
+});
+var YIELD_DEPOSIT_TOOL = {
+  name: "q402_yield_deposit",
+  description: "WRITE \u2014 MOVES FUNDS. Supplies the Agent Wallet's stablecoin (USDC / USDT) into Aave V3 (Q402 Yield) so it starts earning supply APY. Server-managed Agent Wallet path (Mode C): authenticated by the configured live Multichain API key \u2014 the server holds the encrypted key, signs the Aave supply, and sponsors gas. BNB CHAIN ONLY \u2014 Q402 Yield supports BNB Chain today; ETH / AVAX and other chains are not yet available. \n\nREQUIRES CONFIRMATION \u2014 like q402_pay, this tool refuses to execute unless `confirm: true` is set. Call it FIRST without confirm to get a one-line preview of exactly what will happen (amount, token, chain, wallet); show that to the user, get explicit approval, THEN re-call with confirm:true. Never set confirm:true on the user's behalf without that approval. \n\nSANDBOX BY DEFAULT \u2014 like q402_pay, no funds move unless a live Multichain key (q402_live_*) is configured AND Q402_ENABLE_REAL_PAYMENTS=1. Without both, confirm:true returns a sandbox preview (no on-chain supply) with a setup hint \u2014 confirm:true alone does NOT move real funds. \n\nUse q402_yield_reserves first to show available markets + APY, and q402_yield_positions afterward to confirm the supplied balance.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      chain: {
+        type: "string",
+        enum: ["bnb"],
+        description: "Chain the Aave market lives on. Q402 Yield is BNB-only today \u2014 only 'bnb' is accepted."
+      },
+      token: {
+        type: "string",
+        enum: ["USDC", "USDT"],
+        description: "Stablecoin to supply into Aave. USDC or USDT."
+      },
+      amount: {
+        type: "string",
+        description: 'Human-readable decimal amount to supply, e.g. "100.00".'
+      },
+      walletId: {
+        type: "string",
+        description: "Optional Agent Wallet address to supply from when the owner holds multiple wallets. Defaults to Q402_AGENT_WALLET_ADDRESS env, then the owner's default wallet on the server."
+      },
+      idempotencyKey: {
+        type: "string",
+        description: "Optional durable idempotency key. Omit and the tool generates a FRESH random key per invocation, so every call executes a distinct deposit. Pass your own STABLE key only for opt-in retry-safety \u2014 re-calling with the same key replays the first result instead of double-supplying."
+      },
+      confirm: {
+        type: "boolean",
+        description: "MUST be true to actually supply funds \u2014 set only after the user explicitly approved this exact deposit in chat. Omit (or false) to preview without moving funds."
+      }
+    },
+    required: ["token", "amount"],
+    additionalProperties: false
+  }
+};
+async function runYieldDeposit(input) {
+  if (!(Number(input.amount) > 0)) {
+    return {
+      content: [{
+        type: "text",
+        text: `amount must be greater than zero (got "${input.amount}").`
+      }],
+      isError: true
+    };
+  }
+  const walletId = typeof input.walletId === "string" && input.walletId.length > 0 ? input.walletId.toLowerCase() : CONFIG.walletId ?? void 0;
+  const idempotencyKey = typeof input.idempotencyKey === "string" && input.idempotencyKey.length > 0 ? input.idempotencyKey : hexlify2(randomBytes2(32));
+  if (input.confirm !== true) {
+    const walletDesc = walletId ? `wallet ${walletId}` : "your default Agent Wallet";
+    return {
+      content: [{
+        type: "text",
+        text: `Will supply ${input.amount} ${input.token} into Aave on ${input.chain} from ${walletDesc}. This MOVES FUNDS. Re-call with confirm:true to execute.`
+      }]
+    };
+  }
+  const resolved = resolveApiKey(input.chain, "multichain");
+  if (!resolved.apiKey || !resolved.apiKey.startsWith("q402_live_")) {
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          configured: false,
+          status: "error",
+          setupHint: resolved.sandboxReason ?? "No live Q402 Multichain API key configured. Set Q402_MULTICHAIN_API_KEY to a q402_live_\u2026 key from https://q402.quackai.ai/payment, or run q402_doctor."
+        }, null, 2)
+      }],
+      isError: true
+    };
+  }
+  if (!CONFIG.realPaymentsRequested) {
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          sandbox: true,
+          success: false,
+          status: "sandbox",
+          action: "yield_deposit",
+          chain: input.chain,
+          token: input.token,
+          amount: input.amount,
+          walletId: walletId ?? null,
+          setupHint: "Sandbox mode \u2014 set Q402_ENABLE_REAL_PAYMENTS=1 to fire a real Q402 Yield deposit. No funds moved."
+        }, null, 2)
+      }]
+    };
+  }
+  let res;
+  try {
+    res = await fetch(`${CONFIG.relayBaseUrl}/wallet/agentic/yield/deposit`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        apiKey: resolved.apiKey,
+        chain: input.chain,
+        token: input.token,
+        amount: input.amount,
+        idempotencyKey,
+        ...walletId ? { walletId } : {}
+      }),
+      signal: AbortSignal.timeout(6e4)
+    });
+  } catch (e) {
+    return {
+      content: [{
+        type: "text",
+        text: `Yield deposit failed: ${e instanceof Error ? e.message : String(e)}. Retry in a moment.`
+      }],
+      isError: true
+    };
+  }
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    return {
+      content: [{
+        type: "text",
+        text: `Yield deposit failed (HTTP ${res.status}): ${JSON.stringify(data)}`
+      }],
+      isError: true
+    };
+  }
+  const summary = data.txHash ? `Supplied ${data.amount ?? input.amount} ${data.asset ?? input.token} into ${data.protocol ?? "Aave"} on ${data.chain ?? input.chain}. txHash ${data.txHash}.` : `Yield deposit submitted on ${data.chain ?? input.chain}.`;
+  return {
+    content: [
+      { type: "text", text: summary },
+      { type: "text", text: JSON.stringify(data, null, 2) }
+    ]
+  };
+}
+
+// src/tools/yield-withdraw.ts
+import { hexlify as hexlify3, randomBytes as randomBytes3 } from "ethers";
+import { z as z17 } from "zod";
+var YieldWithdrawInputSchema = z17.object({
+  chain: z17.enum(["bnb"]).default("bnb").describe("Chain the Aave market lives on. Q402 Yield is BNB-only today \u2014 only 'bnb' is accepted."),
+  token: z17.enum(["USDC", "USDT"]).describe("Stablecoin to withdraw from Aave. USDC or USDT."),
+  amount: z17.string().regex(/^(\d+(\.\d+)?|max)$/, 'amount must be a positive decimal string or "max"').describe('Human-readable decimal amount to withdraw, e.g. "100.00", or the literal "max" to withdraw the full position.'),
+  walletId: z17.string().optional().describe(
+    "Optional Agent Wallet address to withdraw to (max 10 per owner). Omit to use Q402_AGENT_WALLET_ADDRESS env, then the owner's default wallet (resolved server-side from the API key)."
+  ),
+  idempotencyKey: z17.string().optional().describe(
+    "Optional durable idempotency key for this logical withdrawal. When omitted the tool generates a FRESH random key per invocation, so each call executes a distinct withdrawal (a re-deposit followed by another `withdraw max` is NOT replayed). Pass your own STABLE key only when you want retry-safety: re-calling with the same key replays the first result instead of double-withdrawing."
+  ),
+  confirm: z17.boolean().optional().describe(
+    "MUST be true to actually withdraw funds. Set this only after the user has explicitly approved this exact withdrawal (amount, token, chain, wallet) in the conversation. When omitted or false the tool previews the action and does NOT move any funds."
+  )
+});
+var YIELD_WITHDRAW_TOOL = {
+  name: "q402_yield_withdraw",
+  description: 'WRITE \u2014 MOVES FUNDS. Withdraws the Agent Wallet\'s supplied stablecoin (USDC / USDT) out of Aave V3 (Q402 Yield) back to the Agent Wallet. Pass amount="max" to withdraw the FULL position. Server-managed Agent Wallet path (Mode C): authenticated by the configured live Multichain API key \u2014 the server holds the encrypted key, signs the Aave withdraw, and sponsors gas. BNB CHAIN ONLY \u2014 Q402 Yield supports BNB Chain today; ETH / AVAX and other chains are not yet available. \n\nREQUIRES CONFIRMATION \u2014 like q402_pay, this tool refuses to execute unless `confirm: true` is set. Call it FIRST without confirm to get a one-line preview of exactly what will happen (amount, token, chain, wallet); show that to the user, get explicit approval, THEN re-call with confirm:true. Never set confirm:true on the user\'s behalf without that approval. \n\nSANDBOX BY DEFAULT \u2014 like q402_pay, no funds move unless a live Multichain key (q402_live_*) is configured AND Q402_ENABLE_REAL_PAYMENTS=1. Without both, confirm:true returns a sandbox preview (no on-chain withdraw) with a setup hint \u2014 confirm:true alone does NOT move real funds. \n\nUse q402_yield_positions first to see the current position size (especially before an amount="max" withdrawal).',
+  inputSchema: {
+    type: "object",
+    properties: {
+      chain: {
+        type: "string",
+        enum: ["bnb"],
+        description: "Chain the Aave market lives on. Q402 Yield is BNB-only today \u2014 only 'bnb' is accepted."
+      },
+      token: {
+        type: "string",
+        enum: ["USDC", "USDT"],
+        description: "Stablecoin to withdraw from Aave. USDC or USDT."
+      },
+      amount: {
+        type: "string",
+        description: 'Human-readable decimal amount to withdraw, e.g. "100.00", or the literal "max" to withdraw the full position.'
+      },
+      walletId: {
+        type: "string",
+        description: "Optional Agent Wallet address to withdraw to when the owner holds multiple wallets. Defaults to Q402_AGENT_WALLET_ADDRESS env, then the owner's default wallet on the server."
+      },
+      idempotencyKey: {
+        type: "string",
+        description: "Optional durable idempotency key. Omit and the tool generates a FRESH random key per invocation, so every call executes a distinct withdrawal. Pass your own STABLE key only for opt-in retry-safety \u2014 re-calling with the same key replays the first result instead of double-withdrawing."
+      },
+      confirm: {
+        type: "boolean",
+        description: "MUST be true to actually withdraw funds \u2014 set only after the user explicitly approved this exact withdrawal in chat. Omit (or false) to preview without moving funds."
+      }
+    },
+    required: ["token", "amount"],
+    additionalProperties: false
+  }
+};
+async function runYieldWithdraw(input) {
+  if (input.amount !== "max" && !(Number(input.amount) > 0)) {
+    return {
+      content: [{
+        type: "text",
+        text: `amount must be greater than zero (got "${input.amount}"), or the literal "max".`
+      }],
+      isError: true
+    };
+  }
+  const walletId = typeof input.walletId === "string" && input.walletId.length > 0 ? input.walletId.toLowerCase() : CONFIG.walletId ?? void 0;
+  const idempotencyKey = typeof input.idempotencyKey === "string" && input.idempotencyKey.length > 0 ? input.idempotencyKey : hexlify3(randomBytes3(32));
+  const amountDesc = input.amount === "max" ? "the FULL position" : `${input.amount} ${input.token}`;
+  if (input.confirm !== true) {
+    const walletDesc = walletId ? `wallet ${walletId}` : "your default Agent Wallet";
+    return {
+      content: [{
+        type: "text",
+        text: `Will withdraw ${amountDesc} from Aave on ${input.chain} back to ${walletDesc}. This MOVES FUNDS. Re-call with confirm:true to execute.`
+      }]
+    };
+  }
+  const resolved = resolveApiKey(input.chain, "multichain");
+  if (!resolved.apiKey || !resolved.apiKey.startsWith("q402_live_")) {
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          configured: false,
+          status: "error",
+          setupHint: resolved.sandboxReason ?? "No live Q402 Multichain API key configured. Set Q402_MULTICHAIN_API_KEY to a q402_live_\u2026 key from https://q402.quackai.ai/payment, or run q402_doctor."
+        }, null, 2)
+      }],
+      isError: true
+    };
+  }
+  if (!CONFIG.realPaymentsRequested) {
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          sandbox: true,
+          success: false,
+          status: "sandbox",
+          action: "yield_withdraw",
+          chain: input.chain,
+          token: input.token,
+          amount: input.amount,
+          walletId: walletId ?? null,
+          setupHint: "Sandbox mode \u2014 set Q402_ENABLE_REAL_PAYMENTS=1 to fire a real Q402 Yield withdrawal. No funds moved."
+        }, null, 2)
+      }]
+    };
+  }
+  let res;
+  try {
+    res = await fetch(`${CONFIG.relayBaseUrl}/wallet/agentic/yield/withdraw`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        apiKey: resolved.apiKey,
+        chain: input.chain,
+        token: input.token,
+        amount: input.amount,
+        idempotencyKey,
+        ...walletId ? { walletId } : {}
+      }),
+      signal: AbortSignal.timeout(6e4)
+    });
+  } catch (e) {
+    return {
+      content: [{
+        type: "text",
+        text: `Yield withdraw failed: ${e instanceof Error ? e.message : String(e)}. Retry in a moment.`
+      }],
+      isError: true
+    };
+  }
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    return {
+      content: [{
+        type: "text",
+        text: `Yield withdraw failed (HTTP ${res.status}): ${JSON.stringify(data)}`
+      }],
+      isError: true
+    };
+  }
+  const summary = data.txHash ? `Withdrew ${data.amount ?? amountDesc} ${data.asset ?? ""}`.trimEnd() + ` from ${data.protocol ?? "Aave"} on ${data.chain ?? input.chain}. txHash ${data.txHash}.` : `Yield withdraw submitted on ${data.chain ?? input.chain}.`;
+  return {
+    content: [
+      { type: "text", text: summary },
+      { type: "text", text: JSON.stringify(data, null, 2) }
+    ]
+  };
+}
+
+// src/tools/recurring-list.ts
+import { z as z18 } from "zod";
+var RecurringListInputSchema = z18.object({
+  walletId: z18.string().optional().describe(
     "Optional lowercased Agent Wallet address to list rules for when the user holds multiple wallets. Omit to use Q402_AGENT_WALLET_ADDRESS env, then the owner's default wallet."
   )
 });
@@ -3422,29 +3893,29 @@ async function runRecurringList(input = {}) {
 }
 
 // src/tools/recurring-create.ts
-import { z as z15 } from "zod";
+import { z as z19 } from "zod";
 var ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
 var AMOUNT_RE = /^\d+(\.\d{1,18})?$/;
-var RecurringCreateInputSchema = z15.object({
-  confirm: z15.literal(true).describe(
+var RecurringCreateInputSchema = z19.object({
+  confirm: z19.literal(true).describe(
     'REQUIRED. Must be literally `true`. Authoring a recurring rule schedules future on-chain payments that the user does not click through one-by-one \u2014 the user has to explicitly say yes BEFORE this is called. Echo back the frequency + recipient + amount + chain + token + cancelWindow you intend to create, get a plain-language confirmation from the user (e.g. "yes, create the schedule"), and ONLY then call this with confirm: true. Mirrors the same guard q402_pay / q402_batch_pay use on one-shot sends.'
   ),
-  frequency: z15.string().min(1).describe(
+  frequency: z19.string().min(1).describe(
     'Cadence string. One of: "hourly:N" (N=1..23), "daily", "weekly:{mon|tue|wed|thu|fri|sat|sun}", "monthly:N" (N=1..31), "monthly:last". Examples: "hourly:1" fires every hour, "weekly:fri" fires every Friday, "monthly:1" fires on the 1st of each month.'
   ),
-  recipient: z15.string().regex(ADDRESS_RE).describe("0x-prefixed 20-byte recipient address. Required."),
-  amount: z15.string().regex(AMOUNT_RE).describe(
+  recipient: z19.string().regex(ADDRESS_RE).describe("0x-prefixed 20-byte recipient address. Required."),
+  amount: z19.string().regex(AMOUNT_RE).describe(
     'Amount per fire, as a decimal string (e.g. "1.5", "0.0001"). Counted in the same unit as `token` (USDC or USDT, both 1:1 USD).'
   ),
-  chain: z15.enum(["bnb", "eth", "avax", "xlayer", "mantle", "injective", "monad", "scroll", "stable", "arbitrum"]).default("bnb").describe(
+  chain: z19.enum(["bnb", "eth", "avax", "xlayer", "mantle", "injective", "monad", "scroll", "stable", "arbitrum"]).default("bnb").describe(
     "Chain to fire the recurring TX on. Defaults to bnb. Recurring requires the paid Multichain subscription on EVERY chain, including bnb \u2014 Trial keys are rejected at create time with MULTICHAIN_REQUIRED. Trial keys can still pay one-shot via q402_pay on BNB."
   ),
-  token: z15.enum(["USDC", "USDT"]).default("USDT").describe("Stablecoin to send. USDC or USDT. Both peg to USD-1."),
-  label: z15.string().max(64).optional().describe("Optional human-readable label (\u226464 chars). Shows up in q402_recurring_list and the dashboard."),
-  cancelWindowHours: z15.number().min(0).optional().describe(
+  token: z19.enum(["USDC", "USDT"]).default("USDT").describe("Stablecoin to send. USDC or USDT. Both peg to USD-1."),
+  label: z19.string().max(64).optional().describe("Optional human-readable label (\u226464 chars). Shows up in q402_recurring_list and the dashboard."),
+  cancelWindowHours: z19.number().min(0).optional().describe(
     "Hours of advance notice before each fire during which the rule can be cancelled. 0 = fire immediately at the next slot, no alert. Capped at the cadence interval (e.g. \u2264 N-0.5h for hourly:N, \u226424 for daily). Defaults to 0."
   ),
-  walletId: z15.string().optional().describe(
+  walletId: z19.string().optional().describe(
     "Optional lowercased Agent Wallet address when the user holds multiple wallets. Defaults to Q402_AGENT_WALLET_ADDRESS env, then the owner's default wallet on the server."
   )
 });
@@ -3573,12 +4044,12 @@ async function runRecurringCreate(input) {
 }
 
 // src/tools/recurring-cancel.ts
-import { z as z16 } from "zod";
-var RecurringCancelInputSchema = z16.object({
-  ruleId: z16.string().min(1).describe(
+import { z as z20 } from "zod";
+var RecurringCancelInputSchema = z20.object({
+  ruleId: z20.string().min(1).describe(
     "Rule id to cancel. Obtain from q402_recurring_list \u2014 each entry's `ruleId` field. Cancelling is immediate."
   ),
-  walletId: z16.string().optional().describe(
+  walletId: z20.string().optional().describe(
     "Optional lowercased Agent Wallet address when the user holds multiple wallets. Defaults to Q402_AGENT_WALLET_ADDRESS env, then the owner's default wallet."
   )
 });
@@ -3666,15 +4137,15 @@ async function runRecurringCancel(input) {
 }
 
 // src/tools/recurring-fires.ts
-import { z as z17 } from "zod";
-var RecurringFiresInputSchema = z17.object({
-  ruleId: z17.string().min(1).describe(
+import { z as z21 } from "zod";
+var RecurringFiresInputSchema = z21.object({
+  ruleId: z21.string().min(1).describe(
     "Rule id whose fire history to fetch. Obtain from q402_recurring_list \u2014 each entry's `ruleId` field."
   ),
-  limit: z17.number().int().min(1).max(50).optional().describe(
+  limit: z21.number().int().min(1).max(50).optional().describe(
     "Max number of fires to return (newest first). Defaults to 50 (the server cap). Pass a smaller number when you only need the most recent few."
   ),
-  walletId: z17.string().optional().describe(
+  walletId: z21.string().optional().describe(
     "Optional lowercased Agent Wallet address when the user holds multiple wallets. Defaults to Q402_AGENT_WALLET_ADDRESS env, then the owner's default wallet."
   )
 });
@@ -3780,12 +4251,12 @@ async function runRecurringFires(input) {
 }
 
 // src/tools/recurring-pause.ts
-import { z as z18 } from "zod";
-var RecurringPauseInputSchema = z18.object({
-  ruleId: z18.string().min(1).describe(
+import { z as z22 } from "zod";
+var RecurringPauseInputSchema = z22.object({
+  ruleId: z22.string().min(1).describe(
     "Rule id to pause. Obtain from q402_recurring_list \u2014 each entry's `ruleId` field. Pausing is immediate and reversible."
   ),
-  walletId: z18.string().optional().describe(
+  walletId: z22.string().optional().describe(
     "Optional lowercased Agent Wallet address when the user holds multiple wallets. Defaults to Q402_AGENT_WALLET_ADDRESS env, then the owner's default wallet."
   )
 });
@@ -3873,12 +4344,12 @@ async function runRecurringPause(input) {
 }
 
 // src/tools/recurring-resume.ts
-import { z as z19 } from "zod";
-var RecurringResumeInputSchema = z19.object({
-  ruleId: z19.string().min(1).describe(
+import { z as z23 } from "zod";
+var RecurringResumeInputSchema = z23.object({
+  ruleId: z23.string().min(1).describe(
     "Rule id to resume. Obtain from q402_recurring_list \u2014 each entry's `ruleId` field. Resume is immediate; nextRunAt advances to the next valid slot."
   ),
-  walletId: z19.string().optional().describe(
+  walletId: z23.string().optional().describe(
     "Optional lowercased Agent Wallet address when the user holds multiple wallets. Defaults to Q402_AGENT_WALLET_ADDRESS env, then the owner's default wallet."
   )
 });
@@ -3966,12 +4437,12 @@ async function runRecurringResume(input) {
 }
 
 // src/tools/recurring-skip-next.ts
-import { z as z20 } from "zod";
-var RecurringSkipNextInputSchema = z20.object({
-  ruleId: z20.string().min(1).describe(
+import { z as z24 } from "zod";
+var RecurringSkipNextInputSchema = z24.object({
+  ruleId: z24.string().min(1).describe(
     "Rule id whose next scheduled fire to skip. Obtain from q402_recurring_list \u2014 each entry's `ruleId` field."
   ),
-  walletId: z20.string().optional().describe(
+  walletId: z24.string().optional().describe(
     "Optional lowercased Agent Wallet address when the user holds multiple wallets. Defaults to Q402_AGENT_WALLET_ADDRESS env, then the owner's default wallet."
   )
 });
@@ -4096,7 +4567,18 @@ async function main() {
       BRIDGE_QUOTE_TOOL,
       BRIDGE_SEND_TOOL,
       BRIDGE_HISTORY_TOOL,
-      BRIDGE_GAS_TANK_TOOL
+      BRIDGE_GAS_TANK_TOOL,
+      // Q402 Yield surface — read-only Aave lending market list + the
+      // Agent Wallet's own positions. No funds move; positions auths via
+      // the live Multichain apiKey (x-api-key header), reserves is public.
+      YIELD_RESERVES_TOOL,
+      YIELD_POSITIONS_TOOL,
+      // Q402 Yield WRITE surface — supply / withdraw the Agent Wallet's
+      // stablecoin to/from Aave V3. MOVES FUNDS, so both gate on confirm:true
+      // (like q402_pay). Mode C: apiKey in the body, server signs the supply
+      // / withdraw with the encrypted key.
+      YIELD_DEPOSIT_TOOL,
+      YIELD_WITHDRAW_TOOL
     ]
   }));
   server.setRequestHandler(CallToolRequestSchema, async (req) => {
@@ -4183,6 +4665,22 @@ async function main() {
           const parsed = BridgeGasTankInputSchema.parse(args ?? {});
           return await runBridgeGasTank(parsed);
         }
+        case "q402_yield_reserves": {
+          const parsed = YieldReservesInputSchema.parse(args ?? {});
+          return await runYieldReserves(parsed);
+        }
+        case "q402_yield_positions": {
+          const parsed = YieldPositionsInputSchema.parse(args ?? {});
+          return await runYieldPositions(parsed);
+        }
+        case "q402_yield_deposit": {
+          const parsed = YieldDepositInputSchema.parse(args ?? {});
+          return await runYieldDeposit(parsed);
+        }
+        case "q402_yield_withdraw": {
+          const parsed = YieldWithdrawInputSchema.parse(args ?? {});
+          return await runYieldWithdraw(parsed);
+        }
         default:
           return {
             isError: true,

package/package.json

@@ -1,75 +1,75 @@
-{
-  "name": "@quackai/q402-mcp",
-  "version": "0.8.17",
-  "description": "MCP server for Q402 — gasless USDC/USDT/RLUSD payments on 10 EVM chains + Chainlink CCIP USDC bridge on the eth/avax/arbitrum triangle, 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",
-    "qs": "^6.15.2",
-    "hono": "^4.12.21"
-  }
-}
+{
+  "name": "@quackai/q402-mcp",
+  "version": "0.8.19",
+  "description": "MCP server for Q402 — gasless USDC/USDT/RLUSD payments on 10 EVM chains + Chainlink CCIP USDC bridge on the eth/avax/arbitrum triangle, 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",
+    "qs": "^6.15.2",
+    "hono": "^4.12.21"
+  }
+}