> ## Documentation Index > Fetch the complete documentation index at: https://veniceai-docs-web3-key-siwe-challenge.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Creazione autonoma di API key per agenti > Crea una chiave API Venice in modo autonomo da un agente AI mettendo in staking VVV su Base e firmando una challenge SIWE con un wallet. Un agente AI che controlla un wallet su Base può generare la propria API key Venice senza intervento umano. L'agente acquisisce VVV, ne effettua lo staking, richiede una challenge a breve durata vincolata all'indirizzo del proprio wallet, la firma e la invia per ricevere una nuova API key associata al wallet di staking. Questa guida illustra l'intero flusso end-to-end e copre le opzioni di finanziamento per pagare effettivamente l'inferenza una volta generata la chiave. ## Prerequisiti * Un wallet EVM su Base controllato dall'agente (chiave privata in una variabile d'ambiente o in un secret manager). * Una piccola quantità di ETH su Base per il gas (lo staking richiede due transazioni: `approve` poi `stake`). * Qualsiasi quantità non zero di VVV in staking. L'endpoint di minting richiede solo che il wallet abbia un saldo sVVV non zero, quindi 1 VVV è sufficiente per generare una chiave. Consulta [Pagare l'inferenza](#paying-for-inference) per ciò che ti serve per chiamare effettivamente gli endpoint a pagamento. Usa un wallet dedicato per l'agente piuttosto che un wallet di tesoreria. La chiave privata del wallet firma ogni challenge Venice, quindi il suo blast radius dovrebbe essere piccolo. ## Passaggi Invia VVV al wallet dell'agente, o fai eseguire all'agente uno swap su un DEX come [Aerodrome](https://aerodrome.finance/swap?from=eth\&to=0xacfe6019ed1a7dc6f7b508c02d1b04ec88cc21bf\&chain0=8453\&chain1=8453) o [Uniswap](https://app.uniswap.org/swap?chain=base\&inputCurrency=NATIVE\&outputCurrency=0xacfe6019ed1a7dc6f7b508c02d1b04ec88cc21bf). Contratto del token VVV su Base: `0xacfE6019Ed1A7Dc6f7B508C02d1b04ec88cC21bf` Esegui lo staking dei VVV nello [smart contract di staking Venice](https://basescan.org/address/0x321b7ff75154472b18edb199033ff4d116f340ff#code) all'indirizzo `0x321b7ff75154472B18EDb199033fF4D116F340Ff`. Sono due transazioni: 1. `approve(spender, amount)` sul token VVV, dove `spender` è il contratto di staking. 2. `stake(amount)` sul contratto di staking. Smart Contract Staking Quando la seconda transazione viene confermata, il saldo VVV del wallet diminuisce e il suo saldo sVVV aumenta della stessa quantità. L'endpoint di minting legge il saldo sVVV per confermare che il wallet ha effettuato lo staking. Chiama `GET /api/v1/api_keys/generate_web3_key?address=` per ottenere una challenge [EIP-4361](https://eips.ethereum.org/EIPS/eip-4361) (Sign-In with Ethereum) a breve durata. L'endpoint non è autenticato, ma la challenge è vincolata all'indirizzo che passi e può essere riscattata solo da quel wallet. ```bash theme={null} curl --request GET \ --url 'https://api.venice.ai/api/v1/api_keys/generate_web3_key?address=' ``` La risposta contiene `message`, `nonce` e `expiresAt`: ```json theme={null} { "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 } ``` La challenge scade 15 minuti dopo l'emissione ed è **monouso**: viene consumata alla prima chiave creata con essa. Richiedine una nuova per ogni chiave. Firma la stringa `message` così com'è con il wallet che detiene i VVV in staking. Si tratta di un `personal_sign` standard. Sia `ethers.Wallet.signMessage(message)` sia `account.signMessage({ message })` di `viem` producono la firma corretta. Non riformattare, non riavvolgere e non rigenerare il messaggio. Venice verifica la firma sui byte esatti che ha emesso e ricontrolla in modo indipendente `domain`, `URI`, `Chain ID`, dichiarazione e indirizzo al suo interno. Esegui `POST` con address, signature e message allo stesso endpoint, insieme al tipo di chiave che desideri. ```bash theme={null} curl --request POST \ --url https://api.venice.ai/api/v1/api_keys/generate_web3_key \ --header 'Content-Type: application/json' \ --data '{ "address": "", "signature": "", "message": "", "apiKeyType": "INFERENCE", "description": "Agent key minted on " }' ``` Campi obbligatori: `address`, `signature`, `message`, `apiKeyType` (`INFERENCE` o `ADMIN`). Campi opzionali: `description`, `expiresAt`, `consumptionLimit` (limita la spesa totale su questa chiave, in `usd`, `vcu` o `diem`). In caso di successo, la risposta contiene la stringa `apiKey` generata. Conservala nel secret store dell'agente e usala come un normale Bearer token (`Authorization: Bearer `). ## Esempio end-to-end L'esempio qui sotto usa un wallet reale da una variabile d'ambiente piuttosto che uno generato casualmente. Un wallet casuale non ha VVV in staking e il minting verrà rifiutato con l'errore `Wallet has no staked VVV on Base`. ```typescript theme={null} 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) ``` ## Riferimento errori L'endpoint restituisce messaggi di errore specifici e azionabili. Mappali nell'agente in modo che possa decidere se ritentare, richiedere una nuova challenge o fermarsi. | Stato | Il messaggio di errore contiene | Significato | Cosa fare | | ----- | ---------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | `400` | `Invalid wallet address` | Il campo `address` non è un indirizzo EVM valido. | Correggi l'indirizzo e reinvia. | | `400` | `The challenge has expired` | La challenge è scaduta prima che tu la firmassi e la inviassi. | Richiedi una nuova challenge, firmala e inviala immediatamente. | | `400` | `This challenge has already been used` | La challenge è già stata riscattata. Ognuna genera al massimo una chiave. | Richiedi una nuova challenge per ogni chiave che generi. | | `400` | `issued for a different wallet address` | L'`address` inviato non è l'indirizzo per cui la challenge è stata emessa. | Richiedi una challenge con `?address=` impostato sul wallet che firmerà. | | `400` | `not a valid Venice API key authorization challenge` | Il `message` non è una challenge Venice, oppure è stato modificato. | Invia la stringa `message` esatta restituita dall'endpoint `GET`. | | `400` | `The challenge statement was modified` | La riga della dichiarazione è stata alterata dopo l'emissione. | Firma il messaggio così com'è. | | `400` | `The challenge domain must be "api.venice.ai"` | La riga `domain` è stata alterata. | Firma il messaggio così com'è. | | `400` | `Wallet signature does not match` | La `signature` non corrisponde all'`address` per il `message` fornito. | Firma il messaggio esatto con il wallet che possiede `address`. | | `400` | `Could not verify wallet signature` | La chiamata RPC per verificare la firma è fallita (transitoria). | Ritenta con backoff. | | `400` | `Wallet has no staked VVV on Base` | Il wallet ha saldo sVVV pari a zero. | Effettua prima lo staking di VVV, poi ritenta. | ## Perché la challenge è vincolata al wallet e monouso La challenge è un messaggio EIP-4361 leggibile da una persona anziché un token opaco, e offre tre protezioni che contano se a un wallet viene mai chiesto di firmarne una al di fuori del tuo agente: * **Vincolo all'indirizzo.** La challenge indica il wallet per cui è stata emessa. Una challenge ottenuta da una parte non può essere firmata e riscattata da un wallet diverso. * **Nonce monouso.** Venice traccia il nonce lato server e lo consuma alla prima generazione riuscita. Una firma genera esattamente una chiave, quindi una firma intercettata non può essere riutilizzata per ottenerne altre. * **Dichiarazione leggibile.** Il messaggio afferma chiaramente che firmare autorizza la creazione di una API key Venice, così un'interfaccia wallet come MetaMask mostra al firmatario ciò che sta approvando invece di un blob binario. Considera una firma su questo messaggio equivalente a cedere i diritti di creazione delle API key sul tuo account Venice. Firma solo challenge la cui riga `domain` riporta `api.venice.ai` e la cui dichiarazione nomina la creazione di una API key Venice. Una chiave `ADMIN` può creare ed eliminare altre chiavi e spendere dai tuoi saldi DIEM, crediti inclusi e USD. ## Pagare l'inferenza Generare una chiave e poter chiamare gli endpoint a pagamento con essa sono due cose distinte. Una chiave appena generata si autentica correttamente ma non può chiamare gli endpoint a pagamento (come `/chat/completions`) finché l'account del wallet non ha un saldo spendibile. La chiave generata può spendere dall'account utente in questo ordine di priorità: DIEM, poi crediti in bundle, poi USD. | Fonte di finanziamento | Autonoma? | Come | | ------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **DIEM dallo staking VVV** | Sì | L'allocazione giornaliera di DIEM del wallet è proporzionale alla sua quota nel pool di staking. L'account ha bisogno di almeno 0,1 DIEM in staking perché qualsiasi DIEM sia spendibile. Stake maggiori guadagnano proporzionalmente più DIEM giornalieri, aggiornati ogni epoca (00:00 UTC). | | **USD via Stripe** | No (browser) | Accedi a venice.ai con lo stesso wallet (Sign-In-With-Ethereum). La dashboard trova il record utente esistente. Aggiungi crediti in Settings, API. | | **Abbonamento crypto Coinbase** | No (browser) | Stesso sign-in con il wallet, poi sottoscrivi tramite la dashboard. Il flusso reindirizza a Coinbase Commerce per il pagamento effettivo, quindi non può essere guidato da uno script. | | **Onramp Coinbase** | No (browser) | Stesso sign-in con il wallet, poi usa il widget di onramp nella dashboard. Ospitato sulla UI di Coinbase. | Se l'agente ha bisogno di un percorso di finanziamento completamente crypto-native e headless, le opzioni più pulite sono: 1. **Effettuare lo staking di più VVV** in modo che l'allocazione giornaliera di DIEM copra la spesa dell'agente. La chiave generata lo riconosce automaticamente. 2. **Usare il [flusso wallet x402](/guides/integrations/x402-venice-api) al posto dell'API key.** Con x402 l'agente firma un messaggio Sign-In-With-X per richiesta, ricarica direttamente con USDC su Base o Solana tramite `POST /api/v1/x402/top-up` e paga per richiesta. Il saldo USDC x402 è legato al wallet, non all'utente, quindi non appare come saldo per la Bearer key generata, ma consente allo stesso wallet di pagare l'inferenza in modo programmatico. ## Risorse correlate Usa Venice sia come provider di modelli sia come layer RPC blockchain per agenti autonomi. Paga per richiesta con USDC su Base o Solana, senza API key. Riferimento dell'endpoint di minting. Per gli utenti che preferiscono generare una chiave dalla dashboard.