# API reference

> Every v1 endpoint with method, scope and purpose.

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

All paths below are relative to `https://app.botradix.com/api/dex/v1` and require an API key with the listed scope. Responses are JSON. Read limits, precision, tick size and order sizes from `/markets` and `/meta` at runtime instead of hard-coding them.

## Market data

| Method | Path | Scope | Purpose |
|---|---|---|---|
| GET | `/status` | `market:read` | API, network and market-engine status |
| GET | `/meta` | `market:read` | Schema versions, scopes and published capabilities |
| GET | `/markets` | `market:read` | Market catalogue with per-market precision and order limits |
| GET | `/candles` | `market:read` | Candles by `pair_id`, `interval` and `limit` |
| GET | `/snapshot` | `market:read` | Market snapshot and current sequence |
| GET | `/summary` | `market:read` | Summary of one market (`pair_id`) |
| GET | `/summaries` | `market:read` | Summaries of all markets |
| GET | `/markets/{pair_id}/funding` | `market:read` | Funding state of one market |
| GET | `/markets/{pair_id}/open-interest` | `market:read` | Long and short open interest of one market |
| GET | `/orderbook` | `market:read` | Order book derived from the available on-chain state |
| GET | `/vault` | `market:read` | Public state of the DEX liquidity vault |

## Account (the key's wallet)

| Method | Path | Scope | Purpose |
|---|---|---|---|
| GET | `/account` | `account:read` | Equity, collateral, margin, health factor and liquidation state |
| GET | `/positions` | `account:read` | Open positions, with mark and liquidation prices |
| GET | `/orders` | `account:read` | Orders indexed from the contracts (paginated) |
| GET | `/orders/by-client-id` | `account:read` | Finds a prepared `open_position` by `client_order_id` |
| GET | `/collateral` | `account:read` | Collateral balances and related account state |
| POST | `/risk/preview` | `account:read` | Risk preview of a change before you execute it |
| GET | `/transactions` | `account:read` | Prepared intents and their on-chain state (paginated) |
| GET | `/trades` | `account:read` | Executed trades indexed from the chain (paginated) |
| GET | `/positions/history` | `account:read` | Closed positions (paginated) |
| GET | `/native/executions/{tx_hash}` | `account:read` | Finality of one execution: `PENDING`, `PENDING_FINALITY` (fewer than 8 confirmations), `REVERTED` or `FINAL`. Optional `account` and `trade_id` |
| GET | `/executions/{command_id}` | `account:read` | Status of a delegated execution |
| GET | `/stream` | `account:read` | Private Server-Sent Events stream. **Not enabled on the public service yet** (see below) |

## Trading

| Method | Path | Scope | Purpose |
|---|---|---|---|
| POST | `/orders/prepare` | Depends on the action | Validates an action and returns what is needed to execute it. Idempotency key required |
| POST | `/orders/execute` | `trade:execute` (plus `orders:manage` for cancel, replace and TP/SL primitives) | Delegated execution, when an executor is bound to the key |

Actions and the scope each one needs:

| Action | 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` |

The full flow, fields and an example are in [Trading through the API](https://docs.botradix.com/api-orders/).

## Pagination

Paginated endpoints accept `cursor` and `limit` (default 50, maximum 200) and return:

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

The object is nested under `orders`, `transactions`, `trades` or `history` depending on the endpoint. Pass `next_cursor` back as `cursor` to get the next page.

## The real-time stream

`GET /stream?pair_id={id}&interval=1m` is designed as a private Server-Sent Events stream (market snapshot, private account snapshot and lifecycle events, with a heartbeat every 12 seconds). It is **not enabled on the public service at the moment** and answers `503 REALTIME_STREAM_ASYNC_WORKER_REQUIRED` with `Retry-After: 5`. Until it is enabled, use [webhooks](https://docs.botradix.com/api-realtime/) for account events and poll the read endpoints within your rate limits.

## Public endpoints without an API key

The web terminal uses unversioned endpoints that anyone can read. They are convenient for dashboards, but they are **not** a stable contract and may change without notice; integrations should prefer `/api/dex/v1`.

| Path (under `https://app.botradix.com`) | Content |
|---|---|
| `/api/dex/config` | Execution, order, fee and precision models, and developer API capabilities |
| `/api/dex/markets`, `/api/dex/summaries`, `/api/dex/summary` | Markets and summaries |
| `/api/dex/candles`, `/api/dex/candles/history` | Candles (1m, 3m, 5m, 15m, 1h, 4h, 1d, 1w). History is paged with `before`, up to 50,000 candles; on 1d and 1w it continues with older external history, named in `history_sources` |
| `/api/dex/marks?pair_ids=1,2` | Mark prices for 1 to 12 markets |
| `/api/dex/orderbook`, `/api/dex/vault`, `/api/dex/liquidations` | Order book, vault and recent liquidations |
| `/api/dex/markets/{id}/funding`, `/api/dex/markets/{id}/open-interest` | Funding and open interest |
| `/api/dex/status`, `/api/dex/circuit-breakers` | Service status and safety switches |
| `/api/dex/account?wallet=0x…` (also `positions`, `orders`, `collateral`, `transactions`, `trades`, `positions/history`) | Read-only views of any wallet. On-chain positions are public by nature |
| `/api/public/baq-market`, `/api/public/baq-metrics` | BAQ market data and metrics (see [BAQ](https://docs.botradix.com/baq/)) |