Panel
ES
Empieza gratis

Cómo un agente de IA paga cada búsqueda web con x402

Sin cuenta ni API key: el challenge 402 real que devuelve FastAF, el cliente Node que lo paga en USDC sobre Base y cómo limitar lo que el agente puede gastar por llamada.

Un agente que necesita una sola búsqueda en Google no debería pasar por un formulario de registro, una API key guardada en un gestor de secretos y un saldo prepagado. Con x402 envía la solicitud, recibe un precio, lo paga desde su propio wallet y obtiene los datos. Aquí tienes el viaje de ida y vuelta completo contra FastAF, con el challenge real y el código real del cliente.

¿Qué es x402?

x402 recupera el código HTTP 402 Payment Required, que llevaba décadas en la especificación sin que nadie lo usara. El servidor responde a una solicitud no pagada con un 402 y un precio legible por máquina; el cliente paga y repite la misma solicitud. En la versión 2 del protocolo esto viaja en tres cabeceras, cada una con JSON codificado en base64: PAYMENT-REQUIRED (del servidor al cliente, el precio), PAYMENT-SIGNATURE (del cliente al servidor, el pago firmado) y PAYMENT-RESPONSE (del servidor al cliente, el resultado de la liquidación), tal como se describe en docs.x402.org, consultado el 19 de octubre de 2026.

El pago en sí es una transferencia de stablecoin, en la práctica USDC sobre Base. El cliente firma una autorización; un facilitador la contrasta con los requisitos del servidor y la envía a la cadena. La documentación del facilitador deja claro que “does not hold funds or act as a custodian”. El protocolo nació como incubación en Coinbase y se cedió a la x402 Foundation, bajo la Linux Foundation, según se anunció el 2 de abril de 2026, con licencia Apache-2.0.

¿Cómo es el challenge 402?

Todos los endpoints de FastAF están disponibles en https://api.fastaf.co/x402/v1/{endpoint} con los mismos parámetros que la API con clave. La primera solicitud no cuesta nada:

curl -i "https://api.fastaf.co/x402/v1/serp?query=x402+payment+protocol"

El 19 de octubre de 2026 esto devolvió HTTP/2 402 en 0,24 segundos. Al decodificar la cabecera payment-required se obtiene (recortado):

{
  "x402Version": 2,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "5000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x05B75e13f071A09A26B50a18Ce5BD02a0755d76F",
    "maxTimeoutSeconds": 300,
    "extra": { "name": "USD Coin", "version": "2" }
  }]
}

Campo por campo:

  • scheme: "exact": paga exactamente este importe, ni un céntimo más.
  • network: "eip155:8453": la mainnet de Base, en notación CAIP-2.
  • amount: "5000": unidades atómicas. USDC tiene 6 decimales, así que 5000 son 0,005 $, el precio de una búsqueda.
  • asset: el contrato de USDC en Base. La propia tabla de activos por defecto del SDK recoge la misma dirección como USDC.
  • payTo: la dirección que recibe el pago.
  • maxTimeoutSeconds: 300: la autorización firmada es válida durante cinco minutos.
  • extra.name y extra.version: el dominio EIP-712 del token, que el cliente necesita para firmar una autorización de transferencia válida.

Un detalle que conviene saber: los parámetros se validan antes de cotizar ningún precio. La misma URL sin q devolvió 400 invalid_parameters, no un 402, así que a un agente nunca se le pide pagar por una solicitud mal formada.

¿Cómo lo paga el agente en Node?

Los paquetes oficiales se encargan del parseo, la firma y el reintento. Las versiones de abajo son las actuales en npm (@x402/fetch 2.28.0, con @x402/core y @x402/evm en la misma versión):

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const client = new x402Client();
registerExactEvmScheme(client, {
  signer: privateKeyToAccount(process.env.AGENT_WALLET_KEY),
  networks: ["eip155:8453"],
});

// Rechaza cualquier pago individual por encima de un centavo.
client.setSpendControls({ maxAmountPerPayment: "$0.01" });

// Deja de pagar cuando esta ejecución haya gastado 0,05 $ (unidades atómicas de USDC).
let spent = 0n;
client.onBeforePaymentCreation(async ({ selectedRequirements }) => {
  const amount = BigInt(selectedRequirements.amount);
  if (spent + amount > 50_000n) return { abort: true, reason: "run budget exhausted" };
  spent += amount;
});

const fetchWithPayment = wrapFetchWithPayment(fetch, client);
const res = await fetchWithPayment("https://api.fastaf.co/x402/v1/serp?query=x402+payment+protocol");
console.log(res.status, res.headers.get("X-FastAF-Credits-Used"));

Sin setSpendControls, @x402/core ya limita cada pago a DEFAULT_MAX_AMOUNT_PER_PAYMENT, que en el código fuente instalado vale "$1". Para una API de búsqueda es demasiado generoso; ajústalo a lo que cueste tu llamada más cara.

Ejecutamos este script el 19 de octubre de 2026 con un wallet recién generado y sin USDC, así que no se completó ninguna llamada pagada: la respuesta 200 con el recibo PAYMENT-RESPONSE es lo que hace el SDK con un wallet con fondos. Lo que sí pasó: con el límite en $0.002, el SDK rechazó el pago en local en 91 ms, antes de firmar nada (“rejected by spendControls.maxAmountPerPayment”). Con el límite en $0.01 parseó el 402, firmó, reintentó, y el servidor volvió a responder 402 con invalid_exact_evm_insufficient_balance. No se ejecutó ninguna búsqueda y no se liquidó nada.

¿Por qué importa que “solo se liquide si sale bien” para los agentes?

Los agentes fallan muchas llamadas: una consulta mala, una página que agota el tiempo de espera, un destino que no está permitido. En FastAF el pago firmado se liquida solo después de que la solicitud upstream haya salido bien. Si la llamada falla, la autorización nunca se envía y caduca pasados maxTimeoutSeconds, así que el wallet conserva su dinero. La API con clave sigue la misma regla: las solicitudes fallidas nunca se cobran.

Los precios son el coste en créditos de la API con clave a 0,001 $ por crédito. Estos importes se leyeron de challenges reales el 19 de octubre de 2026:

Solicitud Créditos Importe x402 Precio
/scrape, página estática 1 1000 0,001 $
/serp, búsqueda de Google 5 5000 0,005 $
/shopping 10 10000 0,01 $
Perfil de /linkedin 60 60000 0,06 $

¿Cuándo conviene más pagar créditos por adelantado?

x402 encaja con un agente que hace llamadas ocasionales, que corre en un sitio donde no puedes aprovisionar una clave, o que debe pagar de su propio presupuesto. Los créditos prepagados ganan en tres casos:

  • Volumen. Un pack Starter de 10 $ son 20.000 créditos, así que 1.000 búsquedas cuestan 2,50 $ en lugar de 5,00 $ con x402, y 1,50 $ con el pack Pro. Los créditos son válidos durante 12 meses, sin suscripción.
  • MCP. El servidor MCP alojado en https://api.fastaf.co/mcp se autentica con una clave Bearer; no acepta pagos x402.
  • Un tope duro en la cuenta. Un saldo agotado devuelve 402 insufficient_credits y se detiene, decida lo que decida el agente. El post sobre el límite de gasto muestra cómo combinarlo con un presupuesto por ejecución.

¿Cómo mantienes seguro el wallet del agente?

La clave privada vive en el entorno del agente y firma sin preguntar a nadie, así que trátala como un hot wallet:

  • Usa un wallet dedicado por agente, nunca uno que guarde cualquier otra cosa.
  • Cárgalo con importes pequeños y recárgalo de forma deliberada; el saldo es tu peor caso.
  • Fija maxAmountPerPayment al precio de tu llamada más cara, más un presupuesto por ejecución en el hook.
  • Fija networks en eip155:8453 para que el cliente nunca pague en una cadena que no tenías prevista.

En resumen

x402 convierte una respuesta 402 en una etiqueta de precio: decodifica PAYMENT-REQUIRED, firma la autorización en USDC y reintenta con PAYMENT-SIGNATURE. En FastAF una búsqueda cuesta 0,005 $, se liquida solo si sale bien, y los controles de gasto del SDK limitan cada pago antes de firmar nada. El flujo completo está en la sección de x402 y todos los precios en precios. Para volumen o MCP, crea una cuenta gratis y empieza con 500 créditos, sin tarjeta.