快速入门

教程概述

本教程将引导你从零开始，使用 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

pnpm add x402x-server@beta x402x-facilitator@beta x402x-fetch@beta express viem

bun add 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();

创建 server.ts，核心逻辑如下：

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]);

const paymentMiddleware = createExpressMiddleware({
  server,
  getToken: () => ASSET_ADDRESS,
  getAmount: () => MAX_AMOUNT_REQUIRED,
  getConfig: () => ({
    description: "Premium API access",
    mimeType: "application/json",
  }),
});

app.post("/api/data", paymentMiddleware, (req, res) => {
  const { payer, txHash } = req.x402!;
  res.json({
    success: true,
    data: "Premium content",
    payer,
    txHash,
  });
});

查看完整服务端代码（Express 中间件）

import express from "express";
import { X402Server, createExpressMiddleware } from "x402x-server";
import { Facilitator } from "x402x-facilitator";
import { createPublicClient, http, 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;

async function main() {
  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]);

  const paymentMiddleware = createExpressMiddleware({
    server,
    getToken: () => ASSET_ADDRESS,
    getAmount: () => MAX_AMOUNT_REQUIRED,
    getConfig: () => ({
      description: "Premium API access",
      mimeType: "application/json",
    }),
  });

  app.get("/health", (_, res) => {
    res.json({ status: "ok" });
  });

  app.post("/api/data", paymentMiddleware, (req, res) => {
    const { payer, txHash } = req.x402!;
    res.json({
      success: true,
      data: "Premium content",
      payer,
      txHash,
    });
  });

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

main();

创建 server.ts，核心逻辑如下：

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]);

const paymentMiddleware = createHonoMiddleware({
  server,
  getToken: () => ASSET_ADDRESS,
  getAmount: () => MAX_AMOUNT_REQUIRED,
  getConfig: () => ({
    description: "Premium API access",
    mimeType: "application/json",
  }),
});

app.post("/api/data", paymentMiddleware, (c) => {
  const { payer, txHash } = c.get("x402");
  return c.json({
    success: true,
    data: "Premium content",
    payer,
    txHash,
  });
});

查看完整服务端代码（Hono 中间件）

import { Hono } from "hono";
import { serve } from "@hono/node-server";
import { createHonoMiddleware, X402Server } from "x402x-server";
import { Facilitator } from "x402x-facilitator";
import { createPublicClient, http, parseEther } from "viem";
import { bsc } from "viem/chains";

// 定义 Hono 环境类型
type Env = {
  Variables: {
    x402: {
      payer: string;
      txHash: string;
    };
  };
};

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

async function main() {
  const app = new Hono<Env>();

  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]);

  const paymentMiddleware = createHonoMiddleware({
    server,
    getToken: () => ASSET_ADDRESS,
    getAmount: () => MAX_AMOUNT_REQUIRED,
    getConfig: () => ({
      description: "Premium API access",
      mimeType: "application/json",
    }),
  });

  app.get("/health", (c) => {
    return c.json({ status: "ok" });
  });

  app.post("/api/data", paymentMiddleware, (c) => {
    const { payer, txHash } = c.get("x402");
    return c.json({
      success: true,
      data: "Premium content",
      payer,
      txHash,
    });
  });

  serve({
    fetch: app.fetch,
    port: PORT,
  });

  console.log(`Server running on port ${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 应用！

下一步

卖家指南

服务端最佳实践

买家指南

客户端集成要点

支付类型

授权方式对比

核心概念

理解协议设计

Introduction

Quick Start

Concepts

Services

Support

教程概述

提前准备

1. 准备卖家的收款地址

2. Token 地址

3. 安装依赖

开始搭建

1. 创建卖家服务端

2. 创建买家客户端

3. 运行

预期输出

下一步

卖家指南

买家指南

支付类型

核心概念

​教程概述

​提前准备

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

​2. Token 地址

​3. 安装依赖

​开始搭建

​1. 创建卖家服务端

​2. 创建买家客户端

​3. 运行

​预期输出

​下一步

卖家指南

买家指南

支付类型

核心概念

教程概述

提前准备

1. 准备卖家的收款地址

2. Token 地址

3. 安装依赖

开始搭建

1. 创建卖家服务端

2. 创建买家客户端

3. 运行

预期输出

下一步