aixyz/app - aixyz

AixyzApp is a framework-agnostic server that manages route registration, middleware chaining, and optional x402 payment gating via a PaymentGateway. It uses web-standard Request/Response — no Express dependency.

import { AixyzApp } from "aixyz/app";

Constructor

new AixyzApp(options?: AixyzAppOptions)

Parameter	Type	Default	Description
`options.facilitators`	`FacilitatorClient \| FacilitatorClient[]`	—	Payment verification service(s)

When facilitators is provided, a PaymentGateway is created and x402 payment verification is enabled for routes that declare a payment option. After constructing, register plugins with await server.withPlugin(...), then call await server.initialize() to finalize payment routes.

Properties

Property	Type	Description
`routes`	`Map<string, RouteEntry>`	Registered routes, keyed by `"METHOD /path"`
`payment`	`PaymentGateway \| undefined`	Payment gateway (present when facilitators provided)

Methods

`route(method, path, handler, options?)`

server.route("POST", "/agent", handler, {
  payment: { scheme: "exact", price: "$0.005" },
});

Parameter	Type	Description
`method`	`HttpMethod`	HTTP method (GET, POST, etc.)
`path`	`string`	Route path
`handler`	`RouteHandler`	`(request: Request) => Response \| Promise<Response>`
`options.payment`	`AcceptsX402`	Optional payment configuration

`fetch(request)`

Dispatch a web-standard Request through payment verification, middleware chain, and route handler:

const response = await server.fetch(new Request("http://localhost/agent", { method: "POST" }));

`use(middleware)`

Append a middleware to the chain. Middlewares run in registration order before the route handler:

server.use(async (request, next) => {
  const response = await next();
  return new Response(await response.text(), {
    status: response.status,
    headers: { ...Object.fromEntries(response.headers), "x-custom": "value" },
  });
});

`withPlugin(plugin)`

Register a plugin. Creates a scoped RegisterContext that auto-tracks routes in plugin.registeredRoutes, calls plugin.register(ctx), and returns this for chaining:

await server.withPlugin(new IndexPagePlugin());

`initialize()`

Initialize payment gateway and plugins. Passes an InitializeContext with read access to all routes, registered plugins, and payment gateway. Must be called after all plugins are registered:

await server.initialize();

Example

app/server.ts

import { AixyzApp } from "aixyz/app";
import { SessionPlugin } from "aixyz/app/plugins/session";
import { IndexPagePlugin } from "aixyz/app/plugins/index-page";
import { A2APlugin } from "aixyz/app/plugins/a2a";
import * as agent from "./agent";

const server = new AixyzApp();

// SessionPlugin must be registered first so its middleware runs before other plugins
await server.withPlugin(new SessionPlugin());
await server.withPlugin(new IndexPagePlugin());
await server.withPlugin(new A2APlugin([{ exports: agent }]));

await server.initialize();

export default server;

​Constructor

​Properties

​Methods

​route(method, path, handler, options?)

​fetch(request)

​use(middleware)

​withPlugin(plugin)

​initialize()

​Example