> For the complete documentation index, see [llms.txt](https://docs.nexus.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexus.xyz/api-reference/es-419/readme.md).

# 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](/api-reference/es-419/guides/get-started.md) · [Autenticación](/api-reference/es-419/guides/authentication.md) · [Claves de agente](/api-reference/es-419/guides/agent-keys.md)                                                                   |
| **Antes de construir** | [Tipos de órdenes](/api-reference/es-419/guides/order-types.md) · [Límites de solicitudes](/api-reference/es-419/guides/rate-limits.md) · [Errores](/api-reference/es-419/guides/errors.md) · [Limitaciones conocidas](/api-reference/es-419/guides/known-gaps.md) |
| **Referencia**         | Una página por endpoint, agrupadas por área en la barra lateral                                                                                                                                                                                                    |
| **Esquemas**           | [Referencia de esquemas (en inglés)](https://docs.nexus.xyz/api-reference/guides/schemas)                                                                                                                                                                          |

## URL base

El contrato declara tres servidores 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). |
| Desarrollo local                 | `http://localhost:9090`            | Un indexador que se ejecuta en tu propia máquina.                                                                                                                                                                                        |

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 110 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](/api-reference/es-419/guides/authentication.md).

{% hint style="info" %}
**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`, o `http://localhost:9090` para desarrollo local. 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/…`.
{% endhint %}

### 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`](https://github.com/nexus-xyz/nexus-exchange-api) y se sirve en vivo en `/openapi.json`. Las versiones se publican en [GitHub Releases](https://github.com/nexus-xyz/nexus-exchange-api/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

| Lenguaje   | Repositorio                                                           | Para qué usarlo                                          |
| ---------- | --------------------------------------------------------------------- | -------------------------------------------------------- |
| Rust       | [`nexus-exchange-rs`](https://github.com/nexus-xyz/nexus-exchange-rs) | Clientes sensibles a la latencia y bots de market making |
| TypeScript | [`nexus-exchange-ts`](https://github.com/nexus-xyz/nexus-exchange-ts) | Aplicaciones web, Node y edge                            |
| Python     | [`nexus-exchange-py`](https://github.com/nexus-xyz/nexus-exchange-py) | Investigación, backtesting y scripting                   |

Cada SDK se encarga de la firma de solicitudes (HMAC o clave de agente), la paginación y el ciclo de vida de las suscripciones de WebSocket, para que no tengas que reimplementarlos. Para ver cuánto cuesta firmar en cada SDK, y si sigue el ritmo de tu nivel, consulta [el costo de firma por SDK](/api-reference/es-419/guides/rate-limits.md#can-your-signer-keep-up). El soporte de versiones y la política de cambios incompatibles están documentados en el README de cada repositorio.

[Portafolio y estado de la cuenta](/api-reference/es-419/guides/portfolio.md) 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](/api-reference/es-419/guides/rate-limits.md) 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.

### Línea de comandos

La [`nexus-exchange-cli`](https://github.com/nexus-xyz/nexus-exchange-cli) envuelve la misma API para uso interactivo y scripting en shell. Administra claves, envía y cancela órdenes y consulta el estado de la cuenta sin que tengas que escribir código. `nexus --version` informa las versiones de la especificación de la API y del SDK con las que está construida.

### Servidor MCP

El servidor [`nexus-exchange-mcp`](https://github.com/nexus-xyz/nexus-exchange-mcp) expone el Exchange como herramientas de [Model Context Protocol](https://modelcontextprotocol.io), para que un asistente o agente de IA pueda operar y leer el estado de la cuenta a través de la misma API autenticada que usa un cliente humano. Está publicado como [`@nexus-xyz/exchange-mcp`](https://www.npmjs.com/package/@nexus-xyz/exchange-mcp):

```bash
claude mcp add nexus-exchange -- npx -y @nexus-xyz/exchange-mcp
```

Funciona por stdio, así que las credenciales se quedan en la máquina que lo agrega, y sus herramientas públicas de datos de mercado funcionan sin ninguna clave.

### Cómo elegir una red

Hoy el Exchange funciona en **Nexus 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](/api-reference/es-419/guides/networks.md) 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](https://docs.nexus.xyz/exchange/apis-and-rates) para la URL base actual; y el [Inicio rápido](https://docs.nexus.xyz/exchange/trading/quickstart) 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](https://docs.nexus.xyz/exchange/trading/quickstart).

> **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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nexus.xyz/api-reference/es-419/readme.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.