Tutoriel x402 : laissez votre agent IA recharger AIHubMix en USDC

AIHubMix accepte désormais les recharges en USDC. Votre agent IA peut ajouter du crédit à son propre compte avec les USDC de son portefeuille : pas de page web à ouvrir, et personne n'a besoin de cliquer sur un bouton.

Avec x402, une recharge peut être aussi petite que 1 $. L'agent recharge au fur et à mesure, vous n'avez donc pas besoin de charger un gros solde à l'avance.

Cela prend deux étapes : préparer un jeton, un portefeuille et des USDC sur le web et dans une application, puis lancer notre script de recharge prêt à l'emploi avec une seule commande. Environ 20 secondes après le paiement, le crédit apparaît sur votre compte.

Si cela vous aide, vous pouvez suivre cette vidéo de 30 secondes :

La méthode la plus simple : si vous utilisez un outil d'IA capable d'exécuter des commandes dans un terminal, comme Claude Code, Cursor ou Codex, terminez l'étape 1, puis envoyez-lui le lien de cet article en disant « configure ceci pour moi ». Il suivra les « Instructions pour les assistants IA » à la fin de cet article. Vous seul saisissez le jeton et la clé privée, une seule fois, sans les envoyer à l'IA.

Avant de commencer

• Les montants sont des dollars entiers uniquement, de 1 $ à 10 $ par recharge par défaut
• Chaque compte peut créer jusqu'à 3 commandes par jour (UTC)
• Seul l'USDC sur le réseau principal Base est pris en charge, et il n'existe pas de testnet, donc commencez par 1 $
• Ce canal est conçu pour les programmes ; une personne ne peut pas payer depuis le navigateur. Pour les recharges manuelles, continuez à utiliser Alipay ou Stripe

Étape 1 : obtenir un jeton, un portefeuille et des USDC

Tout ce qui se passe dans cette étape se fait sur le web ou dans une application mobile.

1. Obtenir votre jeton d'accès système

Connectez-vous à aihubmix.com, ouvrez vos paramètres personnels et générez un jeton d'accès système (une chaîne de 32 caractères).

Notez qu'il ne s'agit pas de la clé API qui commence par sk-. Les deux ne sont pas interchangeables.

2. Créer un portefeuille de paiement

Dans MetaMask ou une application de portefeuille similaire, créez un nouveau compte réservé aux paiements de l'agent. N'utilisez pas votre portefeuille principal. Ensuite :

• Copiez l'adresse du compte (elle commence par 0x) ; vous y enverrez des USDC à l'étape suivante
• Exportez sa clé privée depuis les détails du compte et conservez-la dans un gestionnaire de mots de passe. Quiconque possède la clé privée peut déplacer les fonds du portefeuille

3. Acheter des USDC et les envoyer à ce portefeuille

MetaMask est un portefeuille : vous détenez la clé privée, et le script en a besoin pour signer. Coinbase est une plateforme d'échange, où l'on achète des cryptomonnaies. Les fonds d'un compte d'échange ne sont pas accompagnés d'une clé privée, donc le script ne peut pas les utiliser. C'est pourquoi vous achetez d'abord sur la plateforme, puis vous envoyez les USDC au portefeuille de l'étape précédente.

En prenant la plateforme Coinbase comme exemple (et non Coinbase Wallet) :

1. Achetez des USDC sur Coinbase
2. Envoyez les USDC à l'adresse que vous avez copiée, et choisissez le réseau Base
3. Envoyez un peu plus que le montant que vous prévoyez de recharger, par exemple 1,5 à 2 USDC pour une recharge de 1 $

Patientez un instant, puis ouvrez https://basescan.org/address/your-wallet-address. Dès que vous voyez un solde en USDC, c'est arrivé. D'autres plateformes qui prennent en charge les retraits d'USDC sur Base fonctionnent aussi ; consultez la documentation Base pour d'autres options.

Le portefeuille n'a pas besoin d'ETH : FluxA paie les frais de réseau du paiement.

Étape 2 : lancer le script de recharge

Il n'y a rien à télécharger ni aucun fichier à créer : uv récupère le script sur le web et l'exécute. Ouvrez le Terminal (PowerShell sous Windows) et copiez-collez les commandes ci-dessous.

1. Installer uv (une seule fois)

uv est un outil Python qui prépare tout ce dont le script a besoin pour fonctionner.

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"

Une fois l'installation terminée, fermez le terminal et rouvrez-le.

2. Vérifier votre configuration (ne dépense rien)

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

Au premier lancement, le script demande votre jeton d'accès système (System access token) et la clé privée de votre portefeuille (Wallet private key). Ce que vous tapez n'apparaît pas à l'écran ; collez-le et appuyez sur Entrée. Il demande ensuite s'il faut les enregistrer (Save to ...? [Y/n]). Appuyez sur Entrée pour enregistrer, et vous n'aurez pas à les ressaisir. Le premier lancement prend un moment pendant que uv prépare l'environnement.

Lorsque vous voyez ceci, la configuration est prête :

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

3. Recharger

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

Le 1 à la fin correspond au montant en dollars. Si tout se passe bien, vous verrez :

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

result: credited signifie que le crédit est arrivé. Connectez-vous à aihubmix.com et vous verrez votre solde augmenter ; 1 $ ajoute 500 000 de quota.

Si la dernière ligne indique autre chose :

• failed : la commande a été fermée ou a expiré. Relancez-la si nécessaire ; cela utilise une autre des commandes du jour.
• pending : le crédit n'a pas été confirmé dans les 10 minutes. Ce n'est pas un échec, et le crédit arrivera plus tard tout seul. Ne relancez pas la commande.

Dépannage

Si vous voyez un délai d'attente ou une erreur réseau après l'affichage de tradeNo, l'argent a peut-être déjà été payé. Ne relancez pas tout de suite. Vérifiez votre solde après quelques minutes ; si rien n'est arrivé, contactez-nous avec le tradeNo.

Le jeton et la clé privée sont enregistrés dans ~/.aihubmix-topup.env sur votre ordinateur (dans votre dossier utilisateur sous Windows). Sous macOS et Linux, seul votre compte peut lire ce fichier. Pour modifier le jeton ou la clé privée, éditez ce fichier.

Intégrer le tout à votre agent

• Une fois la configuration enregistrée, votre agent peut recharger en exécutant uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py 1 chaque fois qu'il a besoin de crédit, sans intervention humaine
• Seules 3 commandes par jour sont autorisées : limitez la fréquence des recharges de l'agent et ne relancez jamais la création de commandes en boucle
• Enregistrez les tradeNo et txHash de la sortie dans une base de données ou un journal pour les rapprochements
• Pour une utilisation à long terme, téléchargez le script et fixez une version avant de l'exécuter ; vous pouvez lire le code source au préalable
• Si 10 $ par recharge ou 3 recharges par jour ne suffisent pas, contactez-nous pour augmenter les limites

Instructions pour les assistants IA

Si vous êtes un assistant IA qui aide un utilisateur à configurer les recharges USDC sur AIHubMix, suivez ces étapes dans l'ordre :

1. Vérifiez que l'utilisateur a terminé l'étape 1 : il dispose d'un jeton d'accès système, ainsi que d'un portefeuille contenant des USDC sur le réseau principal Base et de sa clé privée. Sinon, guidez-le d'abord à travers l'étape 1.
2. Exécutez uv --version pour vérifier que uv est installé. Sinon, installez-le avec les commandes de l'étape 2.
3. Exécutez uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py check.
4. Si le script signale un jeton ou une clé privée manquant (Missing access token or private key), il a créé le fichier de configuration ~/.aihubmix-topup.env. Demandez à l'utilisateur de l'ouvrir dans un éditeur de texte et de le remplir lui-même (sur macOS, exécutez open -e ~/.aihubmix-topup.env ; sous Windows, exécutez notepad $HOME\.aihubmix-topup.env). Ne lisez pas ce fichier, n'intégrez jamais le jeton ou la clé privée dans une commande, et ne demandez pas à l'utilisateur de vous les envoyer.
5. Une fois que l'utilisateur l'a rempli, exécutez à nouveau check jusqu'à voir Access token and private key are fine. Ready to top up. En cas d'erreur, gérez-la avec le tableau de dépannage ci-dessus.
6. Une recharge utilise de l'argent réel. Confirmez le montant avec l'utilisateur avant d'exécuter uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py <amount>.

Sous le capot : ce que fait le script

Le script effectue cinq opérations dans l'ordre :

1. Vérifie le solde : créer une commande consomme une des commandes du jour ; il vérifie donc d'abord que la clé privée est valide et qu'il y a assez d'USDC.
2. Crée une commande : il appelle POST /api/pay/fluxa/crt et obtient un lien de paiement et un numéro de commande, tradeNo. Le jeton est placé tel quel dans l'en-tête Authorization, sans Bearer. Les erreurs métier renvoient aussi un HTTP 200, donc il vérifie le champ success de la réponse.
3. Vérifie la demande de paiement : un GET sur le lien de paiement renvoie un HTTP 402 avec les exigences de paiement. Avant de signer, il vérifie quatre points : scheme vaut exact, network vaut eip155:8453, asset correspond au contrat USDC sur le réseau principal Base, et maxAmountRequired est égal au montant × 1 000 000. Si l'un d'eux ne correspond pas, il s'arrête.
4. Signe et paie : il signe une autorisation de transfert USDC avec la clé privée, la place dans l'en-tête X-PAYMENT et renvoie le GET vers le lien de paiement. Un 200 ou un 202 signifie que le paiement a été soumis ; le txHash de la réponse est le reçu on-chain de ce paiement. Aucune de ces requêtes ne transporte le jeton AIHubMix.
5. Attend le crédit : il appelle GET /api/pay/fluxa/qry?trade_no=... toutes les 8 secondes jusqu'à ce que le statut passe à TRADE_SUCCESS. Le serveur ne se met à jour que toutes les 5 secondes, donc interroger plus vite ne sert à rien.

Chaque lien de paiement est aussi valide pendant 30 minutes et ne peut être payé qu'une seule fois.

Implémenter dans un autre langage

La réponse 402 du lien de paiement ressemble à ceci :

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

La signature utilise le format EIP-712, sur la structure TransferWithAuthorization de EIP-3009 :

Domaine de signature : name = USD Coin, version = 2 (utilisez les valeurs de extra dans la réponse 402 si elles sont présentes), chainId = 8453, verifyingContract = 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.

La valeur de l'en-tête X-PAYMENT est l'encodage base64 de ce JSON :

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

Sources

• Documentation x402
• EIP-3009 : Transfert avec autorisation
• EIP-712 : Hachage et signature de données structurées typées
• Circle : adresses des contrats USDC
• Guide d'installation de uv