¿Cómo crear una clave de API de WEEX? Seguí nuestros pasos y conectate a los mercados de WEEX

La API de WEEX permite que desarrolladores y traders algorítmicos se conecten directamente a los mercados spot y de futuros USDT-M de WEEX: pueden obtener datos de mercado, administrar cuentas y colocar órdenes mediante programación, en vez de hacerlo desde la interfaz web o de la app. Esta guía explica todo el proceso para crear una clave de API, entender sus permisos, firmar correctamente las solicitudes y mantenerse dentro de los límites de frecuencia de WEEX, sobre la base de la documentación oficial de la API de WEEX.

Esta es una guía técnica, no asesoramiento de inversión. Crear o ejecutar un sistema de trading automatizado implica el mismo riesgo de mercado que el trading manual, además de riesgos técnicos adicionales (los bugs, los problemas de conectividad y los permisos mal configurados pueden causar operaciones o pérdidas no deseadas). Probá todo exhaustivamente antes de ejecutar cualquier estrategia con fondos reales.

Qué cubre la API de WEEX

WEEX ofrece APIs REST y WebSocket para dos líneas principales de productos: Spot y Futuros USDT-M, además de interfaces de API adicionales para integraciones de Broker, Copy Trading y AI Wars. Dentro de Spot y Futuros, la documentación está organizada en cuatro categorías principales:

• Datos de mercado: información del ticker, velas (en todos los intervalos), profundidad del libro de órdenes y flujos de operaciones en tiempo real mediante WebSocket.
• Cuenta: consultas de saldo e información de la cuenta.
• Trade: colocación, cancelación y consulta de órdenes.
• Configuración/Común: hora del servidor, información del exchange y datos de referencia compartidos entre los endpoints.

Cada una de estas categorías está documentada por separado para Spot y Futuros, ya que las rutas de las solicitudes, los parámetros y algunos comportamientos difieren entre ambos productos, aunque el mecanismo de autenticación subyacente es el mismo.

Paso 1: creá tu clave de API

1. Iniciá sesión en tu cuenta de WEEX desde la plataforma web.
2. Entrá en Cuenta → Gestión de API o accedé directamente a la página para crear una clave de API.
3. Seleccioná Crear clave de API y completá la verificación de seguridad requerida (normalmente, esto implica confirmar tu identidad mediante los métodos de 2FA/verificación existentes en tu cuenta).
4. Configurá los permisos de la clave y — muy recomendado — vinculala a una dirección IP o rango de IP específico (se explica en detalle más abajo).
5. Una vez creada, WEEX te mostrará tres credenciales. Guardá las tres de inmediato, ya que se muestran una sola vez:

Cada cuenta de WEEX puede crear hasta 10 grupos de claves de API, algo útil si querés usar claves separadas para distintos bots, estrategias o herramientas de monitoreo de solo lectura, en lugar de reutilizar una única clave en todas partes.

Paso 2: configurá los permisos

De forma predeterminada, toda clave de API nueva tiene acceso Solo lectura. Si querés que la clave pueda colocar operaciones, tenés que habilitar explícitamente el permiso de trading correspondiente al producto con el que la vas a integrar:

• Spot: permite operar en los mercados spot de WEEX.
• Futuros/Contrato: permite operar en los mercados de futuros USDT-M de WEEX.

Estos permisos son independientes. Por eso, una clave destinada exclusivamente a obtener datos de mercado o saldos de cuenta para un dashboard puede mantenerse como Solo lectura, mientras que una clave destinada a ejecutar una estrategia de trading necesita que el permiso de trading correspondiente esté activado explícitamente. Como práctica general de seguridad, conviene crear claves separadas con acceso únicamente a lo que realmente necesita cada integración específica, en lugar de usar una sola clave con todos los permisos en todas partes.

Paso 3: vinculá una dirección IP (muy recomendado)

Al crear o editar una clave de API, podés restringirla para que acepte únicamente solicitudes originadas desde una dirección IP específica o una lista de direcciones. La propia documentación de WEEX lo señala directamente: una clave de API sin vinculación a una dirección IP representa un riesgo de seguridad, ya que cualquiera que obtenga tu APIKey y SecretKey podría usarlas desde cualquier lugar. Vincular la clave a las IP del servidor desde el que realmente funciona tu aplicación reduce significativamente el impacto de una credencial filtrada.

Cómo entender los endpoints públicos y privados

La documentación de la API de WEEX divide los endpoints en dos categorías:

• APIs públicas: se usan para obtener configuraciones y datos de mercado, como precios del ticker o profundidad del libro de órdenes. No requieren autenticación y pueden llamarse sin ninguna clave de API.
• APIs privadas: se usan para administrar cuentas y órdenes, incluidos saldos, colocación de órdenes e historial de órdenes. Toda solicitud privada debe autenticarse mediante el método de firma estandarizado de WEEX, que se describe a continuación.

Firmá tus solicitudes (endpoints privados)

Cada llamada a una API privada debe incluir una firma válida para que WEEX pueda verificar que la solicitud realmente provino de vos y que no fue manipulada. La firma se genera de la siguiente manera:

1. Creá la cadena del mensaje concatenando: timestamp + method (uppercase) + requestPath + "?" + queryString + body; la parte "?" + queryString solo se incluye si la solicitud tiene parámetros de consulta; de lo contrario, se omite.
2. Firmá el mensaje usando HMAC SHA256 con tu SecretKey: Signature = hmac_sha256(secretKey, message).
3. Codificá el resultado en Base64 para obtener el valor final del encabezado ACCESS-SIGN.

En la práctica, hay algunos detalles adicionales importantes:

• El encabezado ACCESS-TIMESTAMP debe expresarse en milisegundos, y WEEX rechaza las solicitudes cuyo timestamp difiere más de 30 segundos de la hora del servidor. Si el reloj local se desvía, consultá el endpoint de hora del servidor de WEEX y sincronizalo, en lugar de depender del reloj local de tu equipo.
• Las solicitudes GET pasan los parámetros mediante la cadena de consulta; las solicitudes POST pasan los parámetros como un cuerpo JSON; las solicitudes DELETE pueden usar cualquiera de las dos opciones, según el endpoint específico.
• El valor de method en la cadena de firma debe estar en mayúsculas (GET, POST, DELETE).

Ejemplo — firmar una solicitud GET (obtener la profundidad de mercado de BTCUSDT):

timestamp = 1591089508404\nmethod = "GET"\nrequestPath = "/api/v3/market/depth"\nqueryString = "symbol=BTCUSDT&limit=20"\n\nmessage = "1591089508404GET/api/v3/market/depth?symbol=BTCUSDT&limit=20"\n

Ejemplo — firmar una solicitud POST (colocar una orden):

timestamp = 1561022985382\nmethod = "POST"\nrequestPath = "/api/v3/order"\nbody = {"symbol":"BTCUSDT","side":"BUY","type":"LIMIT","timeInForce":"GTC","quantity":"1","price":"68900","newClientOrderId":"my-order-001"}\n\nmessage = '1561022985382POST/api/v3/order{"symbol":"BTCUSDT","side":"BUY","type":"LIMIT","timeInForce":"GTC","quantity":"1","price":"68900","newClientOrderId":"my-order-001"}'\n

En ambos casos, esa cadena del mensaje se procesa mediante HMAC SHA256 + Base64 para producir el valor final del encabezado ACCESS-SIGN.

Límites de frecuencia: cómo funcionan realmente

La API REST de WEEX aplica dos categorías diferentes de límites de frecuencia, y entender la diferencia es importante si estás creando algo que opera activamente:

Límites de frecuencia por IP (todo excepto la colocación de órdenes)

Casi todos los endpoints —datos de mercado, consultas de cuenta, cancelación de órdenes y consulta del estado de las órdenes— tienen límites definidos por dirección IP, no por clave de API ni por cuenta. Cada endpoint tiene un “peso”, y los endpoints que consumen más recursos del servidor tienen un peso mayor. Cada respuesta incluye encabezados que muestran tu uso actual:

• X-USED-WEIGHT-(intervalNum)(intervalLetter): peso utilizado hasta el momento en el intervalo actual (por ejemplo, X-USED-WEIGHT-1M para una ventana de 1 minuto).
• X-REMAINING-WEIGHT-(intervalNum)(intervalLetter): peso restante en ese mismo intervalo.

Límites de frecuencia de ORDERS (solo colocación de órdenes)

En particular, los endpoints para colocar órdenes individuales y por lotes tienen límites definidos por cuenta (userId) en vez de por IP, y no consumen ningún peso de IP: el contador del límite de frecuencia por IP para estas llamadas muestra 0. Los encabezados de respuesta relevantes son:

• X-ORDER-COUNT-(intervalNum)(intervalLetter): órdenes colocadas hasta el momento en el intervalo actual.
• X-ORDER-REMAINING-(intervalNum)(intervalLetter): órdenes restantes en ese intervalo.

Otras acciones relacionadas con órdenes —como cancelarlas o consultarlas— no están cubiertas por el límite de ORDERS y, en cambio, quedan sujetas al límite estándar de peso basado en IP.

Qué pasa si superás un límite

Superar un límite de frecuencia devuelve un código de estado HTTP 429. En ese momento, WEEX espera que dejes de enviar solicitudes: seguir accediendo a la API después de un 429 se considera abuso y genera una prohibición de 10 segundos. Para cualquier sistema en producción, conviene incorporar margen (reducir el ritmo antes de acercarse al límite) en lugar de esperar a detectar los errores 429 de forma reactiva.

Checklist práctico antes de salir en vivo

• Guardá tu APIKey, SecretKey y Passphrase de forma segura en el momento en que crees la clave: ninguna podrá recuperarse después, y perder la Passphrase implica crear una clave completamente nueva.
• Vinculá tu clave a una IP específica en vez de dejarla sin restricciones.
• Limitá los permisos a lo que realmente necesita cada integración: Solo lectura para dashboards y herramientas de monitoreo; permisos de trading únicamente para claves que efectivamente coloquen órdenes.
• Sincronizá tu reloj local con la hora del servidor de WEEX si estás viendo fallas de firma relacionadas con el timestamp.
• Leé los encabezados de respuesta, no solo el cuerpo: los encabezados de peso y de cantidad de órdenes te indican qué tan cerca estás de alcanzar un límite antes de hacerlo.
• Manejá los errores 429 reduciendo el ritmo, no reintentando de inmediato, para evitar extender la prohibición.
• Eliminá de inmediato cualquier clave de API si sospechás que fue expuesta o comprometida.

Reflexiones finales

Crear una clave de API de WEEX es un proceso breve —generar la clave, configurar sus permisos y guardar las credenciales de forma segura—, pero usarla correctamente requiere entender con mayor profundidad dos aspectos: cómo funciona realmente la firma de solicitudes y cómo los dos sistemas independientes de límites de frecuencia (límites de peso basados en IP y límites de órdenes basados en cuenta) se aplican a distintos tipos de endpoints. Ajustar exactamente el formato de la firma y respetar ambos tipos de límites son las dos fuentes más comunes de problemas de integración para los nuevos usuarios de la API.

Para consultar la referencia completa y actualizada de endpoints, empezá por la Introducción a la API oficial y la guía de preparación de la API Spot, que también enlaza con la documentación equivalente de Futuros, la referencia de Restricciones de acceso y la documentación de cada endpoint para todas las llamadas de Market, Account y Trade.

Operar mediante la API implica el mismo riesgo de mercado subyacente que el trading manual: la automatización no reduce ni elimina la posibilidad de pérdidas. Probá cualquier integración exhaustivamente, empezá con montos pequeños y asegurate de entender exactamente qué permisos tiene cada clave que crees.

WEEX no ofrece servicios a usuarios en Estados Unidos, sus territorios ni en determinadas otras jurisdicciones restringidas. Revisá los Términos de uso para consultar la lista vigente de jurisdicciones excluidas y los requisitos de elegibilidad antes de crear una cuenta o una clave de API.