¿Se puede agregar x402 a una API existente sin código? Sí: este es el paso a paso

Payzum es un procesador de pagos cripto sin custodia y enfocado en stablecoins: los pagos se liquidan directo en wallets que controla el comercio. En x402 eso significa que el USDC que paga un agente por una llamada llega a la dirección de Base que configuras, no a un saldo de Payzum. Esta guía es la versión clic a clic de esa configuración: qué necesitas antes de empezar, los cinco campos que importan, cómo probarlo gratis y qué revisar antes de cobrar dinero real.

¿Puedes agregar pagos x402 a una API existente sin escribir código?

Sí, si pones un proxy delante de la API en vez de cambiar la API. x402 es un protocolo abierto que le da un significado concreto al estado HTTP 402 Payment Required: el servidor responde a una petición sin pago con un precio, el cliente firma un pago en stablecoins y reintenta, y el servidor devuelve los datos. Alguien tiene que hablar ese protocolo. La pregunta es si lo hace tu servicio o una capa delante de él.

Con Payzum es la capa de delante. Publicas una puerta adicional, con precio, hacia el endpoint que ya operas. Tus clientes actuales siguen llamando a tu API igual que antes; los agentes llaman a la URL x402, reciben un 402 con tu precio, pagan y reciben la respuesta de tu origen sin cambios. La configuración vive en el dashboard del comercio, por eso un proveedor de API puede empezar a servir agentes el mismo día. Conviene dejar claro el reparto de roles, porque muchos proveedores lo mezclan:

Payzum no es el facilitador. Serlo es una ambición futura, no una afirmación sobre hoy. La documentación de x402 describe al facilitador como el servicio que verifica los pagos y los liquida en la blockchain, y es explícita: «no custodia fondos ni actúa como custodio» (docs.x402.org, página Facilitator, consultada el 20 de octubre de 2026).

Por qué agregar x402 por tu cuenta sigue siendo un proyecto

La referencia honesta es la guía oficial para vendedores. A 20 de octubre de 2026 te pide instalar los paquetes de x402 para tu framework (el middleware para Express, Next.js, Hono y Fastify, módulos de Go para Gin y Echo, o el paquete de Python para FastAPI y Flask), apuntar el middleware a un facilitador, listar las rutas que quieres proteger e indicar la dirección de tu wallet. Es buena documentación y una tarde razonable para un equipo dueño de su código. Pero también es un cambio en tu servicio, con su despliegue, su revisión y su plan de reversa.

Dos detalles de esa misma documentación pesan en producción. El facilitador público de x402.org que usa la guía funciona solo en Base Sepolia y Solana devnet, y los docs advierten que es para desarrollo y testnet, no para mainnet. Para mainnet necesitas un facilitador de producción, uno propio o autofacilitación. En la práctica eso significa abrir una cuenta con un proveedor y guardar sus credenciales en la configuración de tu servicio. El CDP Facilitator de Coinbase, por ejemplo, se autentica con el ID y el secreto de tu API key de CDP (docs de CDP, consultados el 20 de octubre de 2026).

Lo que te cuesta esperar a un cambio de código

El costo casi nunca es la tarde. Es la cola. Muchas de las APIs que valdría la pena vender a agentes viven donde cambiar un middleware no es una edición rápida: un producto alojado por un tercero que configuras pero no puedes parchear, un servicio heredado que nadie quiere volver a desplegar, un monorepo con calendario de releases, una API que pertenece a otro equipo distinto del que quiere los ingresos. La idea de x402 muere en la primera reunión de planificación, antes de que nadie sepa si un solo agente pagaría.

Eso importa porque la demanda sigue siendo incierta. La auditoría de Bitquery sobre los pagos x402 de 2026, que comentamos en la primera auditoría de x402, encontró que el vendedor mediano en Base ganaba unos 2,50 dólares al mes. Para un mercado así, el formato correcto es un experimento pequeño y reversible: una ruta, un precio, un interruptor para apagarla. Un proyecto es el formato equivocado.

Por qué las vías habituales pesan más de lo que parece

Hay tres formas comunes de poner x402 delante de una API y cada una trae un costo fácil de pasar por alto.

• Escribir el middleware en tu servicio. Control total y es el camino de referencia en la documentación. Eres dueño de la integración con el facilitador, de la tabla de rutas, del manejo de claves y de cada actualización cuando la especificación cambia (x402 ya tuvo una migración de V1 a V2).
• Montar tu propio gateway o función en el edge. No tocas el servicio, pero ahora operas, monitoreas y aseguras un componente nuevo en el camino del dinero.
• Usar una plataforma que liquida en su propio saldo. Rápido para empezar, pero los ingresos quedan en la plataforma hasta un retiro, que es el modelo de custodia que la mayoría de los negocios de API quería dejar atrás.

Un proxy de solo configuración que liquida en tu propia dirección elimina las tres cosas: ningún código en tu servicio, ningún gateway que operar y ningún saldo en el medio. Si antes quieres el panorama de quién hace qué en el ecosistema, lee el mapa del ecosistema x402.

Cómo Payzum agrega x402 sin tocar tu API

Payzum mantiene una correspondencia entre una URL x402 pública y tu endpoint privado. Cuando un agente llama a la URL pública sin pagar, Payzum responde 402 Payment Required con el precio exacto. Cuando el agente reintenta con un pago firmado, Payzum lo valida con el facilitador externo, reenvía la petición a tu origen con tu credencial adjunta y devuelve la respuesta. Tu servicio atiende la llamada como cualquier otra petición.

# 1 — el agente pide (sin pagar)
GET /v1/x402/pzm_tucomercio/market-data

# 2 — Payzum responde con el desafío
HTTP/1.1 402 Payment Required
→ price: 0.01 USDC · network: base · asset: USDC

# 3 — el agente firma una autorización de USDC y reintenta
GET /v1/x402/pzm_tucomercio/market-data
(pago firmado adjunto)

# 4 — verificado con el facilitador y reenviado a tu origen
HTTP/1.1 200 OK     ← la respuesta de tu origen, sin cambios

El activo es USDC en Base mainnet, un ERC-20 con seis decimales, así que un precio de 0,01 USDC es exactamente un centavo y uno de 0,001 USDC sigue siendo un pago real. El agente firma una autorización de transferencia EIP-3009 en vez de emitir él mismo una transacción, y eso es lo que hace viable una llamada de una fracción de centavo. Base confirma en unos dos segundos y el pago es final al liquidarse: sin contracargos y sin una red de tarjetas que decida si el dinero es tuyo.

Cómo agregar x402 a tu API, paso a paso

Todo lo que sigue es configuración del dashboard. Calcula unos 20 minutos para la primera ruta, casi todos en la cuenta de facilitador si todavía no tienes una.

Antes de empezar

• Un endpoint accesible por HTTPS desde internet. Es el «origen»: la URL a la que Payzum reenviará las llamadas pagadas.
• La credencial que espera tu origen, si la hay: una API key o un bearer token. Si hoy el endpoint está abierto, crea primero una clave para él (ver el paso 3).
• Una dirección de Base que controles y que recibirá el USDC.
• Para mainnet, tu propia cuenta de facilitador. Payzum llama a un facilitador externo, hoy el de Coinbase, con credenciales que tú aportas. Para probar puedes saltarte esto y usar la opción gratuita de testnet.

1. Crea la ruta

En el dashboard del comercio abre API for Agents y agrega un endpoint nuevo. Dale un path: el último segmento de la URL pública que llamarán los agentes, por ejemplo market-data. Un comercio puede tener muchas rutas, así que nómbralas por lo que venden.

2. Apúntala a la API que ya operas

Indica la URL de la API, el endpoint HTTPS al que Payzum debe reenviar las llamadas pagadas. Es tu servicio actual, sin cambios. Payzum no mueve tu API: publica una puerta adicional, con precio, hacia ella.

3. Guarda la credencial de tu origen

Si tu API autentica a quien la llama, agrega la API key o el bearer token a la ruta. Se guarda cifrado y se inyecta cuando Payzum reenvía una llamada pagada, así que tu servicio autentica la petición igual que hoy y el agente nunca ve el secreto. Si tu endpoint hoy está abierto, este es el momento de ponerle una clave. Si no, cualquiera que conozca la URL del origen puede saltarse el muro de pago llamándola directamente.

4. Fija el precio por llamada

Indica el precio en USDC de una llamada. Puedes poner precios distintos en rutas distintas, de modo que una consulta barata y un análisis caro convivan. Fija el precio según el valor de la respuesta para quien llama y ten presente el costo fijo de cada pago: nuestro análisis sobre el precio mínimo en los pagos máquina a máquina explica por qué una ruta con precio inferior al costo de liquidarla no puede funcionar.

5. Indica la dirección de Base que recibe el dinero

Introduce la dirección de Base donde debe caer el USDC. Los pagos se liquidan en esa dirección a través de tu propia cuenta de facilitador. Payzum verifica y reenvía; nunca toma custodia, no agrupa tus ingresos ni tiene un calendario de pagos que tengas que esperar.

6. Elige cómo se liquida: primero testnet, luego mainnet

Abre los ajustes de liquidación. La opción testnet liquida en Base Sepolia a través de un facilitador público, gratis: mismo handshake, mismo cableado, sin USDC real. La opción mainnet conecta tu propia clave de Coinbase Developer Platform, de modo que el USDC real se liquida en Base y el costo por transacción y el gas se facturan a esa misma cuenta, la que recibe el dinero. Empieza en testnet.

7. Activa la ruta y copia la URL

Cambia la ruta a Live. Payzum publica la URL x402 pública, y esa cadena es toda la integración del lado del comprador. Llámala sin pagar y comprueba que recibes un 402 con tu precio, red y activo. Después haz una llamada pagada desde un cliente compatible con x402 contra testnet y confirma que tu origen devuelve su respuesta habitual.

8. Opcional: hazla descubrible

Marca el endpoint como descubrible para listarlo en el catálogo de descubrimiento. Si liquidas con el facilitador de Coinbase, esos metadatos también se publican en el x402 Bazaar. Ajusta las expectativas: los docs de x402 describen el Bazaar como una iniciativa en desarrollo temprano, «más Yahoo search que Google», con funciones y APIs que pueden cambiar (docs.x402.org, página Bazaar, consultada el 20 de octubre de 2026).

Qué revisar antes de cobrar dinero real

• El origen rechaza llamadas sin autenticar. Llama directamente a la URL del origen sin clave. Si responde 200, el muro de pago se puede saltar.
• El precio cubre el costo de un pago. El facilitador cobra por transacción on-chain después de un nivel gratuito (mira la sección de cifras más abajo) y el gas se paga en Base.
• La respuesta es la misma por las dos puertas. Compara una llamada directa con una reenviada. Deben coincidir, salvo por el paso del pago.
• Puedes apagarla. Desactiva la ruta y comprueba que los agentes reciben un fallo limpio mientras tus clientes directos no notan nada.

Quién agrega x402 así: casos de uso

El patrón es una respuesta acotada, valiosa en el momento en que se pide, vendida por alguien que prefiere no rehacer su sistema de facturación para averiguar si los agentes pagarán.

• Un proveedor de datos de cumplimiento con código cerrado. La API de screening de sanciones corre sobre una infraestructura que el equipo configura pero no parchea. Exponen una ruta a diez centavos, mantienen su clave actual en el origen y no tocan sus contratos empresariales.
• Una API de enriquecimiento con nivel gratuito que la gente rastrea. Las consultas de geolocalización e IP son respuestas de menos de un centavo. Una ruta por llamada da a los llamadores automáticos de alto volumen una forma de pagar sin registrarse, mientras los desarrolladores humanos siguen en los planes con clave.
• Un equipo pequeño con un servidor MCP o un endpoint de herramienta. Cualquier endpoint accesible por HTTP puede ir detrás de una ruta. Mira cómo monetizar un servidor MCP con x402 para la versión específica de herramientas.
• Una agencia que opera varias APIs de clientes, de Medellín a Madrid. Un comercio, varias rutas con precios distintos, cada una con su propia credencial de origen. Un cambio de precio de un cliente es una edición, no un release.

Agregar x402 con Payzum vs hacerlo tú mismo: comparativa

Las cifras que conviene conocer antes de empezar

Tres datos con fecha enmarcan la economía. Primero, el lado del facilitador: las primeras 1.000 transacciones on-chain de cada mes en el CDP Facilitator son gratis, cada transacción adicional cuesta 0,001 dólares y la verificación de pagos siempre es gratuita (docs de CDP, consultados el 20 de octubre de 2026). Segundo, el historial: la misma página dice que el facilitador ha procesado más de 100 millones de transacciones y 28 millones de dólares en volumen de pagos entre Base y Solana. Tercero, el lado comprador es joven: en la auditoría de Bitquery citada antes, el vendedor mediano en Base ganó unos 2,50 dólares al mes, así que trata la primera ruta como un experimento con un tope de esfuerzo, no como una línea de ingresos.

Del lado de Payzum, el costo del facilitador y el gas se facturan a la cuenta de facilitador que conectes, la misma que recibe el USDC. Para el precio propio de Payzum en las rutas x402, confirma las cifras vigentes en una llamada en vez de fiarte de un número en un blog. Para el panorama completo del pago por llamada, incluida la comparación con la facturación por API key, mira x402: pago por llamada de API y la página de producto de x402.

Objeciones frecuentes

«No quiero un proxy delante de mi API.»

No estás moviendo tu API. Estás agregando una segunda puerta, con precio. Tu tráfico actual nunca pasa por Payzum y apagar la ruta x402 es un interruptor, no una reversa.

«¿Qué impide que alguien llame directo a mi origen?»

La autenticación de tu propio origen, por eso importa el paso 3. La ruta x402 es el único lugar donde un agente puede comprar una llamada sin cuenta. Todo lo demás sigue necesitando la clave, igual que antes.

«Tendría que custodiar cripto.»

Recibes USDC, que sigue al dólar, en una dirección que controlas en Base. Lo que hagas después es decisión tuya, y mientras tanto Payzum no retiene nada. Es el modelo sin custodia que describimos en nuestra guía de procesadores sin custodia.

«Todavía no hay suficientes agentes pagando.»

Puede ser cierto en tu nicho hoy. Averiguarlo cuesta una entrada en el dashboard y nada de código, y el endpoint que ya operas sigue atendiendo a sus clientes actuales como antes.