Exécuter ce notebook dans Google Colab
Chaque étape ci-dessous sous forme de notebook exécutable. Il fonctionne sans portefeuille approvisionné et s’arrête au mur de paiement, pour que vous puissiez voir tout le flux avant de dépenser quoi que ce soit.
Comment cela fonctionne
Quatre pièces mobiles, dont trois ne sont que du HTTP :
L’inférence elle-même est l’ordinaire appel
/chat/completions. La seule différence est l’en-tête que vous envoyez.
Ce qu’il en coûte pour commencer
Deux chiffres comptent et ce ne sont pas le même chiffre. L’approvisionnement minimum est de cinq dollars. C’est le plus petit montant que/x402/top-up acceptera de régler, et il est renvoyé dans la réponse de découverte plutôt que codé en dur quelque part, alors lisez-le plutôt que de vous fier à cette page.
Le solde minimum pour passer un appel est de dix cents. Un portefeuille contenant moins que cela reçoit un 402 de l’inférence même s’il détient de l’argent.
Cinq dollars est donc le plus petit portefeuille qui vaille la peine d’être approvisionné, et cinq dollars, c’est ce que ce guide donne à l’agent. À savoir ce que cela achète : une question courte à qwen3-5-9b coûte environ vingt-sept jetons d’entrée et vingt-six jetons de sortie, ce qui, aux prix de ce modèle, équivaut à environ sept millionièmes de dollar. Cinq dollars, c’est de l’ordre de trois quarts de million de questions. Le budget ici n’est pas une contrainte serrée, c’est un rayon d’impact.
Mise en place
Le SDK x402 se charge de signer les paiements. Ne l’écrivez pas à la main : l’autorisation de transfert est de la donnée typée EIP-712 et un nonce réutilisé échoue à la vérification d’une manière fastidieuse à déboguer.Le SDK Python x402 nécessite Python 3.10 ou plus récent. Colab convient. Un Python système livré avec macOS peut ne pas convenir.
agent.py avec la configuration. BUDGET_USD est le plafond que l’agent s’applique à lui-même, fixé ici à la totalité du portefeuille. Abaissez-le et l’agent s’arrête avant que l’argent ne s’épuise, ce qui est le seul bouton que vous êtes susceptible de changer.
Un portefeuille que l’agent possède
L’agent a besoin d’une paire de clés. En production, c’est un portefeuille que vous avez approvisionné délibérément et dont la clé vit dans un gestionnaire de secrets. Pendant que vous construisez, en générer un jetable est le bon choix, car un portefeuille sans argent ne peut rien faire de coûteux par accident.userdata.get("WALLET_KEY").
Se connecter plutôt que s’authentifier
Il n’y a pas de clé à envoyer, donc chaque requête porte une preuve que le propriétaire du portefeuille l’a émise. La preuve est un message EIP-4361, signé, puis encodé en base64 dans l’en-têteSIGN-IN-WITH-X.
Le format du message est strict. Venice reconstruit ces octets de son côté et vérifie votre signature contre eux, donc une ligne vide de trop signifie une signature rejetée plutôt qu’une erreur utile.
Issued At. Chaque nonce est à usage unique pendant environ cinq minutes et demie. Et le signataire doit correspondre au portefeuille dans le chemin, donc un portefeuille ne peut pas en inspecter un autre et reçoit un 403 s’il essaie.
La conséquence pratique est que vous signez un en-tête frais par requête plutôt que d’en mettre un en cache. Signer est local et gratuit, donc cela ne coûte rien.
canConsume est le champ sur lequel se brancher. Il prend en compte le plancher de dix cents, donc vous n’avez pas à le faire.
Mettre de l’argent dedans
Approvisionner tient en deux requêtes. La première demande ce que Venice accepte et n’est pas authentifiée, car il n’y a encore rien à authentifier. La seconde porte une autorisation de transfert signée.amount est en unités de base, et USDC a six décimales, donc 5000000 vaut cinq dollars et non cinq millions de quoi que ce soit. Sur le rail Solana, extra.feePayer est un compte opéré par Venice qui couvre les frais de transaction, ce qui est ce qui permet à un portefeuille de payer sans détenir de SOL.
Régler depuis un portefeuille sans USDC renvoie un 400 avec PAYMENT_VERIFICATION_FAILED. C’est la forme attendue de l’échec : la signature était correcte et le transfert non.
Payer à chaque appel
Une fois un solde en place, l’inférence est une requête normale qui se trouve porter une signature. Désactiver le prompt système Venice compte plus qu’il n’y paraît : cela représente environ mille sept cents jetons d’entrée par appel, soit deux ordres de grandeur de plus que la question elle-même.402 comme un résultat normal plutôt que comme une exception, c’est tout le principe de la conception. Un agent qui paie son propre chemin finira par manquer d’argent, et manquer d’argent n’est pas un plantage.
Lire ce qu’il a dépensé
Le registre fait foi. Plutôt que d’estimer à partir des comptes de jetons, demandez ce qui a effectivement été facturé.TOP_UP et REFUND apparaissent ici aussi, avec des montants positifs. Filtrer sur CHARGE vous donne la dépense.
L’exécution sous budget
Voici la boucle. Avant chaque appel, l’agent vérifie ce qu’il a dépensé, et il refuse d’entreprendre un travail qu’il ne peut pas payer.Où cela vous laisse
L’agent détient son propre argent, prouve son identité par une signature, et ne peut pas dépasser une limite que vous fixez, le tout sans qu’aucun compte n’existe nulle part. Pour une tâche planifiée, une fonction sans serveur, ou tout ce à quoi vous préféreriez ne pas confier une clé de longue durée, c’est une posture de sécurité radicalement différente. Quelques choses à faire ensuite qui en valent la peine :Plafonner dans le protocole
Les contrôles de dépense du SDK sont par paiement, pas par session. Associez-les à la boucle de budget ci-dessus pour qu’un bug dans l’un ne puisse pas défaire l’autre.
Recharger quand c'est vide
Attrapez le
402, approvisionnez, et réessayez. C’est ce que venice-x402-client fait pour vous côté TypeScript.Payer sur Solana
Même flux, rail différent. Signez en Ed25519 et fixez le
feePayer renvoyé pour que le portefeuille n’ait besoin d’aucun SOL.Donnez-lui du vrai travail
Remplacez la liste de tâches par une boucle d’appel d’outils et le registre commence à vous montrer ce que chaque décision a coûté.