@quackai/q402-mcp 0.5.3 → 0.5.5

package/README.md

@@ -9,7 +9,7 @@
 >
 > **Trial-scope policy:** API keys minted under the free-trial program (`plan: "trial"`) are restricted to BNB Chain with USDC/USDT — server-side enforcement, returns `403 TRIAL_BNB_ONLY` otherwise. **Paid API keys see the full 9-chain matrix at all times.**
 
-Claude can now reason about stablecoin payments end to end — quote a transfer across 9 chains, pick the cheapest route, and (optionally) settle the transaction over [Q402](https://q402.quackai.ai)'s EIP-7702 relayer infrastructure. The recipient receives the full amount; the sender pays $0 in gas.
+AI agents — Claude (Desktop / Code), OpenAI Codex CLI, Cursor, Cline, and any other MCP-compatible client — can now reason about stablecoin payments end to end: quote a transfer across 9 chains, pick the cheapest route, and (optionally) settle the transaction over [Q402](https://q402.quackai.ai)'s EIP-7702 relayer infrastructure. The recipient receives the full amount; the sender pays $0 in gas.
 
 ---
 
@@ -120,8 +120,8 @@ The server has no client-specific code. If your client speaks stdio MCP, point i
 | `q402_pay` | API key + private key + flag | Send a gasless payment to a single recipient. **Sandbox by default** — see [Sandbox vs live mode](#sandbox-vs-live-mode). |
 | `q402_batch_pay` | API key + private key + flag | Send a gasless payment to **multiple** recipients in one call on a single chain × token. Trial keys: 5 rows max. Paid keys: 20 rows max. **Auto-routing:** same rule as `q402_pay` (BNB + Trial key set ⇒ Trial, else Multichain). **Ambiguity gate:** 6+ recipient BNB batches with Trial set return `status="ambiguous"` instead of executing — the agent asks the user to pick `keyScope="trial"` (first 5), `"multichain"` (all paid), or two calls (5 free + remainder paid). **Supported chains: avax, bnb, eth, mantle, injective, monad, scroll** (default EIP-7702 mode). xlayer + stable are NOT batchable — use `q402_pay` in a loop for those. Same sandbox gating as `q402_pay`. **Rate-limit note:** the inner `/api/relay` budget (30/min per key) is consumed per row, so a paid 20-row batch leaves ~10 inner slots for the next minute. |
 | `q402_receipt` | none | Look up a Trust Receipt by `rct_…` id and locally verify its ECDSA signature against the relayer EOA. Returns the public settlement record + a `verified` boolean. *receiptId-only today; tx-hash lookup reserved for a future release.* |
-| `q402_wallet_status` | private key | Per-chain EIP-7702 delegation status for the EOA derived from `Q402_PRIVATE_KEY`, across all 9 Q402 chains. Read-only — no on-chain action, no quota consumption. Use to answer "why is my wallet showing Smart account?" and to pick chains for `q402_clear_delegation`. |
-| `q402_clear_delegation` | API key + private key | Clear the EIP-7702 delegation on a single chain for the configured wallet. Local signing with `Q402_PRIVATE_KEY` (key never leaves the user's machine); Q402 broadcasts the type-0x04 TX from a sponsor wallet so the user pays $0 gas. After clearing, `eth_getCode` returns `0x` — the next `q402_pay` on that chain auto-recreates a fresh delegation. Useful when the wallet needs to receive native gas tokens (BNB/ETH/etc.) directly without revert, or to remove the wallet UI's "Smart account" indicator. |
+| `q402_wallet_status` | private key | Per-chain EIP-7702 delegation status for the EOA derived from `Q402_PRIVATE_KEY`, across all 9 Q402 chains. Read-only — no on-chain action, no quota consumption. Useful as the diagnostic step before `q402_clear_delegation`. |
+| `q402_clear_delegation` | private key | Clear the EIP-7702 delegation on a single chain for the configured wallet. Local signing with `Q402_PRIVATE_KEY`; Q402 sponsors the on-chain TX so the user pays $0 gas. After clearing, the next `q402_pay` on that chain recreates a fresh delegation automatically. |
 
 `q402_pay` and `q402_batch_pay` follow a "confirm in chat first" contract: the tool description instructs the model to never call it without explicit user approval of the recipient address(es), amount(s), chain, and token. For batch calls the user must approve the **full batch**, not the individual rows.
 

package/dist/index.js

@@ -748,7 +748,7 @@ async function runPay(input) {
       token: input.token
     });
     guardsApplied.push("mode=sandbox");
-    const setupHint = resolved.sandboxReason ?? describeSandboxReason(resolved.apiKey ?? "");
+    const setupHint = resolved.sandboxReason ?? describeSandboxReason(resolved.apiKey ?? "", resolved.scope);
     return { result: result2, guardsApplied, setupHint };
   }
   const client = new Q402NodeClient({
@@ -765,17 +765,19 @@ async function runPay(input) {
   guardsApplied.push("mode=live");
   return { result, guardsApplied };
 }
-function describeSandboxReason(resolvedKey) {
+function describeSandboxReason(resolvedKey, scope) {
   const missing = [];
   if (!resolvedKey.startsWith("q402_live_")) missing.push("a live API key (must start with q402_live_)");
   if (!CONFIG.privateKey) missing.push("Q402_PRIVATE_KEY");
   if (!CONFIG.realPaymentsRequested) missing.push("Q402_ENABLE_REAL_PAYMENTS=1");
   if (missing.length === 0) return "Sandbox mode active (no env state change needed).";
-  return "Sandbox mode is active because the following env vars are missing or not yet set: " + missing.join(", ") + ". Get a live API key at https://q402.quackai.ai/dashboard.";
+  const tier = scope === "trial" ? "Free Trial" : "Multichain";
+  const url = scope === "trial" ? "https://q402.quackai.ai/event" : "https://q402.quackai.ai/payment";
+  return "Sandbox mode is active because the following env vars are missing or not yet set: " + missing.join(", ") + `. Get a live ${tier} key at ${url}.`;
 }
 var PAY_TOOL = {
   name: "q402_pay",
-  description: "Send a gasless USDC, USDT, or RLUSD payment via Q402. Auto-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, and Q402_ENABLE_REAL_PAYMENTS=1. The recipient receives the full amount; the sender pays $0 in gas. Note: the first q402_pay on a chain creates a persistent EIP-7702 delegation on the sender's EOA (set-code TX, Pectra). Subsequent payments on the same chain reuse it (gas-efficient). To remove the delegation later, call q402_clear_delegation. ALWAYS get explicit user confirmation of the exact recipient address, amount, chain, and token in conversation immediately before calling this tool.",
+  description: "Send a gasless USDC, USDT, or RLUSD payment via Q402. Auto-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, and Q402_ENABLE_REAL_PAYMENTS=1. The recipient receives the full amount; the sender pays $0 in gas. After the first payment on a chain, follow-up payments on the same chain are faster and cheaper (Q402 reuses the wallet's setup); q402_clear_delegation resets it if the user ever asks. ALWAYS get explicit user confirmation of the exact recipient address, amount, chain, and token in conversation immediately before calling this tool.",
   inputSchema: {
     type: "object",
     properties: {
@@ -901,7 +903,7 @@ async function runBatchPay(input) {
       (r) => sandboxPay(chain, { to: r.to, amount: r.amount, token: input.token })
     );
     guardsApplied.push("mode=sandbox");
-    const reason = resolved.sandboxReason ?? describeSandboxReason2(resolved.apiKey ?? "");
+    const reason = resolved.sandboxReason ?? describeSandboxReason2(resolved.apiKey ?? "", resolved.scope);
     return {
       mode: "sandbox",
       status: "sandbox",
@@ -950,17 +952,19 @@ async function runBatchPay(input) {
     throw err;
   }
 }
-function describeSandboxReason2(resolvedKey) {
+function describeSandboxReason2(resolvedKey, scope) {
   const missing = [];
   if (!resolvedKey.startsWith("q402_live_")) missing.push("a live API key (must start with q402_live_)");
   if (!CONFIG.privateKey) missing.push("Q402_PRIVATE_KEY");
   if (!CONFIG.realPaymentsRequested) missing.push("Q402_ENABLE_REAL_PAYMENTS=1");
   if (missing.length === 0) return "Sandbox mode active (no env state change needed).";
-  return "Sandbox mode is active because the following env vars are missing or not yet set: " + missing.join(", ") + ". Get a live API key at https://q402.quackai.ai/dashboard.";
+  const tier = scope === "trial" ? "Free Trial" : "Multichain";
+  const url = scope === "trial" ? "https://q402.quackai.ai/event" : "https://q402.quackai.ai/payment";
+  return "Sandbox mode is active because the following env vars are missing or not yet set: " + missing.join(", ") + `. Get a live ${tier} key at ${url}.`;
 }
 var BATCH_PAY_TOOL = {
   name: "q402_batch_pay",
-  description: `Send gasless payments to MULTIPLE recipients on a single chain \xD7 token in one call. Auto-routing follows the same rule as q402_pay: chain='bnb' + Q402_TRIAL_API_KEY set \u2192 Trial; else Multichain. Trial keys: max ${RECIPIENT_LIMIT_TRIAL} recipients per call, BNB Chain + USDC/USDT only. Multichain keys: max ${RECIPIENT_LIMIT_PAID} recipients per call across 7 EIP-7702 default chains (avax, bnb, eth, mantle, injective, monad, scroll). xlayer + stable are NOT batchable \u2014 use q402_pay in a loop. AMBIGUITY GATE: when auto would land on Trial AND recipients.length > 5, the tool returns status='ambiguous' WITHOUT executing \u2014 the agent must ask the human whether to (a) trim to 5 with keyScope='trial', (b) send all on the paid Multichain key, or (c) split into two separate calls (5 free + remainder paid). Re-invoke with explicit keyScope after the choice. SANDBOX BY DEFAULT \u2014 real on-chain TX only when the resolved key is live (q402_live_*), Q402_PRIVATE_KEY is set, and Q402_ENABLE_REAL_PAYMENTS=1. Every recipient receives the full amount; the sender pays $0 in gas for the entire batch. Note: same EIP-7702 delegation behaviour as q402_pay \u2014 the first call on a chain creates a persistent set-code delegation on the sender's EOA, reused by subsequent calls. Use q402_clear_delegation to remove. ALWAYS get explicit user confirmation of the complete recipient + amount list, chain, and token in conversation immediately before calling this tool \u2014 the user must approve the full batch, not the individual rows.`,
+  description: `Send gasless payments to MULTIPLE recipients on a single chain \xD7 token in one call. Auto-routing follows the same rule as q402_pay: chain='bnb' + Q402_TRIAL_API_KEY set \u2192 Trial; else Multichain. Trial keys: max ${RECIPIENT_LIMIT_TRIAL} recipients per call, BNB Chain + USDC/USDT only. Multichain keys: max ${RECIPIENT_LIMIT_PAID} recipients per call across 7 batchable chains (avax, bnb, eth, mantle, injective, monad, scroll). xlayer + stable are NOT batchable \u2014 use q402_pay in a loop. AMBIGUITY GATE: when auto would land on Trial AND recipients.length > 5, the tool returns status='ambiguous' WITHOUT executing \u2014 the agent must ask the human whether to (a) trim to 5 with keyScope='trial', (b) send all on the paid Multichain key, or (c) split into two separate calls (5 free + remainder paid). Re-invoke with explicit keyScope after the choice. SANDBOX BY DEFAULT \u2014 real on-chain TX only when the resolved key is live (q402_live_*), Q402_PRIVATE_KEY is set, and Q402_ENABLE_REAL_PAYMENTS=1. Every recipient receives the full amount; the sender pays $0 in gas for the entire batch. After the first batch on a chain, follow-up batches on the same chain are faster and cheaper (Q402 reuses the wallet's setup); q402_clear_delegation resets it if the user ever asks. ALWAYS get explicit user confirmation of the complete recipient + amount list, chain, and token in conversation immediately before calling this tool \u2014 the user must approve the full batch, not the individual rows.`,
   inputSchema: {
     type: "object",
     properties: {
@@ -1271,19 +1275,24 @@ async function runWalletStatus() {
   }
   const url = `${CONFIG.relayBaseUrl.replace(/\/$/, "")}/wallet/delegation-status?address=${address}`;
   let body;
+  let res;
   try {
-    const res = await fetch(url);
+    res = await fetch(url);
     body = await res.json();
-    if (!res.ok) {
-      return {
-        address,
-        error: typeof body === "object" && body && "error" in body ? String(body.error) : `HTTP ${res.status}`
-      };
-    }
   } catch (e) {
     return {
       address,
-      error: e instanceof Error ? e.message : String(e)
+      error: "RELAY_UNREACHABLE",
+      hint: `Could not reach Q402 at ${url}: ${e instanceof Error ? e.message : String(e)}`
+    };
+  }
+  if (!res.ok) {
+    const errBody = body;
+    return {
+      address,
+      error: errBody.error ?? `HTTP ${res.status}`,
+      hint: errBody.hint ?? errBody.reason,
+      retryAfterSec: errBody.retryAfterSec
     };
   }
   const parsed = body;
@@ -1295,7 +1304,7 @@ async function runWalletStatus() {
 }
 var WALLET_STATUS_TOOL = {
   name: "q402_wallet_status",
-  description: "Report the EIP-7702 delegation status of your Q402 wallet (the EOA derived from Q402_PRIVATE_KEY) across all 9 Q402-supported chains. Returns per-chain { delegated, impl } and a one-line summary. Read-only \u2014 no signing, no on-chain TX, no quota consumption. Use this before q402_clear_delegation to figure out which chains need a cleanup, or when answering 'why is my wallet showing Smart account?' Requires Q402_PRIVATE_KEY in env (same as q402_pay).",
+  description: "Report the EIP-7702 delegation status of your Q402 wallet (the EOA derived from Q402_PRIVATE_KEY) across all 9 Q402-supported chains. Returns per-chain { delegated, impl } and a one-line summary. Read-only \u2014 no signing, no on-chain TX, no quota consumption. Pair with q402_clear_delegation when the user wants to reset a specific chain. Requires Q402_PRIVATE_KEY in env (same as q402_pay).",
   inputSchema: {
     type: "object",
     properties: {},
@@ -1429,7 +1438,7 @@ async function runClearDelegation(input) {
 }
 var CLEAR_DELEGATION_TOOL = {
   name: "q402_clear_delegation",
-  description: "Clear the EIP-7702 delegation on a Q402 chain for the configured wallet. After your first q402_pay on a chain, Q402 delegates your EOA to a vetted implementation contract (Pectra set-code transaction) so subsequent payments are gasless without redoing the authorization each time. The delegation persists until explicitly cleared. Call this when: (a) the user wants to receive native gas tokens (BNB/ ETH/etc.) directly to their EOA without revert, (b) the wallet UI is showing a 'Smart account' indicator the user wants to remove, or (c) the user explicitly asks to 'clean up' or 'reset' the delegation. Do NOT call this immediately before another q402_pay on the same chain \u2014 the next payment would just re-create the delegation, wasting one TX. Pair with q402_wallet_status first to see which chains actually have an active delegation. Signing happens locally with Q402_PRIVATE_KEY; the signed authorization is POSTed to Q402 which broadcasts the type-0x04 TX from a sponsor wallet \u2014 the user pays zero gas. Requires Q402_PRIVATE_KEY in env.",
+  description: "Clear the EIP-7702 delegation on a Q402 chain for the configured wallet. Call this only when the user explicitly asks to reset or clean up their Q402 wallet on a chain \u2014 the next q402_pay will recreate the delegation automatically, so calling clear right before another payment just wastes a TX. Pair with q402_wallet_status first to see which chains actually have an active delegation. Signing happens locally with Q402_PRIVATE_KEY (same key q402_pay uses); Q402 sponsors the on-chain TX so the user pays zero gas.",
   inputSchema: {
     type: "object",
     properties: {
@@ -1446,7 +1455,7 @@ var CLEAR_DELEGATION_TOOL = {
 
 // src/index.ts
 var PACKAGE_NAME = "@quackai/q402-mcp";
-var PACKAGE_VERSION = "0.5.3";
+var PACKAGE_VERSION = "0.5.5";
 function jsonText(value) {
   return { type: "text", text: JSON.stringify(value, null, 2) };
 }

package/package.json

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