## What is x-payment-info?

`x-payment-info` is an [OpenAPI](/kb/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`:

```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/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](https://paymentauth.org/draft-payment-discovery-00.html) — Payment discovery draft specification