@quackai/q402-mcp 0.6.5 → 0.7.0

package/README.md

@@ -70,7 +70,7 @@ Q402 supports three signing modes — pick ONE:
 |---|---|---|---|
 | **A** | `Q402_PRIVATE_KEY` | your MetaMask EOA, local | Simplest. After the first payment that EOA shows "Smart account" in MetaMask (EIP-7702 delegation, reversible via `q402_clear_delegation`). |
 | **B** | `Q402_AGENTIC_PRIVATE_KEY` | dedicated Agent Wallet, local | Export the PK from the [dashboard](https://q402.quackai.ai/dashboard) Agent tab → Export. Signs locally just like Mode A, but the signer is your Agent Wallet — MetaMask is never touched. Recommended for AI-agent automation. |
-| **C** | (just the paid API key) | dedicated Agent Wallet, server-managed | The encrypted Agent Wallet key lives on the Q402 server and signs on your behalf. No private key on the client. Optionally set `Q402_AGENT_WALLET_ADDRESS` to pick among multiple wallets (max 10 per owner). Mode C requires a paid Multichain API key — not available on the free Trial. |
+| **C** | (just an API key) | dedicated Agent Wallet, server-managed | The encrypted Agent Wallet key lives on the Q402 server and signs on your behalf. No private key on the client. Optionally set `Q402_AGENT_WALLET_ADDRESS` to pick among multiple wallets (max 10 per owner). **One-shot pays** work with either `Q402_TRIAL_API_KEY` (BNB-only sponsored) or `Q402_MULTICHAIN_API_KEY` (paid, all 9 chains). **Recurring** (`q402_recurring_create`) requires the paid Multichain key on every chain, including BNB. |
 
 When more than one signing mode is set at once, `q402_pay` asks the user which to use rather than picking silently. The picker lives in the `walletMode` argument: `"agentic-server"` (Mode C), `"agentic-local"` (Mode B), `"eoa"` (Mode A).
 
@@ -163,7 +163,7 @@ Three signing paths. Pick one when `q402_doctor` asks on first install. You can
 
 | Mode | Best for | Env to set | Private key in env? |
 |---|---|---|---|
-| **C — Server-managed** (recommended) | Most users. AI agents, automations, anyone who wants payments to "just work". Q402 holds an encrypted Agent Wallet for you; no MetaMask popup, no Smart-account marker. | `Q402_MULTICHAIN_API_KEY` (paid) **or** `Q402_TRIAL_API_KEY` (free BNB) | **No** |
+| **C — Server-managed** (recommended) | Most users. AI agents, automations, anyone who wants payments to "just work". Q402 holds an encrypted Agent Wallet for you; no MetaMask popup, no Smart-account marker. One-shot pays accept either key; **recurring schedules require the paid Multichain key on every chain (BNB included)**. | `Q402_MULTICHAIN_API_KEY` (paid, full surface) **or** `Q402_TRIAL_API_KEY` (free BNB, one-shot only) | **No** |
 | **B — Local Agent Wallet PK** | You want Agent Wallet automation but prefer to hold the PK yourself. Export from the dashboard once. MCP signs locally — key never leaves your machine. Your MetaMask is never touched. | `Q402_AGENTIC_PRIVATE_KEY` + an API key | Yes (Agent Wallet's exported PK) |
 | **A — Your own EOA** | Power users who want their existing MetaMask address to be the on-chain payer. Your EOA signs directly via EIP-7702; the "Smart account" marker after first use is normal + reversible with `q402_clear_delegation`. **Use a fresh wallet.** | `Q402_PRIVATE_KEY` + an API key | Yes (your EOA's PK) |
 

package/dist/index.js

@@ -211,7 +211,7 @@ var isValidPrivateKey = (s) => typeof s === "string" && PRIVATE_KEY_RE.test(s);
 
 // src/version.ts
 var PACKAGE_NAME = "@quackai/q402-mcp";
-var PACKAGE_VERSION = "0.6.5";
+var PACKAGE_VERSION = "0.7.0";
 
 // src/tools/quote.ts
 import { z } from "zod";
@@ -2268,8 +2268,8 @@ async function runDoctor() {
       {
         pick: "C",
         title: "Q402 server signs for me (recommended, simplest)",
-        description: "Q402 holds an encrypted Agent Wallet for you. You only set an API key \u2014 no private key in your env, no MetaMask popup, no Smart-account marker on your wallet. Best for AI agents, automations, and anyone who just wants payments to work.",
-        env: ["Q402_MULTICHAIN_API_KEY (paid)", "or Q402_TRIAL_API_KEY (free BNB)"],
+        description: "Q402 holds an encrypted Agent Wallet for you. You only set an API key \u2014 no private key in your env, no MetaMask popup, no Smart-account marker on your wallet. Best for AI agents, automations, and anyone who just wants payments to work. One-shot pays accept either key below; recurring schedules require the paid Multichain key on every chain (BNB included).",
+        env: ["Q402_MULTICHAIN_API_KEY (paid \u2014 required for recurring)", "or Q402_TRIAL_API_KEY (free BNB, one-shot pays only)"],
         privateKeyRequired: false
       },
       {
@@ -2407,7 +2407,7 @@ async function runDoctor() {
     primary: modes.primary,
     /** Plain-English picker that the AI should echo when the user asks
      *  "which mode do I use?" or "do I need a private key?". */
-    recommendation: recommendedMode === "C" ? "You're configured for Mode C \u2014 Q402's server signs with your Agent Wallet. No private key needed. Simplest path; recommended for most users." : recommendedMode === "B" ? "You're configured for Mode B \u2014 your exported Agent Wallet PK signs locally. Your MetaMask is never touched." : recommendedMode === "A" ? "You're configured for Mode A \u2014 your MetaMask EOA signs directly. EIP-7702 delegates it to Q402 for the call. (If the Smart-account banner in MetaMask is a concern, switch to Mode B or C.)" : "No signing path configured yet. Easiest: set Q402_MULTICHAIN_API_KEY (or Q402_TRIAL_API_KEY for free BNB) and let the server sign \u2014 that's Mode C, no PK needed.",
+    recommendation: recommendedMode === "C" ? "You're configured for Mode C \u2014 Q402's server signs with your Agent Wallet. No private key needed. Simplest path; recommended for most users. (One-shot pays accept either Trial or Multichain keys; recurring schedules require the paid Multichain key on every chain.)" : recommendedMode === "B" ? "You're configured for Mode B \u2014 your exported Agent Wallet PK signs locally. Your MetaMask is never touched." : recommendedMode === "A" ? "You're configured for Mode A \u2014 your MetaMask EOA signs directly. EIP-7702 delegates it to Q402 for the call. (If the Smart-account banner in MetaMask is a concern, switch to Mode B or C.)" : "No signing path configured yet. Easiest: set Q402_MULTICHAIN_API_KEY (paid, recommended) \u2014 covers one-shot pays and recurring schedules across all 9 chains. Q402_TRIAL_API_KEY alone unlocks one-shot pays on BNB only; recurring requires the paid key.",
     /** All three modes documented so the AI can answer "what are my
      *  options?" without re-deriving from envState. */
     catalog: [
@@ -2661,7 +2661,7 @@ var RecurringCreateInputSchema = z11.object({
     '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: z11.enum(["bnb", "eth", "avax", "xlayer", "mantle", "injective", "monad", "scroll", "stable"]).default("bnb").describe(
-    "Chain to fire the recurring TX on. Defaults to bnb (the only chain supported on Trial). Non-bnb requires the paid Multichain subscription."
+    "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: z11.enum(["USDC", "USDT"]).default("USDT").describe("Stablecoin to send. USDC or USDT. Both peg to USD-1."),
   label: z11.string().max(64).optional().describe("Optional human-readable label (\u226464 chars). Shows up in q402_recurring_list and the dashboard."),
@@ -2971,6 +2971,255 @@ async function runRecurringFires(input) {
   }
 }
 
+// src/tools/recurring-pause.ts
+import { z as z14 } from "zod";
+var RecurringPauseInputSchema = z14.object({
+  ruleId: z14.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: z14.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."
+  )
+});
+var RECURRING_PAUSE_TOOL = {
+  name: "q402_recurring_pause",
+  description: `Pause an active recurring-payment rule. Takes a ruleId (from q402_recurring_list). The rule transitions to status "paused" \u2014 the cron skips it on every tick until you resume. Fully reversible via q402_recurring_resume. Use this when the user says 'pause my Friday payout' or 'hold on, stop my recurring rule for now' \u2014 gentler than cancel, no re-authoring required. Authenticated by the paid Multichain API key (same gate as create/cancel). Read q402_recurring_list first to find the matching ruleId.`,
+  inputSchema: {
+    type: "object",
+    properties: {
+      ruleId: {
+        type: "string",
+        description: "Rule id from q402_recurring_list. Required."
+      },
+      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."
+      }
+    },
+    required: ["ruleId"],
+    additionalProperties: false
+  }
+};
+async function runRecurringPause(input) {
+  const base = CONFIG.relayBaseUrl;
+  const dashboardUrl = base.replace(/\/api$/, "") + "/dashboard?tab=agent";
+  if (!CONFIG.apiKey || !CONFIG.apiKey.startsWith("q402_live_")) {
+    return {
+      ok: false,
+      walletId: null,
+      rule: null,
+      error: "API_KEY_REQUIRED",
+      message: "No live Q402 API key configured. Run q402_doctor to set one up.",
+      dashboardUrl
+    };
+  }
+  const explicitWalletId = typeof input.walletId === "string" && input.walletId.length > 0 ? input.walletId.toLowerCase() : CONFIG.walletId;
+  try {
+    const res = await fetch(`${base}/wallet/agentic/recurring-by-key`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        apiKey: CONFIG.apiKey,
+        action: "pause",
+        ruleId: input.ruleId,
+        ...explicitWalletId ? { walletId: explicitWalletId } : {}
+      })
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      return {
+        ok: false,
+        walletId: explicitWalletId,
+        rule: null,
+        error: data.error ?? `HTTP_${res.status}`,
+        message: data.message ?? `Pause failed with HTTP ${res.status}.`,
+        dashboardUrl
+      };
+    }
+    return {
+      ok: true,
+      walletId: data.walletId ?? explicitWalletId,
+      rule: data.rule ?? null,
+      dashboardUrl
+    };
+  } catch (e) {
+    return {
+      ok: false,
+      walletId: explicitWalletId,
+      rule: null,
+      error: "NETWORK_ERROR",
+      message: e instanceof Error ? e.message : String(e),
+      dashboardUrl
+    };
+  }
+}
+
+// src/tools/recurring-resume.ts
+import { z as z15 } from "zod";
+var RecurringResumeInputSchema = z15.object({
+  ruleId: z15.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: z15.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."
+  )
+});
+var RECURRING_RESUME_TOOL = {
+  name: "q402_recurring_resume",
+  description: "Resume a paused or stopped recurring-payment rule. Takes a ruleId (from q402_recurring_list). Supported transitions: paused \u2192 active, paused-by-archive \u2192 active (after restoring the wallet), and fired-cap-exceeded \u2192 active (after raising the per-tx cap or re-subscribing). nextRunAt is advanced to the next valid slot so the rule doesn't immediately fire on a stale schedule. Cancelled rules cannot be resumed \u2014 re-author via q402_recurring_create. Authenticated by the paid Multichain API key.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      ruleId: {
+        type: "string",
+        description: "Rule id from q402_recurring_list. Required."
+      },
+      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."
+      }
+    },
+    required: ["ruleId"],
+    additionalProperties: false
+  }
+};
+async function runRecurringResume(input) {
+  const base = CONFIG.relayBaseUrl;
+  const dashboardUrl = base.replace(/\/api$/, "") + "/dashboard?tab=agent";
+  if (!CONFIG.apiKey || !CONFIG.apiKey.startsWith("q402_live_")) {
+    return {
+      ok: false,
+      walletId: null,
+      rule: null,
+      error: "API_KEY_REQUIRED",
+      message: "No live Q402 API key configured. Run q402_doctor to set one up.",
+      dashboardUrl
+    };
+  }
+  const explicitWalletId = typeof input.walletId === "string" && input.walletId.length > 0 ? input.walletId.toLowerCase() : CONFIG.walletId;
+  try {
+    const res = await fetch(`${base}/wallet/agentic/recurring-by-key`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        apiKey: CONFIG.apiKey,
+        action: "resume",
+        ruleId: input.ruleId,
+        ...explicitWalletId ? { walletId: explicitWalletId } : {}
+      })
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      return {
+        ok: false,
+        walletId: explicitWalletId,
+        rule: null,
+        error: data.error ?? `HTTP_${res.status}`,
+        message: data.message ?? `Resume failed with HTTP ${res.status}.`,
+        dashboardUrl
+      };
+    }
+    return {
+      ok: true,
+      walletId: data.walletId ?? explicitWalletId,
+      rule: data.rule ?? null,
+      dashboardUrl
+    };
+  } catch (e) {
+    return {
+      ok: false,
+      walletId: explicitWalletId,
+      rule: null,
+      error: "NETWORK_ERROR",
+      message: e instanceof Error ? e.message : String(e),
+      dashboardUrl
+    };
+  }
+}
+
+// src/tools/recurring-skip-next.ts
+import { z as z16 } from "zod";
+var RecurringSkipNextInputSchema = z16.object({
+  ruleId: z16.string().min(1).describe(
+    "Rule id whose next scheduled fire to skip. Obtain from q402_recurring_list \u2014 each entry's `ruleId` field."
+  ),
+  walletId: z16.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."
+  )
+});
+var RECURRING_SKIP_NEXT_TOOL = {
+  name: "q402_recurring_skip_next",
+  description: "Skip ONLY the next scheduled fire of a recurring-payment rule. Cadence is preserved \u2014 the fire after the skipped one runs normally. Use this when the user says 'skip the next Friday payout, Alice is on holiday' or 'don't fire this month's subscription, charge it next month'. The rule must be in active status; paused / cancelled rules must be resumed first. Authenticated by the paid Multichain API key. Call q402_recurring_list first to confirm the ruleId and current schedule.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      ruleId: {
+        type: "string",
+        description: "Rule id from q402_recurring_list. Required."
+      },
+      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."
+      }
+    },
+    required: ["ruleId"],
+    additionalProperties: false
+  }
+};
+async function runRecurringSkipNext(input) {
+  const base = CONFIG.relayBaseUrl;
+  const dashboardUrl = base.replace(/\/api$/, "") + "/dashboard?tab=agent";
+  if (!CONFIG.apiKey || !CONFIG.apiKey.startsWith("q402_live_")) {
+    return {
+      ok: false,
+      walletId: null,
+      rule: null,
+      error: "API_KEY_REQUIRED",
+      message: "No live Q402 API key configured. Run q402_doctor to set one up.",
+      dashboardUrl
+    };
+  }
+  const explicitWalletId = typeof input.walletId === "string" && input.walletId.length > 0 ? input.walletId.toLowerCase() : CONFIG.walletId;
+  try {
+    const res = await fetch(`${base}/wallet/agentic/recurring-by-key`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        apiKey: CONFIG.apiKey,
+        action: "skip-next",
+        ruleId: input.ruleId,
+        ...explicitWalletId ? { walletId: explicitWalletId } : {}
+      })
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      return {
+        ok: false,
+        walletId: explicitWalletId,
+        rule: null,
+        error: data.error ?? `HTTP_${res.status}`,
+        message: data.message ?? `Skip-next failed with HTTP ${res.status}.`,
+        dashboardUrl
+      };
+    }
+    return {
+      ok: true,
+      walletId: data.walletId ?? explicitWalletId,
+      rule: data.rule ?? null,
+      dashboardUrl
+    };
+  } catch (e) {
+    return {
+      ok: false,
+      walletId: explicitWalletId,
+      rule: null,
+      error: "NETWORK_ERROR",
+      message: e instanceof Error ? e.message : String(e),
+      dashboardUrl
+    };
+  }
+}
+
 // src/index.ts
 function jsonText(value) {
   return { type: "text", text: JSON.stringify(value, null, 2) };
@@ -2995,6 +3244,9 @@ async function main() {
       RECURRING_LIST_TOOL,
       RECURRING_CREATE_TOOL,
       RECURRING_FIRES_TOOL,
+      RECURRING_PAUSE_TOOL,
+      RECURRING_RESUME_TOOL,
+      RECURRING_SKIP_NEXT_TOOL,
       RECURRING_CANCEL_TOOL,
       CLEAR_DELEGATION_TOOL
     ]
@@ -3055,6 +3307,18 @@ async function main() {
           const parsed = RecurringFiresInputSchema.parse(args ?? {});
           return { content: [jsonText(await runRecurringFires(parsed))] };
         }
+        case "q402_recurring_pause": {
+          const parsed = RecurringPauseInputSchema.parse(args ?? {});
+          return { content: [jsonText(await runRecurringPause(parsed))] };
+        }
+        case "q402_recurring_resume": {
+          const parsed = RecurringResumeInputSchema.parse(args ?? {});
+          return { content: [jsonText(await runRecurringResume(parsed))] };
+        }
+        case "q402_recurring_skip_next": {
+          const parsed = RecurringSkipNextInputSchema.parse(args ?? {});
+          return { content: [jsonText(await runRecurringSkipNext(parsed))] };
+        }
         default:
           return {
             isError: true,

package/package.json

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