← ナレッジベース

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/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 — 決済ディスカバリーのドラフト仕様

関連: AIエージェント対応とは何か？