Samouczek x402: pozwól swojemu agentowi AI doładować AIHubMix w USDC

AIHubMix przyjmuje teraz doładowania w USDC. Twój agent AI może dodać środki na własne konto, korzystając z USDC znajdujących się w jego portfelu: bez otwierania strony internetowej i bez klikania przycisku przez kogokolwiek.

Dzięki x402 doładowanie może wynosić już 1 USD. Agent doładowuje konto w miarę potrzeb, więc nie musisz wcześniej wpłacać dużego salda.

Wystarczą dwa kroki: przygotuj token, portfel i trochę USDC w sieci oraz w aplikacji, a następnie uruchom nasz gotowy skrypt doładowania jedną komendą. Około 20 sekund po płatności kredyt pojawi się na Twoim koncie.

Jeśli to pomoże, możesz śledzić proces w tym 30-sekundowym filmie:

Najprostszy sposób: jeśli używasz narzędzia AI, które potrafi uruchamiać komendy w terminalu, np. Claude Code, Cursor lub Codex, wykonaj krok 1, a następnie wyślij mu link do tego wpisu i napisz „skonfiguruj to za mnie”. Narzędzie postępuje zgodnie z sekcją „Instrukcje dla asystentów AI” na końcu tego wpisu. Tylko raz sam wpisujesz token i klucz prywatny, bez przesyłania ich AI.

Zanim zaczniesz

• Kwoty to wyłącznie pełne dolary, domyślnie od 1 do 10 USD na jedno doładowanie
• Każde konto może utworzyć maksymalnie 3 zamówienia dziennie (UTC)
• Obsługiwane jest wyłącznie USDC w sieci głównej Base, a testnetu nie ma, dlatego zacznij od 1 USD
• Ten kanał jest przeznaczony dla programów; człowiek nie może zapłacić w przeglądarce. Przy ręcznych doładowaniach korzystaj nadal z Alipay lub Stripe

Krok 1: Zdobądź token, portfel i USDC

Wszystko w tym kroku odbywa się w przeglądarce internetowej lub w aplikacji mobilnej.

1. Zdobądź systemowy token dostępu

Zaloguj się na aihubmix.com, otwórz swoje ustawienia osobiste i wygeneruj systemowy token dostępu (32-znakowy ciąg).

Pamiętaj, że nie jest to klucz API zaczynający się od sk-. Te dwa elementy nie są wymienne.

2. Utwórz portfel do płatności

W MetaMask lub podobnej aplikacji portfela utwórz nowe konto wyłącznie do płatności agenta. Nie używaj głównego portfela. Następnie:

• Skopiuj adres konta (zaczyna się od 0x); na ten adres wyślesz USDC w następnym kroku
• Wyeksportuj jego klucz prywatny ze szczegółów konta i przechowuj go w menedżerze haseł. Każdy, kto ma klucz prywatny, może przenosić środki z portfela

3. Kup USDC i wyślij go na ten portfel

MetaMask to portfel: to Ty posiadasz klucz prywatny, a skrypt potrzebuje go do podpisywania. Coinbase to giełda, na której kupujesz kryptowaluty. Środki na koncie giełdowym nie mają klucza prywatnego, więc skrypt nie może z nich skorzystać. Dlatego najpierw kupujesz na giełdzie, a następnie wysyłasz USDC na portfel z poprzedniego kroku.

Na przykładzie giełdy Coinbase (nie Coinbase Wallet):

1. Kup USDC na Coinbase
2. Wyślij USDC na skopiowany adres i wybierz sieć Base
3. Wyślij nieco więcej, niż planujesz doładować, np. 1,5 do 2 USDC na doładowanie w wysokości 1 USD

Poczekaj chwilę, a następnie otwórz https://basescan.org/address/your-wallet-address. Gdy zobaczysz saldo USDC, oznacza to, że środki dotarły. Działają też inne giełdy obsługujące wypłaty USDC w sieci Base; więcej opcji znajdziesz w dokumentacji Base.

Portfel nie potrzebuje żadnego ETH: opłatę sieciową za płatność pokrywa FluxA.

Krok 2: Uruchom skrypt doładowania

Nie ma czego pobierać ani pliku do tworzenia: uv pobiera skrypt z sieci i go uruchamia. Otwórz Terminal (PowerShell w Windows) i skopiuj oraz wklej poniższe komendy.

1. Zainstaluj uv (raz)

uv to narzędzie Pythona, które przygotowuje wszystko, czego skrypt potrzebuje do działania.

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"

Po zakończeniu zamknij terminal i otwórz go ponownie.

2. Sprawdź konfigurację (nic nie kosztuje)

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

Przy pierwszym uruchomieniu skrypt poprosi o systemowy token dostępu (System access token) i klucz prywatny portfela (Wallet private key). To, co wpisujesz, nie jest wyświetlane na ekranie; wklej je i naciśnij Enter. Następnie zapyta, czy je zapisać (Save to ...? [Y/n]). Naciśnij Enter, aby zapisać, a nie będziesz musiał wpisywać ich ponownie. Pierwsze uruchomienie trwa chwilę, bo uv przygotowuje środowisko.

Gdy zobaczysz poniższy komunikat, konfiguracja jest gotowa:

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

3. Doładuj konto

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

Cyfra 1 na końcu to kwota w dolarach. Jeśli wszystko przebiegnie prawidłowo, zobaczysz:

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

result: credited oznacza, że kredyt dotarł. Zaloguj się na aihubmix.com, a zobaczysz wzrost salda; 1 USD dodaje 500 000 quota.

Jeśli ostatnia linia zawiera coś innego:

• failed: zamówienie zostało zamknięte lub wygasło. Jeśli potrzebujesz, uruchom skrypt ponownie; zużyje to kolejne z dzisiejszych zamówień.
• pending: kredyt nie został potwierdzony w ciągu 10 minut. To nie jest błąd, a kredyt dotrze później automatycznie. Nie uruchamiaj skryptu ponownie.

Rozwiązywanie problemów

Jeśli po wypisaniu tradeNo pojawi się błąd przekroczenia czasu lub sieci, pieniądze mogły już zostać zapłacone. Nie uruchamiaj skryptu ponownie od razu. Sprawdź saldo po kilku minutach; jeśli nic nie dotarło, skontaktuj się z nami, podając tradeNo.

Token i klucz prywatny są zapisane w ~/.aihubmix-topup.env na Twoim komputerze (w Windows w folderze użytkownika). W macOS i Linux tylko Twoje konto ma do niego dostęp. Aby zmienić token lub klucz prywatny, edytuj ten plik.

Podłączanie do agenta

• Po zapisaniu konfiguracji agent może doładowywać konto, uruchamiając uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py 1 zawsze, gdy potrzebuje kredytu, nawet bez nadzoru człowieka
• Dozwolone są tylko 3 zamówienia dziennie, dlatego ogranicz częstotliwość doładowań agenta i nigdy nie ponawiaj tworzenia zamówienia w pętli
• Zapisuj tradeNo i txHash z wyniku w bazie danych lub logu, aby móc je uzgadniać
• Do długoterminowego użytku pobierz skrypt i przypnij wersję przed uruchomieniem; najpierw możesz przeczytać kod źródłowy
• Jeśli limit 10 USD na doładowanie lub 3 zamówienia dziennie nie wystarcza, skontaktuj się z nami, aby go podnieść

Instrukcje dla asystentów AI

Jeśli jesteś asystentem AI pomagającym użytkownikowi skonfigurować doładowania AIHubMix w USDC, wykonaj poniższe kroki po kolei:

1. Upewnij się, że użytkownik ukończył krok 1: ma systemowy token dostępu oraz portfel z USDC w sieci głównej Base i jego klucz prywatny. Jeśli nie, najpierw przeprowadź go przez krok 1.
2. Uruchom uv --version, aby sprawdzić, czy uv jest zainstalowany. Jeśli nie, zainstaluj go poleceniami z kroku 2.
3. Uruchom uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py check.
4. Jeśli skrypt zgłosi brak tokenu lub klucza prywatnego (Missing access token or private key), oznacza to, że utworzył plik konfiguracyjny ~/.aihubmix-topup.env. Poproś użytkownika, aby otworzył go w edytorze tekstu i uzupełnił samodzielnie (na macOS uruchom open -e ~/.aihubmix-topup.env; w Windows uruchom notepad $HOME\.aihubmix-topup.env). Nie czytaj tego pliku, nie umieszczaj tokenu ani klucza prywatnego w żadnej komendzie i nie proś użytkownika, aby Ci je przesłał.
5. Gdy użytkownik uzupełni plik, uruchom check ponownie, aż zobaczysz Access token and private key are fine. Ready to top up.. Jeśli pojawi się błąd, obsłuż go według tabeli rozwiązywania problemów powyżej.
6. Doładowanie wydaje prawdziwe pieniądze. Potwierdź kwotę z użytkownikiem przed uruchomieniem uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py <amount>.

Pod spodem: co robi skrypt

Skrypt wykonuje pięć czynności po kolei:

1. Sprawdza saldo: utworzenie zamówienia zużywa jedno z dzisiejszych zamówień, dlatego najpierw upewnia się, że klucz prywatny jest prawidłowy i że USDC jest wystarczająco dużo.
2. Tworzy zamówienie: wywołuje POST /api/pay/fluxa/crt i otrzymuje link do płatności oraz numer zamówienia tradeNo. Token trafia do nagłówka Authorization bez zmian, bez Bearer. Błędy biznesowe również zwracane są jako HTTP 200, dlatego skrypt sprawdza pole success w odpowiedzi.
3. Sprawdza żądanie płatności: żądanie GET na link do płatności zwraca HTTP 402 z wymaganiami płatności. Przed podpisaniem sprawdza cztery rzeczy: scheme to exact, network to eip155:8453, asset to kontrakt USDC w sieci głównej Base, a maxAmountRequired równa się kwocie × 1 000 000. Jeśli którakolwiek z tych wartości się nie zgadza, skrypt się zatrzymuje.
4. Podpisuje i płaci: podpisuje autoryzację transferu USDC kluczem prywatnym, umieszcza ją w nagłówku X-PAYMENT i ponownie wysyła GET na link do płatności. Odpowiedzi 200 lub 202 oznaczają, że płatność została przesłana; txHash w odpowiedzi to potwierdzenie on-chain tej płatności. Żadne z żądań nie zawiera tokenu AIHubMix.
5. Czeka na kredyt: co 8 sekund wywołuje GET /api/pay/fluxa/qry?trade_no=..., aż status zmieni się na TRADE_SUCCESS. Serwer odświeża dane tylko co 5 sekund, więc częstsze odpytywanie nic nie przyspieszy.

Każdy link do płatności jest też ważny przez 30 minut i można go opłacić tylko raz.

Implementacja w innym języku

Odpowiedź 402 z linku do płatności wygląda tak:

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

Podpis używa formatu EIP-712 i dotyczy struktury TransferWithAuthorization z EIP-3009:

Domena podpisu: name = USD Coin, version = 2 (użyj wartości z pola extra w odpowiedzi 402, jeśli jest obecne), chainId = 8453, verifyingContract = 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.

Wartość nagłówka X-PAYMENT to zakodowany w base64 poniższy JSON:

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

Źródła

• Dokumentacja x402
• EIP-3009: Transfer With Authorization
• EIP-712: Typed structured data hashing and signing
• Circle: adresy kontraktów USDC
• Przewodnik instalacji uv