x402-tutorial: laat je AI-agent AIHubMix opwaarderen met USDC

AIHubMix accepteert nu opwaarderingen met USDC. Je AI-agent kan met de USDC in zijn wallet zelf tegoed toevoegen aan zijn account: je hoeft geen webpagina te openen en niemand hoeft op een knop te klikken.

Met x402 kan een opwaardering al met $1 worden gedaan. De agent waardeert op wanneer dat nodig is, zodat je niet vooraf een groot saldo hoeft te storten.

Het zijn twee stappen: zorg op het web en in een app voor een token, een wallet en wat USDC, en voer daarna ons kant-en-klare opwaardeerscript uit met één commando. Ongeveer 20 seconden na de betaling verschijnt het tegoed op je account.

Als het helpt, kun je deze video van 30 seconden volgen:

De makkelijkste manier: als je een AI-tool gebruikt die terminalcommando's kan uitvoeren, zoals Claude Code, Cursor of Codex, rond dan stap 1 af en stuur de link naar deze post met de zin "zet dit voor me op". Die volgt dan de "Instructies voor AI-assistenten" aan het eind van deze post. Alleen het token en de private key vul je zelf één keer in, zonder ze naar de AI te sturen.

Voordat je begint

• Bedragen zijn alleen hele dollars, standaard $1 tot $10 per opwaardering
• Elk account kan maximaal 3 orders per dag aanmaken (UTC)
• Alleen USDC op Base mainnet wordt ondersteund, en er is geen testnet, begin dus met $1
• Dit kanaal is gebouwd voor programma's; een persoon kan niet in de browser betalen. Voor handmatige opwaarderingen gebruik je nog steeds Alipay of Stripe

Stap 1: Een token, een wallet en USDC regelen

Alles in deze stap gebeurt op het web of in een app op je telefoon.

1. Haal je systeemtoegangstoken op

Log in op aihubmix.com, open je persoonlijke instellingen en genereer een systeemtoegangstoken (een tekenreeks van 32 tekens).

Let op: dit is niet de API-sleutel die begint met sk-. De twee zijn niet inwisselbaar.

2. Maak een betaalwallet aan

Maak in MetaMask of een vergelijkbare wallet-app een nieuw account aan dat alleen voor de betalingen van de agent is. Gebruik je hoofdwallet niet. Daarna:

• Kopieer het adres van het account (het begint met 0x); daar stuur je in de volgende stap USDC naartoe
• Exporteer de private key uit de accountgegevens en bewaar die in een wachtwoordmanager. Wie de private key heeft, kan het geld in de wallet verplaatsen

3. Koop USDC en stuur het naar deze wallet

MetaMask is een wallet: jij beheert de private key en het script heeft die nodig om te ondertekenen. Coinbase is een exchange, waar je crypto koopt. Geld op een exchangeaccount komt niet met een private key, dus het script kan dat niet gebruiken. Daarom koop je eerst op de exchange en stuur je daarna de USDC naar de wallet uit de vorige stap.

Als voorbeeld de Coinbase-exchange (niet Coinbase Wallet):

1. Koop USDC op Coinbase
2. Stuur de USDC naar het adres dat je hebt gekopieerd en kies het Base-netwerk
3. Stuur iets meer dan je wilt opwaarderen, bijvoorbeeld 1,5 tot 2 USDC voor een opwaardering van $1

Wacht even en open daarna https://basescan.org/address/your-wallet-address. Zodra je een USDC-saldo ziet, is het aangekomen. Andere exchanges die USDC-opnames op Base ondersteunen, werken ook; zie de Base-documentatie voor meer opties.

De wallet heeft geen ETH nodig: FluxA betaalt de netwerkkosten voor de betaling.

Stap 2: Voer het opwaardeerscript uit

Je hoeft niets te downloaden en geen bestand aan te maken: uv haalt het script van het web en voert het uit. Open Terminal (PowerShell op Windows) en kopieer en plak de onderstaande commando's.

1. Installeer uv (eenmalig)

uv is een Python-tool die alles klaarzet wat het script nodig heeft om te draaien.

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"

Als dat klaar is, sluit je de terminal en open je hem opnieuw.

2. Controleer je installatie (kost niets)

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

Bij de eerste keer vraagt het script om je systeemtoegangstoken (System access token) en de private key van je wallet (Wallet private key). Wat je typt, wordt niet op het scherm getoond; plak het en druk op Enter. Daarna vraagt het of je ze wilt opslaan (Save to ...? [Y/n]). Druk op Enter om op te slaan, dan hoef je ze niet opnieuw in te typen. De eerste keer duurt even, omdat uv alles klaarzet.

Als je dit ziet, is je installatie klaar:

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

3. Waardeer op

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

De 1 aan het eind is het bedrag in dollars. Als alles goed gaat, zie je:

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

result: credited betekent dat het tegoed is aangekomen. Log in op aihubmix.com en je ziet je saldo omhoog gaan; $1 voegt 500.000 quota toe.

Als de laatste regel iets anders zegt:

• failed: de order is gesloten of verlopen. Voer het opnieuw uit als je dat nodig hebt; dat gebruikt een andere van de orders van vandaag.
• pending: het tegoed is niet binnen 10 minuten bevestigd. Dit is geen fout, en het tegoed komt later vanzelf aan. Voer het niet opnieuw uit.

Problemen oplossen

Als je een time-out- of netwerkfout ziet nadat tradeNo is afgedrukt, is het geld mogelijk al betaald. Voer het niet meteen opnieuw uit. Controleer je saldo na een paar minuten; is er niets aangekomen, neem dan contact met ons op en geef de tradeNo door.

Het token en de private key worden opgeslagen in ~/.aihubmix-topup.env op je computer (in je gebruikersmap op Windows). Op macOS en Linux kan alleen je eigen account dit bestand lezen. Wil je het token of de private key wijzigen, bewerk dan dit bestand.

Je agent ermee verbinden

• Zodra de installatie is opgeslagen, kan je agent zonder toezicht opwaarderen door uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py 1 uit te voeren wanneer het tegoed nodig heeft
• Er zijn maar 3 orders per dag toegestaan, dus beperk hoe vaak de agent opwaardeert en probeer het aanmaken van orders nooit in een lus opnieuw
• Bewaar de tradeNo en txHash uit de uitvoer in een database of logboek voor afstemming
• Download voor langdurig gebruik het script en leg een versie vast voordat je het uitvoert; je kunt de broncode vooraf lezen
• Als $10 per opwaardering of 3 per dag niet genoeg is, neem dan contact met ons op om de limieten te verhogen

Instructies voor AI-assistenten

Als je een AI-assistent bent die een gebruiker helpt met het instellen van USDC-opwaarderingen bij AIHubMix, volg dan deze stappen in volgorde:

1. Controleer of de gebruiker stap 1 heeft afgerond: hij heeft een systeemtoegangstoken, plus een wallet met Base mainnet-USDC en de bijbehorende private key. Zo niet, begeleid hem dan eerst door stap 1.
2. Voer uv --version uit om te controleren of uv is geïnstalleerd. Is dat niet het geval, installeer het dan met de commando's uit stap 2.
3. Voer uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py check uit.
4. Meldt het een ontbrekend token of ontbrekende private key (Missing access token or private key), dan heeft het script het configuratiebestand ~/.aihubmix-topup.env aangemaakt. Vraag de gebruiker om het in een teksteditor te openen en het zelf in te vullen (op macOS voer je open -e ~/.aihubmix-topup.env uit; op Windows voer je notepad $HOME\.aihubmix-topup.env uit). Lees dit bestand niet, zet het token of de private key nooit in een commando en vraag de gebruiker niet om ze aan jou te sturen.
5. Zodra de gebruiker het heeft ingevuld, voer je check opnieuw uit totdat je Access token and private key are fine. Ready to top up. ziet. Bij een fout los je die op met de tabel Problemen oplossen hierboven.
6. Een opwaardering kost echt geld. Bevestig het bedrag met de gebruiker voordat je uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py <amount> uitvoert.

Achter de schermen: wat het script doet

Het script doet vijf dingen in deze volgorde:

1. Controleert het saldo: het aanmaken van een order gebruikt een van de orders van vandaag, dus eerst controleert het of de private key geldig is en of er genoeg USDC is.
2. Maakt een order aan: het roept POST /api/pay/fluxa/crt aan en krijgt een betaallink en een ordernummer, tradeNo. Het token gaat ongewijzigd in de Authorization-header, zonder Bearer. Ook zakelijke fouten komen terug als HTTP 200, dus het controleert het veld success in het antwoord.
3. Controleert het betalingsverzoek: een GET op de betaallink geeft HTTP 402 terug met de betalingsvereisten. Voordat het ondertekent, controleert het vier dingen: scheme is exact, network is eip155:8453, asset is het USDC-contract op Base mainnet, en maxAmountRequired is gelijk aan het bedrag × 1.000.000. Klopt een van die niet, dan stopt het.
4. Ondertekent en betaalt: het ondertekent een USDC-overdrachtsautorisatie met de private key, zet die in de X-PAYMENT-header en stuurt de GET opnieuw naar de betaallink. Een 200 of 202 betekent dat de betaling is ingediend; de txHash in het antwoord is de on-chain bewijsstuk voor deze betaling. Geen van beide verzoeken bevat het AIHubMix-token.
5. Wacht op het tegoed: het roept elke 8 seconden GET /api/pay/fluxa/qry?trade_no=... aan totdat de status TRADE_SUCCESS wordt. De server vernieuwt zijn gegevens maar elke 5 seconden, dus sneller pollen helpt niet.

Elke betaallink is ook 30 minuten geldig en kan maar één keer worden betaald.

Implementeren in een andere taal

De 402-respons van de betaallink ziet er zo uit:

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

De handtekening gebruikt het EIP-712-formaat, over de TransferWithAuthorization-struct uit EIP-3009:

Ondertekeningsdomein: name = USD Coin, version = 2 (gebruik de waarden in extra van de 402-respons als die aanwezig zijn), chainId = 8453, verifyingContract = 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.

De waarde van de X-PAYMENT-header is de base64-codering van dit JSON:

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

Bronnen

• x402-documentatie
• EIP-3009: Transfer With Authorization
• EIP-712: Typed structured data hashing and signing
• Circle: USDC-contractadressen
• uv-installatiegids