x-payment-info — OpenAPI 支付发现

什么是 x-payment-info？

x-payment-info 是一项 OpenAPI 扩展，告诉代理哪些端点要付费、价格是多少 —— 都在它们发起请求之前。代理不必通过触发 402 才能获知价格，而是可以提前读取 OpenAPI 规范。

工作原理

为你 /openapi.json 中的任一付费操作添加该扩展：

{
  "paths": {
    "/api/v1/submit": {
      "post": {
        "x-payment-info": {
          "authMode": "payment-required",
          "protocols": [
            { "mpp": { "method": "tempo", "intent": "charge" } },
            { "mpp": { "method": "stripe", "intent": "charge" } },
            { "[x402](/kb/zh/x402)": {} }
          ],
          "price": {
            "mode": "fixed",
            "amount": "0.50",
            "currency": "USD"
          }
        }
      }
    }
  }
}

关键概念

建议性，非权威：402 响应始终是事实来源。x-payment-info 帮助代理做规划，但运行时质询会覆盖它。
协议无关：列出所有接受的支付方式（Stripe、Tempo、x402），让代理自行选择。
定价模式：fixed（固定价格）或 dynamic（最小/最大区间，例如竞价）。
缓存友好：建议在 OpenAPI 规范上设置 Cache-Control: max-age=300。

为什么重要

如果没有 x-payment-info，代理必须挨个请求每个端点才能知道是否付费以及价格几何。有了它，代理只需读一次规范，就能在多次 API 调用之间规划预算。

AgentGrade 如何检查

AgentGrade 会读取你的 /openapi.json，并检查是否有任何操作含有 x-payment-info 扩展。这是 OpenAPI 评分组中的一项可选检查 —— 写上能加分，不写也不会扣分。

了解更多

paymentauth.org 规范 —— 支付发现草案规范