Creación autónoma de API Key por agente

Acuña una clave de API de Venice de forma autónoma desde un agente on-chain con staking de VVV en Base y firma de un desafío SIWE con monedero.

Un agente de IA que controla un monedero en Base puede acuñar su propia API key de Venice sin intervención humana. El agente adquiere VVV, lo pone en staking, solicita un desafío de corta duración vinculado a la dirección de su monedero, lo firma y lo envía de vuelta para recibir una API key nueva vinculada al monedero con staking.

Esta guía recorre el flujo completo de extremo a extremo y cubre las opciones de financiación para pagar realmente la inferencia una vez que se ha acuñado la clave.

​

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.

Usa un monedero dedicado del agente en lugar de un monedero de tesorería. La clave privada del monedero firma cada desafío de Venice, por lo que su radio de impacto debe ser pequeño.

​

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

El ejemplo siguiente usa un monedero real desde una variable de entorno en lugar de uno generado aleatoriamente. Un monedero aleatorio no tiene VVV en staking y el minteo se rechazará con el error 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)

​

Referencia de errores

El endpoint devuelve mensajes de error específicos y accionables. Mapéalos en el agente para que pueda decidir si reintentar, solicitar un nuevo desafío o detenerse.

Estado	El mensaje de error contiene	Significado	Qué hacer
400	Invalid wallet address	El campo address no es una dirección EVM válida.	Corrige la dirección y reenvía.
400	The challenge has expired	El desafío expiró antes de firmarlo y enviarlo.	Solicita un nuevo desafío, fírmalo y envíalo de inmediato.
400	This challenge has already been used	El desafío ya se canjeó. Cada uno acuña como máximo una clave.	Solicita un desafío nuevo para cada clave que acuñes.
400	issued for a different wallet address	La address enviada no es la dirección para la que se emitió el desafío.	Solicita un desafío con ?address= establecido en el monedero que va a firmar.
400	not a valid Venice API key authorization challenge	El message no es un desafío de Venice, o fue modificado.	Envía la cadena message exacta devuelta por el endpoint GET.
400	The challenge statement was modified	La línea de la declaración se alteró tras la emisión.	Firma el mensaje tal cual.
400	The challenge domain must be "api.venice.ai"	La línea domain se alteró.	Firma el mensaje tal cual.
400	Wallet signature does not match	La signature no coincide con la address para el message dado.	Firma el mensaje exacto con el monedero propietario de address.
400	Could not verify wallet signature	La llamada RPC para verificar la firma falló (transitorio).	Reintenta con backoff.
400	Wallet has no staked VVV on Base	El monedero tiene saldo de sVVV cero.	Haz staking de VVV primero y reintenta.

​

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

El desafío es un mensaje EIP-4361 legible por personas en lugar de un token opaco, y cuenta con tres protecciones que importan si alguna vez se pide a un monedero que firme uno fuera de tu propio agente:

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

Trata una firma sobre este mensaje como equivalente a ceder derechos de creación de API keys en tu cuenta de Venice. Firma únicamente desafíos cuya línea domain sea api.venice.ai y cuya declaración mencione la creación de API keys de Venice. Una clave ADMIN puede crear y eliminar otras claves y gastar de tus saldos de DIEM, créditos incluidos y USD.

​

Pagar la inferencia

Acuñar una clave y poder llamar a endpoints de pago con ella son dos cosas distintas. Una clave recién acuñada se autentica correctamente, pero no puede llamar a endpoints de pago (como /chat/completions) hasta que la cuenta del monedero tenga un saldo gastable.

La clave acuñada puede gastar de la cuenta de usuario en este orden de prioridad: DIEM, luego créditos incluidos y luego USD.

Fuente de financiación	¿Autónoma?	Cómo
DIEM por staking de VVV	Sí	La asignación diaria de DIEM del monedero es proporcional a su parte en la piscina de staking. La cuenta necesita al menos 0,1 DIEM en staking para que cualquier DIEM sea gastable. Cantidades mayores en staking obtienen proporcionalmente más DIEM diario, renovado cada época (00:00 UTC).
USD vía Stripe	No (navegador)	Inicia sesión en venice.ai con el mismo monedero (Sign-In-With-Ethereum). El dashboard encuentra el registro de usuario existente. Añade créditos en Settings, API.
Suscripción cripto de Coinbase	No (navegador)	Inicio de sesión con el mismo monedero y luego suscríbete a través del dashboard. El flujo redirige a Coinbase Commerce para el pago real, por lo que no se puede automatizar por script.
Onramp de Coinbase	No (navegador)	Inicio de sesión con el mismo monedero y luego usa el widget de onramp en el dashboard. Alojado en la UI de Coinbase.

Si el agente necesita una ruta de financiación totalmente nativa de cripto y sin interfaz, las opciones más limpias son:

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

Cripto y agentes

Usa Venice tanto como proveedor de modelos como capa RPC de blockchain para agentes autónomos.

Autenticación de monedero x402

Paga por solicitud con USDC en Base o Solana, sin necesidad de API key.

Endpoint Generate Web3 API Key

Referencia del endpoint de minteo.

Guía estándar de API Key

Para los usuarios que prefieren acuñar una clave desde el dashboard.