@quackai/q402-mcp 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @quackai/q402-mcp
 
-> MCP server for Q402 — gasless USDC and USDT payments across 7 EVM chains, callable directly from Claude Desktop and any other Model Context Protocol client.
+> 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.
 
 [![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)
@@ -41,11 +41,17 @@ You'll get a ranked breakdown immediately — no API key, no signup, no funds at
 | Tool | Auth | Purpose |
 |---|---|---|
 | `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 (live vs sandbox). |
+| `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_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_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:
+
+> *"Pay 0.10 USDT on BNB to vitalik.eth, then verify the receipt."*  
+> *"Is `rct_afa5f50bc49a65ebba3b28ab` a real Q402 receipt? Verify the signature."*
+
 > Per-chain gas tank balances and full transaction history live in the [dashboard](https://q402.quackai.ai/dashboard) — those endpoints require a wallet signature, not a bare API key, so the MCP server points the agent there instead of exposing them.
 
 ---
@@ -95,7 +101,7 @@ Combined with the `confirm: true` argument the tool requires, this means the mod
 | Chain | Chain ID | Token(s) | Notes |
 |---|---|---|---|
 | BNB Chain | 56 | USDC, USDT | |
-| Ethereum | 1 | USDC, USDT | L1 — gas is volatile, quote is a snapshot. |
+| Ethereum | 1 | USDC, USDT, **RLUSD** | L1 — gas is volatile, quote is a snapshot. RLUSD (Ripple USD, NY DFS regulated, decimals 18) Ethereum-only. |
 | Avalanche C-Chain | 43114 | USDC, USDT | |
 | X Layer | 196 | USDC, USDT | |
 | Stable | 988 | USDT0 (USDC and USDT both alias) | Gas paid in USDT0. |

package/dist/index.js

@@ -71,6 +71,7 @@ var CHAIN_CONFIG = {
     explorer: "https://snowtrace.io",
     usdc: { address: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E", decimals: 6 },
     usdt: { address: "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7", decimals: 6 },
+    supportedTokens: ["USDC", "USDT"],
     approxGasCostUsd: 3e-3
   },
   bnb: {
@@ -83,6 +84,7 @@ var CHAIN_CONFIG = {
     explorer: "https://bscscan.com",
     usdc: { address: "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d", decimals: 18 },
     usdt: { address: "0x55d398326f99059fF775485246999027B3197955", decimals: 18 },
+    supportedTokens: ["USDC", "USDT"],
     approxGasCostUsd: 1e-3
   },
   eth: {
@@ -95,8 +97,12 @@ var CHAIN_CONFIG = {
     explorer: "https://etherscan.io",
     usdc: { address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", decimals: 6 },
     usdt: { address: "0xdAC17F958D2ee523a2206206994597C13D831ec7", decimals: 6 },
+    // Ripple USD (RLUSD) — NY DFS regulated, decimals 18, UUPS proxy.
+    // Ethereum-only; other chains' supportedTokens omits RLUSD.
+    rlusd: { address: "0x8292Bb45bf1Ee4d140127049757C2E0fF06317eD", decimals: 18 },
+    supportedTokens: ["USDC", "USDT", "RLUSD"],
     approxGasCostUsd: 1.2,
-    note: "L1 \u2014 gas is volatile; quote is a snapshot, expect 5\u201310x swings during congestion."
+    note: "L1 \u2014 gas is volatile; quote is a snapshot, expect 5\u201310x swings during congestion. RLUSD supported here only."
   },
   xlayer: {
     key: "xlayer",
@@ -108,6 +114,7 @@ var CHAIN_CONFIG = {
     explorer: "https://www.oklink.com/xlayer",
     usdc: { address: "0x74b7F16337b8972027F6196A17a631aC6dE26d22", decimals: 6 },
     usdt: { address: "0x1E4a5963aBFD975d8c9021ce480b42188849D41D", decimals: 6 },
+    supportedTokens: ["USDC", "USDT"],
     approxGasCostUsd: 2e-3
   },
   stable: {
@@ -121,6 +128,7 @@ var CHAIN_CONFIG = {
     // USDT0 (the only token on Stable) — both USDC and USDT API tokens resolve here.
     usdc: { address: "0x779ded0c9e1022225f8e0630b35a9b54be713736", decimals: 18 },
     usdt: { address: "0x779ded0c9e1022225f8e0630b35a9b54be713736", decimals: 18 },
+    supportedTokens: ["USDC", "USDT"],
     approxGasCostUsd: 5e-4,
     note: "Gas is paid in USDT0; both USDC and USDT API inputs alias to USDT0."
   },
@@ -135,6 +143,7 @@ var CHAIN_CONFIG = {
     usdc: { address: "0x09Bc4E0D864854c6aFB6eB9A9cdF58aC190D0dF9", decimals: 6 },
     // USDT0 (LayerZero OFT) — Mantle ecosystem default since the 2025-11-27 migration.
     usdt: { address: "0x779Ded0c9e1022225f8E0630b35a9b54bE713736", decimals: 6 },
+    supportedTokens: ["USDC", "USDT"],
     approxGasCostUsd: 2e-3
   },
   injective: {
@@ -160,13 +169,23 @@ function getChain(key) {
   return cfg;
 }
 function tokenFor(cfg, token) {
+  if (token === "RLUSD") {
+    if (!cfg.rlusd) {
+      throw new Error(
+        `RLUSD is not supported on ${cfg.name} (key=${cfg.key}). RLUSD is currently Ethereum-only.`
+      );
+    }
+    return cfg.rlusd;
+  }
   return token === "USDC" ? cfg.usdc : cfg.usdt;
 }
 
 // src/tools/quote.ts
 var QuoteInputSchema = z.object({
   amount: z.string().regex(/^\d+(\.\d+)?$/, 'amount must be a positive decimal string like "5.00"').describe('Human-readable decimal amount the user intends to send (e.g. "5", "50.00").'),
-  token: z.enum(["USDC", "USDT"]).optional().describe("Optional token filter. When omitted, both stablecoin options are reported."),
+  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"]).optional().describe(
     "Optional chain filter. When omitted, all 7 chains are compared and ranked by gas cost."
   )
@@ -424,7 +443,9 @@ var PayInputSchema = z2.object({
   chain: z2.enum(["avax", "bnb", "eth", "xlayer", "stable", "mantle", "injective"]),
   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"]),
+  token: z2.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."
+  ),
   confirm: z2.literal(true).describe(
     "MUST be true. Prove the user explicitly approved this exact recipient and amount in the conversation right before this tool was called. Setting this to true on behalf of the user without confirmation is a violation of the tool contract."
   )
@@ -580,7 +601,7 @@ var ReceiptShape = z4.object({
   chain: z4.string(),
   payer: z4.string(),
   recipient: z4.string(),
-  token: z4.enum(["USDC", "USDT"]),
+  token: z4.enum(["USDC", "USDT", "RLUSD"]),
   tokenAmount: z4.string(),
   tokenAmountRaw: z4.string(),
   method: z4.enum(["eip7702", "eip3009", "eip7702_xlayer", "eip7702_stable"]),
@@ -658,7 +679,7 @@ function pageBase() {
 }
 async function runReceipt(input) {
   const apiBase = receiptApiBase();
-  let receiptId = input.receiptId ?? null;
+  const receiptId = input.receiptId ?? null;
   if (!receiptId && input.txHash) {
     return {
       receiptId: null,
@@ -713,19 +734,19 @@ async function runReceipt(input) {
 }
 var RECEIPT_TOOL = {
   name: "q402_receipt",
-  description: "Look up a Q402 Trust Receipt by its rct_\u2026 id and return the settlement record + a locally-verified ECDSA boolean (the tool re-runs the same hash recovery the receipt page does in the browser). Read-only; no API key required. Use after q402_pay to give the user a shareable verified-by-Q402 URL, or to independently verify a receipt id someone shared with you.",
+  description: "Look up a Q402 Trust Receipt by its rct_\u2026 receiptId and return the settlement record + a locally-verified ECDSA boolean (the tool re-runs the same canonical-JSON + EIP-191 recovery the receipt page does in the browser). Read-only; no API key required. Use after q402_pay to give the user a shareable verified-by-Q402 URL, or to independently verify a receipt id someone shared with you. **receiptId is required**; passing only txHash returns notFound (tx \u2192 receiptId lookup is reserved for a future release).",
   inputSchema: {
     type: "object",
     properties: {
       receiptId: {
         type: "string",
         pattern: "^rct_[0-9a-f]{24}$",
-        description: "Receipt id (rct_ + 24 hex chars). Returned by q402_pay; also visible at the end of any /receipt/ URL."
+        description: "Receipt id (rct_ + 24 hex chars). Returned by q402_pay; also visible at the end of any /receipt/ URL. This is the only path that resolves today."
       },
       txHash: {
         type: "string",
         pattern: "^0x[0-9a-fA-F]{64}$",
-        description: "Optional on-chain tx hash. Reserved for a future tx \u2192 receipt index; today the tool returns notFound when only txHash is given."
+        description: "Reserved for a future tx \u2192 receipt index. Today this is unimplemented and the tool returns notFound when only txHash is provided. Pass receiptId instead."
       }
     },
     additionalProperties: false
@@ -734,7 +755,7 @@ var RECEIPT_TOOL = {
 
 // src/index.ts
 var PACKAGE_NAME = "@quackai/q402-mcp";
-var PACKAGE_VERSION = "0.2.0";
+var PACKAGE_VERSION = "0.3.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.2.0",
-  "description": "MCP server for Q402 — gasless USDC and USDT payments across 7 EVM chains, callable directly from Claude Desktop and any other Model Context Protocol client.",
+  "version": "0.3.0",
+  "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": [
     "mcp",
@@ -12,6 +12,8 @@
     "stablecoin",
     "usdc",
     "usdt",
+    "rlusd",
+    "ripple",
     "gasless",
     "eip-7702",
     "payments",