x-payment-info — Descubrimiento de Pagos en OpenAPI

¿Qué es x-payment-info?

x-payment-info es una extensión de 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:

{
  "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 — Borrador de especificación de descubrimiento de pagos