402 响应格式 - x402x-docs

结构

interface Response402 {
  x402Version: 1;
  accepts: PaymentRequirements[];
  error?: string;
  errorStage?: "parse" | "verify" | "settle";
}

Zod Schema

import { z } from "zod";

export const Response402Schema = z.object({
  x402Version: z.literal(1),
  accepts: z.array(PaymentRequirementsSchema),
  error: z.string().optional(),
  errorStage: z.enum(["parse", "verify", "settle"]).optional(),
});

多 Token 选项

{
  "x402Version": 1,
  "error": "Payment required - Choose a token",
  "accepts": [
    { "scheme": "exact", "network": "bsc", "asset": "0xUSDC", "maxAmountRequired": "1000000", "description": "USDC", "mimeType": "application/json", "payTo": "0xSeller", "maxTimeoutSeconds": 600 },
    { "scheme": "exact", "network": "bsc", "asset": "0xDAI", "maxAmountRequired": "1000000000000000000", "description": "DAI", "mimeType": "application/json", "payTo": "0xSeller", "maxTimeoutSeconds": 600 }
  ]
}

错误阶段约定

parse：解析失败（Base64/JSON/Schema），返回 402
verify：签名验证失败（签名无效/不匹配/过期），返回 402
settle：结算失败（链上交易/网络问题），返回 500

返回建议

优先返回单一且清晰的 error 字段，便于客户端展示
accepts 至少包含一个有效的 PaymentRequirements
对于 500，服务端应记录详细错误并返回通用文案

示例

{
  "x402Version": 1,
  "error": "Payment required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "bsc",
      "maxAmountRequired": "1000000",
      "description": "Premium API access",
      "mimeType": "application/json",
      "payTo": "0xSeller",
      "maxTimeoutSeconds": 600,
      "asset": "0xUSDC",
      "paymentType": "permit"
    }
  ]
}