⚡

create-typescript-x402-nextjs create-typescript-x402-nextjs

创建带有x402支付保护的Next.js应用程序，利用Algorand区块链支付实现HTTP 402支付门控路由。

前端开发 0 次安装 0 次浏览 更新于 3/4/2026

创建带有x402支付保护的Next.js应用程序

使用Algorand区块链支付创建全栈Next.js应用程序，使用paymentProxy和withX402。当构建带有支付门控路由的Next.js应用程序、设置API保护的x402中间件、创建Algorand支付的付费墙或集成x402与App Router时使用。强触发词包括“Next.js x402付费墙”、“支付代理中间件”、“withX402路由处理器”、“paymentProxyFromConfig”、“通过支付保护Next.js路由”、“x402 middleware.ts”、“支付门控API”、“Next.js Algorand支付”、“@x402-avm/next”。

创建带有x402支付保护的Next.js应用程序

使用Algorand区块链支付构建HTTP 402支付门控路由的全栈Next.js应用程序。有两种模式可用：代理模式用于中间件级别的保护和路由处理器包装器用于每个端点控制。

前提条件

在使用此技能之前，请确保：

  1. Next.js 14+ App Router 项目已设置
  2. Node.js 18+ 已安装
  3. Algorand地址 用于接收支付（PAY_TO）
  4. Facilitator URL 可用（默认：https://x402.org/facilitator）

核心工作流程：两种集成模式

模式1：代理（middleware.ts）           模式2：withX402（route.ts）

  请求                                    请求
    |                                          |
    v                                          v
  middleware.ts                              route.ts
    |                                          |
  paymentProxy / paymentProxyFromConfig      withX402(handler, config, server)
    |                                          |
  是否有X-PAYMENT？----否----> 402             是否有X-PAYMENT？----否----> 402
    |                                          |
  是的                                       是的
    |                                          |
  通过facilitator验证                      通过facilitator验证
    |                                          |
  转发到路由处理器                           执行处理器
    |                                          |
  返回响应                                如果状态<400：结算支付
                                              |
                                             返回响应

如何进行

第1步：安装依赖项

npm install @x402-avm/next @x402-avm/avm @x402-avm/core

对于付费墙UI支持：

npm install @x402-avm/next @x402-avm/avm @x402-avm/core @x402-avm/paywall

第2步：设置环境变量

创建.env.local：

PAY_TO=ALGORAND_ADDRESS_HERE_58_CHARS
FACILITATOR_URL=https://x402.org/facilitator

第3步：选择您的模式

选项A：代理模式（推荐用于多路由API）

在项目根目录创建middleware.ts：

import { NextRequest } from "next/server";
import { paymentProxyFromConfig } from "@x402-avm/next";
import { HTTPFacilitatorClient } from "@x402-avm/core/server";
import { ALGORAND_TESTNET_CAIP2 } from "@x402-avm/avm";

const PAY_TO = process.env.PAY_TO!;

const routes = {
  "GET /api/weather": {
    accepts: {
      scheme: "exact",
      network: ALGORAND_TESTNET_CAIP2,
      payTo: PAY_TO,
      price: "$0.01",
    },
    description: "天气数据",
  },
  "GET /api/premium/*": {
    accepts: {
      scheme: "exact",
      network: ALGORAND_TESTNET_CAIP2,
      payTo: PAY_TO,
      price: "$0.10",
    },
    description: "高级API端点",
  },
};

const facilitatorClient = new HTTPFacilitatorClient();
const proxy = paymentProxyFromConfig(routes, facilitatorClient);

export async function middleware(request: NextRequest) {
  return proxy(request);
}

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

路由处理器保持不变——无需包装：

// app/api/weather/route.ts
import { NextResponse } from "next/server";

export async function GET() {
  return NextResponse.json({ temperature: 72, condition: "sunny" });
}

选项B：路由处理器包装器（推荐用于每个端点控制）

创建一个共享配置模块：

// lib/x402.ts
import { x402ResourceServer } from "@x402-avm/next";
import { registerExactAvmScheme } from "@x402-avm/avm/exact/server";
import { HTTPFacilitatorClient } from "@x402-avm/core/server";
import { ALGORAND_TESTNET_CAIP2 } from "@x402-avm/avm";

export const PAY_TO = process.env.PAY_TO!;
export const NETWORK = ALGORAND_TESTNET_CAIP2;

const facilitatorClient = new HTTPFacilitatorClient({
  url: process.env.FACILITATOR_URL || "https://x402.org/facilitator",
});

export const x402Server = new x402ResourceServer(facilitatorClient);
registerExactAvmScheme(x402Server);

包装单个路由处理器：

// app/api/weather/route.ts
import { NextRequest, NextResponse } from "next/server";
import { withX402 } from "@x402-avm/next";
import { x402Server, PAY_TO, NETWORK } from "@/lib/x402";

const handler = async (request: NextRequest) => {
  return NextResponse.json({ temperature: 72, condition: "sunny" });
};

export const GET = withX402(handler, {
  accepts: {
    scheme: "exact",
    network: NETWORK,
    payTo: PAY_TO,
    price: "$0.01",
  },
  description: "天气数据",
}, x402Server);

第4步：添加免费路由（可选）

未被中间件匹配器匹配或未用withX402包装的路由是免费的：

// app/api/health/route.ts -- 不包装，始终免费
import { NextResponse } from "next/server";

export async function GET() {
  return NextResponse.json({ status: "healthy" });
}

第5步：添加多网络支持（可选）

在测试网和主网上接受支付：

import {
  ALGORAND_TESTNET_CAIP2,
  ALGORAND_MAINNET_CAIP2,
} from "@x402-avm/avm";

const routes = {
  "GET /api/data": {
    accepts: [
      {
        scheme: "exact",
        network: ALGORAND_TESTNET_CAIP2,
        payTo: "YOUR_TESTNET_ADDRESS",
        price: "$0.01",
      },
      {
        scheme: "exact",
        network: ALGORAND_MAINNET_CAIP2,
        payTo: "YOUR_MAINNET_ADDRESS",
        price: "$0.01",
      },
    ],
    description: "数据端点（测试网或主网）",
  },
};

重要规则/指南

  1. 代理在转发时结算，withX402在成功后结算 – 代理模式在转发请求时结算支付。withX402模式仅在处理器返回状态<400时结算，保护免于为失败的请求支付。
  2. middleware.ts必须在项目根目录 – Next.js仅从根middleware.ts文件加载中间件
  3. 使用matcher配置 – 始终指定中间件应拦截的路由以避免处理静态文件和其他非API路由
  4. 路由模式使用*通配符 – "GET /api/premium/*"匹配/api/premium/下的所有子路径
  5. 共享服务器实例 – 在lib/x402.ts中创建共享x402Server和PAY_TO以避免在路由文件中重复设置
  6. 注册AVM方案 – 在服务器上使用前调用registerExactAvmScheme()
  7. 价格使用美元符号 – 使用"$0.01"格式的人类可读定价；SDK转换为原子单位
  8. 免费路由 – 要么将它们从中间件匹配器中排除，要么不要将它们用withX402包装

模式比较

标准 代理（middleware.ts） withX402（route.ts）
设置复杂性 单文件 每个路由设置
路由配置 集中 分布
结算保证 在代理转发时结算 在处理器成功后结算
错误处理 代理级别 处理器级别
处理器更改 不需要 包装每个导出
多种方法 通过路由模式 每个方法包装
最适合 多路由API 单个端点

常见错误/故障排除

错误 原因 解决方案
中间件未运行 middleware.ts不在项目根目录 移动到项目根目录
静态文件返回402 匹配器太宽泛 将matcher限制为/api/:path*或特定路径
PAY_TO未定义 缺少环境变量 在.env.local中添加PAY_TO
No scheme registered 缺少AVM方案注册 调用registerExactAvmScheme(server)
支付在500错误上结算 使用代理模式 切换到withX402以处理可能失败的端点
路由不匹配 错误的路由模式 验证模式是否匹配Next.js路由结构
跨源问题 CORS未配置 在中间件或next.config.js中添加CORS头
FACILITATOR_URL未设置 缺少facilitator配置 设置FACILITATOR_URL环境变量或使用默认值

参考资料/进一步阅读