> ## Documentation Index > Fetch the complete documentation index at: https://veniceai-docs-web3-key-siwe-challenge.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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](#paying-for-inference) 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 Envía VVV al monedero del agente, o haz que el agente realice un swap en un DEX como [Aerodrome](https://aerodrome.finance/swap?from=eth\&to=0xacfe6019ed1a7dc6f7b508c02d1b04ec88cc21bf\&chain0=8453\&chain1=8453) o [Uniswap](https://app.uniswap.org/swap?chain=base\&inputCurrency=NATIVE\&outputCurrency=0xacfe6019ed1a7dc6f7b508c02d1b04ec88cc21bf). Contrato del token VVV en Base: `0xacfE6019Ed1A7Dc6f7B508C02d1b04ec88cC21bf` Haz staking del VVV en el [Smart Contract de staking de Venice](https://basescan.org/address/0x321b7ff75154472b18edb199033ff4d116f340ff#code) 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. Smart Contract 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. Llama a `GET /api/v1/api_keys/generate_web3_key?address=` para obtener un desafío [EIP-4361](https://eips.ethereum.org/EIPS/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. ```bash theme={null} curl --request GET \ --url 'https://api.venice.ai/api/v1/api_keys/generate_web3_key?address=' ``` La respuesta contiene `message`, `nonce` y `expiresAt`: ```json theme={null} { "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. 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. Haz `POST` de la dirección, la firma y el mensaje al mismo endpoint, junto con el tipo de clave que quieras. ```bash theme={null} curl --request POST \ --url https://api.venice.ai/api/v1/api_keys/generate_web3_key \ --header 'Content-Type: application/json' \ --data '{ "address": "", "signature": "", "message": "", "apiKeyType": "INFERENCE", "description": "Agent key minted on " }' ``` 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 `). ## 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`. ```typescript theme={null} 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](/guides/integrations/x402-venice-api) 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 Usa Venice tanto como proveedor de modelos como capa RPC de blockchain para agentes autónomos. Paga por solicitud con USDC en Base o Solana, sin necesidad de API key. Referencia del endpoint de minteo. Para los usuarios que prefieren acuñar una clave desde el dashboard.