Variables de entorno¶
Todas las estrategias se ejecutan a través del sidecar de pasarela (iniciado automáticamente por almanak strat run). La pasarela almacena los secretos, proporciona acceso RPC y ejecuta transacciones.
Crea un archivo .env en el directorio de tu estrategia con las variables que se indican a continuación.
Obligatorias¶
Estas variables deben configurarse antes de ejecutar cualquier estrategia.
| Variable | Descripción | Ejemplo |
|---|---|---|
ALMANAK_PRIVATE_KEY |
Clave privada de la wallet para firmar transacciones y derivar la dirección de tu wallet | 0x4c0883a6... |
Acceso RPC (recomendado; se usan RPCs públicos gratuitos si no se configura)¶
| Variable | Prioridad | Descripción | Ejemplo |
|---|---|---|---|
ALMANAK_{CHAIN}_RPC_URL |
1 (más alta) | URL RPC por cadena con prefijo ALMANAK | https://arb-mainnet.infura.io/v3/KEY |
{CHAIN}_RPC_URL |
2 | URL RPC por cadena (ej: ARBITRUM_RPC_URL) |
https://arb-mainnet.infura.io/v3/KEY |
ALMANAK_RPC_URL |
3 | URL RPC genérica para todas las cadenas | https://your-rpc.com/v1/KEY |
RPC_URL |
4 | URL RPC genérica básica | https://your-rpc.com/v1/KEY |
ALCHEMY_API_KEY |
5 (respaldo) | Clave API de Alchemy -- URLs construidas automáticamente por cadena | abc123def456 |
TENDERLY_API_KEY_{CHAIN} |
6 (respaldo) | Clave API de Tenderly por cadena (ej: TENDERLY_API_KEY_ARBITRUM) |
abc123... |
Cualquier proveedor funciona: Infura, QuickNode, auto-hospedado, Alchemy, etc. ALCHEMY_API_KEY es un respaldo opcional que construye automáticamente URLs para todas las cadenas soportadas. Si no se configura ninguna, la pasarela usa RPCs públicos gratuitos (con límites de velocidad, mejor esfuerzo).
Warning
Nunca hagas commit de claves privadas. Usa una wallet de prueba dedicada para desarrollo.
Nota: La pasarela también acepta ALMANAK_GATEWAY_PRIVATE_KEY (con su propio prefijo). Si se configura, tiene prioridad. De lo contrario, la pasarela usa ALMANAK_PRIVATE_KEY -- así que solo necesitas una variable.
Claves API opcionales¶
Configura estas según los protocolos y funcionalidades que use tu estrategia.
| Variable | Cuándo se necesita | Obtener clave |
|---|---|---|
ENSO_API_KEY |
Enrutamiento de swaps vía el agregador Enso Finance | enso.finance |
COINGECKO_API_KEY |
Mejora los límites de velocidad para datos de precios (funciona sin clave) | coingecko.com/en/api |
ALMANAK_API_KEY |
Autenticación de la plataforma Almanak | app.almanak.co |
THEGRAPH_API_KEY |
Backtesting con datos de subgraphs (volúmenes DEX, APYs de préstamo) | thegraph.com/studio |
Específicas por protocolo¶
Solo necesarias si tu estrategia usa estos protocolos específicos.
Kraken¶
| Variable | Descripción |
|---|---|
KRAKEN_API_KEY |
Clave API de Kraken (obtener credenciales) |
KRAKEN_API_SECRET |
Secreto API de Kraken |
Polymarket¶
| Variable | Descripción |
|---|---|
POLYMARKET_WALLET_ADDRESS |
Dirección de wallet de Polymarket |
POLYMARKET_PRIVATE_KEY |
Clave de firma de Polymarket |
POLYMARKET_API_KEY |
Clave API CLOB |
POLYMARKET_SECRET |
Secreto HMAC |
POLYMARKET_PASSPHRASE |
Frase secreta API |
Pendle¶
| Variable | Descripción |
|---|---|
ALMANAK_GATEWAY_PENDLE_API_KEY |
Clave API del protocolo Pendle |
Solana¶
| Variable | Descripción |
|---|---|
SOLANA_PRIVATE_KEY |
Par de claves Ed25519 en formato base58 (o semilla hexadecimal de 64 caracteres). Requerido para estrategias de Solana. |
SOLANA_RPC_URL |
Endpoint RPC de Solana. Por defecto https://api.mainnet-beta.solana.com (con límite de tasa). Usa Helius, QuickNode o Triton en producción. |
JUPITER_API_KEY |
Clave API del agregador Jupiter. Se usa el nivel gratuito si no se define. |
DRIFT_DATA_API_BASE_URL |
Sobrescritura de la URL base de la API de datos de Drift (por defecto https://data.api.drift.trade). |
METEORA_API_BASE_URL |
Sobrescritura de la URL base de la API de Meteora (por defecto https://dlmm.datapi.meteora.ag). |
ORCA_API_BASE_URL |
Sobrescritura de la URL base de la API de Orca (por defecto https://api.orca.so/v2/solana). |
RAYDIUM_API_BASE_URL |
Sobrescritura de la URL base de la API de Raydium (por defecto https://api-v3.raydium.io). |
Endpoints de datos de Polymarket¶
| Variable | Descripción |
|---|---|
POLYMARKET_GAMMA_URL |
Sobrescritura del endpoint Polymarket Gamma (metadatos de mercado). Recurre al valor por defecto aguas arriba si no se define. |
POLYMARKET_CLOB_URL |
Sobrescritura del endpoint Polymarket CLOB (libro de órdenes + gestión de órdenes). |
POLYMARKET_DATA_API_URL |
Sobrescritura del endpoint de la API de datos de Polymarket (posiciones / historial). |
Otras integraciones externas¶
| Variable | Descripción |
|---|---|
LIFI_API_KEY |
Clave API del agregador de bridge / swap Li.Fi. |
RUGCHECK_API_KEY |
Clave API de Rugcheck.xyz para puntuación de riesgo de tokens Solana. |
Autenticación y seguridad de la pasarela¶
Crítico para los despliegues alojados (Almanak Infra). Cada variable se lee una vez al iniciar la pasarela; los cambios requieren reiniciarla.
| Variable | Descripción |
|---|---|
ALMANAK_GATEWAY_AUTH_TOKEN |
Token de secreto compartido para la autenticación gRPC. Cuando está definido, los clientes deben proporcionar este token en los metadatos para acceder a los servicios. Obligatorio en despliegues alojados. |
ALMANAK_GATEWAY_ALLOW_INSECURE |
Cuando es true, permite que la pasarela arranque sin ALMANAK_GATEWAY_AUTH_TOKEN. Por defecto false (la pasarela se niega a arrancar). Solo desarrollo local — nunca lo actives en un despliegue alojado. |
ALMANAK_GATEWAY_OPERATOR_TOKEN |
Token de segundo factor (VIB-4493 Fase 1) requerido para los RPC de mutación en DashboardService (PreviewReconcile, ApplyReconcile, RefreshRegistryFromChain). Los llamadores deben enviar el mismo valor en el encabezado de metadatos x-operator-token además del token de autenticación habitual. Cuando no está definido (por defecto), los handlers caen de nuevo a autenticación solo con auth-token — seguro para despliegues mono-usuario / locales. |
Los despliegues alojados son inseguros sin estas variables
Omitir ALMANAK_GATEWAY_AUTH_TOKEN (o activar ALMANAK_GATEWAY_ALLOW_INSECURE=true) en una pasarela alojada expone cada servicio gRPC a llamadores no autenticados — incluido ExecutionService, que firma y envía transacciones. Trata ambos como secretos de producción.
Sobrescrituras manuales de precios¶
Recurso de último resorte para tokens que ninguna fuente de oráculo real puede valorar (p. ej., tokens long-tail en cadenas emergentes).
| Variable | Descripción |
|---|---|
ALMANAK_GATEWAY_ENABLE_MANUAL_PRICE_OVERRIDES |
Habilita el fallback ManualPriceOverrideSource. Por defecto false. Desactivado por defecto porque una variable mal configurada podría inyectar un precio erróneo en las decisiones de slippage / teardown. |
ALMANAK_PRICE_OVERRIDE_<TOKEN> |
Precio de sobrescritura por token en USD. Solo se consulta cuando todas las fuentes de oráculo reales fallaron al valorar el token. Ejemplo: ALMANAK_PRICE_OVERRIDE_W0G=0.012. |
Configura ambas: el flag de habilitación enciende la fuente; las variables por token suministran los precios.
Simulación con Tenderly¶
Usada por SimulationService.SimulateBundle cuando el simulador está fijado a "tenderly" (o autoseleccionado). Las tres deben establecerse juntas — dejar una vacía desactiva Tenderly y cae al simulador Alchemy si está disponible.
| Variable | Descripción |
|---|---|
ALMANAK_GATEWAY_TENDERLY_ACCOUNT_SLUG |
Slug de cuenta Tenderly (el segmento <account> de la URL del panel). |
ALMANAK_GATEWAY_TENDERLY_PROJECT_SLUG |
Slug de proyecto Tenderly dentro de la cuenta. |
ALMANAK_GATEWAY_TENDERLY_ACCESS_KEY |
Clave de acceso Tenderly con permisos de simulación (ajustes de la cuenta → claves de acceso). |
Proveedor de portafolio (multi-proveedor)¶
Configura la(s) fuente(s) de valoración de portafolio de la pasarela. Usado por IntegrationService.GetWalletPortfolio / GetWalletPositions para agregar saldos y posiciones DeFi a través de cadenas.
| Variable | Descripción |
|---|---|
ALMANAK_GATEWAY_PORTFOLIO_API_KEY |
Clave API mono-proveedor (ruta heredada mono-proveedor). |
ALMANAK_GATEWAY_PORTFOLIO_API_PROVIDER |
Nombre del proveedor único. Por defecto zerion. |
ALMANAK_GATEWAY_PORTFOLIO_PROVIDERS |
Sobrescritura multi-proveedor. Nombres de proveedores separados por comas en orden de prioridad (p. ej., zerion,moralis). Cuando se define, tiene prioridad sobre las claves mono-proveedor. Cada proveedor lee su propia clave API desde {NAME}_API_KEY (p. ej., ZERION_API_KEY, MORALIS_API_KEY). |
Wallet Safe¶
Para estrategias que se ejecutan a través de un multisig de Gnosis Safe.
| Variable | Descripción |
|---|---|
ALMANAK_GATEWAY_SAFE_ADDRESS |
Dirección de la wallet Safe |
ALMANAK_GATEWAY_SAFE_MODE |
direct (Anvil/umbral-1) o zodiac (producción) |
ALMANAK_GATEWAY_ZODIAC_ROLES_ADDRESS |
Dirección del módulo Zodiac Roles (modo zodiac) |
ALMANAK_GATEWAY_SIGNER_SERVICE_URL |
URL del servicio de firma remoto (modo zodiac) |
ALMANAK_GATEWAY_SIGNER_SERVICE_JWT |
JWT del firmante remoto (modo zodiac) |
Backtesting¶
URLs RPC de archivo¶
Necesarias para datos históricos on-chain (precios de Chainlink, cálculos TWAP). Los nodos RPC estándar no soportan consultas de estado histórico. Usa proveedores con soporte de archivo como Alchemy (de pago), QuickNode o Infura.
Patrón: ARCHIVE_RPC_URL_{CHAIN} (ej: ARCHIVE_RPC_URL_ARBITRUM, ARCHIVE_RPC_URL_ETHEREUM, ARCHIVE_RPC_URL_BASE, ARCHIVE_RPC_URL_OPTIMISM, ARCHIVE_RPC_URL_POLYGON, ARCHIVE_RPC_URL_AVALANCHE)
Claves API de exploradores de bloques¶
Opcionales, para datos históricos de precio de gas. Patrón: {EXPLORER}_API_KEY
| Variable | Explorador |
|---|---|
ETHERSCAN_API_KEY |
etherscan.io |
ARBISCAN_API_KEY |
arbiscan.io |
BASESCAN_API_KEY |
basescan.org |
OPTIMISTIC_ETHERSCAN_API_KEY |
optimistic.etherscan.io |
POLYGONSCAN_API_KEY |
polygonscan.com |
SNOWTRACE_API_KEY |
snowtrace.io |
BSCSCAN_API_KEY |
bscscan.com |
.env de inicio rápido¶
# Obligatorio
ALMANAK_PRIVATE_KEY=0xYOUR_PRIVATE_KEY
# Acceso RPC (elige uno)
RPC_URL=https://your-rpc-provider.com/v1/your-key
# ALCHEMY_API_KEY=your_alchemy_key # alternativa: construye URLs automáticamente por cadena
# Recomendado
ENSO_API_KEY=your_enso_key
COINGECKO_API_KEY=your_coingecko_key
Todos los demás ajustes de la pasarela y del framework tienen valores predeterminados razonables y no necesitan configurarse. Consulta .env.example para la lista completa de opciones avanzadas.