> ## Documentation Index
> Fetch the complete documentation index at: https://aixyz.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# aixyz/app

> The core application class built on web-standard Request/Response

`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.

```typescript theme={null}
import { AixyzApp } from "aixyz/app";
```

## Constructor

```typescript theme={null}
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?)`

Register a route with an optional x402 payment requirement:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
await server.initialize();
```

## Example

```typescript title="app/server.ts" theme={null}
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;
```