@quackai/q402-mcp 0.5.15 → 0.5.17

package/README.md

@@ -91,8 +91,8 @@ Q402_ENABLE_REAL_PAYMENTS=1
 # Default Q402 deployment. Only change for self-hosted.
 Q402_RELAY_BASE_URL=https://q402.quackai.ai/api
 
-# Optional safety guards:
-# Q402_MAX_AMOUNT_PER_CALL=5
+# Safety guards (max-amount ships uncommented at $200; lower for tighter caps):
+Q402_MAX_AMOUNT_PER_CALL=200
 # Q402_ALLOWED_RECIPIENTS=0xabc...,0xdef...
 ```
 
@@ -165,10 +165,10 @@ Then export the values in `~/.zshrc` / `~/.bashrc`. See the [Codex config refere
 
 By default the MCP server operates in **sandbox mode**: `q402_pay` returns a random fake transaction hash with `success: false` and `sandbox: true`, no funds move, no gas-tank credit is consumed. That makes it safe to plug into any MCP client without worrying about an accidental payment — if the agent misreads the conversation and fires `q402_pay` before you intended, nothing moves AND the response cannot be mistaken for a confirmed settlement.
 
-To enable real on-chain transactions, the resolved API key must be live (`q402_live_*`), `Q402_PRIVATE_KEY` must be set to a valid 32-byte hex key, and `Q402_ENABLE_REAL_PAYMENTS=1`. The block below is the template `q402_doctor` writes to `~/.q402/mcp.env` — every secret line is commented out and the live flag defaults to `1`. Uncomment the lines you need and paste real values in your editor; the live-mode gate only flips once a real key + valid PK are present, so saving the template as-is stays in sandbox. Change the flag to `0` if you want to force sandbox even with real keys (e.g. for chained testing on a paid plan):
+To enable real on-chain transactions, the resolved API key must be live (`q402_live_*`), `Q402_PRIVATE_KEY` must be set to a valid 32-byte hex key, and `Q402_ENABLE_REAL_PAYMENTS=1`. The block below is the template `q402_doctor` writes to `~/.q402/mcp.env` — the three secret lines ship empty (no `#` to remove, just paste the value on the right of `=`) and the live flag defaults to `1`. The live-mode gate only flips once a real key + valid 32-byte PK are populated, so saving the template as-is stays in sandbox automatically. Change the flag to `0` if you want to force sandbox even with real keys (e.g. for chained testing on a paid plan):
 
 ```bash
-# Two-key model — uncomment ONE (or both for auto-routing).
+# Two-key model — fill ONE (or both for auto-routing).
 # Auto-routing (same for q402_pay AND q402_batch_pay):
 #   chain="bnb" + Q402_TRIAL_API_KEY set  → Trial (free sponsored)
 #   anything else                          → Multichain (paid 9-chain)
@@ -176,20 +176,19 @@ To enable real on-chain transactions, the resolved API key must be live (`q402_l
 #   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 9-chain key (per-chain Gas Tank)
+Q402_TRIAL_API_KEY=                # BNB-only sponsored Trial key (from /event)
+Q402_MULTICHAIN_API_KEY=           # paid 9-chain key (per-chain Gas Tank)
 
-# Q402_PRIVATE_KEY=0x...                   # signer for the payer EOA (32-byte hex)
+Q402_PRIVATE_KEY=                  # signer for the payer EOA (0x + 64 hex chars)
 
 # Live mode switch:
 #   0 = sandbox (test mode, no funds move — every q402_pay returns a fake hash)
 #   1 = real on-chain payments (live mode)
-# Default is 1: real payments enabled. Safe because mode only flips
-# to live when BOTH a live API key (q402_live_*) AND a valid 32-byte
-# private key are set above. Placeholders ("0x...") are rejected by
-# the live-mode gate, so partial setups stay in sandbox with a hint.
-# Change to 0 to force sandbox even with real keys (e.g. for chained
-# testing on a paid plan).
+# Default 1: real payments enabled. Safe because mode only flips to live
+# when BOTH a live API key (q402_live_*) AND a valid 32-byte private
+# key are populated above. Empty values fail the gate, so partial setups
+# stay in sandbox with a hint. Change to 0 to force sandbox even with
+# real keys (e.g. for chained testing on a paid plan).
 Q402_ENABLE_REAL_PAYMENTS=1
 ```
 
@@ -203,7 +202,7 @@ Two additional guards run before every payment regardless of mode:
 
 | Env var | Default | Effect |
 |---|---|---|
-| `Q402_MAX_AMOUNT_PER_CALL` | `5` | Reject any single call where `amount > N` USD-equivalent. |
+| `Q402_MAX_AMOUNT_PER_CALL` | `200` | Reject any single call where `amount > N` USD-equivalent. |
 | `Q402_ALLOWED_RECIPIENTS` | (empty = off) | Comma-separated address allowlist. When set, all other recipients are rejected. |
 
 Combined with the `confirm: true` argument the tool requires, this means the model needs (a) explicit user OK in chat, (b) amount ≤ cap, (c) recipient on allowlist if one exists, (d) all three live-mode env vars set, before a single wei moves.
@@ -218,7 +217,7 @@ Combined with the `confirm: true` argument the tool requires, this means the mod
 | `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_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. |
-| `Q402_MAX_AMOUNT_PER_CALL` | optional | USD-equivalent cap. Defaults to `5`. |
+| `Q402_MAX_AMOUNT_PER_CALL` | optional | USD-equivalent cap. Defaults to `200`. Lower for tighter agent blast-radius. |
 | `Q402_ALLOWED_RECIPIENTS` | optional | Comma-separated lowercase addresses. Defaults to no allowlist. |
 | `Q402_RELAY_BASE_URL` | optional | Defaults to `https://q402.quackai.ai/api`. Override for self-hosted Q402. |
 

package/dist/index.js

@@ -96,7 +96,7 @@ var Q402_ENV_FILE_KEYS_ALL = Object.freeze(
   new Set(Object.keys(FILE_ENV))
 );
 var DEFAULT_RELAY_BASE = "https://q402.quackai.ai/api";
-var DEFAULT_MAX_AMOUNT = 5;
+var DEFAULT_MAX_AMOUNT = 200;
 function classifyApiKey(k) {
   if (!k) return "missing";
   if (k.startsWith("q402_live_")) return "live";
@@ -121,7 +121,8 @@ function loadConfig() {
   const apiKeyKind = classifyApiKey(apiKey);
   const privateKey = ENV.Q402_PRIVATE_KEY ?? null;
   const realPaymentsRequested = ENV.Q402_ENABLE_REAL_PAYMENTS === "1";
-  const live = realPaymentsRequested && apiKeyKind === "live" && typeof privateKey === "string" && privateKey.length > 0;
+  const anyLiveKey = classifyApiKey(trialApiKey) === "live" || classifyApiKey(multichainApiKey) === "live" || classifyApiKey(legacyApiKey) === "live";
+  const live = realPaymentsRequested && anyLiveKey && typeof privateKey === "string" && privateKey.length > 0;
   return {
     trialApiKey,
     multichainApiKey,
@@ -187,7 +188,7 @@ var isValidPrivateKey = (s) => typeof s === "string" && PRIVATE_KEY_RE.test(s);
 
 // src/version.ts
 var PACKAGE_NAME = "@quackai/q402-mcp";
-var PACKAGE_VERSION = "0.5.15";
+var PACKAGE_VERSION = "0.5.17";
 
 // src/tools/quote.ts
 import { z } from "zod";
@@ -1043,6 +1044,16 @@ async function runBatchPay(input) {
     }
   }
   const scopeRequest = input.keyScope ?? "auto";
+  if (scopeRequest === "trial" && input.recipients.length > RECIPIENT_LIMIT_TRIAL) {
+    guardsApplied.push("trial_cap_exceeded");
+    return {
+      mode: "none",
+      status: "trial_cap_exceeded",
+      guardsApplied,
+      senderWallet,
+      setupHint: `keyScope="trial" caps at ${RECIPIENT_LIMIT_TRIAL} recipients per call (BNB-only sponsored). Your batch has ${input.recipients.length}. Either trim to the first ${RECIPIENT_LIMIT_TRIAL} recipients and re-invoke with keyScope="trial", or send the full batch on the paid Multichain key by re-invoking with keyScope="multichain" (charges the paid pool + Gas Tank, up to ${RECIPIENT_LIMIT_PAID} per call).`
+    };
+  }
   if (scopeRequest === "auto" && input.chain === "bnb" && CONFIG.trialApiKey && input.recipients.length > RECIPIENT_LIMIT_TRIAL) {
     const overflow = input.recipients.length - RECIPIENT_LIMIT_TRIAL;
     guardsApplied.push("batch_cap_ambiguous");
@@ -1691,11 +1702,12 @@ Q402_RELAY_BASE_URL=https://q402.quackai.ai/api
 
 
 # \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
-# Optional safety guards (uncomment + edit to enable)
+# Safety guards
 # \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
-# Max USD per single q402_pay call (default: 5)
-# Q402_MAX_AMOUNT_PER_CALL=5
-#
+# Max USD per single q402_pay call. Any request above this is rejected
+# before signing. Lower this if you want a tighter agent blast-radius.
+Q402_MAX_AMOUNT_PER_CALL=200
+
 # Comma-separated lowercase recipient allowlist (unset = any address OK)
 # Q402_ALLOWED_RECIPIENTS=0xabc...,0xdef...
 `;
@@ -1722,11 +1734,12 @@ function mask2(key) {
 }
 function detectPhase() {
   const anyKey = !!(CONFIG.trialApiKey || CONFIG.multichainApiKey || CONFIG.legacyApiKey);
+  const anyLiveKey = classifyApiKey(CONFIG.trialApiKey) === "live" || classifyApiKey(CONFIG.multichainApiKey) === "live" || classifyApiKey(CONFIG.legacyApiKey) === "live";
   const hasValidPrivateKey = isValidPrivateKey(CONFIG.privateKey);
   if (!Q402_ENV_FILE_PRESENT && !anyKey && !CONFIG.privateKey) {
     return "first-install";
   }
-  const allEssentials = anyKey && hasValidPrivateKey && CONFIG.realPaymentsRequested && CONFIG.apiKeyKind === "live";
+  const allEssentials = anyKey && hasValidPrivateKey && CONFIG.realPaymentsRequested && anyLiveKey;
   if (allEssentials) return "live-check";
   if (anyKey || CONFIG.privateKey || Q402_ENV_FILE_PRESENT) return "needs-completion";
   return "first-install";

package/package.json

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