Creazione autonoma di API key per agenti

​

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 per ciò che ti serve per chiamare effettivamente gli endpoint a pagamento.

​

Passaggi

1

Acquisisci VVV

Invia VVV al wallet dell’agente, o fai eseguire all’agente uno swap su un DEX come Aerodrome o Uniswap.Contratto del token VVV su Base: 0xacfE6019Ed1A7Dc6f7B508C02d1b04ec88cC21bf

2

Effettua lo staking di VVV con Venice

Esegui lo staking dei VVV nello smart contract di staking Venice 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.

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.

3

Richiedi una challenge per il wallet

Chiama GET /api/v1/api_keys/generate_web3_key?address=<wallet address> per ottenere una challenge 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.

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

La risposta contiene message, nonce e 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
}

La challenge scade 15 minuti dopo l’emissione ed è monouso: viene consumata alla prima chiave creata con essa. Richiedine una nuova per ogni chiave.

4

Firma la challenge con il wallet di staking

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.

5

Genera l'API key

Esegui POST con address, signature e message allo stesso endpoint, insieme al tipo di chiave che desideri.

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

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 <key>).

​

Esempio end-to-end

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

​

Perché la challenge è vincolata al wallet e monouso

• 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.

​

Pagare l’inferenza

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 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