@quackai/q402-mcp 0.3.7 → 0.3.9

package/README.md

@@ -5,9 +5,9 @@
 [![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-13 → 2026-05-20)** — 2,000 gasless transactions on BNB Chain (USDC + USDT), 30-day window, no card. One wallet signature: <https://q402.quackai.ai>.
+> **🎟️ 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>.
 >
-> **BNB-focus sprint window:** while the sprint is on, `q402_pay` accepts `chain: "bnb"` with `token: "USDC"` or `"USDT"` only; the other 6 chains and RLUSD return after the sprint. `q402_quote` is narrowed to BNB Chain accordingly. Source-of-truth flag: [`feature-flags.ts`](https://github.com/bitgett/Q402-Institutional/blob/feat/bnb-focus-sprint/app/lib/feature-flags.ts).
+> **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 7-chain matrix at all times.**
 
 Claude can now reason about stablecoin payments end to end — quote a transfer across 7 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.
 
@@ -46,10 +46,11 @@ You'll get a ranked breakdown immediately — no API key, no signup, no funds at
 |---|---|---|
 | `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. **Sandbox by default** — see [Sandbox vs live mode](#sandbox-vs-live-mode). |
+| `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. Same sandbox gating as `q402_pay`. |
 | `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` follows a "confirm in chat first" contract: the tool description instructs the model to never call it without explicit user approval of the recipient address, amount, chain, and token.
+`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.
 
 `q402_receipt` is the natural follow-up: after `q402_pay` returns a `receiptUrl`, hand the agent the `rct_…` id and ask *"verify this receipt"* — the tool re-runs the same canonical-JSON + EIP-191 recovery the receipt page does in the browser, so the verification doesn't depend on trusting any UI. Example prompts that work today:
 

package/dist/index.js

@@ -431,6 +431,116 @@ var Q402NodeClient = class _Q402NodeClient {
     data.explorerUrl = _Q402NodeClient.explorerUrl(chain, data.txHash);
     return data;
   }
+  /**
+   * Multi-recipient settlement on a single chain + token. Trial keys can
+   * fan out to at most 5 recipients per call; paid keys up to 20. The
+   * server enforces the cap and rejects oversized batches with
+   * `BATCH_TOO_LARGE`.
+   *
+   * Each recipient is independently authorised: one EIP-712
+   * TransferAuthorization witness + one EIP-7702 authorization tuple
+   * per row. The authorization nonces are issued sequentially starting
+   * from the EOA's current on-chain nonce, so the EVM applies them
+   * cleanly in batch order. Execution is sequential server-side; the
+   * first transfer must succeed (it installs / re-confirms the
+   * delegation), after which the remaining transfers are surfaced in
+   * the result array even if individual ones fail.
+   */
+  async batchPay(inputs) {
+    if (!Array.isArray(inputs) || inputs.length === 0) {
+      throw new Error("batchPay requires at least one recipient");
+    }
+    const { chain, relayBaseUrl, apiKey, privateKey } = this.opts;
+    for (let i = 0; i < inputs.length; i++) {
+      const inp = inputs[i];
+      const tokenCfg = tokenFor(chain, inp.token);
+      if (chain.supportedTokens && !chain.supportedTokens.includes(inp.token)) {
+        throw new Error(
+          `recipient[${i}]: token ${inp.token} is not supported on chain ${chain.key}. Supported: ${chain.supportedTokens.join(", ")}.`
+        );
+      }
+      try {
+        toRawAmount(inp.amount, tokenCfg.decimals);
+      } catch (e) {
+        throw new Error(
+          `recipient[${i}]: ${e instanceof Error ? e.message : String(e)}`
+        );
+      }
+    }
+    const rpcUrl = this.opts.rpcUrl ?? DEFAULT_RPC[chain.chainId];
+    if (!rpcUrl) {
+      throw new Error(
+        `no RPC URL configured for chain ${chain.key} (chainId ${chain.chainId})`
+      );
+    }
+    const provider = new JsonRpcProvider(rpcUrl);
+    const wallet = new Wallet(privateKey, provider);
+    const owner = await wallet.getAddress();
+    const facilitator = await this.fetchFacilitator();
+    const baseAuthNonce = await provider.getTransactionCount(owner);
+    const deadline = Math.floor(Date.now() / 1e3) + 600;
+    const recipients = [];
+    for (let i = 0; i < inputs.length; i++) {
+      const inp = inputs[i];
+      const tokenCfg = tokenFor(chain, inp.token);
+      const amountRaw = toRawAmount(inp.amount, tokenCfg.decimals);
+      const paymentNonce = toBigInt(randomBytes(32));
+      const witnessSig = await wallet.signTypedData(
+        {
+          name: chain.domainName,
+          version: "1",
+          chainId: chain.chainId,
+          verifyingContract: owner
+        },
+        TRANSFER_AUTH_TYPES,
+        {
+          owner,
+          facilitator,
+          token: tokenCfg.address,
+          recipient: inp.to,
+          amount: BigInt(amountRaw),
+          nonce: paymentNonce,
+          deadline: BigInt(deadline)
+        }
+      );
+      const authorization = await signAuthorization(wallet, {
+        chainId: chain.chainId,
+        address: chain.implContract,
+        nonce: baseAuthNonce + i
+      });
+      const baseRow = {
+        from: owner,
+        to: inp.to,
+        amount: amountRaw,
+        deadline,
+        witnessSig,
+        authorization
+      };
+      const row = chain.key === "xlayer" ? { ...baseRow, xlayerNonce: paymentNonce.toString() } : chain.key === "stable" ? { ...baseRow, stableNonce: paymentNonce.toString() } : { ...baseRow, nonce: paymentNonce.toString() };
+      recipients.push(row);
+    }
+    const resp = await fetch(`${relayBaseUrl.replace(/\/$/, "")}/relay/batch`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        apiKey,
+        chain: chain.key,
+        token: inputs[0].token,
+        // all recipients must share token; pre-validated above
+        facilitator,
+        recipients
+      })
+    });
+    const data = await resp.json();
+    if (!resp.ok) {
+      throw new Error(data.error ?? `relay/batch failed (HTTP ${resp.status})`);
+    }
+    data.results = data.results.map((r) => ({
+      ...r,
+      ...r.success && r.txHash ? { explorerUrl: _Q402NodeClient.explorerUrl(chain, r.txHash) } : {}
+    }));
+    return data;
+  }
 };
 function sandboxPay(chain, input) {
   const tokenCfg = tokenFor(chain, input.token);
@@ -561,9 +671,154 @@ var PAY_TOOL = {
   }
 };
 
-// src/tools/balance.ts
+// src/tools/batch-pay.ts
+import { isAddress as isAddress3 } from "ethers";
 import { z as z3 } from "zod";
-var BalanceInputSchema = z3.object({});
+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", "xlayer", "stable", "mantle", "injective"]),
+  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."
+  ),
+  recipients: z3.array(
+    z3.object({
+      to: z3.string().refine(isAddress3, "to must be a valid 0x-prefixed EVM address").describe("Recipient EVM address (0x + 40 hex)."),
+      amount: z3.string().regex(/^\d+(\.\d+)?$/, "amount must be a positive decimal string").describe('Human-readable decimal amount for this recipient, e.g. "5.00".')
+    })
+  ).min(1, "recipients must contain at least one row").max(CLIENT_RECIPIENT_CAP, `recipients cannot exceed ${CLIENT_RECIPIENT_CAP} (server enforces tighter cap by key scope)`).describe(
+    `Array of {to, amount} pairs. All recipients share the same chain and token. Trial keys: max ${RECIPIENT_LIMIT_TRIAL} rows. Paid keys: max ${RECIPIENT_LIMIT_PAID} rows.`
+  ),
+  confirm: z3.literal(true).describe(
+    "MUST be true. The user must have explicitly approved this exact set of recipients, amounts, chain, and token in the conversation right before this tool was called. Setting confirm=true on behalf of the user without that approval is a violation of the tool contract."
+  )
+});
+function maxAmountGuardBatch(recipients, cap) {
+  for (let i = 0; i < recipients.length; i++) {
+    const r = recipients[i];
+    const numeric = Number(r.amount);
+    if (!Number.isFinite(numeric)) {
+      throw new Error(`recipients[${i}]: unparseable amount "${r.amount}"`);
+    }
+    if (numeric > cap) {
+      throw new Error(
+        `recipients[${i}]: amount $${r.amount} exceeds the per-call cap of $${cap}. Set Q402_MAX_AMOUNT_PER_CALL to a higher value if intentional.`
+      );
+    }
+  }
+}
+function recipientAllowlistGuardBatch(recipients, allow) {
+  if (allow.length === 0) return;
+  for (let i = 0; i < recipients.length; i++) {
+    const to = recipients[i].to.toLowerCase();
+    if (!allow.includes(to)) {
+      throw new Error(
+        `recipients[${i}]: ${recipients[i].to} is not in Q402_ALLOWED_RECIPIENTS. Either add this address to the allowlist or unset the env var to disable the guard.`
+      );
+    }
+  }
+}
+async function runBatchPay(input) {
+  const chain = getChain(input.chain);
+  tokenFor(chain, input.token);
+  if (chain.supportedTokens && !chain.supportedTokens.includes(input.token)) {
+    throw new Error(
+      `token ${input.token} is not supported on chain ${chain.key}. Supported on this chain: ${chain.supportedTokens.join(", ")}.`
+    );
+  }
+  const guardsApplied = [];
+  maxAmountGuardBatch(input.recipients, CONFIG.maxAmountPerCallUsd);
+  guardsApplied.push(`max_amount<=${CONFIG.maxAmountPerCallUsd} (per recipient)`);
+  recipientAllowlistGuardBatch(input.recipients, CONFIG.allowedRecipients);
+  if (CONFIG.allowedRecipients.length > 0) {
+    guardsApplied.push(`recipient_allowlist[${CONFIG.allowedRecipients.length}]`);
+  }
+  if (CONFIG.mode === "sandbox") {
+    const sandboxResults = input.recipients.map(
+      (r) => sandboxPay(chain, { to: r.to, amount: r.amount, token: input.token })
+    );
+    guardsApplied.push("mode=sandbox");
+    return {
+      mode: "sandbox",
+      result: { sandbox: sandboxResults, reason: describeSandboxReason2() },
+      guardsApplied,
+      setupHint: describeSandboxReason2()
+    };
+  }
+  const client = new Q402NodeClient({
+    apiKey: CONFIG.apiKey,
+    privateKey: CONFIG.privateKey,
+    chain,
+    relayBaseUrl: CONFIG.relayBaseUrl
+  });
+  const result = await client.batchPay(
+    input.recipients.map((r) => ({ to: r.to, amount: r.amount, token: input.token }))
+  );
+  guardsApplied.push("mode=live");
+  guardsApplied.push(`scope=${result.scope} (server enforced)`);
+  guardsApplied.push(`batch_size=${input.recipients.length}/${result.limit}`);
+  return { mode: "live", result, guardsApplied };
+}
+function describeSandboxReason2() {
+  const missing = [];
+  if (CONFIG.apiKeyKind !== "live") missing.push("Q402_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.";
+}
+var BATCH_PAY_TOOL = {
+  name: "q402_batch_pay",
+  description: `Send gasless payments to MULTIPLE recipients on a single chain \xD7 token in one call. Trial keys (q402_live_* with plan='trial'): max ${RECIPIENT_LIMIT_TRIAL} recipients per call, BNB Chain + USDC/USDT only. Paid keys: max ${RECIPIENT_LIMIT_PAID} recipients per call, full 7-chain support. SANDBOX BY DEFAULT \u2014 real on-chain TX only when Q402_API_KEY (live), Q402_PRIVATE_KEY, and Q402_ENABLE_REAL_PAYMENTS=1 are all set. 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: {
+      chain: {
+        type: "string",
+        enum: CHAIN_KEYS,
+        description: "Target chain. Applies to every recipient in the batch."
+      },
+      token: {
+        type: "string",
+        enum: ["USDC", "USDT", "RLUSD"],
+        description: "Stablecoin for the entire batch. USDC / USDT supported on most chains; Injective is USDT-only; RLUSD (decimals 18) is Ethereum-only."
+      },
+      recipients: {
+        type: "array",
+        minItems: 1,
+        maxItems: CLIENT_RECIPIENT_CAP,
+        description: "List of recipients. Trial keys: max 5. Paid keys: max 20. Each item is {to, amount}.",
+        items: {
+          type: "object",
+          properties: {
+            to: {
+              type: "string",
+              description: "Recipient EVM address (0x + 40 hex)."
+            },
+            amount: {
+              type: "string",
+              description: 'Human-readable decimal amount for this recipient, e.g. "5.00".'
+            }
+          },
+          required: ["to", "amount"],
+          additionalProperties: false
+        }
+      },
+      confirm: {
+        type: "boolean",
+        const: true,
+        description: "MUST be true and only set after the user has confirmed the entire batch in chat."
+      }
+    },
+    required: ["chain", "token", "recipients", "confirm"],
+    additionalProperties: false
+  }
+};
+
+// src/tools/balance.ts
+import { z as z4 } from "zod";
+var BalanceInputSchema = z4.object({});
 function mask(key) {
   if (!key || key.length < 12) return null;
   return `${key.slice(0, 12)}\u2026${key.slice(-4)}`;
@@ -609,39 +864,39 @@ var BALANCE_TOOL = {
 };
 
 // src/tools/receipt.ts
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 import { keccak256, toUtf8Bytes, getBytes, verifyMessage } from "ethers";
-var ReceiptShape = z4.object({
-  receiptId: z4.string(),
-  createdAt: z4.string(),
-  txHash: z4.string(),
-  blockNumber: z4.number().optional(),
-  chain: z4.string(),
-  payer: z4.string(),
-  recipient: z4.string(),
-  token: z4.enum(["USDC", "USDT", "RLUSD"]),
-  tokenAmount: z4.string(),
-  tokenAmountRaw: z4.string(),
-  method: z4.enum(["eip7702", "eip3009", "eip7702_xlayer", "eip7702_stable"]),
-  gasCostNative: z4.string().optional(),
-  apiKeyTier: z4.string().optional(),
+var ReceiptShape = z5.object({
+  receiptId: z5.string(),
+  createdAt: z5.string(),
+  txHash: z5.string(),
+  blockNumber: z5.number().optional(),
+  chain: z5.string(),
+  payer: z5.string(),
+  recipient: z5.string(),
+  token: z5.enum(["USDC", "USDT", "RLUSD"]),
+  tokenAmount: z5.string(),
+  tokenAmountRaw: z5.string(),
+  method: z5.enum(["eip7702", "eip3009", "eip7702_xlayer", "eip7702_stable"]),
+  gasCostNative: z5.string().optional(),
+  apiKeyTier: z5.string().optional(),
   // hidden by default in publicView
-  showTier: z4.boolean(),
-  sandbox: z4.boolean(),
-  webhook: z4.object({
-    configured: z4.boolean(),
-    event: z4.string(),
-    deliveryStatus: z4.enum(["pending", "delivered", "failed", "not_configured"]),
-    attempts: z4.number().optional(),
-    lastStatusCode: z4.number().optional(),
-    lastError: z4.string().optional(),
-    deliveredAt: z4.string().optional(),
-    payloadSha256: z4.string().optional(),
-    signatureSha256: z4.string().optional()
+  showTier: z5.boolean(),
+  sandbox: z5.boolean(),
+  webhook: z5.object({
+    configured: z5.boolean(),
+    event: z5.string(),
+    deliveryStatus: z5.enum(["pending", "delivered", "failed", "not_configured"]),
+    attempts: z5.number().optional(),
+    lastStatusCode: z5.number().optional(),
+    lastError: z5.string().optional(),
+    deliveredAt: z5.string().optional(),
+    payloadSha256: z5.string().optional(),
+    signatureSha256: z5.string().optional()
   }),
-  signature: z4.string(),
-  signedBy: z4.string(),
-  signedAt: z4.string()
+  signature: z5.string(),
+  signedBy: z5.string(),
+  signedAt: z5.string()
 });
 function canonicalize(fields) {
   const sorted = {};
@@ -674,9 +929,9 @@ function verifyReceiptSignature(r) {
     return false;
   }
 }
-var ReceiptInputSchema = z4.object({
-  receiptId: z4.string().regex(/^rct_[0-9a-f]{24}$/, "receiptId must match rct_<24-hex>").optional(),
-  txHash: z4.string().regex(/^0x[0-9a-fA-F]{64}$/, "txHash must be a 0x-prefixed 32-byte hex").optional()
+var ReceiptInputSchema = z5.object({
+  receiptId: z5.string().regex(/^rct_[0-9a-f]{24}$/, "receiptId must match rct_<24-hex>").optional(),
+  txHash: z5.string().regex(/^0x[0-9a-fA-F]{64}$/, "txHash must be a 0x-prefixed 32-byte hex").optional()
 }).refine((v) => !!v.receiptId || !!v.txHash, {
   message: "Provide receiptId OR txHash (at least one)"
 });
@@ -773,7 +1028,7 @@ var RECEIPT_TOOL = {
 
 // src/index.ts
 var PACKAGE_NAME = "@quackai/q402-mcp";
-var PACKAGE_VERSION = "0.3.7";
+var PACKAGE_VERSION = "0.3.9";
 function jsonText(value) {
   return { type: "text", text: JSON.stringify(value, null, 2) };
 }
@@ -783,7 +1038,7 @@ async function main() {
     { capabilities: { tools: {} } }
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: [QUOTE_TOOL, BALANCE_TOOL, PAY_TOOL, RECEIPT_TOOL]
+    tools: [QUOTE_TOOL, BALANCE_TOOL, PAY_TOOL, BATCH_PAY_TOOL, RECEIPT_TOOL]
   }));
   server.setRequestHandler(CallToolRequestSchema, async (req) => {
     const { name, arguments: args } = req.params;
@@ -801,6 +1056,10 @@ async function main() {
           const parsed = PayInputSchema.parse(args ?? {});
           return { content: [jsonText(await runPay(parsed))] };
         }
+        case "q402_batch_pay": {
+          const parsed = BatchPayInputSchema.parse(args ?? {});
+          return { content: [jsonText(await runBatchPay(parsed))] };
+        }
         case "q402_receipt": {
           const parsed = ReceiptInputSchema.parse(args ?? {});
           return { content: [jsonText(await runReceipt(parsed))] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quackai/q402-mcp",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "MCP server for Q402 — gasless USDC, USDT, and RLUSD payments across 7 EVM chains, callable directly from Claude Desktop and any other Model Context Protocol client.",
   "mcpName": "io.github.bitgett/q402-mcp",
   "keywords": [