x402-avm/next Reference

@x402-avm/next Reference

Detailed API reference for the x402-avm Next.js integration package.

Dependencies

{
  "dependencies": {
    "@x402-avm/next": "latest",
    "@x402-avm/core": "latest",
    "@x402-avm/avm": "latest",
    "next": ">=14.0.0"
  }
}

For paywall UI:

{
  "dependencies": {
    "@x402-avm/paywall": "latest"
  }
}

Package Exports: @x402-avm/next

paymentProxyFromConfig

The simplest proxy setup. Creates the x402ResourceServer internally.

function paymentProxyFromConfig(
  routes: Record<string, RouteDefinition>,
  facilitatorClient: HTTPFacilitatorClient,
  paywallConfig?: PaywallConfig,
): (request: NextRequest) => Promise<NextResponse>;

Parameters

Route Pattern Format

Route patterns follow the format "METHOD /path/pattern":

paymentProxy

Create proxy with a pre-configured x402ResourceServer.

function paymentProxy(
  routes: Record<string, RouteDefinition>,
  server: x402ResourceServer,
  paywallConfig?: PaywallConfig,
): (request: NextRequest) => Promise<NextResponse>;

Parameters

paymentProxyFromHTTPServer

Most advanced proxy variant. Uses an x402HTTPResourceServer for HTTP-level hooks.

function paymentProxyFromHTTPServer(
  httpServer: x402HTTPResourceServer,
): (request: NextRequest) => Promise<NextResponse>;

Parameters

withX402

Wrap an individual route handler with payment protection.

function withX402(
  handler: (request: NextRequest) => Promise<NextResponse>,
  routeConfig: RouteDefinition,
  server: x402ResourceServer,
): (request: NextRequest) => Promise<NextResponse>;

Parameters

Settlement Behavior

• Payment is verified before the handler executes
• Payment is settled only if the handler returns a response with status < 400
• If the handler returns 4xx or 5xx, payment is not settled (user is not charged)

withX402FromHTTPServer

Wrap a route handler using an x402HTTPResourceServer with hooks.

function withX402FromHTTPServer(
  handler: (request: NextRequest) => Promise<NextResponse>,
  httpServer: x402HTTPResourceServer,
): (request: NextRequest) => Promise<NextResponse>;

Parameters

RouteDefinition

interface RouteDefinition {
  accepts: AcceptsConfig | AcceptsConfig[];
  description?: string;
  mimeType?: string;
  customPaywallHtml?: string;
  unpaidResponseBody?: (context: RequestContext) => {
    contentType: string;
    body: unknown;
  };
}

AcceptsConfig

interface AcceptsConfig {
  scheme: "exact";
  network: string;          // CAIP-2 identifier
  payTo: string;             // Algorand address (58 chars)
  price: string;             // Dollar amount, e.g., "$0.01", "$1.00"
  extra?: {
    asset?: string;          // ASA ID for token payments
  };
}

Price Format

The price field uses dollar notation:

PaywallConfig

interface PaywallConfig {
  title?: string;
  description?: string;
  logoUrl?: string;
}

Used by the proxy pattern to render a browser-friendly paywall page when the request's Accept header includes text/html.

x402HTTPResourceServer Hooks

onProtectedRequest

Register a hook that runs before payment processing.

httpServer.onProtectedRequest(async (context, routeConfig) => {
  // Return { grantAccess: true } to skip payment
  // Return { abort: true, reason: string } to reject the request
  // Return undefined to continue to payment flow
});

Hook Return Values

Middleware Configuration

middleware.ts Placement

The middleware.ts file must be at the project root (next to app/):

my-project/
  middleware.ts    <-- here
  app/
    page.tsx
    api/
      ...

Matcher Configuration

Always specify which routes the middleware should intercept:

export const config = {
  matcher: "/api/:path*",            // All API routes
};

// Or specific routes:
export const config = {
  matcher: [
    "/api/weather/:path*",
    "/api/premium/:path*",
    "/premium-article",
  ],
};

Matcher Patterns

Proxy Pattern vs. withX402 Comparison

Proxy Pattern Variants

withX402 Pattern Variants

Environment Variables

CAIP-2 Network Identifiers

USDC ASA IDs

Shared Config Pattern

For projects using the withX402 pattern across multiple routes, create a shared config module:

lib/
  x402.ts          <-- shared x402Server, PAY_TO, NETWORK
app/
  api/
    weather/route.ts    <-- imports from @/lib/x402
    premium/route.ts    <-- imports from @/lib/x402
    generate/route.ts   <-- imports from @/lib/x402

The shared module creates and configures the x402ResourceServer once, and exports it along with common constants.

Testing

1. Start with Algorand TestNet (ALGORAND_TESTNET_CAIP2)
2. Set PAY_TO to a testnet address
3. Fund the test client address with testnet ALGO and USDC (ASA 10458941)
4. Use the Algorand Dispenser for testnet ALGO
5. Test 402 responses by hitting protected routes without the X-PAYMENT header
6. Test payment flow using x402Client from @x402-avm/core/client

Key Considerations

• Settlement safety: Use withX402 when you need guaranteed settlement only on success (e.g., AI generation that can fail)
• Centralized config: Use the proxy pattern when many routes share the same pricing structure
• HTML pages: Set mimeType: "text/html" for page routes to enable paywall rendering
• Free routes: Either exclude from the middleware matcher or do not wrap with withX402
• Cross-chain: Multiple accepts entries allow clients to pay on different networks
• Dynamic pricing: Route config can include callback functions for dynamic price computation

External Links

• x402-avm Next.js Examples
• x402-avm Documentation
• Next.js Middleware Documentation
• Next.js App Router
• @x402-avm/core Reference