> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getavenir.co/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> WebSocket APIs for every Avenir simulator

All simulator traffic uses `wss://www.getavenir.co/ws` as JSON text frames. Set `action` on client messages; the server replies and pushes with `type`.

| Simulator                           | Connect                            | Purpose                                                    |
| ----------------------------------- | ---------------------------------- | ---------------------------------------------------------- |
| [Tutorial](/api-reference/tutorial) | `userConnected` + Clerk JWT        | Guided steps and ladder trading                            |
| [Mirage](/api-reference/mirage)     | `userConnected` + Clerk JWT        | Timed PM order via `mirageStartSession`, countdown, broker |
| [Artefact](/api-reference/artefact) | `userConnected` + Clerk JWT        | Interview arb on three ladders                             |
| [Atlas](/api-reference/atlas)       | `userConnected` + Clerk JWT        | Headline feed and two-stock book                           |
| [Opera](/api-reference/opera)       | `operaConnect` + short-lived token | External bots; request/response orders                     |

Trading is WebSocket-only. Past sessions and leaderboards use separate REST routes under `/api`.

## Auth

### UI simulators (`userConnected`)

```json theme={null}
{
  "action": "userConnected",
  "token": "<Clerk session JWT>",
  "applicationType": "mirage",
  "sessionId": "optional-client-id"
}
```

* Identity comes from `token` (`sub`). Do not rely on a client-supplied `userId`.
* `applicationType` must be one of: `tutorial`, `mirage`, `artefact`, `atlas`, `opera`.
* Access is checked server-side (`forbidden` if you lack simulator access).
* Marks the socket as a **UI** client. Only one live UI socket per user per app; a new connect can close the old one (`superseded`).
* Wait for the first `orderBook` (and any app bootstrap push) before sending trading or session-start actions — `userConnected` auth is async.

Get a Clerk JWT the same way the web app does (signed-in session). Tokens expire; reconnect with a fresh JWT on `unauthorized`.

### Opera API clients (`operaConnect`)

External bots authenticate with a short-lived token copied from `/opera`. See [Opera](/api-reference/opera). That path marks the socket as an **API** client and blocks UI-only actions.

## Shared trading (UI clients)

Tutorial, Mirage, Artefact, and Atlas place and cancel with these actions (UI sockets only). There is no per-order ack; watch `orderBook` (and app-specific pushes). Invalid place/cancel (bad instrument, off-ladder price, not your order) and rate-limit hits are usually dropped without a client error frame.

| Action            | Body                                                                   | Notes                                                     |
| ----------------- | ---------------------------------------------------------------------- | --------------------------------------------------------- |
| `placeOrder`      | `type` (`bid`\|`ask`), `price`, `quantity`, `orderId`, `instrumentId?` | Price must land on a ladder tick. Default instrument `0`. |
| `cancelOrder`     | `orderId`, `instrumentId?`                                             | Own orders only                                           |
| `cancelAllOrders` | —                                                                      | Cancels your resting orders                               |
| `setBotsActive`   | `active: false`                                                        | Turns bots off only                                       |
| `resetExchange`   | `sessionId?`                                                           | Resets the book; may log a session depending on the app   |
| `recordSession`   | app-specific fields                                                    | Persist a past session                                    |

Rate limits (per user per app): **120** places and **240** cancels per 60 seconds.

### Instruments

| App                     | `instrumentId`              |
| ----------------------- | --------------------------- |
| Tutorial, Mirage, Opera | `0`                         |
| Atlas                   | `1`, `2`                    |
| Artefact                | `1` (A), `2` (B), `3` (A−B) |

### Common server messages

| Type        | Role                                                            |
| ----------- | --------------------------------------------------------------- |
| `orderBook` | Open orders, participants, bots flags, volume-by-price          |
| `error`     | `{ error: "unauthorized" \| "forbidden" \| "superseded" \| … }` |

## Related guides

* [Tutorial](/tutorial) · [Mirage](/mirage) · [Artefact](/artefact) · [Atlas](/atlas) · [Opera](/opera)