API overview

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	`userConnected` + Clerk JWT	Guided steps and ladder trading
Mirage	`userConnected` + Clerk JWT	Timed PM order via `mirageStartSession`, countdown, broker
Artefact	`userConnected` + Clerk JWT	Interview arb on three ladders
Atlas	`userConnected` + Clerk JWT	Headline feed and two-stock book
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`)

{
  "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. 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" \| … }`

Tutorial · Mirage · Artefact · Atlas · Opera

Overview

Simulators

Opera schemas

Auth

UI simulators (`userConnected`)

Opera API clients (`operaConnect`)

Shared trading (UI clients)

Instruments

Common server messages

​Auth

​UI simulators (userConnected)

​Opera API clients (operaConnect)

​Shared trading (UI clients)

​Instruments

​Common server messages

​Related guides

Auth

UI simulators (`userConnected`)

Opera API clients (`operaConnect`)

Shared trading (UI clients)

Instruments

Common server messages

Related guides