API: visión general y autenticación

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#

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:

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.

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.

# 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#

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"]
  }'

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

Scopes#

Da a cada clave solo los scopes que necesite.

Gestión de claves y webhooks#

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