Protocolo x402: implementación de pagos HTTP 402 para API y agentes de IA

Qué estandariza realmente el protocolo x402

El protocolo x402 es una especificación abierta y neutral para pagos nativos de internet construida sobre el código de estado HTTP 402 Payment Required, que llevaba mucho tiempo inactivo. En lugar de redirigir al cliente a una página de pago, un servidor habilitado para x402 responde a una solicitud no pagada con una respuesta 402 cuyo cuerpo contiene instrucciones de pago legibles por máquina: cuánto pagar, a quién, en qué red y bajo qué esquema de pago. El cliente construye una carga útil de pago, reenvía la solicitud con un encabezado de autorización y un facilitador verifica y liquida el pago antes de que el servidor libere el recurso.

La propiedad de diseño importante es que la negociación del pago ocurre dentro de HTTP ordinario. No hay una sesión separada, creación de cuenta ni paso de aprovisionamiento de claves API en el flujo base. Eso hace que x402 sea un ajuste natural para la monetización de API y para agentes de IA que necesitan comprar pequeñas unidades de datos o cómputo sin que un humano complete un formulario de registro. La especificación es deliberadamente agnóstica a la red: pretende admitir múltiples cadenas y formas de valor, con esquemas individuales que definen el formato exacto de la carga útil.

Esta guía trata el protocolo como comportamiento documentado más decisiones de implementación que debes probar. No afirma cifras específicas de rendimiento, comisiones o finalidad para ninguna cadena o proveedor; esas dependen del riel que elijas y deben medirse en tu propio despliegue.

• Documentado: la forma del desafío/respuesta 402, las instrucciones de pago en el cuerpo de la respuesta y la verificación y liquidación basadas en facilitador.
• Tu decisión: qué red y esquema aceptar, en qué facilitador confiar y cuánta latencia tolera tu caso de uso.
• Tu medición: latencia de extremo a extremo de la solicitud pagada, tiempo de confirmación de liquidación y tasas de fallo bajo carga.

Supuestos y requisitos previos antes de construir

El recorrido a continuación asume que tienes un servicio Node.js (el middleware estilo Express es la integración más documentada), una billetera cliente financiada en una red de prueba y acceso a un endpoint de facilitador x402. También asume que puedes alcanzar un endpoint RPC confiable para la red de liquidación, porque tanto el facilitador como tu propia lógica de verificación necesitan leer el estado de la cadena.

Mantén los secretos fuera del control de versiones: carga PRIVATE_KEY y cualquier credencial del facilitador desde variables de entorno. Usa una billetera de prueba dedicada, nunca una clave de producción. Si aún estás eligiendo una red de liquidación o un proveedor RPC, la guía de endpoints RPC multicadena explica cómo la calidad del endpoint afecta la visibilidad de confirmación, y la guía de endpoints RPC cubre los conceptos básicos de los endpoints autenticados.

• Node.js 18+ y un gestor de paquetes.
• Un SDK de servidor x402 o paquete de middleware compatible con tu framework.
• Una billetera de red de prueba con un pequeño saldo del activo aceptado.
• Una URL de facilitador y una RPC_URL para la red de liquidación.
• Un entorno de staging donde los pagos fallidos no puedan afectar a clientes reales.

El ciclo de vida de la solicitud x402 como modelo mental

Piensa en x402 como un handshake de cuatro pasos que puede completarse dentro de un solo reintento del cliente. Primero, el cliente solicita un recurso protegido sin pago. Segundo, el servidor responde con 402 Payment Required y un cuerpo que describe las opciones de pago aceptables. Tercero, el cliente selecciona una opción, autoriza un pago y reintenta la solicitud original con un encabezado de pago. Cuarto, un facilitador verifica la carga útil y la liquida, y el servidor devuelve el recurso.

Dos detalles importan para la depuración. La respuesta 402 no es un error en el sentido tradicional: es una oferta estructurada, por lo que su cuerpo debe ser analizable y estable. Y la liquidación es asíncrona respecto a la verificación en muchas implementaciones: el facilitador puede confirmar la validez antes de la liquidación final en cadena, lo que significa que tu servidor debe decidir explícitamente si libera el recurso en la verificación o en la liquidación. Documenta esa elección, porque determina tu exposición a pagos fallidos o revertidos.

• Desafío: la solicitud no pagada recibe 402 más los requisitos de pago.
• Autorización: el cliente firma o construye una carga útil de pago y reintenta.
• Verificación: el facilitador comprueba la carga útil contra los requisitos declarados.
• Liquidación: el valor se mueve en el riel elegido; el servidor libera el recurso.

Proteger un endpoint de API con middleware de pago

La integración útil más pequeña declara qué rutas requieren pago y qué acepta el servidor. La configuración a continuación es ilustrativa: reemplaza la red, el activo, la dirección de pago y la URL del facilitador de marcador de posición con valores de la documentación de tu propio facilitador. La forma —mapa de rutas más un array accepts— es la parte que se generaliza entre SDK.

Observa que el middleware no contiene lógica de negocio. Intercepta solicitudes no pagadas, emite el desafío 402 y delega la verificación. Tu manejador se ejecuta solo después de que la ruta de pago tiene éxito, lo que mantiene las preocupaciones de monetización separadas de las de datos.

import express from "express";
import { paymentMiddleware } from "@x402/express";

const app = express();

app.use(
  paymentMiddleware(
    {
      "GET /v1/weather": {
        accepts: [
          {
            scheme: "exact",
            network: "base-sepolia",
            maxAmountRequired: "10000",
            resource: "https://api.example.com/v1/weather",
            payTo: process.env.PAY_TO_ADDRESS,
            asset: process.env.SETTLEMENT_ASSET,
            maxTimeoutSeconds: 60
          }
        ],
        description: "Current weather data"
      }
    },
    {
      facilitatorUrl: process.env.FACILITATOR_URL,
      rpcUrl: process.env.RPC_URL
    }
  )
);

app.get("/v1/weather", (req, res) => {
  res.json({ temperatureC: 21, condition: "clear" });
});

app.listen(3000, () => console.log("listening on :3000"));

Inspeccionar el desafío 402 con curl

Antes de escribir un cliente, confirma que el servidor emite un desafío bien formado. Una solicitud no pagada debe devolver el estado 402 y un cuerpo JSON que puedas analizar. Los nombres exactos de los campos dependen de la versión del esquema que implemente tu SDK, así que trata la salida a continuación como una plantilla para comparar con la especificación de tu facilitador, no como un contrato fijo.

Si recibes un 200 en lugar de un 402, el middleware no está coincidiendo con la ruta: verifica el método y la cadena de ruta, incluidos los slashes finales. Si recibes un 500, el middleware está fallando antes de poder construir el desafío, lo que normalmente significa una variable de entorno faltante o un facilitador inalcanzable.

curl -i https://api.example.com/v1/weather

# Expected shape (fields vary by scheme version):
# HTTP/1.1 402 Payment Required
# Content-Type: application/json
#
# {
#   "x402Version": 1,
#   "accepts": [
#     {
#       "scheme": "exact",
#       "network": "base-sepolia",
#       "maxAmountRequired": "10000",
#       "payTo": "0xYourAddress",
#       "asset": "0xAssetAddress",
#       "resource": "https://api.example.com/v1/weather"
#     }
#   ]
# }

Construir un cliente que paga y confirmar el acceso

Un cliente que paga debe analizar el cuerpo 402, elegir una opción aceptable, construir la carga útil de pago con su billetera y reintentar la solicitud original con el encabezado de pago. El cliente a continuación usa marcadores de posición para la clave de billetera y el facilitador; el flujo de control —solicitar, analizar, pagar, reintentar— es lo que debes reproducir en tu propio lenguaje.

El resultado de verificación que buscas es simple: la solicitud reintentada devuelve 200 con el cuerpo del recurso, y el facilitador informa un pago liquidado o verificado para esa carga útil. Registra el identificador de pago devuelto por el facilitador junto con tu ID de solicitud para poder conciliar ambos más tarde.

import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { baseSepolia } from "viem/chains";

const account = privateKeyToAccount(process.env.PRIVATE_KEY);
const wallet = createWalletClient({ account, chain: baseSepolia, transport: http(process.env.RPC_URL) });

const url = "https://api.example.com/v1/weather";

const first = await fetch(url);
if (first.status !== 402) throw new Error(`expected 402, got ${first.status}`);

const challenge = await first.json();
const option = challenge.accepts[0];
console.log("paying", option.maxAmountRequired, "to", option.payTo, "on", option.network);

// Build the payment payload using your x402 client SDK, then retry:
// const payload = await buildPaymentPayload({ wallet, option });
// const paid = await fetch(url, { headers: { "X-PAYMENT": payload } });
// console.log(paid.status, await paid.text());

Una medición reproducible de latencia y tasa de éxito

La corrección del protocolo y el rendimiento del protocolo son cuestiones separadas. Para medir lo segundo, ejecuta un número fijo de solicitudes pagadas contra staging y registra cuatro marcas de tiempo por solicitud: desafío recibido, pago enviado, recurso devuelto y liquidación confirmada. Calcula la mediana y el percentil 95 para cada intervalo en lugar de informar un único promedio, porque los flujos de pago tienen colas largas.

Registra los resultados en una tabla como la siguiente, completando tus propios números. No copies valores de documentación ni de otros despliegues: las comisiones, la finalidad y el comportamiento del facilitador difieren según la red y la carga. Ejecuta al menos tres sesiones en diferentes momentos del día e informa la dispersión.

• | Métrica | Sesión 1 | Sesión 2 | Sesión 3 | Notas |
• | --- | --- | --- | --- | --- |
• | Solicitudes intentadas | | | | N fijo, p. ej. 200 |
• | Desafíos 402 recibidos | | | | debería igualar los intentos |
• | Solicitudes pagadas que devuelven 200 | | | | tasa de éxito |
• | Mediana de desafío a recurso (ms) | | | | reloj del lado del cliente |
• | p95 de desafío a recurso (ms) | | | | comportamiento de la cola |
• | Mediana de envío a liquidación (ms) | | | | informado por el facilitador |
• | Pagos fallidos o expirados | | | | categorizar causas |

Solución de problemas que realmente verás

La mayoría de los problemas de integración de x402 caen en cuatro categorías: el desafío nunca aparece, el cliente no puede construir una carga útil válida, el facilitador rechaza el pago o el recurso se libera pero la liquidación falla después. Trabájalos en ese orden, porque cada etapa depende de la anterior.

Para síntomas a nivel de cadena —tiempos de espera al leer el estado de liquidación, nonces obsoletos o confirmaciones inconsistentes— el problema puede ser tu endpoint RPC en lugar del protocolo. La explicación del nonce en blockchain ayuda a diagnosticar transacciones atascadas o duplicadas, y si necesitas una conexión dedicada para el monitoreo de liquidación, revisa las opciones de nodo dedicado.

• No se devuelve 402: discrepancia de ruta, orden del middleware o un proxy que elimina el código de estado.
• Carga útil malformada: discrepancia de esquema o versión entre el desafío del servidor y el SDK del cliente.
• Rechazo del facilitador: maxTimeoutSeconds expirado, payTo incorrecto o red no admitida.
• Fallo de liquidación después de liberar: elegiste verificar-luego-liberar; agrega conciliación o cambia a liquidar-luego-liberar.
• Tiempos de espera intermitentes: verifica la salud del RPC y la accesibilidad del facilitador antes de cambiar el código del protocolo.

Compensaciones: lo que x402 no resuelve por ti

x402 elimina el aprovisionamiento de cuentas de la ruta de pago, pero no elimina la responsabilidad operativa. Sigues siendo dueño de la gestión de claves, la protección contra repetición, la idempotencia para solicitudes reintentadas y la decisión de política sobre cuándo liberar un recurso. También heredas las características de finalidad y comisiones del riel que aceptes, y esas características deben guiar tu configuración de tiempos de espera y reintentos.

También hay una compensación de UX. Los usuarios humanos pueden encontrar desconocido el pago basado en billetera, por lo que muchos equipos ejecutan x402 junto con la facturación convencional en lugar de reemplazarla. Y como el estándar es agnóstico a la red, aceptar múltiples opciones aumenta la flexibilidad pero multiplica las rutas de verificación que debes probar. Comienza con un esquema en una red de prueba, mide y luego expande.

Por último, la elección del facilitador es una decisión de confianza. Un facilitador que verifica pero no liquida, o que liquida lentamente, cambia tu perfil de riesgo. Lee su documentación, confirma qué pasos realiza y monitorea la liquidación de forma independiente en lugar de depender únicamente de sus respuestas de API.

Próximos pasos: de staging a un despliegue monitoreado

Una vez que un solo endpoint pasa el procedimiento de verificación anterior, promuévelo detrás de un flag de funcionalidad y agrega observabilidad antes de aumentar el tráfico. Emite registros estructurados para la emisión de desafíos, la verificación de pagos, la confirmación de liquidación y la liberación de recursos, todos correlacionados por ID de solicitud. Alerta sobre la proporción de desafíos a pagos exitosos, porque una caída repentina suele indicar una regresión del cliente o del facilitador en lugar de un cambio en la demanda.

Si tu monitoreo de liquidación depende de lecturas de cadena, elige un endpoint sobre el que puedas razonar. La página de precios de RPC explica cómo los planes se asignan al volumen de solicitudes, y el servicio de API de OnFinality describe el acceso gestionado en las redes admitidas. Para la pregunta concreta de qué endpoint o proveedor se ajusta a tu red de liquidación, usa RPC Assistant en lugar de adivinar: está hecho exactamente para esa recomendación breve. Explora las redes admitidas para confirmar que tu cadena objetivo está cubierta antes de comprometerte con un esquema.

• Lanza una ruta de pago detrás de un flag; mantén la ruta no pagada disponible para comparar.
• Agrega claves de idempotencia para que los reintentos del cliente no puedan cobrar dos veces.
• Concilia diariamente los ID de pago del facilitador con tus propios registros de solicitudes.
• Vuelve a ejecutar la tabla de latencia después de cualquier cambio de facilitador, SDK o RPC.