Una API key de exchange se compone de API Key y API Secret. Con esta key, los programas y servicios trabajan con una cuenta a través de la API: leen saldos, abren y cierran trades y ejecutan otras operaciones permitidas para esa key sin iniciar sesión en el panel web.
Objetivo del material: describir las restricciones que un exchange aplica a las solicitudes API: verificación de firma mediante API Secret, key permissions, vinculación de la fuente de la solicitud a una IP whitelist, restricciones de retiro mediante una withdrawal address whitelist e aislamiento de saldos mediante sub-accounts. Estas restricciones reducen el riesgo de que una filtración del par API Key + API Secret derive en un retiro de activos o en trades con pérdidas.
🧭 Cómo los exchanges cripto controlan el acceso API
Las API keys son utilizadas por trading bots, terminales, servicios de reporting e integraciones internas. Un exchange ejecuta una solicitud API solo después de verificar la firma (API Secret), los derechos de operación (permissions), la dirección IP de origen (IP whitelist) y la hora de la solicitud (timestamp y recvWindow). La verificación temporal bloquea una repetición posterior de la solicitud, incluso si la solicitud fue interceptada.
El riesgo API se reduce mediante la configuración de la key. IP whitelist acepta solicitudes solo desde direcciones IP especificadas. Permissions limita el conjunto de operaciones que el exchange ejecuta con la key. Una withdrawal address whitelist limita la lista de destinatarios. Sub-accounts separa saldos y keys entre sub-accounts, de modo que una key no tenga acceso a todos los activos de la cuenta.
🔍 Cómo un exchange verifica una solicitud API: firma, derechos, IP y tiempo
Una API key se compone de una API Key (el identificador de la key) y un API Secret (el secret utilizado para firmar). La firma confirma al exchange que la solicitud fue creada con el API Secret y no fue modificada durante el tránsito.
- Creación de parámetros de solicitud para el API endpoint del exchange (la dirección API que acepta una operación concreta)
- La solicitud define la operación: abrir o cancelar una orden, consultar un saldo, ejecutar un transfer o iniciar un retiro.
- La solicitud contiene un timestamp y, a veces, una ventana temporal permitida (recvWindow). El exchange compara estos valores con su propia hora y rechaza la solicitud si queda fuera del intervalo permitido.
- Firma de los parámetros de la solicitud mediante HMAC
- HMAC es una firma basada en hash que se genera con una secret key. La cadena de parámetros se firma con el API Secret.
- El exchange recalcula el HMAC con los mismos parámetros y compara la firma. Una discrepancia significa que el remitente no posee el API Secret o que los parámetros fueron modificados.
- Verificación de restricciones de la key y decisión sobre la ejecución
- Permissions define qué operaciones están permitidas para la key (read/trade/transfer/withdraw en la mayoría de los exchanges centralizados, CEXs).
- IP whitelist restringe las fuentes de solicitud. El exchange rechaza una solicitud si la IP del remitente no está incluida en la whitelist de la key.
- Ejecución de la operación y devolución del resultado
- Si los derechos no son suficientes, el exchange devuelve un rechazo y no ejecuta la operación, incluso con una firma válida.
- Si la IP no coincide, el exchange devuelve un rechazo en la fase de autorización y no continúa con una operación de trading o retiro.
Componentes de acceso API controlados por el exchange
El exchange reduce el riesgo API mediante tres verificaciones en cada solicitud: firma con API Secret, permissions para operaciones e IP whitelist para la fuente de la solicitud.
- API Secret se almacena solo en un secrets vault y en la memoria del proceso que firma solicitudes.
- Permissions se activa según la tarea de la key: lectura para reporting, trading para un bot y retiro solo para pagos operativos.
- IP whitelist contiene solo las direcciones IP de los servidores que realmente envían solicitudes, para que la lista no amplíe la superficie de ataque.
Si un atacante obtiene una API Key sin el API Secret, el exchange rechaza la solicitud por una firma no válida. Si un atacante obtiene tanto la API Key como el API Secret, el exchange rechaza la solicitud cuando permissions no permite la operación o la IP no está incluida en la whitelist.
🎯 Qué pérdidas son posibles a través de API: retiros, transfers y pérdidas de trading
El daño API depende de las permissions activadas y del saldo disponible para esa key. Una trade-only key implica menor riesgo en un sub-account con un saldo operativo pequeño y mayor riesgo en un sub-account con capital principal.
Tres escenarios que un exchange ejecuta mediante API
Las pérdidas API surgen por retiro, transfer interno o trades que generan una pérdida al precio de ejecución.
- Retiro directo: una key con withdraw permission inicia un retiro hacia una dirección que el exchange permite después de sus verificaciones y reglas de whitelist.
- Transfer interno: una key con transfer permission mueve activos entre product wallets o entre sub-accounts si el exchange permite esas operaciones mediante la API.
- Pérdida de trading sin retiro: una key con trade permission coloca órdenes en un mercado de baja liquidez y ejecuta trades a un precio peor, lo que genera una pérdida por slippage, spread y comisiones.
La withdraw permission desactivada elimina el retiro directo. Trade permission sigue siendo una fuente de pérdidas si se almacena un saldo grande en la trading wallet y la key no está restringida por IP e instrumentos.
Señales tras las cuales una revisión API se vuelve necesaria
- Aparecieron órdenes que no coinciden con la lógica del trading system ni con el calendario de lanzamiento.
- Aparecieron transfers entre wallets o sub-accounts sin una razón operativa.
- En la configuración de la key aparecieron nuevas permissions o se eliminó IP whitelist.
- En los logs del trading system aparecieron errores de firma y aumentó la frecuencia de solicitudes aunque el código siguió sin cambios.
🌐 IP whitelist: vinculación de una key al servidor que envía solicitudes
IP whitelist obliga al exchange a aceptar solicitudes solo desde direcciones IP predefinidas. Si API Secret entra en el código, logs, backups o un servicio de terceros, un atacante no podrá enviar una solicitud desde una IP que no esté en la whitelist.
Selección de una fuente estable para solicitudes API
- Un VPS (virtual private server) con IP pública estática es adecuado para IP whitelist y para el funcionamiento continuo de un trading system.
- Una conexión doméstica con IP dinámica no es adecuada porque un cambio de IP provoca errores de solicitud API hasta que la whitelist se actualiza.
Configuración de IP whitelist para una API key
- IP whitelist contiene la IP del servidor del trading system y del servidor de backup si el servidor de backup se utiliza realmente.
- Si el exchange admite CIDR (notación de subred, por ejemplo 203.0.113.10/32), se establece el rango más pequeño para que la lista de fuentes no se amplíe.
Verificación de la resiliencia del acceso API
- Una API key de backup en una IP separada se utiliza durante migraciones de infraestructura y cambios de dirección del servidor.
- El procedimiento para actualizar IP whitelist se documenta por adelantado para que un cambio de IP no coincida con la pérdida de control de órdenes.
En infraestructura cloud, las solicitudes pueden salir a internet mediante NAT (traducción de direcciones en el borde de la red). En este caso, la IP externa que ve el exchange puede diferir de la IP del contenedor o de la máquina virtual. La IP whitelist debe contener la egress IP (la IP externa del tráfico saliente); de lo contrario, el exchange rechazará las solicitudes.
IP whitelist no protege frente a una compromisión del VPS. Si el servidor es tomado, un atacante envía solicitudes desde la misma IP, por lo que la protección del acceso al VPS y el control de actualizaciones siguen siendo parte de la protección API.
IP whitelist bloquea solicitudes de servidores no autorizados porque el exchange compara la IP de origen con la whitelist y rechaza la solicitud antes de ejecutar una operación de trading o retiro.
🔑 Permissions: qué derechos se asignan a una key para una tarea concreta
Permissions define qué API endpoints el exchange permite llamar a esta key. Los nombres de los derechos dependen del exchange, pero el modelo suele ser similar: read para lectura, trade para órdenes, transfer para transfers internos y withdraw para retiros en blockchain.
| Tarea | Permitir | Bloquear | Operación bloqueada |
|---|---|---|---|
| Screener/analytics | Read | Trade; Transfer; Withdraw | Colocación de órdenes y movimiento de activos |
| Trading bot | Read; Trade | Withdraw | Retiro directo de fondos mediante API |
| Reporting | Read | Trade; Transfer; Withdraw | Operaciones si el servicio de reporting se ve comprometido |
| Transfers operativos | Read; Transfer | Trade; Withdraw | Operaciones de trading y retiros en blockchain |
Read-only key para monitoring y reporting
Una read-only key se utiliza cuando un sistema necesita leer saldos, historial de trades y estados de posiciones, pero no debe cambiar el estado de la cuenta.
- Una read-only key bloquea la colocación y cancelación de órdenes porque el exchange rechaza los trading endpoints para esta key.
- IP whitelist limita el acceso a datos a un servidor específico y bloquea solicitudes desde IPs no autorizadas si el API Secret se filtra.
- Una read-only key separada para reporting aísla el riesgo del servicio de reporting del riesgo de la trading key.
Una read-only key expone saldos e historial, pero no permite retiros ni trades porque el exchange rechaza endpoints trade/transfer/withdraw.
Trade key para un trading system sin retiros
Una trade key se utiliza para colocar y cancelar órdenes. Withdraw permission no es necesaria para operaciones de trading.
- Trade permission da acceso a la gestión de órdenes y posiciones dentro de los mercados de la cuenta.
- Withdraw permission desactivada bloquea retiros porque el exchange rechaza withdrawal endpoints para esta key.
- IP whitelist vincula la key al servidor del trading system y bloquea solicitudes desde máquinas no autorizadas si el API Secret se filtra.
Una trade-only key crea riesgo para los fondos en la trading wallet, por lo que el trading sub-account normalmente mantiene un saldo operativo y no el capital principal.
Transfer key para movimientos internos
Una transfer key se utiliza para transfers dentro del exchange: entre product wallets o entre sub-accounts si el exchange permite esas operaciones mediante la API.
- Transfer permission permite transfers internos que no van a la blockchain.
- Trade permission desactivada excluye trades porque la transfer key no puede crear órdenes.
- Withdraw permission desactivada excluye retiros en blockchain si la transfer key se ve comprometida.
Separar transfer y trade en keys distintas reduce el daño por un leak porque una key no proporciona acceso simultáneo a trades y movimiento de activos.
Permissions define qué operación permitirá el exchange para esta key. Permissions adicionales amplían el conjunto de acciones que el exchange ejecutará con una key comprometida, por lo que los derechos se activan solo para un proceso concreto.
🏷️ Protección de retiros: address whitelist, confirmaciones y límites
Withdraw permission permite a una API key iniciar un retiro de fondos desde el saldo de un exchange hacia una blockchain. La protección de retiros se apoya en una whitelist de direcciones de destinatario, el control de cambios de whitelist y los límites de retiro.
En integraciones de trading, withdraw permission normalmente está desactivada. Las órdenes, cancelaciones y consultas de saldo se ejecutan dentro del exchange y no requieren retiros en la red. Read permission es suficiente para monitoring y reporting. Trade permission es suficiente para trading algorítmico.
Ejemplo: un trading bot trabaja mediante una key con trade permission y sin withdraw permission. Si la key se ve comprometida, un atacante puede abrir y cerrar trades mediante trading endpoints. El exchange rechazará una solicitud de retiro porque la key no tiene withdraw permission.
Una withdrawal address whitelist limita el destinatario del retiro: el exchange envía fondos solo a direcciones añadidas previamente. En muchos exchanges, añadir una dirección a la whitelist requiere 2FA (autenticación de dos factores) y confirmación mediante un canal separado, como email, app o hardware key. En este caso, el retiro a una dirección nueva depende no solo de la API key, sino también del control sobre esos canales de confirmación.
Una demora en cambios de whitelist (security lock o hold) no activa inmediatamente la dirección añadida. Cuando la demora está activada, el retiro a una dirección nueva queda bloqueado durante el periodo de hold, por lo que la dirección añadida puede detectarse antes del primer retiro.
La conexión API para trading bots, trade-only keys e IP whitelist se aborda en el material «Ganar con bots de trading cripto».
Los límites de retiro limitan la suma de pérdidas si un atacante obtiene una key que supera las verificaciones de whitelist y confirmación. El límite diario se fija para importes regulares de pagos operativos, no para el saldo total de la cuenta, de modo que un ciclo de retiro no pueda vaciar todo el depósito.
La compromisión del email aumenta el riesgo porque muchos exchanges usan email para confirmaciones de adición de direcciones y restablecimientos de seguridad, incluidos enlaces de confirmación y notificaciones sobre cambios de whitelist.
Withdraw permission sin withdrawal address whitelist convierte un API-key leak en un canal directo para retiros en blockchain. Withdraw permission con withdrawal address whitelist y una demora en cambios de whitelist desplaza el riesgo crítico hacia la compromisión de canales de confirmación. Los límites de retiro restringen la suma de pérdidas si se eluden las demás restricciones.
🛡️ Sub-accounts: aislar saldos, keys y procesos
Sub-accounts separa saldos y API keys dentro de un exchange. Si una key se filtra, las operaciones quedan limitadas a los activos de un sub-account específico.
- Separación de storage y trading en distintos sub-accounts
- El storage sub-account mantiene el capital principal y no utiliza API keys de trading permanentes.
- Los trading sub-accounts mantienen saldos operativos para bots y estrategias concretas.
- Control de transfers internos mediante API
- Desactivar transfer permission en trading keys reduce la capacidad de mover activos si una trading key se filtra.
- Una transfer key dedicada se utiliza cuando los transfers internos forman parte del proceso operativo.
- Restricción de instrumentos de la key cuando se admite trading pair whitelist
- Trading pair whitelist bloquea trades en instrumentos que no pertenecen al trading system.
- Las restricciones de pares reducen el riesgo de pérdidas en mercados de baja liquidez.
Modelo de aislamiento para varios trading systems
El modelo de aislamiento separa saldos mediante sub-accounts y separa acceso mediante API keys, permissions e IP whitelist.
- Un trading system en un exchange trabaja mediante un sub-account separado y una trade-only key vinculada a la IP del VPS.
- Reporting se conecta con una read-only key en un servidor separado para que un reporting leak no exponga la trading key.
- Los transfers operativos se ejecutan con una transfer key sin trade ni withdraw permissions.
Si una key del trading system se filtra, el exchange ejecuta operaciones solo dentro del saldo de su sub-account, por lo que las pérdidas se limitan al saldo operativo.
🗄️ Almacenamiento de secrets y rotación: cómo API Secret se filtra desde la infraestructura
API Secret se filtra con más frecuencia no desde el exchange, sino desde la infraestructura del trading system: repositorios de código, pipelines CI/CD (procesos automatizados de build y deployment), logs de aplicaciones, volcados de bases de datos, capturas de pantalla y backups. Secret Management define dónde se almacena el API Secret y qué roles pueden acceder a él.
API Secret no se almacena en el código de la aplicación. El valor del secret se inyecta al iniciar el servicio desde un almacenamiento protegido y no se guarda en archivos del proyecto ni en el repositorio. El código y la configuración mantienen una referencia al secret, no su valor.
Ejemplo: un trading bot se despliega mediante CI/CD. En el repositorio solo se almacena el nombre del secret, y el valor de API Secret se inyecta en la fase de deployment desde un almacenamiento protegido. Si el código y el historial de commits se filtran, API Secret no está presente allí.
En production, API Secret se almacena en un secret manager: un servicio que mantiene secrets cifrados y los entrega solo a procesos con permiso mediante IAM (control de acceso basado en roles). Este modelo separa production secrets de entornos de desarrollo y servicios de prueba.
Las causas conductuales de errores en la gestión del riesgo y en los planes de trading se tratan en el material «Psicología del trading».
La rotación de API keys reduce el riesgo de un leak de larga duración. La rotación incluye crear una nueva key en el exchange, cambiar el sistema al nuevo API Secret y revocar la key anterior para que el exchange deje de aceptar firmas con el secret antiguo.
El cambio se planifica para un periodo sin posiciones abiertas ni órdenes límite activas, de modo que la modificación del API Secret no interrumpa la gestión de órdenes y riesgos.
Reglas mínimas para almacenar API Secret
- API Secret se almacena en un secret manager o en almacenamiento cifrado con control de acceso.
- API Secret no entra en Git, Docker image, CI artifacts ni backups en texto plano.
- El production secret no es accesible desde el entorno de desarrollo ni para roles que no ejecutan el trading system.
- La rotación incluye revocar la key anterior después del cambio para que el secret antiguo deje de funcionar en el lado del exchange.
Permissions, IP whitelist y withdrawal address whitelist protegen del lado del exchange, mientras que Secret Management reduce el riesgo de que API Secret se filtre desde código y logs del lado de la infraestructura.
🧩 Terminales y bots de terceros: cómo la conexión afecta el riesgo
Un servicio de terceros recibe API Key y API Secret para firmar solicitudes en nombre de la cuenta. Si el servicio acepta la key en un panel web, API Secret se almacena en la infraestructura del proveedor. Durante un incidente del proveedor, un atacante podría firmar solicitudes y superar la verificación de firma en el lado del exchange.
✅ Señales de riesgo controlado
- El servicio trabaja con read-only y trade-only keys y no exige withdraw permission para trading y reporting.
- El servicio muestra un log de acciones API: órdenes creadas y endpoints llamados.
- El servicio admite conexión mediante un sub-account separado con un saldo operativo limitado.
❌ Señales de riesgo elevado
- El servicio exige withdraw permission para funciones que no están relacionadas con pagos operativos.
- El servicio exige desactivar IP whitelist y no ofrece un modelo con un agente del lado del usuario y una IP fija.
- El servicio no proporciona historial de acciones API, por lo que la investigación depende de señales indirectas.
Ejemplo de configuración: las señales y reporting usan una read-only key, las operaciones de trading usan una trade-only key en un sub-account con saldo operativo, y los retiros por API están desactivados.
Un servicio de terceros no anula las restricciones del exchange. Un sub-account, IP whitelist, permissions mínimas y withdraw permission desactivada limitan el riesgo al saldo operativo.
🧯 Respuesta a un key leak: detener la ejecución y conservar rastros
Cuando se sospecha un leak del par API Key + API Secret, el riesgo se desarrolla rápidamente porque el exchange ejecuta operaciones inmediatamente después de verificar firma, derechos, IP y hora de la solicitud. La respuesta comienza con detener la autorización de la key y conservar los rastros de operaciones.
- Revocación de la key del lado del exchange
- Desactivar o eliminar la key detiene la aceptación de solicitudes firmadas para esta API Key.
- Desactivar todas las keys del sub-account se utiliza si no se identifica la fuente del leak.
- Conservación de rastros de operaciones
- La lista de órdenes abiertas y el historial de trades del periodo anómalo muestran qué operaciones fueron ejecutadas.
- El historial de retiros y los cambios en withdrawal address whitelist muestran intentos de retiro y preparación de direcciones.
- Cierre de canales adicionales de acceso a la cuenta
- El cambio de contraseña y la verificación de 2FA reducen el riesgo de acceso a la interfaz web.
- Las verificaciones de seguridad del email son necesarias porque las confirmaciones de retiro y los cambios de whitelist suelen estar vinculados al email.
- Restauración del acceso operativo
- Se crea una nueva key con permissions mínimas e IP whitelist para el servidor actual.
- API Secret se actualiza en el secret manager para que el secret antiguo deje de usarse.
La revocación de la key detiene la ejecución de acciones porque el exchange deja de aceptar firmas para esta API Key, incluso si siguen llegando solicitudes.
✅ Configuración que reduce el riesgo de retiro tras un key leak
El riesgo de retiro tras un leak del par API Key + API Secret se reduce cuando la trade key no tiene withdraw permission, las solicitudes están restringidas por IP whitelist y el capital principal está separado del trading sub-account.
Parámetros mínimos para una trade key de trading system
- El trading system funciona en un VPS con IP fija, y esta IP se añade a la IP whitelist de la key.
- La key tiene read + trade permissions y no tiene withdraw permission.
- El trading sub-account contiene el saldo operativo, mientras que el capital principal se almacena por separado sin trading keys permanentes.
- API Secret se almacena en un secret manager o en almacenamiento cifrado y no entra en repositorios ni logs.
IP whitelist, permissions mínimas, withdrawal address whitelist para retiros poco frecuentes e aislamiento mediante sub-accounts limitan el daño al saldo operativo y reducen el riesgo de retiro en blockchain mediante una key comprometida.
❓ FAQ sobre seguridad de API keys
¿Por qué IP whitelist protege incluso si API Secret se filtra?
El exchange compara la IP de origen de la solicitud con la IP whitelist de la key y rechaza la solicitud si la IP no coincide. La firma HMAC puede ser válida, pero la operación no se ejecuta porque la verificación de IP ocurre del lado del exchange.
¿Cuándo se necesita realmente withdraw permission?
Withdraw permission se necesita para pagos operativos automatizados en la blockchain. Para trading, monitoring y reporting, withdraw permission no es necesaria porque estos procesos utilizan endpoints de trading y lectura dentro del exchange.
¿Por qué una trade-only key puede causar pérdidas sin retiro?
Una trade-only key permite colocar órdenes. Con acceso a una trade-only key, un atacante puede ejecutar trades a un precio peor en un mercado de baja liquidez y generar pérdidas por slippage, spread y comisiones cuando hay un saldo grande en la trading wallet.
¿Por qué usar un sub-account separado para cada trading system?
Un sub-account limita el saldo disponible para la key. Si una key del trading system se filtra, el daño se limita a los activos de este sub-account porque el exchange ejecuta operaciones dentro del saldo del sub-account concreto.
¿Cómo rotar keys sin perder el control de órdenes?
La rotación incluye crear una nueva key, cambiar el trading system al nuevo API Secret y revocar la key anterior. El cambio se planifica para un periodo sin posiciones abiertas ni órdenes límite activas, de modo que el cambio de key no interrumpa la gestión de órdenes.
¿Cómo se limita el riesgo al conectar un terminal de terceros?
El riesgo se limita mediante una trade-only key en un sub-account con saldo operativo, IP whitelist (si las solicitudes pasan por un agente del lado del usuario) y withdraw permission desactivada cuando el terminal no participa en retiros operativos.
🧷 Cómo las restricciones API reducen el riesgo de retiros y daño de trading
El riesgo API depende de las operaciones permitidas y de las verificaciones que el exchange aplica a cada solicitud: firma (API Secret), permissions, IP whitelist y parámetros de tiempo de solicitud.
- Withdraw permission desactivada bloquea retiros en blockchain mediante API porque el exchange rechaza withdrawal endpoints para una key sin este derecho.
- Una withdrawal address whitelist limita el destinatario porque el exchange envía fondos solo a direcciones añadidas previamente.
- IP whitelist limita la fuente de la solicitud porque el exchange rechaza solicitudes de IPs que no están en la lista de la key, incluso con una firma válida.
- Sub-accounts limitan la magnitud de las pérdidas porque la key obtiene acceso al saldo de un sub-account específico, no a todos los activos de la cuenta.