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

# @armory-sh/middleware-next

x402 payment middleware for Next.js App Router.

## Installation

```bash theme={null}
# npm
npm install @armory-sh/middleware-next

# yarn
yarn add @armory-sh/middleware-next

# pnpm
pnpm add @armory-sh/middleware-next

# bun
bun add @armory-sh/middleware-next
```

## Features

* Per-route payment configuration
* Route pattern matching (exact, wildcard, parameterized)
* Resource server for payment scheme management
* Built-in verification integration
* Full TypeScript support

## Quick Start

```typescript theme={null}
// middleware.ts
import { paymentProxy, x402ResourceServer } from "@armory-sh/middleware-next";

const verificationClient = {
  async verify(headers: Headers) {
    return { success: true, payerAddress: "0x..." };
  },
};

const resourceServer = new x402ResourceServer(verificationClient);

export const proxy = paymentProxy(
  {
    "/api/protected": {
      accepts: {
        scheme: "exact",
        price: "1000000",
        network: "eip155:8453",
        payTo: "0xYourAddress...",
      },
    },
  },
  resourceServer
);

export const config = { matcher: ["/api/protected/:path*"] };
```

## API

### `paymentProxy(routes, resourceServer)`

Creates a payment proxy handler for Next.js middleware.

**Parameters:**

* `routes`: Record mapping route patterns to payment config
* `resourceServer`: x402ResourceServer instance

**Returns:** Next.js middleware function

### `x402ResourceServer`

Registers and manages payment schemes.

**Methods:**

* `register(chainId, scheme)`: Register a payment scheme
* `getRequirements(chainId)`: Get requirements for a chain
* `getAllRequirements()`: Get all registered requirements

### Types

```typescript theme={null}
interface VerificationClient {
  verify(headers: Headers): Promise<{
    success: boolean;
    payerAddress?: string;
    error?: string
  }>;
  settle?(headers: Headers): Promise<{
    success: boolean;
    txHash?: string;
    error?: string
  }>;
}

interface PaymentScheme {
  name: string;
  getRequirements(): PaymentRequirementsV2;
}

interface RoutePaymentConfig {
  accepts: {
    scheme: string;
    price: string;
    network: string;
    payTo: string;
  };
  description?: string;
}
```

## Route Patterns

Supports three types of route patterns:

* **Exact**: `/api/users` - matches only `/api/users`
* **Wildcard**: `/api/*` - matches `/api/users`, `/api/posts/123`
* **Parameterized**: `/api/users/:id` - matches `/api/users/123`

## Examples

See the [Next.js Middleware guide](../../accept-payments/next) for complete examples.

## Advanced Mix-and-Match Config (Current API)

If you are using `paymentMiddleware` directly, you can route by chain/token/facilitator and attach extensions:

```typescript theme={null}
import { paymentMiddleware } from "@armory-sh/middleware-next";

const middleware = paymentMiddleware({
  payTo: "0x1234567890123456789012345678901234567890",
  chains: ["base", "skale-base"],
  tokens: ["usdc", "usdt", "weth", "wbtc"],
  amount: "1.0",
  facilitatorUrl: "https://fallback-facilitator.example",
  facilitatorUrlByChain: {
    base: "https://payai.example",
  },
  facilitatorUrlByToken: {
    base: { usdc: "https://payai.example" },
    "skale-base": {
      usdc: "https://payai.example",
      usdt: "https://kobaru.example",
      weth: "https://kobaru.example",
      wbtc: "https://kobaru.example",
    },
  },
  extensions: {
    bazaar: { info: { input: { sku: "pro-plan" } }, schema: { type: "object" } },
    "sign-in-with-x": { info: { domain: "api.example.com" }, schema: { type: "object" } },
  },
});
```

For mixed amounts per route/combination, use explicit `requirements` arrays:

```typescript theme={null}
paymentMiddleware({
  requirements: [
    {
      scheme: "exact",
      network: "eip155:8453",
      amount: "1000000",
      asset: "0x833589fCD6eDb6E08f4c7C32D4f71B54bdA02913",
      payTo: "0x1234567890123456789012345678901234567890",
      maxTimeoutSeconds: 300,
    },
    {
      scheme: "exact",
      network: "eip155:1187947933",
      amount: "2500000",
      asset: "0x5f9beea3f6f22be1f4f8efc120f5095f58dbb8a2",
      payTo: "0x1234567890123456789012345678901234567890",
      maxTimeoutSeconds: 300,
    },
  ],
  facilitatorUrlByToken: {
    base: { usdc: "https://payai.example" },
    "skale-base": { usdt: "https://kobaru.example" },
  },
});
```

Unsupported extension keys are fail-open filtered out per facilitator capability response.