El flujo del comprador en x402 v2: quién firma y quién liquida
x402 convierte 402 Payment Required en un paso de pago que funciona: una API de pago responde con un precio, el cliente firma un pago en stablecoin y reintenta, y el vendedor lo liquida y sirve la respuesta. Esta guía sigue un pago desde el lado del comprador, en x402 v2 con el esquema exact y USDC en Base. En resumen: el comprador firma y el vendedor liquida. Un comprador que liquida su propio pago es el error más común, y el final de esta guía explica por qué.
Las cuatro partes
| Parte | Papel |
|---|---|
| Comprador | El cliente que quiere el recurso. En un agente de IA, el código que hace la petición HTTP. |
| Cartera | Guarda el USDC y firma una autorización de transferencia. Puede ser una cartera CDP o una clave en la máquina del comprador. |
| Vendedor | La API de pago. Fija el precio y decide cuándo servir. |
| Facilitador | Un servicio que usa el vendedor para verificar el pago firmado y enviarlo a la cadena. |
Un plano de control del gasto como Burnbound añade un paso en el lado del comprador: antes de que la cartera firme, comprueba el pago contra las reglas del agente. No es parte del pago en sí. Nunca custodia fondos y nunca habla con el facilitador.
Paso 1: La primera petición recibe un 402
El comprador envía una petición normal:
GET /v1/report HTTP/1.1
Host: api.example.com
El vendedor responde 402 Payment Required con una cabecera PAYMENT-REQUIRED. Su valor es un JSON en base64 que enumera lo que acepta el vendedor:
{
"x402Version": 2,
"resource": { "url": "https://api.example.com/v1/report" },
"accepts": [
{
"scheme": "exact",
"network": "eip155:8453",
"asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"amount": "10000",
"payTo": "0x…",
"maxTimeoutSeconds": 60
}
]
}
amount va en la unidad más pequeña del activo. USDC tiene 6 decimales, así que 10000 son 0.01 USDC. network es un id CAIP-2: eip155:8453 es Base y eip155:84532 es Base Sepolia. Un vendedor puede listar varias entradas, por ejemplo Base y Solana. El comprador elige una que pueda pagar.
En x402 v1 la misma información llegaba en el cuerpo de la respuesta, y las cabeceras eran X-PAYMENT y X-PAYMENT-RESPONSE. v2 la pasó a las cabeceras PAYMENT-*.
Paso 2: El comprador decide si paga
Este es el paso que x402 deja al comprador, y donde un agente necesita reglas. Antes de firmar, comprueba como mínimo:
- El host. ¿Es un vendedor al que el agente puede pagar?
- El recurso. ¿Apunta
resource.urlal host que respondió? Un challenge que nombra otro host es una señal de alarma. - El importe, contra un máximo por pago y lo que queda de un presupuesto diario.
- La red y el activo. Paga solo donde la cartera tiene fondos y donde querías pagar.
Con Burnbound, el servidor MCP envía el challenge y la URL a la API de Burnbound, que evalúa la política del agente y responde permitir, denegar o step-up (una persona tiene que aprobarlo). Un pago denegado nunca se firma. Uno permitido queda registrado y cuenta para el tope diario desde ese momento. Consulta Cómo limitar el gasto de un agente de IA.
Paso 3: La cartera firma una autorización EIP-3009
Para USDC, el esquema exact usa TransferWithAuthorization de EIP-3009: una firma EIP-712 que deja a otro mover un importe fijo de la cartera a payTo, una sola vez y dentro de una ventana de tiempo. La autorización firmada tiene estos campos:
| Campo | Valor |
|---|---|
from |
La cartera del comprador. |
to |
El payTo del vendedor. |
value |
El amount del challenge. |
validAfter |
Cuándo empieza a ser válida la autorización (segundos Unix). |
validBefore |
Cuándo deja de ser válida. Mantenla corta. |
nonce |
32 bytes. El contrato de USDC acepta cada nonce de una cartera una sola vez. |
Burnbound deriva el nonce del id del pago, así que la misma compra siempre produce el mismo nonce y puede mover dinero como mucho una vez, aunque se vuelva a firmar por error. La cartera no necesita ETH: la firma no es una transacción.
Paso 4: El comprador reintenta con PAYMENT-SIGNATURE
El comprador repite la misma petición una vez, con la carga firmada en una cabecera PAYMENT-SIGNATURE (JSON en base64):
{
"x402Version": 2,
"resource": { "url": "https://api.example.com/v1/report" },
"accepted": {
"scheme": "exact",
"network": "eip155:8453",
"amount": "10000",
"…": "…"
},
"payload": {
"signature": "0x…",
"authorization": {
"from": "0x…",
"to": "0x…",
"value": "10000",
"validAfter": "…",
"validBefore": "…",
"nonce": "0x…"
}
}
}
accepted es la propia entrada del vendedor, sin cambios. Dos reglas hacen seguro este reintento:
- Envíalo a la URL que lo pidió. No sigas una redirección con un pago firmado encima.
fetch_paidnunca sigue redirecciones después de pagar. - Envíalo una vez. Si la respuesta se pierde, no firmes un pago nuevo. Con Burnbound, un reintento con la misma clave de idempotencia repite la misma compra y nunca cobra dos veces.
Paso 5: El vendedor liquida y sirve
El vendedor pasa la carga a su facilitador, que comprueba la firma, el importe, el payee y la ventana de tiempo, y envía la transferencia al contrato de USDC. El facilitador paga el gas. Después, el vendedor responde 200 con el recurso y una cabecera PAYMENT-RESPONSE que indica si la liquidación salió bien, con el hash de la transacción.
Cuándo liquida exactamente el vendedor, antes o después de ejecutar su handler, depende de su middleware. En cualquier caso, quien envía la transferencia es el facilitador del vendedor.
Paso 6: El comprador registra el recibo
El comprador guarda el PAYMENT-RESPONSE como recibo. El servidor MCP de Burnbound se lo comunica a Burnbound, que comprueba la transferencia en la cadena antes de marcar el pago como settled. Si el vendedor responde a la petición pagada con algo distinto de un 2xx, el resultado es un error (payment_rejected_by_seller o payment_not_completed), nunca paid, y el recibo fallido queda en el registro de auditoría.
Por qué el comprador nunca debe liquidar
El endpoint /settle del facilitador es para el vendedor. Un comprador, o una herramienta que actúa por él, que envía su propia autorización rompe el flujo:
- Pagas sin que te sirvan. La liquidación mueve el USDC tanto si el vendedor responde como si no. El vendedor todavía no ha aceptado nada.
- Después el vendedor te rechaza. Cuando el vendedor intenta liquidar la misma autorización, el nonce ya está usado, así que su facilitador la rechaza. Recibes un error u otro 402 en lugar del recurso.
- Eliges un facilitador que el vendedor no eligió. El vendedor se fía de la verificación de su propio facilitador, no de la tuya.
Así que un comprador firma y envía; nunca llama a /verify ni a /settle. Burnbound lo cumple: ni tu agente ni Burnbound llaman a un facilitador. Consulta Conceptos para ver el mismo flujo en términos de Burnbound.
Prueba el flujo sin escribir un cliente
El servidor MCP de Burnbound ejecuta todo este flujo del comprador dentro de una sola herramienta, fetch_paid, con las comprobaciones de arriba incluidas. Para verlo con vendedores reales, elige uno del catálogo de APIs x402, como Exa o CoinGecko, y sigue Cómo pagar una API x402 desde Claude Code. Para configurarlo desde cero, empieza por los Primeros pasos. x402 es una de las formas en que Burnbound controla lo que gasta un agente: la misma política cubre los reembolsos de Stripe y las tarjetas de Stripe Issuing.