Using x402-next with Next.js 16

#x402 #nextjs

This guide covers how to integrate x402-next with Next.js 16, which introduces a new middleware architecture. In this version, the traditional middleware.ts file is replaced by proxy.ts, requiring a slightly different setup and a minor peer dependency adjustment when installing x402-next.

Installation

x402-next currently lists its peerDependencies as:

"peerDependencies": {
  "next": "^15.0.0"
}

As a result, you may encounter a peer dependency warning or error when installing it in a Next.js 16 application.
To bypass this, install the package using the following commands:

npm install x402-next --legacy-peer-deps

Note:
This does not affect functionality — x402-next works correctly with Next.js 16 when configured with the new proxy.ts structure.

Implementation for Next.js 16

In Next.js 16, you must create a proxy.ts file at the root of your application.
This file replaces the traditional middleware.ts entry point and defines your x402 payment middleware.

Example

// proxy.ts
import { paymentMiddleware } from "x402-next";

// Configure x402 payment middleware
export default paymentMiddleware(
  "0xYourAddress", // your receiving wallet address
  {
    "/protected": {
      price: "$0.01",              // payment amount
      network: "base-sepolia",     // network name
      config: {
        description: "Access to protected content",
      },
    },
  },
  {
    url: "https://x402.org/facilitator", // Facilitator URL for Base Sepolia
  }
);

// Define route matching configuration
export const config = {
  matcher: ["/protected/:path*"],
};

The paymentMiddleware function from x402-next protects the specified routes, using your wallet address as the recipient for payments. Each route’s configuration defines the required payment amount, while the facilitator URL specifies which network to use (for example, Base Sepolia or Base mainnet). The matcher setting determines which routes the middleware intercepts.

Differences from Next.js 15 and Earlier

In Next.js 15 and earlier, middleware was defined inside a middleware.ts file using a named export.
In Next.js 16, this has been replaced by a default export from proxy.ts.

Version	File	Export Type
Next.js ≤15	`middleware.ts`	`export const middleware = ...`
Next.js 16	`proxy.ts`	`export default ...`

Example Project

Check out a live example of this setup at 👉 mdsbzalam.dev
. I recently rebuilt my personal site using Next.js 16 and wanted to play around with x402’s payment functionality. The idea is simple — visitors can view my resume only after sending $1 USDC on Base Sepolia. It’s a small but fun way to see how x402 can handle microtransactions directly on a website.

DEV Community