@quackai/q402-mcp 0.5.1 → 0.5.3

package/README.md

@@ -103,7 +103,7 @@ Then run `codex` and ask the same kind of question. The first call may take a fe
 
 ### Any other MCP client
 
-The server has no client-specific code. If your client speaks stdio MCP, point it at `npx -y @quackai/q402-mcp` and the five tools listed below will appear.
+The server has no client-specific code. If your client speaks stdio MCP, point it at `npx -y @quackai/q402-mcp` and the seven tools listed below will appear.
 
 ---
 
@@ -120,6 +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_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

@@ -775,7 +775,7 @@ function describeSandboxReason(resolvedKey) {
 }
 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. 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. 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.",
   inputSchema: {
     type: "object",
     properties: {
@@ -960,7 +960,7 @@ function describeSandboxReason2(resolvedKey) {
 }
 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. 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 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.`,
   inputSchema: {
     type: "object",
     properties: {
@@ -1249,9 +1249,204 @@ var RECEIPT_TOOL = {
   }
 };
 
+// src/tools/wallet-status.ts
+import { z as z6 } from "zod";
+import { Wallet as Wallet2 } from "ethers";
+var WalletStatusInputSchema = z6.object({});
+async function runWalletStatus() {
+  if (!CONFIG.privateKey) {
+    return {
+      error: "MISSING_PRIVATE_KEY",
+      hint: "Set Q402_PRIVATE_KEY in the MCP environment so this tool can derive the EOA to inspect."
+    };
+  }
+  let address;
+  try {
+    address = new Wallet2(CONFIG.privateKey).address;
+  } catch {
+    return {
+      error: "INVALID_PRIVATE_KEY",
+      hint: "Q402_PRIVATE_KEY is set but does not parse as a valid 32-byte hex private key."
+    };
+  }
+  const url = `${CONFIG.relayBaseUrl.replace(/\/$/, "")}/wallet/delegation-status?address=${address}`;
+  let body;
+  try {
+    const 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)
+    };
+  }
+  const parsed = body;
+  return {
+    address: parsed.address,
+    chains: parsed.chains,
+    summary: parsed.summary
+  };
+}
+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).",
+  inputSchema: {
+    type: "object",
+    properties: {},
+    additionalProperties: false
+  }
+};
+
+// src/tools/clear-delegation.ts
+import { z as z7 } from "zod";
+import { Wallet as Wallet3, JsonRpcProvider as JsonRpcProvider2 } from "ethers";
+var ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+var DEFAULT_RPC2 = {
+  1: "https://ethereum.publicnode.com",
+  56: "https://bsc-dataseed1.binance.org/",
+  143: "https://rpc.monad.xyz",
+  196: "https://rpc.xlayer.tech",
+  988: "https://rpc.stable.xyz",
+  1776: "https://sentry.evm-rpc.injective.network/",
+  5e3: "https://rpc.mantle.xyz",
+  43114: "https://api.avax.network/ext/bc/C/rpc",
+  534352: "https://rpc.scroll.io"
+};
+var ClearDelegationInputSchema = z7.object({
+  chain: z7.enum(["avax", "bnb", "eth", "xlayer", "stable", "mantle", "injective", "monad", "scroll"]).describe("Which Q402 chain to clear the delegation on.")
+});
+async function runClearDelegation(input) {
+  if (!CONFIG.privateKey) {
+    return {
+      ok: false,
+      error: "MISSING_PRIVATE_KEY",
+      hint: "Set Q402_PRIVATE_KEY in the MCP environment \u2014 same key q402_pay uses. The MCP tool signs locally and never sends the key to Q402."
+    };
+  }
+  const cfg = CHAIN_CONFIG[input.chain];
+  if (!cfg) {
+    return { ok: false, error: "INVALID_CHAIN", hint: `Unknown chain: ${input.chain}` };
+  }
+  let wallet;
+  try {
+    const provider = new JsonRpcProvider2(DEFAULT_RPC2[cfg.chainId]);
+    wallet = new Wallet3(CONFIG.privateKey, provider);
+  } catch {
+    return {
+      ok: false,
+      error: "INVALID_PRIVATE_KEY",
+      hint: "Q402_PRIVATE_KEY is set but does not parse as a valid 32-byte hex private key."
+    };
+  }
+  const address = wallet.address;
+  let nonce;
+  try {
+    nonce = await wallet.provider.getTransactionCount(address);
+  } catch (e) {
+    return {
+      ok: false,
+      address,
+      error: "RPC_FAILED",
+      hint: `Could not read transaction count for ${address} on ${input.chain}: ${e instanceof Error ? e.message : String(e)}`
+    };
+  }
+  let auth;
+  try {
+    auth = await wallet.authorize({
+      chainId: cfg.chainId,
+      address: ZERO_ADDRESS,
+      nonce
+    });
+  } catch (e) {
+    return {
+      ok: false,
+      address,
+      error: "SIGN_FAILED",
+      hint: `Local signing failed: ${e instanceof Error ? e.message : String(e)}`
+    };
+  }
+  const url = `${CONFIG.relayBaseUrl.replace(/\/$/, "")}/wallet/clear-delegation`;
+  const body = {
+    chain: input.chain,
+    address,
+    authorization: {
+      chainId: Number(auth.chainId),
+      address: auth.address,
+      nonce: Number(auth.nonce),
+      yParity: auth.signature.yParity,
+      r: auth.signature.r,
+      s: auth.signature.s
+    }
+  };
+  let res;
+  let json;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    json = await res.json();
+  } catch (e) {
+    return {
+      ok: false,
+      address,
+      error: "RELAY_UNREACHABLE",
+      hint: `Could not reach Q402 relay at ${url}: ${e instanceof Error ? e.message : String(e)}`
+    };
+  }
+  const payload = json;
+  if (!res.ok || payload.cleared !== true) {
+    return {
+      ok: false,
+      chain: input.chain,
+      address,
+      txHash: payload.txHash,
+      blockNumber: payload.blockNumber,
+      gasUsed: payload.gasUsed,
+      cleared: payload.cleared ?? false,
+      explorerUrl: payload.explorerUrl,
+      error: payload.error ?? `HTTP ${res.status}`,
+      hint: payload.reason ?? "The sponsored TX did not clear the delegation. If a txHash is present, the broadcast confirmed but the EOA's code is still non-empty (commonly a stale nonce) \u2014 refresh and retry."
+    };
+  }
+  return {
+    ok: true,
+    chain: input.chain,
+    address,
+    txHash: payload.txHash,
+    blockNumber: payload.blockNumber,
+    gasUsed: payload.gasUsed,
+    cleared: true,
+    explorerUrl: payload.explorerUrl
+  };
+}
+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.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      chain: {
+        type: "string",
+        enum: CHAIN_KEYS,
+        description: "Which Q402 chain to clear the delegation on."
+      }
+    },
+    required: ["chain"],
+    additionalProperties: false
+  }
+};
+
 // src/index.ts
 var PACKAGE_NAME = "@quackai/q402-mcp";
-var PACKAGE_VERSION = "0.5.1";
+var PACKAGE_VERSION = "0.5.3";
 function jsonText(value) {
   return { type: "text", text: JSON.stringify(value, null, 2) };
 }
@@ -1261,7 +1456,15 @@ async function main() {
     { capabilities: { tools: {} } }
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: [QUOTE_TOOL, BALANCE_TOOL, PAY_TOOL, BATCH_PAY_TOOL, RECEIPT_TOOL]
+    tools: [
+      QUOTE_TOOL,
+      BALANCE_TOOL,
+      PAY_TOOL,
+      BATCH_PAY_TOOL,
+      RECEIPT_TOOL,
+      WALLET_STATUS_TOOL,
+      CLEAR_DELEGATION_TOOL
+    ]
   }));
   server.setRequestHandler(CallToolRequestSchema, async (req) => {
     const { name, arguments: args } = req.params;
@@ -1287,6 +1490,14 @@ async function main() {
           const parsed = ReceiptInputSchema.parse(args ?? {});
           return { content: [jsonText(await runReceipt(parsed))] };
         }
+        case "q402_wallet_status": {
+          WalletStatusInputSchema.parse(args ?? {});
+          return { content: [jsonText(await runWalletStatus())] };
+        }
+        case "q402_clear_delegation": {
+          const parsed = ClearDelegationInputSchema.parse(args ?? {});
+          return { content: [jsonText(await runClearDelegation(parsed))] };
+        }
         default:
           return {
             isError: true,

package/package.json

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