AgentGrade
EnglishEspañol日本語中文
← Base de Conocimientos

x402 — Protocolo de Pago HTTP

¿Qué es x402?

x402 convierte el código de estado HTTP 402 Payment Required en un protocolo de pago real. Cuando un agente accede a un endpoint pagado, el servidor devuelve una respuesta 402 con un encabezado Payment-Required que contiene instrucciones de pago estructuradas. El agente (o su wallet) inspecciona el encabezado, decide si el precio es aceptable, paga en cadena, adjunta el recibo a un reintento y recibe la respuesta.

Conceptualmente, x402 finalmente completa el código de estado HTTP 402 que ha permanecido sin uso en la especificación HTTP desde 1996 — la especificación reservó el código para "Payment Required" pero nunca especificó cómo debía pagar un cliente. x402 especifica el mecanismo: USDC en Base, intenciones de pago firmadas, liquidación mediada por facilitador, y un formato de descubrimiento para que los agentes encuentren endpoints pagados antes de llamarlos.

Por qué importa x402

La monetización tradicional de API está construida para humanos: registrarse, generar una clave de API, gestionar una tarjeta de crédito, recibir una factura mensual. Cada paso requiere una interfaz, una cuenta y una relación fuera de banda entre el proveedor de la API y el desarrollador.

Los agentes autónomos no tienen esas cosas. Un agente que llama a una API pagada por primera vez necesita:

x402 aborda los cuatro con un único mecanismo. El precio está en el encabezado 402. El pago es una transacción firmada en Base. La liquidación es sub-segundo. El recibo es la confirmación en cadena.

Esto hace de x402 la primitiva de pago fundacional para la web agéntica — análogo a lo que fue TLS para la web comercial, o OAuth para la autorización delegada: un protocolo que convierte algo previamente mediado por humanos en algo que las máquinas pueden negociar de extremo a extremo.

Cómo funciona

  1. El agente envía una petición a un endpoint pagado
  2. El servidor devuelve HTTP 402 con un encabezado Payment-Required codificado en base64
  3. El encabezado contiene: monto, activo (USDC), red (Base), wallet receptor y facilitador
  4. El agente paga vía el facilitador (p. ej., Coinbase)
  5. El agente reintenta la petición con un encabezado Payment que contiene el recibo
  6. El servidor verifica el pago a través del facilitador y sirve la respuesta

El flujo completo tarda unos pocos segundos de extremo a extremo. Sin claves de API. Sin suscripciones. Sin humano en el bucle.

x402 frente a monetización tradicional de API

AspectoClaves de API + suscripciónx402
RegistroCuenta requeridaNinguno
AutenticaciónClave de API por cuentaPago por petición
Modelo de facturaciónSuscripción mensualPago por petición
DescubrimientoFuera de banda (docs, ventas)En el protocolo (encabezado 402)
LiquidaciónCiclo de factura (~30 días)Sub-segundo (en cadena)
Modo de falloCuota excedida → 429Pago insuficiente → 402
Compatibilidad con agentesDifícil (gestión de cuentas)Nativa
Limitaciones geográficasComunes (restricciones de Stripe)Mínimas (en cadena)

El cambio clave: x402 pone el precio dentro del propio protocolo, donde cualquier agente puede leerlo. Con claves de API, el precio existe sólo en un contrato negociado entre humanos. Con x402, el precio está en la respuesta HTTP, de la misma manera que lo está el código de estado — metadatos de transporte de primera clase, no papeleo.

Conceptos clave

Quién usa x402

El ecosistema x402 se ha formado en torno a dos anclas:

Más allá de esas anclas, proveedores individuales de API, runtimes de agentes y operadores de servidores MCP están integrando x402 para facturación por llamada — herramientas MCP pagadas, APIs de datos medidas, endpoints de inferencia de IA y mercados de agentes.

Cómo añadir x402 a tu servicio

1. Instala el SDK

npm install @coinbase/x402-express

2. Añade middleware a tu app Express

import { paymentMiddleware } from '@coinbase/x402-express';

app.use('/api/paid-endpoint', paymentMiddleware({
  payTo: '0xYourWalletAddress',
  amount: '100000', // 0.10 USDC (unidad mínima)
  network: 'base',
  facilitator: 'coinbase',
}));

3. Publica el archivo de descubrimiento

Sirve /.well-known/x402.json para que los agentes encuentren tus endpoints pagados:

{
  "x402Version": 2,
  "name": "Tu Servicio",
  "network": "base",
  "facilitator": "coinbase",
  "payTo": "0xYourWalletAddress",
  "services": [{
    "method": "POST",
    "path": "/api/paid-endpoint",
    "amount": "100000",
    "discoverable": true
  }]
}

4. Prueba el flujo

curl -i https://your-domain.com/api/paid-endpoint
# Espera: HTTP/1.1 402 Payment Required
# Espera: Payment-Required: <instrucciones de pago en base64>

Decodifica el encabezado Payment-Required (base64 → JSON) y confirma que el monto, activo, receptor y facilitador coinciden con la configuración del middleware.

Errores comunes y depuración

El escáner de AgentGrade prueba estos directamente — su comprobación x402 verifica que las respuestas 402 en vivo se parsean limpiamente y que el archivo de descubrimiento coincide con lo que devuelven los endpoints.

Preguntas frecuentes

¿Es x402 un protocolo de blockchain o un protocolo HTTP?

Ambos. El transporte es HTTP (un estado 402 con encabezados estructurados). La liquidación es en cadena (USDC en Base). x402 es el puente — el protocolo que permite a servidores HTTP y clientes HTTP negociar un pago que se liquida en una blockchain.

¿Necesito una wallet de cripto para aceptar pagos x402?

Sí. Necesitas una wallet de Base para recibir USDC. El CDP de Coinbase lo hace manejable para equipos no nativos en cripto — puedes aprovisionar una wallet custodiada vía API sin tocar claves.

¿Cuál es la diferencia entre x402 y Stripe?

Stripe es el riel tradicional dominante: claves de API por cuenta, suscripciones mensuales, detección de fraude entrenada con compradores humanos. x402 es por petición, nativo para agentes, y se liquida en cadena. Son complementarios — Stripe para checkout humano, x402 para acceso medido por agentes. Tempo MPP hace de puente entre ambos.

¿Está x402 listo para producción?

Sí. x402 v2 es soportado por Coinbase con SDKs oficiales en TypeScript, Go y Python. El facilitador canónico opera en producción y el ecosistema de servicios pagados está creciendo.

¿Pueden los agentes pagarse entre sí con x402, no sólo a proveedores de API?

Sí. A x402 no le importa si el "servidor" es una API operada por humanos, un agente o una herramienta MCP. Cualquier respondedor HTTP puede devolver un 402 y cualquier solicitante HTTP puede pagar. El trabajo medido entre agentes es uno de los casos de uso más activos.

¿Por qué USDC y no ETH?

Estable. Precio predecible. La mayoría de proveedores de API fijan precios en dólares y quieren un activo estable en dólares para liquidación; los activos volátiles crean fricción contable que anula el modelo por petición.

¿Qué pasa si el agente no tiene fondos?

La wallet devuelve fondos insuficientes y la llamada falla. No hay un flujo de reintento-comprar-créditos en el protocolo en sí — financiar es asunto de la wallet, no de la API.

¿Qué tan descubribles son los endpoints x402?

Los endpoints marcados como "discoverable": true en tu x402.json aparecen en el x402 Bazaar — el catálogo público de servicios pagados. Los agentes navegan el Bazaar igual que los desarrolladores navegan npm.

Madurez de la especificación

Listo para producción. x402 v2 es el envelope actual, soportado por Coinbase con SDKs oficiales en TypeScript, Go y Python. El protocolo es estable, el facilitador canónico opera en producción, y el ecosistema se expande por proveedores de herramientas MCP, APIs de datos y mercados de agentes.

Más información

Relacionado

Relacionado: ¿Qué es la preparación para agentes de IA?