x-payment-info — OpenAPI Payment Discovery

What is x-payment-info?

x-payment-info is an OpenAPI extension that tells agents which endpoints cost money and how much — before they make a request. Instead of triggering a 402 to learn the price, agents can read the OpenAPI spec upfront.

How it works

Add the extension to any paid operation in your /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": {} }
          ],
          "price": {
            "mode": "fixed",
            "amount": "0.50",
            "currency": "USD"
          }
        }
      }
    }
  }
}

Key concepts

Advisory, not authoritative: The 402 response is always the source of truth. x-payment-info helps agents plan, but runtime challenges override it.
Protocol-agnostic: Lists all accepted payment methods (Stripe, Tempo, x402) so agents can choose.
Pricing modes: fixed (exact price) or dynamic (min/max range, e.g., bidding).
Cache-friendly: Recommended Cache-Control: max-age=300 on the OpenAPI spec.

Why it matters

Without x-payment-info, agents must hit every endpoint to discover if it's paid and how much it costs. With it, agents can read the spec once and plan their budget across multiple API calls.

How agentgrade checks for it

agentgrade reads your /openapi.json and checks if any operation has an x-payment-info extension. This is an optional check in the OpenAPI scoring group — it can help your score but won't hurt it if missing.

Learn more

paymentauth.org spec — Payment discovery draft specification