> ## Documentation Index > Fetch the complete documentation index at: https://veniceai-docs-revamp.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Crypto RPC per agenti > Fornisci al tuo agente AI inferenza e accesso on-chain tramite una sola credenziale Venice Venice fornisce al tuo agente sia l'inferenza (oltre 230 modelli) sia l'accesso blockchain (10 chain EVM più Starknet) tramite una sola credenziale. Il tuo agente può pensare, firmare e inviare transazioni senza dover gestire account separati per provider di inferenza e RPC. Una sola API key (o wallet) sia per l'inferenza LLM sia per le chiamate JSON-RPC. Ethereum, Base, Arbitrum, Optimism, Polygon, Linea, Avalanche, BSC, Blast, zkSync Era e Starknet (mainnet più testnet). Fai staking di VVV su Base per guadagnare DIEM giornalieri, l'unico percorso di finanziamento completamente headless per una API key generata. Ricariche in USD e crypto sono disponibili anche tramite dashboard. Gli agenti possono autenticarsi con una firma del wallet e pagare in USDC su Base o Solana. ## Perché Venice per agenti on-chain? | Capacità | Cosa ottiene il tuo agente | | ------------------ | ------------------------------------------------------------------------------------------------------------------ | | **Inferenza** | Oltre 230 modelli di testo, immagini, video, audio ed embedding tramite un singolo endpoint compatibile con OpenAI | | **Crypto RPC** | Proxy JSON-RPC 2.0 verso 10 chain EVM più Starknet (mainnet e testnet) | | **Autenticazione** | API key standard o autenticazione wallet x402 (nessun account Venice richiesto) | | **Finanziamento** | Autonomo: staking VVV per DIEM giornalieri. Browser: ricariche USD o crypto tramite dashboard | | **Batching** | Fino a 100 chiamate JSON-RPC per richiesta, multi-chain in parallelo | | **Idempotenza** | Retry sicuri con l'header `Idempotency-Key` | ## Autenticazione Scegli il metodo di autenticazione che corrisponde al modo in cui viene eseguito il tuo agente. | Metodo | Ideale per | Come funziona | | --------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **API key** | Agenti server-side, deployment fissi | Header `Authorization: Bearer `. Ottieni una chiave su [venice.ai/settings/api](https://venice.ai/settings/api). | | **Wallet x402** | Agenti autonomi, crypto-native o effimeri | Il wallet firma un messaggio Sign-In-With-X, paga per richiesta in USDC su Base o Solana. Nessun account Venice necessario. Consulta la [guida x402](/guides/integrations/x402-venice-api). | Entrambi i metodi condividono gli stessi rate limit e la stessa fatturazione in crediti Venice. Gli agenti veramente autonomi possono generare la propria API key facendo staking di VVV su Base. Consulta [Creazione autonoma di API key per agenti](/guides/getting-started/generating-api-key-agent). ## Avvio rapido Crypto RPC Invia qualsiasi metodo JSON-RPC 2.0 a `POST /crypto/rpc/{network}`. ```bash theme={"dark"} curl https://api.venice.ai/api/v1/crypto/rpc/ethereum-mainnet \ -H "Authorization: Bearer $VENICE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "eth_chainId", "params": [], "id": 1 }' ``` Risposta: ```json theme={"dark"} { "jsonrpc": "2.0", "id": 1, "result": "0x1" } ``` Gli header di risposta includono `X-Venice-RPC-Credits` (crediti addebitati), `X-Venice-RPC-Cost-USD` (costo in dollari) e `X-Request-ID` (ID di correlazione). ### Reti supportate | Famiglia | Mainnet | Testnet | | ----------------- | ------------------- | -------------------------------------- | | Ethereum | `ethereum-mainnet` | `ethereum-sepolia`, `ethereum-holesky` | | Base | `base-mainnet` | `base-sepolia` | | Arbitrum | `arbitrum-mainnet` | `arbitrum-sepolia` | | Optimism | `optimism-mainnet` | `optimism-sepolia` | | Polygon | `polygon-mainnet` | `polygon-amoy` | | Linea | `linea-mainnet` | `linea-sepolia` | | Avalanche C-Chain | `avalanche-mainnet` | `avalanche-fuji` | | BNB Smart Chain | `bsc-mainnet` | `bsc-testnet` | | Blast | `blast-mainnet` | `blast-sepolia` | | zkSync Era | `zksync-mainnet` | `zksync-sepolia` | | Starknet | `starknet-mainnet` | `starknet-sepolia` | Usa [`GET /crypto/rpc/networks`](/api-reference/endpoint/crypto/networks) per l'elenco live autorevole. ### Tier dei metodi I metodi sono raggruppati in tre tier di credito. Costo totale = `baseCredits[chain] × methodTier`. | Tier | Moltiplicatore | Esempi | | ------------ | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | **Standard** | 1x | `eth_call`, `eth_getBalance`, `eth_blockNumber`, `eth_sendRawTransaction`, `eth_getLogs`, `eth_getTransactionReceipt`, `eth_estimateGas` | | **Advanced** | 2x | `trace_block`, `trace_call`, `trace_transaction`, `debug_traceCall`, `debug_traceTransaction` | | **Large** | 4x | `trace_replayBlockTransactions`, `trace_replayTransaction`, `txpool_content` | Elenco completo e dettaglio dei prezzi nel [riferimento API Crypto RPC](/api-reference/endpoint/crypto/rpc). ## Ricette per agenti Pattern comuni per agenti AI che hanno bisogno di leggere e scrivere on-chain. ### Leggere il saldo nativo di un wallet ```bash theme={"dark"} curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \ -H "Authorization: Bearer $VENICE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "eth_getBalance", "params": ["0xYourWalletAddress", "latest"], "id": 1 }' ``` ### Leggere il saldo di un token ERC-20 Chiama il selettore `balanceOf(address)` con `eth_call`. Il campo `data` è il selettore di 4 byte (`0x70a08231`) seguito dall'indirizzo del wallet con padding a sinistra a 32 byte. Più facile lasciarlo codificare a una libreria: ```typescript theme={"dark"} import { encodeFunctionData, parseAbi } from 'viem' const data = encodeFunctionData({ abi: parseAbi(['function balanceOf(address) view returns (uint256)']), args: ['0xWalletAddress'], }) const response = await fetch('https://api.venice.ai/api/v1/crypto/rpc/base-mainnet', { method: 'POST', headers: { Authorization: `Bearer ${process.env.VENICE_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ jsonrpc: '2.0', method: 'eth_call', params: [{ to: '0xacfE6019Ed1A7Dc6f7B508C02d1b04ec88cC21bf', data }, 'latest'], id: 1, }), }) ``` L'indirizzo del contratto sopra è VVV su Base. Sostituiscilo con qualsiasi contratto ERC-20. ### Inviare una transazione firmata (ciclo di vita completo) Venice non detiene mai le tue chiavi private. L'agente raccoglie i parametri della tx tramite letture RPC, firma localmente con una libreria come [viem](https://viem.sh) o [ethers](https://docs.ethers.org), quindi inoltra l'hex raw tramite Venice. ```bash theme={"dark"} curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \ -H "Authorization: Bearer $VENICE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"eth_getTransactionCount","params":["0xAgentWallet","pending"],"id":1}' ``` Usa `"pending"` in modo che invii consecutivi non si scontrino. ```bash theme={"dark"} curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \ -H "Authorization: Bearer $VENICE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"eth_gasPrice","params":[],"id":1}' ``` Per chain EIP-1559, preferisci `eth_feeHistory` per calcolare `maxFeePerGas` e `maxPriorityFeePerGas`. ```bash theme={"dark"} curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \ -H "Authorization: Bearer $VENICE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"eth_estimateGas","params":[{"from":"0xAgentWallet","to":"0xRecipient","value":"0x0","data":"0x..."}],"id":1}' ``` ```typescript theme={"dark"} import { privateKeyToAccount } from 'viem/accounts' import { base } from 'viem/chains' const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY) const signed = await account.signTransaction({ chainId: base.id, nonce, // dallo step 1 gas, // dallo step 3 maxFeePerGas, // dallo step 2 (fee history) maxPriorityFeePerGas, // dallo step 2 (fee history) to: '0xRecipient', value: 0n, data: '0x...', }) ``` ```bash theme={"dark"} curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \ -H "Authorization: Bearer $VENICE_API_KEY" \ -H "Idempotency-Key: agent-tx-" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"eth_sendRawTransaction","params":["0xSignedHex"],"id":1}' ``` Imposta sempre `Idempotency-Key` sui relay in modo che un'interruzione di rete non possa duplicare il broadcast. ```bash theme={"dark"} curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \ -H "Authorization: Bearer $VENICE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["0xTxHash"],"id":1}' ``` Esegui polling ogni pochi secondi finché `result` non è non-null. Controlla `result.status` (`"0x1"` = successo). Ogni chiamata a `eth_sendRawTransaction` viene loggata lato server con l'hash della tx, la rete, l'ID di richiesta e l'ID utente chiamante. Il payload firmato in sé non viene conservato. Questo audit trail esiste in modo che chiavi compromesse usate per relay illeciti possano essere ricondotte all'account responsabile. ### Batch di più chiamate (controllo portfolio multi-chain) Invia fino a 100 oggetti JSON-RPC in una sola richiesta. Ognuno viene validato e fatturato indipendentemente. ```bash theme={"dark"} curl https://api.venice.ai/api/v1/crypto/rpc/ethereum-mainnet \ -H "Authorization: Bearer $VENICE_API_KEY" \ -H "Content-Type: application/json" \ -d '[ { "jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1 }, { "jsonrpc": "2.0", "method": "eth_getBalance", "params": ["0xWallet", "latest"], "id": 2 }, { "jsonrpc": "2.0", "method": "eth_gasPrice", "params": [], "id": 3 } ]' ``` Per letture multi-chain (una chiamata per chain), emetti richieste parallele a endpoint `{network}` diversi. ### Retry sicuri con idempotenza Imposta l'header `Idempotency-Key` su qualsiasi stringa che corrisponda a `[A-Za-z0-9_-]{1,255}`. Venice memorizza la risposta in cache per 24 ore con chiave `(user, key)`. I replay restituiscono il risultato memorizzato con `Idempotent-Replayed: true` e non addebitano nulla. ```bash theme={"dark"} curl https://api.venice.ai/api/v1/crypto/rpc/base-mainnet \ -H "Authorization: Bearer $VENICE_API_KEY" \ -H "Idempotency-Key: agent-tx-2026-04-21-001" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "eth_sendRawTransaction", "params": ["0xSignedRawTxHex"], "id": 1 }' ``` Questo è critico per i relay di transazioni dove un'interruzione di rete potrebbe altrimenti far sì che il tuo agente faccia broadcast della stessa tx due volte. ## Finanziare l'API key dell'agente Una volta che l'agente ha una API key Venice, ha bisogno di un saldo spendibile sull'account sottostante prima che gli endpoint a pagamento accettino la chiave. Ci sono due modi per metterci un saldo: | Percorso | Autonomo? | Come funziona | | ------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **DIEM da staking VVV** | Sì | Fai staking di VVV nello [smart contract di staking Venice](https://basescan.org/address/0x321b7ff75154472B18EDb199033fF4D116F340Ff#code) su Base. L'allocazione giornaliera di DIEM del wallet è proporzionale alla sua quota nel pool di staking. L'account ha bisogno di almeno 0,1 DIEM accumulati prima che qualsiasi DIEM sia spendibile. I DIEM si aggiornano alle 00:00 UTC. Per aumentare la spesa giornaliera, fai più staking di VVV. | | **Ricarica USD o crypto tramite dashboard** | No (browser) | Accedi a [venice.ai](https://venice.ai) con lo stesso wallet (Sign-In-With-Ethereum), quindi aggiungi crediti in Settings, API. Sia Stripe (carta) sia Coinbase (crypto) sono dietro quella pagina e richiedono un browser. I crediti non scadono mai. | Per un agente che gira senza supervisione, **DIEM via staking VVV è oggi l'unico percorso di finanziamento completamente headless per una API key generata**. Se la spesa giornaliera dell'agente supera la sua allocazione di DIEM, le opzioni realistiche sono: fare più staking di VVV o far accedere un operatore per ricaricare in USD o crypto. ### Staking VVV autonomo e generazione di chiave Un agente veramente autonomo può gestire il proprio wallet VVV su Base, farne staking e generare la propria API key Venice senza intervento umano. Il flusso completo: Invia VVV al wallet dell'agente (o fagli fare swap su [Aerodrome](https://aerodrome.finance) o [Uniswap](https://app.uniswap.org)), più una piccola quantità di ETH su Base per le due transazioni di staking. `approve` del contratto di staking sul token VVV, poi `stake(amount)` su `0x321b7ff75154472B18EDb199033fF4D116F340Ff`. Il saldo sVVV del wallet si aggiorna atomicamente con lo stake. `GET /api/v1/api_keys/generate_web3_key` restituisce un JWT che scade 15 minuti dopo l'emissione. Firma il token raw con il wallet in staking, poi fai `POST` con address, firma e token. Venice restituisce una API key associata all'account utente derivato da quel wallet. Il minting richiede solo un saldo sVVV non zero, quindi 1 VVV in staking è sufficiente per ricevere una chiave. **Spendere** con la chiave è una questione separata, governata dalla tabella di finanziamento sopra. Consulta [Creazione autonoma di API key per agenti](/guides/getting-started/generating-api-key-agent) per il walkthrough completo con codice e riferimento errori completo. ## Wallet auth x402 in 30 secondi Se il tuo agente ha già un wallet Base o Solana, salta del tutto l'API key. L'SDK [`venice-x402-client`](https://github.com/veniceai/x402-client) gestisce la firma Sign-In-With-X, le ricariche e il tracking del saldo. ```bash theme={"dark"} npm install venice-x402-client ``` ```typescript theme={"dark"} import { VeniceClient } from 'venice-x402-client' const venice = new VeniceClient(process.env.WALLET_KEY) await venice.topUp(10) // salta se il wallet ha già saldo const response = await venice.chat({ model: 'kimi-k2-6', messages: [{ role: 'user', content: 'What is the latest block on Base?' }] }) ``` La stessa wallet auth funziona contro `/crypto/rpc/{network}` per letture e scritture blockchain. Dettagli completi del protocollo nella [guida x402](/guides/integrations/x402-venice-api). ## Prezzi Crypto RPC è fatturato in crediti Venice. Ogni risposta include `X-Venice-RPC-Credits` (crediti addebitati) e `X-Venice-RPC-Cost-USD` (costo in dollari) in modo che il tuo agente possa tracciare la spesa per richiesta. ### Crediti base per chain | Crediti base | Chain | | ------------ | ----------------------------------------------------------------------------------- | | **20** | Ethereum, Base, Optimism, Arbitrum, Polygon, Linea, Avalanche, BSC, Blast, Starknet | | **30** | zkSync Era | ### Esempi di costo Prezzi osservati per i tier di metodi standard, advanced e large: | Chiamata | Crediti | Costo USD | | ----------------------------------------------- | ------- | ------------- | | `eth_call` su Ethereum (20 × 1x) | 20 | \~\$0,0000140 | | `trace_transaction` su Ethereum (20 × 2x) | 40 | \~\$0,0000280 | | `trace_replayTransaction` su Ethereum (20 × 4x) | 80 | \~\$0,0000560 | | `eth_call` su zkSync (30 × 1x) | 30 | \~\$0,0000210 | Affidati sempre all'header di risposta `X-Venice-RPC-Cost-USD` per il costo autorevole. Gli elementi in errore nelle richieste batch sono fatturati a 5 crediti ciascuno. ### Rate limit | Tier | Richieste al minuto | | -------- | ------------------- | | Standard | 100 | | Staff | 1.000 | Quando superati, l'endpoint restituisce `429` con gli header di risposta standard `X-RateLimit-*`. ## Gestione degli errori Risposte HTTP comuni che il tuo agente dovrebbe gestire: | Stato | Significato | Cosa fare | | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | Metodo JSON-RPC non supportato o non mappato, o batch malformato | Verifica il metodo contro l'[allowlist](/api-reference/endpoint/crypto/rpc). Il corpo dell'errore nomina il metodo offensivo. | | `400` | Replay di un `Idempotency-Key` con body diverso | Usa una chiave nuova per richieste distinte. | | `402` | Nessun header di auth (il body della risposta include `authOptions` che elenca entrambi i percorsi di auth supportati), o crediti esauriti con un header di auth valido | Se no auth: allega l'header `Authorization: Bearer ...` o l'header `X-Sign-In-With-X` x402. Se crediti esauriti: con una Bearer key, finanzia l'account (DIEM, USD o ricarica dashboard); con auth x402, chiama `POST /api/v1/x402/top-up` direttamente. | | `429` | Rate limit raggiunto (100 req/min standard, 1.000 req/min staff) | Rispetta `X-RateLimit-Reset` e fai backoff. Esegui batch fino a 100 chiamate per richiesta per ammortizzare il limite. | | `5xx` | Singhiozzo del nodo RPC upstream | Ritenta con lo stesso `Idempotency-Key` per evitare doppi addebiti. | Gli errori per elemento batch (es. parametri non validi su una delle N chiamate) tornano all'interno di una risposta `200 OK` con un campo `error` JSON-RPC sull'elemento offensivo. Quegli elementi sono fatturati a 5 crediti ciascuno. ## Non supportati Queste categorie di metodi sono intenzionalmente rifiutate: * **Solo WebSocket** (`eth_subscribe`, `eth_unsubscribe`): il proxy è solo HTTP. Fai polling invece. * **Filter con stato** (`eth_newFilter`, `eth_getFilterChanges`, ecc.): lo stato del filter è fissato a un singolo backend e si interrompe su un proxy con load balancing. Usa invece `eth_getLogs`. * **Metodi che detengono chiavi** (`eth_sign`, `eth_accounts`, `eth_mining`): i provider ospitati non detengono le chiavi degli utenti. Firma lato client e invia tramite `eth_sendRawTransaction`. * **Metodi non mappati**: tutto ciò che non è in allowlist restituisce `400`. Contatta il supporto per richiedere aggiunte. ## Risorse Elenco completo dei metodi, prezzi e header di risposta Elenco live degli slug delle reti supportate Autenticati e paga con un wallet Base o Solana Genera la tua chiave facendo staking di VVV 27 esempi Crypto RPC pronti all'uso DIEM, prezzi dei crediti e opzioni di pagamento