@quackai/q402-mcp 0.3.10 → 0.3.12

package/README.md

@@ -42,13 +42,24 @@ Restart Claude Desktop and ask:
 
 ### OpenAI Codex CLI
 
-One-liner using Codex's built-in registration command:
+Three install paths — pick the one that matches your workflow.
+
+**(a) Codex plugin marketplace** (recommended — bundles the MCP config so users don't write TOML):
+
+```bash
+codex plugin marketplace add bitgett/q402-mcp
+codex /plugins        # browse and install "q402"
+```
+
+This repo carries a Codex plugin manifest at [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json) and a marketplace catalog at [`.agents/plugins/marketplace.json`](./.agents/plugins/marketplace.json), so any signed-in Codex user can register it as a marketplace source and install with one click.
+
+**(b) Single MCP server via `codex mcp add`** (no plugin wrapper — just register the stdio server):
 
 ```bash
 codex mcp add q402 -- npx -y @quackai/q402-mcp
 ```
 
-Or edit `~/.codex/config.toml` directly (`.codex/config.toml` for per-project scope):
+**(c) Direct `~/.codex/config.toml` edit** (`.codex/config.toml` for per-project scope):
 
 ```toml
 [mcp_servers.q402]
@@ -89,7 +100,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. Same sandbox gating as `q402_pay`. |
+| `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. **Supported chains: avax, bnb, eth, mantle, injective** (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.

package/dist/index.js

@@ -445,28 +445,44 @@ var Q402NodeClient = class _Q402NodeClient {
    * 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.
+   *
+   * Signature shape: `{ token, recipients }`. The previous revision took
+   * `PayInput[]` (with token on each row), which read as if rows could
+   * carry different tokens — but the request body only ships one token
+   * field, so the per-row token on rows 1..N was silently ignored. The
+   * new shape surfaces the constraint in the type so consumers can't
+   * accidentally build a "mixed-token batch" that quietly drops the
+   * second token. Same chain + same token across one batch, full stop.
    */
-  async batchPay(inputs) {
-    if (!Array.isArray(inputs) || inputs.length === 0) {
+  async batchPay(input) {
+    const { token, recipients: rows } = input;
+    if (!Array.isArray(rows) || rows.length === 0) {
       throw new Error("batchPay requires at least one recipient");
     }
+    if (typeof token !== "string") {
+      throw new Error("batchPay({ token, recipients }): token must be a string");
+    }
     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(", ")}.`
-        );
-      }
+    const tokenCfg = tokenFor(chain, token);
+    if (chain.supportedTokens && !chain.supportedTokens.includes(token)) {
+      throw new Error(
+        `token ${token} is not supported on chain ${chain.key}. Supported: ${chain.supportedTokens.join(", ")}.`
+      );
+    }
+    for (let i = 0; i < rows.length; i++) {
       try {
-        toRawAmount(inp.amount, tokenCfg.decimals);
+        toRawAmount(rows[i].amount, tokenCfg.decimals);
       } catch (e) {
         throw new Error(
           `recipient[${i}]: ${e instanceof Error ? e.message : String(e)}`
         );
       }
     }
+    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 (default EIP-7702 mode). For "${chain.key}" use pay() in a client-side loop.`
+      );
+    }
     const rpcUrl = this.opts.rpcUrl ?? DEFAULT_RPC[chain.chainId];
     if (!rpcUrl) {
       throw new Error(
@@ -479,11 +495,10 @@ var Q402NodeClient = class _Q402NodeClient {
     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 signedRows = [];
+    for (let i = 0; i < rows.length; i++) {
+      const row = rows[i];
+      const amountRaw = toRawAmount(row.amount, tokenCfg.decimals);
       const paymentNonce = toBigInt(randomBytes(32));
       const witnessSig = await wallet.signTypedData(
         {
@@ -497,7 +512,7 @@ var Q402NodeClient = class _Q402NodeClient {
           owner,
           facilitator,
           token: tokenCfg.address,
-          recipient: inp.to,
+          recipient: row.to,
           amount: BigInt(amountRaw),
           nonce: paymentNonce,
           deadline: BigInt(deadline)
@@ -508,16 +523,15 @@ var Q402NodeClient = class _Q402NodeClient {
         address: chain.implContract,
         nonce: baseAuthNonce + i
       });
-      const baseRow = {
+      signedRows.push({
         from: owner,
-        to: inp.to,
+        to: row.to,
         amount: amountRaw,
+        nonce: paymentNonce.toString(),
         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",
@@ -525,15 +539,29 @@ var Q402NodeClient = class _Q402NodeClient {
       body: JSON.stringify({
         apiKey,
         chain: chain.key,
-        token: inputs[0].token,
-        // all recipients must share token; pre-validated above
+        token,
         facilitator,
-        recipients
+        recipients: signedRows
       })
     });
     const data = await resp.json();
-    if (!resp.ok) {
-      throw new Error(data.error ?? `relay/batch failed (HTTP ${resp.status})`);
+    if (!resp.ok || data.ok === false) {
+      const err = new BatchPayError(
+        data.aborted ? `Batch aborted: recipient[0] failed (${data.results?.[0]?.error ?? "unknown"}). No transfers landed.` : data.totalFailed > 0 ? `Batch completed with ${data.totalFailed}/${data.results?.length ?? "?"} failed rows.` : data.error ?? `relay/batch failed (HTTP ${resp.status})`,
+        {
+          aborted: !!data.aborted,
+          // Preserve the server's scope/limit so the MCP tool surface can
+          // report the actual tier (trial vs paid) rather than guessing.
+          // Falls back to "paid" / row count only when the failure didn't
+          // come from the relay route (e.g. network-level error).
+          scope: data.scope ?? "paid",
+          limit: data.limit ?? signedRows.length,
+          totalSuccess: data.totalSuccess ?? 0,
+          totalFailed: data.totalFailed ?? signedRows.length,
+          results: data.results ?? []
+        }
+      );
+      throw err;
     }
     data.results = data.results.map((r) => ({
       ...r,
@@ -542,6 +570,24 @@ var Q402NodeClient = class _Q402NodeClient {
     return data;
   }
 };
+var BatchPayError = class extends Error {
+  aborted;
+  scope;
+  limit;
+  totalSuccess;
+  totalFailed;
+  results;
+  constructor(message, details) {
+    super(message);
+    this.name = "BatchPayError";
+    this.aborted = details.aborted;
+    this.scope = details.scope;
+    this.limit = details.limit;
+    this.totalSuccess = details.totalSuccess;
+    this.totalFailed = details.totalFailed;
+    this.results = details.results;
+  }
+};
 function sandboxPay(chain, input) {
   const tokenCfg = tokenFor(chain, input.token);
   const tokenAmount = toRawAmount(input.amount, tokenCfg.decimals);
@@ -678,7 +724,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", "xlayer", "stable", "mantle", "injective"]),
+  chain: z3.enum(["avax", "bnb", "eth", "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."
   ),
@@ -741,6 +787,7 @@ async function runBatchPay(input) {
     guardsApplied.push("mode=sandbox");
     return {
       mode: "sandbox",
+      status: "sandbox",
       result: { sandbox: sandboxResults, reason: describeSandboxReason2() },
       guardsApplied,
       setupHint: describeSandboxReason2()
@@ -752,13 +799,39 @@ async function runBatchPay(input) {
     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 };
+  try {
+    const result = await client.batchPay({
+      token: input.token,
+      recipients: input.recipients.map((r) => ({ to: r.to, amount: r.amount }))
+    });
+    guardsApplied.push("mode=live");
+    guardsApplied.push(`scope=${result.scope} (server enforced)`);
+    guardsApplied.push(`batch_size=${input.recipients.length}/${result.limit}`);
+    return { mode: "live", status: "success", result, guardsApplied };
+  } catch (err) {
+    if (err instanceof BatchPayError) {
+      guardsApplied.push("mode=live");
+      guardsApplied.push(`scope=${err.scope} (server enforced)`);
+      guardsApplied.push(`batch_${err.aborted ? "aborted" : "partial_failure"}`);
+      const status = err.aborted ? "aborted" : "partial_failure";
+      return {
+        mode: "live",
+        status,
+        result: {
+          ok: false,
+          scope: err.scope,
+          limit: err.limit,
+          totalSuccess: err.totalSuccess,
+          totalFailed: err.totalFailed,
+          aborted: err.aborted,
+          results: err.results
+        },
+        guardsApplied,
+        error: err.message
+      };
+    }
+    throw err;
+  }
 }
 function describeSandboxReason2() {
   const missing = [];
@@ -770,14 +843,17 @@ function describeSandboxReason2() {
 }
 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.`,
+  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 across 5 EIP-7702 default chains (avax, bnb, eth, mantle, injective). xlayer + stable are NOT batchable \u2014 use q402_pay in a loop. 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."
+        // 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"],
+        description: "Target chain. Applies to every recipient in the batch. xlayer + stable are NOT supported here \u2014 use q402_pay in a loop."
       },
       token: {
         type: "string",
@@ -1028,7 +1104,7 @@ var RECEIPT_TOOL = {
 
 // src/index.ts
 var PACKAGE_NAME = "@quackai/q402-mcp";
-var PACKAGE_VERSION = "0.3.10";
+var PACKAGE_VERSION = "0.3.12";
 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.3.10",
+  "version": "0.3.12",
   "description": "MCP server for Q402 — gasless USDC, USDT, and RLUSD payments across 7 EVM chains, callable from Claude (Desktop / Code), OpenAI Codex CLI, and any other Model Context Protocol client.",
   "mcpName": "io.github.bitgett/q402-mcp",
   "keywords": [