Autonome Agenten-API-Schlüssel-Erstellung

Ein On-Chain-KI-Agent prägt autonom einen Venice-API-Schlüssel — durch VVV-Staking auf Base und Wallet-Signatur einer Venice-SIWE-Challenge.

Ein KI-Agent, der eine Wallet auf Base kontrolliert, kann seinen eigenen Venice-API-Schlüssel ohne menschliches Zutun erstellen. Der Agent erwirbt VVV, staked es, fordert eine kurzlebige, an seine Wallet-Adresse gebundene Challenge an, signiert diese und sendet sie zurück, um einen frischen API-Schlüssel zu erhalten, der an die Staking-Wallet gebunden ist.

Dieser Leitfaden führt Sie End-to-End durch den gesamten Ablauf und behandelt die Finanzierungsoptionen, mit denen Sie nach der Schlüsselerstellung tatsächlich für Inferenz bezahlen können.

​

Voraussetzungen

• Eine EVM-Wallet auf Base, die vom Agenten kontrolliert wird (Private Key in einer Umgebungsvariablen oder einem Secret Manager).
• Ein kleiner Betrag ETH auf Base für Gas (Staking sind zwei Transaktionen: approve und dann stake).
• Ein beliebiger Nicht-Null-Betrag VVV zum Staken. Der Mint-Endpoint erfordert lediglich, dass die Wallet ein Nicht-Null-sVVV-Guthaben hat, sodass 1 VVV ausreicht, um einen Schlüssel zu erstellen. Siehe Bezahlung für Inferenz für die Voraussetzungen, um bezahlte Endpoints tatsächlich aufzurufen.

Verwenden Sie eine dedizierte Agenten-Wallet statt einer Treasury-Wallet. Der Private Key der Wallet signiert jede Venice-Challenge, daher sollte der Schaden im Falle einer Kompromittierung möglichst gering sein.

​

Schritte

1. VVV erwerben

   Senden Sie VVV an die Wallet des Agenten oder lassen Sie den Agenten auf einem DEX wie Aerodrome oder Uniswap tauschen.

   VVV-Token-Vertrag auf Base: 0xacfE6019Ed1A7Dc6f7B508C02d1b04ec88cC21bf

2. VVV bei Venice staken

   Staken Sie das VVV im Venice Staking Smart Contract unter 0x321b7ff75154472B18EDb199033fF4D116F340Ff. Das sind zwei Transaktionen:

   1. approve(spender, amount) auf dem VVV-Token, wobei spender der Staking-Contract ist.
   2. stake(amount) auf dem Staking-Contract.

   

   Wenn die zweite Transaktion bestätigt ist, sinkt das VVV-Guthaben der Wallet, und ihr sVVV-Guthaben steigt um denselben Betrag. Der Mint-Endpoint liest das sVVV-Guthaben, um zu bestätigen, dass die Wallet gestaked ist.

3. Eine Challenge für die Wallet anfordern

   Rufen Sie GET /api/v1/api_keys/generate_web3_key?address=<wallet address> auf, um eine kurzlebige EIP-4361-Challenge (Sign-In with Ethereum) zu erhalten. Der Endpoint ist unauthentifiziert, aber die Challenge ist an die übergebene Adresse gebunden und kann nur von dieser Wallet eingelöst werden.

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

   Die Antwort enthält message, nonce und 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
   }
   

   Die Challenge läuft 15 Minuten nach Ausstellung ab und ist einmalig verwendbar — sie wird beim ersten damit erstellten Schlüssel verbraucht. Fordern Sie für jeden Schlüssel eine neue an.

4. Die Challenge mit der Staking-Wallet signieren

   Signieren Sie den message-String unverändert mit der Wallet, die das gestakte VVV hält. Dies ist ein standardmäßiger personal_sign. Sowohl ethers.Wallet.signMessage(message) als auch account.signMessage({ message }) in viem erzeugen die korrekte Signatur.

   Formatieren, umbrechen oder regenerieren Sie die Nachricht nicht. Venice verifiziert die Signatur über exakt die ausgestellten Bytes und prüft domain, URI, Chain ID, Statement und Adresse darin zusätzlich unabhängig.

5. Den API-Schlüssel erstellen

   POSTen Sie die Adresse, die Signatur und die Nachricht zusammen mit dem gewünschten Schlüsseltyp an denselben Endpoint.

   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>"
     }'
   

   Erforderliche Felder: address, signature, message, apiKeyType (INFERENCE oder ADMIN).

   Optionale Felder: description, expiresAt, consumptionLimit (begrenzt die Gesamtausgaben dieses Schlüssels, denominiert in usd, vcu oder diem).

   Bei Erfolg enthält die Antwort den erstellten apiKey-String. Speichern Sie ihn im Secret-Store des Agenten und verwenden Sie ihn als normales Bearer-Token (Authorization: Bearer <key>).

​

End-to-End-Beispiel

Das folgende Beispiel verwendet eine echte Wallet aus einer Umgebungsvariablen statt einer zufällig generierten. Eine zufällige Wallet hat kein gestaktes VVV, und der Mint wird mit dem Fehler Wallet has no staked VVV on Base abgelehnt.

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)

​

Fehlerreferenz

Der Endpoint gibt spezifische, umsetzbare Fehlermeldungen zurück. Mappen Sie diese im Agenten, damit er entscheiden kann, ob er es erneut versucht, eine neue Challenge anfordert oder abbricht.

Status	Fehlermeldung enthält	Bedeutung	Vorgehen
400	Invalid wallet address	Das address-Feld ist keine gültige EVM-Adresse.	Adresse korrigieren und erneut einreichen.
400	The challenge has expired	Die Challenge ist abgelaufen, bevor Sie sie signiert und eingereicht haben.	Neue Challenge anfordern, signieren und sofort einreichen.
400	This challenge has already been used	Die Challenge wurde bereits eingelöst. Jede erstellt höchstens einen Schlüssel.	Fordern Sie für jeden Schlüssel eine neue Challenge an.
400	issued for a different wallet address	Die eingereichte address ist nicht die Adresse, für die die Challenge ausgestellt wurde.	Fordern Sie eine Challenge mit ?address= der signierenden Wallet an.
400	not a valid Venice API key authorization challenge	Die message ist keine Venice-Challenge oder wurde verändert.	Senden Sie den exakten message-String aus dem GET-Endpoint.
400	The challenge statement was modified	Die Statement-Zeile wurde nach der Ausstellung verändert.	Signieren Sie die Nachricht unverändert.
400	The challenge domain must be "api.venice.ai"	Die domain-Zeile wurde verändert.	Signieren Sie die Nachricht unverändert.
400	Wallet signature does not match	Die signature passt nicht zur address für die angegebene message.	Signieren Sie die exakte Nachricht mit der Wallet, die address besitzt.
400	Could not verify wallet signature	Der RPC-Aufruf zur Verifizierung der Signatur ist fehlgeschlagen (transient).	Mit Backoff erneut versuchen.
400	Wallet has no staked VVV on Base	Die Wallet hat ein sVVV-Guthaben von Null.	Zuerst VVV staken, dann erneut versuchen.

​

Warum die Challenge wallet-gebunden und einmalig verwendbar ist

Die Challenge ist eine menschenlesbare EIP-4361-Nachricht statt eines undurchsichtigen Tokens und bietet drei Schutzmechanismen, die relevant werden, falls eine Wallet jemals außerhalb Ihres eigenen Agenten zur Signatur aufgefordert wird:

• Adressbindung. Die Challenge nennt die Wallet, für die sie ausgestellt wurde. Eine von einer Partei erhaltene Challenge kann nicht von einer anderen Wallet signiert und eingelöst werden.
• Einmal-Nonce. Venice verfolgt die Nonce serverseitig und verbraucht sie beim ersten erfolgreichen Erstellen. Eine Signatur erstellt genau einen Schlüssel, eine abgefangene Signatur kann also nicht für weitere Schlüssel wiederverwendet werden.
• Lesbares Statement. Die Nachricht sagt klar, dass die Signatur die Erstellung eines Venice-API-Schlüssels autorisiert, sodass eine Wallet-Oberfläche wie MetaMask dem Signierenden zeigt, was er genehmigt, statt eines Binär-Blobs.

Behandeln Sie eine Signatur über diese Nachricht wie die Übergabe von Rechten zur API-Schlüssel-Erstellung in Ihrem Venice-Konto. Signieren Sie nur Challenges, deren domain-Zeile api.venice.ai lautet und deren Statement die Erstellung eines Venice-API-Schlüssels nennt. Ein ADMIN-Schlüssel kann andere Schlüssel erstellen und löschen sowie von Ihren DIEM-, Bundle-Guthaben- und USD-Beständen ausgeben.

​

Bezahlung für Inferenz

Einen Schlüssel zu erstellen und damit bezahlte Endpoints aufrufen zu können sind zwei verschiedene Dinge. Ein frisch erstellter Schlüssel authentifiziert sich korrekt, kann aber keine bezahlten Endpoints (z. B. /chat/completions) aufrufen, bis das Konto der Wallet ein verfügbares Guthaben hat.

Der erstellte Schlüssel kann vom Benutzerkonto in dieser Prioritätsreihenfolge ausgeben: DIEM, dann gebündelte Credits, dann USD.

Finanzierungsquelle	Autonom?	Wie
DIEM aus VVV-Staking	Ja	Die tägliche DIEM-Zuteilung der Wallet ist proportional zu ihrem Anteil am Staking-Pool. Das Konto benötigt mindestens 0,1 gestakte DIEM, damit überhaupt DIEM ausgegeben werden können. Größere Stakes verdienen proportional mehr tägliches DIEM, das jede Epoche (00:00 UTC) erneuert wird.
USD über Stripe	Nein (Browser)	Melden Sie sich auf venice.ai mit derselben Wallet an (Sign-In-With-Ethereum). Das Dashboard findet den vorhandenen Benutzerdatensatz. Credits unter Settings, API hinzufügen.
Coinbase Crypto Subscription	Nein (Browser)	Gleiche Wallet-Anmeldung, dann über das Dashboard abonnieren. Der Flow leitet für die eigentliche Zahlung zu Coinbase Commerce um, daher kann er nicht aus einem Skript gesteuert werden.
Coinbase Onramp	Nein (Browser)	Gleiche Wallet-Anmeldung, dann das Onramp-Widget im Dashboard verwenden. Wird auf der Coinbase-UI gehostet.

Wenn der Agent einen vollständig krypto-nativen, headless Finanzierungspfad benötigt, sind die saubersten Optionen:

1. Mehr VVV staken, sodass die tägliche DIEM-Zuteilung die Ausgaben des Agenten abdeckt. Der erstellte Schlüssel verwendet dies automatisch.
2. Verwenden Sie den x402-Wallet-Flow anstelle des API-Schlüssels. Bei x402 signiert der Agent pro Anfrage eine Sign-In-With-X-Nachricht, lädt direkt mit USDC auf Base oder Solana über POST /api/v1/x402/top-up auf und bezahlt pro Anfrage. Das x402-USDC-Guthaben ist wallet-gebunden, nicht benutzerbezogen, sodass es nicht als Guthaben für den erstellten Bearer-Schlüssel angezeigt wird, aber es ermöglicht es derselben Wallet, programmatisch für Inferenz zu bezahlen.

​

Verwandte Ressourcen

Krypto und Agenten

Verwenden Sie Venice sowohl als Modellanbieter als auch als Blockchain-RPC-Schicht für autonome Agenten.

x402-Wallet-Authentifizierung

Bezahlen Sie pro Anfrage mit USDC auf Base oder Solana, ohne API-Schlüssel.

Web3 API Key Endpoint generieren

Endpoint-Referenz für den Mint-Endpoint.

Standard-API-Schlüssel-Leitfaden

Für Nutzer, die einen Schlüssel über das Dashboard erstellen möchten.