Qué es x402.
x402 es un protocolo abierto para pagos nativos de HTTP, publicado por Coinbase a finales de 2024. Define cómo un servidor devuelve 402 Payment Required con un cuerpo JSON estructurado - una lista de requisitos de pago aceptables (esquema, red, id de cadena, dirección del destinatario, monto en unidades base de USDC y un id de solicitud de pago) - para que un cliente de máquina pueda analizar la respuesta, pagar en la cadena y reintentar la llamada original con un encabezado X-Payment, todo programáticamente.
HTTP 402 estuvo sin usar durante treinta años. x402 lo hizo funcionar.
The 402 Payment Required status code was reserved in the original HTTP spec for "future use" and never received a standardized implementation. For three decades, every actual payment flow on the web was built on top of 200 / 401 / 403: a server returns 401 when authentication is missing, the client signs up via a separate UI flow, gets credentials, and re-authenticates. The signup happens out of band. None of this works for AI agents, which cannot complete signup forms.
x402 fixes this by giving 402 a usable specification. A server can return 402 with structured machine-readable payment instructions; a client can parse those instructions, pay, and retry, all without ever touching a signup form. The protocol is the missing piece between "AI agents can call APIs" and "AI agents can pay for the APIs they call". Before x402, the only practical agent payment paths were pre-paid balance accounts (with manual top-up) or proprietary integrations per API. Both broke at scale.
La importancia estratégica de x402 es que establece un estándar contra el cual el resto del ecosistema puede construir. Las billeteras implementan un manejador x402 una vez, y cada API compatible con x402 funciona con esa billetera. Los marcos de servidor implementan un middleware x402 una vez, y cada cliente consciente de x402 puede pagarles. Los facilitadores (servicios que liquidan los pagos subyacentes) compiten en calidad de servicio en lugar de en bloqueo.
Una respuesta, un reintento, un pago.
El ciclo de vida tiene tres estados: llamada no pagada, pago, llamada reintentada. A continuación se muestra cómo se ve realmente la respuesta de la llamada no pagada a través de la red.
HTTP/1.1 402 Payment Required Content-Type: application/json { "resource": "POST /api/research-query", "accepts": [ { "scheme": "exact-usdc", "network": "mainnet", "chainId": "eip155:8453", "payToAddress": "0xAgent...", "amountWeiUsdc": "50000", "paymentRequestId": "pr_01J9...", "maxAgeSeconds": 60 } ] }
- Status code 402. Distinct from 401 (auth missing) and 403 (auth refused). The presence of 402 signals "payment is the missing input."
- resource + accepts[]. El cuerpo nombra el recurso protegido y enumera uno o más requisitos de pago aceptables. Una migración puede cotizar dos requisitos (por ejemplo, mainnet y testnet) y dejar que el cliente elija.
- scheme / network / chainId. El esquema de pago (exact-usdc), la cadena (mainnet es Base) y su id CAIP-2. El cliente coincide con estos antes de pagar.
- payToAddress / amountWeiUsdc. La billetera del destinatario y la cantidad exacta en unidades base de USDC (50000 = 0.05 USDC, 6 decimales). El cliente verifica ambos antes de pagar.
- paymentRequestId + maxAgeSeconds. El id vincula el pago a esta cotización; maxAgeSeconds es cuán reciente debe ser el pago. Un pago que referencia un id diferente, o es más antiguo que la ventana, es rechazado.
- El reintento lleva un encabezado X-Payment. El cliente paga en cadena, luego vuelve a emitir la solicitud original con un encabezado X-Payment que prueba el pago. El servidor lo verifica y devuelve el resultado real. Ningún encabezado de respuesta o página alojada es parte del cable x402 en sí.
x402 en el mundo.
Tres implementaciones concretas, ordenadas por cuán madura es la adopción en cada capa.
Servidor MCP devolviendo un desafío 402 a una llamada de herramienta no pagada
Una herramienta MCP pagada recibe una invocación de Claude Desktop y el llamador aún no está marcado como pagado. El servidor construye un desafío requirePayment - un 402 cuyo cuerpo lleva el precio y un hostedUrl - y lo devuelve como un error de herramienta. Claude Desktop renderiza el enlace en el chat; el usuario paga $0.05 USDC; la siguiente llamada a la misma herramienta tiene éxito.
Control de acceso a la API por facturación por llamada
Una API de investigación cobra $0.50 por llamada detrás del adaptador del servidor x402. Un agente de IA llama al endpoint, recibe un 402 que lista la cantidad y el destinatario, paga en Base desde su billetera y vuelve a emitir la solicitud con un encabezado X-Payment. El adaptador verifica el encabezado y devuelve la respuesta pagada. Todo el bucle se completa en menos de 60 segundos.
Agente pagando programáticamente a través de una billetera compatible con x402
El tiempo de ejecución de un agente es consciente de x402 (implementa la especificación). Cuando recibe un 402, lee el payToAddress y la cantidad de accepts[], firma una transferencia desde su billetera preautorizada (dentro de su permiso de gasto), transmite en Base y reintenta la llamada original con un encabezado X-Payment. Sin intervención humana; el ciclo se completa en 5-10 segundos.
Qué rodea a x402 en la pila.
x402 es el protocolo. Estos tres términos cubren los conceptos sobre los que se basa y los casos de uso que habilita.