aixyz 0.33.0 → 0.34.0

package/accepts.ts

@@ -1,32 +1,47 @@
 import { z } from "zod";
 import { FacilitatorClient, HTTPFacilitatorClient } from "@x402/core/server";
 
-export type Accepts = AcceptsX402 | AcceptsFree;
-
-export type AcceptsX402 = {
-  scheme: "exact";
-  price: string;
+const AcceptsX402Scheme = z.object({
+  scheme: z.literal("exact"),
+  price: z.string(),
   // TODO(kevin): update type to Network (`string:string`)
-  network?: string;
-  payTo?: string;
-};
-
-export type AcceptsFree = {
-  scheme: "free";
-};
-
-export const AcceptsScheme = z.discriminatedUnion("scheme", [
-  z.object({
-    scheme: z.literal("exact"),
-    price: z.string(),
-    network: z.string().optional(),
-    payTo: z.string().optional(),
-  }),
-  z.object({
-    scheme: z.literal("free"),
-  }),
+  network: z.string().optional(),
+  payTo: z.string().optional(),
+});
+
+/** Used for multiple accepts — explicit network is required to properly register schemes on the resource server. */
+const AcceptsX402EntryScheme = z.object({
+  scheme: z.literal("exact"),
+  price: z.string(),
+  network: z.string(),
+  payTo: z.string().optional(),
+});
+
+const AcceptsFreeScheme = z.object({
+  scheme: z.literal("free"),
+});
+
+export type AcceptsX402 = z.infer<typeof AcceptsX402Scheme>;
+export type AcceptsX402Entry = z.infer<typeof AcceptsX402EntryScheme>;
+export type AcceptsX402Multi = AcceptsX402Entry[];
+export type AcceptsFree = z.infer<typeof AcceptsFreeScheme>;
+export type Accepts = AcceptsX402 | AcceptsFree | AcceptsX402Multi;
+
+export const AcceptsScheme: z.ZodType<Accepts> = z.union([
+  z.discriminatedUnion("scheme", [AcceptsX402Scheme, AcceptsFreeScheme]),
+  z.array(AcceptsX402EntryScheme).min(1),
 ]);
 
+export function normalizeAcceptsX402(accepts: AcceptsX402 | AcceptsX402Multi): AcceptsX402[] {
+  return Array.isArray(accepts) ? accepts : [accepts];
+}
+
+export function isAcceptsPaid(accepts: Accepts): accepts is AcceptsX402 | AcceptsX402Multi {
+  if (Array.isArray(accepts))
+    return accepts.length > 0 && accepts.every((e) => e.scheme === "exact" && typeof e.network === "string");
+  return accepts.scheme === "exact";
+}
+
 export type { FacilitatorClient };
 
 export { HTTPFacilitatorClient };

package/app/index.ts

@@ -1,8 +1,8 @@
-import type { AcceptsX402 } from "../accepts";
+import { isAcceptsPaid, AcceptsScheme } from "../accepts";
+import type { Accepts } from "../accepts";
 import type { FacilitatorClient } from "@x402/core/server";
-import { type HttpMethod, type RouteHandler, type Middleware, type RouteEntry } from "./types";
+import { type HttpMethod, type RouteHandler, type Middleware, type RouteEntry, type RouteOptions } from "./types";
 import { PaymentGateway } from "./payment/payment";
-import { Network } from "@x402/core/types";
 import { getAixyzConfig } from "@aixyz/config";
 import { loadEnvConfig } from "@next/env";
 import { BasePlugin, type RegisterContext, type InitializeContext } from "./plugin";
@@ -37,7 +37,6 @@ export class AixyzApp {
 
     if (options?.facilitators) {
       this.payment = new PaymentGateway(options.facilitators, config);
-      this.payment.register((config.x402.network as Network) ?? "eip155:8453");
     }
   }
 
@@ -87,14 +86,21 @@ export class AixyzApp {
     return `${method} ${path}`;
   }
 
-  /** Register a route with an optional x402 payment requirement. */
-  route(method: HttpMethod, path: string, handler: RouteHandler, options?: { payment?: AcceptsX402 }): void {
+  /** Register a route with an optional x402 payment requirement. Free accepts are filtered out. */
+  route(method: HttpMethod, path: string, handler: RouteHandler, options?: RouteOptions): void {
     const key = this.getRouteKey(method, path);
+    if (options?.payment) {
+      const result = AcceptsScheme.safeParse(options.payment);
+      if (!result.success) {
+        throw new Error(`Invalid accepts config for route "${method} ${path}": ${result.error.message}`);
+      }
+    }
+    const payment = options?.payment && isAcceptsPaid(options.payment) ? options.payment : undefined;
     this.routes.set(key, {
       method,
       path,
       handler,
-      payment: options?.payment,
+      payment,
     });
   }
 

package/app/payment/payment.ts

@@ -8,7 +8,8 @@ import {
   type HTTPResponseInstructions,
 } from "@x402/core/http";
 import { ExactEvmScheme } from "@x402/evm/exact/server";
-import type { AcceptsX402 } from "../../accepts";
+import type { AcceptsX402, AcceptsX402Multi } from "../../accepts";
+import { normalizeAcceptsX402 } from "../../accepts";
 import { Network, PaymentPayload, PaymentRequirements } from "@x402/core/types";
 import { AixyzConfig } from "@aixyz/config";
 
@@ -78,29 +79,49 @@ export class PaymentGateway {
   /**
    * Add a payment-gated route. Must be called before initialize().
    */
-  addRoute(method: string, path: string, accepts: AcceptsX402): void {
+  addRoute(method: string, path: string, accepts: AcceptsX402 | AcceptsX402Multi): void {
     const pattern = this.getRouteKey(method, path);
+    const items = normalizeAcceptsX402(accepts);
     this.pendingRoutes.set(pattern, {
-      accepts: {
-        scheme: accepts.scheme,
-        payTo: accepts.payTo ?? this.config.x402.payTo,
-        price: accepts.price,
-        network: (accepts.network as Network) ?? (this.config.x402.network as Network),
-      },
+      accepts: items.map((a) => ({
+        scheme: a.scheme,
+        payTo: a.payTo ?? this.config.x402.payTo,
+        price: a.price,
+        network: (a.network as Network) ?? (this.config.x402.network as Network),
+      })),
     });
   }
 
   /**
-   * Initialize the payment gateway. Builds the x402HTTPResourceServer from registered routes.
+   * Initialize the payment gateway. Registers all required network schemes
+   * from pending routes, then builds the x402HTTPResourceServer.
    * Must be called after all routes are added.
    */
   async initialize(): Promise<void> {
+    this.registerNetworksFromRoutes();
     const routes: RoutesConfig =
       this.pendingRoutes.size > 0 ? Object.fromEntries(this.pendingRoutes) : { "* /*": { accepts: [] } };
     this.httpServer = new x402HTTPResourceServer(this.resourceServer, routes);
     await this.httpServer.initialize();
   }
 
+  private registerNetworksFromRoutes(): void {
+    const networks = new Set<Network>();
+    const defaultNetwork = (this.config.x402.network as Network) ?? ("eip155:8453" as Network);
+    networks.add(defaultNetwork);
+
+    for (const [, route] of this.pendingRoutes) {
+      const accepts = Array.isArray(route.accepts) ? route.accepts : [route.accepts];
+      for (const opt of accepts) {
+        if (opt.network) networks.add(opt.network as Network);
+      }
+    }
+
+    for (const network of networks) {
+      this.register(network);
+    }
+  }
+
   /**
    * Verify payment for a request. Returns a 402 Response if payment is required/invalid,
    * or null if the request is authorized to proceed.

package/app/plugin.ts

@@ -1,5 +1,4 @@
-import type { HttpMethod, RouteHandler, RouteEntry, Middleware } from "./types";
-import type { AcceptsX402 } from "../accepts";
+import type { HttpMethod, RouteHandler, RouteEntry, RouteOptions, Middleware } from "./types";
 import type { PaymentGateway } from "./payment/payment";
 
 /**
@@ -14,7 +13,7 @@ import type { PaymentGateway } from "./payment/payment";
  */
 export interface RegisterContext {
   /** Register a route on the application. Automatically tracked in `plugin.registeredRoutes`. */
-  route(method: HttpMethod, path: string, handler: RouteHandler, options?: { payment?: AcceptsX402 }): void;
+  route(method: HttpMethod, path: string, handler: RouteHandler, options?: RouteOptions): void;
   /** Append a middleware to the application's middleware chain. */
   use(middleware: Middleware): void;
 }

package/app/plugins/a2a.ts

@@ -250,7 +250,7 @@ export class A2APlugin extends BasePlugin {
         return Response.json(result);
       },
       {
-        payment: entry.exports.accepts.scheme === "exact" ? entry.exports.accepts : undefined,
+        payment: entry.exports.accepts,
       },
     );
   }

package/app/plugins/index-page/index.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { BasePlugin, type RegisterContext, type InitializeContext } from "../../plugin";
 import type { MCPPlugin } from "../mcp";
 import { renderHtml } from "./html";
+import { isAcceptsPaid } from "../../../accepts";
 
 export type AixyzConfigRuntime = ReturnType<typeof getAixyzConfigRuntime>;
 
@@ -141,7 +142,7 @@ export class IndexPagePlugin extends BasePlugin {
           protocol: "a2a",
           name,
           path: entry.path,
-          paid: entry.payment?.scheme === "exact",
+          paid: !!entry.payment, // only set for paid routes (free accepts filtered in AixyzApp.route())
         });
       }
     }
@@ -170,7 +171,7 @@ export class IndexPagePlugin extends BasePlugin {
           name: tool.name,
           path: "/mcp",
           description: tool.tool.description,
-          paid: tool.accepts?.scheme === "exact",
+          paid: tool.accepts ? isAcceptsPaid(tool.accepts) : false,
           inputSchema,
         });
       }

package/app/plugins/mcp.ts

@@ -4,9 +4,10 @@ import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/
 import { createPaymentWrapper } from "@x402/mcp";
 import { BasePlugin, type RegisterContext, type InitializeContext } from "../plugin";
 import type { Accepts } from "../../accepts";
-import { AcceptsScheme } from "../../accepts";
+import { AcceptsScheme, isAcceptsPaid, normalizeAcceptsX402 } from "../../accepts";
 import { getAixyzConfig, getAixyzConfigRuntime } from "../../config";
 import { Network } from "@x402/core/types";
+import { ExactEvmScheme } from "@x402/evm/exact/server";
 
 /**
  * MCP (Model Context Protocol) plugin. Collects tools and exposes them
@@ -83,21 +84,43 @@ export class MCPPlugin extends BasePlugin {
 
     const config = getAixyzConfig();
     const resourceServer = ctx.payment.resourceServer;
+    const defaultNetwork = (config.x402.network as Network) ?? ("eip155:8453" as Network);
+
+    // MCP payment operates via @x402/mcp wrappers independently of the HTTP payment
+    // middleware (PaymentGateway), so network schemes must be registered here separately.
+    // The default network is already registered by PaymentGateway.initialize() on the
+    // shared resourceServer — seed the set so we skip re-registering it.
+    const registeredNetworks = new Set<string>([defaultNetwork]);
+    for (const { accepts } of this.registeredTools) {
+      if (!accepts || !isAcceptsPaid(accepts)) continue;
+      for (const a of normalizeAcceptsX402(accepts)) {
+        const network = a.network ?? defaultNetwork;
+        if (!registeredNetworks.has(network)) {
+          registeredNetworks.add(network);
+          resourceServer.register(network as Network, new ExactEvmScheme());
+        }
+      }
+    }
 
     for (const { name, accepts } of this.registeredTools) {
-      if (accepts?.scheme !== "exact") continue;
-
-      const reqs = await resourceServer.buildPaymentRequirements({
-        scheme: accepts.scheme,
-        payTo: accepts.payTo ?? config.x402.payTo,
-        price: accepts.price,
-        network: (accepts.network as Network) ?? (config.x402.network as Network),
-      });
+      if (!accepts || !isAcceptsPaid(accepts)) continue;
+
+      const items = normalizeAcceptsX402(accepts);
+      const allReqs: Awaited<ReturnType<typeof resourceServer.buildPaymentRequirements>> = [];
+      for (const a of items) {
+        const reqs = await resourceServer.buildPaymentRequirements({
+          scheme: a.scheme,
+          payTo: a.payTo ?? config.x402.payTo,
+          price: a.price,
+          network: (a.network as Network) ?? defaultNetwork,
+        });
+        allReqs.push(...reqs);
+      }
 
       this.paymentWrappers.set(
         name,
         createPaymentWrapper(resourceServer, {
-          accepts: reqs,
+          accepts: allReqs,
           resource: { url: `mcp://tool/${name}` },
         }),
       );

package/app/types.ts

@@ -1,4 +1,4 @@
-import type { AcceptsX402 } from "../accepts";
+import type { Accepts, AcceptsX402, AcceptsX402Multi } from "../accepts";
 
 export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS";
 
@@ -6,9 +6,13 @@ export type RouteHandler = (request: Request) => Response | Promise<Response>;
 
 export type Middleware = (request: Request, next: () => Promise<Response>) => Response | Promise<Response>;
 
+export interface RouteOptions {
+  payment?: Accepts;
+}
+
 export interface RouteEntry {
   method: HttpMethod;
   path: string;
   handler: RouteHandler;
-  payment?: AcceptsX402;
+  payment?: AcceptsX402 | AcceptsX402Multi;
 }

package/docs/api-reference/accepts.mdx

@@ -6,18 +6,18 @@ description: "Payment configuration types and facilitator client for x402 gating
 Types and utilities for configuring x402 payment gating on agent and tool endpoints.
 
 ```typescript
-import type { Accepts, AcceptsX402, AcceptsFree } from "aixyz/accepts";
-import { HTTPFacilitatorClient, facilitator } from "aixyz/accepts";
+import type { Accepts, AcceptsX402, AcceptsX402Entry, AcceptsX402Multi, AcceptsFree } from "aixyz/accepts";
+import { HTTPFacilitatorClient, facilitator, normalizeAcceptsX402, isAcceptsPaid } from "aixyz/accepts";
 ```
 
 ## Types
 
 ### `Accepts`
 
-Union type for payment configuration:
+Union type for payment configuration. Supports a single payment option, free access, or an array of payment options for multi-network support:
 
 ```typescript
-type Accepts = AcceptsX402 | AcceptsFree;
+type Accepts = AcceptsX402 | AcceptsFree | AcceptsX402Multi;
 ```
 
 ### `AcceptsX402`
@@ -40,6 +40,34 @@ type AcceptsX402 = {
 | `network` | `string` | No       | CAIP-2 chain ID, overrides `x402.network` from config         |
 | `payTo`   | `string` | No       | EVM address to receive payment, overrides `x402.payTo` config |
 
+### `AcceptsX402Entry`
+
+A single payment option within a multi-accepts array. Same as `AcceptsX402` but `network` is **required** — the server needs an explicit network to register each payment scheme:
+
+```typescript
+type AcceptsX402Entry = {
+  scheme: "exact";
+  price: string;
+  network: string; // required
+  payTo?: string;
+};
+```
+
+| Field     | Type     | Required | Description                                                   |
+| --------- | -------- | -------- | ------------------------------------------------------------- |
+| `scheme`  | `string` | Yes      | Must be `"exact"`                                             |
+| `price`   | `string` | Yes      | USD price string (e.g. `"$0.005"`)                            |
+| `network` | `string` | Yes      | CAIP-2 chain ID — required for multi-accepts                  |
+| `payTo`   | `string` | No       | EVM address to receive payment, overrides `x402.payTo` config |
+
+### `AcceptsX402Multi`
+
+An array of payment entries, enabling multi-network support. Must contain at least one entry:
+
+```typescript
+type AcceptsX402Multi = AcceptsX402Entry[];
+```
+
 ### `AcceptsFree`
 
 No payment required:
@@ -52,6 +80,22 @@ type AcceptsFree = {
 
 ## Exports
 
+### `normalizeAcceptsX402`
+
+Converts a single or multi accepts value into a uniform array:
+
+```typescript
+function normalizeAcceptsX402(accepts: AcceptsX402 | AcceptsX402Multi): AcceptsX402[];
+```
+
+### `isAcceptsPaid`
+
+Type guard that returns `true` if the accepts config requires payment (i.e., is not `{ scheme: "free" }`):
+
+```typescript
+function isAcceptsPaid(accepts: Accepts): accepts is AcceptsX402 | AcceptsX402Multi;
+```
+
 ### `HTTPFacilitatorClient`
 
 Client for communicating with an x402 facilitator service. Re-exported from `@x402/core/server`.
@@ -74,12 +118,19 @@ import { facilitator } from "aixyz/accepts";
 
 ### `AcceptsScheme`
 
-Zod schema for validating `Accepts` objects at runtime:
+Zod schema for validating `Accepts` objects at runtime. Accepts a single object or an array of payment entries:
 
 ```typescript
 import { AcceptsScheme } from "aixyz/accepts";
 
+// Single accepts
 AcceptsScheme.parse({ scheme: "exact", price: "$0.005" });
+
+// Multiple accepts
+AcceptsScheme.parse([
+  { scheme: "exact", price: "$0.005", network: "eip155:8453" },
+  { scheme: "exact", price: "$0.005", network: "eip155:84532" },
+]);
 ```
 
 ## Usage
@@ -103,6 +154,21 @@ export const accepts: Accepts = {
 };
 ```
 
+### Multiple payment options
+
+Accept payment across multiple networks by passing an array. Each entry requires an explicit `network`:
+
+```typescript title="app/agent.ts"
+import type { Accepts } from "aixyz/accepts";
+
+export const accepts: Accepts = [
+  { scheme: "exact", price: "$0.005", network: "eip155:8453" },
+  { scheme: "exact", price: "$0.005", network: "eip155:84532" },
+];
+```
+
+All referenced networks are automatically registered with the payment gateway during initialization — no manual setup required.
+
 ### Custom facilitator
 
 Create `app/accepts.ts` to override the default facilitator:

package/docs/api-reference/agent.mdx

@@ -38,7 +38,7 @@ export default new ToolLoopAgent({
 | `accepts`      | `Accepts`       | No       | Payment config — gates the A2A `/agent` route                       |
 | `capabilities` | `Capabilities`  | No       | A2A capabilities — controls streaming and push notification support |
 
-When `accepts` is exported, the `/agent` endpoint requires x402 payment. Without it, the agent is not registered on the A2A endpoint.
+When `accepts` is exported, the `/agent` endpoint requires x402 payment. Without it, the agent is not registered on the A2A endpoint. `accepts` can also be an array of payment entries for [multi-network support](/getting-started/payments#multiple-payment-options).
 
 ## Capabilities
 

package/docs/api-reference/tools.mdx

@@ -28,10 +28,10 @@ export default tool({
 
 ## Exports
 
-| Export    | Type      | Required | Description                                   |
-| --------- | --------- | -------- | --------------------------------------------- |
-| `default` | `tool()`  | Yes      | The tool instance                             |
-| `accepts` | `Accepts` | No       | Payment config — gates the tool on MCP `/mcp` |
+| Export    | Type      | Required | Description                                                                                                                                  |
+| --------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `default` | `tool()`  | Yes      | The tool instance                                                                                                                            |
+| `accepts` | `Accepts` | No       | Payment config — gates the tool on MCP `/mcp`. Supports [array format](/getting-started/payments#multiple-payment-options) for multi-network |
 
 ## Conventions
 

package/docs/getting-started/agent-and-tools.mdx

@@ -43,6 +43,15 @@ The optional `accepts` named export controls [x402 payment](/getting-started/pay
 - Agents **with** `accepts` are registered on payment-gated A2A endpoints
 - Agents **without** `accepts` are not registered
 
+You can also pass an array to accept payment on multiple networks:
+
+```typescript
+export const accepts: Accepts = [
+  { scheme: "exact", price: "$0.005", network: "eip155:8453" },
+  { scheme: "exact", price: "$0.005", network: "eip155:84532" },
+];
+```
+
 ### `capabilities` Export
 
 The optional `capabilities` named export configures the A2A agent card's capabilities and controls how the executor runs your agent:
@@ -160,6 +169,8 @@ export const accepts: Accepts = { scheme: "exact", price: "$0.001" };
 export default tool({ ... });
 ```
 
+Tools also support [multiple payment options](/getting-started/payments#multiple-payment-options) via an array of accepts entries.
+
 ## Custom Server
 
 For full control over endpoint registration and middleware, create `app/server.ts`. This overrides auto-generation entirely:

package/docs/getting-started/payments.mdx

@@ -64,6 +64,37 @@ export const accepts: Accepts = {
 - Tool `accepts` gates the tool on the MCP `/mcp` endpoint
 - Agents and tools **without** `accepts` are not registered on protocol endpoints
 
+## Multiple Payment Options
+
+Accept payment across multiple networks by passing an array of payment entries. This lets clients pay on whichever network they prefer:
+
+```typescript
+export const accepts: Accepts = [
+  { scheme: "exact", price: "$0.005", network: "eip155:8453" }, // Base
+  { scheme: "exact", price: "$0.005", network: "eip155:84532" }, // Base Sepolia
+];
+```
+
+When using the array format, `network` is **required** on each entry so the server can register the correct payment scheme for each network.
+
+All referenced networks are automatically discovered and registered during server initialization — no manual configuration needed beyond the `accepts` export.
+
+This works for both agents and tools:
+
+```typescript
+// app/agent.ts — multi-network agent pricing
+export const accepts: Accepts = [
+  { scheme: "exact", price: "$0.01", network: "eip155:8453" },
+  { scheme: "exact", price: "$0.01", network: "eip155:1" },
+];
+
+// app/tools/premium-search.ts — multi-network tool pricing
+export const accepts: Accepts = [
+  { scheme: "exact", price: "$0.001", network: "eip155:8453" },
+  { scheme: "exact", price: "$0.001", network: "eip155:1" },
+];
+```
+
 ## Payment Networks
 
 Configure the payment network in `aixyz.config.ts`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aixyz",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "Payment-native SDK for AI Agent",
   "keywords": [
     "ai",
@@ -40,9 +40,9 @@
   },
   "dependencies": {
     "@a2a-js/sdk": "^0.3.10",
-    "@aixyz/cli": "0.33.0",
-    "@aixyz/config": "0.33.0",
-    "@aixyz/erc-8004": "0.33.0",
+    "@aixyz/cli": "0.34.0",
+    "@aixyz/config": "0.34.0",
+    "@aixyz/erc-8004": "0.34.0",
     "@kitajs/html": "^4.2.13",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@next/env": "^16.1.6",