Guía de integración de la API de WEEX: Autenticación, límites y la trampa del error 403

La mayoría de las guías sobre la API de un exchange de criptomonedas se detienen en "crea una clave y apunta tu bot hacia ella". Eso te lleva a tu primer -1052, no a una integración funcional. La API de WEEX es un sistema de dos capas: spot y futuros residen en dominios diferentes con esquemas de órdenes distintos, y los fallos que más tiempo cuestan a los desarrolladores no son conceptuales. Son un encabezado User-Agent faltante, un reloj con un desfase de 31 segundos y un par de trading que existe en el exchange pero no está habilitado para acceso programático.

Esta guía recorre la integración de la API de WEEX de principio a fin: qué cubre la API, cómo aprovisionar una clave que no te bloquee, cómo se construye realmente la firma, los límites de tasa que encontrarás en producción y los errores específicos que rompen la mayoría de los primeros intentos. Cada cifra aquí proviene de la documentación de WEEX V3 a fecha de agosto de 2026.

Qué cubre la API de WEEX y qué aún no

La API de WEEX expone dos superficies REST independientes más una capa WebSocket. No son intercambiables, y esta es la primera decisión estructural que una integración debe acertar.

La cobertura es real pero limitada. El anuncio de la beta de la OpenAPI de WEEX enumera más de 140 pares soportados, pero la división es desigual: la tabla de futuros llega a unos 130 contratos perpetuos, mientras que la lista de spot ronda los 25 pares. Si tu estrategia opera un par spot de capitalización media, revisa esa lista antes de escribir una línea de código, porque que un par esté activo en la interfaz web no significa que acepte órdenes por API.

Dos ausencias importan para cualquiera que migre desde otra plataforma. Las FAQ de la API spot de WEEX, actualizadas por última vez el 14 de abril de 2026, establecen claramente que actualmente no se admite ni la API FIX ni la integración con TradingView. Si tu stack de ejecución asume una sesión FIX o alertas de webhook enrutadas desde TradingView, tendrás que reconstruir esa capa sobre REST y WebSocket.

También vale la pena señalar: los endpoints V1 y V2 están siendo obsoletos, y WEEX recomienda V3 para nuevas construcciones. El código de ejemplo que encuentres en plataformas de bots de terceros aún puede apuntar a rutas V2.

Cómo crear una clave API de WEEX sin bloquearte

La creación de claves ocurre en la página de gestión de API de WEEX bajo Cuenta. La mecánica toma dos minutos. Las decisiones de configuración llevan más tiempo, y tres de ellas son irreversibles.

1. Crea la clave. Cada cuenta admite hasta 10 grupos de claves API. Las nuevas claves son Read Only por defecto.
2. Selecciona permisos explícitamente. Readonly, Spot y Futures/Contract son independientes. Marcar Spot no otorga acceso a futuros, y una orden de futuros enviada con una clave solo para spot devuelve -1052 INSUFFICIENT_PERMISSIONS en lugar de algo más descriptivo.
3. Establece la frase de contraseña con cuidado. La guía de seguridad de WEEX dice que se usen solo caracteres alfanuméricos; los caracteres especiales en la frase son una fuente documentada de fallos de autenticación. La frase no se puede modificar ni recuperar. Si la pierdes, crea una clave nueva.
4. Vincula una lista blanca de IP. Hasta 10 IPs, separadas por comas. Las claves sin restricciones son el mayor riesgo de custodia en una configuración de API, y WEEX las marca como tales.
5. Espera. Las claves recién creadas o modificadas tardan aproximadamente 15 minutos en propagarse por los sistemas de WEEX. Los desarrolladores suelen interpretar este periodo como una firma rota y empiezan a reescribir código que funciona.

Guarda la APIKey, SecretKey y Passphrase al crearla. Solo la APIKey se puede recuperar después.

Un hábito que vale la pena adoptar desde el primer día: nunca habilites permisos de retiro en una clave que viva en un proceso de trading. Separa las claves de solo lectura para monitoreo de las claves con permisos de trading para ejecución, y dale a cada una su propia vinculación de IP. El costo operativo es de diez minutos; el modo de fallo que evita es total.

Firmar una solicitud de la API de WEEX: La ventana de 30 segundos

Cada llamada privada a la API de WEEX lleva cuatro encabezados más un tipo de contenido:

El mensaje que firmas es una concatenación, y la regla de concatenación cambia dependiendo de si existe una cadena de consulta:

# queryString presente
timestamp + METHOD + requestPath + "?" + queryString + body

# queryString ausente
timestamp + METHOD + requestPath + body

METHOD está en mayúsculas. body es la cadena JSON cruda, idéntica byte a byte a lo que transmites: serializa una vez, firma esa cadena, envía esa cadena. Re-serializar entre firmar y enviar es el fallo de firma autoinfligido más común, porque el orden de las claves o los espacios en blanco cambian y el hash ya no coincide.

Un ejemplo de la especificación de firma de WEEX, obteniendo profundidad:

1591089508404GET/api/v3/market/depth?symbol=BTCUSDT&limit=20

Y una orden:

1561022985382POST/api/v3/order{"symbol":"BTCUSDT","side":"BUY","type":"LIMIT","timeInForce":"GTC","quantity":"1","price":"68900","newClientOrderId":"my-order-001"}

Luego HMAC-SHA256 con tu clave secreta, luego Base64.

La restricción que atrapa a la gente en producción es el reloj. Las solicitudes se rechazan si ACCESS-TIMESTAMP se desvía más de 30 segundos del tiempo del servidor de WEEX, devolviendo -1046 ACCESS_TIMESTAMP_EXPIRED. Los contenedores con relojes desfasados, arranques en frío serverless y máquinas virtuales sin NTP fallan de forma intermitente, lo cual es peor que fallar constantemente, porque parece un problema de red. Consulta el endpoint de tiempo del servidor al iniciar, guarda el desfase y aplícalo a cada marca de tiempo.

Los canales privados de WebSocket usan un mensaje más corto: timestamp + "/v3/ws/private", firmado de la misma manera: mismos encabezados, mismos pasos de HMAC-SHA256 y Base64, solo una cadena diferente.

Límites de tasa de la API de WEEX que realmente alcanzarás

Exceder un límite devuelve un HTTP 429 y un bloqueo de 10 segundos. WEEX divide la limitación en dos presupuestos independientes, que es la parte que la mayoría de las integraciones modelan incorrectamente.

Límites de tasa obtenidos de la documentación y FAQ de la API spot de WEEX, vigentes al 14 de abril de 2026.

La distinción que importa: la colocación de órdenes está limitada por cuenta, todo lo demás por IP. Los endpoints de colocación consumen cero peso de IP; el contador de IP en sus encabezados de respuesta lee 0. Así que ejecutar tres estrategias detrás de una IP no triplica tu presupuesto de órdenes (es por cuenta), pero sí triplica tu consumo del pool de 500 de peso de IP para datos de mercado y consultas.

Lee los encabezados en lugar de adivinar. Cada respuesta lleva X-USED-WEIGHT-1M y X-REMAINING-WEIGHT-1M; los endpoints de órdenes llevan X-ORDER-COUNT-10S y X-ORDER-REMAINING-10S. Un retroceso impulsado por el encabezado de peso restante superará cualquier intervalo de espera fijo que codifiques.

Las órdenes Spot y de Futuros no comparten esquema

Esta es la divergencia que rompe las capas de abstracción compartidas, y no se destaca de forma prominente en ninguna parte de la documentación; la encuentras comparando las dos páginas de órdenes.

Esa última fila merece énfasis. El endpoint de futuros puede devolver HTTP 200 con {"success": false, "errorCode": "...", "errorMessage": "..."}. El código que solo verifica el estado HTTP registrará una orden rechazada como ejecutada y procederá alegremente a construir una posición que no tiene. Verifica success explícitamente en cada respuesta de orden de futuros.

También hay una inconsistencia en la documentación misma. La página de Parámetros Públicos de la API spot todavía enumera enums en minúsculas (buy, sell, limit, market) junto con un campo force, mientras que los endpoints de órdenes V3 bajo Trade usan BUY, SELL, LIMIT y timeInForce en mayúsculas. Las páginas de endpoints reflejan V3; la página de parámetros lleva valores de la era V2. Cuando no estén de acuerdo, confía en la página del endpoint, y envía -1116 INVALID_ORDER_TYPE a tus registros como señal de que copiaste del lugar equivocado.

Los símbolos distinguen entre mayúsculas y minúsculas y deben estar en mayúsculas. btcusdt devuelve -1121.

Cinco errores que rompen la mayoría de las integraciones de la API de WEEX

El 403 de WebSocket es el que vale la pena interiorizar. No tiene nada que ver con tus credenciales: el borde de WEEX rechaza las conexiones sin encabezado, por lo que una suscripción privada perfectamente firmada falla igual que una no firmada. Los desarrolladores depuran su firma durante una hora antes de encontrarlo. WEEX documenta esto en las FAQ de la API spot, y la solución es una línea.

Mantén las conexiones vivas correctamente también. El servidor envía pings periódicos — {"event":"ping","time":"..."} en canales públicos, {"type":"ping","time":"..."} en privados — y espera {"method":"PONG","id":1} de vuelta. Si fallas más de 10, el servidor cierra la conexión. Una desconexión silenciosa durante una sesión volátil es cómo un bot termina operando en un libro de órdenes obsoleto.

La taxonomía completa de errores vive en las FAQ de la API spot de WEEX y referencia de códigos de error.

Prueba en modo Demo antes de arriesgar margen real

WEEX ofrece un entorno de futuros simulado accesible a través del mismo patrón autenticado, bajo /capi/v3/sim/. El endpoint de saldo demo devuelve posiciones denominadas en SUSDT — USDT simulado — junto con availableBalance, frozen y unrealizePnl. PlaceOrder, GetAllPositions y GetOrderHistory de demo están todos expuestos.

Úsalo para lo que realmente es bueno: validar la construcción de tu firma, tu manejo de errores y tu lógica de reconexión. No lo uses para validar la economía de la estrategia. Un entorno simulado no tiene posición en cola, ni comportamiento de llenado parcial bajo estrés, ni deslizamiento (slippage): las tres cosas que separan un backtest de un P&L.

Para calibración en el lado real: WEEX cotizó perpetuos de BTC a 65.088,80 USDT en su mercado de futuros BTC/USDT al 21 de agosto de 2026, con apalancamiento disponible hasta 400x. Ese techo de apalancamiento es una razón para ser conservador con un sistema automatizado, no una característica en la que apoyarse. Un error de firma que dispara órdenes duplicadas es sobrevivible a 3x. No lo es a 400x.

La versión corta

La API de WEEX es sencilla una vez que tres cosas son ciertas: tu reloj está sincronizado dentro de la ventana de 30 segundos, tu WebSocket envía un User-Agent y tu código de futuros verifica el campo success en lugar del estado HTTP. Todo lo demás — permisos, listas blancas de IP, retroceso de límites de tasa — es trabajo estándar de integración de exchange.

Lo único que no es estándar, y por lo que vale la pena presupuestar tiempo, es la divergencia de esquemas entre spot y futuros. Una abstracción de órdenes compartida en ambas superficies parecerá correcta en la revisión y fallará en producción. Constrúyelos como dos adaptadores.

¿Listo para empezar? Crea una clave en Cuenta → Gestión de API en WEEX, apúntala al modo demo primero y solo amplía los permisos una vez que tus rutas de reconexión y error estén probadas.

FAQ

1. ¿Es gratis usar la API de WEEX?

Sí. No hay cargo separado por el acceso a la API. Pagas las tarifas estándar de trading spot o futuros en las órdenes ejecutadas, igual que en el trading manual.

2. ¿Cuántas claves API puedo crear en WEEX?

Hasta 10 grupos de claves API por cuenta. Cada clave se puede configurar independientemente con permisos de Readonly, Spot o Futures/Contract y su propia lista blanca de IP de hasta 10 direcciones.

3. ¿Por qué mi clave API de WEEX funciona en Postman pero no desde mi servidor?

Casi siempre es la lista blanca de IP (-1056) o el desfase del reloj (-1046). Los entornos en la nube frecuentemente salen desde una IP NAT rotativa que no está en tu lista blanca, y los contenedores sin NTP se desfasan más allá de la ventana de firma de 30 segundos.

4. ¿La API de WEEX admite webhooks de FIX o TradingView?

No. A fecha de la actualización de documentación de abril de 2026, no se admite ni la API FIX ni la integración con TradingView. REST y WebSocket son los transportes disponibles.

5. ¿Cuánto tiempo tarda en funcionar una nueva clave API de WEEX?

Aproximadamente 15 minutos para que una clave nueva o modificada se propague. Los fallos de autenticación dentro de esa ventana son esperados y no son un problema de firma.

6. ¿Puedo probar estrategias de API de WEEX sin fondos reales?

Sí, para futuros. Los endpoints de demo bajo /capi/v3/sim/ aceptan las mismas solicitudes autenticadas y devuelven saldos denominados en SUSDT. Trátalos como un banco de pruebas de integración, no como un backtest de estrategia.

Advertencia de riesgo

Los criptoactivos son volátiles y operarlos puede resultar en una pérdida parcial o total de capital. El trading por API concentra ese riesgo en lugar de reducirlo: un error de lógica, un rechazo no manejado o un feed de WebSocket obsoleto pueden ejecutar docenas de órdenes no deseadas antes de que un humano se dé cuenta. WEEX ofrece apalancamiento de hasta 400x en algunos contratos perpetuos, lo que magnifica tanto las señales correctas como las incorrectas: un sistema automatizado ejecutándose con alto apalancamiento puede ser liquidado en un solo movimiento adverso.

Riesgos específicos a tener en cuenta en un despliegue de API: riesgo de custodia por claves sin restricciones o filtradas, que otorgan control total de trading de la cuenta; riesgo operativo por desfase de reloj, bloqueos de límite de tasa y conexiones caídas que dejan posiciones sin gestionar; riesgo de liquidez en pares con poco volumen donde una orden de mercado mueve el libro en tu contra; y riesgo de contraparte y regulatorio, ya que la disponibilidad del trading por API y pares específicos puede cambiar sin previo aviso. Vincula una lista blanca de IP, mantén los permisos de retiro desactivados en las claves de trading, limita el tamaño de la posición en el código en lugar de en la intención y prueba las rutas de error en modo demo antes de desplegar capital. Nada de esto es asesoramiento de inversión.