## ¿Qué es x-payment-info?

`x-payment-info` es una extensión de [OpenAPI](/kb/es/openapi) que indica a los agentes qué endpoints cuestan dinero y cuánto — antes de que hagan una solicitud. En lugar de disparar un 402 para conocer el precio, los agentes pueden leer la especificación OpenAPI por adelantado.

## Cómo funciona

Agrega la extensión a cualquier operación de pago en tu `/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/es/x402)": {} }
          ],
          "price": {
            "mode": "fixed",
            "amount": "0.50",
            "currency": "USD"
          }
        }
      }
    }
  }
}
```

## Conceptos clave

- **Informativo, no autoritativo**: La respuesta 402 siempre es la fuente de verdad. `x-payment-info` ayuda a los agentes a planificar, pero los desafíos en tiempo de ejecución la sustituyen.
- **Agnóstico al protocolo**: Lista todos los métodos de pago aceptados (Stripe, Tempo, x402) para que los agentes puedan elegir.
- **Modos de precio**: `fixed` (precio exacto) o `dynamic` (rango min/max, por ejemplo, para subastas).
- **Apto para caché**: Se recomienda `Cache-Control: max-age=300` en la especificación OpenAPI.

## Por qué importa

Sin `x-payment-info`, los agentes deben acceder a cada endpoint para descubrir si es de pago y cuánto cuesta. Con él, los agentes pueden leer la especificación una sola vez y planificar su presupuesto a través de múltiples llamadas a la API.

## Cómo lo verifica agentgrade

agentgrade lee tu `/openapi.json` y verifica si alguna operación tiene una extensión `x-payment-info`. Esta es una verificación opcional dentro del grupo de puntuación de OpenAPI — puede ayudar a tu puntuación pero no la perjudica si falta.

## Más información

- [Especificación de paymentauth.org](https://paymentauth.org/draft-payment-discovery-00.html) — Borrador de especificación de descubrimiento de pagos