Referencia de la API

La interfaz programática de Nexus Exchange, con cada endpoint, las guías que los explican y los clientes oficiales.

Todo lo que un trader puede hacer en Nexus Exchange está disponible de forma programática. Esta sección tiene una página por endpoint, guías escritas a mano que los explican y los clientes con soporte oficial.

Empieza aquí	Primeros pasos · SDK y herramientas · Autenticación · Claves de agente
Antes de construir	Tipos de órdenes · Límites de solicitudes · Errores · Limitaciones conocidas
Referencia	Una página por endpoint, agrupadas por área en la barra lateral
Esquemas	Referencia de esquemas (en inglés)

URL base

El contrato declara dos servidores públicos a nivel de documento, en este orden:

Servidor	URL	Uso
Testnet pública (predeterminada)	https://api.testnet.nexus.xyz/v1	Fondos de prueba. La base de transporte /v1, para las rutas sin prefijo. Es la primera de la lista, así que es la base que un generador elige de forma predeterminada.
Mainnet	https://api.nexus.xyz/v1	Fondos reales. Aparece después de testnet a propósito, para que nada que busque "el primer servidor https" termine en el destino con fondos reales. Todavía no resuelve. El DNS es un cambio de infraestructura aparte (ENG-8155).

El contrato no define ninguna red predeterminada, así que selecciona una explícitamente. En la tabla de arriba, "predeterminada" solo significa que testnet es servers[0], la base que elige un generador cuando tú no eliges. La base del gateway heredado https://exchange.nexus.xyz/api/exchange está dada de baja. Ya no figura en el contrato y responde HTTP 410 con un cuerpo JSON que nombra su reemplazo. Apunta los SDK, la CLI y el servidor MCP a la base pública de testnet de arriba, que aplica los límites de solicitudes y los niveles.

Rutas versionadas (/api/v1) y sin prefijo

40 de las 116 rutas son equivalentes versionadas /api/v1/… de las rutas sin prefijo. Son las mismas operaciones, a las que se llega a través de un montaje versionado. Ambas formas funcionan en el host público de testnet:

https://api.testnet.nexus.xyz/v1/tickers       → 200
https://api.testnet.nexus.xyz/api/v1/tickers   → 200

Prefiere la forma sin prefijo sobre la base /v1. Es lo que declara la entrada servers a nivel de documento, y es la estructura hacia la que se están moviendo los clientes oficiales. El contrato no marca ninguna de las dos variantes como deprecated. Las cinco rutas /api/v1/bridge/… todavía no tienen una forma sin prefijo en el contrato, así que, por ahora, llámalas en su forma /api/v1.

Firma la ruta del contrato, no la ruta de la URL. El prefijo de transporte que selecciona un montaje (/v1 en la base pública de testnet) se elimina antes de que la solicitud llegue al servicio que verifica tu firma, así que no forma parte de la cadena canónica HMAC. El prefijo /api/v1 sí forma parte de la ruta del contrato y sí se firma. Llamar a https://api.testnet.nexus.xyz/api/v1/tickers significa firmar /api/v1/tickers; llamar a https://api.testnet.nexus.xyz/v1/tickers significa firmar /tickers. Consulta Autenticación.

Las rutas /api/v1 llevan una anulación de servers, y los clientes deberían respetarla. Las 40 declaran una anulación a nivel de ruta hacia la raíz del host público de testnet, https://api.testnet.nexus.xyz. La ruta completa de la operación se agrega a ella, así que /api/v1/tickers se resuelve como https://api.testnet.nexus.xyz/api/v1/tickers. Ese es el "servidor declarado" que muestran las páginas generadas de la Referencia, y un cliente generado que lo respeta llega a la API.

La anulación existe porque esa base difiere de la del nivel de documento. La entrada de testnet del documento lleva /v1 y espera una ruta sin prefijo (https://api.testnet.nexus.xyz/v1/tickers), mientras que las rutas con prefijo necesitan la raíz del host. Combinar las dos mitades a mano produce https://api.testnet.nexus.xyz/v1/api/v1/…, que no es la URL que el contrato declara para estas rutas. El contrato señala que el chart público de testnet también la acepta: el chart elimina solo el /v1 exterior, y la solicitud sigue firmando /api/v1/….

Cómo leer esta sección

Las páginas de la Referencia se generan a partir del contrato. Cada una indica lo que openapi.json declara para esa operación y nada más: parámetros, cuerpo de la solicitud, respuestas, esquema de autenticación y clase de límite de solicitudes. La CI las vuelve a generar y las compara, así que no pueden desviarse del contrato.

Las Guías están escritas a mano. Cubren lo que una página por endpoint no puede cubrir: la matriz de requisitos por tipo de orden en todas las operaciones que envían órdenes, las convenciones de signo, el modelo de errores y la lista de cosas que el contrato no dice.

Esta sección no indica cuántos endpoints o esquemas hay. Un conteo mantenido a mano se desvió la última vez. La versión anterior de esta sección publicaba una versión de la especificación desactualizada por dieciocho versiones menores, con conteos de operaciones y esquemas igual de desactualizados. La barra lateral se genera a partir del contrato, y el contrato se sirve en /openapi.json. Ambos son la fuente de referencia, así que ninguno necesita que se repita un número en la prosa.

La especificación OpenAPI

La API es contract-first. El esquema legible por máquina, con cada ruta, cuerpo de solicitud y respuesta y correspondencia con métodos de CCXT, está publicado en nexus-xyz/nexus-exchange-api y se sirve en vivo en /openapi.json. Las versiones se publican en GitHub Releases. Los SDK, la CLI y el servidor MCP de abajo se generan a partir de una versión publicada de esta especificación, o están fijados a ella, así que coinciden con el gateway.

SDK y herramientas

Los SDK de Rust, TypeScript, Python y Go, la CLI nexus, un servidor MCP y skills para agentes llaman a esta API. SDK y herramientas presenta cada uno con su repositorio y su línea de instalación.

Portafolio y estado de la cuenta cubre los endpoints de cuenta y de portafolio para las cuatro interfaces a la vez: el estado consolidado de la cuenta, el saldo disponible para retirar, la tabla de comisiones, los campos enriquecidos de riesgo de las posiciones y las series de tiempo de patrimonio/PnL/volumen.

El mismo presupuesto se aplica sin importar con qué construyas. Las solicitudes se cobran por peso por segundo, no se cuentan, y las lecturas, las escrituras de órdenes y el plano de control de WebSocket consumen tres buckets independientes. Lee Límites de solicitudes antes de escribir un limitador del lado del cliente. Un cliente que regula su ritmo por cantidad de solicitudes recibe rechazos mientras su propio contador todavía parece estar bien.

Cómo elegir una red

Hoy el Exchange funciona en testnet como una versión preliminar de desarrollo, y después llegará una mainnet pública. Cada interfaz apunta a una red a la vez (testnet, mainnet o local), que se selecciona al construir el cliente. El cliente incluye los destinos REST y WebSocket de esa red, la disponibilidad del faucet y el dominio de firma. Los SDK, la CLI y el servidor MCP usan testnet cuando no pasas ninguna red, y mainnet todavía no es accesible. Las credenciales están limitadas a la red en la que se crearon.

Consulta Redes para ver cómo selecciona una red cada interfaz, cómo anular el destino y qué vincula una clave de API a una red; APIs y límites de solicitudes para la URL base actual; y el Inicio rápido para el flujo de conexión de punta a punta.

Autenticación

La autenticación es idéntica en todas las interfaces. Firmas un mensaje fijo con tu billetera (EIP-191) para obtener un token de sesión de corta duración, usas ese token una vez para generar una clave de API HMAC y luego firmas cada solicitud de trading con esa clave. Los SDK y la CLI firman las solicitudes por ti. El recorrido completo, con ejemplos ejecutables, está en el Inicio rápido.

Estado: versión preliminar de desarrollo en testnet. Las interfaces siguen la especificación OpenAPI versión por versión; fija una versión de la especificación en producción y consulta las notas de versión de cada repositorio antes de actualizar. Las credenciales y los saldos de testnet no tienen valor en el mundo real.