API overview and authentication

The BotRadix DEX API (version 1) lets a server, bot or integration read market data and one wallet's account, and prepare or execute trading actions for that wallet. It is a JSON API over HTTPS.

At a glance#

Two kinds of credentials#

BotRadix separates managing credentials from using them:

1. Developer session. Proves that you control a wallet. You get it by signing a text message with that wallet; this is free and sends no transaction. A session lasts 4 hours and is used only to create, rotate and revoke API keys and to manage webhooks.
2. API key. Used by your server or bot for every /api/dex/v1 call. Each key belongs to exactly one wallet and has its own scopes, expiry, rate limits and an optional IP allowlist.

A trading API key cannot manage other keys, and a developer session cannot call the trading API.

Sending the API key#

Send the key in the X-BotRadix-API-Key header:

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

Authorization: Bearer <key> is also accepted. If both are present, X-BotRadix-API-Key wins. Keys start with BRX.

Without a key the API answers 401 API_KEY_REQUIRED. See Errors, limits and versioning for every authentication error.

Getting a developer session#

1. Ask for a challenge for your wallet. It expires after 5 minutes.
2. Sign the returned message exactly as received, with personal_sign (a plain message signature, not a transaction).
3. Exchange the nonce and signature for a developer session.

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

# 2. Sign "message" with the wallet (personal_sign).

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

The challenge text names the wallet, the host, the network (Base, 8453), the nonce and the expiry, so it cannot be replayed elsewhere. After five wrong signatures the challenge is discarded.

All key and webhook management calls then use Authorization: Bearer <developer_session>.

Creating an API key#

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

The response (201) contains the full key in api_key. It is shown only once. A wallet can hold up to 10 active keys.

Scopes#

Give each key only the scopes it needs.

Managing keys and webhooks#

Developer routes are limited to 10 requests per second per IP address.

Security checklist#

• Use one key per bot or service, so you can revoke one without stopping the others.
• Grant the minimum scopes, set an expiry and, if your server has a fixed IP, an IP allowlist.
• Store keys in a secrets manager or environment variables, never in code or logs.
• Rotate keys periodically and immediately if you suspect a leak; revoke keys you no longer use.
• Verify webhook signatures and deduplicate events by ID (see Real-time data and webhooks).