Antes de que un bot pueda operar por ti, Freya necesita una conexión al exchange donde están tus fondos — Binance, OKX o Bybit. Para hacerlo, no mueves tus fondos ni compartes tu contraseña. En su lugar, creas una clave API: una credencial restringida que permite a Freya colocar operaciones en tu nombre, mientras tu dinero permanece en tu propia cuenta del exchange.
Esta guía explica exactamente qué permisos conceder (y cuáles nunca conceder), cómo agregar la clave a Freya, y qué hacer si la conexión no se valida. Si quieres entender el panorama completo de por qué esto es seguro, lee primero ¿Está Mi Dinero Seguro en Freya Finance?.
Puntos clave
- Conectas un exchange con una clave API — una credencial restringida — no moviendo fondos ni compartiendo la contraseña de tu exchange.
- La clave necesita permisos de Lectura y de trading Spot o Futuros (o ambos). NUNCA debe tener permiso de retiro.
- Las claves de OKX requieren una frase de contraseña que tú estableces al crearlas; Binance y Bybit no la usan.
- Agrega la clave en Freya desde Configuración → Claves API → Agregar clave API, y Freya la valida al instante.
- Si la validación falla, Freya te dice exactamente por qué — clave inválida, IP no incluida en lista blanca, o un permiso faltante — y cada caso tiene una solución sencilla.
Un Resumen Rápido de los Pasos
- Crea una clave API en tu exchange con permisos de lectura y trading, pero sin retiro.
- Copia las credenciales — la clave API, la clave secreta y (para OKX) la frase de contraseña.
- Agrega la clave a Freya desde Configuración → Claves API → Agregar clave API, y selecciona tu exchange.
- Deja que Freya la valide — Freya verifica la conexión y los permisos de inmediato.
- Corrige cualquier error que reporte — Freya te dice exactamente qué está mal si la validación falla.
Qué Es una Clave API — y Qué Permisos Necesita Freya
Una clave API es un par de credenciales (una clave y un secreto) que permite a una aplicación comunicarse con tu cuenta del exchange de forma limitada. Tú decides qué puede hacer esa clave. Para Freya, habilita únicamente:
- Lectura — para que Freya pueda ver tus saldos, posiciones y el estado de las órdenes.
- Trading Spot o Trading de Futuros (o ambos) — para que tu bot pueda colocar las órdenes que necesita. Habilita el que coincida con los bots que planeas ejecutar.
Freya coloca operaciones; nunca necesita sacar dinero de tu cuenta. Deja siempre el permiso de retiro deshabilitado en la clave que conectas. Este es un permiso que tú controlas en el exchange — con él desactivado, ni Freya ni nadie que pudiera obtener la clave puede retirar tus fondos. Es el hábito más importante al conectar cualquier plataforma de bots.
Paso 1: Crea una Clave API en Tu Exchange
En la sección de gestión de API de tu exchange, crea una nueva clave API:
- Binance — crea la clave en Gestión de API, habilita lectura y trading Spot o Futuros (o ambos), y deja los retiros desactivados.
- OKX — crea la clave y establece una frase de contraseña (la necesitarás en Freya); habilita lectura y trading, no retiros.
- Bybit — crea la clave con permisos de lectura y trading para los productos que vayas a usar, y deja los retiros desactivados.
Si tu exchange ofrece lista blanca de IP, es una buena práctica restringir la clave a las direcciones IP de Freya. Si lo haces, asegúrate de incluir las IPs de Freya en la lista blanca, o la conexión será rechazada (consulta la tabla de errores más abajo).
Cuando creas la clave, el exchange muestra el secreto una única vez. Cópialo de inmediato y guárdalo en un lugar seguro. Si lo pierdes, no puedes recuperarlo — tendrás que eliminar la clave y crear una nueva.
Paso 2: Agrega la Clave a Freya
En Freya, ve a Configuración → Claves API y selecciona Agregar clave API. Luego:
- Elige tu exchange (Binance, OKX o Bybit).
- Pega la clave API y el secreto. Para OKX, ingresa además la frase de contraseña que estableciste.
- Asígnale un nombre a la clave para que puedas reconocerla más tarde.
Puedes conectar más de un exchange, y administrar o eliminar tus claves desde esta misma página en cualquier momento.
Paso 3: Freya Valida Tu Clave
Apenas agregas la clave, Freya verifica la conexión y los permisos — sin conjeturas. Si todo está correcto, la clave queda verificada y lista para usar. Si algo está mal, Freya muestra un mensaje claro explicando exactamente qué corregir.
Entendiendo los Errores de Validación
Si la validación falla, relaciona el mensaje que muestra Freya con la solución de abajo:
| Lo que muestra Freya | Qué significa | Cómo solucionarlo |
|---|---|---|
| Clave API inválida | La clave se copió incorrectamente o se eliminó en el exchange | Vuelve a copiar la clave API con exactitud, o crea una nueva |
| Clave secreta inválida | El secreto no coincide con la clave | Vuelve a copiar el secreto; si lo perdiste, crea una clave nueva |
| Dirección IP no incluida en lista blanca | La clave está restringida por IP y la dirección de Freya no está permitida | Incluye las IPs de Freya en la lista blanca de la clave, o quita la restricción de IP |
| Permisos faltantes | La clave carece de permiso de lectura o de trading | Habilita lectura y trading Spot/Futuros en la clave |
| Permiso de lectura deshabilitado | Freya no puede leer tu cuenta | Habilita el permiso de lectura/visualización en la clave |
| Permiso Spot/Futuros deshabilitado | La clave no puede colocar las órdenes que tu bot necesita | Habilita el tipo de trading (Spot o Futuros) que coincida con tu bot |
| Conexión fallida | Un problema temporal de red o del exchange | Espera un momento e intenta agregar la clave de nuevo |
Freya también señalará una clave que esté en modo «Sin restricciones» — es decir, sin restricción de IP. Por tu seguridad, Freya te pide que actives la restricción de IP y agregues la dirección que muestra antes de poder guardar la clave. Habilita solo lectura y trading (nunca retiro), y restringe la clave a la IP de Freya. (Más sobre errores de conexión en ¿No Puedes Conectar Tu Exchange?.)
Una Nota Sobre la Seguridad
La conexión es segura por diseño, pero unos pocos hábitos la mantienen así:
- Retiro desactivado, siempre — Freya nunca lo necesita.
- Usa lista blanca de IP cuando tu exchange lo permita.
- Una clave, un propósito — y elimina las claves que ya no uses.
Para el panorama completo de cómo se protegen tus fondos y tus claves, consulta ¿Está Mi Dinero Seguro en Freya Finance? y Seguridad de la API del Exchange y Mitigación de Riesgos.
Preguntas Frecuentes
¿Qué permisos necesita Freya en mi clave API?
Lectura (para ver tus saldos, posiciones y órdenes) y trading Spot o Futuros, o ambos (para colocar las órdenes de tu bot). Habilita el tipo de trading que coincida con los bots que vayas a ejecutar. Freya nunca necesita permiso de retiro, así que déjalo siempre deshabilitado.
¿Necesita Freya permiso para retirar mis fondos?
No. Freya solo coloca y gestiona operaciones; no puede ni debería poder sacar fondos de tu exchange. Deja siempre el permiso de retiro desactivado en la clave que conectas — es un permiso que tú controlas en el exchange.
¿Por qué Freya dice «Dirección IP no incluida en lista blanca»?
Tu clave API está restringida a direcciones IP específicas, y la dirección de Freya no está en la lista. Agrega las direcciones IP de Freya a la lista blanca de la clave en tu exchange, o quita la restricción de IP de la clave. Después de actualizarla, agrega la clave en Freya de nuevo.
¿Por qué dice «Clave API inválida» o «Clave secreta inválida»?
Normalmente, la clave o el secreto se copiaron incorrectamente, o la clave se eliminó o regeneró en el exchange. Vuelve a copiar ambos valores con exactitud. Como el secreto solo se muestra una vez al crear la clave, si ya no lo tienes, elimina la clave en el exchange y crea una nueva.
¿Qué es la frase de contraseña y por qué OKX la pide?
Las claves API de OKX incluyen una frase de contraseña que tú mismo estableces al crear la clave — es una credencial adicional junto a la clave y el secreto. Ingresa la misma frase de contraseña en Freya al agregar una clave de OKX. Binance y Bybit no usan frase de contraseña.
¿Puedo conectar más de un exchange?
Sí. Puedes agregar claves API para Binance, OKX y Bybit, y administrarlas o eliminarlas en cualquier momento desde Configuración → Claves API.
¿Es seguro darle a Freya mi clave API?
Sí, cuando la clave está configurada correctamente — solo lectura y trading, sin retiro, e incluida en la lista blanca de IP donde sea posible. Tus fondos permanecen en tu propio exchange, y la clave que compartes no puede moverlos. Para la explicación completa, consulta ¿Está Mi Dinero Seguro en Freya Finance?.
¿Qué exchanges soporta Freya?
Freya actualmente se conecta con Binance, OKX y Bybit (spot y futuros). Es posible que se agreguen más exchanges con el tiempo. Operas en aquel que conectes — tus fondos y los mercados disponibles permanecen en ese exchange.
¿Qué monedas o pares de trading puedo operar?
Los pares disponibles provienen de los propios listados de tu exchange conectado, no de una lista separada de Freya — así que si tu exchange lista un par (p.ej., BTC/USDT, ETH/USDT), puedes crear un bot sobre él. La mayor parte del trading se hace contra USDT como moneda de cotización. Si un exchange deslista un par, deja de poder operarse allí.