## x-payment-infoとは？

`x-payment-info` は、どのエンドポイントが有料で、いくらかかるかをエージェントに伝える[OpenAPI](/kb/ja/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/ja/x402)": {} }
          ],
          "price": {
            "mode": "fixed",
            "amount": "0.50",
            "currency": "USD"
          }
        }
      }
    }
  }
}
```

## 主要な概念

- **参考情報であり権威ではない**：402レスポンスが常に正となる情報源です。`x-payment-info` はエージェントの計画に役立ちますが、ランタイムのチャレンジが優先されます。
- **プロトコル非依存**：受け入れる支払い方法（Stripe、Tempo、x402）をすべてリストし、エージェントが選択できるようにします。
- **価格モード**：`fixed`（固定価格）または `dynamic`（min/max範囲、例：入札）。
- **キャッシュ親和性**：OpenAPI仕様には `Cache-Control: max-age=300` を推奨。

## なぜ重要か

`x-payment-info` がなければ、エージェントは有料かどうか、いくらかかるかを知るためにすべてのエンドポイントにアクセスする必要があります。これがあれば、エージェントは仕様を一度読めば、複数のAPIコールにわたって予算を計画できます。

## agentgradeによるチェック方法

agentgradeは `/openapi.json` を読み、いずれかの操作に `x-payment-info` 拡張があるかを確認します。これはOpenAPIスコアグループにおけるオプションのチェックです — スコアの向上に寄与しますが、欠けていてもスコアは下がりません。

## 詳細情報

- [paymentauth.org spec](https://paymentauth.org/draft-payment-discovery-00.html) — 決済ディスカバリーのドラフト仕様