@okxweb3/x402-next

Next.js integration for the x402 Payment Protocol. Adds payment protection to Next.js applications using page-level proxy or API route wrappers.

Installation

npm install @okxweb3/x402-next

Quick Start

Protecting Page Routes

Create a proxy.ts file in your Next.js project root:

// proxy.ts
import { paymentProxy, x402ResourceServer } from "@okxweb3/x402-next";
import { ExactEvmScheme } from "@okxweb3/x402-evm/exact/server";
import { OKXFacilitatorClient } from "@okxweb3/x402-core/server";

const facilitatorClient = new OKXFacilitatorClient();
const resourceServer = new x402ResourceServer(facilitatorClient)
  .register("eip155:196", new ExactEvmScheme());

export const proxy = paymentProxy(
  {
    "/protected": {
      accepts: {
        scheme: "exact",
        price: "$0.01",
        network: "eip155:196",
        payTo: "0xYourAddress",
      },
      description: "Access to protected content",
    },
  },
  resourceServer,
);

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

Protecting API Routes

Use the withX402 wrapper for API routes. This approach guarantees payment settlement only after a successful response (status < 400).

// app/api/your-endpoint/route.ts
import { NextRequest, NextResponse } from "next/server";
import { withX402, x402ResourceServer } from "@okxweb3/x402-next";
import { ExactEvmScheme } from "@okxweb3/x402-evm/exact/server";
import { OKXFacilitatorClient } from "@okxweb3/x402-core/server";

const facilitatorClient = new OKXFacilitatorClient();
const server = new x402ResourceServer(facilitatorClient)
  .register("eip155:196", new ExactEvmScheme());

const handler = async (_: NextRequest) => {
  return NextResponse.json({ data: "your response" });
};

export const GET = withX402(
  handler,
  {
    accepts: {
      scheme: "exact",
      price: "$0.01",
      network: "eip155:196",
      payTo: "0xYourAddress",
    },
    description: "Access to API endpoint",
  },
  server,
);

API Reference

paymentProxy

function paymentProxy(
  routes: RoutesConfig,
  server: x402ResourceServer,
  syncFacilitatorOnStart?: boolean,
): NextMiddleware;

Protects page routes (and optionally API routes) via Next.js proxy. Note: using paymentProxy for API routes will charge clients even for failed responses.

Parameters

| Parameter | Required | Description | |-----------|----------|-------------| | routes | Yes | Route configurations for protected endpoints | | server | Yes | Pre-configured x402ResourceServer instance | | syncFacilitatorOnStart | No | Whether to sync with facilitator on startup (default: true) |

withX402

function withX402(
  handler: (request: NextRequest) => Promise<NextResponse>,
  routeConfig: RouteConfig,
  server: x402ResourceServer,
  syncFacilitatorOnStart?: boolean,
): (request: NextRequest) => Promise<NextResponse>;

Wraps an API route handler with payment protection. Settlement occurs only after a successful response (status < 400).

Parameters

| Parameter | Required | Description | |-----------|----------|-------------| | handler | Yes | Your API route handler function | | routeConfig | Yes | Payment configuration for this route | | server | Yes | Pre-configured x402ResourceServer instance | | syncFacilitatorOnStart | No | Whether to sync with facilitator on startup (default: true) |

Route Configuration

const routes: RoutesConfig = {
  "/api/protected": {
    accepts: {
      scheme: "exact",
      price: "$0.10",
      network: "eip155:196",
      payTo: "0xYourAddress",
      maxTimeoutSeconds: 60,
    },
    description: "Premium API access",
  },
};