# Referencia de la API

> Todos los endpoints v1 con método, scope y propósito.

Source: https://docs.botradix.com/es/api-reference/

Todas las rutas son relativas a `https://app.botradix.com/api/dex/v1` y requieren una clave de API con el scope indicado. Las respuestas son JSON. Lee los límites, la precisión, el tick size y los tamaños de orden desde `/markets` y `/meta` en tiempo de ejecución, en lugar de fijarlos en tu código.

## Datos de mercado

| Método | Ruta | Scope | Para qué |
|---|---|---|---|
| GET | `/status` | `market:read` | Estado de la API, la red y el motor de mercado |
| GET | `/meta` | `market:read` | Versiones de esquema, scopes y capacidades publicadas |
| GET | `/markets` | `market:read` | Catálogo de mercados con precisión y límites de orden de cada uno |
| GET | `/candles` | `market:read` | Velas por `pair_id`, `interval` y `limit` |
| GET | `/snapshot` | `market:read` | Snapshot de mercado y secuencia actual |
| GET | `/summary` | `market:read` | Resumen de un mercado (`pair_id`) |
| GET | `/summaries` | `market:read` | Resúmenes de todos los mercados |
| GET | `/markets/{pair_id}/funding` | `market:read` | Estado del funding de un mercado |
| GET | `/markets/{pair_id}/open-interest` | `market:read` | Open interest largo y corto de un mercado |
| GET | `/orderbook` | `market:read` | Libro de órdenes derivado del estado disponible en cadena |
| GET | `/vault` | `market:read` | Estado público del vault de liquidez del DEX |

## Cuenta (la wallet de la clave)

| Método | Ruta | Scope | Para qué |
|---|---|---|---|
| GET | `/account` | `account:read` | Patrimonio, colateral, margen, factor de salud y estado de liquidación |
| GET | `/positions` | `account:read` | Posiciones abiertas, con precio de marca y de liquidación |
| GET | `/orders` | `account:read` | Órdenes indexadas desde los contratos (paginado) |
| GET | `/orders/by-client-id` | `account:read` | Busca un `open_position` preparado por su `client_order_id` |
| GET | `/collateral` | `account:read` | Saldos de colateral y estado asociado |
| POST | `/risk/preview` | `account:read` | Previsualiza el riesgo de un cambio antes de ejecutarlo |
| GET | `/transactions` | `account:read` | Intenciones preparadas y su estado en cadena (paginado) |
| GET | `/trades` | `account:read` | Operaciones ejecutadas indexadas desde la cadena (paginado) |
| GET | `/positions/history` | `account:read` | Posiciones cerradas (paginado) |
| GET | `/native/executions/{tx_hash}` | `account:read` | Finalidad de una ejecución: `PENDING`, `PENDING_FINALITY` (menos de 8 confirmaciones), `REVERTED` o `FINAL`. Parámetros opcionales `account` y `trade_id` |
| GET | `/executions/{command_id}` | `account:read` | Estado de una ejecución delegada |
| GET | `/stream` | `account:read` | Stream privado Server-Sent Events. **Aún no está activado en el servicio público** (ver abajo) |

## Trading

| Método | Ruta | Scope | Para qué |
|---|---|---|---|
| POST | `/orders/prepare` | Según la acción | Valida una acción y devuelve lo necesario para ejecutarla. Requiere clave de idempotencia |
| POST | `/orders/execute` | `trade:execute` (y `orders:manage` para cancelar, reemplazar y primitivas de TP/SL) | Ejecución delegada, cuando la clave tiene un ejecutor vinculado |

Acciones y el scope que necesita cada una:

| Acción | Scope |
|---|---|
| `open_position`, `close_position_market`, `close_position_limit`, `invert_position`, `update_tpsl`, `add_isolated_margin`, `reduce_isolated_margin`, `change_isolated_leverage` | `trade:prepare` |
| `cancel_order`, `replace_order` | `orders:manage` |
| `add_collateral`, `withdraw_collateral` | `collateral:manage` |

El flujo completo, los campos y un ejemplo están en [Operar con la API](https://docs.botradix.com/es/api-orders/).

## Paginación

Los endpoints paginados aceptan `cursor` y `limit` (por defecto 50, máximo 200) y devuelven:

```json
{ "items": [ … ], "next_cursor": 1234, "has_more": true, "limit": 50 }
```

El objeto va dentro de `orders`, `transactions`, `trades` o `history` según el endpoint. Envía `next_cursor` como `cursor` para obtener la página siguiente.

## El stream en tiempo real

`GET /stream?pair_id={id}&interval=1m` está diseñado como un stream privado Server-Sent Events (snapshot de mercado, snapshot privado de la cuenta y eventos de ciclo de vida, con un latido cada 12 segundos). **Por ahora no está activado en el servicio público** y responde `503 REALTIME_STREAM_ASYNC_WORKER_REQUIRED` con `Retry-After: 5`. Mientras tanto, usa [webhooks](https://docs.botradix.com/es/api-realtime/) para los eventos de cuenta y consulta los endpoints de lectura dentro de tus límites.

## Endpoints públicos sin clave

El terminal web usa endpoints sin versión que cualquiera puede leer. Son útiles para paneles, pero **no** son un contrato estable y pueden cambiar sin aviso; las integraciones deben usar `/api/dex/v1`.

| Ruta (en `https://app.botradix.com`) | Contenido |
|---|---|
| `/api/dex/config` | Modelos de ejecución, órdenes, comisiones y precisión, y capacidades de la API |
| `/api/dex/markets`, `/api/dex/summaries`, `/api/dex/summary` | Mercados y resúmenes |
| `/api/dex/candles`, `/api/dex/candles/history` | Velas (1m, 3m, 5m, 15m, 1h, 4h, 1d, 1w). El histórico se pagina con `before`, hasta 50.000 velas; en 1d y 1w continúa con historial externo anterior, indicado en `history_sources` |
| `/api/dex/marks?pair_ids=1,2` | Precios de marca de 1 a 12 mercados |
| `/api/dex/orderbook`, `/api/dex/vault`, `/api/dex/liquidations` | Libro de órdenes, vault y liquidaciones recientes |
| `/api/dex/markets/{id}/funding`, `/api/dex/markets/{id}/open-interest` | Funding y open interest |
| `/api/dex/status`, `/api/dex/circuit-breakers` | Estado del servicio e interruptores de seguridad |
| `/api/dex/account?wallet=0x…` (también `positions`, `orders`, `collateral`, `transactions`, `trades`, `positions/history`) | Vistas de solo lectura de cualquier wallet. Las posiciones en cadena son públicas por naturaleza |
| `/api/public/baq-market`, `/api/public/baq-metrics` | Datos de mercado y métricas de BAQ (ver [BAQ](https://docs.botradix.com/es/baq/)) |