Creación autónoma de API Key por agente

​

Requisitos previos

• Un monedero EVM en Base controlado por el agente (clave privada en una variable de entorno o gestor de secretos).
• Una pequeña cantidad de ETH en Base para gas (el staking son dos transacciones: approve y luego stake).
• Cualquier cantidad no nula de VVV para hacer staking. El endpoint de minteo solo requiere que el monedero tenga un saldo de sVVV no nulo, por lo que 1 VVV es suficiente para acuñar una clave. Consulta Pagar la inferencia para saber qué necesitas para llamar realmente a los endpoints de pago.

​

Pasos

1

Adquiere VVV

Envía VVV al monedero del agente, o haz que el agente realice un swap en un DEX como Aerodrome o Uniswap.Contrato del token VVV en Base: 0xacfE6019Ed1A7Dc6f7B508C02d1b04ec88cC21bf

2

Haz staking de VVV con Venice

Haz staking del VVV en el Smart Contract de staking de Venice en 0x321b7ff75154472B18EDb199033fF4D116F340Ff. Son dos transacciones:

1. approve(spender, amount) en el token VVV, donde spender es el contrato de staking.
2. stake(amount) en el contrato de staking.

Cuando se confirma la segunda transacción, el saldo de VVV del monedero disminuye y su saldo de sVVV aumenta en la misma cantidad. El endpoint de minteo lee el saldo de sVVV para confirmar que el monedero tiene staking.

3

Solicita un desafío para el monedero

Llama a GET /api/v1/api_keys/generate_web3_key?address=<wallet address> para obtener un desafío EIP-4361 (Sign-In with Ethereum) de corta duración. El endpoint no está autenticado, pero el desafío queda vinculado a la dirección que envías y solo puede canjearlo ese monedero.

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

La respuesta contiene message, nonce y 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
}

El desafío expira 15 minutos después de su emisión y es de un solo uso: se consume la primera vez que se acuña una clave con él. Solicita uno nuevo para cada clave.

4

Firma el desafío con el monedero de staking

Firma la cadena message tal cual con el monedero que tiene el VVV en staking. Es un personal_sign estándar. Tanto ethers.Wallet.signMessage(message) como account.signMessage({ message }) de viem producen la firma correcta.No reformatees, reajustes ni regeneres el mensaje. Venice verifica la firma sobre los bytes exactos que emitió y vuelve a comprobar de forma independiente el domain, la URI, el Chain ID, la declaración y la dirección que contiene.

5

Acuña la API key

Haz POST de la dirección, la firma y el mensaje al mismo endpoint, junto con el tipo de clave que quieras.

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 obligatorios: address, signature, message, apiKeyType (INFERENCE o ADMIN).Campos opcionales: description, expiresAt, consumptionLimit (limita el gasto total en esta clave, denominado en usd, vcu o diem).En caso de éxito, la respuesta contiene la cadena apiKey acuñada. Guárdala en el almacén de secretos del agente y úsala como un token Bearer normal (Authorization: Bearer <key>).

​

Ejemplo de extremo a extremo

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)

​

Referencia de errores

​

Por qué el desafío está vinculado al monedero y es de un solo uso

• Vinculación de dirección. El desafío nombra el monedero para el que se emitió. Un desafío obtenido por una parte no puede firmarse ni canjearse con un monedero distinto.
• Nonce de un solo uso. Venice registra el nonce en el servidor y lo consume en la primera acuñación correcta. Una firma acuña exactamente una clave, así que una firma capturada no puede reutilizarse para obtener más claves.
• Declaración legible. El mensaje indica con claridad que firmar autoriza la creación de una API key de Venice, de modo que una interfaz de monedero como MetaMask muestra al firmante lo que está aprobando en lugar de un bloque binario.

​

Pagar la inferencia

1. Hacer más staking de VVV para que la asignación diaria de DIEM cubra el gasto del agente. La clave acuñada lo recoge automáticamente.
2. Usa el flujo de monedero x402 en lugar de la API key. Con x402, el agente firma un mensaje Sign-In-With-X por solicitud, recarga directamente con USDC en Base o Solana mediante POST /api/v1/x402/top-up y paga por solicitud. El saldo de USDC x402 está vinculado al monedero, no al usuario, por lo que no aparece como saldo para la clave Bearer acuñada, pero sí permite que el mismo monedero pague la inferencia de forma programática.

​

Recursos relacionados