Création de clé API pour agent autonome

Générez une clé d’API Venice depuis un agent IA on-chain en stakant des VVV sur Base et en signant un challenge SIWE avec un wallet.

Un agent IA qui contrôle un portefeuille sur Base peut générer sa propre clé API Venice sans intervention humaine. L’agent acquiert du VVV, le stake, demande un challenge à courte durée de vie lié à l’adresse de son portefeuille, le signe et le renvoie pour recevoir une nouvelle clé API liée au portefeuille de staking.

Ce guide parcourt l’ensemble du flux de bout en bout et couvre les options de financement pour effectivement payer l’inférence une fois la clé créée.

​

Prérequis

• Un portefeuille EVM sur Base contrôlé par l’agent (clé privée dans une variable d’environnement ou un gestionnaire de secrets).
• Une petite quantité d’ETH sur Base pour les frais de gas (le staking est constitué de deux transactions : approve puis stake).
• Une quantité non nulle de VVV à staker. L’endpoint de création requiert seulement que le portefeuille ait un solde sVVV non nul, donc 1 VVV suffit pour générer une clé. Voir Payer pour l’inférence pour ce dont vous avez réellement besoin pour appeler les endpoints payants.

Utilisez un portefeuille agent dédié plutôt qu’un portefeuille de trésorerie. La clé privée du portefeuille signe chaque challenge Venice, son rayon d’impact doit donc être limité.

​

Étapes

1. Acquérir du VVV

   Envoyez du VVV au portefeuille de l’agent, ou faites en sorte que l’agent le swap sur un DEX comme Aerodrome ou Uniswap.

   Contrat du token VVV sur Base : 0xacfE6019Ed1A7Dc6f7B508C02d1b04ec88cC21bf

2. Staker du VVV avec Venice

   Stakez le VVV dans le Smart Contract de Staking Venice à l’adresse 0x321b7ff75154472B18EDb199033fF4D116F340Ff. Il s’agit de deux transactions :

   1. approve(spender, amount) sur le token VVV, où spender est le contrat de staking.
   2. stake(amount) sur le contrat de staking.

   

   Lorsque la deuxième transaction est confirmée, le solde VVV du portefeuille diminue et son solde sVVV augmente du même montant. L’endpoint de création lit le solde sVVV pour confirmer que le portefeuille est staké.

3. Demander un challenge pour le portefeuille

   Appelez GET /api/v1/api_keys/generate_web3_key?address=<wallet address> pour obtenir un challenge EIP-4361 (Sign-In with Ethereum) à courte durée de vie. L’endpoint n’est pas authentifié, mais le challenge est lié à l’adresse transmise et ne peut être utilisé que par ce portefeuille.

   curl --request GET \
     --url 'https://api.venice.ai/api/v1/api_keys/generate_web3_key?address=<wallet address>'
   

   La réponse contient message, nonce et expiresAt :

   {
     "data": {
       "message": "api.venice.ai wants you to sign in with your Ethereum account:\n0x...\n\nAuthorize Venice API key creation. Only sign this on venice.ai — anyone holding this signature can create an API key on your Venice account.\n\nURI: https://api.venice.ai/api/v1/api_keys/generate_web3_key\nVersion: 1\nChain ID: 8453\nNonce: 9f2c1d6b4a8e05337c1b9d2e6f4a7c81\nIssued At: 2026-06-30T11:02:41.167Z\nExpiration Time: 2026-06-30T11:17:41.167Z\nResources:\n- urn:venice:api-key:create",
       "nonce": "9f2c1d6b4a8e05337c1b9d2e6f4a7c81",
       "expiresAt": "2026-06-30T11:17:41.167Z"
     },
     "success": true
   }
   

   Le challenge expire 15 minutes après son émission et est à usage unique : il est consommé à la première clé créée avec lui. Demandez-en un nouveau pour chaque clé.

4. Signer le challenge avec le portefeuille de staking

   Signez la chaîne message telle quelle avec le portefeuille qui détient le VVV staké. Il s’agit d’un personal_sign standard. À la fois ethers.Wallet.signMessage(message) et account.signMessage({ message }) de viem produisent la signature correcte.

   Ne reformatez pas, ne recoupez pas et ne régénérez pas le message. Venice vérifie la signature sur les octets exacts qu’il a émis et revérifie indépendamment le domain, l’URI, le Chain ID, la déclaration et l’adresse qu’il contient.

5. Créer la clé API

   Faites un POST de l’adresse, de la signature et du message au même endpoint, avec le type de clé que vous souhaitez.

   curl --request POST \
     --url https://api.venice.ai/api/v1/api_keys/generate_web3_key \
     --header 'Content-Type: application/json' \
     --data '{
       "address": "<wallet address>",
       "signature": "<signature of the challenge message>",
       "message": "<the unmodified challenge message>",
       "apiKeyType": "INFERENCE",
       "description": "Agent key minted on <date>"
     }'
   

   Champs requis : address, signature, message, apiKeyType (INFERENCE ou ADMIN).

   Champs optionnels : description, expiresAt, consumptionLimit (plafonne la dépense totale sur cette clé, libellée en usd, vcu ou diem).

   En cas de succès, la réponse contient la chaîne apiKey créée. Stockez-la dans le secret store de l’agent et utilisez-la comme un token Bearer normal (Authorization: Bearer <key>).

​

Exemple de bout en bout

L’exemple ci-dessous utilise un vrai portefeuille depuis une variable d’environnement plutôt qu’un portefeuille généré aléatoirement. Un portefeuille aléatoire n’a pas de VVV staké et la création sera rejetée avec l’erreur Wallet has no staked VVV on Base.

import { ethers } from "ethers"

const wallet = new ethers.Wallet(process.env.WALLET_PRIVATE_KEY!)
const address = wallet.address

const challengeResponse = await fetch(
  `https://api.venice.ai/api/v1/api_keys/generate_web3_key?address=${address}`,
)
const { data: { message } } = await challengeResponse.json()

const signature = await wallet.signMessage(message)

const mintResponse = await fetch("https://api.venice.ai/api/v1/api_keys/generate_web3_key", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    address,
    signature,
    message,
    apiKeyType: "INFERENCE",
    description: "Agent key",
  }),
})

const result = await mintResponse.json()
if (!mintResponse.ok) {
  throw new Error(`Mint failed: ${result.error}`)
}

console.log("Minted key:", result.data.apiKey)

​

Référence des erreurs

L’endpoint renvoie des messages d’erreur spécifiques et exploitables. Mappez-les dans l’agent pour qu’il puisse décider de réessayer, demander un nouveau challenge ou s’arrêter.

Statut	Le message d’erreur contient	Ce que cela signifie	Que faire
400	Invalid wallet address	Le champ address n’est pas une adresse EVM valide.	Corrigez l’adresse et resoumettez.
400	The challenge has expired	Le challenge a expiré avant que vous ne le signiez et le soumettiez.	Demandez un nouveau challenge, signez-le et soumettez-le immédiatement.
400	This challenge has already been used	Le challenge a déjà été utilisé. Chacun ne crée au plus qu’une clé.	Demandez un nouveau challenge pour chaque clé créée.
400	issued for a different wallet address	L’address soumise n’est pas celle pour laquelle le challenge a été émis.	Demandez un challenge avec ?address= défini sur le portefeuille signataire.
400	not a valid Venice API key authorization challenge	Le message n’est pas un challenge Venice, ou il a été modifié.	Envoyez exactement la chaîne message renvoyée par l’endpoint GET.
400	The challenge statement was modified	La ligne de déclaration a été altérée après l’émission.	Signez le message tel quel.
400	The challenge domain must be "api.venice.ai"	La ligne domain a été altérée.	Signez le message tel quel.
400	Wallet signature does not match	La signature ne correspond pas à l’address pour le message donné.	Signez le message exact avec le portefeuille qui possède address.
400	Could not verify wallet signature	L’appel RPC pour vérifier la signature a échoué (transitoire).	Réessayez avec backoff.
400	Wallet has no staked VVV on Base	Le portefeuille a un solde sVVV nul.	Stakez d’abord du VVV, puis réessayez.

​

Pourquoi le challenge est lié au portefeuille et à usage unique

Le challenge est un message EIP-4361 lisible par un humain plutôt qu’un token opaque, et il apporte trois protections qui comptent si un portefeuille est un jour invité à en signer un en dehors de votre propre agent :

• Liaison à l’adresse. Le challenge nomme le portefeuille pour lequel il a été émis. Un challenge obtenu par une partie ne peut pas être signé ni utilisé par un autre portefeuille.
• Nonce à usage unique. Venice suit le nonce côté serveur et le consomme à la première création réussie. Une signature ne crée qu’une seule clé, une signature interceptée ne peut donc pas être rejouée pour en obtenir d’autres.
• Déclaration lisible. Le message indique clairement que signer autorise la création d’une clé API Venice, si bien qu’une interface de portefeuille comme MetaMask montre au signataire ce qu’il approuve au lieu d’un blob binaire.

Considérez une signature sur ce message comme équivalente à céder les droits de création de clés API sur votre compte Venice. Ne signez que des challenges dont la ligne domain indique api.venice.ai et dont la déclaration mentionne la création d’une clé API Venice. Une clé ADMIN peut créer et supprimer d’autres clés et dépenser vos soldes DIEM, crédits inclus et USD.

​

Payer pour l’inférence

Générer une clé et pouvoir appeler des endpoints payants avec elle sont deux choses distinctes. Une clé fraîchement créée s’authentifie correctement mais ne peut pas appeler les endpoints payants (comme /chat/completions) tant que le compte du portefeuille n’a pas un solde dépensable.

La clé créée peut dépenser depuis le compte utilisateur dans cet ordre de priorité : DIEM, puis crédits groupés, puis USD.

Source de financement	Autonome ?	Comment
DIEM depuis le staking VVV	Oui	L’allocation quotidienne de DIEM du portefeuille est proportionnelle à sa part dans le pool de staking. Le compte a besoin d’au moins 0,1 DIEM staké pour que tout DIEM soit dépensable. Les enjeux plus importants rapportent proportionnellement plus de DIEM quotidiens, rafraîchis à chaque epoch (00:00 UTC).
USD via Stripe	Non (navigateur)	Connectez-vous à venice.ai avec le même portefeuille (Sign-In-With-Ethereum). Le tableau de bord trouve l’enregistrement utilisateur existant. Ajoutez des crédits dans Settings, API.
Abonnement crypto Coinbase	Non (navigateur)	Même connexion par portefeuille, puis abonnez-vous via le tableau de bord. Le flux redirige vers Coinbase Commerce pour le paiement effectif, il ne peut donc pas être piloté depuis un script.
Onramp Coinbase	Non (navigateur)	Même connexion par portefeuille, puis utilisez le widget onramp dans le tableau de bord. Hébergé sur l’UI de Coinbase.

Si l’agent a besoin d’un chemin de financement entièrement crypto-natif et headless, les options les plus propres sont :

1. Staker plus de VVV pour que l’allocation quotidienne de DIEM couvre la dépense de l’agent. La clé créée le récupère automatiquement.
2. Utiliser le flux portefeuille x402 au lieu de la clé API. Avec x402, l’agent signe un message Sign-In-With-X par requête, recharge directement avec de l’USDC sur Base ou Solana via POST /api/v1/x402/top-up, et paie par requête. Le solde USDC x402 est lié au portefeuille, pas à l’utilisateur, donc il n’apparaît pas comme solde pour la clé Bearer créée, mais cela permet au même portefeuille de payer l’inférence de manière programmatique.

​

Ressources connexes

Crypto et agents

Utilisez Venice à la fois comme fournisseur de modèle et comme couche RPC blockchain pour les agents autonomes.

Authentification par portefeuille x402

Payez par requête avec de l’USDC sur Base ou Solana, sans clé API requise.

Endpoint de génération de clé API Web3

Référence de l’endpoint pour l’endpoint de création.

Guide de clé API standard

Pour les utilisateurs qui préfèrent générer une clé depuis le tableau de bord.