Construye y lanza tu propia API x402

1. Por qué esto importa ahora

x402 es un protocolo de pago abierto, construido sobre el código HTTP 402 ("Payment Required") que existía en el estándar desde los años 90 sin que nadie lo usara. Coinbase lo revivió: cuando un agente de IA llama a una API sin pagar, el servidor responde 402 con instrucciones de pago legibles por máquina; el agente paga en USDC (stablecoin, siempre vale $1) por Base o Solana, reintenta, y recibe el recurso. Todo en segundos, sin cuentas, sin API keys.

El mercado creció de casi cero a más de 100 millones de transacciones acumuladas en menos de un año, con Visa, Mastercard, Google y Stripe uniéndose a la Fundación x402 en julio de 2026. Sigue siendo temprano — la mediana de los ~22.000 servicios listados gana centavos al mes — pero temprano es la palabra clave: quien construye ahora entra con historial cuando el mercado madure.

Esta guía documenta, paso a paso, cómo construimos Toolrail (toolrail.dev): una API real, en producción, cobrando dinero real en dos redes, con datos oficiales de siete países latinoamericanos. No es teoría — es el camino que caminamos, con los errores que cometimos y cómo los arreglamos.

2. La arquitectura mínima que funciona

Un servidor x402 no necesita nada exótico: un servidor HTTP normal (usamos Express/Node.js, pero el protocolo es agnóstico de lenguaje) con un middleware de pago delante de tus rutas. La pieza clave es el 'resource server': un objeto que sabe qué redes acepta, qué esquema de pago usa ('exact' es el estándar: precio fijo por llamada) y a qué dirección de wallet debe llegar el dinero.

El flujo interno en cuatro pasos: (1) la petición llega a tu servidor, (2) el middleware de pago revisa si trae comprobante de pago válido, (3) si no lo trae, corta la petición y responde 402 con un JSON codificado en base64 dentro de una cabecera describiendo cuánto cuesta y a quién pagarle, (4) si sí lo trae, verifica el pago contra un 'facilitador' (un servicio intermediario que confirma en la blockchain que el pago es real) y deja pasar la petición a tu código normal.

import express from "express";
import { paymentMiddleware, x402ResourceServer } from "@x402/express";
import { HTTPFacilitatorClient } from "@x402/core/server";
import { ExactSvmScheme } from "@x402/svm/exact/server";

const app = express();
const facilitator = new HTTPFacilitatorClient({ url: "https://x402.org/facilitator" });
const resourceServer = new x402ResourceServer(facilitator)
  .register("solana:<CAIP-2-network-id>", new ExactSvmScheme());

app.use(paymentMiddleware(
  { "GET /my-endpoint": { accepts: { scheme: "exact", price: "$0.01", network: "solana:...", payTo: "YOUR_WALLET" } } },
  resourceServer
));

app.get("/my-endpoint", (req, res) => res.json({ valuable: "data" }));
app.listen(3000);

3. El primer bug real: testnet vs. devnet de Solana

Esto nos costó una hora el primer día, y te la ahorramos. Solana tiene TRES redes de prueba con nombres confusos: 'devnet', 'testnet' y 'mainnet' (la real). El identificador que usamos al configurar la red importa letra por letra — usamos el de 'testnet' y el deploy falló con un error de 'facilitador no soporta este esquema en esta red', porque el facilitador gratuito de x402.org solo soporta 'devnet' para pruebas, no 'testnet'.

La lección generalizable: antes de fijar cualquier identificador de red, consulta el endpoint /supported de tu facilitador (todo facilitador serio lo expone) y usa exactamente lo que ahí aparece. No confíes en la documentación general del protocolo — confía en lo que tu facilitador específico soporta hoy.

4. Elegir facilitador: pruebas vs. producción

Para desarrollar y probar, el facilitador gratuito de x402.org basta y no requiere cuenta. Para producción — dinero real, y aparecer automáticamente en el índice de descubrimiento ('Bazaar') de Coinbase — necesitas el facilitador de Coinbase Developer Platform (CDP), que se activa con una cuenta gratuita y un par de llaves API.

Un detalle que documentamos porque no está claro en ningún lado: para que el Bazaar te catalogue de verdad (no solo proceses pagos), tu servidor debe registrar explícitamente la extensión de descubrimiento (bazaarResourceServerExtension del paquete @x402/extensions) en el resource server. Sin esa línea, puedes estar cobrando perfectamente y aun así ser invisible en el índice — lo descubrimos por accidente revisando la documentación con lupa después de varios días.

5. Cómo elegir QUÉ vender: el filtro de 3 preguntas

Antes de programar un solo endpoint, pásalo por este filtro. Un dato o cálculo vale la pena venderlo si cumple las tres condiciones:

• ¿Un agente lo necesita a mitad de una tarea? (no es curiosidad — bloquea el paso siguiente: "no puedo emitir la factura sin el tipo de cambio")
• ¿Es doloroso de mantener uno mismo? (tablas que cambian cada mes, reglas legisladas, formatos que se rompen — nadie quiere ser dueño de eso)
• ¿No existe una fuente gratuita confiable y estable? (o la que existe se cae seguido — la confiabilidad ES el producto)

Con ese filtro descartamos ideas atractivas pero equivocadas: datos de redes sociales (scraping en zona legal gris — los términos de servicio de la mayoría de plataformas prohíben explícitamente revender el acceso), sanciones internacionales (ya lo hacía bien otro servicio del ecosistema, entrar tercero no suma), sueldos mínimos regionales sin fuente verificable al día. Y encontramos oro donde nadie miraba: unidades de indexación de bancos centrales latinoamericanos, validación de identificadores tributarios de siete países, un agregador de tipos de cambio oficiales — nada de eso lo servía nadie más en todo el ecosistema.

6. De dónde sacar datos sin meterte en problemas

La regla de oro: fuentes oficiales o con licencia abierta explícita, nunca scraping de páginas que no lo autorizan. Antes de conectar cualquier fuente, verificamos tres cosas: (1) ¿el dato es un hecho público (un tipo de cambio oficial, un feriado legislado) o contenido con derechos de autor? Los hechos oficiales no tienen dueño. (2) ¿Existe una API o dataset publicado con licencia abierta (MIT, dominio público) o son datos internos protegidos por términos de servicio? (3) Si usamos un proyecto de un tercero, les avisamos y ofrecemos atribución — construye relaciones, no solo código.

Ejemplo de lo que evitamos: la API de YouTube prohíbe explícitamente revender el acceso a sus datos sin permiso escrito de Google, y las transcripciones ni siquiera están en su API oficial. Ejemplo de lo que sí hicimos: bancos centrales que publican sus series históricas en JSON abierto, sin necesitar ni siquiera una clave — ahí no hay ambigüedad posible.

Truco de investigador: cuando un banco central no documenta una API pública, abre su propio sitio web, mira en las herramientas de desarrollador del navegador qué llamadas hace su propio gráfico interactivo — casi siempre existe un endpoint interno JSON, sin key, que su equipo de frontend ya usa. Es 100% legítimo: es la misma data que muestran públicamente, solo que sin documentar formalmente.

7. El segundo bug real: JSON que no es JSON

Una de nuestras fuentes (un banco central) tiene un backend antiguo en PHP que, ocasionalmente, agrega volcados de advertencias de PHP DESPUÉS del JSON válido — cientos de caracteres de HTML de error pegados al final de una respuesta que, hasta ese punto, era JSON perfecto. JSON.parse() estándar falla con eso.

La solución no es 'esperar que no pase' — es defensiva: en vez de confiar en dónde termina la respuesta, contamos llaves { } balanceadas desde el primer '{' hasta que el contador vuelve a cero, y parseamos solo ese fragmento. Además, en fines de semana esa misma fuente devuelve el texto "n.d." en vez de un número — así que caminamos hacia atrás en la serie histórica hasta encontrar el último valor numérico real.

La lección: cuando integres una fuente gubernamental o de infraestructura antigua, NUNCA asumas que su JSON es JSON válido garantizado. Escribe el parser a la defensiva desde el día uno, con reintentos y extracción tolerante a basura.

8. El tercer bug real: la seguridad que se mordió la cola

Después de una auditoría de seguridad, agregamos una política CSP (Content-Security-Policy) muy estricta a nuestra página: 'default-src none' — bloquea cualquier recurso no autorizado explícitamente. Perfecto para bloquear scripts maliciosos... excepto que también bloqueó silenciosamente nuestro propio ícono de pestaña del navegador, declarado con un simple <link rel="icon"> en la misma página.

Nadie lo notó en los tests automáticos porque el servidor entregaba el archivo perfectamente — el bloqueo ocurría en el navegador del visitante, no en nuestro servidor. Lo encontramos porque alguien insistió en probar en dos navegadores distintos y modo incógnito antes de aceptar 'debe ser el caché'. La solución fue una línea: agregar 'img-src self' a la política.

La lección: cuando endurezcas la seguridad de una página, prueba CADA recurso que la propia página necesita cargar, no solo los que quieres bloquear.

9. Checklist de seguridad para producción

Lo mínimo que aplicamos antes de anunciar el servicio públicamente:

• Límite de tasa por IP (evita que una inundación de peticiones tumbe el servidor gratis)
• Cabeceras de seguridad: HSTS, X-Content-Type-Options nosniff, X-Frame-Options DENY, Referrer-Policy
• Sanitizar cualquier credencial (tokens, API keys) que pudiera aparecer en mensajes de error
• Si generas PDFs o renderizas HTML de terceros: deshabilita JavaScript y bloquea peticiones de red durante el render
• Manejador de errores que nunca exponga stack traces ni rutas internas — siempre JSON limpio y genérico hacia afuera
• Verifica tu propio historial de git en busca de secretos commiteados por accidente antes de hacer el repositorio público

10. Deploy: de tu computador a internet en una tarde

Usamos Render.com con Docker: un plan gratuito basta para probar, un plan de ~$7 USD/mes para producción real (el gratuito 'duerme' tras inactividad, lo que agrega segundos de latencia a la primera llamada). Si tu servicio genera PDFs o hace capturas de pantalla, tu Dockerfile necesita instalar Chromium.

El ciclo completo que usamos en cada cambio: escribir código → correr pruebas automáticas localmente → si pasan, subir a git → Render despliega automáticamente por el webhook → verificar desde afuera con curl que el cambio llegó a producción. Nunca confiar en que 'debería haber funcionado' — siempre verificar el resultado real.

11. Que te encuentren: los 5 canales reales

• El índice Bazaar de Coinbase: automático tras tu primer pago liquidado a través de su facilitador
• Directorios comunitarios (como x402-list.com): formulario de envío, prueban tus endpoints automáticamente
• Listas curadas en GitHub (como awesome-x402): se contribuye vía pull request
• x402scan y exploradores similares: indexan automáticamente según actividad on-chain real
• Un archivo /.well-known/x402.json en tu dominio: convención que permite a rastreadores automatizados descubrir tu catálogo

Ninguno de estos reemplaza la distribución humana: comunidades de Discord del ecosistema, foros de desarrolladores locales, y — si tu nicho tiene un aliado natural — el contacto directo genuino, ofreciendo algo de valor real en el mensaje.

12. La realidad de los números (sin inflar nada)

Sé honesto contigo mismo antes de empezar: la mediana de los servicios x402 gana centavos al mes. El mercado creció rapidísimo pero sigue siendo joven — la mayoría de las llamadas de valor alto (más de $1) se concentran en un puñado de servicios establecidos.

El valor real de construir ahora no es el ingreso inmediato — es la posición: historial acumulado en los índices de descubrimiento, aprendizaje profundo de una infraestructura que recién está madurando. Trátalo como una apuesta barata y bien pensada, no como un plan de ingresos garantizado.

Checklist de arranque

• Elige tu nicho con el filtro de 3 preguntas (sección 5) antes de escribir código
• Verifica la licencia/términos de cada fuente de datos antes de conectarla
• Configura el facilitador de pruebas (x402.org) primero; nunca actives dinero real sin probar el flujo completo
• … 6 puntos más en la versión PDF imprimible ↓