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

​

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.

​

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

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

​

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

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

​

Pagando pela inferência

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