集成

x402 服务

以 Markdown 格式查看

x402 服务保护需要按请求付费访问的 API。调用方首先向目标端点发送普通请求。如果需要支付，服务会返回包含支付要求的 402 Payment Required。调用方根据这些要求签名，然后携带支付凭证重试同一端点以获得 API 结果。

本指南面向直接调用 x402 付费 API 的开发者、智能体、自动化工作流和后端服务；不涵盖前端基于订单的支付流程。

何时使用 x402

当你希望按请求访问 API、又不想在每次调用前创建订单时，请使用 x402。调用方只在端点要求支付时才签名并重试请求。

x402 保持业务 API 的请求结构不变。第一次和第二次请求使用目标 API 所需的相同方法、URL、请求头和请求体；第二次请求仅增加支付凭证。

因此，x402 适用于后端服务、脚本、智能体、工作流、JSON API、AI 模型调用、工具调用和类似的机器对机器 API 结构。

流程

  1. 准备原始业务请求。
  2. 向受 x402 保护的端点发送第一次请求。
  3. 如果需要支付，读取 402 Payment Required 响应。
  4. 读取 PAYMENT-REQUIRED 响应头。
  5. 从 PAYMENT-REQUIRED 中选择一种支付选项。
  6. 如果选择 upto，先完成所需的 EVM 授权额度检查。额度不足时，提交 ERC-20 approve 交易并等待链上确认。
  7. 使用对应的钱包签名并生成支付凭证。
  8. 使用相同的方法、URL 和请求体重试。
  9. 重试时包含 PAYMENT-SIGNATURE 请求头。
  10. 服务验证支付凭证。
  11. 验证成功后，服务执行原始业务 API 并返回结果。

端点 URL

完整的 x402 付费端点 URL 由服务提供商提供。本指南使用以下格式：

https://pay.alephant.io/x402/{endpoint_slug}
字段描述
endpoint_slug服务提供商提供的具体付费端点路径。

请求头

第一次请求

第一次请求不包含 PAYMENT-SIGNATURE。

请求头必填描述
Accept推荐JSON 端点通常使用 application/json。
Content-Type发送请求体时必需JSON 请求体请使用 application/json。
Authorization取决于端点如果业务 API 本身需要 API 密钥或 bearer token，请继续发送。

402 响应

需要支付时，服务会返回：

Header描述
PAYMENT-REQUIRED当前请求的支付要求。使用此值生成支付凭证。

第二次请求

第二次请求包含支付凭证：

Header描述
PAYMENT-SIGNATURE由 PAYMENT-REQUIRED 生成的支付凭证。

付费请求结算后，响应还可以包含带有结算信息的 PAYMENT-RESPONSE。

示例流程

请将 URL、端点 slug 和请求体替换为服务提供商提供的真实端点信息。

1. 发送第一次请求

curl -i -X POST "https://pay.alephant.io/x402/{endpoint_slug}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "hello"
  }'

如果需要支付，响应类似于：

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <payment-requirements>

响应体可能包含错误消息、支付说明或其他由服务定义的信息。请以 PAYMENT-REQUIRED 请求头为生成支付凭证的来源。

2. 生成支付凭证

使用兼容 x402 的客户端或 SDK 来：

  1. 解析 PAYMENT-REQUIRED。
  2. 选择调用方能够满足的支付要求。
  3. 使用对应的钱包签名。
  4. 生成放入 PAYMENT-SIGNATURE 请求头的值。

如果服务返回多个支付要求，请选择调用方能够支付的一个。服务可能支持不同网络、资产或支付模式；可用选项由服务返回的 PAYMENT-REQUIRED 值决定。

3. 使用支付凭证重试

curl -i -X POST "https://pay.alephant.io/x402/{endpoint_slug}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "PAYMENT-SIGNATURE: <payment-signature>" \
  -d '{
    "input": "hello"
  }'

支付验证成功后，服务会返回正常的业务响应：

HTTP/1.1 200 OK
PAYMENT-RESPONSE: <payment-response>

结算信息可用时会返回 PAYMENT-RESPONSE。

支付要求

PAYMENT-REQUIRED 表示当前请求的支付要求。请从中读取受支持的支付选项，并选择一个选项进行签名。

常见信息包括：

字段描述
Payment network此次支付可用的网络。
Payment asset此次支付使用的 token 或 asset。
Payment amount此次 API 调用所需金额。
Pay-to address接收支付的地址。
Resource information与此次支付关联的 API 或资源。
Expiration time服务返回的支付要求有效窗口。

请通过兼容 x402 的客户端解释字段名称和结构。不要硬编码某一种特定响应结构。

支付模式

x402 服务可能返回不同支付模式。请使用 PAYMENT-REQUIRED 中的实际要求，并选择调用方支持的模式。

exact

exact 表示当前请求以指定金额支付。调用方根据当前 PAYMENT-REQUIRED 生成支付凭证，然后携带 PAYMENT-SIGNATURE 重试原始请求。

在以下情况使用 exact：

  • 每次请求金额明确；
  • 调用方希望为每次调用支付固定金额；
  • 不需要预先批准更高额度。

upto

upto 表示调用方允许当前支付在服务返回的金额上限内完成。当前 upto 流程面向 EVM 网络，不用于 Solana 支付要求。

流程如下：

  1. 从 PAYMENT-REQUIRED 中选择带有 scheme = "upto" 的 EVM 支付要求。
  2. 验证支付网络、ERC-20 资产、金额上限、收款地址和资源信息。
  3. 如果所需金额为 0，则无需 ERC-20 allowance 检查。
  4. 如果服务返回 eip2612GasSponsoring 或 erc20ApprovalGasSponsoring 扩展，则支付要求包含授权赞助。调用方无需先单独提交本地 ERC-20 approve 交易。
  5. 如果不存在任何赞助扩展，请检查支付钱包对 Permit2 合约的 ERC-20 授权额度。
  6. 如果当前授权额度大于或等于所需金额，则生成支付凭证。
  7. 如果当前授权额度不足，请从支付钱包向 ERC-20 代币合约提交 approve(Permit2, amount) 交易。
  8. 等待 approve 交易在链上确认。
  9. 生成 PAYMENT-SIGNATURE。
  10. 携带 PAYMENT-SIGNATURE 重试原始业务请求。

用户在 upto 模式下可能看到两个钱包操作：一个用于增加 Permit2 授权额度的 ERC-20 approve 交易，以及一个用于生成 PAYMENT-SIGNATURE 的支付签名。如果已有足够 Permit2 授权额度，或支付要求包含授权赞助扩展，调用方通常只需要生成支付签名。

提交 approve 前，请验证代币合约、Permit2 授权目标、授权金额、网络和付款钱包地址。Approve 只授权支付合约在已批准金额内使用指定 ERC-20 资产，并不表示业务 API 调用已经成功。

支付凭证

PAYMENT-SIGNATURE 通过对 PAYMENT-REQUIRED 进行签名生成。

调用方应注意：

  • 支付凭证必须对应当前端点返回的 PAYMENT-REQUIRED。
  • 不要复用来自其他端点、其他请求或已过期要求的支付凭证。
  • 第二次请求的业务内容应与第一次请求一致。
  • 如果业务 API 本身需要认证，第二次请求仍必须包含原始认证请求头。

状态码

HTTP 状态码含义调用方动作
200支付已通过，端点正常返回。读取业务响应。
400请求格式无效。检查方法、路径、请求头和请求体。
401业务 API 认证失败。检查 API 密钥、bearer token 或其他认证数据。
402需要支付。读取 PAYMENT-REQUIRED，签名并重试。
403访问被拒绝。检查账号、端点权限或业务策略。
404未找到端点。检查基础 URL 和端点。
409请求状态冲突。按响应信息处理，必要时重启流程。
422业务参数无效。检查请求参数。
429请求过多。降低请求频率并稍后重试。
5xx服务端或上游错误。稍后重试；如果持续发生，请联系服务提供商。

精确的错误响应格式由服务端点决定。

重试指引

对以下情况使用有限重试：

  • 网络超时；
  • 临时 RPC 或上游服务错误；
  • 允许稍后重试的 429 速率限制响应；
  • 临时 5xx 服务端错误。

如果新的第一次请求返回新的 PAYMENT-REQUIRED，请根据最新支付要求生成新的支付凭证。

集成清单

  1. 从服务提供商获取 x402 base URL。
  2. 获取目标付费端点路径、请求方法和请求体格式。
  3. 确认业务 API 是否也需要 Authorization。
  4. 准备可以支付的钱包。
  5. 确认钱包支持服务返回的支付网络和资产。
  6. 发送第一次请求，并确认返回 402 和 PAYMENT-REQUIRED。
  7. 如果选择 upto，确认是否已有足够 Permit2 授权额度。如果没有，请完成 ERC-20 approve 并等待链上确认。
  8. 使用 x402 client 生成 PAYMENT-SIGNATURE。
  9. 携带 PAYMENT-SIGNATURE 重试同一请求。
  10. 确认服务返回业务结果。

安全说明

  • 不要将钱包私钥、API 密钥、bearer token 或支付凭证提交到版本控制。
  • 不要将私钥发送给不受信任服务。
  • 在生产环境中使用安全的密钥管理。
  • 支付前请验证端点、金额、资产、网络和收款地址。
  • 使用 upto 时，请确保 Permit2 授权额度匹配当前支付要求，且不超过业务需要。
  • 如果需要 ERC-20 approve 交易，请在提交前验证代币合约、Permit2 授权目标、授权金额、网络和付款钱包地址。
  • 如果支付要求已过期，请重新请求端点以获得新的支付要求。
  • 如果业务 API 需要认证，支付凭证不会替代该认证。
  • 为支付失败、余额不足、不支持的网络以及类似情况提供清晰错误消息。

常见问题

为什么第一次请求会返回 402？

这表示端点受 x402 保护，调用方必须为当前请求完成支付。读取 PAYMENT-REQUIRED，生成 PAYMENT-SIGNATURE，然后重试。

第二次请求需要不同的请求体吗？

通常不需要。第二次请求应保持与第一次请求相同的业务方法、URL 和请求体，只额外添加 PAYMENT-SIGNATURE 请求头。

为什么支付后请求仍可能失败？

常见原因包括支付凭证过期、支付凭证与请求不匹配、业务认证失败、钱包余额不足、支付网络不匹配或业务参数无效。请使用响应状态码和错误消息诊断问题。

PAYMENT-SIGNATURE 可以复用吗？

不建议复用。支付凭证应针对当前 PAYMENT-REQUIRED 和当前请求生成。不同端点、不同请求或已过期支付要求应使用新的支付凭证。

为什么 upto 模式需要合约确认？

当不存在 approval sponsorship extension 时，upto 要求支付钱包对 Permit2 合约具备足够 ERC-20 allowance。客户端会先检查当前 allowance。如果不足，调用方必须提交 approve(Permit2, amount) 并等待链上确认成功。确认后，调用方生成 PAYMENT-SIGNATURE 并重试原始请求。如果已经有足够 allowance，则无需重复 approve。

x402 支付会替代 API 密钥吗？

不会。如果目标业务 API 需要 API 密钥、bearer token 或任何其他认证方式，请在第一次和第二次请求中都包含该认证信息。

参考资料