Artefact

Artefact runs a timed interview on three instruments (A, B, A−B). Connect as a UI client, start the interview, trade the arb, then end to receive a report. Product overview: Artefact. Shared connect and order fields: API overview.

Protocol

Connect to wss://www.getavenir.co/ws
{ "action": "userConnected", "token": "<Clerk JWT>", "applicationType": "artefact" }
Receive artefactConfig and orderBook
{ "action": "startInterview" } — bots on, timer starts
Trade with placeOrder / cancelOrder on instrumentId 1, 2, or 3
{ "action": "endInterview" } — bots off; server pushes interviewReport
Persist with recordSession if you want a past-session row (not automatic on disconnect)

Interview lifecycle actions require a UI socket (userConnected), not an Opera API client.

Client actions

Action	Body	Effect
`userConnected`	`token`, `applicationType: "artefact"`, `sessionId?`	Bind UI socket; push config
`startInterview`	`startTimestamp?`	Create interview; activate bots
`endInterview`	`endTimestamp?`	Stop bots; push `interviewReport`
`clearInterview`	—	Drop interview state
`getInterviewReport`	—	Re-push report or `{ error: "not_found" }`
`placeOrder` / `cancelOrder` / `cancelAllOrders`	See overview	`instrumentId` ∈ `{1,2,3}`
`resetExchange`	—	Reset book without logging a session
`recordSession`	`startTime`, `endTime`, `pnl`, `cash`, `passed`, `positionsByInstrument`, `pnlByInstrument`, `recap?`, `sessionId?`	Explicit past-session write
`setBotsActive`	`active: false`	Bots off

Server messages

`artefactConfig`

{
  "type": "artefactConfig",
  "interviewCountdownSeconds": 60,
  "laddersByInstrument": { }
}

Sent on connect. Ladder bounds for instruments 1–3 are in laddersByInstrument.

`interviewReport`

{
  "type": "interviewReport",
  "report": {
    "startTimestamp": 1710000000000,
    "endTimestamp": 1710000060000,
    "duration": 60,
    "finalPnL": 120,
    "cash": 80,
    "positionsByInstrument": { "1": 2, "2": -2, "3": 0 },
    "pnlByInstrument": { },
    "marketAnalysis": {
      "topOfBook": [],
      "impliedSpread": {},
      "arbitrageOpportunities": []
    }
  }
}

Or { "type": "interviewReport", "error": "not_found" } when no report exists.

Field	Notes
`finalPnL`	Used with arb analysis for pass/fail in the UI
`marketAnalysis`	Initial books, implied spread, detected arbs
Mark pricing	Last trade if present, else mid (differs from Mirage)

`orderBook`

Multi-instrument book for 1, 2, and 3.

Guide: Artefact
Shared auth and orders: API overview

Overview

Simulators

Opera schemas

Protocol

Client actions

Server messages

`artefactConfig`

`interviewReport`

`orderBook`

​Protocol

​Client actions

​Server messages

​artefactConfig

​interviewReport

​orderBook

​Related

Protocol

Client actions

Server messages

`artefactConfig`

`interviewReport`

`orderBook`

Related