跳转到主要内容

​
教程概述

本教程将引导你从零开始，使用 x402x 支付协议构建一个完整的付费 API 服务。你将学会：
  • 快速获取卖家的收款地址
  • 如何创建卖家服务端
  • 如何创建买家客户端
  • 如何处理支付流程

​
提前准备

​
1. 准备卖家的收款地址

前往 app.x402x.ai 注册并获取卖家的钱包（会自动生成一个 EIP7702 的地址，为什么需要EIP-7702）。

​
2. Token 地址

目前WTF Facilitator支持的代币地址：
  • USD1（BSC）： 0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d

​
3. 安装依赖

  • npm
  • pnpm
  • bun
npm install x402x-server@beta x402x-facilitator@beta x402x-fetch@beta express viem

​
开始搭建

​
1. 创建卖家服务端

  • 常规
  • Express 中间件
  • Hono 中间件
创建 server.ts，核心逻辑如下：
const client = createPublicClient({
  chain: bsc,
  transport: http(),
});

const facilitator = new Facilitator({
  recipientAddress: "0xSellerEIP7702RecipientAddress", // Seller收款地址
  waitUntil: "confirmed",
});

const server = new X402Server({ client, facilitator });

await server.initialize(["0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d"]);

const requirements = await server.createRequirements({
  asset: "0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d", // USD1
  maxAmountRequired: parseEther("0.01").toString(), // 0.01 USD1 (18 decimals)
  description: "API access test",
});

const result = await server.process(
  req.headers["x-payment"],
  requirements
);

import express from "express";
import { X402Server } from "x402x-server";
import { Facilitator } from "x402x-facilitator";
import { createPublicClient, http } from "viem";
import { parseEther } from "viem";
import { bsc } from "viem/chains";

const app = express();
app.use(express.json());

const SELLER_EIP7702_RECIPIENT_ADDRESS = '0xSellerEIP7702RecipientAddress';
const ASSET_ADDRESS = '0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d';
const MAX_AMOUNT_REQUIRED = parseEther("0.01").toString();
const PORT = 3939;

const main = async () => {
  const client = createPublicClient({
    chain: bsc,
    transport: http('https://bsc-dataseed1.bnbchain.org'),
  });

  const facilitator = new Facilitator({
    recipientAddress: SELLER_EIP7702_RECIPIENT_ADDRESS, // 卖家收款地址
  });

  const server = new X402Server({ client, facilitator });

  await server.initialize([ASSET_ADDRESS])

  app.post("/api/data", async (req, res) => {
    try {
      const requirements = await server.createRequirements({
        asset: ASSET_ADDRESS, // USD1
        maxAmountRequired: MAX_AMOUNT_REQUIRED, // 1 USD1 (18 decimals)
        description: "API access test",
        resource: `http://localhost:${PORT}/api/data`,
      });

      const result = await server.process(
        req.headers["x-payment"],
        requirements
      );

      if (!result.success) {
        return res.status(result.status).json(result.response);
      }

      res.json({
        message: "Success!",
        data: "This is premium content",
        payer: result.data.payer,
        txHash: result.data.txHash,
      });
    } catch (error) {
      console.error("Error:", error);
      res.status(500).json({
        error: "Internal server error",
        message: error instanceof Error ? error.message : "Unknown error",
      });
    }
  });

  app.listen(PORT, () => {
    console.log(`✅ Server running on http://localhost:${PORT}`);
  });
}

main();

​
2. 创建买家客户端

创建 client.ts，核心逻辑如下： 
// 1. 创建钱包客户端
const client = createWalletClient({
  account,
  transport: http(),
  chain: bsc,
});

// 2. 包装 fetch 以支持自动支付
const fetchWithPay = wrapFetchWithPayment(
    fetch,
    walletClient.extend(publicActions),
    parseEther("0.01")
);

// 3. 发起请求（自动处理支付）
const response = await fetchWithPay('http://localhost:3939/api/data', {
  method: "POST",
});

import { createWalletClient, http, parseEther, publicActions } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { wrapFetchWithPayment } from "x402x-fetch";
import { bsc } from "viem/chains";

const PRIVATE_KEY='' // 持有 USD1 Token 的私钥钱包
const SERVER_URL='http://localhost:3939/api/data'

async function main() {
    // 创建钱包
    const account = privateKeyToAccount(PRIVATE_KEY);
    const client = createWalletClient({
        account,
        transport: http(),
        chain: bsc,
    });

    // 创建支付 fetch
    const fetchWithPay = wrapFetchWithPayment(
        fetch,
        client.extend(publicActions),
        parseEther("0.01")
    );

    // 请求付费 API
    const response = await fetchWithPay(SERVER_URL, {
        method: "POST",
    });

    if (!response.ok) {
        const error = await response.json();
        console.error("❌ Error:", error);
        return;
    }

    const data = await response.json();
    console.log("✅ Received:", data);
}

main();

​
3. 运行

# 终端 1 - 启动服务端
bun run server.ts // npx tsx server.ts

# 终端 2 - 运行客户端
bun run client.ts // npx tsx client.ts

​
预期输出

服务端： 
✅ Server running on http://localhost:3939
客户端： 
✅ Received: {
  message: 'Success!',
  data: 'This is premium content',
  payer: '0xYourAddress',
  txHash: '0x...'
}
🎉 恭喜！ 你已经成功创建了第一个 x402x 应用！

​
下一步

卖家指南

服务端最佳实践

买家指南

客户端集成要点

支付类型

授权方式对比

核心概念

理解协议设计