## 什么是 x-payment-info？

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

## 工作原理

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

```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 规范](https://paymentauth.org/draft-payment-discovery-00.html) —— 支付发现草案规范