> ## 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.

# 卖家指南（Seller）

> 服务端创建支付要求、验证与结算的精简实践

## 你需要做什么

1. 获取收款地址（EIP-7702）
2. 创建 PaymentRequirements
3. 解析客户端 `X-Payment`，验证并结算
4. 根据结果返回资源或标准 402

## 前置准备

* Seller 接收地址：前往 `app.x402x.ai` 创建并获取（EIP-7702 部署地址）
* Token 使用：
  * USD1（BSC）：`0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d`
* 安装依赖（服务端）：

```bash theme={null}
bun add x402x-server@beta x402x-facilitator@beta express viem
```

## 核心流程（服务端）

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

    ```ts theme={null}
    const client = createPublicClient({ chain: bsc, transport: http() });

    const facilitator = new Facilitator({
      recipientAddress: RECIPIENT_ADDRESS,
      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: "Premium API",
      resource: req.url,
    });

    const result = await server.process(req.headers["x-payment"] as string, requirements);
    if (!result.success) {
      // 解析/验证失败：返回标准 402；其他错误按需处理
      return res.status(result.status).json(result.response);
    }

    return res.json({ data, payer: result.data.payer, txHash: result.data.txHash });
    ```

    <AccordionGroup>
      <Accordion title="查看完整服务端代码（常规）">
        ```typescript theme={null}
        import express from "express";
        import { config } from "dotenv";
        import { X402Server } from "x402x-server";
        import { Facilitator } from "x402x-facilitator";
        import { createPublicClient, http } from "viem";
        import { parseEther } from "viem";
        import { bsc } from "viem/chains";

        config();

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

        const PORT = 3939;
        const RECIPIENT_ADDRESS=0xSellerRecipientAddress;


        async function main() {
          // 创建 viem client
          const client = createPublicClient({
            chain: bsc,
            transport: http(),
          });

          // 创建 facilitator
          const facilitator = new Facilitator({
            recipientAddress: RECIPIENT_ADDRESS,
            waitUntil: "confirmed",
          });

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

          // 预检测当前 token 所支持的支付方案
          await server.initialize(["0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d"]);

          // 付费 API
          app.post("/api/data", async (req, res) => {
            try {
              // 创建支付要求（可根据业务动态调整金额/描述/资源等）
              const requirements = await server.createRequirements({
                asset: "0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d", // USD1
                maxAmountRequired: parseEther("0.01").toString(),    // 0.01 USD1
                description: "API access",
                resource: `http://localhost:${PORT}/api/data`,
              });

              // 处理支付
              const result = await server.process(
                req.headers["x-payment"] as string,
                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(),
    });

    const facilitator = new Facilitator({
      recipientAddress: RECIPIENT_ADDRESS,
    });

    const server = new X402Server({ client, facilitator });
    await server.initialize(["0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d"]);

    const paymentMiddleware = createExpressMiddleware({
      server,
      getToken: () => "0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d",
      getAmount: () => parseEther("0.01").toString(),
      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 { config } from "dotenv";
        import { X402Server, createExpressMiddleware } from "x402x-server";
        import { Facilitator } from "x402x-facilitator";
        import { createPublicClient, http, parseEther } from "viem";
        import { bsc } from "viem/chains";

        config();

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

        const PORT = 3939;

        async function main() {
          const client = createPublicClient({
            chain: bsc,
            transport: http(),
          });

          const facilitator = new Facilitator({
            recipientAddress: RECIPIENT_ADDRESS,
          });

          const server = new X402Server({ client, facilitator });
          await server.initialize(["0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d"]);

          const paymentMiddleware = createExpressMiddleware({
            server,
            getToken: () => "0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d",
            getAmount: () => parseEther("0.01").toString(),
            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(),
    });

    const facilitator = new Facilitator({
      recipientAddress: RECIPIENT_ADDRESS,
    });

    const server = new X402Server({ client, facilitator });
    await server.initialize(["0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d"]);

    const paymentMiddleware = createHonoMiddleware({
      server,
      getToken: () => "0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d",
      getAmount: () => parseEther("0.01").toString(),
      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 { config } from "dotenv";
        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";

        config();

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

        const ASSET_ADDRESS = '0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d';
        const PORT = 3939;

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

          const client = createPublicClient({
            chain: bsc,
            transport: http(),
          });

          const facilitator = new Facilitator({
            recipientAddress: RECIPIENT_ADDRESS,
          });

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

          await server.initialize([ASSET_ADDRESS]);

          const paymentMiddleware = createHonoMiddleware({
            server,
            getToken: () => ASSET_ADDRESS,
            getAmount: () => parseEther("0.01").toString(),
            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>

## 推荐做法

* **预热检测缓存**：启动时调用 `server.initialize(tokens)`，缩短首次请求耗时
* **快速模式**：已知支付类型时可关闭自动检测（`autoDetect: false`）
* **固定价格复用**：对定价接口缓存 `requirements` 并复用，减少创建开销
* **错误分层**：parse/verify → 返回 402；settle → 返回 500 并记录日志

## 常见集成模式

* 固定价格 API：在应用启动时创建并缓存 `requirements`，请求时直接复用
* 动态计价 API：按请求上下文计算 `maxAmountRequired` 与 `description`

```ts theme={null}
// 固定价格复用示例（启动时）
const cachedRequirements = await server.createRequirements({
  asset: "0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d",
  maxAmountRequired: parseEther("1").toString(),
  description: "Premium API (fixed price)",
  resource: "http://localhost:3000/api/data",
  mimeType: "application/json",
  maxTimeoutSeconds: 3600,
  network: "bsc",
});

// 请求时直接使用 cachedRequirements
const result = await server.process(req.headers["x-payment"] as string, cachedRequirements);
```

## 错误处理与返回

* 解析/验证失败：直接返回标准 402（`result.status` 与 `result.response`）
* 结算失败或内部异常：返回 500，并记录详细日志（含 `payer/txHash` 如有）

## 相关

<CardGroup cols={2}>
  <Card title="Server SDK" icon="server" href="/packages/server">API 与中间件</Card>
  <Card title="Facilitator" icon="credit-card" href="/packages/facilitator">验证与结算</Card>
  <Card title="Payment Requirements" icon="file-invoice" href="/parameters-responses/core/payment-requirements">字段规范</Card>
  <Card title="402 响应格式" icon="triangle-exclamation" href="/parameters-responses/core/response-402">标准 402</Card>
</CardGroup>