Skip to main content
Un agente con una chiave API può spendere qualunque cosa la chiave possa spendere. Va bene quando una persona lo sta guardando ed è imbarazzante quando nessuno lo fa. Le soluzioni consuete vivono fuori dall’agente, in una dashboard o in un avviso di fatturazione che ti informa del problema dopo che è successo. Venice supporta una seconda via d’ingresso. Invece di una chiave, l’agente detiene un wallet. Si autentica firmando un messaggio, paga ogni richiesta con un saldo USDC associato all’indirizzo di quel wallet, e ogni addebito finisce in un registro che può rileggere. Non c’è account, dashboard, né chiave da far trapelare. Il tetto è il saldo, e sei tu a decidere cosa metterci. Questa guida costruisce un agente che fa esattamente questo, sotto un budget che si impone da solo.

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.
Crea 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.
Tieni la chiave privata fuori dal notebook. In Colab, mettila in Secrets e leggila con 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’header SIGN-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.
Tre regole governano questi header, e tutte e tre esistono per fermare il replay. La firma è valida per cinque minuti da 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.
Su un wallet nuovo:
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.
La discovery restituisce una voce per rail. Base e Solana oggi:
Due dettagli lì dentro sono facili da tralasciare. 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.
Il controllo di spesa predefinito è la prima cosa che ti fermerà. L’SDK viene distribuito con max_amount_per_payment impostato a un dollaro, e il top-up minimo di Venice è cinque, quindi un client non modificato rifiuta ogni rail offerta e solleva NoMatchingRequirementsError prima ancora di contattare la rete. Alza il tetto deliberatamente piuttosto che disattivare i controlli di spesa.
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.
Gestire 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.
Ogni riga rimanda alla chiamata che l’ha causata:
Le righe 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.
Eseguilo con l’intero importo di cinque dollari e il budget non stringe mai, che è il risultato onesto a questi prezzi. Per vedere il tetto funzionare davvero, impostane uno che una singola chiamata infrangerà:

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.
Per il riferimento completo dell’endpoint, consulta x402 top-up e Usare x402 con l’API Venice.