El buyer stack de x402: cómo pagan los agentes

Cada post de x402 en esta serie cubrió hasta ahora el lado que cobra: schemes, facilitators, discovery, settlement. Este recorre la otra mitad — el cliente que recibe un 402, decide si paga, firma y reintenta. Ese code path es donde el dinero del agente sale realmente de la wallet.

El buyer stack es engañosamente pequeño. La integración canónica es un wrapper alrededor de fetch. Pero detrás de esa línea está toda la superficie de decisión de un comprador autónomo: en qué cadena pagar, qué llave firma, qué límites aplican y qué pasa cuando falla la creación del pago. A partir de la versión 2.19.0, publicada el 2026-07-17, los SDKs oficiales exponen todo eso — y la mayoría de los equipos solo usa el wrapper.

La mitad del handshake que le toca al buyer

El flujo del protocolo, visto desde el cliente, son cuatro pasos. El fetch envuelto hace el request inicial. Si el servidor responde 402 Payment Required, el SDK parsea el array accepts de payment requirements, crea y firma un payment payload para uno de ellos, y reintenta el request con el header PAYMENT-SIGNATURE. El quickstart para buyers describe exactamente esta secuencia, y es el mismo transport v2 que mapeamos desde el lado del servidor en el deep dive del facilitator.

El recibo vuelve por la misma vía por la que salió: como header. @x402/fetch incluye un helper decodePaymentResponseHeader, y el x402HTTPClient de más alto nivel envuelve el round trip completo — processResponse devuelve la respuesta de settlement decodificada junto al body. Si los posts anteriores enseñaron algo, es que los clientes deben conservar esos recibos: el transaction hash que llevan dentro es el único artefacto que permite auditar las afirmaciones de un facilitator contra un RPC independiente.

Un cliente, todos los rieles

La re-arquitectura v2 del SDK separó el buyer stack en paquetes ortogonales dentro del monorepo de la x402 Foundation: @x402/core para los tipos del protocolo, paquetes de mecanismo como @x402/evm y @x402/svm para las implementaciones de schemes, y bindings HTTP — fetch, axios, más los server-side express, fastify, hono y next — versionados en lockstep. La composición ocurre en el builder x402Client, indexada por patrones de red CAIP-2:

import { x402Client, wrapFetchWithPayment, x402HTTPClient } from '@x402/fetch';
import { ExactEvmScheme } from '@x402/evm/exact/client';
import { UptoEvmScheme } from '@x402/evm/upto/client';
import { ExactSvmScheme } from '@x402/svm/exact/client';

const client = new x402Client()
  .register('eip155:*', new ExactEvmScheme(evmSigner))    // todas las cadenas EVM
  .register('eip155:1', new ExactEvmScheme(mainnetSigner)) // override para mainnet
  .register('eip155:*', new UptoEvmScheme(evmSigner))
  .register('solana:*', new ExactSvmScheme(svmSigner));

const fetchWithPayment = wrapFetchWithPayment(fetch, client);
const response = await fetchWithPayment('https://api.example.com/paid');
const result = await new x402HTTPClient(client).processResponse(response);

Dos detalles importan aquí. Primero, los patrones específicos tienen precedencia sobre los wildcards — eip155:1 con un signer dedicado de mainnet anula el catch-all eip155:*. Así es como mantienes en el mismo proceso una hot key de bajo valor para testnets y una llave controlada por separado para mainnet. Segundo, los schemes se apilan: registrar UptoEvmScheme junto a ExactEvmScheme significa que el cliente puede responder a sellers que cotizan precios upto medidos además de precios exact fijos. El lado buyer de upto es deliberadamente aburrido — el SDK firma la autorización máxima y al buyer se le cobra el monto real liquidado.

La amplitud es mayor de lo que la mayoría asume. Más allá de EVM y Solana, los ejemplos oficiales de cliente registran implementaciones de schemes para Stellar, Keeta, Aptos, Concordium, Hedera y XRPL — cada una detrás de la misma llamada register(pattern, scheme). El buyer no elige un riel al integrar; declara para qué rieles puede firmar, y el array accepts del seller decide la intersección en tiempo de request.

La superficie de política: hooks y selectores

Esta es la parte del buyer stack que importa para agentes autónomos, y de la que casi nadie escribe. x402Client expone tres hooks de lifecycle de pago, encadenables en el builder:

const client = new x402Client()
  .register('eip155:*', new ExactEvmScheme(signer))
  .onBeforePaymentCreation(async ctx => {
    if (exceedsBudget(ctx.selectedRequirements)) {
      return { abort: true, reason: 'presupuesto diario agotado' };
    }
  })
  .onAfterPaymentCreation(async ctx => {
    audit.log(ctx.paymentPayload);  // recibos, métricas, alertas
  })
  .onPaymentCreationFailure(async ctx => {
    // devolver { recovered: true, payload: alternativo } para reintentar
  });

onBeforePaymentCreation corre antes de firmar nada y puede abortar devolviendo { abort: true, reason }. Eso lo convierte en el asiento natural de la política de gasto: topes de precio por request, presupuestos diarios, allowlists de payees. onAfterPaymentCreation es la toma de observabilidad — cada payload firmado pasa por ahí, que es exactamente donde un operador de agentes debería registrar recibos. onPaymentCreationFailure puede recuperarse devolviendo un payload alternativo, lo que habilita lógica de fallback entre redes o tokens — el análogo en pagos de las cadenas de fallback de modelos que usamos del lado de inferencia.

La elección de red es un punto de extensión separado y más limpio. El constructor de x402Client acepta una función selectora que recibe la lista completa de payment requirements del 402 y devuelve la que se va a pagar. El ejemplo oficial implementa preferencias ordenadas — EVM primero, luego Solana, luego Stellar — con fallback a la primera opción mutuamente soportada. Para un operador de flota esto es una palanca de costos: cuando un seller acepta una L2 y Solana al mismo precio nominal, el selector es donde codificas qué riel te resulta más barato de fondear, custodiar y reconciliar.

Custodia: tres formas de sostener la llave

Los ejemplos parten todos de privateKeyToAccount(process.env.EVM_PRIVATE_KEY), y eso está bien para un demo en testnet y es peligroso en producción, por las razones que detallamos en el deep dive de account abstraction: una llave cruda en el entorno de un agente es un mandato de gasto permanente e ilimitado. El buyer stack ofrece hoy tres posturas de custodia. Llaves crudas vía signers de viem o @solana/kit. Wallets gestionadas — el CdpX402Client de Coinbase conecta una wallet gestionada por CDP a wrapFetchWithPayment, de modo que el proceso nunca maneja una llave privada. Y delegación acotada — session keys y spend permissions — que el SDK acomoda vía su abstracción de signer: cualquier cosa capaz de producir la firma del scheme puede registrarse, incluida una session key cuyos límites se aplican on-chain y no en un hook.

Hay una conveniencia más del lado buyer fácil de pasar por alto: pasar un EVM_RPC_URL habilita extensiones de gas sponsoring (permits EIP-2612 y approvals ERC-20), permitiendo al cliente manejar tokens más allá de la ruta nativa EIP-3009 sin que el agente prefinancie gas. El RPC se usa para lecturas on-chain; el modelo de firma no cambia.

Más allá de fetch: axios, Python, MCP

El mismo núcleo de cliente monta otros transportes. @x402/axios (también 2.19.0) hace la danza de interceptar-y-reintentar para usuarios de axios. Los buyers en Python tienen pip install "x402[httpx]" y un x402HttpxClient que envuelve httpx igual que wrapFetchWithPayment envuelve fetch. Y @x402/mcp cierra el círculo para agentes que llaman tools: createX402MCPClient toma los mismos registros de schemes más un flag autoPayment y un callback onPaymentRequested que devuelve true o false — una compuerta de pago por tool call, de modo que un tool MCP que cuesta $0.10 se aprueba o rechaza por política antes de que exista firma alguna. Para agentes cuya interfaz completa con el mundo es MCP, ese callback es el buyer stack.

Qué significa para LLM4Agents

LLM4Agents está en ambos lados de este handshake. Como seller, el gateway cobra la inferencia detrás de depósitos Bearer y x402 walk-up, según el árbol de decisión que publicamos. Pero los agentes que corren nuestros operadores son buyers: llaman APIs externas pagas, tools MCP con precio x402 y servicios de datos descubiertos vía Bazaar. El buyer stack es la última milla entre un runtime de agente y todos los rieles de settlement que cubrió esta serie — y su superficie de política (hooks, selectores, compuertas de pago) tiene exactamente la forma de los controles de gasto que nuestros operadores piden, pero aplicados client-side, por agente, en vez de platform-side, por cuenta.

Eso es una oportunidad y una amenaza. Oportunidad: una plataforma que entrega un cliente buyer preconfigurado — hooks de presupuesto cableados a la facturación de la plataforma, recibos cableados a su observabilidad — elimina el filo más peligroso de la autonomía del agente para sus usuarios. Amenaza: si la política de gasto se estandariza dentro del cliente open source, la capa de billing de la plataforma tiene que interoperar con él en vez de reemplazarlo, o los operadores esquivarán la plataforma para sus pagos salientes.

Cómo mantenerse en la frontera

Secuencia concreta para la plataforma, en orden de prioridad:

• Publicar un preset de buyer. Un paquete delgado que devuelva un x402Client precableado: enforcement de presupuesto en onBeforePaymentCreation, captura de recibos en onAfterPaymentCreation, recuperación cross-network en onPaymentCreationFailure, defaults para Base y Solana.
• Llevar los hooks a observabilidad. Cada payload firmado y cada razón de aborto debe caer en el mismo dashboard que rastrea el gasto en tokens — los pagos salientes son un stream de costos igual que la inferencia.
• Adoptar upto del lado buyer. Registrar UptoEvmScheme por defecto para que los agentes de la plataforma consuman sellers medidos como Apify sin trabajo de integración.
• Ofrecer tiers de custodia gestionada. Llave cruda para sandbox, wallet gestionada o signer de session key para producción — alineado con los límites on-chain del post de account abstraction, para que la frontera dura nunca viva en un callback.
• Cablear @x402/mcp en la capa de tools. La compuerta onPaymentRequested debe consultar el mismo presupuesto que los hooks HTTP, para que una sola política gobierne ambos transportes.

El arco x402 de este blog ya cubre schemes, settlement, facilitators, discovery — y, con este post, el cliente que paga. Lo que falta es la parte que ningún SDK entrega: decidir, por agente y por dólar, cuándo vale la pena pagar. Ese es un problema de economía, y es donde las plataformas de agentes van a competir de verdad.