Guía de la API de WEEX: Desde la clave API hasta tu primera orden firmada

La mayoría de las integraciones de la API de WEEX no fallan por la lógica de la estrategia. Fallan en la primera hora, por cuatro cosas que no son obvias hasta que te chocas con ellas: la clave que acabas de crear aún no está activa, el par que quieres operar no está en la lista blanca de la API, tu conexión WebSocket es rechazada porque no enviaste un encabezado User-Agent, y tu firma falla por un byte porque firmaste un cuerpo re-serializado en lugar de la cadena exacta que enviaste.

Esta guía recorre la API de WEEX de principio a fin: creación de claves, permisos, la regla de firma, límites de tasa, los códigos de error que realmente detienen las compilaciones y los endpoints de trading en papel que te permiten probar todo sin arriesgar capital. Todo lo siguiente fue verificado con la documentación oficial de la V3 el 21 de agosto de 2026.

Qué cubre la API de WEEX: spot, futuros y WebSocket

La API de WEEX se divide en dos productos independientes con dos dominios REST independientes. El spot reside en api-spot.weex.com bajo la ruta /api/v3. Los futuros residen en api-contract.weex.com bajo la ruta /capi/v3. Comparten un esquema de firma y un conjunto de encabezados, pero nada más: banderas de permiso separadas, hosts de WebSocket separados, parámetros de orden separados.

Los endpoints se dividen en dos clases de acceso. Los endpoints públicos (hora del servidor, profundidad del libro de órdenes, klines, tasa de financiación, tickers de 24h) no necesitan autenticación alguna, lo que los convierte en la forma más rápida de confirmar que tu ruta de red funciona antes de tocar la firma. Los endpoints privados (saldos, posiciones, órdenes) requieren la firma completa de cuatro encabezados en cada solicitud.

Para cualquier cosa a nivel de tick, WEEX te dirige hacia WebSocket en lugar de polling REST, y es la decisión correcta: los canales públicos llevan streams de ticker, profundidad y operaciones, y un canal privado lleva actualizaciones de cuenta, posición y órdenes. Hacer polling de profundidad a través de REST para construir un libro de órdenes consumirá tu presupuesto de peso de IP sin beneficio alguno.

Un punto de referencia fechado para la escala: al 21 de agosto de 2026, el contrato perpetuo BTC/USDT cotizaba a un último precio de 65.088,8 USDT en el libro de futuros de WEEX, el mismo tick que devuelve tu llamada /capi/v3/market/ticker24h.

Cómo crear una clave API de WEEX y configurar permisos

Las claves se crean desde Cuenta → Gestión de API en la plataforma web. Cada cuenta puede tener hasta 10 grupos de claves API.

La creación devuelve tres valores, y el tercero es el que la gente pierde:

• APIKey — identificador público, enviado en el encabezado ACCESS-KEY.
• SecretKey — el secreto de firma HMAC. Se muestra una vez.
• Passphrase — definida por el usuario, enviada en ACCESS-PASSPHRASE. No se puede cambiar ni recuperar. Si la pierdes, debes recrear la clave.

Tres detalles de configuración causan más tickets de soporte que todo lo demás combinado:

1. Las claves nuevas son de solo lectura por defecto. El permiso de trading es una casilla de verificación separada, y es específica del producto: Spot para trading spot, Futures para contratos. Marcar una no habilita la otra. Colocar una orden con una clave de solo lectura devuelve -1052.
2. Las claves tardan unos 15 minutos en propagarse globalmente. Una clave que se autentica bien y luego falla en un endpoint diferente generalmente es porque aún no está completamente activa. Espera antes de empezar a depurar tu firma.
3. Mantén la passphrase alfanumérica. WEEX recomienda explícitamente no usar caracteres especiales. Los errores de codificación en caracteres especiales son una clase de error genuinamente miserable de perseguir.

Vincula una lista blanca de IP mientras estás en la pantalla de creación. Una clave no vinculada es una credencial al portador que funciona desde cualquier lugar de internet, y si una máquina que la contiene es comprometida, la lista blanca es lo único que se interpone entre un atacante y tus posiciones.

API de spot de WEEX vs API de futuros: las diferencias que importan

Esta es la tabla que debes mantener abierta mientras desarrollas. Los dos productos parecen simétricos y no lo son.

Dos de estos son los que más afectan. Futuros requiere newClientOrderId en cada orden, por lo que una base de código diseñada primero para spot que lo omita será rechazada en el momento en que la apuntes a contratos. Y POST_ONLY existe solo en futuros: una estrategia de solo maker escrita contra la API de spot no tiene forma nativa de garantizar que no cruce el spread.

Los parámetros TP/SL de futuros merecen más atención de la que suelen recibir. Adjuntar tpTriggerPrice y slTriggerPrice a la orden de entrada significa que tu stop existe en el exchange desde el momento en que se abre la posición, en lugar de ser colocado por una llamada de seguimiento que podría no sobrevivir a un bloqueo del proceso o una partición de red. También puedes elegir la fuente de activación por tramo a través de TpWorkingType y SlWorkingType: MARK_PRICE para el stop es el valor predeterminado más seguro, ya que CONTRACT_PRICE puede verse afectado por una impresión de última operación en un par ilíquido.

Cómo firmar una solicitud de API de WEEX correctamente

Cada llamada privada lleva cuatro encabezados: ACCESS-KEY, ACCESS-SIGN, ACCESS-PASSPHRASE, ACCESS-TIMESTAMP, además de Content-Type: application/json.

La regla de firma es idéntica en ambos dominios. Construye esta cadena:

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

Elimina el ? y queryString cuando no haya parámetros de consulta; elimina body cuando no haya ninguno. Aplica HMAC-SHA256 con tu SecretKey, luego codifica el resultado en Base64.

import base64, hashlib, hmac, json, time, requests

API_KEY, SECRET, PASSPHRASE = "...", "...", "..."
BASE = "https://api-contract.weex.com"
path = "/capi/v3/order"
body = json.dumps({
    "symbol": "BTCUSDT", "side": "BUY", "positionSide": "LONG",
    "type": "LIMIT", "timeInForce": "GTC", "quantity": "0.01",
    "price": "60000", "newClientOrderId": "my-order-0001",
}, separators=(",", ":"))

ts = str(int(time.time() * 1000))
message = ts + "POST" + path + body
sign = base64.b64encode(
    hmac.new(SECRET.encode(), message.encode(), hashlib.sha256).digest()
).decode()

r = requests.post(BASE + path, data=body, headers={
    "ACCESS-KEY": API_KEY, "ACCESS-SIGN": sign,
    "ACCESS-PASSPHRASE": PASSPHRASE, "ACCESS-TIMESTAMP": ts,
    "Content-Type": "application/json",
})

Nota data=body, no json=payload. Firma los bytes exactos que transmites. Si tu cliente HTTP re-serializa el dict (reordenando claves o insertando espacios después de los separadores), el servidor calcula un resumen diferente y obtienes -1047, sin ninguna pista de que la causa fue un espacio en blanco.

La ventana de tiempo es de 30 segundos respecto a la hora del servidor de WEEX. Si el reloj de tu host se desvía, las solicitudes comienzan a fallar intermitentemente de una manera que parece un error de firma. Llama a GET /capi/v3/market/time y rastrea el desplazamiento en lugar de confiar en la hora local.

Los canales privados de WebSocket se firman de manera diferente y esto atrapa a la gente: el mensaje es solo timestamp + requestPath, donde requestPath es /v3/ws/private. Sin método, sin cuerpo.

Una peculiaridad de la documentación que vale la pena conocer antes de copiar y pegar: la página de Firma de futuros ilustra la regla usando rutas de spot (/api/v3/order). La regla es correcta; las rutas de ejemplo no son las de futuros. Usa /capi/v3/... cuando estés en el dominio de contratos.

Límites de tasa de la API de WEEX: dos cubetas, no una

WEEX ejecuta dos contadores de límite de tasa independientes, y confundirlos es la razón por la que los bots obtienen 429 que no esperaban.

El detalle consecuente: la colocación de órdenes consume cero peso de IP, y las cancelaciones y consultas consumen cero conteo de órdenes. Son libros de contabilidad genuinamente separados. Un bucle de creación de mercado que coloca y cancela agresivamente agotará la cubeta de ÓRDENES al colocar, mientras que su tráfico de cancelación drena silenciosamente el peso de IP, y ninguno de los contadores te advierte sobre el otro.

Lee los encabezados en lugar de contar las solicitudes del lado del cliente. X-REMAINING-WEIGHT-1M y X-ORDER-REMAINING-1M regresan en cada llamada y reflejan la vista del servidor, que es la única vista que importa. Exceder un límite devuelve HTTP 429 y activa una prohibición de 10 segundos, y continuar martilleando a través de un 429 es la ruta más rápida para que el control de riesgos deshabilite tu acceso a la API.

Si estás ejecutando varias estrategias desde una caja, recuerda que la cubeta de IP es compartida. Dos bots en un servidor compiten por el mismo peso de 500 por cada 10 segundos.

Los errores de la API de WEEX que detienen la mayoría de las integraciones

Las respuestas de error son un par de código y mensaje. Estos son los que aparecen durante la integración en lugar de en producción:

-1058 merece un flujo de trabajo específico. No todos los contratos de WEEX están habilitados para trading vía API, y no hay forma de inferir cuál desde la interfaz de usuario. Llama a GET /capi/v3/market/apiTradingSymbols al inicio, almacena el array en caché y valida los símbolos contra él antes de que tu estrategia construya una orden. Esa única verificación elimina toda una clase de fallos en tiempo de ejecución.

Dos más que parecen errores y no lo son. Un handshake de WebSocket que devuelve 403 casi siempre significa que omitiste el encabezado User-Agent: el contenido es arbitrario, pero el firewall descarta las conexiones sin él. Y los documentos actualmente no están de acuerdo sobre los fallos de cancelación: la referencia de códigos de error asigna -1054 a un error genérico del sistema y -3200 a "la orden no existe", mientras que las preguntas frecuentes de futuros atribuyen "la orden no existe" a -1054. Maneja ambos códigos en las rutas de cancelación en lugar de ramificarte en uno.

Prueba primero en los endpoints de trading en papel de WEEX

WEEX agregó endpoints de trading simulado en el dominio de futuros, y reflejan la superficie real lo suficientemente cerca como para ser una prueba en seco real en lugar de un juguete:

• GET /capi/v3/sim/balance — saldos simulados, denominados en SUSDT
• GET /capi/v3/sim/position/allPosition — posiciones, incluidos pares largo/corto en modo cobertura
• POST /capi/v3/sim/order — colocación de órdenes en los tipos habituales
• GET /capi/v3/sim/order/history — rellenos simulados históricos

Mismo dominio, mismos encabezados, misma regla de firma. Cambiar /capi/v3/order por /capi/v3/sim/order es a menudo el único cambio necesario para ejecutar una prueba de integración completa.

Úsalos para validar las partes de tu sistema que solo fallan en condiciones reales: lógica de reconexión después de un WebSocket caído, si tu máquina de estados de órdenes se recupera cuando llega un relleno antes del reconocimiento REST, si el tamaño de tu posición hace lo correcto en el techo de apalancamiento. Esos son los fallos que cuestan dinero en producción, y ninguno de ellos requiere capital real para aparecer.

Vale la pena saber antes de diseñar alrededor de ellos: WEEX actualmente no admite la ejecución de webhooks de TradingView ni una puerta de enlace FIX. Si tu estrategia asumía cualquiera de los dos, presupuesta REST y WebSocket en su lugar.

Conclusión

La API de WEEX es sencilla una vez que internalizas que spot y futuros son dos productos que comparten un esquema de firma y casi nada más. Haz bien los cuatro encabezados, firma los bytes exactos que envías, almacena en caché la lista blanca de símbolos de trading de la API, lee los encabezados de límite de tasa en lugar de contar las solicitudes, y maneja -1047, -1052 y -1058 explícitamente: eso cubre la gran mayoría de lo que sale mal.

La secuencia que menos tiempo desperdicia: crea una clave con permiso de solo lectura, confirma que un endpoint público responde, haz que funcione una lectura privada firmada, ejecuta tu estrategia completa contra los endpoints de trading en papel, y solo entonces habilita el permiso de trading y vincula una lista blanca de IP. Las referencias completas de los endpoints residen en la documentación de la API de futuros de WEEX y la documentación de la API de spot de WEEX, con detalles de permisos y límites de tasa recopilados en las preguntas frecuentes de la API de futuros.

FAQ

1. ¿Necesito claves API de WEEX separadas para spot y futuros?

No: una clave puede llevar ambos permisos. Pero son casillas de verificación separadas, y cada una está desactivada por defecto. Una clave con solo Spot marcado devolverá -1052 en cada orden de futuros, y viceversa.

2. ¿Cuáles son los límites de tasa de la API de WEEX?

Dos cubetas independientes: 500 de peso por cada 10 segundos por IP para endpoints REST generales, y 300 colocaciones de órdenes por minuto por cuenta para futuros. WebSocket está limitado a 20 conexiones concurrentes por IP, 100 canales por conexión. Exceder cualquiera de ellos devuelve HTTP 429 y una prohibición de 10 segundos.

3. ¿Por qué mi clave API de WEEX devuelve -1049 justo después de crearla?

Las claves nuevas y modificadas tardan unos 15 minutos en propagarse por los sistemas de WEEX. Si la clave es nueva, espera antes de depurar más. Si persiste, verifica si la passphrase contiene caracteres especiales: WEEX recomienda solo alfanuméricos.

4. ¿Puedo operar todos los pares de WEEX a través de la API?

No. Solo los pares en la lista blanca de trading de la API están disponibles programáticamente. Llama a GET /capi/v3/market/apiTradingSymbols para obtener la lista actual; cualquier cosa fuera de ella devuelve -1058.

5. ¿WEEX admite alertas de TradingView o FIX?

Ninguno es compatible a partir de la actualización de la documentación de abril de 2026. La automatización se ejecuta a través de las API REST y WebSocket.

6. ¿Cómo pruebo una estrategia de API de WEEX sin arriesgar fondos?

Usa los endpoints de trading en papel de futuros bajo /capi/v3/sim/. Aceptan la misma autenticación y firma que los endpoints reales y se liquidan en SUSDT simulados.

Advertencia de riesgo

Los activos criptográficos son volátiles y pueden perder valor rápidamente; operarlos puede resultar en una pérdida parcial o total de capital. El trading vía API concentra ese riesgo en lugar de reducirlo. Los sistemas automatizados pueden colocar cientos de órdenes antes de que un humano note una falla, y un error de firma, una alimentación de precios obsoleta o una reconexión no manejada pueden abrir posiciones que nadie pretendía. El trading de futuros añade riesgo de apalancamiento: con un apalancamiento disponible de hasta 400× en algunos contratos de WEEX, los movimientos adversos pueden liquidar una posición en segundos, y usar CONTRACT_PRICE como disparador de stop en un mercado poco líquido te expone a stop-outs impulsados por mechas. Las claves API también son un riesgo de custodia: una clave no vinculada con permiso de trading es una credencial activa que funciona desde cualquier IP en internet. Vincula una lista blanca de IP, mantén el permiso de trading desactivado hasta que tu integración esté probada contra los endpoints de trading en papel, y dimensiona las posiciones asumiendo que tu propio código eventualmente se comportará mal.