# API overview and authentication

> Base URL, API keys, scopes, wallet-signed developer sessions and key management.

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

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

| Item | Value |
|---|---|
| Base URL | `https://app.botradix.com/api/dex/v1` (the same API also answers on `https://botradix.com/api/dex/v1`) |
| Network | Base mainnet, chain ID `8453` |
| Format | JSON, UTF-8. Request bodies up to 48 KiB |
| Authentication | An API key bound to one wallet, with scopes |
| Version headers | `X-BotRadix-API-Version: v1` and `X-BotRadix-API-Schema: botradix-dex-api-v1.1` |
| Request tracing | Every response carries `X-Request-ID`; you can send your own (8–80 characters of `A-Z a-z 0-9 . _ : -`) |
| Browser access | Same-origin only. Call the API from your server, never from a public web page |

> [!IMPORTANT]
> An API key is a secret that can act on your wallet's DEX account within its scopes. Keep it on a server or in a secrets manager. Never embed it in a website, a mobile app or a public repository.

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

```bash
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](https://docs.botradix.com/api-errors/) 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.

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

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

| Field | Rules |
|---|---|
| `label` | A name for your own reference |
| `scopes` | Any of the scopes below. Unknown scopes are ignored; if none is valid the request fails. If omitted, the key receives every scope except `collateral:manage` |
| `expires_in_days` | 1 to 2000. Default 180 |
| `ip_allowlist` | Optional list (or comma-separated string) of IP addresses or CIDR ranges. Requests from other addresses get `403 IP_NOT_ALLOWED` |
| `quotas` | Optional per-key rate limits, within the caps in [Errors, limits and versioning](https://docs.botradix.com/api-errors/) |

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

> [!NOTE]
> Keys created from the **API** view of the DEX terminal are "bot-ready": the wallet also signs a one-time trading-agent grant, and the key receives the default scopes. To choose scopes yourself, create the key through the API as shown above.

## Scopes

| Scope | Allows |
|---|---|
| `market:read` | Markets, candles, summaries, funding, open interest, order book and vault data |
| `account:read` | The key's wallet: account, positions, orders, collateral, transactions, trades, history and execution status |
| `trade:prepare` | Preparing opens, closes, inversions, TP/SL updates and isolated-margin changes |
| `trade:execute` | Delegated execution through `/orders/execute`, when an executor is bound to the key |
| `orders:manage` | Cancelling and replacing orders, and TP/SL primitives in delegated execution |
| `collateral:manage` | Preparing collateral deposits and withdrawals |

Give each key only the scopes it needs.

## Managing keys and webhooks

| Method | Path | Purpose |
|---|---|---|
| POST | `/api/dex/developer/challenge` | Message for the wallet to sign |
| POST | `/api/dex/developer/session` | Verifies the signature and returns a 4-hour developer session |
| GET | `/api/dex/developer/keys` | Lists the wallet's keys (up to 64) |
| POST | `/api/dex/developer/keys` | Creates a key |
| POST | `/api/dex/developer/keys/prepare` | Step 1 of a bot-ready key: a new trading agent and the grant the wallet signs once. Nothing is created until that signature is sent with `POST /keys` (valid 30 minutes) |
| POST | `/api/dex/developer/keys/{key_id}/rotate` | Issues a new secret. The previous secret stops working immediately |
| PUT | `/api/dex/developer/keys/{key_id}/expiry` | Sets the validity from now: 30, 90, 360 or 2000 days |
| POST | `/api/dex/developer/keys/{key_id}/agent` | Creates (or returns) the key's trading agent and the grant to sign |
| POST | `/api/dex/developer/keys/{key_id}/agent/grant` | Stores the wallet's signed agent grant after verifying it |
| PUT | `/api/dex/developer/keys/{key_id}/executor` | Binds the key to one executor for delegated execution |
| POST | `/api/dex/developer/keys/{key_id}/execution-payment` | Prepares a transaction for the wallet to sign; managing keys never grants spending rights by itself |
| DELETE | `/api/dex/developer/keys/{key_id}` | Revokes the key (and its agent). Safe to repeat |
| GET | `/api/dex/developer/audit` | Audit log of credential activity |
| GET, POST | `/api/dex/developer/webhooks` | Lists or creates webhook subscriptions |
| DELETE | `/api/dex/developer/webhooks/{webhook_id}` | Disables a webhook subscription |

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](https://docs.botradix.com/api-realtime/)).