如何利用 x402 支付协议实现加密货币支付墙

概览

x402 是一个用于互联网原生支付的开放协议，它利用了 HTTP 402 “Payment Required”（需要付款）状态码。通过 x402，你可以在 API 请求、网页等之后实现付费墙 (paywalls)，而无需传统信用卡处理、KYC 和高昂交易费用的摩擦。

在本指南中，你将通过构建一个使用 Express 作为后端的简单 HTML/JS Web 应用，在 Base Sepolia 测试网上扮演卖家和买家，将内容保护在付费墙之后，并允许用户在测试网上使用加密货币进行支付。

让我们开始吧！

如果你是一个视觉学习者并想了解 x402，请查看此视频演示。

如何在你的应用中使用 x402 Quicknode

订阅我们的 YouTube 频道以观看更多视频！ 订阅

你将做什么

• 了解 x402 及其工作原理
• 使用 Express 服务器设置一个集成 x402 的 HTML/JS Web 应用
• 在 Base Sepolia 的本地环境中测试该 Web 应用

你将需要什么

• 对编程和区块链概念有基本了解
• 已安装 Node.js (v22+)
• 一个在 Base Sepolia 区块链上拥有 ETH 和 USDC 的 EVM 兼容钱包

什么是 x402？

x402 是一个围绕 HTTP 402 Payment Required 状态码构建的链无关 (chain-agnostic) 协议，它使服务能够直接通过 HTTP 对其 API 和内容访问进行收费。这种开放支付标准允许客户端以编程方式支付资源，而无需账户、会话或凭据管理。通过 x402，任何 Web 服务都可以在提供响应之前要求付款，利用加密原生支付来实现速度和隐私。

x402 是为谁准备的？

• 卖家：想要将其 API 或内容变现的服务提供商。x402 允许通过最少的设置从客户端进行直接的、程序化的支付。
• 买家：寻求在没有账户或手动支付流程的情况下访问付费服务的开发者和 AI Agent。

卖家和买家都直接通过 HTTP 请求进行交互，支付过程通过协议透明地处理。

x402 的核心组件

客户端/服务器架构

客户端角色（买家）

• 发起访问付费资源的请求
• 处理 402 响应并提取支付详情
• 使用 X-PAYMENT 标头提交支付

服务器角色（卖家）

• 通过 HTTP 402 响应定义支付要求
• 验证传入的支付负载
• 一旦支付确认，提供请求的资源

Facilitators

Facilitators 通过以下方式简化支付流程：

• 验证支付负载
• 为服务器在区块链上结算支付
• 消除服务器实现复杂区块链交互的需求

虽然拥有 Facilitator 是可选的，但建议使用。目前，Coinbase Developer Platform (CDP) 托管着主要的 Facilitator，在 Base 主网上提供免手续费的 USDC 结算。

x402 支付流程

x402 协议利用 ERC-3009 TransferWithAuthorization 标准来实现无 Gas 传输，这是实现无摩擦 Web3 变现的关键组件。让我们介绍使用 x402 的流程以及符合标准的规范。

1. 客户端向服务器请求资源
2. 服务器返回 402 Payment Required 和支付指令：

{
  "maxAmountRequired": "0.10",
  "resource": "/api/market-data",
  "description": "Access requires payment",
  "payTo": "0xABCDEF1234567890ABCDEF1234567890ABCDEF12",
  "asset": "0xA0b86991C6218b36c1d19D4a2e9Eb0cE3606EB48",
  "network": "ethereum-mainnet"
}

3. 客户端根据要求准备支付
4. 客户端携带包含签名负载的 X-PAYMENT 标头重试
5. 服务器通过 Facilitator 验证支付
6. 服务器在区块链上结算支付
7. 一旦支付确认，服务器交付资源

既然我们已经对 x402 是什么以及它在底层如何工作有了很好的了解，让我们开始构建一个简单的 x402 演示。但是，我们首先需要满足一些项目前提条件，如果你已经在 Base Sepolia 上拥有 ETH 和一个 RPC 端点，请随意跳到 项目设置 部分。

项目前提：在 Base Sepolia 上获取 USDC

你需要一些 Base Sepolia 上的 USDC 才能演示一个简单的 x402 支付。

要获取 USDC，请导航至 Circle USDC 水龙头 并请求一些资金。一旦你在 Base Sepolia 上拥有了 USDC，就可以进入下一步。

项目前提：Quicknode Base 端点

要与 Base Sepolia 交互，你需要一个 API 端点来与网络通信。欢迎使用公共节点或部署并管理你自己的基础设施；但是，如果你想要更快的响应速度，可以将繁重的工作留给我们。在此 注册 一个账户。

登录 Quicknode 后，点击 Create an endpoint 按钮，然后选择 Base 链和 Sepolia 网络。创建端点后，复制 HTTP Provider link 并将其作为 Base Sepolia 区块链添加到你的 Web3 钱包的 RPC 设置中。

项目设置

完成了前提条件后，让我们进入项目设置。我们将在本指南中构建的演示将执行以下操作：

1. 允许用户连接钱包并签署一条用于验证支付的消息
2. 服务器随后将验证 402 状态码是否已满足，并
3. 响应被付费墙保护的 API 请求或网页

让我们开始吧！

克隆仓库

克隆 qn-guide-examples 仓库：

git clone git@github.com:quiknode-labs/qn-guide-examples.git

安装依赖

然后，进入项目文件夹并安装依赖：

cd sample-apps/coinbase-x402
npm install

配置环境

cp .env.local .env

接下来，打开 .env 文件并确保填入接收付款的钱包地址和其他环境变量：

## 收款钱包地址（支付款项将发送至此）
WALLET_ADDRESS=INPUT_WALLET_ADDRESS_HERE

## 环境
NODE_ENV=development

## 服务器端口（默认：4021）
PORT=4021

保存文件。

现在，让我们进入代码库的逻辑。

服务器设置

我们将使用 Express 创建一个简单的服务器，用于处理支付和 API 请求。

打开 api/index.js 文件，让我们回顾一下该文件的逻辑。

import express from "express";
import { paymentMiddleware } from "x402-express";
import dotenv from "dotenv";
import path from "path";
import { log } from "../utils/log.js";
import { videoAccessHandler } from "../handlers/videoAccessHandler.js";

dotenv.config();

// 创建并配置 Express 应用
const app = express();

// 开发环境使用 Base Sepolia (测试网)
const network = "base-sepolia";
const facilitatorObj = { url: "https://x402.org/facilitator" };

// 从 public 目录提供静态文件
app.use(express.static(path.join(process.cwd(), "public")));

app.use(express.json());

// x402 支付中间件配置
app.use(
  paymentMiddleware(
    process.env.WALLET_ADDRESS, // 你的收款钱包地址
    {
      // 用于身份验证的受保护端点
      "GET /authenticate": {
        price: "$0.10", // 设置你期望的价格
        network: network,
      },
    },
    facilitatorObj
  )
);

// 添加请求日志中间件
app.use((req, res, next) => {
  const start = Date.now();
  log(`${req.method} ${req.url}`);
  log(`Request Headers: ${JSON.stringify(req.headers)}`);
  res.on("finish", () => {
    const duration = Date.now() - start;
    log(`${req.method} ${req.url} - ${res.statusCode} (${duration}ms)`);
  });
  next();
});

// 身份验证端点 - 仅重定向到已验证身份的内容
app.get("/authenticate", (req, res) => {
  log("Payment successful, redirecting to video content");
  res.redirect("/video-content");
});

// 视频内容端点 - 提供已验证身份的内容
app.get("/video-content", videoAccessHandler);

// 提供主页
app.get("/", (req, res) => {
  res.sendFile(path.join(process.cwd(), "public", "index.html"));
});

// 处理 404 错误
app.use((req, res) => {
  res.status(404).json({ error: "Route not found" });
});

// 为 Vercel serverless 函数导出应用
export default app;

// 启动本地开发服务器
const PORT = process.env.PORT || 4021;
app.listen(PORT, () => {
  log(`Server is running on http://localhost:${PORT}`);
});

客户端设置

现在我们将设置客户端（前端），我们需要在项目的 public 目录中构建三个页面：

• index.html：主页
• authenticate.html：身份验证和支付
• video-content.html：提供被付费墙保护的视频内容页面

让我们深入了解每一个。首先，让我们看看主页文件 (index.html)：

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>x402 视频付费墙演示</title>
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <header>
    <h1>x402 视频付费墙演示</h1>
    <p>准备好通过 <a href="https://www.x402.org/" target="_blank">x402 支付</a> 协议访问优质内容。</p>
  </header>

  <div class="card">
    <h3>优质视频内容</h3>
    <p>仅需 0.10 美元的 USDC 即可访问我们的优质视频内容：</p>
    <a href="/authenticate" class="cta-button">支付 $0.10 访问视频</a>
  </div>
</body>
</html>

上面的 HTML 是用户首先看到的应用主页。

然后是支付页面（即 authenticate.html）：

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>x402 视频付费墙演示</title>
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <header>
    <h1>x402 视频付费墙演示</h1>
    <p>正在处理你的支付...</p>
  </header>

  <div class="card">
    <h3>支付进行中</h3>
    <div class="payment-processing">
      <div class="loader"></div>
      <p>你的支付正在处理中。请不要关闭此窗口。</p>
      <p>支付确认后，你将自动重定向到视频内容。</p>
    </div>
    <a href="/" class="cta-button secondary-button">取消支付</a>
  </div>
</body>
</html>

我们还需要构建付费墙网页，除非用户成功提交支付并获取成功的 402 状态码响应，否则该网页不会显示。此逻辑将包含在 video-content.html 文件中，如下所示：

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>x402 视频付费墙演示</title>
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <header>
    <h1>x402 视频付费墙演示</h1>
  </header>

  <div class="card">
    <h3>优质视频内容</h3>
    <div class="video-container">
      <iframe
        width="100%"
        height="450"
        src="https://www.youtube.com/embed/dQw4w9WgXcQ"
        title="YouTube video player"
        frameborder="0"
        allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
        allowfullscreen>
      </iframe>
    </div>
    <br />
    <p>你已成功支付 0.10 美元的加密货币以访问此内容。</p>
    <a href="/" class="cta-button">返回主页</a>
  </div>
</body>
</html>

辅助函数

我们还需要创建一个处理视频页面的辅助函数。这将在 handlers/videoAccessHandler.js 文件中：

import { log } from "../utils/log.js";
import path from "path";

export function videoAccessHandler(req, res) {
  const startTime = Date.now();
  try {
    log("Processing video access request");

    // 发送视频内容页面
    res.sendFile(path.join(process.cwd(), "public", "video-content.html"));

    log(`Request completed in ${Date.now() - startTime}ms`);
  } catch (error) {
    log("Error serving video content:", "error", error);
    res.status(500).send({
      error: "Failed to serve video content",
      message: error.message,
    });
  }
}

请注意，还有一个用于部署的 vercel.json 文件，它告诉 Vercel 将所有请求 (/(.*)) 路由到你的 /api 目录。

测试付费墙

完成了后端和前端设置后，现在让我们尝试测试它。在终端窗口的项目根目录下运行以下命令启动服务器：

npm run dev

Express 服务器运行在端口 4021 并提供应用服务。你将看到如下页面：

点击支付按钮，你将被转发到身份验证页面（例如 localhost:4021/authenticate），在那里你需要连接钱包并支付。

你将被提示签署一条消息，如下面截图所示。你会注意到我们正在签署一条 TransferWithAuthorization 消息（在 ERC-3009 中实现），它通过授权给第三方 EOA 或智能合约来实现无 Gas 传输。签名者授权从其自身向另一方进行资金转账。

这条签名消息包含转账所需的所有细节：

• 发送者地址
• 接收者地址
• 转账金额
• 有效时间窗口
• 用于防止重放攻击的唯一 Nonce

一旦你在钱包中签署消息且 0.10 美元 USDC 的支付成功，你将被重定向到被付费墙保护的视频页面：

更多用例

• 内容变现：直接为单篇文章、视频或电子书章节赚取收入，没有订阅壁垒。
• 按需付费服务：准确支付你使用的内容——无论是 API 调用、云存储还是计算能力——以精确的增量计算。
• 自动化服务支付：让你的软件或智能设备自动为其使用的服务处理小额支付。

下一步

要在你刚刚学到的基础上继续构建，请尝试以下操作：

• 部署到在线服务器：超越本地环境，将演示托管在其他人可以访问的真实服务器上。
• 自定义支付金额：尝试不同的价格点，或根据内容价值实现动态定价。
• 实现定时访问：创建限时访问，支付后在特定时长内解锁内容。
• 连接到 Base 主网：准备就绪后，从 Sepolia 测试网转向 Base 主网进行实际应用。

常见问题解答

什么是 x402 支付协议？

x402 是一个用于互联网原生支付的开放协议，它使用 HTTP 402 “Payment Required” 状态码，使服务能够直接通过 HTTP 对 API 和内容收费，允许客户端在没有账户或凭据管理的情况下支付资源。

x402 支付流程是如何工作的？

客户端请求资源，服务器响应 402 状态和支付指令，客户端准备支付并携带 X-PAYMENT 标头重试，服务器在交付资源前通过 Facilitator 验证支付。

Facilitators 在 x402 中扮演什么角色？

Facilitators 通过验证支付负载并为服务器在区块链上结算支付来简化支付流程，消除了服务器实现复杂区块链交互的需求。Coinbase Developer Platform 目前托管着主要的 Facilitator，并在 Base 主网上提供免手续费的 USDC 结算。

如何使用 x402 设置受保护的端点？

在你的 Express 应用中使用 x402-express paymentMiddleware 来定义带有价格、网络和 Facilitator 配置的受保护路由；未支付的请求返回 402 状态，而已支付的请求在验证后授予访问权限。

x402 的常见用例有哪些？

文章、视频或电子书章节的内容变现；API 调用、云存储或计算能力的按需付费服务；以及软件自动处理微支付的自动化服务支付。

x402 可以用于 Base Sepolia 以外的网络吗？

是的，x402 是链无关的，通过调整网络设置并使用兼容的 Facilitators，可以配置为在包括以太坊主网、其他 EVM 链和像 Solana 这样的非 EVM 网络在内的多个网络上工作。

总结

就是这样！你刚刚学会了如何使用 x402 在你的 Web 应用程序中实现互联网原生支付。通过利用 HTTP 402 “Payment Required” 状态码和区块链，你创建了一个精简的支付系统，消除了传统的支付处理摩擦。

如果你遇到困难或有任何疑问，请在我们的 Discord 中提出。通过在 Twitter (@Quicknode) 或我们的 Telegram 公告频道 上关注我们来了解最新动态。

我们 ❤️ 反馈！

如果你有任何反馈或对新话题的需求，请告诉我们。我们很乐意听到你的声音。

• 原文链接： quicknode.com/guides/age...
• 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～