> ## 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.

# Artefact

> WebSocket API for the Artefact interview simulator

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](/artefact). Shared connect and order fields: [API overview](/api-reference/introduction).

## Protocol

1. Connect to `wss://www.getavenir.co/ws`
2. `{ "action": "userConnected", "token": "<Clerk JWT>", "applicationType": "artefact" }`
3. Receive `artefactConfig` and `orderBook`
4. `{ "action": "startInterview" }` — bots on, timer starts
5. Trade with `placeOrder` / `cancelOrder` on `instrumentId` `1`, `2`, or `3`
6. `{ "action": "endInterview" }` — bots off; server pushes `interviewReport`
7. 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](/api-reference/introduction)                                                                         | `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`

```json theme={null}
{
  "type": "artefactConfig",
  "interviewCountdownSeconds": 60,
  "laddersByInstrument": { }
}
```

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

### `interviewReport`

```json theme={null}
{
  "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`.

## Related

* Guide: [Artefact](/artefact)
* Shared auth and orders: [API overview](/api-reference/introduction)