> For the complete documentation index, see [llms.txt](https://docs.nexus.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexus.xyz/exchange/apis-and-rates/exchange-rest.md).

# Exchange REST

Base URL: `https://exchange.nexus.xyz/api/exchange`

All routes **except** `/health`, `/openapi.json`, and `/auth/login` require HMAC authentication (see Quickstart → Sign requests). The complete machine-readable schema, including request/response bodies and CCXT method mappings, is at `/openapi.json`.

Conventions:

* All monetary values are decimal **strings**.
* On single-order routes, `market_id` is **required** as a query parameter — the engine routes directly to the owning market.
* Authenticated requests carry `X-API-Key`, `X-Timestamp`, `X-Signature`. The timestamp must be within ±30s of server time.

### Authentication & keys

| Method | Path          | Auth    | Description                                                     |
| ------ | ------------- | ------- | --------------------------------------------------------------- |
| POST   | `/auth/login` | —       | EIP-191 wallet signature → 24h session Bearer token             |
| POST   | `/keys`       | Session | Create an HMAC API key (`key_id` + `secret`; secret shown once) |
| GET    | `/keys`       | Session | List your API keys                                              |
| DELETE | `/keys/{id}`  | Session | Revoke an API key                                               |
| POST   | `/ws-tokens`  | HMAC    | Mint a 60s single-use token for a WebSocket subscription        |

### Account

| Method | Path                                    | Auth | Description                                                           |
| ------ | --------------------------------------- | ---- | --------------------------------------------------------------------- |
| GET    | `/account`                              | HMAC | Balance, equity, margin used, margin ratio                            |
| GET    | `/positions`                            | HMAC | Open positions with unrealized PnL                                    |
| POST   | `/account/credit`                       | HMAC | Faucet synthetic USDX (testnet; up to 500/day per key)                |
| GET    | `/account/{address}/adl-history?limit=` | HMAC | Auto-deleveraging events where the account was target or counterparty |

### Orders

| Method | Path                      | Auth | Description                                                        |
| ------ | ------------------------- | ---- | ------------------------------------------------------------------ |
| POST   | `/orders`                 | HMAC | Place a limit or market order                                      |
| POST   | `/orders/batch`           | HMAC | Place multiple orders (sequential; results preserve request order) |
| GET    | `/orders`                 | HMAC | List open orders                                                   |
| GET    | `/orders/{id}?market_id=` | HMAC | Get a single order                                                 |
| PATCH  | `/orders/{id}?market_id=` | HMAC | Amend an order                                                     |
| DELETE | `/orders/{id}?market_id=` | HMAC | Cancel a single order                                              |
| DELETE | `/orders?market_id=`      | HMAC | Cancel all open orders in a market                                 |

Order body fields: `market_id`, `side` (`Buy`/`Sell`), `order_type` (`Limit`/`Market`), `quantity`, `price` (limit only), `time_in_force` (`GTC`/`IOC`/`FOK`), and optional `reduce_only`.

### Market data

| Method | Path                              | Description                                            |
| ------ | --------------------------------- | ------------------------------------------------------ |
| GET    | `/markets`                        | List all live markets and their status                 |
| GET    | `/markets/summary`                | Mark price, 24h volume, trade count, status per market |
| GET    | `/markets/{id}/ticker`            | Last / bid / ask / volume / change                     |
| GET    | `/markets/{id}/orderbook`         | L2 order book depth                                    |
| GET    | `/markets/{id}/trades`            | Recent trades                                          |
| GET    | `/markets/{id}/candles`           | OHLCV candles (1m / 5m / 1h)                           |
| GET    | `/markets/{id}/funding`           | Funding rate history                                   |
| GET    | `/markets/{id}/mark-price`        | Current mark price                                     |
| GET    | `/markets/{id}/status`            | Active/halted, reason, timestamp, ADL count            |
| GET    | `/markets/{id}/adl-events?limit=` | Per-market auto-deleveraging history                   |
| GET    | `/tickers`                        | All tickers in one call                                |
| GET    | `/stats`, `/stats/history`        | Exchange-wide stats                                    |

### Streaming

Real-time order book, trade, and account updates are delivered over WebSocket, not REST. See the WebSocket API Reference.

> **Status:** testnet preview. Endpoint set tracks the versioned OpenAPI spec at [`nexus-xyz/nexus-exchange-api`](https://github.com/nexus-xyz/nexus-exchange-api); consult `/openapi.json` for the authoritative, current schema.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nexus.xyz/exchange/apis-and-rates/exchange-rest.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.