Esegui questo notebook in Google Colab
Ogni passo qui sotto come notebook eseguibile. Gira senza un wallet finanziato e si ferma al muro del pagamento, così puoi vedere l’intero flusso prima di spendere qualcosa.
Come funziona
Quattro parti in movimento, tre delle quali sono semplicemente HTTP:
L’inferenza in sé è la normale chiamata a
/chat/completions. L’unica differenza è quale header invii.
Quanto costa iniziare
Contano due numeri, e non sono lo stesso numero. Il top-up minimo è di cinque dollari. È la somma più piccola che/x402/top-up accetterà, ed è restituita nella risposta di discovery piuttosto che essere cablata da qualche parte, quindi leggila invece di fidarti di questa pagina.
Il saldo minimo per effettuare una chiamata è di dieci centesimi. Un wallet che detiene meno di questo riceve un 402 dall’inferenza anche se ha del denaro.
Quindi cinque dollari è il wallet più piccolo che valga la pena finanziare, e cinque dollari è ciò che questa guida dà all’agente. Vale la pena sapere cosa compra: una breve domanda a qwen3-5-9b costa circa ventisette token di input e ventisei di output, che ai prezzi di quel modello equivalgono a circa sette milionesimi di dollaro. Cinque dollari sono nell’ordine di tre quarti di milione di domande. Il budget qui non è un vincolo stretto, è un raggio d’esplosione.
Configurazione
L’SDK x402 si occupa della firma dei pagamenti. Non farlo a mano: l’autorizzazione al trasferimento è un typed data EIP-712 e un nonce riutilizzato fallisce la verifica in modi tediosi da fare debug.L’SDK Python di x402 richiede Python 3.10 o successivo. Colab va bene. Un Python di sistema arrivato con macOS potrebbe non andare bene.
agent.py con la configurazione. BUDGET_USD è il tetto che l’agente si impone da solo, impostato qui sull’intero wallet. Abbassalo e l’agente si ferma prima dei soldi, che è l’unica manopola che probabilmente cambierai.
Un wallet che l’agente possiede
All’agente serve una coppia di chiavi. In produzione questo è un wallet che hai finanziato deliberatamente e la cui chiave vive in un secret manager. Mentre stai costruendo, generarne uno usa e getta è la mossa giusta, perché un wallet senza denaro non può fare nulla di costoso per sbaglio.userdata.get("WALLET_KEY").
Firmare invece di autenticarsi
Non c’è una chiave da inviare, quindi ogni richiesta porta una prova che il proprietario del wallet l’ha fatta. La prova è un messaggio EIP-4361, firmato, poi codificato in base64 nell’headerSIGN-IN-WITH-X.
Il formato del messaggio è preciso. Venice ricostruisce questi byte dal suo lato e verifica la tua firma contro di essi, quindi una riga vuota di troppo significa una firma rifiutata piuttosto che un errore utile.
Issued At. Ogni nonce è usa e getta per circa cinque minuti e mezzo. E il firmatario deve corrispondere al wallet nel path, così un wallet non può ispezionarne un altro e riceve un 403 per averci provato.
La conseguenza pratica è che firmi un header fresco per richiesta invece di metterne uno in cache. Firmare è locale e gratuito, quindi non costa nulla.
canConsume è il campo su cui ramificarti. Tiene conto del pavimento dei dieci centesimi, così non devi farlo tu.
Depositare denaro
Il top-up è di due richieste. La prima chiede cosa Venice accetta ed è non autenticata, perché non c’è ancora nulla da autenticare. La seconda porta un’autorizzazione al trasferimento firmata.amount è in unità base, e USDC ha sei decimali, quindi 5000000 sono cinque dollari e non cinque milioni di qualcosa. Sulla rail Solana, extra.feePayer è un account operato da Venice che copre la fee della transazione, che è ciò che permette a un wallet di pagare senza detenere SOL.
Effettuare il pagamento da un wallet senza USDC restituisce un 400 con PAYMENT_VERIFICATION_FAILED. È la forma attesa del fallimento: la firma era a posto e il trasferimento no.
Pagare per ogni chiamata
Con un saldo in essere, l’inferenza è una normale richiesta che si dà il caso di portare una firma. Spegnere il system prompt di Venice conta più di quanto sembri: vale circa millesettecento token di input per chiamata, che sono due ordini di grandezza più della domanda stessa.402 come esito normale piuttosto che come eccezione è tutto il design. Un agente che paga la propria strada prima o poi finirà i soldi, e finire i soldi non è un crash.
Leggere cosa ha speso
Il registro è autorevole. Piuttosto che stimare dai conteggi di token, chiedi cosa è stato effettivamente addebitato.TOP_UP e REFUND appaiono anch’esse qui, con importi positivi. Filtrare a CHARGE ti dà la spesa.
L’esecuzione a budget
Ora il ciclo. Prima di ogni chiamata l’agente controlla cosa ha speso, e si rifiuta di iniziare un lavoro che non può pagare.Dove ti lascia questo
L’agente detiene il proprio denaro, dimostra la propria identità con una firma, e non può superare un limite che imposti tu, tutto senza che esista un account da nessuna parte. Per un job pianificato, una serverless function, o qualsiasi cosa a cui preferiresti non consegnare una chiave a lunga durata, questa è una postura di sicurezza materialmente diversa. Alcune cose che vale la pena fare dopo:Metti il tetto nel protocollo
I controlli di spesa nell’SDK sono per pagamento, non per sessione. Abbinali al ciclo del budget qui sopra così un bug in uno non può vanificare l’altro.
Ricarica quando è vuoto
Cattura il
402, effettua un top-up e ritenta. Questo è ciò che venice-x402-client fa per te sul lato TypeScript.Paga su Solana
Stesso flusso, rail diversa. Firma Ed25519 e imposta il
feePayer restituito così il wallet non ha bisogno di SOL.Dagli lavoro vero
Sostituisci la lista dei compiti con un ciclo di tool-calling e il registro inizia a mostrarti quanto è costata ogni decisione.