x402-Tutorial: Lass deinen KI-Agenten AIHubMix mit USDC aufladen

AIHubMix akzeptiert jetzt USDC-Aufladungen. Dein KI-Agent kann seinem eigenen Konto mit den USDC in seiner Wallet Guthaben hinzufügen: ohne eine Webseite zu öffnen und ohne dass jemand auf einen Button klicken muss.

Mit x402 kann eine Aufladung schon ab 1 $ erfolgen. Der Agent lädt nach Bedarf nach, sodass du nicht im Voraus ein großes Guthaben hinterlegen musst.

Es sind zwei Schritte: Du bereitest im Web und in einer App einen Token, eine Wallet und etwas USDC vor und führst dann unser fertiges Aufladeskript mit einem einzigen Befehl aus. Etwa 20 Sekunden nach der Zahlung erscheint das Guthaben in deinem Konto.

Falls es hilft, kannst du diesem 30-Sekunden-Video folgen:

Der einfachste Weg: Wenn du ein KI-Tool nutzt, das Terminal-Befehle ausführen kann, etwa Claude Code, Cursor oder Codex, erledige Schritt 1 und schicke ihm dann den Link zu diesem Beitrag mit der Bitte „richte das für mich ein“. Es folgt dann den „Anleitung für KI-Assistenten“ am Ende dieses Beitrags. Token und privaten Schlüssel trägst nur du selbst ein, einmalig, ohne sie an die KI zu senden.

Bevor du anfängst

• Beträge sind nur in ganzen Dollar möglich, standardmäßig 1 $ bis 10 $ pro Aufladung
• Jedes Konto kann höchstens 3 Bestellungen pro Tag (UTC) anlegen
• Unterstützt wird nur USDC im Base-Mainnet, ein Testnetz gibt es nicht. Starte daher mit 1 $
• Dieser Kanal ist für Programme gedacht; eine Person kann im Browser nicht zahlen. Für manuelle Aufladungen nutzt du weiterhin Alipay oder Stripe

Schritt 1: Token, Wallet und USDC besorgen

Alles in diesem Schritt passiert im Web oder in einer Smartphone-App.

1. Systemzugriffstoken abrufen

Melde dich bei aihubmix.com an, öffne deine persönlichen Einstellungen und erzeuge ein Systemzugriffstoken (eine Zeichenfolge aus 32 Zeichen).

Beachte, dass dies nicht der API-Schlüssel ist, der mit sk- beginnt. Beide sind nicht austauschbar.

2. Zahlungs-Wallet erstellen

Erstelle in MetaMask oder einer ähnlichen Wallet-App ein neues Konto, nur für die Zahlungen des Agenten. Verwende nicht deine Haupt-Wallet. Danach:

• Kopiere die Adresse des Kontos (sie beginnt mit 0x); du sendest im nächsten Schritt USDC dorthin
• Exportiere den privaten Schlüssel aus den Kontodetails und bewahre ihn in einem Passwort-Manager auf. Wer den privaten Schlüssel hat, kann das Geld in der Wallet bewegen

3. USDC kaufen und an diese Wallet senden

MetaMask ist eine Wallet: Du hältst den privaten Schlüssel, und das Skript braucht ihn zum Signieren. Coinbase ist eine Börse, auf der du Kryptowährungen kaufst. Guthaben auf einem Börsenkonto kommen ohne privaten Schlüssel, daher kann das Skript sie nicht nutzen. Deshalb kaufst du zuerst an der Börse und sendest das USDC dann an die Wallet aus dem vorherigen Schritt.

Am Beispiel der Börse Coinbase (nicht Coinbase Wallet):

1. Kaufe USDC bei Coinbase
2. Sende das USDC an die kopierte Adresse und wähle das Base-Netzwerk
3. Sende etwas mehr, als du aufladen möchtest, zum Beispiel 1,5 bis 2 USDC für eine Aufladung über 1 $

Warte einen Moment und öffne dann https://basescan.org/address/your-wallet-address. Sobald du ein USDC-Guthaben siehst, ist es angekommen. Andere Börsen, die USDC-Auszahlungen im Base-Netzwerk unterstützen, funktionieren ebenfalls; weitere Optionen findest du in der Base-Dokumentation.

Die Wallet braucht kein ETH: FluxA übernimmt die Netzwerkgebühr für die Zahlung.

Schritt 2: Aufladeskript ausführen

Du musst nichts herunterladen und keine Datei anlegen: uv holt das Skript aus dem Web und führt es aus. Öffne das Terminal (PowerShell unter Windows) und kopiere die folgenden Befehle hinein.

1. uv installieren (einmalig)

uv ist ein Python-Werkzeug, das alles einrichtet, was das Skript zum Ausführen braucht.

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"

Wenn die Installation fertig ist, schließe das Terminal und öffne es erneut.

2. Einrichtung prüfen (kostet nichts)

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

Beim ersten Start fragt das Skript nach deinem Systemzugriffstoken (System access token) und dem privaten Schlüssel der Wallet (Wallet private key). Was du eintippst, wird nicht angezeigt; füge es ein und drücke die Eingabetaste. Dann fragt es, ob es die Daten speichern soll (Save to ...? [Y/n]). Drücke die Eingabetaste zum Speichern, dann musst du sie nicht erneut eingeben. Der erste Start dauert einen Moment, während uv alles vorbereitet.

Wenn du das siehst, ist die Einrichtung fertig:

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

3. Aufladen

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

Die 1 am Ende ist der Betrag in Dollar. Wenn alles gut läuft, siehst du:

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

result: credited bedeutet, dass das Guthaben angekommen ist. Melde dich bei aihubmix.com an, dort siehst du, wie dein Guthaben steigt; 1 $ ergibt 500.000 Quota.

Wenn in der letzten Zeile etwas anderes steht:

• failed: Die Bestellung wurde geschlossen oder ist abgelaufen. Führe den Befehl bei Bedarf erneut aus; das verbraucht eine weitere der heutigen Bestellungen.
• pending: Das Guthaben wurde nicht innerhalb von 10 Minuten bestätigt. Das ist kein Fehler, das Guthaben wird später automatisch eintreffen. Führe den Befehl nicht erneut aus.

Fehlerbehebung

Wenn nach der Ausgabe von tradeNo ein Timeout- oder Netzwerkfehler auftritt, wurde das Geld unter Umständen schon bezahlt. Führe den Befehl nicht sofort erneut aus. Prüfe dein Guthaben nach einigen Minuten; ist nichts angekommen, kontaktiere uns mit der tradeNo.

Token und privater Schlüssel werden in ~/.aihubmix-topup.env auf deinem Computer gespeichert (unter Windows im Benutzerordner). Unter macOS und Linux kann nur dein eigenes Benutzerkonto diese Datei lesen. Um Token oder privaten Schlüssel zu ändern, bearbeite diese Datei.

Einbindung in deinen Agenten

• Sobald die Einrichtung gespeichert ist, kann dein Agent aufladen, indem er uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py 1 ausführt, wann immer er Guthaben braucht, auch ohne dass jemand dabei ist
• Es sind nur 3 Bestellungen pro Tag erlaubt. Begrenze daher, wie oft der Agent auflädt, und wiederhole die Bestellerstellung niemals in einer Schleife
• Speichere die tradeNo und txHash aus der Ausgabe in einer Datenbank oder einem Log, um sie später abzugleichen
• Für den Dauerbetrieb lade das Skript herunter und fixiere eine Version, bevor du es ausführst; du kannst den Quellcode vorher lesen
• Reichen 10 $ pro Aufladung oder 3 pro Tag nicht aus, kontaktiere uns, um die Limits zu erhöhen

Anleitung für KI-Assistenten

Wenn du ein KI-Assistent bist und einem Nutzer bei den USDC-Aufladungen für AIHubMix hilfst, folge diesen Schritten der Reihe nach:

1. Vergewissere dich, dass der Nutzer Schritt 1 abgeschlossen hat: Er hat ein Systemzugriffstoken sowie eine Wallet mit USDC im Base-Mainnet und deren privaten Schlüssel. Falls nicht, führe ihn zuerst durch Schritt 1.
2. Führe uv --version aus, um zu prüfen, ob uv installiert ist. Falls nicht, installiere es mit den Befehlen aus Schritt 2.
3. Führe uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py check aus.
4. Meldet das Skript ein fehlendes Token oder einen fehlenden privaten Schlüssel (Missing access token or private key), hat es die Konfigurationsdatei ~/.aihubmix-topup.env erstellt. Bitte den Nutzer, sie in einem Texteditor zu öffnen und selbst auszufüllen (auf macOS mit open -e ~/.aihubmix-topup.env; unter Windows mit notepad $HOME\.aihubmix-topup.env). Lies diese Datei nicht, füge Token oder privaten Schlüssel in keinen Befehl ein und bitte den Nutzer nicht, sie dir zu schicken.
5. Sobald der Nutzer die Datei ausgefüllt hat, führe check erneut aus, bis du Access token and private key are fine. Ready to top up. siehst. Tritt ein Fehler auf, behandle ihn mit der Fehlerbehebungstabelle oben.
6. Eine Aufladung gibt echtes Geld aus. Bestätige den Betrag mit dem Nutzer, bevor du uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py <amount> ausführst.

Hinter den Kulissen: Was das Skript tut

Das Skript führt der Reihe nach fünf Schritte aus:

1. Prüft das Guthaben: Das Anlegen einer Bestellung verbraucht eine der heutigen Bestellungen. Deshalb prüft das Skript zuerst, ob der private Schlüssel gültig ist und genug USDC vorhanden ist.
2. Erstellt eine Bestellung: Es ruft POST /api/pay/fluxa/crt auf und erhält einen Zahlungslink und eine Bestellnummer, tradeNo. Das Token wird unverändert in den Authorization-Header gesetzt, ohne Bearer. Geschäftsfehler kommen ebenfalls mit HTTP 200 zurück, daher prüft es das Feld success in der Antwort.
3. Prüft die Zahlungsanfrage: Ein GET auf den Zahlungslink liefert HTTP 402 mit den Zahlungsvoraussetzungen. Vor dem Signieren prüft das Skript vier Dinge: scheme ist exact, network ist eip155:8453, asset ist der USDC-Vertrag im Base-Mainnet, und maxAmountRequired entspricht Betrag × 1.000.000. Weicht etwas davon ab, bricht es ab.
4. Signiert und zahlt: Es signiert mit dem privaten Schlüssel eine USDC-Transferautorisierung, legt sie in den X-PAYMENT-Header und sendet den GET erneut an den Zahlungslink. Ein 200 oder 202 bedeutet, dass die Zahlung übermittelt wurde; das txHash in der Antwort ist der On-Chain-Beleg für diese Zahlung. Keine der beiden Anfragen enthält das AIHubMix-Token.
5. Wartet auf das Guthaben: Es ruft alle 8 Sekunden GET /api/pay/fluxa/qry?trade_no=... auf, bis der Status TRADE_SUCCESS ist. Der Server aktualisiert nur alle 5 Sekunden, daher hilft schnelleres Abfragen nicht.

Jeder Zahlungslink ist außerdem 30 Minuten gültig und kann nur einmal bezahlt werden.

Umsetzung in einer anderen Sprache

Die 402-Antwort des Zahlungslinks sieht so aus:

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

Die Signatur verwendet das EIP-712-Format für die Struktur TransferWithAuthorization aus EIP-3009:

Signaturdomäne: name = USD Coin, version = 2 (verwende die Werte aus extra der 402-Antwort, falls vorhanden), chainId = 8453, verifyingContract = 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.

Der Wert des X-PAYMENT-Headers ist die Base64-Kodierung dieses JSON:

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

Quellen

• x402-Dokumentation
• EIP-3009: Transfer With Authorization
• EIP-712: Typed structured data hashing and signing
• Circle: USDC-Vertragsadressen
• uv-Installationsanleitung