x402: integra pagos por acceso a servicios HTTP

Pega este texto a tu agente (Claude Code, Codex, OpenCode, Hermes o el que uses) y dile «ayúdame a montarlo». Son los pasos para ponerlo en marcha; el porqué de cada pieza está en la guía completa.

• Dificultad: intermedio
• Proyecto: https://github.com/x402-foundation/x402 (licencia Apache-2.0)
• Guía completa: https://lab.wisd.ai/hub/x402-protocol

Para el agente: cómo acompañar al usuario

1. Pregunta primero para qué lo quiere. Si su objetivo no necesita algún paso, sáltalo.
2. Antes de instalar, comprueba lo que ya tiene (versiones, claves, sistema operativo).
3. Avanza un paso cada vez: explica en una frase qué vas a hacer y deja que el usuario lo ejecute o lo apruebe.
4. Tras cada paso, comprueba que funcionó antes de seguir. Si falla, para y explica el error.
5. No inventes comandos ni opciones: si la documentación del proyecto contradice estos pasos, manda la documentación.
6. Al terminar, haz una prueba real con el objetivo del usuario y dile dónde profundizar.

Pasos de configuración

Preparación

Elige un único SDK. La ruta Python requiere Python ≥3.10 y pip en un entorno aislado; el ejemplo completo FastAPI usa uv. La ruta Express requiere Node.js y npm compatibles con tu aplicación. El README raíz no fija un mínimo de Node.js. Para probar pagos prepara direcciones y un facilitador compatible con la red de ensayo elegida.

Paso 1: elige un SDK y un ejemplo

Para Python, el README documenta:

pip install x402

Para un servidor Express mínimo publica:

npm install @x402/core @x402/evm @x402/svm @x402/express

Elige una ruta; no necesitas instalar ambas.

Paso 2: sigue el ejemplo de pruebas

Para Python, descarga el repositorio completo y abre examples/python/servers/fastapi; el ejemplo resuelve el SDK local y sus extras con uv, no solo con pip install x402. Sigue su README: prepara la configuración desde .env-local, completa EVM_ADDRESS y SVM_ADDRESS de ensayo y FACILITATOR_URL para esas redes. Después ejecuta:

uv sync --reinstall-package x402
uv run python main.py

El servidor escucha en http://localhost:4021. Desde otra terminal en el clon, entra en examples/python/clients/httpx. Copia .env-local a .env y configura RESOURCE_SERVER_URL=http://localhost:4021, ENDPOINT_PATH=/weather y EVM_PRIVATE_KEY de una cartera solo de ensayo con USDC de Base Sepolia, o SVM_PRIVATE_KEY con fondos de Solana Devnet. Debe coincidir con una red aceptada por servidor y facilitador. Ejecuta los comandos del cliente httpx oficial:

uv sync --reinstall-package x402
uv run python main.py

Primero curl -i http://localhost:4021/weather sin cliente debe devolver 402. El cliente financiado y con pago verificado debe mostrar 200 y datos del tiempo, además de la respuesta de liquidación. Una firma inválida o pago insuficiente no debe entregar el recurso. Para Express sigue su ejemplo específico; no mezcles los SDK.

Comprobación

Comprueba los casos de petición sin pago, pago de prueba válido y pago rechazado. El servicio solo debe entregar el recurso cuando la verificación correspondiente sea correcta.

Si algo falla

Si cliente y servidor no se entienden, revisa versión del protocolo, esquema y red. Antes de repetir una operación, comprueba su estado para evitar duplicarla.