Criação autônoma de chave de API por agente

Gere uma chave da Venice API de forma autônoma com um agente on-chain: faça stake de VVV na Base e assine um desafio SIWE com a carteira.

Um agente de IA que controla uma carteira na Base pode gerar sua própria chave de API Venice sem nenhum humano no processo. O agente adquire VVV, faz stake, solicita um desafio de curta duração vinculado ao endereço da sua carteira, assina esse desafio e o envia de volta para receber uma nova chave de API vinculada à carteira de stake.

Este guia percorre o fluxo completo de ponta a ponta e cobre as opções de financiamento para efetivamente pagar pela inferência depois que a chave é gerada.

​

Pré-requisitos

• Uma carteira EVM na Base controlada pelo agente (chave privada em uma variável de ambiente ou gerenciador de segredos).
• Uma pequena quantidade de ETH na Base para gás (o staking são duas transações: approve e depois stake).
• Qualquer quantidade diferente de zero de VVV para fazer stake. O endpoint de geração exige apenas que a carteira tenha saldo de sVVV diferente de zero, então 1 VVV é suficiente para gerar uma chave. Veja Pagando pela inferência para saber o que você precisa para realmente chamar endpoints pagos.

Use uma carteira de agente dedicada em vez de uma carteira de tesouraria. A chave privada da carteira assina cada desafio da Venice, portanto seu raio de impacto deve ser pequeno.

​

Passos

1. Adquira VVV

   Envie VVV para a carteira do agente, ou faça com que o agente realize um swap em uma DEX como Aerodrome ou Uniswap.

   Contrato do token VVV na Base: 0xacfE6019Ed1A7Dc6f7B508C02d1b04ec88cC21bf

2. Faça stake de VVV na Venice

   Faça stake do VVV no Smart Contract de Staking da Venice em 0x321b7ff75154472B18EDb199033fF4D116F340Ff. São duas transações:

   1. approve(spender, amount) no token VVV, onde spender é o contrato de staking.
   2. stake(amount) no contrato de staking.

   

   Quando a segunda transação for confirmada, o saldo de VVV da carteira diminui e o saldo de sVVV aumenta na mesma quantia. O endpoint de geração lê o saldo de sVVV para confirmar que a carteira está com stake.

3. Solicite um desafio para a carteira

   Chame GET /api/v1/api_keys/generate_web3_key?address=<wallet address> para obter um desafio EIP-4361 (Sign-In with Ethereum) de curta duração. O endpoint não exige autenticação, mas o desafio fica vinculado ao endereço que você informa e só pode ser resgatado por essa carteira.

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

   A resposta contém 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
   }
   

   O desafio expira 15 minutos após sua emissão e é de uso único — ele é consumido na primeira chave gerada com ele. Solicite um novo para cada chave.

4. Assine o desafio com a carteira de stake

   Assine a string message exatamente como recebida, com a carteira que detém o VVV em stake. Esse é um personal_sign padrão. Tanto ethers.Wallet.signMessage(message) quanto account.signMessage({ message }) do viem produzem a assinatura correta.

   Não reformate, não reajuste as quebras de linha nem regenere a mensagem. A Venice verifica a assinatura sobre os bytes exatos que emitiu e revalida de forma independente o domain, a URI, o Chain ID, a declaração e o endereço contidos nela.

5. Gere a chave de API

   Faça POST com o endereço, a assinatura e a mensagem para o mesmo endpoint, junto com o tipo de chave que você quer.

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

   Campos obrigatórios: address, signature, message, apiKeyType (INFERENCE ou ADMIN).

   Campos opcionais: description, expiresAt, consumptionLimit (limita o gasto total nessa chave, denominado em usd, vcu ou diem).

   Em caso de sucesso, a resposta contém a string apiKey gerada. Armazene-a no cofre de segredos do agente e use-a como um Bearer token normal (Authorization: Bearer <key>).

​

Exemplo de ponta a ponta

O exemplo abaixo usa uma carteira real obtida de uma variável de ambiente, em vez de uma gerada aleatoriamente. Uma carteira aleatória não tem VVV em stake e a geração será rejeitada com o erro 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)

​

Referência de erros

O endpoint retorna mensagens de erro específicas e acionáveis. Mapeie-as no agente para que ele possa decidir se deve tentar novamente, solicitar um novo desafio ou parar.

Status	A mensagem de erro contém	O que significa	O que fazer
400	Invalid wallet address	O campo address não é um endereço EVM válido.	Corrija o endereço e reenvie.
400	The challenge has expired	O desafio expirou antes de você assiná-lo e enviá-lo.	Solicite um novo desafio, assine-o e envie imediatamente.
400	This challenge has already been used	O desafio já foi resgatado. Cada um gera no máximo uma chave.	Solicite um novo desafio para cada chave que você gerar.
400	issued for a different wallet address	O address enviado não é o endereço para o qual o desafio foi emitido.	Solicite um desafio com ?address= definido como a carteira que vai assinar.
400	not a valid Venice API key authorization challenge	O message não é um desafio da Venice, ou foi modificado.	Envie exatamente a string message retornada pelo endpoint GET.
400	The challenge statement was modified	A linha da declaração foi alterada após a emissão.	Assine a mensagem exatamente como recebida.
400	The challenge domain must be "api.venice.ai"	A linha domain foi alterada.	Assine a mensagem exatamente como recebida.
400	Wallet signature does not match	A signature não corresponde ao address para o message informado.	Assine a mensagem exata com a carteira proprietária de address.
400	Could not verify wallet signature	A chamada RPC para verificar a assinatura falhou (transitório).	Tente novamente com backoff.
400	Wallet has no staked VVV on Base	A carteira tem saldo de sVVV zero.	Faça stake de VVV primeiro e tente novamente.

​

Por que o desafio é vinculado à carteira e de uso único

O desafio é uma mensagem EIP-4361 legível por humanos, e não um token opaco, e traz três proteções que importam caso alguma carteira seja solicitada a assinar um desafio fora do seu próprio agente:

• Vínculo de endereço. O desafio nomeia a carteira para a qual foi emitido. Um desafio obtido por uma parte não pode ser assinado e resgatado por outra carteira.
• Nonce de uso único. A Venice registra o nonce no servidor e o consome na primeira geração bem-sucedida. Uma assinatura gera exatamente uma chave, então uma assinatura capturada não pode ser reutilizada para obter chaves adicionais.
• Declaração legível. A mensagem afirma claramente que assinar autoriza a criação de uma chave de API Venice, de modo que uma interface de carteira como o MetaMask mostra ao signatário o que ele está aprovando, em vez de um blob binário.

Trate uma assinatura sobre esta mensagem como equivalente a entregar direitos de criação de chaves de API na sua conta Venice. Assine apenas desafios cuja linha domain seja api.venice.ai e cuja declaração mencione a criação de chave de API Venice. Uma chave ADMIN pode criar e excluir outras chaves e gastar dos seus saldos de DIEM, créditos inclusos e USD.

​

Pagando pela inferência

Gerar uma chave e ser capaz de chamar endpoints pagos com ela são duas coisas separadas. Uma chave recém-gerada autentica corretamente, mas não pode chamar endpoints pagos (como /chat/completions) até que a conta da carteira tenha um saldo gastável.

A chave gerada pode gastar a partir da conta do usuário nesta ordem de prioridade: DIEM, depois créditos agrupados, depois USD.

Fonte de financiamento	Autônoma?	Como
DIEM a partir de staking de VVV	Sim	A alocação diária de DIEM da carteira é proporcional à sua participação no pool de staking. A conta precisa de pelo menos 0,1 DIEM em stake para que qualquer DIEM seja gastável. Stakes maiores ganham proporcionalmente mais DIEM diariamente, renovado a cada época (00:00 UTC).
USD via Stripe	Não (navegador)	Faça login em venice.ai com a mesma carteira (Sign-In-With-Ethereum). O dashboard encontra o registro de usuário existente. Adicione créditos em Settings, API.
Assinatura cripto Coinbase	Não (navegador)	Mesmo login com carteira, depois assine pelo dashboard. O fluxo redireciona para o Coinbase Commerce para o pagamento, então não pode ser conduzido por script.
Onramp Coinbase	Não (navegador)	Mesmo login com carteira, depois use o widget de onramp no dashboard. Hospedado na UI da Coinbase.

Se o agente precisar de um caminho de financiamento totalmente cripto-nativo e headless, as opções mais limpas são:

1. Fazer stake de mais VVV para que a alocação diária de DIEM cubra o gasto do agente. A chave gerada usa isso automaticamente.
2. Usar o fluxo de carteira x402 em vez da chave de API. Com o x402 o agente assina uma mensagem Sign-In-With-X por requisição, faz recarga diretamente com USDC na Base ou Solana via POST /api/v1/x402/top-up e paga por requisição. O saldo de USDC do x402 é vinculado à carteira, não ao usuário, portanto não aparece como saldo para a chave Bearer gerada, mas permite que a mesma carteira pague pela inferência programaticamente.

​

Recursos relacionados

Cripto e agentes

Use a Venice como provedor de modelos e camada de RPC blockchain para agentes autônomos.

Autenticação x402 por carteira

Pague por requisição com USDC na Base ou Solana, sem necessidade de chave de API.

Endpoint de geração de chave de API Web3

Referência do endpoint de geração de chave.

Guia padrão de chave de API

Para usuários que preferem gerar uma chave pelo dashboard.