API Key de Binance con tres niveles de permisos e IP whitelist: configuración de mínima exposición para trading programático

El equipo de Biabahub explica en detalle las diferencias entre los permisos de solo lectura, trading y retiro de la API Key de Binance, ejemplos de firma con Passphrase y HMAC-SHA256, pasos para vincular la IP whitelist a la IP pública de tu servidor, ciclo de rotación cada 90 días y el post-mortem de un caso real de vaciado en 30 segundos. Configuración en unos 15 minutos.

Publicado el 2026-07-13 · Unos 32 min de lectura · Ajustes de seguridad

Entre los incidentes de API que ha gestionado Biabahub, el más rápido tardó 28 segundos desde la fuga de la clave hasta el vaciado total de la cuenta: el atacante usó la clave filtrada para abrir una posición con apalancamiento 100x en contra de la tendencia y forzó la liquidación. La API Key es el eslabón «con más privilegios y verificación más débil» del ecosistema de seguridad de Binance. Este artículo explica de una vez los tres niveles de permisos, la IP whitelist, la Passphrase, la firma HMAC y la cadencia de rotación. Para revisar la configuración en el navegador, entra al Sitio Oficial de Binance; si necesitas confirmar desde móvil, entra en /es/download/ o consigue la App Oficial de Binance.

Respuesta directa: ¿cómo configuro las API Keys para trading programático?

R: Divide la operativa en al menos 3 claves: una de solo lectura para monitorización, otra de trading para lanzar órdenes desde la estrategia y una tercera exclusiva para retiros que casi nunca esté activa. Cada clave debe recibir solo el permiso mínimo que necesita el negocio y todas deben tener IP whitelist que permita únicamente la IP pública de tu servidor. Una clave con permisos por defecto y sin IP whitelist puede vaciarse en 30 segundos tras una filtración. La configuración completa toma unos 15 minutos y toca tres pantallas: la página de gestión de API, la consulta de IP de salida del servidor y el archivo de configuración de tu estrategia. Cualquier atajo saltándose la IP whitelist se paga con el capital completo.


1. Fronteras de cada nivel de permisos y endpoints permitidos

Los permisos de la API de Binance fueron reestructurados en 2024 en tres niveles. La tabla interna de correspondencias de Biabahub queda así.

1.1 Cruce permiso / endpoint / nivel de riesgo

Nivel de permiso Endpoints de ejemplo No permite Nivel de riesgo Consecuencia si se filtra
Solo lectura (Read Only) GET /account, GET /myTrades, GET /openOrders Cualquier POST/DELETE Bajo Fuga de privacidad, cacería de posiciones
Trading spot POST /order, DELETE /order, GET /openOrders Futuros, préstamo con margen, retiro Medio Órdenes contrarias, wash trading pump & dump
Trading de futuros POST /fapi/v1/order, POST /fapi/v1/leverage Retiro, transferencia fuera de la cuenta principal Alto Liquidación directa con 100x reverso
Retiro (Withdraw) POST /wapi/v3/withdraw -- Extremo Vaciado total en 30 segundos

Conclusión de Biabahub: el 99 % de las estrategias diarias solo necesita «trading spot» o «trading de futuros»; nunca apiles el permiso «retiro» encima. El retiro debe vivir en una clave aparte y estar desactivado por defecto.

1.2 Restricciones específicas del permiso de retiro

  • Las claves con permiso de retiro deben llevar IP whitelist; a partir de 2024 Binance lo impone.
  • Las claves con permiso de retiro deben especificar una lista de direcciones de destino permitidas; solo pueden retirar a direcciones incluidas en la lista blanca.
  • Las claves con permiso de retiro caducan a los 90 días de forma obligatoria y no se pueden renovar.
  • Los límites por operación y diarios se configuran de forma independiente y prevalece el menor entre el de la clave y el de la cuenta.

Las claves de retiro de Biabahub viven en estado «desactivada» todo el año y solo se activan durante 2 horas el día del rebalanceo mensual, tras el cual se eliminan.


2. Passphrase y flujo de generación de la API Key

Binance introdujo en la segunda mitad de 2025 el mecanismo Passphrase para usuarios avanzados de API, similar a la práctica temprana de OKX. Actúa como segunda cerradura además de la firma.

2.1 Creación de una clave en 5 pasos

  1. Inicia sesión en la web de Binance y pulsa avatar → «Gestión de API».
  2. Introduce una etiqueta para la clave (convención Biabahub: uso-estrategia-servidor-YYYYMM, por ejemplo spot-grid-us1-202607) y pulsa «Crear API».
  3. Elige entre «HMAC-SHA256 generado por el sistema» o «Ed25519 con clave pública subida»; recomendamos Ed25519 (el servidor de Binance no guarda tu clave privada).
  4. Tras validar el código por correo y el 2FA, la página muestra por única vez el Secret o Passphrase; cópialo de inmediato en el gestor de contraseñas.
  5. Edita la clave, marca los permisos necesarios, vincula la IP whitelist y define la fecha de expiración.

P: ¿Qué ventajas ofrece Ed25519 frente a HMAC-SHA256? R: Tres. Primero, el servidor de Binance solo guarda tu clave pública; ni siquiera una fuga interna de Binance filtra tu clave privada. Segundo, el algoritmo de firma es más resistente cuánticamente (en términos relativos). Tercero, cada firma incluye un nonce aleatorio, elevando el coste de un ataque de replay. La desventaja: algunas librerías cliente antiguas no lo soportan; hay que usar las últimas versiones de python-binance o ccxt.

2.2 Recomendaciones para nombrar las claves

Campo Ejemplo Descripción
Uso spot / futures / readonly / withdraw Muestra el nivel de permiso de un vistazo
Estrategia grid / martin / dca / monitor Facilita rotaciones futuras
Servidor us1 / hk2 / local Coincide con la IP whitelist
Año-mes 202607 Caducidad = creación + 90 días

Ejemplos negativos: test, api1, 我的 Key. El 40 % de los incidentes registrados por Biabahub tiene relación con esta clase de nombres, porque el operador que hereda la clave no sabe a quién pertenece ni si es seguro eliminarla.


3. IP whitelist: el paso más saltado y también el más crítico

Una clave sin IP whitelist equivale a colgar la llave de casa en un poste; cualquiera con Key + Secret entra sin más.

3.1 Flujo estándar para añadir IP whitelist

  1. En el servidor de la estrategia ejecuta curl ifconfig.me o curl ipinfo.io/ip para obtener la IP pública de salida.
  2. Si usas cloud, confirma la IP desde el panel de IP elástica / NAT de salida (no confundas con la IP privada).
  3. Si haces salida por CDN o proxy, asegúrate de tomar la IP final de salida, no la de entrada.
  4. Vuelve a la página de gestión de API de Binance, edita la clave y pega la IP; se admiten hasta 4 IP.
  5. Guarda y prueba de inmediato desde el servidor con curl -H "X-MBX-APIKEY: ..." contra /api/v3/account; si la respuesta es correcta, has terminado.

3.2 Errores frecuentes con la IP whitelist

Error Consecuencia Buena práctica
Poner IP privada (192.168 / 10.x) Binance la rechaza, la clave queda inservible Introduce la IP pública
Poner la IP de entrada del CDN La IP de salida cambia y deja de funcionar Usa la IP final del NAT de salida
Poner IP dinámica del hogar Al cambiar la IP la clave muere Configura DDNS y actualiza a mano
Poner 0.0.0.0/0 Equivalente a no tener whitelist Absolutamente prohibido
Compartir una misma IP entre varios servidores Comprometer uno hunde a todos Una estrategia por IP

Todas las claves productivas de Biabahub están ancladas a una única IP elástica fija; cualquier cambio requiere aprobación por ticket.

3.3 Cambio del coste de ataque con y sin IP whitelist

Escenario Sin IP whitelist Con IP whitelist Cambio en el coste de ataque
Secret filtrado en GitHub 30 segundos hasta el bot escáner Inútil De 0 a comprometer tu servidor
Logs del servidor comprometidos Uso inmediato Inútil Necesita control adicional de la IP whitelist
Empleado se marcha con la clave Uso inmediato Inútil Requiere entrar a la red interna

Conclusión: la IP whitelist eleva la barrera de «ingeniería social / credential stuffing» a «intrusión al servidor», un beneficio defensivo de órdenes de magnitud.


4. Ejemplo mínimo ejecutable de firma HMAC-SHA256

Aquí tienes el código para que puedas contrastar tu implementación.

4.1 Implementación de referencia en Python

import time
import hmac
import hashlib
import urllib.parse
import requests

API_KEY = "leer desde gestor de contraseñas, nunca hardcodear"
API_SECRET = b"leer desde gestor de contraseñas, nunca hardcodear"
BASE_URL = "https://api.binance.com"

def sign(params: dict) -> str:
    params["timestamp"] = int(time.time() * 1000)
    query = urllib.parse.urlencode(params)
    signature = hmac.new(API_SECRET, query.encode(), hashlib.sha256).hexdigest()
    return query + "&signature=" + signature

def get_account():
    query = sign({"recvWindow": 5000})
    r = requests.get(
        f"{BASE_URL}/api/v3/account?" + query,
        headers={"X-MBX-APIKEY": API_KEY},
        timeout=5,
    )
    r.raise_for_status()
    return r.json()

4.2 Seis reglas de hierro para firmar con seguridad

  1. El Secret nunca entra al repositorio: inyéctalo por variables de entorno o gestores como AWS Secrets Manager o HashiCorp Vault.
  2. recvWindow ≤ 5000 ms: por defecto son 5000; más de 60000 lo rechaza el servidor; cuanto mayor sea, más peligrosa es la ventana de replay.
  3. Sincroniza NTP: si la diferencia entre servidor y Binance excede recvWindow recibirás -1021; también es una defensa contra replay.
  4. Ofusca los logs de peticiones: cualquier signature= en los logs debe enmascarar los últimos 32 caracteres.
  5. Rollback ante excepciones: tres fallos consecutivos de firma disparan alerta; puede ser Secret revocado o servidor comprometido.
  6. Timeout máximo: fija timeout ≤ 5s en todas las peticiones para evitar conexiones secuestradas y colgadas.

5. Rotación cada 90 días y revocación de emergencia

5.1 Cadencia de rotación estándar

  • Clave de retiro: expira a los 90 días por imposición de Binance.
  • Clave de trading: rotación cada 90 días por norma interna de Biabahub, alineada con la de retiro.
  • Clave de solo lectura: rotación cada 180 días para reducir carga operativa.
  • Flujo de rotación: crear nueva → desplegar en la estrategia → validar 24 horas sin anomalías → revocar la antigua. No permitir convivencia superior a 72 horas.

5.2 SOP de revocación de emergencia

Ante la sospecha de fuga, sigue este orden:

  1. En la página de gestión de API pulsa «Eliminar API» para desactivarla al instante.
  2. Simultáneamente detén el proceso de la estrategia que usa la clave, evitando que los -2015 en reintentos saturen la monitorización.
  3. Si la clave con permiso de retiro se filtró, congela además la cuenta con el botón «Seguridad → Congelación de emergencia».
  4. Revisa órdenes y retiros de las últimas 24 horas y exporta CSV como evidencia.
  5. Presenta un informe de incidente por el canal oficial de tickets, con análisis de la causa raíz de la filtración.
  6. Para el post-mortem, lee también Migración de 2FA de Binance y códigos de respaldo y Configuración de whitelist de retiro de Binance para reforzar el perímetro defensivo global.

6. Caso real: reproducción técnica de un vaciado en 30 segundos

En marzo de 2026 Biabahub gestionó un incidente típico: el usuario A subió a un repositorio público de GitHub código de depuración con API_KEY y API_SECRET sin ofuscar y sin IP whitelist.

Línea de tiempo Acción del atacante Pérdida del usuario
T+0s Push a GitHub dispara los bots escaneadores 0
T+8s El bot captura Key/Secret y valida su vigencia 0
T+12s El atacante abre un futuro perpetuo de BTC con 125x en contra Margen bloqueado
T+22s El atacante recoge beneficios con una orden opuesta desde su propia vault A liquidado
T+30s El atacante se lleva 8,4 BTC; A pierde 12,6 BTC Totales

Post-mortem:

  • Con IP whitelist activa, el atacante habría tenido que comprometer el servidor de A antes; el coste sube de 0 al orden de 100 000 USD.
  • Con separación del permiso de retiro, el atacante no puede llevarse el efectivo directamente y depende del arbitraje en mercado.
  • Con notificaciones por correo y push activadas, A habría recibido alerta en T+30s (aunque tarde para actuar).

Preguntas frecuentes

P1: ¿Existen límites de velocidad en la API de Binance?

Sí. Los endpoints REST se limitan por IP, con un peso máximo de 6000/min; los de envío de órdenes se limitan por UID, unos 200/10s. Superarlos devuelve 429 o 418; el 418 bloquea la IP durante 5-10 minutos. La estrategia de Biabahub incorpora backoff, con retroceso lineal al recibir 429.

P2: ¿Se pueden aislar claves por subcuenta?

Sí. Cada subcuenta puede generar claves propias sin compartir permisos con la cuenta principal. Las empresas deberían separar por línea de negocio en subcuentas y claves, limitando el radio de explosión a esa subcuenta.

P3: ¿Cómo se protege la clave privada Ed25519?

Se genera una única vez y se elimina tras usarla. Flujo recomendado por Biabahub: genera el par de claves con OpenSSL en local, sube la pública a Binance, importa la privada de inmediato en un KMS (AWS KMS, GCP KMS…) y destruye la copia local. El proceso de la estrategia obtiene la privada del KMS y la mantiene solo en memoria; al reiniciar el proceso vuelve a solicitarla.

P4: ¿Qué hago si la API devuelve constantemente el error -1021 de timestamp?

Casi siempre es NTP mal configurado o con demasiado drift. Ejecuta sudo timedatectl set-ntp true en Linux o w32tm /resync en Windows. Si el error persiste, compara el resultado de GET /api/v3/time con la hora local: la diferencia debe ser menor que recvWindow.

P5: ¿Puedo usar la misma clave para spot y futuros?

Técnicamente sí; los permisos de spot y futuros son interruptores independientes. Pero Biabahub recomienda separar: la magnitud de riesgo de una orden spot y de una liquidación de futuros es incomparable; compartir clave supone que un bug en una estrategia arrastre a la otra.

P6: ¿Avisa Binance antes de que caduque una API Key?

Sí, envía correo 7 días antes de la caducidad. Biabahub aconseja añadir además un contador propio en la estrategia para no depender de un solo canal.

P7: Tras revocar una clave antigua, ¿puedo seguir consultando el histórico de órdenes?

Sí. El historial está desacoplado de la clave; revocarla solo cierra el canal de firma, pero las órdenes permanecen en el flujo de la cuenta y se pueden exportar en CSV desde la web.


Aviso de riesgo

Este artículo fue compilado por el equipo de Biabahub con fines educativos sobre la configuración de API Key e IP whitelist. No constituye asesoría de inversión, jurídica ni promesa alguna sobre el resultado de estrategias concretas. El trading programático implica apalancamiento, liquidaciones, slippage, latencia de red, fallos del exchange y otros riesgos. El código de ejemplo es puramente docente; antes de operar en real hay que validarlo con backtest completo, paper trading y una fase de real con capital pequeño. El usuario asume el resultado de la estrategia. Una API Key filtrada debe revocarse inmediatamente; cualquier petición del tipo «envíamela para ayudarte a diagnosticarlo» es un fraude: Binance nunca solicita Secret, Passphrase ni clave privada. La IP whitelist no es infalible: si el servidor cae, el atacante puede usar la clave desde la IP legítima; por eso también hay que aplicar mínimo privilegio, parcheo periódico y auditoría de logs al propio servidor. La rotación cada 90 días es un mínimo, no un objetivo: para cuentas de alto valor recomendamos rotar cada 30 días o por evento. Si necesitas registrarte por vía oficial, entra al Sitio Oficial de Binance; si necesitas descargar la aplicación, obtén la App Oficial de Binance.

Documento publicado el 2026-07-01. Próxima revisión prevista: 2026-10-01.