> 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/exchange/es-419/apis-and-rates/apis-and-rates/exchange-rest.md).

# Exchange REST

La API REST de un vistazo: autenticación y claves, cuenta, órdenes, datos de mercado y estadísticas.

URL base: `https://api.testnet.nexus.xyz/v1`, la base pública de testnet.

Todas las rutas **excepto** `/health`, `/openapi.json` y `/auth/login` requieren autenticación HMAC (consulta el paso Firmar solicitudes del Inicio rápido). El esquema completo legible por máquina, incluidos los cuerpos de solicitud y respuesta y las correspondencias con métodos de CCXT, está en `/openapi.json`.

Convenciones:

* Todos los valores monetarios son **cadenas** decimales.
* En las rutas de una sola orden, `market_id` es **obligatorio** como parámetro de consulta. El motor enruta directamente al mercado propietario.
* Las solicitudes autenticadas llevan `X-API-Key`, `X-Timestamp`, `X-Signature`. La marca de tiempo debe estar dentro de ±30s respecto a la hora del servidor.

### Autenticación y claves

| Método | Ruta          | Auth   | Descripción                                                                     |
| ------ | ------------- | ------ | ------------------------------------------------------------------------------- |
| POST   | `/auth/login` | —      | Firma de billetera EIP-191 → token Bearer de sesión de 24h                      |
| POST   | `/keys`       | Sesión | Crea una clave de API HMAC (`key_id` + `secret`; el secreto se muestra una vez) |
| GET    | `/keys`       | Sesión | Lista tus claves de API                                                         |
| DELETE | `/keys/{id}`  | Sesión | Revoca una clave de API                                                         |
| POST   | `/ws/token`   | HMAC   | Genera un token de un solo uso de 60s para el WebSocket `/ws`                   |
| POST   | `/ws-tokens`  | HMAC   | Ruta de tokens heredada. Nada en la API actual necesita sus tokens              |

### Cuenta

| Método | Ruta                                        | Auth | Descripción                                                                              |
| ------ | ------------------------------------------- | ---- | ---------------------------------------------------------------------------------------- |
| GET    | `/account`                                  | HMAC | Saldo, patrimonio, margen usado, ratio de margen                                         |
| GET    | `/account/summary`                          | HMAC | Agregados del portafolio más el saldo disponible para retirar                            |
| GET    | `/account/state`                            | HMAC | Resumen del portafolio **y** todas las posiciones abiertas en una sola lectura coherente |
| GET    | `/account/fees`                             | HMAC | Tabla efectiva de comisiones maker/taker de la cuenta                                    |
| POST   | `/leverage`                                 | HMAC | Define el apalancamiento permanente de la cuenta para un mercado                         |
| GET    | `/account/portfolio-history?window=&limit=` | HMAC | Series de tiempo de patrimonio / PnL acumulado / volumen acumulado                       |
| GET    | `/positions`                                | HMAC | Posiciones abiertas con PnL no realizado y detalle de riesgo por posición                |
| POST   | `/account/credit`                           | HMAC | USDX sintético del faucet (testnet; hasta 500/día por clave)                             |
| GET    | `/account/{address}/adl-history?limit=`     | HMAC | Eventos de desapalancamiento automático en los que la cuenta fue objetivo o contraparte  |

[Portafolio y estado de la cuenta](https://docs.nexus.xyz/interfaces/portfolio) documenta por completo las rutas del portafolio y los campos enriquecidos de posición, incluida la convención de campos que admiten null, el signo de `funding_paid` y por qué `/account/state` es mejor que dos llamadas separadas.

### Órdenes

| Método | Ruta                            | Auth | Descripción                                                                                    |
| ------ | ------------------------------- | ---- | ---------------------------------------------------------------------------------------------- |
| POST   | `/orders`                       | HMAC | Envía una orden de cualquiera de los ocho tipos de órdenes                                     |
| POST   | `/orders/batch`                 | HMAC | Envía varias órdenes (secuencial; los resultados conservan el orden de la solicitud)           |
| POST   | `/orders/preview`               | HMAC | Proyecta el impacto en margen, patrimonio, comisiones y liquidación sin enviar la orden        |
| GET    | `/orders`                       | HMAC | Lista las órdenes abiertas                                                                     |
| GET    | `/orders/history`               | HMAC | Historial de órdenes en estado terminal                                                        |
| GET    | `/orders/{order_id}?market_id=` | HMAC | Obtiene una sola orden                                                                         |
| PATCH  | `/orders/{order_id}?market_id=` | HMAC | Modifica una orden (cancelar y reemplazar de forma atómica; devuelve un id de orden **nuevo**) |
| DELETE | `/orders/{order_id}?market_id=` | HMAC | Cancela una sola orden                                                                         |
| DELETE | `/orders?market_id=`            | HMAC | Cancela todas las órdenes abiertas de un mercado                                               |

Campos del cuerpo de la orden: `market_id`, `side` (`Buy`/`Sell`), `order_type`, `quantity`, `time_in_force` (`GTC`/`IOC`/`FOK`/`PostOnly`), `price` (solo tipos de la familia límite) y el opcional `reduce_only`.

`order_type` acepta uno de **ocho** valores: `Limit` y `Market`, más seis tipos condicionales (`StopLimit`, `StopMarket`, `TakeProfitLimit`, `TakeProfitMarket`, `TrailingStop`, `TrailingLimit`). Cuáles de `price`, `trigger_price`, `trailing_offset_bps` y `limit_offset_bps` necesita una solicitud depende del tipo. Consulta [Tipos de órdenes](/exchange/es-419/trading/trading/perpetuals/order-types.md) para la vista del trader y [Tipos de órdenes](https://docs.nexus.xyz/api-reference/guides/order-types) para la matriz completa de requisitos por tipo.

### Datos de mercado

| Método | Ruta                              | Descripción                                                                |
| ------ | --------------------------------- | -------------------------------------------------------------------------- |
| GET    | `/markets`                        | Lista todos los mercados en vivo y su estado                               |
| GET    | `/markets/summary`                | Precio de marca, volumen 24h, cantidad de operaciones y estado por mercado |
| GET    | `/markets/{id}/ticker`            | Último / compra / venta / volumen / variación                              |
| GET    | `/markets/{id}/orderbook`         | Profundidad del libro de órdenes de nivel 2                                |
| GET    | `/markets/{id}/trades`            | Operaciones recientes                                                      |
| GET    | `/markets/{id}/candles`           | Velas OHLCV (1m / 5m / 1h)                                                 |
| GET    | `/markets/{id}/funding`           | Historial de la tasa de financiamiento                                     |
| GET    | `/markets/{id}/mark-price`        | Precio de marca actual                                                     |
| GET    | `/markets/{id}/status`            | Activo/detenido, motivo, marca de tiempo, cantidad de ADL                  |
| GET    | `/markets/{id}/adl-events?limit=` | Historial de desapalancamiento automático por mercado                      |
| GET    | `/tickers`                        | Todos los tickers en una sola llamada                                      |
| GET    | `/stats`, `/stats/history`        | Estadísticas de todo el exchange                                           |

### Streaming

Las actualizaciones en tiempo real del libro de órdenes, de las operaciones y de la cuenta se entregan por WebSocket, no por REST. Consulta la Referencia de la API WebSocket.

> **Estado:** versión preliminar de testnet. El conjunto de endpoints sigue la especificación OpenAPI versionada en [`nexus-xyz/nexus-exchange-api`](https://github.com/nexus-xyz/nexus-exchange-api); consulta `/openapi.json` para ver el esquema actual de referencia.


---

# 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/exchange/es-419/apis-and-rates/apis-and-rates/exchange-rest.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.