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 nvidia-nemotron-3-nano-30b-a3b costa circa ventisette token di input e ventisei di output, che ai prezzi di quel modello equivalgono a circa dieci milionesimi di dollaro. Cinque dollari sono nell’ordine di mezzo 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. Non saltarlo nemmeno. Un semplice trasferimento di USDC all’indirizzopayTo non viene accreditato, perché il saldo si muove solo quando un pagamento firmato viene regolato tramite /x402/top-up.
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 è costituita dai campi di un messaggio EIP-4361 più la tua firma su quel messaggio, codificati in base64 nell’headerSIGN-IN-WITH-X nel formato sign-in-with-x di x402.
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.