@quackai/q402-mcp 0.8.31 → 0.8.33

package/README.md

@@ -156,7 +156,7 @@ Then export the values in `~/.zshrc` / `~/.bashrc`. See the [Codex config refere
 
 ## Tools exposed
 
-**24 tools** — read-only by default; live mode needs an API key + signing path + `Q402_ENABLE_REAL_PAYMENTS=1`.
+**27 tools** — read-only by default; live mode needs an API key + signing path + `Q402_ENABLE_REAL_PAYMENTS=1`.
 
 | Tool | Auth | Purpose |
 |---|---|---|
@@ -184,8 +184,11 @@ Then export the values in `~/.zshrc` / `~/.bashrc`. See the [Codex config refere
 | `q402_yield_positions` | api key | Show the Agent Wallet's open Q402 Yield positions (balance, principal, accrued interest, APY) + total supplied in USD. Mode C. |
 | `q402_yield_deposit` | live mode | Supply the Agent Wallet's USDC/USDT into Aave V3 (Q402 Yield) to earn supply APY. Mode C, BNB-only. Requires `confirm: true`; sandbox-by-default. |
 | `q402_yield_withdraw` | live mode | Withdraw supplied USDC/USDT out of Aave V3 back to the Agent Wallet (`amount: "max"` = full position). Mode C, BNB-only. Requires `confirm: true`; sandbox-by-default. |
+| `q402_request_create` | api key | Publish a payment request (invoice). No funds move; returns a shareable `/pay` link + `req_…` id. Recipient defaults to the Agent Wallet. |
+| `q402_request_status` | none | Look up a payment request by `req_…` id (amount, token, chain, recipient, status). Read-only; `notFound` instead of throwing. |
+| `q402_request_pay` | live mode | Pay a request gaslessly from the payer's own Agent Wallet (Mode C). Terms come from the stored request, so they can't be redirected. Two-phase consent (same as `q402_pay`). |
 
-`q402_pay` + `q402_batch_pay` + `q402_bridge_send` + `q402_yield_deposit` + `q402_yield_withdraw` require explicit in-chat confirmation. Batch confirmation = full batch, not per-row.
+`q402_pay` + `q402_batch_pay` + `q402_bridge_send` + `q402_yield_deposit` + `q402_yield_withdraw` + `q402_request_pay` require explicit in-chat confirmation. Batch confirmation = full batch, not per-row.
 
 > ℹ️ `q402_pay` expects a 0x address — ENS isn't resolved server-side. Resolve client-side first.
 > Per-chain Gas Tank balances + full TX history live in the [dashboard](https://q402.quackai.ai/dashboard) (wallet-signature only).

package/dist/index.js

@@ -211,7 +211,7 @@ var isValidPrivateKey = (s) => typeof s === "string" && PRIVATE_KEY_RE.test(s);
 // package.json
 var package_default = {
   name: "@quackai/q402-mcp",
-  version: "0.8.31",
+  version: "0.8.33",
   description: "MCP server for Q402 \u2014 gasless USDC/USDT/RLUSD payments on 10 EVM chains + Chainlink CCIP USDC bridge on the eth/avax/arbitrum triangle, callable from Claude (Desktop / Code), OpenAI Codex CLI, and any other Model Context Protocol client.",
   mcpName: "io.github.bitgett/q402-mcp",
   keywords: [
@@ -279,7 +279,9 @@ var package_default = {
     access: "public"
   },
   overrides: {
-    esbuild: "^0.28.1"
+    esbuild: "^0.28.1",
+    ws: "^8.21.0",
+    hono: "^4.12.25"
   }
 };
 
@@ -4778,6 +4780,302 @@ async function runRecurringSkipNext(input) {
   }
 }
 
+// src/tools/request-create.ts
+import { z as z25 } from "zod";
+var ADDRESS_RE2 = /^0x[0-9a-fA-F]{40}$/;
+var AMOUNT_RE2 = /^\d+(\.\d{1,18})?$/;
+var RequestCreateInputSchema = z25.object({
+  amount: z25.string().regex(AMOUNT_RE2).describe('Amount to request, as a decimal string (e.g. "5", "1.50"). Counted in `token` (USDC or USDT, both USD-1).'),
+  token: z25.enum(["USDC", "USDT"]).default("USDT").describe("Stablecoin to be paid. USDC or USDT. Both peg USD-1."),
+  chain: z25.enum(["bnb", "eth", "avax", "xlayer", "stable", "mantle", "injective", "monad", "scroll", "arbitrum"]).default("bnb").describe("Chain the request settles on. Defaults to bnb."),
+  recipient: z25.string().regex(ADDRESS_RE2).optional().describe("0x address that receives the funds. Defaults to Q402_AGENT_WALLET_ADDRESS (the agent bills itself) when omitted."),
+  memo: z25.string().max(200).optional().describe("Optional note shown to the payer (\u2264200 chars), e.g. an invoice number or service description."),
+  ttlDays: z25.number().int().min(1).max(90).optional().describe("Days until the request expires. Defaults to 7 (max 90).")
+});
+async function runRequestCreate(input) {
+  const base = CONFIG.relayBaseUrl;
+  if (!CONFIG.apiKey) {
+    return {
+      ok: false,
+      requestId: null,
+      payUrl: null,
+      request: null,
+      error: "API_KEY_REQUIRED",
+      message: "No Q402 API key configured. Run q402_doctor to set one up."
+    };
+  }
+  const recipient = input.recipient?.toLowerCase() ?? CONFIG.walletId;
+  if (!recipient) {
+    return {
+      ok: false,
+      requestId: null,
+      payUrl: null,
+      request: null,
+      error: "RECIPIENT_REQUIRED",
+      message: "No recipient given and no Q402_AGENT_WALLET_ADDRESS configured. Pass `recipient` (the 0x address that should receive the funds)."
+    };
+  }
+  try {
+    const res = await fetch(`${base}/request`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        apiKey: CONFIG.apiKey,
+        chain: input.chain ?? "bnb",
+        token: input.token ?? "USDT",
+        amount: input.amount,
+        recipient,
+        ...input.memo !== void 0 ? { memo: input.memo } : {},
+        ...input.ttlDays !== void 0 ? { ttlDays: input.ttlDays } : {}
+      }),
+      signal: AbortSignal.timeout(15e3)
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok || !data.requestId) {
+      return {
+        ok: false,
+        requestId: null,
+        payUrl: null,
+        request: null,
+        error: data.error ?? `HTTP_${res.status}`,
+        message: data.error ?? `Create failed with HTTP ${res.status}.`
+      };
+    }
+    return {
+      ok: true,
+      requestId: data.requestId,
+      payUrl: data.payUrl ?? null,
+      request: data.request ?? null
+    };
+  } catch (e) {
+    return {
+      ok: false,
+      requestId: null,
+      payUrl: null,
+      request: null,
+      error: "NETWORK_ERROR",
+      message: e instanceof Error ? e.message : String(e)
+    };
+  }
+}
+var REQUEST_CREATE_TOOL = {
+  name: "q402_request_create",
+  description: "Publish a Q402 payment request (an invoice / bill). Moves no funds \u2014 it creates a shareable request to RECEIVE money \u2014 so no confirmation is needed and a Trial key works. Returns a req_ id + a /pay link you can share with a human, or hand the requestId to another agent that pays it gaslessly via q402_request_pay. The recipient defaults to your configured Agent Wallet, so you can bill yourself with just an amount. Pair with q402_request_status to poll for payment.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      amount: {
+        type: "string",
+        pattern: "^\\d+(\\.\\d{1,18})?$",
+        description: 'Required. Amount to request as a decimal string (e.g. "5", "1.50").'
+      },
+      token: {
+        type: "string",
+        enum: ["USDC", "USDT"],
+        description: "Default 'USDT'. Both peg USD-1."
+      },
+      chain: {
+        type: "string",
+        enum: ["bnb", "eth", "avax", "xlayer", "stable", "mantle", "injective", "monad", "scroll", "arbitrum"],
+        description: "Default 'bnb'. Chain the request settles on."
+      },
+      recipient: {
+        type: "string",
+        pattern: "^0x[0-9a-fA-F]{40}$",
+        description: "Optional 0x address to receive funds. Defaults to Q402_AGENT_WALLET_ADDRESS (bill yourself)."
+      },
+      memo: {
+        type: "string",
+        maxLength: 200,
+        description: "Optional note shown to the payer (\u2264200 chars)."
+      },
+      ttlDays: {
+        type: "number",
+        minimum: 1,
+        maximum: 90,
+        description: "Days until expiry. Default 7."
+      }
+    },
+    required: ["amount"],
+    additionalProperties: false
+  }
+};
+
+// src/tools/request-status.ts
+import { z as z26 } from "zod";
+var RequestStatusInputSchema = z26.object({
+  requestId: z26.string().regex(/^req_[0-9a-f]{24}$/, "requestId must match req_<24-hex>").describe("Payment request id (req_ + 24 hex chars). Returned by q402_request_create; also the tail of any /pay/ URL.")
+});
+async function runRequestStatus(input) {
+  const base = CONFIG.relayBaseUrl;
+  const pageBase2 = base.replace(/\/api\/?$/, "");
+  const resp = await fetch(`${base}/request/${input.requestId}`, {
+    signal: AbortSignal.timeout(1e4)
+  });
+  if (resp.status === 404) {
+    return { found: false, request: null, payUrl: null, notFound: true };
+  }
+  if (!resp.ok) {
+    throw new Error(`request status fetch failed: HTTP ${resp.status}`);
+  }
+  const data = await resp.json();
+  return {
+    found: true,
+    request: data.request,
+    payUrl: `${pageBase2}/pay/${data.request.id}`
+  };
+}
+var REQUEST_STATUS_TOOL = {
+  name: "q402_request_status",
+  description: "Look up a Q402 payment request by its req_ id. Read-only, no API key. Returns the amount, token, chain, recipient, status (open | paid | expired | cancelled) and a shareable pay URL. Use it to poll a request you created, or to inspect a requestId before paying it with q402_request_pay. An unknown or expired id returns notFound:true (no throw).",
+  inputSchema: {
+    type: "object",
+    properties: {
+      requestId: {
+        type: "string",
+        pattern: "^req_[0-9a-f]{24}$",
+        description: "Payment request id (req_ + 24 hex). Returned by q402_request_create; also the tail of a /pay/ URL."
+      }
+    },
+    required: ["requestId"],
+    additionalProperties: false
+  }
+};
+
+// src/tools/request-pay.ts
+import { z as z27 } from "zod";
+var RequestPayInputSchema = z27.object({
+  requestId: z27.string().regex(/^req_[0-9a-f]{24}$/, "requestId must match req_<24-hex>").describe("The payment request to pay (req_ + 24 hex). Get it from a /pay link, a 402 response, or whoever billed you."),
+  confirm: z27.literal(true).describe(
+    "REQUIRED. Must be literally `true`. Acknowledges this moves real funds from your Agent Wallet."
+  ),
+  consentToken: z27.string().optional().describe(
+    'Two-phase consent, identical to q402_pay. Call FIRST WITHOUT it: the tool moves no money and returns status="needs_consent" with a `preview` of the exact payment plus a `consentToken`. Relay the preview to the user, get an explicit yes, then re-call with the SAME requestId PLUS this consentToken. The token is re-derived from the request\'s terms, so a previewed payment cannot be swapped for a different one. confirm:true alone does NOT fire a payment.'
+  ),
+  walletId: z27.string().optional().describe("Optional lowercased Agent Wallet address to pay from when you hold multiple. Defaults to Q402_AGENT_WALLET_ADDRESS, then the server default.")
+});
+async function runRequestPay(input) {
+  const base = CONFIG.relayBaseUrl;
+  let req;
+  try {
+    const r = await fetch(`${base}/request/${input.requestId}`, { signal: AbortSignal.timeout(1e4) });
+    if (r.status === 404) {
+      return { ok: false, status: "not_payable", requestId: input.requestId, txHash: null, receiptId: null, error: "NOT_FOUND", message: "No request with that id." };
+    }
+    if (!r.ok) throw new Error(`HTTP ${r.status}`);
+    req = (await r.json()).request;
+  } catch (e) {
+    return { ok: false, status: "failed", requestId: input.requestId, txHash: null, receiptId: null, error: "LOOKUP_FAILED", message: e instanceof Error ? e.message : String(e) };
+  }
+  const terms = { amount: req.amount, token: req.token, chain: req.chain, recipient: req.recipient };
+  if (req.status !== "open") {
+    return { ok: false, status: "not_payable", requestId: req.id, txHash: null, receiptId: null, ...terms, error: req.status.toUpperCase(), message: `Request is ${req.status} \u2014 nothing to pay.` };
+  }
+  const amountNum = Number(req.amount);
+  if (Number.isFinite(amountNum) && amountNum > CONFIG.maxAmountPerCallUsd) {
+    return { ok: false, status: "not_payable", requestId: req.id, txHash: null, receiptId: null, ...terms, error: "AMOUNT_EXCEEDS_CAP", message: `Request amount $${req.amount} exceeds your Q402_MAX_AMOUNT_PER_CALL cap of $${CONFIG.maxAmountPerCallUsd}.` };
+  }
+  if (CONFIG.allowedRecipients.length > 0 && !CONFIG.allowedRecipients.includes(req.recipient.toLowerCase())) {
+    return { ok: false, status: "not_payable", requestId: req.id, txHash: null, receiptId: null, ...terms, error: "RECIPIENT_NOT_ALLOWED", message: `Recipient ${req.recipient} is not in Q402_ALLOWED_RECIPIENTS.` };
+  }
+  const consentIntent = {
+    t: "request_pay",
+    requestId: req.id,
+    to: req.recipient.toLowerCase(),
+    amount: req.amount,
+    token: req.token,
+    chain: req.chain
+  };
+  const consent = checkConsent(consentIntent, input.consentToken);
+  if (!consent.ok) {
+    return {
+      ok: false,
+      status: "needs_consent",
+      requestId: req.id,
+      txHash: null,
+      receiptId: null,
+      ...terms,
+      message: "Relay this preview to the user and get an explicit yes, then re-call with the same requestId plus consentToken. No funds moved.",
+      needsConsent: {
+        status: "needs_confirmation",
+        preview: `Pay ${req.amount} ${req.token} to ${req.recipient} on ${req.chain} (request ${req.id}).`,
+        consentToken: consent.expected
+      }
+    };
+  }
+  const resolved = resolveApiKey(req.chain, "auto");
+  if (!resolved.apiKey || !resolved.apiKey.startsWith("q402_live_")) {
+    return {
+      ok: false,
+      status: "sandbox",
+      requestId: req.id,
+      txHash: null,
+      receiptId: null,
+      ...terms,
+      error: "LIVE_KEY_REQUIRED",
+      message: "Paying a request settles real funds and needs a live Q402 API key.",
+      setupHint: resolved.sandboxReason ?? "Configure a live Q402_MULTICHAIN_API_KEY (or Q402_TRIAL_API_KEY for BNB) to pay requests."
+    };
+  }
+  if (!CONFIG.realPaymentsRequested) {
+    return {
+      ok: false,
+      status: "sandbox",
+      requestId: req.id,
+      txHash: null,
+      receiptId: null,
+      ...terms,
+      error: "REAL_PAYMENTS_DISABLED",
+      message: "Real payments are off, so this request was not paid.",
+      setupHint: "Set Q402_ENABLE_REAL_PAYMENTS=1 to let q402_request_pay settle real funds."
+    };
+  }
+  const walletId = typeof input.walletId === "string" && input.walletId.length > 0 ? input.walletId.toLowerCase() : CONFIG.walletId;
+  try {
+    const res = await fetch(`${base}/request/${req.id}/pay`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        payerApiKey: resolved.apiKey,
+        ...walletId ? { walletId } : {}
+      }),
+      signal: AbortSignal.timeout(6e4)
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok || !data.txHash) {
+      return { ok: false, status: "failed", requestId: req.id, txHash: null, receiptId: null, ...terms, error: data.error ?? `HTTP_${res.status}`, message: data.message ?? data.error ?? `Settlement failed (HTTP ${res.status}).` };
+    }
+    return { ok: true, status: "paid", requestId: req.id, txHash: data.txHash, receiptId: data.receiptId ?? null, ...terms };
+  } catch (e) {
+    return { ok: false, status: "failed", requestId: req.id, txHash: null, receiptId: null, ...terms, error: "NETWORK_ERROR", message: e instanceof Error ? e.message : String(e) };
+  }
+}
+var REQUEST_PAY_TOOL = {
+  name: "q402_request_pay",
+  description: "Pay a Q402 payment request from your own Agent Wallet, gaslessly. Give it a req_ id (from a /pay link, a 402 Payment Required response, or whoever billed you) and it settles the exact amount + token + recipient the request specifies \u2014 you cannot redirect or change them. MOVES FUNDS: requires confirm:true, a live API key, and Q402_ENABLE_REAL_PAYMENTS=1, same as q402_pay. Call q402_request_status first to show the user what they're paying. This is the agent-to-agent billing path: agent A bills with q402_request_create, agent B settles here.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      requestId: {
+        type: "string",
+        pattern: "^req_[0-9a-f]{24}$",
+        description: "Required. The req_ id to pay."
+      },
+      confirm: {
+        type: "boolean",
+        const: true,
+        description: "REQUIRED. Must be literally true. Paying moves real funds \u2014 get an explicit user yes first."
+      },
+      walletId: {
+        type: "string",
+        description: "Optional. Agent Wallet address to pay from. Defaults to the configured / server-default wallet."
+      }
+    },
+    required: ["requestId", "confirm"],
+    additionalProperties: false
+  }
+};
+
 // src/index.ts
 function jsonText(value) {
   return { type: "text", text: JSON.stringify(value, null, 2) };
@@ -4827,7 +5125,14 @@ async function main() {
       // (like q402_pay). Mode C: apiKey in the body, server signs the supply
       // / withdraw with the encrypted key.
       YIELD_DEPOSIT_TOOL,
-      YIELD_WITHDRAW_TOOL
+      YIELD_WITHDRAW_TOOL,
+      // Payment Requests — the receive side. create publishes an invoice
+      // (no funds move, apiKey only), status is a public id lookup, pay
+      // settles a request gaslessly from the payer's own Agent Wallet
+      // (Mode C, confirm-gated like q402_pay). Enables agent-to-agent billing.
+      REQUEST_CREATE_TOOL,
+      REQUEST_STATUS_TOOL,
+      REQUEST_PAY_TOOL
     ]
   }));
   server.setRequestHandler(CallToolRequestSchema, async (req) => {
@@ -4930,6 +5235,18 @@ async function main() {
           const parsed = YieldWithdrawInputSchema.parse(args ?? {});
           return await runYieldWithdraw(parsed);
         }
+        case "q402_request_create": {
+          const parsed = RequestCreateInputSchema.parse(args ?? {});
+          return { content: [jsonText(await runRequestCreate(parsed))] };
+        }
+        case "q402_request_status": {
+          const parsed = RequestStatusInputSchema.parse(args ?? {});
+          return { content: [jsonText(await runRequestStatus(parsed))] };
+        }
+        case "q402_request_pay": {
+          const parsed = RequestPayInputSchema.parse(args ?? {});
+          return { content: [jsonText(await runRequestPay(parsed))] };
+        }
         default:
           return {
             isError: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quackai/q402-mcp",
-  "version": "0.8.31",
+  "version": "0.8.33",
   "description": "MCP server for Q402 — gasless USDC/USDT/RLUSD payments on 10 EVM chains + Chainlink CCIP USDC bridge on the eth/avax/arbitrum triangle, callable from Claude (Desktop / Code), OpenAI Codex CLI, and any other Model Context Protocol client.",
   "mcpName": "io.github.bitgett/q402-mcp",
   "keywords": [
@@ -68,6 +68,8 @@
     "access": "public"
   },
   "overrides": {
-    "esbuild": "^0.28.1"
+    "esbuild": "^0.28.1",
+    "ws": "^8.21.0",
+    "hono": "^4.12.25"
   }
 }