@quackai/q402-mcp 0.4.9 → 0.5.0

package/README.md

@@ -1,15 +1,15 @@
 # @quackai/q402-mcp
 
-> MCP server for Q402 — gasless USDC, USDT, and RLUSD payments across 8 EVM chains, callable from Claude (Desktop / Code), OpenAI Codex CLI, and any other Model Context Protocol client.
+> 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.
 
 [![npm](https://img.shields.io/npm/v/@quackai/q402-mcp.svg)](https://www.npmjs.com/package/@quackai/q402-mcp)
 [![license](https://img.shields.io/npm/l/@quackai/q402-mcp.svg)](./LICENSE)
 
 > **🎟️ Free trial available (2026-05-19 → 2026-06-30)** — 2,000 gasless transactions on BNB Chain (USDC + USDT), 30-day window, no card. One wallet signature: <https://q402.quackai.ai>.
 >
-> **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 8-chain matrix at all times.**
+> **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 8 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.
+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.
 
 ---
 
@@ -38,7 +38,7 @@ Or edit `claude_desktop_config.json` directly:
 
 Restart Claude Desktop and ask:
 
-> *"Compare gas costs to send 50 USDC to vitalik.eth across all 8 Q402 chains."*
+> *"Compare gas costs to send 50 USDC to vitalik.eth across all 9 Q402 chains."*
 
 ### OpenAI Codex CLI
 
@@ -79,7 +79,7 @@ env = {
   # Two-key model: set whichever applies — both is best.
   # Auto-routing rule (same for q402_pay AND q402_batch_pay):
   #   chain="bnb" + Q402_TRIAL_API_KEY set  → Trial (free sponsored)
-  #   anything else                          → Multichain (paid 8-chain)
+  #   anything else                          → Multichain (paid 9-chain)
   # Batch ambiguity: when auto would land on Trial AND recipients.length > 5,
   # q402_batch_pay returns status="ambiguous" WITHOUT executing so the agent
   # can ask the user — pass keyScope="trial" (first 5), "multichain" (all
@@ -88,7 +88,7 @@ env = {
   # carries the scope, not the key string. Get the values from the
   # dashboard (each key has its own copy button per view).
   Q402_TRIAL_API_KEY        = "q402_live_...",         # BNB-only sponsored (from /event)
-  Q402_MULTICHAIN_API_KEY   = "q402_live_...",         # paid 8-chain (from /payment)
+  Q402_MULTICHAIN_API_KEY   = "q402_live_...",         # paid 9-chain (from /payment)
   # Legacy fallback — used if neither scoped key above is set.
   Q402_API_KEY              = "q402_live_...",
   Q402_PRIVATE_KEY          = "0xabc...",
@@ -118,7 +118,7 @@ The server has no client-specific code. If your client speaks stdio MCP, point i
 | `q402_quote` | none | Compare gas cost and supported tokens across chains. Read-only. |
 | `q402_balance` | API key | Verify the API key and report its plan tier + remaining quota credits (live vs sandbox). |
 | `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** (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_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_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.
@@ -142,12 +142,12 @@ To enable real on-chain transactions, the resolved API key must be live (`q402_l
 # Two-key model — set whichever applies. Both is best.
 # Auto-routing (same for q402_pay AND q402_batch_pay):
 #   chain="bnb" + Q402_TRIAL_API_KEY set  → Trial (free sponsored)
-#   anything else                          → Multichain (paid 8-chain)
+#   anything else                          → Multichain (paid 9-chain)
 # Batch ambiguity: 6+ recipient BNB batch with Trial set returns
 #   status="ambiguous" instead of executing — agent asks user to pick.
 # Override per call with keyScope: "auto" | "trial" | "multichain".
 Q402_TRIAL_API_KEY=q402_live_...           # BNB-only sponsored Trial key (from /event)
-Q402_MULTICHAIN_API_KEY=q402_live_...      # paid 8-chain key (per-chain Gas Tank)
+Q402_MULTICHAIN_API_KEY=q402_live_...      # paid 9-chain key (per-chain Gas Tank)
 
 # Legacy fallback. Used for both scopes when the two above are unset —
 # single-env setups (only Q402_API_KEY set) keep working unchanged.
@@ -181,7 +181,7 @@ Combined with the `confirm: true` argument the tool requires, this means the mod
 | Env var | Required for | Notes |
 |---|---|---|
 | `Q402_TRIAL_API_KEY` | live-pay (BNB) | BNB-only sponsored Trial key. Free at https://q402.quackai.ai/event. Auto-routed for `chain="bnb"` in both `q402_pay` and `q402_batch_pay` (≤5 recipients) when set. 6+ recipient BNB batches return `status="ambiguous"` so the agent can ask the user how to split. |
-| `Q402_MULTICHAIN_API_KEY` | live-pay (8-chain) | Paid 8-chain key. Get one at https://q402.quackai.ai/payment. Auto-routed for non-BNB chains AND for BNB when no Trial key is set. Cap: 20 recipients per batch. |
+| `Q402_MULTICHAIN_API_KEY` | live-pay (9-chain) | Paid 9-chain key. Get one at https://q402.quackai.ai/payment. Auto-routed for non-BNB chains AND for BNB when no Trial key is set. Cap: 20 recipients per batch. |
 | `Q402_API_KEY` | legacy fallback | Single-env legacy path. Used for both scopes when the two above are unset. Keep set if you only have one key. |
 | `Q402_PRIVATE_KEY` | live-pay | Signer for the payer EOA. **Never share. Never paste in chat.** |
 | `Q402_ENABLE_REAL_PAYMENTS` | live-pay | Set to `1` to opt in. Any other value (or unset) → sandbox. |
@@ -203,6 +203,7 @@ Combined with the `confirm: true` argument the tool requires, this means the mod
 | Mantle | 5000 | USDC, USDT0 | LayerZero OFT USDT0 since 2025-11-27. |
 | Injective EVM | 1776 | USDT only | Native USDC via Circle CCTP announced for Q2 2026. |
 | Monad | 143 | USDC, USDT0 | Native Circle USDC (CCTP V2) + USDT0 (LayerZero OFT). |
+| Scroll | 534352 | USDC, USDT | zkEVM L2 — EIP-7702 live since the Euclid Phase 2 upgrade (2025-04-22). |
 
 ---
 

package/dist/index.js

@@ -109,7 +109,8 @@ var CHAIN_KEYS = [
   "stable",
   "mantle",
   "injective",
-  "monad"
+  "monad",
+  "scroll"
 ];
 var CHAIN_CONFIG = {
   avax: {
@@ -226,6 +227,22 @@ var CHAIN_CONFIG = {
     usdt: { address: "0xe7cd86e13AC4309349F30B3435a9d337750fC82D", decimals: 6 },
     supportedTokens: ["USDC", "USDT"],
     approxGasCostUsd: 2e-3
+  },
+  scroll: {
+    key: "scroll",
+    name: "Scroll",
+    chainId: 534352,
+    domainName: "Q402 Scroll",
+    implContract: "0x2fb2B2D110b6c5664e701666B3741240242bf350",
+    gasToken: "ETH",
+    explorer: "https://scrollscan.com",
+    // Native Circle USDC + canonical Tether on Scroll mainnet (addresses
+    // confirmed with Scroll team during integration handshake).
+    usdc: { address: "0x06eFdBFf2a14a7c8E15944D1F4A48F9F95F663A4", decimals: 6 },
+    usdt: { address: "0xf55BEC9cafDbE8730f096Aa55dad6D22d44099Df", decimals: 6 },
+    supportedTokens: ["USDC", "USDT"],
+    approxGasCostUsd: 1e-3,
+    note: "zkEVM L2 \u2014 EIP-7702 live since the Euclid Phase 2 upgrade (2025-04-22). Data-availability cost dominates per-tx gas."
   }
 };
 var BNB_FOCUS_MODE = false;
@@ -263,8 +280,8 @@ var QuoteInputSchema = z.object({
   token: z.enum(["USDC", "USDT", "RLUSD"]).optional().describe(
     'Optional token filter. USDC / USDT are supported on most chains; RLUSD (Ripple USD, NY DFS regulated, decimals 18) is Ethereum-only \u2014 passing RLUSD here narrows the quote to chain="eth".'
   ),
-  chain: z.enum(["avax", "bnb", "eth", "xlayer", "stable", "mantle", "injective", "monad"]).optional().describe(
-    "Optional chain filter. When omitted, all 8 chains are compared and ranked by gas cost."
+  chain: z.enum(["avax", "bnb", "eth", "xlayer", "stable", "mantle", "injective", "monad", "scroll"]).optional().describe(
+    "Optional chain filter. When omitted, all 9 chains are compared and ranked by gas cost."
   )
 });
 function quoteForChain(cfg) {
@@ -305,7 +322,7 @@ function runQuote(input) {
 }
 var QUOTE_TOOL = {
   name: "q402_quote",
-  description: "Compare gas costs and supported tokens across the 8 chains Q402 relays for (avax, bnb, eth, xlayer, stable, mantle, injective, monad). Returns the full chain \xD7 token matrix unconditionally \u2014 this tool does not read any API key, so it can't filter by trial vs multichain scope. When the caller intends to settle with a Trial API Key, treat any non-BNB row as informational only (q402_pay will return 403 TRIAL_BNB_ONLY for those). Includes RLUSD on Ethereum and Injective USDT-only. Read-only \u2014 no API key needed, no funds move. Use this before q402_pay so the user can see what's available and pick a chain.",
+  description: "Compare gas costs and supported tokens across the 9 chains Q402 relays for (avax, bnb, eth, xlayer, stable, mantle, injective, monad, scroll). Returns the full chain \xD7 token matrix unconditionally \u2014 this tool does not read any API key, so it can't filter by trial vs multichain scope. When the caller intends to settle with a Trial API Key, treat any non-BNB row as informational only (q402_pay will return 403 TRIAL_BNB_ONLY for those). Includes RLUSD on Ethereum and Injective USDT-only. Read-only \u2014 no API key needed, no funds move. Use this before q402_pay so the user can see what's available and pick a chain.",
   // Plain JSON schema mirroring the Zod schema above; MCP servers receive parameters as JSON.
   inputSchema: {
     type: "object",
@@ -351,7 +368,8 @@ var DEFAULT_RPC = {
   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"
+  43114: "https://api.avax.network/ext/bc/C/rpc",
+  534352: "https://rpc.scroll.io"
 };
 var TRANSFER_AUTH_TYPES = {
   TransferAuthorization: [
@@ -546,7 +564,7 @@ var Q402NodeClient = class _Q402NodeClient {
     }
     if (chain.key === "xlayer" || chain.key === "stable") {
       throw new Error(
-        `batchPay does not yet support chain "${chain.key}". Supported batch chains: avax, bnb, eth, mantle, injective, monad (default EIP-7702 mode). For "${chain.key}" use pay() in a client-side loop.`
+        `batchPay does not yet support chain "${chain.key}". Supported batch chains: avax, bnb, eth, mantle, injective, monad, scroll (default EIP-7702 mode). For "${chain.key}" use pay() in a client-side loop.`
       );
     }
     const rpcUrl = this.opts.rpcUrl ?? DEFAULT_RPC[chain.chainId];
@@ -672,7 +690,7 @@ function sandboxPay(chain, input) {
 
 // src/tools/pay.ts
 var PayInputSchema = z2.object({
-  chain: z2.enum(["avax", "bnb", "eth", "xlayer", "stable", "mantle", "injective", "monad"]),
+  chain: z2.enum(["avax", "bnb", "eth", "xlayer", "stable", "mantle", "injective", "monad", "scroll"]),
   to: z2.string().refine(isAddress2, "to must be a valid 0x-prefixed EVM address").describe("Recipient EVM address (0x + 40 hex)."),
   amount: z2.string().regex(/^\d+(\.\d+)?$/, "amount must be a positive decimal string").describe('Human-readable decimal amount, e.g. "5.00".'),
   token: z2.enum(["USDC", "USDT", "RLUSD"]).describe(
@@ -757,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 8-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 \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. 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: {
@@ -802,7 +820,7 @@ var RECIPIENT_LIMIT_TRIAL = 5;
 var RECIPIENT_LIMIT_PAID = 20;
 var CLIENT_RECIPIENT_CAP = RECIPIENT_LIMIT_PAID;
 var BatchPayInputSchema = z3.object({
-  chain: z3.enum(["avax", "bnb", "eth", "mantle", "injective", "monad"]),
+  chain: z3.enum(["avax", "bnb", "eth", "mantle", "injective", "monad", "scroll"]),
   token: z3.enum(["USDC", "USDT", "RLUSD"]).describe(
     "Stablecoin symbol. USDC / USDT supported on most chains (Injective is USDT-only). RLUSD (Ripple USD, NY DFS regulated, decimals 18) is Ethereum-only. The same token applies to every recipient in the batch."
   ),
@@ -942,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 6 EIP-7702 default chains (avax, bnb, eth, mantle, injective, monad). 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. 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: {
@@ -951,7 +969,7 @@ var BATCH_PAY_TOOL = {
         // Narrower than the full chain set — xlayer and stable are NOT batchable
         // (chain-specific nonce field shapes). Use q402_pay in a loop for
         // those chains.
-        enum: ["avax", "bnb", "eth", "mantle", "injective", "monad"],
+        enum: ["avax", "bnb", "eth", "mantle", "injective", "monad", "scroll"],
         description: "Target chain. Applies to every recipient in the batch. xlayer + stable are NOT supported here \u2014 use q402_pay in a loop."
       },
       token: {
@@ -1233,7 +1251,7 @@ var RECEIPT_TOOL = {
 
 // src/index.ts
 var PACKAGE_NAME = "@quackai/q402-mcp";
-var PACKAGE_VERSION = "0.4.9";
+var PACKAGE_VERSION = "0.5.0";
 function jsonText(value) {
   return { type: "text", text: JSON.stringify(value, null, 2) };
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@quackai/q402-mcp",
-  "version": "0.4.9",
-  "description": "MCP server for Q402 — gasless USDC, USDT, and RLUSD payments across 8 EVM chains, callable from Claude (Desktop / Code), OpenAI Codex CLI, and any other Model Context Protocol client.",
+  "version": "0.5.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": [
     "mcp",