# API: visión general y autenticación

> URL base, claves de API, scopes, sesiones de desarrollador firmadas y gestión de claves.

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

La API del BotRadix DEX (versión 1) permite que un servidor, un bot o una integración lean datos de mercado y la cuenta de una wallet, y que preparen o ejecuten operaciones para esa wallet. Es una API JSON sobre HTTPS.

## Resumen

| Elemento | Valor |
|---|---|
| URL base | `https://app.botradix.com/api/dex/v1` (la misma API responde también en `https://botradix.com/api/dex/v1`) |
| Red | Base mainnet, chain ID `8453` |
| Formato | JSON, UTF-8. Cuerpos de petición de hasta 48 KiB |
| Autenticación | Una clave de API vinculada a una wallet, con scopes |
| Cabeceras de versión | `X-BotRadix-API-Version: v1` y `X-BotRadix-API-Schema: botradix-dex-api-v1.1` |
| Trazabilidad | Cada respuesta lleva `X-Request-ID`; puedes enviar el tuyo (8–80 caracteres de `A-Z a-z 0-9 . _ : -`) |
| Navegador | Solo mismo origen. Llama a la API desde tu servidor, nunca desde una página pública |

> [!IMPORTANT]
> Una clave de API es un secreto que puede actuar sobre la cuenta DEX de tu wallet dentro de sus scopes. Guárdala en un servidor o en un gestor de secretos. Nunca la incluyas en una web, una app móvil o un repositorio público.

## Dos tipos de credenciales

BotRadix separa **administrar** credenciales de **usarlas**:

1. **Sesión de desarrollador.** Demuestra que controlas una wallet. Se obtiene firmando un mensaje de texto con esa wallet; es gratis y no envía ninguna transacción. Dura **4 horas** y solo sirve para crear, rotar y revocar claves de API y para gestionar webhooks.
2. **Clave de API.** La usa tu servidor o bot en cada llamada a `/api/dex/v1`. Cada clave pertenece a una sola wallet y tiene sus propios scopes, caducidad, límites de uso y, opcionalmente, una lista de IP permitidas.

Una clave de trading no puede administrar otras claves, y una sesión de desarrollador no puede llamar a la API de trading.

## Enviar la clave de API

Envía la clave en la cabecera `X-BotRadix-API-Key`:

```bash
curl https://app.botradix.com/api/dex/v1/account \
  -H "X-BotRadix-API-Key: $BOTRADIX_API_KEY"
```

También se acepta `Authorization: Bearer <clave>`. Si llegan las dos, manda `X-BotRadix-API-Key`. Las claves empiezan por `BRX`.

Sin clave, la API responde `401 API_KEY_REQUIRED`. Todos los errores de autenticación están en [Errores, límites y versionado](https://docs.botradix.com/es/api-errors/).

## Obtener una sesión de desarrollador

1. Pide un challenge para tu wallet. Caduca a los 5 minutos.
2. Firma el `message` devuelto, tal cual, con `personal_sign` (una firma de mensaje, no una transacción).
3. Canjea el nonce y la firma por una sesión de desarrollador.

```bash
# 1. Challenge
curl -X POST https://app.botradix.com/api/dex/developer/challenge \
  -H "Content-Type: application/json" \
  -d '{"wallet":"0xTuWallet"}'
# → {"success":true,"wallet":"0x…","message":"…","nonce":"…",
#    "expires_at":"…","network":"Base","chain_id":8453}

# 2. Firma "message" con la wallet (personal_sign).

# 3. Sesión
curl -X POST https://app.botradix.com/api/dex/developer/session \
  -H "Content-Type: application/json" \
  -d '{"wallet":"0xTuWallet","nonce":"…","signature":"0x…"}'
# → {"success":true,"wallet":"0x…","developer_session":"brxds1.…",
#    "expires_at_ms":…,"developer":{…}}
```

El texto del challenge incluye la wallet, el dominio, la red (Base, 8453), el nonce y la caducidad, así que no puede reutilizarse en otro sitio. Tras cinco firmas incorrectas el challenge se descarta.

A partir de ahí, toda la gestión de claves y webhooks usa `Authorization: Bearer <developer_session>`.

## Crear una clave de API

```bash
curl -X POST https://app.botradix.com/api/dex/developer/keys \
  -H "Authorization: Bearer $DEVELOPER_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "market-maker-01",
    "scopes": ["market:read", "account:read", "trade:prepare"],
    "expires_in_days": 90,
    "ip_allowlist": ["203.0.113.10"]
  }'
```

| Campo | Reglas |
|---|---|
| `label` | Un nombre para identificarla |
| `scopes` | Cualquiera de los scopes de abajo. Los desconocidos se ignoran; si no queda ninguno válido, la petición falla. Si no se indica, la clave recibe todos los scopes salvo `collateral:manage` |
| `expires_in_days` | De 1 a 2000. Por defecto 180 |
| `ip_allowlist` | Lista opcional (o texto separado por comas) de IP o rangos CIDR. Las peticiones desde otras direcciones reciben `403 IP_NOT_ALLOWED` |
| `quotas` | Límites de uso propios de la clave, dentro de los máximos de [Errores, límites y versionado](https://docs.botradix.com/es/api-errors/) |

La respuesta (`201`) contiene la clave completa en `api_key`. **Solo se muestra una vez.** Una wallet puede tener hasta **10 claves activas**.

> [!NOTE]
> Las claves creadas desde la vista **API** del terminal DEX son "listas para bots": la wallet firma además una autorización única para un agente de trading, y la clave recibe los scopes por defecto. Para elegir los scopes tú mismo, crea la clave por API como se muestra arriba.

## Scopes

| Scope | Permite |
|---|---|
| `market:read` | Mercados, velas, resúmenes, funding, open interest, libro de órdenes y vault |
| `account:read` | La wallet de la clave: cuenta, posiciones, órdenes, colateral, transacciones, operaciones, historial y estado de ejecuciones |
| `trade:prepare` | Preparar aperturas, cierres, inversiones, cambios de TP/SL y de margen aislado |
| `trade:execute` | Ejecución delegada mediante `/orders/execute`, cuando la clave tiene un ejecutor vinculado |
| `orders:manage` | Cancelar y reemplazar órdenes, y las primitivas de TP/SL en ejecución delegada |
| `collateral:manage` | Preparar depósitos y retiros de colateral |

Da a cada clave solo los scopes que necesite.

## Gestión de claves y webhooks

| Método | Ruta | Para qué |
|---|---|---|
| POST | `/api/dex/developer/challenge` | Mensaje que la wallet debe firmar |
| POST | `/api/dex/developer/session` | Verifica la firma y entrega una sesión de desarrollador de 4 horas |
| GET | `/api/dex/developer/keys` | Lista las claves de la wallet (hasta 64) |
| POST | `/api/dex/developer/keys` | Crea una clave |
| POST | `/api/dex/developer/keys/prepare` | Paso 1 de una clave lista para bots: un agente de trading nuevo y la autorización que la wallet firma una vez. No se crea nada hasta que esa firma llega con `POST /keys` (válido 30 minutos) |
| POST | `/api/dex/developer/keys/{key_id}/rotate` | Genera un secreto nuevo. El anterior deja de funcionar al instante |
| PUT | `/api/dex/developer/keys/{key_id}/expiry` | Fija la validez desde ahora: 30, 90, 360 o 2000 días |
| POST | `/api/dex/developer/keys/{key_id}/agent` | Crea (o devuelve) el agente de trading de la clave y la autorización a firmar |
| POST | `/api/dex/developer/keys/{key_id}/agent/grant` | Guarda la autorización firmada por la wallet tras verificarla |
| PUT | `/api/dex/developer/keys/{key_id}/executor` | Vincula la clave a un ejecutor para la ejecución delegada |
| POST | `/api/dex/developer/keys/{key_id}/execution-payment` | Prepara una transacción que firma la wallet; administrar claves nunca concede permisos de gasto por sí mismo |
| DELETE | `/api/dex/developer/keys/{key_id}` | Revoca la clave (y su agente). Se puede repetir sin riesgo |
| GET | `/api/dex/developer/audit` | Registro de auditoría de la actividad de credenciales |
| GET, POST | `/api/dex/developer/webhooks` | Lista o crea suscripciones de webhook |
| DELETE | `/api/dex/developer/webhooks/{webhook_id}` | Desactiva una suscripción de webhook |

Las rutas de desarrollador admiten hasta 10 peticiones por segundo por IP.

## Lista de seguridad

- Usa una clave por bot o servicio, para poder revocar una sin parar las demás.
- Concede los scopes mínimos, fija una caducidad y, si tu servidor tiene IP fija, una lista de IP permitidas.
- Guarda las claves en un gestor de secretos o en variables de entorno, nunca en el código ni en los registros.
- Rota las claves periódicamente y de inmediato si sospechas una filtración; revoca las que ya no uses.
- Verifica la firma de los webhooks y descarta duplicados por su ID (ver [Tiempo real y webhooks](https://docs.botradix.com/es/api-realtime/)).