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

# Mirage

> Execute a PM order against a live ladder

Mirage puts you on a single stock ladder executing an order from a Portfolio Manager (PM). You have a timed session to finish with the required quantity while staying within the price level.

## Objective

Complete the PM order. Aim for a good fill price, but prioritize getting the full quantity.

Skills targeted: order placement and cancellation, position management, adaptive trading style.

Open Mirage from the Simulator hub (or go to `/mirage`).

## How a session works

1. Click **Start session** in the broker panel (or send `mirageStartSession` over the WebSocket).
2. Bots turn on, the countdown starts, and the PM order appears in the broker panel (side, quantity, and price level).
3. Trade on the ladder until your position matches the target (or time runs out).
4. Session length defaults to **60 seconds** and is configurable under Mirage Settings (1–600 s).

Starting again while a session is already running does not stop bots or restart the clock; it returns the same PM order.

## Mirage Score

After a run, the Mirage Score (0–1) measures how well your execution matched the given order.

### Weights

* **Quantity** (30%) — Did you get the right position size?
* **Price** (30%) — Did you get good fill prices?
* **Profit** (40%) — Did you make money?

### Formula

**Quantity Score:**
$qty\_score = e^{-\frac{(fill\_qty - target\_qty)^2}{2|target\_qty|}}$

**Price Score:**
$px\_improvement = (target\_px - fill\_px) \times \text{sign}(target\_qty)$

$px\_score = \frac{1}{1 + e^{-\frac{px\_improvement}{|target\_px| \times 0.1}}}$

**Profitability Score:**
$pnl\_score = 0.5 + 0.5 \times \tanh\left(\frac{pnl}{|target\_qty \times target\_px| \times 0.01}\right)$

**Final Score:**
$final\_score = (qty\_score \times 0.3) + (px\_score \times 0.3) + (pnl\_score \times 0.4)$

$mirage\_score = \max(0, \min(1, final\_score))$

### Examples

**Perfect execution with profit**

* Target: Buy 100 shares at 50 limit
* Actual: Bought 100 at 50 average, P\&L +1,000
* Score: **0.85**

**Good price, flat P\&L**

* Target: Buy 100 at 50
* Actual: Bought 100 at 40 average, P\&L 0
* Score: **0.76**

**Partial fill**

* Target: Buy 100 at 50
* Actual: Bought 75 at 50, P\&L 0
* Score: **0.36**

**Zero fill**

* Target: Buy 100 at 50
* Actual: Bought 0
* Score: **0.00**

## Related

* Interface basics: [Tutorial](/tutorial)
* Spread arb: [Artefact](/artefact)
* WebSocket API: [Mirage](/api-reference/mirage)