Cómo implementar x402 en su sitio web o API para pagos.
Guía paso a paso para agregar middleware de pago x402 a su sitio web o API. Cubre el formato de respuesta 402, validación de pagos, integración con llms.txt.
Updated April 12, 2026
La implementación de x402 hace que su sitio web o API sea instantáneamente monetizable por agentes. Cuando un agente de IA solicita contenido o computación, su servidor devuelve HTTP 402 con condiciones de pago estructuradas. El agente paga con USDC. Se concede el acceso. Todo en un viaje de ida y vuelta HTTP sin estado.
La implementación en cinco pasos#
Paso 1: agregar middleware que verifique el pago#
Inserte middleware antes de sus puntos finales protegidos. Comprueba el encabezado X-PAYMENT en las solicitudes entrantes. Si el encabezado está presente y es válido, la solicitud continúa. Si falta o es insuficiente, el middleware devuelve una respuesta 402.
Este middleware se encuentra entre su servidor web y su lógica empresarial. No cambia el funcionamiento interno de sus puntos finales.
Paso 2: Estructurar la respuesta 402#
Cuando falta el pago, devuelve un código de estado 402 con un cuerpo JSON que contiene: precio (la cantidad requerida), moneda (USDC), cadena (la cadena de bloques para pagar, Base es la predeterminada), beneficiario (la dirección de su billetera), descripción (a qué otorga acceso el pago) y vencimiento (por cuánto tiempo siguen siendo válidas las condiciones de pago).
La respuesta estructurada es lo que permite a los agentes realizar pagos automáticos. Un 402 simple sin este cuerpo JSON no le da al agente nada con qué trabajar.
Paso 3: Validar los pagos recibidos#
Cuando un agente vuelva a intentarlo con un encabezado X-PAYMENT, valide el pago en cadena. Utilice el SDK de la plataforma para desarrolladores de Coinbase o una llamada RPC directa para verificar que el pago se realizó a la dirección correcta por el monto correcto en la cadena correcta.
La validación debe completarse dentro del ciclo de vida de la solicitud. No haga que el agente espere un flujo de confirmación por separado.
Paso 4: otorgar acceso y registrar la transacción#
Una vez validado el pago, procese la solicitud original normalmente y devuelva la respuesta. Registre la transacción: identificador del agente, monto pagado, punto final al que se accedió, respuesta devuelta, marca de tiempo.
Estos registros alimentan sus bucles de retroalimentación y análisis de ingresos.
Paso 5: publique sus puntos finales x402 en archivos de descubrimiento#
Agregue sus terminales pagos a su llms.txt con información de precios. Inclúyalos en su lista de capacidades de agent-card.json con el requisito de pago anotado. Si tiene un servidor MCP, agregue un campo de pago_requerido a las descripciones de las herramientas relevantes.
Esto garantiza que los agentes descubran no sólo lo que su sitio puede hacer, sino también cuánto cuesta utilizar cada capacidad.
Combinando x402 con pagos con tarjeta#
Los pagos con tarjeta de agente de Nevermined (lanzados el 9 de abril de 2026) permiten a los agentes pagar con autoridad delegada de Visa o Mastercard mientras que los comerciantes reciben la liquidación a través de procesadores de pago estándar como Stripe o Adyen.Este enfoque híbrido le permite aceptar micropagos criptográficos (para agentes con billeteras) y pagos con tarjeta tradicional (para agentes con autoridad delegada sobre tarjetas) a través del mismo punto final.
Comparación: monetización de API tradicional frente a x402#
| Método | Tiempo de configuración | Fricción del agente | Modelo de ingresos | Pago mínimo viable |
| — |
| — |
| — |
| — |
| Claves API con suscripciones |
| x402 |
Errores comunes#
Devolviendo un 402 simple sin el cuerpo JSON estructurado. Los agentes no pueden realizar pagos automáticos si no reciben condiciones de pago estructuradas. Incluya siempre la especificación JSON completa.
No publicar puntos finales x402 en archivos de descubrimiento. Si los agentes no saben que un terminal requiere pago antes de llamarlo, la respuesta 402 se siente como un error en lugar de una oportunidad de transacción.
Fijar precios demasiado altos para los casos de uso de micropagos. El poder de x402 permite pagos que antes eran demasiado pequeños para procesar. Una consulta de datos que cuesta 5 dólares recibirá menos llamadas de agentes que una que cuesta 0,01 dólares y aumenta en volumen.
La descripción general de x402 explica el contexto estratégico. La lista de verificación de aplicaciones web listas para agentes cubre la configuración más amplia para desarrolladores.
Preguntas frecuentes#
¿Cuánto tiempo lleva la implementación de x402? El middleware básico para un único punto final tarda de 1 a 2 horas. Agregar la validación de pago y el registro agrega otras 2 a 4 horas. La integración completa con llms.txt y Agent Cards lleva un día.
¿Qué lenguajes de programación tienen middleware x402 disponible? Node.js, Python, Go y Cloudflare Workers tienen middleware prediseñado. El protocolo es lo suficientemente simple como para implementarlo en cualquier lenguaje que pueda devolver respuestas HTTP y realizar llamadas RPC.
¿Necesito una billetera criptográfica? Sí, para recibir pagos. Una simple billetera USDC en Base es suficiente. Puede convertir USDC recibido a fiat a través de cualquier intercambio o procesador de pagos que admita la liquidación de monedas estables.
¿Puedo establecer precios diferentes para diferentes puntos finales? Sí. Cada punto final puede devolver su propia respuesta 402 con precios diferentes. Una simple consulta de datos puede costar 0,001 dólares, mientras que un cálculo complejo cuesta 1 dólar.
¿Qué pasa si un agente no es compatible con x402? El agente recibe una respuesta 402 que no puede procesar y continúa. Puede ofrecer métodos de acceso alternativos (claves API, suscripciones) para clientes que no sean x402 y al mismo tiempo mantener x402 como la ruta de pago principal del agente.
—Este artículo analiza los protocolos de pago y la infraestructura de criptomonedas únicamente con fines educativos e informativos. No constituye asesoramiento financiero. Consulte nuestro Aviso legal para conocer los términos completos.