Tutorial de x402: deja que tu agente de IA recargue AIHubMix con USDC

AIHubMix ahora acepta recargas con USDC. Tu agente de IA puede añadir crédito a su propia cuenta con el USDC de su billetera: no hay que abrir ninguna página web ni que alguien haga clic en un botón.

Con x402, una recarga puede ser de tan solo $1. El agente recarga sobre la marcha, así que no tienes que cargar un saldo grande por adelantado.

Son dos pasos: tener listos un token, una billetera y algo de USDC en la web y en una aplicación, y luego ejecutar nuestro script de recarga listo para usar con un solo comando. Unos 20 segundos después del pago, el crédito aparece en tu cuenta.

Si te resulta útil, puedes seguir este vídeo de 30 segundos:

La forma más fácil: si usas una herramienta de IA que puede ejecutar comandos de terminal, como Claude Code, Cursor o Codex, completa el paso 1 y luego envíale el enlace a esta entrada y di "configúralo por mí". Seguirá las "Instrucciones para asistentes de IA" al final de esta entrada. Tú solo introduces el token y la clave privada, una vez, sin enviárselos a la IA.

Antes de empezar

• Los importes son solo dólares enteros, de $1 a $10 por recarga de forma predeterminada
• Cada cuenta puede crear hasta 3 pedidos al día (UTC)
• Solo se admite USDC en la red principal de Base, y no hay testnet, así que empieza con $1
• Este canal está diseñado para programas; una persona no puede pagar desde el navegador. Para recargas manuales, sigue usando Alipay o Stripe

Paso 1: obtén un token, una billetera y USDC

Todo lo de este paso se hace en la web o en una aplicación del teléfono.

1. Obtén tu token de acceso al sistema

Inicia sesión en aihubmix.com, abre tu configuración personal y genera un token de acceso al sistema (una cadena de 32 caracteres).

Ten en cuenta que no es la clave API que empieza por sk-. No son intercambiables.

2. Crea una billetera para pagos

En MetaMask o en una aplicación de billetera similar, crea una cuenta nueva solo para los pagos del agente. No uses tu billetera principal. Después:

• Copia la dirección de la cuenta (empieza por 0x); le enviarás USDC en el siguiente paso
• Exporta su clave privada desde los detalles de la cuenta y guárdala en un gestor de contraseñas. Cualquiera que tenga la clave privada puede mover el dinero de la billetera

3. Compra USDC y envíalo a esta billetera

MetaMask es una billetera: tú tienes la clave privada, y el script la necesita para firmar. Coinbase es un exchange, donde compras criptomonedas. Los fondos de una cuenta de exchange no vienen con una clave privada, así que el script no puede usarlos. Por eso compras primero en el exchange y luego envías el USDC a la billetera del paso anterior.

Tomando como ejemplo el exchange Coinbase (no Coinbase Wallet):

1. Compra USDC en Coinbase
2. Envía el USDC a la dirección que copiaste y elige la red Base
3. Envía un poco más de lo que piensas recargar, por ejemplo entre 1.5 y 2 USDC para una recarga de $1

Espera un momento y luego abre https://basescan.org/address/your-wallet-address. Cuando veas un saldo de USDC, significa que ha llegado. Otros exchanges que admiten retiros de USDC en Base también funcionan; consulta la documentación de Base para ver más opciones.

La billetera no necesita ETH: FluxA paga la comisión de red del pago.

Paso 2: ejecuta el script de recarga

No hay nada que descargar ni archivo que crear: uv obtiene el script de la web y lo ejecuta. Abre la Terminal (PowerShell en Windows) y copia y pega los comandos siguientes.

1. Instala uv (una sola vez)

uv es una herramienta de Python que prepara todo lo que necesita el script para ejecutarse.

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Cuando termine, cierra la terminal y vuelve a abrirla.

2. Comprueba tu configuración (no gasta nada)

uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py check

En la primera ejecución, el script pide tu token de acceso al sistema (System access token) y la clave privada de la billetera (Wallet private key). Lo que escribes no se muestra en pantalla; pégalo y pulsa Enter. Luego pregunta si quieres guardarlos (Save to ...? [Y/n]). Pulsa Enter para guardarlos y no tendrás que volver a escribirlos. La primera ejecución tarda un momento mientras uv prepara todo.

Cuando veas esto, la configuración está lista:

Wallet: 0x... (USDC balance 2.0)
Access token and private key are fine. Ready to top up.

3. Recarga

uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py 1

El 1 del final es el importe en dólares. Si todo va bien, verás:

Wallet: 0x... (USDC balance 2.0)
tradeNo: pl_XXXXXXXX
txHash: 0x...
result: credited

result: credited significa que el crédito ha llegado. Inicia sesión en aihubmix.com y verás que tu saldo aumenta; $1 añade 500,000 de cuota.

Si la última línea muestra otra cosa:

• failed: el pedido se cerró o expiró. Vuelve a ejecutarlo si lo necesitas; eso consume otro de los pedidos de hoy.
• pending: el crédito no se confirmó en 10 minutos. No es un fallo, y el crédito llegará más tarde por sí solo. No lo vuelvas a ejecutar.

Solución de problemas

Si ves un error de tiempo de espera o de red después de que se imprima tradeNo, es posible que el dinero ya se haya pagado. No lo vuelvas a ejecutar de inmediato. Revisa tu saldo después de unos minutos; si no llegó nada, contacta con nosotros con el tradeNo.

El token y la clave privada se guardan en ~/.aihubmix-topup.env en tu equipo (en la carpeta de tu usuario en Windows). En macOS y Linux, solo tu cuenta puede leerlo. Para cambiar el token o la clave privada, edita este archivo.

Integración con tu agente

• Una vez guardada la configuración, tu agente puede recargar ejecutando uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py 1 cada vez que necesite crédito, sin que nadie esté presente
• Solo se permiten 3 pedidos al día, así que limita con qué frecuencia recarga el agente y nunca reintentes la creación de pedidos en un bucle
• Guarda el tradeNo y el txHash de la salida en una base de datos o en un registro para la conciliación
• Para uso a largo plazo, descarga el script y fija una versión antes de ejecutarlo; puedes leer el código fuente primero
• Si $10 por recarga o 3 al día no bastan, contacta con nosotros para aumentar los límites

Instrucciones para asistentes de IA

Si eres un asistente de IA que ayuda a un usuario a configurar las recargas USDC de AIHubMix, sigue estos pasos en orden:

1. Confirma que el usuario ha terminado el paso 1: tiene un token de acceso al sistema, además de una billetera con USDC en la red principal de Base y su clave privada. Si no es así, guíalo primero por el paso 1.
2. Ejecuta uv --version para comprobar que uv está instalado. Si no lo está, instálalo con los comandos del paso 2.
3. Ejecuta uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py check.
4. Si informa de un token o una clave privada que falta (Missing access token or private key), el script ha creado el archivo de configuración ~/.aihubmix-topup.env. Pide al usuario que lo abra en un editor de texto y lo complete él mismo (en macOS, ejecuta open -e ~/.aihubmix-topup.env; en Windows, ejecuta notepad $HOME\.aihubmix-topup.env). No leas este archivo, no pongas el token ni la clave privada en ningún comando y no pidas al usuario que te los envíe.
5. Cuando el usuario lo haya completado, ejecuta check de nuevo hasta que veas Access token and private key are fine. Ready to top up. Si hay un error, resuélvelo con la tabla de solución de problemas de arriba.
6. Una recarga gasta dinero real. Confirma el importe con el usuario antes de ejecutar uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py <amount>.

Por dentro: qué hace el script

El script hace cinco cosas en orden:

1. Comprueba el saldo: crear un pedido consume uno de los pedidos de hoy, así que primero se asegura de que la clave privada es válida y de que hay USDC suficiente.
2. Crea un pedido: llama a POST /api/pay/fluxa/crt y obtiene un enlace de pago y un número de pedido, tradeNo. El token va en el encabezado Authorization tal cual, sin Bearer. Los errores de negocio también llegan como HTTP 200, así que comprueba el campo success de la respuesta.
3. Revisa la solicitud de pago: una petición GET al enlace de pago devuelve HTTP 402 con los requisitos de pago. Antes de firmar, comprueba cuatro cosas: scheme es exact, network es eip155:8453, asset es el contrato USDC en la red principal de Base y maxAmountRequired es igual al importe × 1,000,000. Si alguna no coincide, se detiene.
4. Firma y paga: firma una autorización de transferencia USDC con la clave privada, la coloca en el encabezado X-PAYMENT y vuelve a enviar el GET al enlace de pago. Un 200 o un 202 significa que el pago se envió; el txHash de la respuesta es el comprobante en cadena de este pago. Ninguna de las dos solicitudes lleva el token de AIHubMix.
5. Espera el crédito: llama a GET /api/pay/fluxa/qry?trade_no=... cada 8 segundos hasta que el estado sea TRADE_SUCCESS. El servidor solo se actualiza cada 5 segundos, así que consultar más rápido no sirve de nada.

Además, cada enlace de pago es válido durante 30 minutos y solo puede pagarse una vez.

Implementación en otro lenguaje

La respuesta 402 del enlace de pago tiene este aspecto:

{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "maxAmountRequired": "1000000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x....",
    "maxTimeoutSeconds": 600,
    "extra": {"name": "USD Coin", "version": "2"}
  }]
}

La firma usa el formato EIP-712, sobre la estructura TransferWithAuthorization de EIP-3009:

Dominio de firma: name = USD Coin, version = 2 (usa los valores de extra en la respuesta 402 si están presentes), chainId = 8453, verifyingContract = 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.

El valor del encabezado X-PAYMENT es la codificación base64 de este JSON:

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "eip155:8453",
  "payload": {
    "signature": "0x...",
    "authorization": {
      "from": "0x...", "to": "0x...", "value": "1000000",
      "validAfter": "...", "validBefore": "...", "nonce": "0x..."
    }
  }
}

Fuentes

• Documentación de x402
• EIP-3009: Transfer With Authorization
• EIP-712: Typed structured data hashing and signing
• Circle: direcciones de contratos USDC
• Guía de instalación de uv