@quackai/q402-mcp 0.8.10 → 0.8.12

package/README.md

@@ -288,6 +288,14 @@ Single transfers and multi-recipient batches ship today. The next layer — recu
 
 ---
 
+## Hooks — programmable payment policies
+
+Q402 Hooks 1.0 is a policy engine that attaches rules to the payment lifecycle: OFAC compliance screening, spend caps + recipient allowlists, ERC-8004 reputation gating, Chainlink-oracle conditional settlement ("only when BTC ≥ $80k"), and automatic multi-payee splits — plus human-in-the-loop approval holds. Uniswap v4 brought programmable hooks to DEX liquidity; Q402 brings them to AI-agent payments.
+
+**Developer reference: [docs/HOOKS.md](docs/HOOKS.md)** — lifecycle, the Hook contract, every shipped hook with config + examples.
+
+---
+
 ## Repository
 
 Source code: https://github.com/bitgett/q402-mcp

package/dist/index.js

@@ -211,7 +211,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.8.10";
+var PACKAGE_VERSION = "0.8.12";
 
 // src/tools/quote.ts
 import { z } from "zod";
@@ -874,6 +874,18 @@ When MORE THAN ONE wallet is configured in the user's environment, you MUST ask
   ),
   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."
+  ),
+  hookParams: z2.object({
+    recipientAgentId: z2.string().optional().describe("ReputationGate: the recipient's ERC-8004 agent id."),
+    condition: z2.object({
+      kind: z2.enum(["price", "timestamp"]),
+      feed: z2.string().optional().describe('Chainlink feed pair for kind="price", e.g. "BTC/USD".'),
+      op: z2.enum([">=", "<=", ">", "<", "after", "before"]),
+      value: z2.number().describe('USD price (kind="price") or unix seconds (kind="timestamp").')
+    }).optional().describe('ConditionalOracle: settle only when this condition holds, e.g. { kind:"price", feed:"BTC/USD", op:">=", value:80000 }.'),
+    splits: z2.array(z2.object({ recipient: z2.string(), bps: z2.number() })).optional().describe("MultiPayeeSplit: per-payment N-way split; bps must sum to 10000.")
+  }).optional().describe(
+    'Q402 Hook parameters (server-managed Agent Wallet path only). Attaches per-payment hook conditions: a ConditionalOracle price/time gate, a MultiPayeeSplit fan-out, or a ReputationGate recipient agent id. Honoured only on walletMode="agentic-server".'
   )
 });
 function maxAmountGuard(amount, cap) {
@@ -1050,7 +1062,12 @@ async function runPay(input) {
           token: input.token,
           to: input.to,
           amount: input.amount,
-          ...explicitWalletId ? { walletId: explicitWalletId } : {}
+          ...explicitWalletId ? { walletId: explicitWalletId } : {},
+          // Q402 Hook params — only the Mode C (agentic-server) path runs
+          // the per-wallet hook dispatch, so forwarding here is the only
+          // place hookParams take effect. The landing route ignores them
+          // for owner-sig calls (trust boundary), so this is safe.
+          ...input.hookParams ? { hookParams: input.hookParams } : {}
         }),
         signal: AbortSignal.timeout(6e4)
       });
@@ -1220,6 +1237,31 @@ var PAY_TOOL = {
         type: "boolean",
         const: true,
         description: "MUST be true and only set after the user has confirmed recipient + amount in chat."
+      },
+      hookParams: {
+        type: "object",
+        description: "Q402 Hook params (server-managed Agent Wallet only). recipientAgentId (ReputationGate), condition (ConditionalOracle price/time gate), or splits (MultiPayeeSplit fan-out, bps sum 10000).",
+        properties: {
+          recipientAgentId: { type: "string" },
+          condition: {
+            type: "object",
+            properties: {
+              kind: { type: "string", enum: ["price", "timestamp"] },
+              feed: { type: "string" },
+              op: { type: "string", enum: [">=", "<=", ">", "<", "after", "before"] },
+              value: { type: "number" }
+            },
+            required: ["kind", "op", "value"]
+          },
+          splits: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: { recipient: { type: "string" }, bps: { type: "number" } },
+              required: ["recipient", "bps"]
+            }
+          }
+        }
       }
     },
     required: ["chain", "to", "amount", "token", "confirm"],
@@ -3900,8 +3942,11 @@ async function main() {
       RECURRING_CANCEL_TOOL,
       CLEAR_DELEGATION_TOOL,
       // CCIP bridge surface — USDC routing on the eth/avax/arbitrum
-      // triangle. Bridge_send is sandbox-only; live execution happens
-      // through the dashboard until session-binding ships.
+      // triangle. Bridge_send goes LIVE on Mode C since 0.8.10 (Mode A/B
+      // still fall through to sandbox since the route's API-key auth
+      // path only exists for the server-managed Agent Wallet). History
+      // + Gas Tank tools remain dashboard-pointer until session-binding
+      // exposes owner-sig auth from MCP.
       BRIDGE_QUOTE_TOOL,
       BRIDGE_SEND_TOOL,
       BRIDGE_HISTORY_TOOL,

package/package.json

@@ -1,75 +1,75 @@
-{
-  "name": "@quackai/q402-mcp",
-  "version": "0.8.10",
-  "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": [
-    "mcp",
-    "model-context-protocol",
-    "claude",
-    "claude-desktop",
-    "claude-code",
-    "codex",
-    "openai-codex",
-    "cline",
-    "q402",
-    "x402",
-    "stablecoin",
-    "usdc",
-    "usdt",
-    "rlusd",
-    "ripple",
-    "gasless",
-    "eip-7702",
-    "payments",
-    "ai-agents"
-  ],
-  "type": "module",
-  "main": "dist/index.js",
-  "bin": {
-    "q402-mcp": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=18.18"
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "lint": "tsc --noEmit",
-    "prepublishOnly": "npm run lint && npm run build",
-    "start": "node dist/index.js"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "ethers": "^6.16.0",
-    "zod": "^3.23.8"
-  },
-  "devDependencies": {
-    "@types/node": "^20.11.0",
-    "tsup": "^8.3.0",
-    "typescript": "^5.5.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/bitgett/q402-mcp.git"
-  },
-  "homepage": "https://q402.quackai.ai/claude",
-  "bugs": {
-    "url": "https://github.com/bitgett/q402-mcp/issues"
-  },
-  "license": "Apache-2.0",
-  "author": "David Lee <davidlee@quackai.ai>",
-  "publishConfig": {
-    "access": "public"
-  },
-  "overrides": {
-    "ws": "^8.20.1",
-    "qs": "^6.15.2",
-    "hono": "^4.12.21"
-  }
-}
+{
+  "name": "@quackai/q402-mcp",
+  "version": "0.8.12",
+  "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": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "claude-desktop",
+    "claude-code",
+    "codex",
+    "openai-codex",
+    "cline",
+    "q402",
+    "x402",
+    "stablecoin",
+    "usdc",
+    "usdt",
+    "rlusd",
+    "ripple",
+    "gasless",
+    "eip-7702",
+    "payments",
+    "ai-agents"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "q402-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run lint && npm run build",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "ethers": "^6.16.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.5.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bitgett/q402-mcp.git"
+  },
+  "homepage": "https://q402.quackai.ai/claude",
+  "bugs": {
+    "url": "https://github.com/bitgett/q402-mcp/issues"
+  },
+  "license": "Apache-2.0",
+  "author": "David Lee <davidlee@quackai.ai>",
+  "publishConfig": {
+    "access": "public"
+  },
+  "overrides": {
+    "ws": "^8.20.1",
+    "qs": "^6.15.2",
+    "hono": "^4.12.21"
+  }
+}