Skip to main content
Un agent muni d’une clé d’API peut dépenser tout ce que la clé peut dépenser. Cela convient quand une personne le surveille et devient gênant quand personne ne le fait. Les correctifs habituels vivent en dehors de l’agent, dans un tableau de bord ou une alerte de facturation qui vous prévient du problème après qu’il s’est produit. Venice prend en charge une seconde manière d’entrer. Au lieu d’une clé, l’agent détient un portefeuille. Il s’authentifie en signant un message, paie chaque requête depuis un solde USDC attaché à l’adresse de ce portefeuille, et chaque prélèvement arrive dans un registre qu’il peut relire. Pas de compte, pas de tableau de bord, et pas de clé à faire fuiter. Le plafond est le solde, et vous décidez ce que vous y placez. Ce guide construit un agent qui fait exactement cela, sous un budget qu’il applique lui-même.

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.
Créez 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.
Gardez la clé privée en dehors du notebook. Dans Colab, mettez-la dans les Secrets et lisez-la avec 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ête SIGN-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.
Trois règles régissent ces en-têtes, et toutes trois existent pour empêcher le rejeu. La signature est valide pendant cinq minutes à partir de 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.
Sur un portefeuille neuf :
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.
La découverte renvoie une entrée par rail. Base et Solana aujourd’hui :
Deux détails là-dedans sont faciles à survoler. 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.
Le contrôle de dépense par défaut est la première chose qui va vous bloquer. Le SDK est livré avec max_amount_per_payment réglé sur un dollar, et l’approvisionnement minimum Venice est de cinq, donc un client non modifié rejette chaque rail proposé et lève NoMatchingRequirementsError avant même de contacter le réseau. Relevez le plafond délibérément plutôt que de désactiver les contrôles de dépense.
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.
Traiter 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é.
Chaque ligne renvoie à l’appel qui l’a causée :
Les lignes 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.
Lancez-le avec les cinq dollars complets et le budget ne se déclenche jamais, ce qui est le résultat honnête à ces prix. Pour voir le plafond agir réellement, fixez-en un qu’un seul appel dépassera :

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é.
Pour la référence complète du point de terminaison, consultez x402 top-up et Utiliser x402 avec l’API Venice.