Tutorial x402: fai ricaricare AIHubMix in USDC al tuo agente AI

AIHubMix ora accetta ricariche in USDC. Il tuo agente AI può aggiungere credito al proprio account con gli USDC presenti nel suo wallet: nessuna pagina web da aprire e nessuno deve cliccare un pulsante.

Con x402, una ricarica può essere di soli $1. L'agente ricarica man mano che procede, quindi non devi caricare in anticipo un saldo elevato.

Servono due passaggi: preparare un token, un wallet e un po' di USDC sul web e in un'app, poi eseguire il nostro script di ricarica pronto all'uso con un solo comando. Circa 20 secondi dopo il pagamento, il credito compare nel tuo account.

Se ti è utile, puoi seguire questo video di 30 secondi:

Il modo più semplice: se usi uno strumento AI che può eseguire comandi da terminale, come Claude Code, Cursor o Codex, completa il passaggio 1, poi inviagli il link a questo articolo e scrivi "configuralo per me". Seguirà le "Istruzioni per assistenti AI" alla fine di questo articolo. Tu inserisci da solo il token e la chiave privata, una sola volta, senza inviarli all'AI.

Prima di iniziare

• Gli importi sono solo in dollari interi, da $1 a $10 per ricarica per impostazione predefinita
• Ogni account può creare fino a 3 ordini al giorno (UTC)
• È supportato solo USDC sulla mainnet di Base e non esiste una testnet, quindi inizia con $1
• Questo canale è pensato per i programmi; una persona non può pagare dal browser. Per le ricariche manuali, continua a usare Alipay o Stripe

Passaggio 1: ottieni un token, un wallet e USDC

Tutto questo passaggio avviene sul web o in un'app per il telefono.

1. Ottieni il tuo token di accesso di sistema

Accedi a aihubmix.com, apri le impostazioni personali e genera un token di accesso di sistema (una stringa di 32 caratteri).

Nota che non è la chiave API che inizia con sk-. I due non sono intercambiabili.

2. Crea un wallet per i pagamenti

In MetaMask o in un'app wallet simile, crea un nuovo account solo per i pagamenti dell'agente. Non usare il tuo wallet principale. Poi:

• Copia l'indirizzo dell'account (inizia con 0x); a quello invierai gli USDC nel passaggio successivo
• Esporta la sua chiave privata dai dettagli dell'account e conservala in un gestore di password. Chiunque abbia la chiave privata può spostare i fondi del wallet

3. Acquista USDC e inviali a questo wallet

MetaMask è un wallet: sei tu a possedere la chiave privata, e lo script ne ha bisogno per firmare. Coinbase è un exchange, dove si compra crypto. I fondi in un account exchange non vengono con una chiave privata, quindi lo script non può usarli. Per questo acquisti prima sull'exchange, poi invii gli USDC al wallet del passaggio precedente.

Prendendo come esempio l'exchange Coinbase (non Coinbase Wallet):

1. Acquista USDC su Coinbase
2. Invia gli USDC all'indirizzo che hai copiato e scegli la rete Base
3. Invia un po' più di quanto prevedi di ricaricare, ad esempio da 1,5 a 2 USDC per una ricarica da $1

Attendi un momento, poi apri https://basescan.org/address/your-wallet-address. Quando vedi un saldo in USDC, significa che è arrivato. Funzionano anche altri exchange che supportano i prelievi in USDC su Base; consulta la documentazione di Base per altre opzioni.

Il wallet non ha bisogno di ETH: FluxA paga la commissione di rete per il pagamento.

Passaggio 2: esegui lo script di ricarica

Non c'è niente da scaricare e nessun file da creare: uv recupera lo script dal web e lo esegue. Apri il Terminale (PowerShell su Windows) e copia e incolla i comandi qui sotto.

1. Installa uv (una sola volta)

uv è uno strumento Python che prepara tutto ciò di cui lo script ha bisogno per funzionare.

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"

Al termine, chiudi il terminale e riaprilo.

2. Verifica la configurazione (non spende nulla)

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

Alla prima esecuzione, lo script chiede il tuo token di accesso di sistema (System access token) e la chiave privata del wallet (Wallet private key). Quello che digiti non viene mostrato sullo schermo; incollalo e premi Invio. Poi chiede se salvarli (Save to ...? [Y/n]). Premi Invio per salvare, così non dovrai digitarli di nuovo. La prima esecuzione richiede un momento mentre uv prepara l'ambiente.

Quando vedi questo, la configurazione è pronta:

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

3. Ricarica

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

Il 1 alla fine è l'importo in dollari. Se tutto va bene, vedrai:

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

result: credited significa che il credito è arrivato. Accedi ad aihubmix.com e vedrai il saldo aumentare; $1 aggiunge 500.000 quota.

Se l'ultima riga dice qualcosa di diverso:

• failed: l'ordine è stato chiuso o è scaduto. Se ti serve, esegui di nuovo il comando; così usi un altro dei tuoi ordini di oggi.
• pending: il credito non è stato confermato entro 10 minuti. Non è un errore e il credito arriverà in seguito da solo. Non eseguire di nuovo il comando.

Risoluzione dei problemi

Se dopo la stampa di tradeNo compare un timeout o un errore di rete, il denaro potrebbe essere già stato pagato. Non eseguire di nuovo il comando subito. Controlla il saldo dopo qualche minuto; se non è arrivato nulla, contattaci indicando il tradeNo.

Il token e la chiave privata sono salvati in ~/.aihubmix-topup.env sul tuo computer (nella cartella utente su Windows). Su macOS e Linux, solo il tuo account può leggerlo. Per cambiare token o chiave privata, modifica questo file.

Integrazione con il tuo agente

• Una volta salvata la configurazione, il tuo agente può ricaricare eseguendo uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py 1 ogni volta che ha bisogno di credito, anche senza nessuno presente
• Sono consentiti solo 3 ordini al giorno, quindi limita la frequenza delle ricariche dell'agente e non riprovare mai la creazione dell'ordine in un ciclo
• Salva il tradeNo e il txHash dell'output in un database o in un log per la riconciliazione
• Per un uso a lungo termine, scarica lo script e fissa una versione prima di eseguirlo; puoi leggere il codice sorgente prima
• Se $10 per ricarica o 3 al giorno non bastano, contattaci per aumentare i limiti

Istruzioni per assistenti AI

Se sei un assistente AI che aiuta un utente a configurare le ricariche USDC di AIHubMix, segui questi passaggi in ordine:

1. Verifica che l'utente abbia completato il passaggio 1: ha un token di accesso di sistema, più un wallet con USDC sulla mainnet di Base e la sua chiave privata. In caso contrario, guidalo prima attraverso il passaggio 1.
2. Esegui uv --version per verificare che uv sia installato. Se non lo è, installalo con i comandi del passaggio 2.
3. Esegui uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py check.
4. Se segnala un token o una chiave privata mancanti (Missing access token or private key), lo script ha creato il file di configurazione ~/.aihubmix-topup.env. Chiedi all'utente di aprirlo con un editor di testo e di compilarlo personalmente (su macOS, esegui open -e ~/.aihubmix-topup.env; su Windows, esegui notepad $HOME\.aihubmix-topup.env). Non leggere questo file, non inserire il token o la chiave privata in nessun comando e non chiedere all'utente di inviarteli.
5. Quando l'utente l'ha compilato, esegui di nuovo check finché non vedi Access token and private key are fine. Ready to top up. Se c'è un errore, gestiscilo con la tabella di risoluzione dei problemi sopra.
6. Una ricarica spende denaro reale. Conferma l'importo con l'utente prima di eseguire uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py <amount>.

Sotto il cofano: cosa fa lo script

Lo script esegue cinque operazioni in ordine:

1. Controlla il saldo: creare un ordine consuma uno dei tuoi ordini di oggi, quindi prima verifica che la chiave privata sia valida e che ci siano abbastanza USDC.
2. Crea un ordine: chiama POST /api/pay/fluxa/crt e ottiene un link di pagamento e un numero d'ordine, tradeNo. Il token va nell'header Authorization così com'è, senza Bearer. Anche gli errori di business arrivano come HTTP 200, quindi controlla il campo success nella risposta.
3. Controlla la richiesta di pagamento: una GET sul link di pagamento restituisce HTTP 402 con i requisiti di pagamento. Prima di firmare, verifica quattro cose: scheme è exact, network è eip155:8453, asset è il contratto USDC sulla mainnet di Base e maxAmountRequired è uguale all'importo × 1.000.000. Se una di queste non torna, si ferma.
4. Firma e paga: firma un'autorizzazione di trasferimento USDC con la chiave privata, la inserisce nell'header X-PAYMENT e invia di nuovo la GET al link di pagamento. Un 200 o un 202 significa che il pagamento è stato inviato; il txHash nella risposta è la ricevuta on-chain di questo pagamento. Nessuna delle due richieste contiene il token di AIHubMix.
5. Attende il credito: chiama GET /api/pay/fluxa/qry?trade_no=... ogni 8 secondi finché lo stato diventa TRADE_SUCCESS. Il server si aggiorna solo ogni 5 secondi, quindi interrogarlo più velocemente non serve a nulla.

Ogni link di pagamento è inoltre valido per 30 minuti e può essere pagato una sola volta.

Implementazione in un altro linguaggio

La risposta 402 del link di pagamento ha questo aspetto:

{
  "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 il formato EIP-712, sulla struttura TransferWithAuthorization di EIP-3009:

Dominio di firma: name = USD Coin, version = 2 (usa i valori in extra della risposta 402, se presenti), chainId = 8453, verifyingContract = 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.

Il valore dell'header X-PAYMENT è la codifica base64 di questo JSON:

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

Fonti

• Documentazione x402
• EIP-3009: Transfer With Authorization
• EIP-712: Typed structured data hashing and signing
• Circle: indirizzi dei contratti USDC
• Guida all'installazione di uv