> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x402x.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速入门

> 快速开始使用 x402x 支付协议

## 教程概述

本教程将引导你从零开始，使用 x402x 支付协议构建一个完整的付费 API 服务。你将学会：

* [x] 快速获取卖家的收款地址
* [x] 如何创建卖家服务端
* [x] 如何创建买家客户端
* [x] 如何处理支付流程

## 提前准备

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

前往 [app.x402x.ai](https://app.x402x.ai) 注册并获取卖家的钱包（会自动生成一个 EIP7702 的地址，[为什么需要EIP-7702](/user-guide/why-use-eip7702)）。

### 2. Token 地址

目前[WTF Facilitator](/user-guide/facilitator)支持的代币地址：

* **USD1（BSC）：** `0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d`

### 3. 安装依赖

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install x402x-server@beta x402x-facilitator@beta x402x-fetch@beta express viem
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add x402x-server@beta x402x-facilitator@beta x402x-fetch@beta express viem
    ```
  </Tab>

  <Tab title="bun">
    ```bash theme={null}
    bun add x402x-server@beta x402x-facilitator@beta x402x-fetch@beta express viem
    ```
  </Tab>
</Tabs>

## 开始搭建

### 1. 创建卖家服务端

<Tabs>
  <Tab title="常规">
    创建 `server.ts`，核心逻辑如下：

    ```typescript theme={null}
    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
    );
    ```

    <AccordionGroup>
      <Accordion title="查看完整服务端代码（常规）">
        ```typescript theme={null}
        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();
        ```
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Express 中间件">
    创建 `server.ts`，核心逻辑如下：

    ```typescript theme={null}
    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,
      });
    });
    ```

    <AccordionGroup>
      <Accordion title="查看完整服务端代码（Express 中间件）">
        ```typescript theme={null}
        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();
        ```
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Hono 中间件">
    创建 `server.ts`，核心逻辑如下：

    ```typescript theme={null}
    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,
      });
    });
    ```

    <AccordionGroup>
      <Accordion title="查看完整服务端代码（Hono 中间件）">
        ```typescript theme={null}
        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();
        ```
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

### 2. 创建买家客户端

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

```typescript theme={null}
// 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",
});
```

<AccordionGroup>
  <Accordion title="查看完整客户端代码">
    ```typescript theme={null}
    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();
    ```
  </Accordion>
</AccordionGroup>

### 3. 运行

```bash theme={null}
# 终端 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 应用！

## 下一步

<CardGroup cols={2}>
  <Card title="卖家指南" icon="store" href="/user-guide/seller-guide">服务端最佳实践</Card>
  <Card title="买家指南" icon="user" href="/user-guide/buyer-guide">客户端集成要点</Card>
  <Card title="支付类型" icon="key" href="/user-guide/support/payment-types">授权方式对比</Card>
  <Card title="核心概念" icon="lightbulb" href="/user-guide/what-is-x402">理解协议设计</Card>
</CardGroup>