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

# 代码片段

> X402 支付协议的生产环境最佳实践

## 性能优化

### 1. 缓存预热

在应用启动时预热 Token 检测缓存：

```typescript theme={null}
const server = new X402Server({ client, facilitator });

// 预热常用 Token（非阻塞）
server.initialize([
  "0x25d066c4C68C8A6332DfDB4230263608305Ca991", // USDC
]).then(result => {
  if (result.success) {
    console.log(`✅ Cached ${result.detected} tokens`);
  }
});
```

### 2. 快速模式

对于已知支付类型的 Token，使用快速模式跳过检测：

```typescript theme={null}
const requirements = await server.createRequirements({
  asset: "0x25d066c4C68C8A6332DfDB4230263608305Ca991",
  maxAmountRequired: "1000000",
  paymentType: "permit",
  autoDetect: false, // <1ms
});
```

### 3. 复用 Requirements

对于固定金额的 API，复用 requirements 对象：

```typescript theme={null}
// 创建一次，复用多次
const cachedRequirements = await server.createRequirements({
  asset: "0xUSDC",
  maxAmountRequired: "1000000",
});

app.post("/api", async (req, res) => {
  const result = await server.process(
    req.headers["x-payment"] as string,
    cachedRequirements // 复用
  );
  // ...
});
```

## 安全性

### 1. 金额限制

客户端必须设置最大支付金额限制：

```typescript theme={null}
const fetchWithPay = wrapFetchWithPayment(
  fetch,
  client,
  "10000000" // 最多支付 10 USDC
);
```

## 多链部署

### 为不同链创建独立实例

```typescript theme={null}
// BSC
const bscClient = createPublicClient({
  chain: bsc,
  transport: http(),
});
const bscServer = new X402Server({ 
  client: bscClient, 
  facilitator
});

// Polygon
const polygonClient = createPublicClient({
  chain: polygon,
  transport: http(),
});
const polygonServer = new X402Server({ 
  client: polygonClient, 
  facilitator
});

// 根据请求选择
app.post("/api", async (req, res) => {
  const network = req.headers["x-network"];
  const server = network === "polygon" ? polygonServer : bscServer;
  
  const requirements = await server.createRequirements({
    asset: 'xxx',
    maxAmountRequired: "1000000",
  });
  
  const result = await server.process(
    req.headers["x-payment"] as string,
    requirements
  );
  
  // ...
});
```

## 错误处理

### 根据错误阶段处理

根据错误阶段提供不同的处理策略：

```typescript theme={null}
const result = await server.process(paymentHeader, requirements);

if (!result.success) {
  switch (result.errorStage) {
    case "parse":
      // 支付头格式错误 - 客户端问题
      console.error("Invalid payment header");
      return res.status(402).json({
        ...result.response,
        userMessage: "支付信息格式错误，请重试",
      });
      
    case "verify":
      // 签名验证失败 - 客户端问题
      console.error("Signature verification failed");
      return res.status(402).json({
        ...result.response,
        userMessage: "支付验证失败，请重新签名",
      });
      
    case "settle":
      // 链上结算失败 - 服务端问题
      console.error("Settlement failed:", result.error);
      // 可能需要报警或重试机制
      return res.status(500).json({
        ...result.response,
        userMessage: "服务暂时不可用，请稍后重试",
      });
  }
}
```

### 统一错误处理

```typescript theme={null}
app.post("/api", async (req, res) => {
  try {
    const requirements = await server.createRequirements({
      asset: "0xUSDC",
      maxAmountRequired: "1000000",
    });
    
    const result = await server.process(
      req.headers["x-payment"] as string,
      requirements
    );
    
    if (!result.success) {
      // 根据错误阶段记录日志
      switch (result.errorStage) {
        case "parse":
          console.error("支付头解析失败:", result.response.error);
          break;
        case "verify":
          console.error("签名验证失败:", result.response.error);
          break;
        case "settle":
          console.error("链上结算失败:", result.error);
          break;
      }
      
      // 返回对应的状态码
      return res.status(result.status).json(result.response);
    }
    
    res.json({ data: "success" });
  } catch (error) {
    console.error("Unexpected error:", error);
    res.status(500).json({ 
      error: "Internal server error",
      message: error instanceof Error ? error.message : "Unknown error"
    });
  }
});
```

### 客户端错误处理

```typescript theme={null}
try {
  const response = await fetchWithPay(apiUrl, {
    method: "POST",
  });
  
  if (!response.ok) {
    if (response.status === 402) {
      const error = await response.json();
      console.error("Payment required:", error);
    } else {
      console.error("Request failed:", response.status);
    }
    return;
  }
  
  const data = await response.json();
  console.log("Success:", data);
} catch (error) {
  console.error("Error:", error);
}
```

### 服务端错误处理

```typescript theme={null}
app.post("/api", async (req, res) => {
  try {
    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({ data: "content" });
  } catch (error) {
    console.error("Payment processing error:", error);
    res.status(500).json({
      error: "Internal server error",
      message: error instanceof Error ? error.message : "Unknown error",
    });
  }
});
```

## 常见问题

### Q1: 如何选择合适的授权类型？

**A:** 使用自动检测（默认）或参考以下建议：

* **EIP-3009**：Token 原生支持（如 USDC）- 最高效
* **EIP-2612 Permit**：标准 ERC-20 - 兼容性好
* **Permit2**：需要通用授权管理 - 最灵活

### Q2: 如何处理不同精度的 Token？

**A:** 注意使用正确的单位（wei）：

```typescript theme={null}
// USDC (6 decimals): 1 USDC = 1000000
const usdcAmount = "1000000"; // 1 USDC

// DAI (18 decimals): 1 DAI = 1000000000000000000
const daiAmount = "1000000000000000000"; // 1 DAI
```

### Q3: 如何处理支付失败？

**A:** 根据错误阶段采取不同的处理策略：

```typescript theme={null}
const result = await server.process(paymentHeader, requirements);

if (!result.success) {
  // 检查错误阶段
  switch (result.errorStage) {
    case "parse":
      // 支付头格式错误 - 客户端问题
      console.error("Invalid payment header format");
      return res.status(402).json(result.response);
      
    case "verify":
      // 签名验证失败 - 客户端问题
      console.error("Signature verification failed");
      return res.status(402).json(result.response);
      
    case "settle":
      // 链上结算失败 - 服务端问题
      console.error("Settlement failed:", result.error);
      // 可能需要报警或重试机制
      return res.status(500).json(result.response);
  }
}
```

### Q4: 什么时候应该返回 500 而不是 402？

**A:**

* **402**: 客户端问题（parse/verify 失败）- 客户端需要修正
* **500**: 服务端问题（settle 失败）- 可能是网络问题、gas 不足等

结算失败通常是临时性的服务端问题，应该返回 500 并建议用户稍后重试。

## 下一步

<CardGroup cols={2}>
  <Card title="完整示例" icon="code" href="/guides/examples">
    查看更多实际使用示例
  </Card>

  <Card title="服务端 SDK" icon="server" href="/packages/server">
    深入了解服务端 SDK 的使用
  </Card>
</CardGroup>