@routexcc/x402 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thalaxis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# @routexcc/x402
+
+x402 middleware wrapper for Routex.
+
+## Install
+
+```bash
+npm install @routexcc/x402
+```
+
+## Usage
+
+```ts
+import { routexMiddleware, handlePaymentRequired } from "@routexcc/x402";
+import { createRouter } from "@routexcc/core";
+
+const router = createRouter({ chains: [baseAdapter] });
+
+// Express middleware
+app.use(routexMiddleware({ router }));
+
+// Or handle 402 responses directly
+const response = await handlePaymentRequired(req, {
+  router,
+  amount: "1.00",
+  currency: "USDC",
+});
+```
+
+## Documentation
+
+See the [main repo README](https://github.com/routexcc/routex) for full documentation.
+
+Part of the [Routex](https://github.com/routexcc/routex) monorepo by [Thalaxis](https://thalaxis.com).
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,109 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  routexMiddleware: () => routexMiddleware
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/middleware.ts
+var import_core = require("@routexcc/core");
+function routexMiddleware(config) {
+  const router = (0, import_core.createRouter)(config.routeConfig);
+  return {
+    router,
+    async handlePaymentRequired(response) {
+      const routeResult = await router.route(response.paymentRequirement, config.signer);
+      if (config.onRouteSelected) {
+        config.onRouteSelected(routeResult);
+      }
+      return {
+        payload: routeResult.payload,
+        routeResult
+      };
+    },
+    parseResponse(status, body) {
+      if (status !== 402) {
+        return void 0;
+      }
+      const paymentRequirement = parsePaymentRequirement(body);
+      if (!paymentRequirement) {
+        return void 0;
+      }
+      return {
+        status: 402,
+        paymentRequirement
+      };
+    }
+  };
+}
+function parsePaymentRequirement(body) {
+  const source = body["paymentRequirement"] ?? body;
+  const chains = source["acceptedChains"];
+  if (!Array.isArray(chains) || chains.length === 0) {
+    return void 0;
+  }
+  const acceptedChains = [];
+  for (const chain of chains) {
+    if (typeof chain !== "object" || chain === null) {
+      continue;
+    }
+    const entry = chain;
+    const chainId = entry["chainId"];
+    const payTo = entry["payTo"];
+    const amount = entry["amount"];
+    const token = entry["token"];
+    if (typeof chainId !== "string" || typeof payTo !== "string" || typeof token !== "string") {
+      continue;
+    }
+    let parsedAmount;
+    if (typeof amount === "bigint") {
+      parsedAmount = amount;
+    } else if (typeof amount === "string") {
+      try {
+        parsedAmount = BigInt(amount);
+      } catch {
+        continue;
+      }
+    } else if (typeof amount === "number" && Number.isInteger(amount)) {
+      parsedAmount = BigInt(amount);
+    } else {
+      continue;
+    }
+    const extra = typeof entry["extra"] === "object" && entry["extra"] !== null ? entry["extra"] : void 0;
+    acceptedChains.push({
+      chainId,
+      payTo,
+      // BigInt: token amounts must never use floating point
+      amount: parsedAmount,
+      token,
+      ...extra ? { extra } : {}
+    });
+  }
+  if (acceptedChains.length === 0) {
+    return void 0;
+  }
+  return { acceptedChains };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  routexMiddleware
+});

package/dist/index.d.cts

@@ -0,0 +1,117 @@
+import { PaymentPayload, RouteResult, PaymentRequirement, Router, RouteConfig, Signer, RouteExhaustedError } from '@routexcc/core';
+
+/**
+ * Configuration for the Routex x402 middleware.
+ */
+interface RoutexMiddlewareConfig {
+    /** Full Routex route configuration. */
+    readonly routeConfig: RouteConfig;
+    /** Signer instance for signing payment payloads. */
+    readonly signer: Signer;
+    /**
+     * Optional callback invoked after a successful route selection.
+     * Can be used for logging or telemetry.
+     */
+    readonly onRouteSelected?: (result: RouteResult) => void;
+    /**
+     * Optional callback invoked when routing fails.
+     * The caller can use this to fall back to direct payment.
+     */
+    readonly onRouteFailed?: (error: RoutexError) => void;
+}
+/** Re-export for convenience in error handling callbacks. */
+type RoutexError = RouteExhaustedError | Error;
+/**
+ * A parsed 402 response containing payment requirements.
+ */
+interface ParsedX402Response {
+    /** HTTP status code (should be 402). */
+    readonly status: number;
+    /** Payment requirements extracted from the 402 response body. */
+    readonly paymentRequirement: PaymentRequirement;
+}
+/**
+ * Result of the middleware processing a 402 response.
+ */
+interface MiddlewareResult {
+    /** The constructed payment payload ready for submission to the facilitator. */
+    readonly payload: PaymentPayload;
+    /** The full route result with scoring details. */
+    readonly routeResult: RouteResult;
+}
+/**
+ * The Routex x402 middleware instance.
+ */
+interface RoutexMiddleware {
+    /**
+     * Handle a 402 response by routing and building a payment payload.
+     *
+     * @param response - The parsed 402 response with payment requirements.
+     * @returns The payment payload and route details.
+     * @throws {RouteExhaustedError} When no eligible route is found.
+     * @throws {PaymentConstructionError} When payload construction fails.
+     *
+     * @example
+     * ```typescript
+     * const result = await middleware.handlePaymentRequired(parsed402);
+     * // Forward result.payload to the facilitator
+     * ```
+     */
+    handlePaymentRequired(response: ParsedX402Response): Promise<MiddlewareResult>;
+    /**
+     * Parse a raw HTTP response into a ParsedX402Response.
+     * Returns undefined if the response is not a 402.
+     *
+     * @param status - HTTP status code.
+     * @param body - Response body (JSON-parsed).
+     * @returns Parsed 402 response, or undefined if not a 402.
+     *
+     * @example
+     * ```typescript
+     * const parsed = middleware.parseResponse(402, responseBody);
+     * if (parsed) {
+     *   const result = await middleware.handlePaymentRequired(parsed);
+     * }
+     * ```
+     */
+    parseResponse(status: number, body: Record<string, unknown>): ParsedX402Response | undefined;
+    /** The underlying router instance. */
+    readonly router: Router;
+}
+/**
+ * Create a Routex x402 middleware instance.
+ *
+ * Intercepts 402 Payment Required responses, extracts payment requirements,
+ * selects the optimal chain via the Routex router, and builds a signed
+ * payment payload for submission to the facilitator.
+ *
+ * @param config - Middleware configuration including route config and signer.
+ * @returns A middleware instance for handling 402 responses.
+ * @throws {Error} When config is missing required fields.
+ *
+ * @example
+ * ```typescript
+ * import { routexMiddleware } from '@routexcc/x402';
+ * import { createBaseAdapter } from '@routexcc/chain-base';
+ *
+ * const middleware = routexMiddleware({
+ *   routeConfig: {
+ *     adapters: new Map([['base', createBaseAdapter(client)]]),
+ *     feeOracle: oracle,
+ *     strategy: 'cheapest',
+ *     maxFeeAgeMs: 60_000,
+ *   },
+ *   signer: mySigner,
+ * });
+ *
+ * // In your HTTP client interceptor:
+ * const parsed = middleware.parseResponse(response.status, response.data);
+ * if (parsed) {
+ *   const { payload } = await middleware.handlePaymentRequired(parsed);
+ *   // Forward payload to facilitator
+ * }
+ * ```
+ */
+declare function routexMiddleware(config: RoutexMiddlewareConfig): RoutexMiddleware;
+
+export { type MiddlewareResult, type ParsedX402Response, type RoutexMiddleware, type RoutexMiddlewareConfig, routexMiddleware };

package/dist/index.d.ts

@@ -0,0 +1,117 @@
+import { PaymentPayload, RouteResult, PaymentRequirement, Router, RouteConfig, Signer, RouteExhaustedError } from '@routexcc/core';
+
+/**
+ * Configuration for the Routex x402 middleware.
+ */
+interface RoutexMiddlewareConfig {
+    /** Full Routex route configuration. */
+    readonly routeConfig: RouteConfig;
+    /** Signer instance for signing payment payloads. */
+    readonly signer: Signer;
+    /**
+     * Optional callback invoked after a successful route selection.
+     * Can be used for logging or telemetry.
+     */
+    readonly onRouteSelected?: (result: RouteResult) => void;
+    /**
+     * Optional callback invoked when routing fails.
+     * The caller can use this to fall back to direct payment.
+     */
+    readonly onRouteFailed?: (error: RoutexError) => void;
+}
+/** Re-export for convenience in error handling callbacks. */
+type RoutexError = RouteExhaustedError | Error;
+/**
+ * A parsed 402 response containing payment requirements.
+ */
+interface ParsedX402Response {
+    /** HTTP status code (should be 402). */
+    readonly status: number;
+    /** Payment requirements extracted from the 402 response body. */
+    readonly paymentRequirement: PaymentRequirement;
+}
+/**
+ * Result of the middleware processing a 402 response.
+ */
+interface MiddlewareResult {
+    /** The constructed payment payload ready for submission to the facilitator. */
+    readonly payload: PaymentPayload;
+    /** The full route result with scoring details. */
+    readonly routeResult: RouteResult;
+}
+/**
+ * The Routex x402 middleware instance.
+ */
+interface RoutexMiddleware {
+    /**
+     * Handle a 402 response by routing and building a payment payload.
+     *
+     * @param response - The parsed 402 response with payment requirements.
+     * @returns The payment payload and route details.
+     * @throws {RouteExhaustedError} When no eligible route is found.
+     * @throws {PaymentConstructionError} When payload construction fails.
+     *
+     * @example
+     * ```typescript
+     * const result = await middleware.handlePaymentRequired(parsed402);
+     * // Forward result.payload to the facilitator
+     * ```
+     */
+    handlePaymentRequired(response: ParsedX402Response): Promise<MiddlewareResult>;
+    /**
+     * Parse a raw HTTP response into a ParsedX402Response.
+     * Returns undefined if the response is not a 402.
+     *
+     * @param status - HTTP status code.
+     * @param body - Response body (JSON-parsed).
+     * @returns Parsed 402 response, or undefined if not a 402.
+     *
+     * @example
+     * ```typescript
+     * const parsed = middleware.parseResponse(402, responseBody);
+     * if (parsed) {
+     *   const result = await middleware.handlePaymentRequired(parsed);
+     * }
+     * ```
+     */
+    parseResponse(status: number, body: Record<string, unknown>): ParsedX402Response | undefined;
+    /** The underlying router instance. */
+    readonly router: Router;
+}
+/**
+ * Create a Routex x402 middleware instance.
+ *
+ * Intercepts 402 Payment Required responses, extracts payment requirements,
+ * selects the optimal chain via the Routex router, and builds a signed
+ * payment payload for submission to the facilitator.
+ *
+ * @param config - Middleware configuration including route config and signer.
+ * @returns A middleware instance for handling 402 responses.
+ * @throws {Error} When config is missing required fields.
+ *
+ * @example
+ * ```typescript
+ * import { routexMiddleware } from '@routexcc/x402';
+ * import { createBaseAdapter } from '@routexcc/chain-base';
+ *
+ * const middleware = routexMiddleware({
+ *   routeConfig: {
+ *     adapters: new Map([['base', createBaseAdapter(client)]]),
+ *     feeOracle: oracle,
+ *     strategy: 'cheapest',
+ *     maxFeeAgeMs: 60_000,
+ *   },
+ *   signer: mySigner,
+ * });
+ *
+ * // In your HTTP client interceptor:
+ * const parsed = middleware.parseResponse(response.status, response.data);
+ * if (parsed) {
+ *   const { payload } = await middleware.handlePaymentRequired(parsed);
+ *   // Forward payload to facilitator
+ * }
+ * ```
+ */
+declare function routexMiddleware(config: RoutexMiddlewareConfig): RoutexMiddleware;
+
+export { type MiddlewareResult, type ParsedX402Response, type RoutexMiddleware, type RoutexMiddlewareConfig, routexMiddleware };

package/dist/index.mjs

@@ -0,0 +1,82 @@
+// src/middleware.ts
+import { createRouter } from "@routexcc/core";
+function routexMiddleware(config) {
+  const router = createRouter(config.routeConfig);
+  return {
+    router,
+    async handlePaymentRequired(response) {
+      const routeResult = await router.route(response.paymentRequirement, config.signer);
+      if (config.onRouteSelected) {
+        config.onRouteSelected(routeResult);
+      }
+      return {
+        payload: routeResult.payload,
+        routeResult
+      };
+    },
+    parseResponse(status, body) {
+      if (status !== 402) {
+        return void 0;
+      }
+      const paymentRequirement = parsePaymentRequirement(body);
+      if (!paymentRequirement) {
+        return void 0;
+      }
+      return {
+        status: 402,
+        paymentRequirement
+      };
+    }
+  };
+}
+function parsePaymentRequirement(body) {
+  const source = body["paymentRequirement"] ?? body;
+  const chains = source["acceptedChains"];
+  if (!Array.isArray(chains) || chains.length === 0) {
+    return void 0;
+  }
+  const acceptedChains = [];
+  for (const chain of chains) {
+    if (typeof chain !== "object" || chain === null) {
+      continue;
+    }
+    const entry = chain;
+    const chainId = entry["chainId"];
+    const payTo = entry["payTo"];
+    const amount = entry["amount"];
+    const token = entry["token"];
+    if (typeof chainId !== "string" || typeof payTo !== "string" || typeof token !== "string") {
+      continue;
+    }
+    let parsedAmount;
+    if (typeof amount === "bigint") {
+      parsedAmount = amount;
+    } else if (typeof amount === "string") {
+      try {
+        parsedAmount = BigInt(amount);
+      } catch {
+        continue;
+      }
+    } else if (typeof amount === "number" && Number.isInteger(amount)) {
+      parsedAmount = BigInt(amount);
+    } else {
+      continue;
+    }
+    const extra = typeof entry["extra"] === "object" && entry["extra"] !== null ? entry["extra"] : void 0;
+    acceptedChains.push({
+      chainId,
+      payTo,
+      // BigInt: token amounts must never use floating point
+      amount: parsedAmount,
+      token,
+      ...extra ? { extra } : {}
+    });
+  }
+  if (acceptedChains.length === 0) {
+    return void 0;
+  }
+  return { acceptedChains };
+}
+export {
+  routexMiddleware
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@routexcc/x402",
+  "version": "1.0.0",
+  "description": "x402 middleware wrapper for Routex",
+  "license": "MIT",
+  "author": "Thalaxis <opensource@thalaxis.com> (https://thalaxis.com)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/routexcc/routex.git",
+    "directory": "packages/x402"
+  },
+  "homepage": "https://github.com/routexcc/routex#readme",
+  "bugs": {
+    "url": "https://github.com/routexcc/routex/issues"
+  },
+  "keywords": [
+    "x402",
+    "middleware",
+    "payment",
+    "402",
+    "routex"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@routexcc/core": "1.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0",
+    "@vitest/coverage-v8": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean --no-sourcemap",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "clean": "rm -rf dist coverage"
+  }
+}