# Build with AI (/docs/ai)



Vike ships two [Model Context Protocol](https://modelcontextprotocol.io/) servers. They know
nothing about each other, and one MCP client can hold both at once.

**[Data API — 31 tools](/docs/ai/data)** — `https://vike.io/mcp`, remote HTTP. Vike runs it; your client
holds a URL and a credential from your Vike account (an `X-API-KEY`, or an OAuth connection for
clients that register themselves). Wallets, tokens, Polymarket and on-chain
transfer alerts. Every call is metered against one hourly budget.

**[Trader — 17 tools](/docs/ai/trader)** — `vike-cli mcp`, a local stdio subprocess your client
launches. No Vike account is involved: it talks to services *you* run — a `vike-datahub` for
backtests, a `vike-tradehub` node for live state and orders — authenticated with your own daemon's
HMAC node keys. Rhai strategy authoring, backtests, sweeps, walk-forwards, and order writes behind
a mandatory preview gate. Nothing is metered.

The difference to carry into setup: one is a URL you point a client at, the other is a command the
client runs. They are configured in different places, and their credentials are different kinds of
thing — an account key versus the keys of a daemon on your own machine.

⚠ Nothing in the navigation links here. The sidebar's product switcher moves between the two
servers directly, so this page exists only for a saved URL. Follow one of the two links above.


# Changelog (/docs/changelog)



The two products version independently and change for different reasons, so they keep separate
records. The switcher in the sidebar moves between them.

## Data API [#data-api]

A **service**, so it changes underneath you: `/v1` routes added and removed, MCP tools added and
fixed, response fields that appeared or changed meaning, and the auth and metering rules on the
bulk archive. There is one published version prefix and routes have been removed *inside* it, so
entries that require a caller to change something are marked **⚠ BREAKING**.

[Read the Data API changelog](/docs/changelog/data)

## Trader [#trader]

A **binary you install**, so nothing changes until you upgrade. One section per released version,
newest first, with what a user gets and what changes behaviour on a box that is already running.

[Read the Trader changelog](/docs/changelog/trader)

<Callout title="Neither page links to a commit">
  The product repository is private. Entries carry a PR number and a commit sha so they can be
  quoted in a support request, but there is nothing to click — which is worth saying once here
  rather than letting you discover it a link at a time.
</Callout>


# Authentication (/docs/data/authentication)



Vike's data planes accept two kinds of credential. All three surfaces authenticate the same way, and
try them in a fixed order:

1. `Authorization: Bearer vk_oat_...` — an OAuth 2.1 access token.
2. `X-API-KEY: vk_...` — an API key.

An invalid bearer token **falls through** to the API-key header rather than failing outright, so a
request may carry either or both. If neither validates, the request is rejected.

| Surface                            | Credential                                                                      |
| ---------------------------------- | ------------------------------------------------------------------------------- |
| `https://vike.io/mcp`              | either — OAuth for desktop clients, `X-API-KEY` for everything else             |
| `https://data.vike.io/v1/...`      | `X-API-Key` header                                                              |
| `https://data.vike.io/archive/...` | `X-API-Key` header (the `manifest.json` index and `/archive/samples/` are open) |

The credential always travels in a header. There is no query-string form, and adding one to a URL
authenticates nothing.

## API keys [#api-keys]

Create keys at [vike.io/account?tab=api-keys](https://vike.io/account?tab=api-keys). A key is the
literal prefix `vk_` followed by 40 bytes of cryptographic randomness, so match on the prefix if you
need to recognise one, and never on its length or shape beyond that.

**Up to 5 active keys per account.** Creating a sixth is refused with a 400. The count is of
*active* keys, so deactivating or deleting one frees a slot.

Every key today has identical reach. There are no scopes to choose between and no way to narrow a
key to a subset of the API, so a key is read access to everything your account can reach.

### Keys are recoverable [#keys-are-recoverable]

Unlike most API products, Vike stores an encrypted copy of the full key at creation, so you can read
it back later from the account page rather than losing it the moment the dialog closes.

The exception is keys created before that behaviour existed: those have no stored copy, and the
reveal endpoint answers with a 410 telling you to create a new one. If you are holding a key old
enough to hit that, rotating it is the fix.

### Using one [#using-one]

```sh
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/onchain/tokens/search?q=USDC&limit=3"
```

The header name is matched case-insensitively, so `X-API-KEY` and `X-API-Key` both work.

<Callout title="One key, one budget">
  The hourly rate limit is counted **per key**, not per account — so a second key is a legitimate way
  to keep a bulk archive job from starving an interactive MCP client. OAuth tokens work the other way
  round and share one pooled counter per user. [Rate limits](/docs/data/rate-limits) has the details.
</Callout>

## OAuth 2.1 [#oauth-21]

Claude Desktop and other clients that support Dynamic Client Registration
([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) need no API key at all. Vike registers
the client automatically; you log in once in a browser tab and approve.

Discovery metadata is published at
`https://vike.io/.well-known/oauth-authorization-server`:

| Field                    | Value                             |
| ------------------------ | --------------------------------- |
| `issuer`                 | `https://vike.io`                 |
| `registration_endpoint`  | `https://vike.io/oauth/register`  |
| `authorization_endpoint` | `https://vike.io/oauth/authorize` |
| `token_endpoint`         | `https://vike.io/oauth/token`     |
| `scopes_supported`       | `mcp:tools`                       |

Access tokens are prefixed `vk_oat_` and go in an `Authorization: Bearer` header. Connected apps are
listed — and can be revoked — under **Account → API Keys → Connected Apps**.

[Getting started](/docs/data/getting-started) walks through the Claude Desktop connector flow step by
step.

## Credential decisions are cached [#credential-decisions-are-cached]

The verdict of a credential check is cached briefly, keyed on a hash of the credential and never on
the credential itself. Two windows matter to you as a user:

* **A valid credential is trusted for up to 45 seconds** before it is re-checked against the
  account record. This is also the worst case for **revocation**: a deleted or deactivated key, or a
  revoked OAuth token, can keep working for a few seconds afterwards. It is a deliberate trade —
  the blast radius is a few seconds of extra reads on a data API — but it means revocation is not
  instantaneous, and any page that says it is is wrong.
* **An invalid credential is remembered as invalid for up to 8 seconds.** If you just fixed a typo'd
  key, give it a few seconds before concluding the new one is broken too.

A check that fails for an *infrastructural* reason rather than a credential one is deliberately
never cached, so a transient outage cannot turn into a multi-second rejection of a credential that
is actually valid.

## Keeping a key safe [#keeping-a-key-safe]

* Put it in an environment variable or a secret store, not in source control. It grants read access
  to your whole quota.
* Rotate by creating the new key first, switching over, then deleting the old one — deletion takes a
  few seconds to propagate through the cache above.
* If a key leaks, delete it. A deleted key stops authenticating within the 45-second window.

Rejections and their exact wire shapes are on [Errors](/docs/data/errors) — including the reason an
unauthenticated MCP call comes back as HTTP 200 rather than 401.


# Errors (/docs/data/errors)



Every Vike data surface answers failures with an HTTP status code, and usually a JSON body. The
status code is the part you should branch on; the body shape varies by which hop rejected you.

## Status codes [#status-codes]

| Code    | Meaning                                                                                                 |
| ------- | ------------------------------------------------------------------------------------------------------- |
| **200** | Success — *and* an MCP auth failure. See [the MCP exception](#mcp-answers-auth-failures-with-http-200). |
| **400** | Your input was rejected: an unknown market, a malformed identifier, both identity forms at once.        |
| **401** | Invalid or missing credential — on `/v1` and on the archive alike.                                      |
| **404** | No such route or file: a missing archive object, or a path that matches no endpoint.                    |
| **429** | Hourly rate limit exceeded. Carries `Retry-After`.                                                      |
| **503** | An upstream data-store failure. Not your fault; retry.                                                  |

Two properties worth relying on:

* **A failed query is never a 200 with an empty body.** An upstream failure comes back as a 503
  rather than an empty list, deliberately — a silent empty result is indistinguishable from "no
  data", which is how bad backfills get built on top of an outage.
* **There is no 403 today.** There are no scopes to be refused: every valid credential has the same
  reach across the whole API. The code exists in the error vocabulary for the day one appears.

## The JSON envelope [#the-json-envelope]

The API emits one envelope shape:

```json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Hourly rate limit exceeded",
    "retry_after": 60
  }
}
```

`retry_after` appears only on 429. The archive's own 401 carries a `docs` field instead:

```json
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "invalid or missing credential — see https://vike.io/docs/data/ for how to authenticate",
    "docs": "https://vike.io/docs/data/"
  }
}
```

<Callout type="warn" title="Branch on the status code, not the body">
  The envelope above is what the API emits. It is not always what reaches you.

  A credential rejection on `/v1` or on the archive is produced ahead of the API — the request is
  turned away before anything can build that envelope — so its body is not the shape above. Measured
  on 2026-09-02, a keyless request to a `/v1` path or to `https://data.vike.io/archive/` returns a
  correct **401** whose body is a stock **HTML** error page.
  Do not assume a 401 carries JSON.

  The status code and the `Retry-After` header are correct on every path and always have been. A
  client that parses the body to decide what happened will break on a hop it did not expect; a client
  that reads the status code will not.
</Callout>

## 429 and `Retry-After` [#429-and-retry-after]

A rate-limit trip returns **429*&#x2A; with &#x2A;*`Retry-After: 60`** on every surface. Every layer that can
return one quotes the same 60, deliberately, so two hops cannot disagree.

The value is an advisory back-off hint, not a promise. The hourly window slides continuously and the
counter refreshes on its own schedule, so "when will capacity exist" has no per-request answer
anyone stores. Sixty seconds is a sane hint chosen over a false precision.

What a client should do:

```python
r = requests.get(url, headers={"X-API-Key": key})
if r.status_code == 429:
    time.sleep(int(r.headers.get("Retry-After", 60)))
    # ...then retry. Do not retry immediately, and do not retry in a tight loop:
    # a rate-limited request is itself metered.
```

A rejected request is recorded and counted like any other, so retrying without backing off keeps you
rejected.
Almost every 429 in practice has one cause — see [Rate limits](/docs/data/rate-limits), particularly the
section on Range requests against the archive.

## MCP auth failures are HTTP 401 [#mcp-auth-failures-are-http-401]

`https://vike.io/mcp` speaks JSON-RPC 2.0, and both failure modes carry a JSON-RPC error object in
the body as well as an HTTP status:

| Failure                       | HTTP status                  | Body                                 |
| ----------------------------- | ---------------------------- | ------------------------------------ |
| Invalid or missing credential | **401** + `WWW-Authenticate` | JSON-RPC error object, code `-32000` |
| Hourly rate limit exceeded    | **429** + `Retry-After`      | JSON-RPC error object, code `-32000` |

An unauthenticated call returns this, with HTTP 401 and `WWW-Authenticate: Bearer resource_metadata="https://vike.io/.well-known/oauth-protected-resource"` (the MCP authorization spec — an OAuth client starts discovery from that URL):

```json
{"jsonrpc": "2.0", "id": null, "error": {"code": -32000, "message": "Invalid or missing API key"}}
```

A rate-limited call returns HTTP 429, and puts the envelope's fields in the JSON-RPC error's `data`
member so both kinds of client can read it:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "Hourly rate limit exceeded",
    "data": { "code": "RATE_LIMITED", "retry_after": 60 }
  }
}
```

Other JSON-RPC errors (`-32700` parse error, `-32601` unknown method or tool) still arrive at HTTP
200, so if you are writing a raw HTTP client against `/mcp`, **checking `response.ok` is not
enough** — you must also look for an `error` member in the body.

## Getting a 401 you did not expect [#getting-a-401-you-did-not-expect]

Three causes, in rough order of likelihood:

* **The header name.** The archive and `/v1` want `X-API-Key`. An OAuth token goes in
  `Authorization: Bearer`. A key in a query string is never read.
* **The key is inactive or was deleted.** Deletion is a soft delete; an inactive key authenticates
  no better than a deleted one.
* **You just changed something.** Credential decisions are cached for up to 45 seconds (positive)
  and 8 seconds (negative), so a newly fixed key can take a few seconds to start working and a
  revoked one a few seconds to stop. See [Authentication](/docs/data/authentication).


# Getting started (/docs/data/getting-started)



There are two ways to start, depending on what you are building.

* **An AI client** — Claude, Cursor, Gemini CLI, Copilot — connects to the MCP endpoint and gets the
  whole tool surface conversationally. Start at [Connect an MCP client](#connect-an-mcp-client).
* **Code** — a script, a notebook, a backfill — uses the REST API or the bulk archive with an API
  key. Start at [Get an API key](#get-an-api-key).

Claude Desktop needs no API key at all; every other path does.

## Claude Desktop — no API key needed [#claude-desktop--no-api-key-needed]

Claude Desktop supports OAuth 2.1 with Dynamic Client Registration, so Vike registers your client
automatically. There is no key to copy, no JSON file to edit and no Node.js involved.

1. Open **Settings → Connectors → Add custom connector**
2. Name: `Vike`
3. URL: `https://vike.io/mcp`
4. Leave the OAuth Client ID and Secret fields **empty**
5. Click **Add**. A browser tab opens — log into Vike and click **Allow**
6. The Vike tools appear under the hammer icon in the chat input

Revoke access at any time under **Account → API Keys → Connected Apps**.

## Get an API key [#get-an-api-key]

Every other client, and all REST and archive access, uses an API key.

1. Create an account at [vike.io](https://vike.io)
2. Go to [Account → API Keys](https://vike.io/account?tab=api-keys)
3. Enter a label (for example `Cursor`) and click **Create Key**
4. Copy the key — it starts with `vk_`

Up to **5 active keys** per account. Unlike most API products, Vike stores an encrypted copy, so you
can read a key back from that page later rather than losing it when the dialog closes.

Keep it in an environment variable for everything below:

```sh
export VIKE_API_KEY="vk_..."
```

## Connect an MCP client [#connect-an-mcp-client]

The endpoint is `https://vike.io/mcp` for every client. What follows is the short version;
[Client setup](/docs/ai/data/setup) has a page per client, with troubleshooting. Vike's second MCP
server — the local `vike-cli mcp` for the trading platform — is set up separately, on
[Trader / Client setup](/docs/ai/trader/setup).

<Callout title="One canonical MCP endpoint">
  Use `https://vike.io/mcp`. `data.vike.io/mcp` reaches the same server with the same tools and
  accepts the same API key, but OAuth clients such as Claude Desktop should use `vike.io/mcp`.
</Callout>

### Claude Code [#claude-code]

One command, user-scoped. Restart any open session afterwards.

```sh
claude mcp add --transport http vike https://vike.io/mcp \
  --header "X-API-KEY: $VIKE_API_KEY"
```

### Cursor [#cursor]

**Settings → MCP → Add new server**, or edit `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "vike": {
      "url": "https://vike.io/mcp",
      "headers": { "X-API-KEY": "YOUR_KEY" }
    }
  }
}
```

### Gemini CLI [#gemini-cli]

```sh
gemini mcp add --transport http \
  --header "X-API-KEY: $VIKE_API_KEY" \
  vike https://vike.io/mcp
```

### GitHub Copilot (VS Code) [#github-copilot-vs-code]

Create `.vscode/mcp.json` in your workspace and reload:

```json
{
  "servers": {
    "vike": {
      "type": "http",
      "url": "https://vike.io/mcp",
      "headers": { "X-API-KEY": "YOUR_KEY" }
    }
  }
}
```

### Raw HTTP [#raw-http]

JSON-RPC 2.0 over HTTP, for scripting or a one-off call:

```sh
curl https://vike.io/mcp \
  -H "X-API-KEY: $VIKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

<Callout type="warn" title="A raw HTTP client must read the body, not just the status">
  On `/mcp`, an authentication failure comes back as **HTTP 200** with a JSON-RPC error object in the
  body — that is what JSON-RPC specifies. Only the rate limit uses a real HTTP error status (429).
  Checking `response.ok` alone will make a rejected call look successful. See
  [Errors](/docs/data/errors).
</Callout>

### Verify it worked [#verify-it-worked]

Ask your assistant:

> Search for PEPE token using Vike

A working connection calls the `token_search` tool and returns matching tokens.

## Vike Skills (CLI playbooks) [#vike-skills-cli-playbooks]

Skill playbooks teach an agent how to use Vike's tools well. The installer auto-detects Claude Code,
Cursor, Codex, Copilot, Gemini CLI and many more.

Preview what is available:

```sh
npx skills add vike-io/vike-cli --list
```

Install:

```sh
npx skills add vike-io/vike-cli
```

## Your first REST call [#your-first-rest-call]

The REST API is plain JSON over HTTPS at `https://data.vike.io/v1`, keyed by the `X-API-Key` header:

```sh
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/hyperliquid/coins/BTC/cohort-metrics?hours=6"
```

Endpoints are grouped into namespaces — `hyperliquid` (35), `onchain` (15) and `polymarket` (11),
plus the archive, the spec surfaces and one WebSocket.
[API endpoints](/docs/endpoints/data) is the per-endpoint reference: one page per endpoint, each
with its method, full path and parameters.

## Your first archive download [#your-first-archive-download]

The bulk archive is date-partitioned Parquet at `https://data.vike.io/archive`. Start with the index,
which needs no key:

```sh
curl -s https://data.vike.io/archive/manifest.json | jq '.dates[0]'
```

It lists every available date and family with row counts and byte sizes, plus the schema of each
stream. Free daily samples live under `https://data.vike.io/archive/samples/`, also keyless.

Data files need a key. Download the whole file:

```sh
curl -O -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/archive/venue=polymarket/date=2026-09-01/trades.parquet"
```

<Callout type="warn" title="Download archive files — do not read them over HTTP">
  A Parquet reader pointed at a URL issues thousands of Range requests for a single file: one 1.26 GB
  partition was measured producing **20,237 separate HTTP requests**. Archive downloads do not spend
  your hourly budget, but each of those requests crosses the network at a per-connection cap, and a
  remote reader pays that cost again on every query. Download the file with `curl -O` (resume with
  `-C -`) and read the local copy. [Rate limits](/docs/data/rate-limits) has the measurements.
</Callout>

## Limits [#limits]

**20,000 requests per rolling hour**, counted per API key. MCP and REST calls both draw on that one
counter; archive downloads are authenticated and recorded, but never charged against it. OAuth
tokens are pooled per user instead of per key.

Older documentation quoting *100 calls/hour* or *2,000/hour* is out of date. Recent calls per key are
visible under **Account → API Keys**.

## Next [#next]

<Cards>
  <Card title="Authentication" href="/docs/data/authentication" description="Both credential types, which surface takes which, and the caching window that delays revocation." />

  <Card title="Rate limits" href="/docs/data/rate-limits" description="One counter shared by MCP and REST, why the archive is exempt from it, and what a 429 looks like." />

  <Card title="Errors" href="/docs/data/errors" description="Status codes, the JSON envelope, and why an MCP auth failure is an HTTP 200." />

  <Card title="MCP tools" href="/docs/ai/data" description="The full tool surface, what each one returns, and worked examples." />
</Cards>


# Vike Data API (/docs/data)



The Vike Data API serves market and on-chain data across three families — on-chain, Hyperliquid
and Polymarket — through three access planes: an MCP endpoint for AI agents, a JSON REST API, and a
bulk Parquet archive for research-scale downloads. It is free to start.

## Three ways in [#three-ways-in]

| Plane            | Where                          | Auth                                                                           |
| ---------------- | ------------------------------ | ------------------------------------------------------------------------------ |
| **MCP**          | `https://vike.io/mcp`          | connect from Claude or any MCP client                                          |
| **REST**         | `https://data.vike.io/v1`      | `X-API-Key` header                                                             |
| **Bulk archive** | `https://data.vike.io/archive` | `X-API-Key` for data files; the `manifest.json` index and the samples are open |

MCP and REST share one hourly budget per credential; archive downloads are authenticated but not
charged against it — see [Rate limits](/docs/data/rate-limits).

### MCP [#mcp]

Point an MCP client at `https://vike.io/mcp` and the whole tool surface is available
conversationally — token screening, wallet tracing, DeFi position decoding, Polymarket smart money,
and the rest. Claude Desktop connects over OAuth with no API key at all. All 31 tools are
documented under [Data tools](/docs/ai/data), and [Client setup](/docs/ai/data/setup) walks each client.

### REST [#rest]

Plain JSON over HTTPS, keyed by an `X-API-Key` header:

```sh
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/hyperliquid/coins/BTC/cohort-metrics?hours=6"
```

### Bulk archive [#bulk-archive]

Research-scale history as date-partitioned Parquet with Hive-style paths, for example the Polymarket
set:

```
/archive/venue=polymarket/date=YYYY-MM-DD/{book_events,trades,l1_quotes}.parquet
```

An open `manifest.json` (no key needed) lists available dates, per-stream schemas, row counts and
sizes, and there are free daily samples under `/archive/samples/`. A second, additive layout groups
the crypto up/down families by `asset` and `tenor` into much smaller files, so a single-family
consumer need not take a whole token-sorted day.

<Callout type="warn" title="Download archive files whole; do not read them over HTTP">
  The archive supports Range requests and every Parquet reader will use them, so a remote read of one
  file becomes thousands of separate HTTP requests over a capped connection — and repeats them on
  every query. Downloads do not spend your hourly budget, but a remote read is far slower than
  fetching the file with `curl -O` and reading the local copy. [Rate limits](/docs/data/rate-limits) has
  the measurements.
</Callout>

## The three families [#the-three-families]

* **onchain** — token screening, transfers and holders, wallet summaries, tracing and PnL, ENS.
* **hyperliquid** — perp top traders, position matching, per-coin cohort metrics, and Hyperliquid's
  own OHLCV candles.
* **polymarket** — markets and detail, smart money, wallet activity, plus the full-L2 bulk archive
  above.

## Start here [#start-here]

<Cards>
  <Card title="Getting started" href="/docs/data/getting-started" description="Connect an MCP client in one command, or get a key and make your first REST call." />

  <Card title="Authentication" href="/docs/data/authentication" description="API keys and OAuth 2.1 — which surface takes which, and how revocation behaves." />

  <Card title="Rate limits" href="/docs/data/rate-limits" description="One counter shared by MCP and REST, the archive exemption, and what a 429 looks like." />

  <Card title="Errors" href="/docs/data/errors" description="Status codes, the JSON envelope, and the endpoint where an auth failure is a 200." />
</Cards>


# Rate limits (/docs/data/rate-limits)



Every MCP tool call and every REST API call spends one unit of the same hourly budget. Archive
downloads are authenticated on every request and recorded on every request, and charged on none.
There is one number, one counter, and one exclusion.

## The number [#the-number]

**20,000 requests per rolling hour.** One value applies to every credential — there are no plan
tiers, no per-endpoint ceilings and nothing to configure.

<Callout title="Older numbers you may have seen are wrong">
  This limit was raised on 2026-07-29. Documentation and product pages previously stated *100
  calls/hour* for MCP and *2,000/hour* for the REST API; both are stale by an order of
  magnitude or more.

  Separately, **archive downloads stopped spending this budget on 2026-09-02**. Any page telling you
  that a Parquet download costs you requests, or that an hour of archive downloads leaves nothing for
  your MCP client, predates that change.
</Callout>

The window slides. What counts is your usage over the *previous* hour, measured from now, so
capacity returns continuously as old requests age out — there is no fixed reset at the top of the
hour, and waiting for one will not help you. A request is counted before it is compared against the
ceiling, so 20,000 is the number of requests *admitted* per window, inclusive.

## One counter, three surfaces [#one-counter-three-surfaces]

Every authenticated request is recorded against your credential under a label you can see in your
usage view. Two of the three surfaces also spend budget:

| You call                           | Recorded as                  | Spends the hourly budget |
| ---------------------------------- | ---------------------------- | ------------------------ |
| `https://vike.io/mcp`              | `mcp`                        | yes                      |
| `https://data.vike.io/v1/...`      | `api_<namespace>_<resource>` | yes                      |
| `https://data.vike.io/archive/...` | `archive_download`           | **no**                   |

The two metered surfaces do **not** have budgets of their own — they share the single counter. An
hour of `/v1` calls leaves nothing for your MCP client: between those two, the labels separate your
usage *analytics*, not your *budget*. The archive is the one surface separated in both.

### Per key, not per account [#per-key-not-per-account]

The counter is keyed on the credential, not on its owner, so **each of your API keys gets its own
20,000**. Issuing a second key is a legitimate way to isolate a bulk job from an interactive one,
and one key tripping the limit does not affect another.

OAuth is the exception. **Every OAuth token you own shares one pooled counter**, held per user
rather than per token. Two connected Claude Desktop clients draw from the same budget; two API keys
do not.

## The archive is authenticated but not metered against your hour [#the-archive-is-authenticated-but-not-metered-against-your-hour]

Every request to `https://data.vike.io/archive/...` still validates its credential, and still
appears in the usage view on your account page. It simply never reaches the rate check. No archive
request can consume your hourly budget, and no amount of downloading can rate-limit you.

### Why a request is the wrong unit for a bulk file [#why-a-request-is-the-wrong-unit-for-a-bulk-file]

The gate in front of the archive counts **HTTP requests**. It does not see *files*, or *bytes*, or
*downloads* — and a Range request is a separate HTTP request.

A remote Parquet read fetches the footer, then each column chunk of each row group it needs, as its
own Range request. The archive actively invites this: `manifest.json` advertises
`"range_requests": true` (verified in the live manifest), and the server returns `Accept-Ranges`,
so pyarrow, DuckDB, fsspec and every other reader will use ranges by default.

<Callout title="The measurement that removed the charge">
  Measured on the live archive: **one 1.26 GB partition produced 20,237 separate requests** — more
  than the entire hourly ceiling, for a single file. Almost every rate-limit rejection recorded in
  the platform's whole history was an archive download, and every one of them was a customer using
  the format exactly as intended.

  The meter was counting the reader's access pattern rather than the download, so the archive stopped
  spending the budget. The real cost of a bulk transfer is bandwidth, which is bounded separately at
  **50 MB/s per connection**.
</Callout>

### Download whole files anyway [#download-whole-files-anyway]

<Callout type="warn" title="Remote-reading no longer burns your hour — it still costs you time">
  Pointing pandas, DuckDB or fsspec straight at an archive URL re-fetches the file's footer and
  column chunks across the network on **every** query, at a rate capped per connection. Pull the
  partition once instead.
</Callout>

One file is one request. Fetch it, then point your reader at the local copy:

```sh
curl -O -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/archive/venue=polymarket/date=2026-09-01/trades.parquet"
```

An interrupted transfer resumes with `-C -` rather than starting over:

```sh
curl -C - -O -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/archive/venue=polymarket/date=2026-09-01/book_events.parquet"
```

Row-group pushdown and column pruning still work against the local file; they just work against
your disk instead of across a 50 MB/s link.

### Download less, not more cleverly [#download-less-not-more-cleverly]

Full-day `book_events` partitions run 4–7 GiB. If you need one market family rather than the whole
Polymarket universe, the archive publishes a second, additive layout that groups the crypto up/down
families into much smaller files:

```
/archive/venue=polymarket/asset=btc/tenor=5m/date=2026-09-01/book_events.parquet
```

Same schema as the `date=` layout. `manifest.json` lists every `(asset, tenor, date)` triple with
its row count and byte size, so you can pick exactly the files you need before transferring a byte
— and the manifest itself needs no key at all, like the free samples under `/archive/samples/`.

## The counter is a backstop, not a meter [#the-counter-is-a-backstop-not-a-meter]

The limit is enforced approximately, and deliberately favours availability over exactness:

* **It is enforced per server process.** Requests from one client can be handled by different
  processes, each keeping its own view of your count, so a client whose requests spread across them
  can see an effective ceiling meaningfully above the nominal one before every process agrees it is
  over.
* **It refreshes on a short interval.** Between refreshes the count is tracked locally with no round
  trip, so a burst can briefly overshoot before the next refresh catches up.
* **A backend failure does not open the gate.** If a refresh fails or times out, the last known
  count is reused rather than the check being skipped.

Treat 20,000 as the number you must design under, not a number you can calibrate against. Do not
build a client that runs deliberately at the edge of it.

## When you are limited [#when-you-are-limited]

You get **HTTP 429** with a `Retry-After: 60` header on every metered surface. Every layer that can
return one quotes the same 60, deliberately, so two hops cannot disagree — and it is advisory: a
sliding hourly window has no single correct answer to "when will capacity exist", so 60 seconds is a
sane back-off hint rather than a promise.

The archive cannot return a rate-limit 429 at all, because an `/archive/` request is never metered.
A missing or invalid credential there is still a **401**.

Honour the header, back off, and retry. A rate-limited request is itself recorded and itself counts,
so hammering a closed door keeps the door closed. The exact body shapes, and the one surface where a
rate-limit trip and an auth failure carry different HTTP statuses, are on [Errors](/docs/data/errors).

## Watching your usage [#watching-your-usage]

Recent calls, per key, are visible under **Account → API Keys** at
[vike.io/account?tab=api-keys](https://vike.io/account?tab=api-keys). Archive downloads appear here
like everything else — they are recorded, just not charged. Each call also carries a credit value
(0–4 for an MCP tool) recorded for accounting, but **the hourly limit counts requests, not
credits** — a 0-credit call consumes a unit of the hourly budget exactly like any other.


# Glossary (/docs/trader/glossary)



Vike Trader's vocabulary is small and precise, and most of it is enforced by a test rather than
described in prose. Each entry below names the code symbol that is the authority for the word and
links to the page that explains it. A word with more than one sense gets every sense it carries.

## Arming and mounting [#arming-and-mounting]

* **ceiling** — the per-venue arming tier in `policy.toml`'s `[venues]` table, a
  `vike_config::VenueMode` ordered `paper < demo < live`, which `vike_mount::make_engine` consults
  before any credential is read. It can only refuse: `VenueMode::cap` is `min`, never `max`, so
  `bybit = "live"` declines to stop bybit going live rather than putting it there, and a box with
  no table mounts every venue paper. The word also names `vike_config::Policy` as a whole — the
  hard ceilings, the one settings type with neither an environment nor a CLI layer. →
  [Risk and arming](/docs/trader/concepts/risk-and-arming), [policy](/docs/trader/reference/settings/policy).
* **arming** — taking a venue past paper. Two gates decide it, in order: the ceiling, then the
  credential gate — present `{VENUE}_DEMO_*` keys spawn a real execution client, absent ones keep
  the venue paper; `crates/vike-bridge-core/src/lib.rs` calls its `credentials` module the
  absent-credentials-is-the-live-gate authority. → [Risk and arming](/docs/trader/concepts/risk-and-arming).
* **paper** — `VenueMode::Paper`: simulated fills against the local paper exchange, no credential
  used, no order leaving the process, the default for every venue. The exchange is
  `vike_paper::PaperExecutionClient`, which fills a resting book with the backtest engine's own
  public fill primitives, so backtest == paper is by construction. →
  [The paper exchange](/docs/trader/concepts/paper-exchange).
* **mount** — three related things. A *venue* mount is what `vike_mount::make_engine` builds: one
  type-erased `ExecutionEngine` for a venue and symbol plus an optional `ReconClient`. A *strategy*
  mount is a strategy on a (venue, symbol, interval) triple, whose identity
  `crates/vike-core/src/strategy_state.rs`'s `mount_id_of` derives deterministically
  (`binance__BTC_USDT__1m`). A *runtime* mount is one added to a running core over the wire
  (`Command::MountStrategy` carrying a `MountSpec`) and recorded so it survives a restart. →
  [Mounting](/docs/trader/concepts/mounting), [Accounts](/docs/trader/concepts/accounts),
  [Venues](/docs/trader/venues/).
* **sidecar** — a JSON file the core writes beside its state through a temp-write, fsync and
  rename: `<state_dir>/<mount_id>.json` for a strategy's durable state, `runtime_mounts.json` for
  the runtime mount topology. Both sit behind the opt-in `CoreConfig::state_dir` and read
  fail-open, so a corrupt one warns rather than refusing a boot. →
  [Mounting](/docs/trader/concepts/mounting).
* **run** — in the live core, a `RunProfile`: the single TOML artifact that names a full runtime
  assembly — event source, broker, sinks, risk and guard stack — so backtest, paper and live are
  one auditable file. In backtesting, what a finished run leaves behind: one directory under
  `<project>/user_data/runs/` holding a common manifest beside a report only that run's kind
  understands. `vike-run` is the crate that mounts a strategy on the production core and feeds it.
  → [Mounting](/docs/trader/concepts/mounting), [Run profiles](/docs/trader/backtesting/run-profiles),
  [Runs on disk](/docs/trader/backtesting/runs-on-disk).

## Inside the core [#inside-the-core]

* **fold** — applying one event to state on the single-writer thread. `ExecutionEngine::on_event`
  folds the venue stream — bare fills into the account, lifecycle events through the
  `ManagedOrder` state machine — and answers with a `Fold` verdict: `Applied` when state changed,
  `Dropped` for an unknown client-order-id, an illegal transition, a reconnect replay, an event
  for a symbol or venue this engine does not own, or a non-finite venue number, and nothing
  downstream may treat a dropped event as having happened. The fold loop is the thread the
  latency gate measures. In reconciliation the verb is the same: a policy decides fold-versus-hold
  per divergence. →
  [The execution core](/docs/trader/concepts/execution-core), [The event bus](/docs/trader/concepts/event-bus),
  [The latency gate](/docs/trader/concepts/latency-gate),
  [Policies](/docs/trader/concepts/reconciliation/policies).
* **lane** — one of the ingest channels into the core, each with its own loss discipline: exec
  events are lossless and back-pressure the venue task, commands `try_send` so the GUI never
  blocks, market data rides a latest-wins conflation slot plus one marker; the bar lanes
  (`BarSeed`/`BarClose`) and the tick lanes (quote, trade, book) are lossless too. The producer
  types live in `crates/vike-exec/src/lanes.rs`, one crate below the core that drains them. Two
  narrower uses: the emulator's `PriceLane` (`Last` or `Mark`) names which price series checks a
  conditional, and the backtester's queue lane is the opt-in queue-position fill path. →
  [Ingest lanes](/docs/trader/concepts/ingest-lanes), [The execution core](/docs/trader/concepts/execution-core),
  [Emulated orders](/docs/trader/concepts/emulated-orders), [The queue lane](/docs/trader/backtesting/queue-lane).
* **snapshot** — `CoreSnapshot`, the immutable state view the core publishes to the GUI through an
  arc-swap cell. The GUI is a lossy downstream observer that reads the latest on repaint and can
  never back-pressure the core; the build is coalesced, never per-event. →
  [Portfolio and snapshot](/docs/trader/concepts/portfolio-and-snapshot).
* **halt** — `TradingState::Halted`, under which the `RiskGate` admits only a position-covered
  reduce (`vike_model::is_covered_reduce`) and denies every opening order; also the halt sentinel
  file every `ExecutionClient` consults, with `crates/vike-exec/src/halt.rs` the one predicate for
  what an engaged halt lets out. **Safe-state** is the halt the core enters by itself when a
  handler panics: halted, a best-effort cancel of every non-terminal working order, the fault
  surfaced in the snapshot, the engine never traded on again until restart. →
  [Halt](/docs/trader/concepts/halt), [The execution core](/docs/trader/concepts/execution-core),
  [The dead-man's switches](/docs/trader/concepts/dead-mans-switch).
* **dead-man's switch** — two of them, with opposite defaults because they read opposite evidence.
  The *connection* one (`vike_core::LinkDeadManConfig`, `policy.toml`'s `link_deadman_grace_ms`,
  armed when the key is absent, `0` the only off) trips on a link a venue's own bridge has reported
  `Disconnected` past the grace and cancels that venue's resting orders; a market that merely closed
  is disclosed `FeedStatus::Stale`, which never counts, so a close cannot reach it. The *silence*
  one (`vike_core::DeadManConfig`, `deadman_timeout_ms`, off unless the key is written) trips on
  ingest that has gone quiet on every venue at once and cancels everything — which is exactly why it
  may not be armed by default, a closed market being silence too. They share `deadman_action`, and
  under its default a trip also engages the halt. →
  [The dead-man's switches](/docs/trader/concepts/dead-mans-switch).
* **journal** — the write-ahead command journal: pre-allocated mmap segments whose frames are
  `[len][check][payload]`; a record failing its check is a torn tail at which reading stops. →
  [The command journal](/docs/trader/concepts/journal/).
* **emulated order** — a conditional order, a fixed or trailing stop, held in the core's own
  `ConditionalBook` for a venue or strategy without native support. Arming bypasses the risk gate;
  the fire goes through the one live path as a plain market order, triggered by
  `vike_model::order_fill_price`, the same oracle the backtest fires on. `Emulated` and `Released`
  are the state machine's client-side conditional states. →
  [Emulated orders](/docs/trader/concepts/emulated-orders).

## Orders and reconciliation [#orders-and-reconciliation]

* **terminal** — one of the five order states after which no further lifecycle event applies:
  `Filled`, `Canceled`, `Rejected` (the venue's refusal), `Denied` (the risk gate's veto,
  pre-venue) and `Expired`. `OrderStatus::is_terminal` names exactly those, and `Liquidated` is
  deliberately not among them. Every order must reach exactly one terminal, and a dead venue path
  must synthesize a terminal `OrderRejected` rather than let an order vanish. →
  [Order lifecycle](/docs/trader/concepts/order-lifecycle), [Events](/docs/trader/concepts/events/).
* **kind** — the member name of a declared roster the runtime consults. A store kind is one
  `kind=` row of `vike_data::store_kind::STORE_KINDS`, the on-disk layout authority; an order kind
  is one of `vike_model::venue_caps::ORDER_KINDS` (`market`, `limit`, `stop`, `stop_limit`,
  `take_profit`, the last three the trigger kinds); a divergence kind is a `DivergenceKind`
  variant; a run kind is the one top-level manifest field a listing may branch on. →
  [Data](/docs/trader/concepts/data/), [Orders](/docs/trader/concepts/orders/),
  [Reconciliation](/docs/trader/concepts/reconciliation/), [Runs on disk](/docs/trader/backtesting/runs-on-disk).
* **divergence** — one detected local-versus-venue disagreement, carrying the venue evidence
  needed to resolve it. `vike_exec::recon::diff` turns venue reports plus a `LocalView` into
  divergences; `resolve` turns those plus a `ReconPolicy` into a `Recon` — events to fold, a
  snapshot seed and alerts — and both are pure, with no I/O. →
  [Reconciliation](/docs/trader/concepts/reconciliation/).
* **held** — a divergence a policy did not fold, kept as an operator alert awaiting confirm. A held
  divergence is a state, not an event: under `quarantine` one that nothing heals is re-diffed and
  re-held every pass, so the warning fires when it enters or leaves the held set and a re-raise
  refreshes its row rather than appending. → [Policies](/docs/trader/concepts/reconciliation/policies).
* **wiring class** — how a venue's exec and reconcile sides are wired into a default live mount,
  the one docs-facing axis no capability table encodes because it is a property of `make_engine`'s
  arms rather than of any adapter. Four classes: `live-exec-recon`, `feature-gated` (the arm
  compiles only under a `vike-mount` feature), `sidecar-exec-no-recon` (exec over an owned child
  process, no reconcile) and `paper-only`. `crates/vike-ops/src/docs_data.rs`'s `WIRING` declares
  one named row per roster venue, gated for completeness, and ships in `venues.json`. →
  [Venues](/docs/trader/venues/), [Reconciliation](/docs/trader/concepts/reconciliation/).

## Data, venues and rules [#data-venues-and-rules]

* **seam** — a trait boundary two sides agree on without seeing each other.
  `vike_exec::ExecutionClient` is the one trait every venue bridge implements; `HistStore` is the
  unified historical-data seam, one store for bars and ticks; `DataClient` is its live mirror. →
  [The ExecutionClient seam](/docs/trader/concepts/execution-client-seam),
  [The history store](/docs/trader/concepts/hist-store), [The live data seam](/docs/trader/concepts/live-data-seam).
* **bridge** — a venue adapter: one crate per venue under `crates/bridges/<venue>`, built from
  `vike-bridge-core`'s shared plumbing — blocking REST transport and signers, the venue-neutral WS
  user-data pump, the `ExecActor` command thread, credentials, the pinned Decimal wire-format
  site. → [Venues](/docs/trader/venues/).
* **roster** — `vike_model::VENUES`, the one canonical venue list: every per-venue capability
  table's completeness test iterates it, so adding a venue fails every table's tests until its rows
  exist, and a roster venue's row is always named even when its value equals the fallback. →
  [Venues](/docs/trader/venues/), [Adding a venue](/docs/trader/developer/adding-a-venue).
* **project** — `<project>`, the one folder holding settings and credentials
  (`<project>/settings/`), program-written state (`<project>/settings/state`), runs and data.
  `$VIKE_SETTINGS_DIR` names the `settings/` directory outright — `<project>` is derived from it —
  and wins over the walk up from the working directory; a blank value is ignored. The history
  store's own root follows one shared precedence — `vike_model::store_path::resolve_store_root` —
  in which anything stated outranks anything inferred. → [Settings](/docs/trader/concepts/settings),
  [The history store](/docs/trader/concepts/hist-store).
* **parity fixture** — the frozen golden files under `fixtures/r0/` through `fixtures/r6/`
  (there is no `r2/`), exported from the retired Python platform; every exporter was deleted, so
  the committed bytes are the oracle, and what the parity suites prove is that this code has not
  changed its arithmetic unnoticed. →
  [The parity gate](/docs/trader/concepts/parity-gate).
* **gate** — a CI test that holds a rule the way a paragraph cannot.
  `crates/vike-ops/tests/layer_gate.rs` turns "dependency direction: down only" into a merge gate
  over every manifest's declared `layer`, and most rules the concepts pages state are held the same
  way. → [Architecture](/docs/trader/concepts/architecture), [Developer guide](/docs/trader/developer/).


# Vike Trader (/docs/trader)



Vike Trader is a trading platform written in Rust. One workspace builds three things — a desktop
charting application, a headless live-trading daemon, and a command-line tool that doubles as a
server for AI agents — and all three sit on the same execution core, the same backtester and the
same 14 venue bridges.

Free. Source-available under FSL-1.1; every release becomes Apache-2.0 two years on.

<Callout type="warn" title="Every venue starts on paper">
  Absent credentials are the live gate, and a per-venue ceiling in `policy.toml` is consulted before
  them. A box with no credential store and no `[venues]` table mounts everything paper, whatever else
  is configured. Arming is something you do deliberately, per venue — see
  [risk and arming](/docs/trader/concepts/risk-and-arming).
</Callout>

## Start here [#start-here]

<Cards>
  <Card title="What is Vike Trader?" href="/docs/trader/getting-started/what-is-vike-trader" description="The two-minute tour: the three surfaces, the venues, the backtester and the licence." />

  <Card title="Install" href="/docs/trader/getting-started/install-docker" description="Docker, Windows or Linux. One project folder, paper by default." />

  <Card title="First backtest" href="/docs/trader/getting-started/quickstart-backtest" description="No credentials: scaffold the examples, seed a tape, run a backtest and read the report." />

  <Card title="First tutorial" href="/docs/trader/tutorials/rsi-mean-reversion-backtest" description="A shipped strategy over real hourly bars, end to end, with every number from a real run." />
</Cards>

## Learn the platform [#learn-the-platform]

The concepts tree is the reference for how the thing works — the execution core and the seam every
venue implements, the write-ahead journal a session replays from, the ingest lanes, the risk gate
and the halt boundary. It is where a claim about behaviour is settled.

<Cards>
  <Card title="Concepts" href="/docs/trader/concepts" description="The execution core, the venue seam, the journal, the data model, the gates. One page per event, store kind, order kind, asset class and reconciliation divergence." />

  <Card title="Backtesting" href="/docs/trader/backtesting" description="Run profiles, the portfolio and vector engines, fill and queue models, costs, latency, sweeps and walk-forward." />

  <Card title="Analytics" href="/docs/trader/analytics" description="The report and its metrics, benchmarks, excursions, Monte Carlo and the anti-overfitting statistics." />

  <Card title="Order flow" href="/docs/trader/orderflow" description="Trade classification, imbalance and runs bars, CVD, footprint, volume profile, VPIN." />

  <Card title="Research" href="/docs/trader/research" description="Studies, the run pipeline, model fitting and inference, the fit cache and the model pins." />

  <Card title="Market making" href="/docs/trader/market-making" description="Avellaneda–Stoikov, intensity fits, quote emission and ladders, inventory skew, and the cross-exchange maker." />
</Cards>

## Build something [#build-something]

<Cards>
  <Card title="Strategies" href="/docs/trader/strategies" description="The strategy trait, the portable registry, the controller seam, and a page per shipped template with its parameters and live verdict." />

  <Card title="Scripting" href="/docs/trader/scripting" description="Rhai strategies and indicators: the engine, the order vocabulary, loading your own, and the limits." />

  <Card title="Indicators" href="/docs/trader/indicators" description="The 171 built-in indicators and 8 pair indicators, by category, each with its parameters — and the guarantee that streaming equals batch, bit for bit." />

  <Card title="Tutorials" href="/docs/trader/tutorials" description="Worked runs, end to end. Every number on these pages was pasted from a real one." />
</Cards>

## Run it [#run-it]

<Cards>
  <Card title="Desktop app" href="/docs/trader/gui" description="Charts, the DOM ladder, the cockpit, the trade panel, the Studio IDE and the Data Manager." />

  <Card title="Command line" href="/docs/trader/cli" description="vike-cli end to end: a session from init to a report, the trade REPL, how it relates to the daemon and the app, and the MCP door." />

  <Card title="Venues" href="/docs/trader/venues" description="All 14 bridges: capabilities, order kinds, time in force, margin, fees, amend semantics and how each is wired." />

  <Card title="Data providers" href="/docs/trader/data-providers" description="Where backfilled history comes from — venue-direct collectors, vendors, the archive, and store maintenance." />

  <Card title="Guides" href="/docs/trader/guides" description="Task-shaped: arm a venue, record a feed, replay a session, read a report, triage a stuck order." />

  <Card title="Troubleshooting" href="/docs/trader/troubleshooting" description="Symptom, cause, fix — sectioned by component, with the symptom quoted as you will meet it." />

  <Card title="Glossary" href="/docs/trader/glossary" description="The vocabulary the concepts pages use: ceiling, mount, lane, fold, divergence, terminal, wiring class." />
</Cards>

## Look something up [#look-something-up]

<Cards>
  <Card title="Reference" href="/docs/trader/reference" description="Every command-line verb, every binary in the workspace, every settings file and every environment variable." />

  <Card title="Developer" href="/docs/trader/developer" description="How the workspace is gated: the CI derivation, the structure and safety gates, the supply chain, and the test tiers." />

  <Card title="Build with AI" href="/docs/ai/trader" description="The agent surface — the tools an agent can call, per-client setup, and a real annotated session." />
</Cards>

## What makes it one platform [#what-makes-it-one-platform]

**One execution core, three front ends.** The desktop application, the daemon and the command-line
tool are thin composition roots over the same crates. One broker-generic registry serves the
backtest simulator and the live daemon alike — but not everything that backtests can mount live:
the registry carries a per-name live verdict, and the daemon refuses a simulator-only name, or one
whose verdict says it would resolve and then never trade, when it loads the profile. The
[execution client seam](/docs/trader/concepts/execution-client-seam) is the single contract every venue
bridge implements.

**Research and paper trading cannot disagree about a fill.** The backtester's simulated fills and
the live paper exchange are built from one shared crate, so a result you get in research is
computed the same way the paper book computes it.

**The capability tables are the documentation.** Every venue page, indicator page, strategy
template and reconciliation page on this site is rendered from the same tables the runtime consults,
exported at each release. A page here cannot describe a capability the product does not have,
because the gate in the product tree fails first.

**Absent credentials are the live gate.** Nothing trades because it was configured to; it trades
because somebody armed that venue, in a file, on purpose.


# Alerts (/docs/ai/data/alerts)



Six tools for on-chain **transfer alerts**: rules that fire when a transfer of a given token
crosses a USD threshold. Unlike every other family here, these tools *write* to your account —
they are the only ones that change state.

Three things constrain what an alert can express today, all of them stated by the tools
themselves:

* **Chains `eth` and `bsc` only.** One chain per alert: passing two silently watches only the
  first, with no error to tell you the second was dropped. Watching both means creating two
  alerts.
* **USD thresholds only.** There is no token-quantity condition — a rule triggers on transfer
  *value*, not on size in tokens.
* **One alert type.** `transfer` is the only kind the service accepts.

Alerts belong to the authenticated user, and every tool enforces ownership: you can only list,
edit or delete your own. Both credentials resolve to a user, so an API key and an OAuth token
reach the same alerts.

## `alerts_list` [#alerts_list]

**Free — 0 credits.** Lists your alert rules. Active only by default.

| Parameter          | Type    | Default | Notes                                  |
| ------------------ | ------- | ------- | -------------------------------------- |
| `include_inactive` | boolean | `false` | Include paused and soft-deleted alerts |

**Returns** `{"alerts": [...]}`, one row each with `id`, `label`, `alert_type`, `chain`,
`token_symbol`, `min_value_usd`, `max_value_usd`, `cooldown_minutes`, `max_triggers_day`,
`notify_channel_ids`, `is_active` and `created_at`.

This is also how you get an `alert_id` — `alerts_edit` and `alerts_delete` both need one, and
neither accepts a label.

> List my alerts, including the paused ones.

## `alerts_list_channels` [#alerts_list_channels]

**Free — 0 credits.** Your enabled notification channels. No parameters.

**Returns** `{"channels": [...]}` with `{id, channel_type, is_verified, label}` per row.

Call it before creating an alert. An alert created against a channel you have not set up is
still created — it simply never notifies anyone, which is the failure mode worth avoiding.

> What notification channels do I have set up?

## `alerts_create` [#alerts_create]

**3 credits.** Creates a transfer alert.

| Parameter          | Type    | Default    | Notes                                       |
| ------------------ | ------- | ---------- | ------------------------------------------- |
| `label`            | string  | *required* | The alert's user-visible name               |
| `token_symbol`     | string  | —          | Ticker in UPPERCASE (`USDC`, `ETH`, `PEPE`) |
| `chain`            | enum    | `eth`      | `eth` or `bsc`, single value                |
| `min_value_usd`    | number  | —          | Fire when transfer USD value ≥ this         |
| `max_value_usd`    | number  | —          | Fire when transfer USD value ≤ this         |
| `channels`         | array   | —          | `["email"]`, `["discord"]`, or both         |
| `cooldown_minutes` | integer | `60`       | Minimum gap between triggers, floor of 1    |

**Returns** `{"alert": {...}}` — the new row in the shape `alerts_list` uses, including its
`id`.

Set both thresholds to bracket a band (transfers between $1M and $5M); set one for an open
range. `cooldown_minutes` is what keeps a busy token from filling your inbox, and it is
enforced per rule.

> Alert me on email when more than $5M of USDC moves on Ethereum, at most once an hour.

## `alerts_edit` [#alerts_edit]

**2 credits.** A partial update: only the fields you pass change.

| Parameter                                                                                          | Type    | Notes                                        |
| -------------------------------------------------------------------------------------------------- | ------- | -------------------------------------------- |
| `alert_id`                                                                                         | integer | *Required.* From `alerts_list`.              |
| `label`, `token_symbol`, `chain`, `min_value_usd`, `max_value_usd`, `channels`, `cooldown_minutes` | —       | Same meaning as in `alerts_create`           |
| `is_active`                                                                                        | boolean | `false` pauses the alert without deleting it |

The exported schema carries no per-field descriptions for this tool — the fields mirror
`alerts_create` above, which is where their meaning is stated.

> Pause my USDC alert.

> Raise the threshold on alert 41 to $10M.

## `alerts_delete` [#alerts_delete]

**2 credits.** Removes an alert.

| Parameter  | Type    | Default    | Notes                                                            |
| ---------- | ------- | ---------- | ---------------------------------------------------------------- |
| `alert_id` | integer | *required* | The alert to delete                                              |
| `hard`     | boolean | `false`    | `true` removes permanently; the default pauses and keeps history |

**Returns** `{"ok": true}` on success. A soft delete is the same state as `is_active: false`,
so an alert deleted this way still appears under `alerts_list` with `include_inactive: true`
and can be re-enabled with `alerts_edit`.

> Delete alert 41 — actually, just pause it.

## `alerts_register_webhook` [#alerts_register_webhook]

**2 credits.** Registers an HTTPS webhook as a delivery channel. Vike POSTs signed JSON to the
URL when your alerts fire.

| Parameter | Type   | Default    | Notes                                                      |
| --------- | ------ | ---------- | ---------------------------------------------------------- |
| `url`     | string | *required* | Webhook URL (http or https), reachable from Vike's servers |
| `secret`  | string | —          | HMAC secret, 16 characters or more. Recommended.           |

### Verifying a delivery [#verifying-a-delivery]

The signing is Stripe-style. Each POST carries:

```
Content-Type: application/json
User-Agent: vike-alerts/1.0
X-Vike-Timestamp: <unix epoch seconds>
X-Vike-Signature: t=<ts>,sig=<hex hmac>
```

Compute `HMAC-SHA256(secret, "<X-Vike-Timestamp>.<raw body>")`, hex-encode it, and compare it
in constant time against the `sig=` value. Reject the delivery if the timestamp is more than
about five minutes old — that is what stops a captured request being replayed.

Without a `secret` the POST still goes out, unsigned. That is fine for a private endpoint and
not fine for anything reachable from the internet, since nothing then distinguishes Vike's POST
from anyone else's.

> Send my alerts to [https://example.com/hooks/vike](https://example.com/hooks/vike) as well, with a signing secret.

## When alerts are evaluated [#when-alerts-are-evaluated]

Alerts are not evaluated inline with the chain. A scheduled checker sweeps recent transfers and
fires matching rules; its lookback window is deliberately twice its run interval, so one missed
run still gets caught rather than dropping the transfers it would have seen. Expect alerting
latency in minutes, and treat these as monitoring rather than as a trading trigger.


# Candles (/docs/ai/data/candles)



Two candle tools, one per venue — deliberately not one tool with a `venue` argument. Vike serves
market data only from venues whose data is on chain, which today means Hyperliquid and Polymarket,
and the two are answered by two different engines. Two tools keep that boundary in the wiring:
crossing it would mean adding a call, not passing a different argument.

<Callout type="warn" title="There is no per-token or exchange-ticker candle tool">
  Neither tool below takes a contract address, so there are no candles for Ethereum, BSC or Base
  tokens, and none for centralised-exchange tickers such as BTCUSDT: vike holds no right to
  redistribute centralised-exchange market data. Asked to chart a token, say plainly that it is not
  available — never substitute transfer flows, holder counts or any other series for a price series.
</Callout>

## `hl_ohlcv` [#hl_ohlcv]

**1 credit.** Historical OHLCV candles for a Hyperliquid market, aggregated from HL's own executed
fills.

| Parameter  | Type    | Default                | Notes                                                                         |
| ---------- | ------- | ---------------------- | ----------------------------------------------------------------------------- |
| `symbol`   | string  | *required*             | HL asset: perp ticker (`BTC`), spot token (`HYPE`) or raw spot index (`@107`) |
| `interval` | enum    | `1h`                   | `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `1d`                                    |
| `market`   | enum    | `perp`                 | `perp` or `spot` — perpetual or HL spot                                       |
| `dex`      | string  | `HL`                   | Perp DEX. `HL` is the core venue; the others are builder-deployed HIP-3 DEXs  |
| `start`    | string  | `end - limit*interval` | ISO-8601 UTC or epoch ms, inclusive                                           |
| `end`      | string  | now                    | ISO-8601 UTC or epoch ms, exclusive                                           |
| `limit`    | integer | `500`                  | Max candles, hard max 5000                                                    |

Buckets are left-aligned UTC and the window is half-open — `[start, end)` — so a bar stamped at the
`end` boundary is not returned. Because `start` defaults to `end - limit*interval`, raising `limit`
on its own reaches further back rather than returning more of the same window.

**Returns** per candle: `ts` (epoch ms, UTC), `open`, `high`, `low`, `close`, `volume`,
`volume_usd` and `n_trades`, ascending by `ts` — plus `source`, naming the rollup that answered.

> Hourly BTC perp candles on Hyperliquid for the last week.

> Daily candles for HYPE on Hyperliquid spot.

## `polymarket_ohlcv` [#polymarket_ohlcv]

**1 credit.** Historical OHLCV bars for **one** Polymarket outcome token, from the recorded L2
tape.

| Parameter  | Type    | Default    | Notes                                                                  |
| ---------- | ------- | ---------- | ---------------------------------------------------------------------- |
| `token_id` | string  | *required* | ERC-1155 outcome token id                                              |
| `interval` | enum    | *required* | `1m`, `5m`, `1h`, `1d` — no default, unlike `hl_ohlcv`                 |
| `from`     | integer | —          | Epoch **milliseconds**, inclusive lower bound. Omit for no lower bound |
| `to`       | integer | —          | Epoch **milliseconds**, inclusive upper bound. Omit for no upper bound |
| `limit`    | integer | `500`      | Max candles, hard max 1000                                             |

`token_id` is the outcome token, not the market: a `condition_id` will **not** work here. Read the
token ids off `clob_token_ids` from [`polymarket_market_detail`](/docs/ai/data/polymarket), and note
that a Yes/No pair is two ids and therefore two calls. Prices are probabilities in `[0, 1]`, not
dollars.

Two window details differ from `hl_ohlcv` and both bite. The bounds are epoch **milliseconds**
only, and `to` is **inclusive** where `hl_ohlcv`'s `end` is exclusive. And there is no cursor, so a
window wider than `limit` is truncated at the **old** end — to reach the recent end of a long
range, raise `from` rather than paging.

**Returns** bars **oldest first**: `ts` (epoch ms, UTC), `open`, `high`, `low`, `close`, `volume`
and `trades`.

> Chart the Yes side of this Polymarket market over the last month.

> Hourly bars for this outcome token since the start of the week.


# Data MCP server (/docs/ai/data)



`https://vike.io/mcp` is the Vike Data API's [Model Context Protocol](https://modelcontextprotocol.io/)
endpoint: one URL, 31 tools, JSON-RPC 2.0 over HTTP POST. Point an MCP client at it and an agent
can screen tokens, trace a wallet's counterparties, decode its DeFi positions, profile a
Polymarket trader and manage on-chain transfer alerts — conversationally, without you writing a
request.

It is a **remote** server. Vike runs it; your client holds a URL and a credential and nothing
else. There is no binary to install, nothing to keep running on your machine, and no local port.

## Who this is for [#who-this-is-for]

Anyone who would otherwise be writing `curl` against [the REST API](/docs/data/getting-started) inside
a loop of "fetch, look, decide what to fetch next". The tools cover the same data the REST plane
does, but shaped so an agent can chain them: `wallet_summary` hands you an address worth
following, `wallet_counterparties` says who it trades with, `wallet_trace` walks the graph, and
none of that needs you to know an endpoint path.

If you want the data in a program rather than in a conversation, the REST API and the bulk Parquet
archive are the other two planes — [Vike Data API](/docs/data) is the map.

## Connect [#connect]

| Property        | Value                                                                 |
| --------------- | --------------------------------------------------------------------- |
| Endpoint        | `https://vike.io/mcp`                                                 |
| Transport       | Streamable HTTP, `POST` only                                          |
| Protocol        | JSON-RPC 2.0                                                          |
| MCP version     | `2025-03-26`                                                          |
| Server identity | `serverInfo` = `vike-mcp`, version `1.0.0`                            |
| Methods         | `initialize`, `notifications/initialized`, `tools/list`, `tools/call` |

`tools/list` returns the whole catalogue in one response — there is no pagination and no cursor.
Any other method is a `-32601`.

**[Client setup](/docs/ai/data/setup)** has the exact configuration per client — Claude Desktop, Claude
Code, Cursor, Gemini CLI, VS Code — plus [the raw wire protocol](/docs/ai/data/setup/raw-http) for a
script or for debugging a client that will not connect.

## Authentication [#authentication]

Two credentials are accepted, and they are tried in this order:

1. `Authorization: Bearer vk_oat_...` — an OAuth 2.1 access token. Clients that support Dynamic
   Client Registration ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) register
   themselves and you approve access in a browser; no key is ever copied. This is the
   [Claude Desktop](/docs/ai/data/setup/claude-desktop) path.
2. `X-API-KEY: vk_...` — a long-lived key you create under **Account → API Keys**. Every other
   client uses this: Claude Code, Cursor, Gemini CLI, VS Code, curl.

Both resolve to the same user and reach the same 31 tools, so the account-scoped ones (the whole
`alerts_*` family) work identically either way. The difference that shows up later is how the
hourly counter is keyed — see [Rate limits](/docs/data/rate-limits).
[Authentication](/docs/data/authentication) covers both credential types in full.

⚠ A validated credential is cached for **45 seconds**, so a key or token you revoke can keep
authenticating for that window. Revocation is not instant; it is a deliberate trade of a few
seconds of staleness for not re-validating the credential from scratch on every request. Plan a
rotation as *create the new credential, move traffic, then delete the old one* — not the reverse.

## The 31 tools [#the-31-tools]

Six families. Each family page gives every tool its parameters, what it returns, and an example
prompt — shown as a quote — that gets an agent to reach for it. Those pages are generated from the
same tool registry `tools/list` serves, so a live `tools/list` is the tie-breaker if one ever
disagrees.

<Cards>
  <Card title="Wallets — 11 tools" href="/docs/ai/data/wallets" description="Summary, discovery, raw transfers, balances, PnL history, counterparties, tracing, comparison, ENS, bulk labels, label provenance." />

  <Card title="Tokens — 4 tools" href="/docs/ai/data/tokens" description="Search, activity screener, top holders, buyers and sellers." />

  <Card title="Polymarket — 4 tools" href="/docs/ai/data/polymarket" description="Trending markets, per-market deep dive, smart-money flows and mispricings, trader profiles." />

  <Card title="Alerts — 6 tools" href="/docs/ai/data/alerts" description="Create, list, edit and delete on-chain transfer alerts, list channels, register a signed webhook." />
</Cards>

**`alerts_*` is the only family that writes anything**, and what it writes is your own alert rows
and notification channels. Nothing here touches a market, an order, or a wallet you control — the
server holds no keys and signs no transactions.

## Credits [#credits]

Every call is metered. Each tool has a fixed cost — 0 to 4, and any tool without an explicit cost
counts as 1 — recorded as `credits_used` on the usage row along with the tool name, duration,
status and arguments. Your own calls are visible under **Account → MCP Calls**.

Credits are an accounting figure, not a gate: nothing in the request path compares them against a
balance. What can refuse a call is the hourly limit below, and that counts *calls*, not credits.

| Family                            | Tools | Credits per call |
| --------------------------------- | :---: | ---------------- |
| [Wallets](/docs/ai/data/wallets)       |   11  | 1–4              |
| [Tokens](/docs/ai/data/tokens)         |   4   | 0–3              |
| [Polymarket](/docs/ai/data/polymarket) |   4   | 1–2              |
| [Candles](/docs/ai/data/candles)       |   2   | 1                |
| [Perps](/docs/ai/data/perps)           |   4   | 1–2              |
| [Alerts](/docs/ai/data/alerts)         |   6   | 0–3              |

`token_search` is the one 0-credit tool worth knowing by name: it makes a free connection test.

## Rate limits [#rate-limits]

**One hourly counter covers MCP and the REST API; the archive is authenticated against the same
credential but does not spend it.** Every `/mcp` tool call and every `/v1` request is checked
against the same counter, so a `/v1` backfill and an agent's tool calls draw down one shared
budget. One ceiling applies to every credential — there are no plan tiers and no per-endpoint
allowances. [Rate limits](/docs/data/rate-limits) states the number and is the authority for it — this
page does not restate it, because both figures the previous docs printed were wrong.

What the counter is keyed on depends on the credential:

* **API key** — per key. Rows are counted by `api_key_id`, so five keys on one account get five
  independent budgets.
* **OAuth token** — pooled per user. OAuth rows carry `api_key_id = 0` and are counted by
  `user_id`, so every OAuth-connected app on an account shares one budget.

The count is a backstop rather than a ledger: it is reseeded from the usage log at most once every
30 seconds and incremented in memory between refreshes, so at the boundary it can drift by up to
that window's worth of calls in either direction.

<Callout type="warn" title="The archive does not spend your hourly budget — but still download whole files">
  Requests under `/archive/` are exempt from the hourly counter. They are still authenticated with
  the same credential and still appear in your usage log, so nothing is lost from the record — the
  exemption is only to the budget, and it holds across the counter's periodic refresh, so an archive
  download never reappears as consumption a few seconds later. Changed 2026-09-02.

  Download whole files anyway; the reason is bandwidth now, not quota. A Parquet reader pointed at an
  archive URL fetches the footer and then each column chunk as its own Range request, and throughput
  is capped per connection (roughly 50 MB/s). `curl -O` moves the same bytes in one sequential pull
  instead of thousands of ranged round trips against that cap, and `curl -C -` resumes an interrupted
  one.

  The measurement that caused the change, which no longer describes current behaviour: one 1.26 GB
  partition produced **20,237 metered requests**, more than an entire hour's ceiling for a single
  file, and **572 of the 573** rate-limit rejections in the platform's history were archive
  downloads. Anything still describing a ranged archive read as spending your allowance describes the
  behaviour before 2026-09-02.
</Callout>

## Two error shapes [#two-error-shapes]

They are different things and they arrive differently, which matters when you are writing the
client rather than talking to it.

**Protocol and credential failures are JSON-RPC error objects.** `-32700` for a body that was not
JSON, `-32601` for an unknown method or an unknown tool name in `tools/call`, `-32000` for an
invalid or missing credential and for an hourly-limit trip. A credential failure also carries
HTTP **401** and a `WWW-Authenticate: Bearer resource_metadata=...` header (where an OAuth client
starts discovery); a rate-limit trip carries HTTP **429**, a `Retry-After` header, and `error.data` holding
`{"code": "RATE_LIMITED", "retry_after": <seconds>}`.

**A tool failure is not a protocol error.** If a tool raises, the server returns
`{"error": "<message>"}` wrapped as an ordinary *successful* result carrying `isError: true`. The
agent reads the message and retries or asks you; the session is not broken.
Every tool returns its payload the same way regardless: JSON, serialized into a single `text`
content block.

The exact bodies are on [Raw HTTP](/docs/ai/data/setup/raw-http); [Errors](/docs/data/errors) is the
cross-plane reference, including why MCP answers an auth failure with a 200 when the REST plane
answers with a 401.


# Perps (/docs/ai/data/perps)



Four tools over perpetual futures, split by what they can see. `perp_funding` and `perp_spreads`
compare **venues** — a funding rate or a price, per exchange, across every perp venue Vike
ingests. `hl_perp_top_traders` and `hl_position_match` are Hyperliquid-only and work at the level
of a **wallet**.

That asymmetry is the interesting thing about this family, and it is not a gap in the catalogue.
Hyperliquid settles on chain, so every position and fill is public and attributable to an
address — which is why the last two tools can answer *who*: rank traders by realized PnL, or
name the wallet behind a share card. No centralised exchange publishes per-account order flow,
so the two cross-venue tools answer only *where*, and there is no CEX counterpart to
`hl_perp_top_traders` to be built.

<Callout type="info" title="Neither cross-venue tool takes a venue parameter">
  `perp_funding` and `perp_spreads` accept `symbol` and nothing else — you cannot restrict the
  comparison to a venue, and the schema enumerates none. The exchange arrives in the **response**
  instead (`long_exchange` / `short_exchange`, `buy_exchange` / `sell_exchange`). Nor is the
  comparison CEX-only: Hyperliquid is one of the venues ranked, its hourly funding normalised to
  daily alongside the eight-hourly CEX rates.
</Callout>

## `perp_funding` [#perp_funding]

**1 credit.** Perpetual funding rates, in two modes selected by whether you pass `symbol`.

| Parameter | Type   | Default | Notes                                                               |
| --------- | ------ | ------- | ------------------------------------------------------------------- |
| `symbol`  | string | —       | One symbol, e.g. `BTC`. Omit for the cross-venue arbitrage ranking. |

* **With `symbol`** — current funding for that asset on every venue that lists it: the raw
  per-interval rate, the funding interval in hours, the next funding timestamp, and 24h perp
  notional per venue.
* **Without `symbol`** — pre-ranked cross-venue funding-arbitrage rows, normalised to **daily
  percent** and filtered to spreads of at least &#x2A;*0.3%**. Each row names both legs:
  `long_exchange` + `long_daily_pct`, `short_exchange` + `short_daily_pct`, and
  `spread_daily_pct`.

The normalisation is the point of the second mode. A single-symbol row gives you the rate **per
funding interval, not annualised**, and the interval is not the same on every venue — so
comparing two raw rates directly is a units error. The arb mode does that conversion for you.

Arb mode returns the **top 5** rows and the count is fixed in the handler — there is no `limit`
parameter to raise, and no way to page past the fifth opportunity.

> What is BTC funding right now across venues?

> Where is the best funding arbitrage today?

## `perp_spreads` [#perp_spreads]

**1 credit.** Cross-venue price gaps on perpetual futures — symbols where the cheapest and the
most expensive venue differ by at least &#x2A;*0.5%**.

| Parameter | Type   | Default | Notes                                        |
| --------- | ------ | ------- | -------------------------------------------- |
| `symbol`  | string | —       | Symbol to compare. Omit for the full matrix. |

**Returns** per row: `buy_exchange` + `buy_price`, `sell_exchange` + `sell_price`, and
`spread_pct`. The rows are pre-ranked, so cite them directly rather than re-sorting. Outliers
more than 400 bps from the cross-venue median are already filtered out — those are typically
unit-mismatch listings such as `1000SHIB`, where two venues quote different contract sizes and
the "spread" is an artefact.

One trap worth knowing: &#x2A;*`symbol` filters the ranking, it does not query the symbol.** The
handler computes the top spreads first and then keeps the rows matching `symbol`, so a symbol
that is not already among the widest gaps comes back **empty** — which means "not one of the
biggest spreads right now", never "this symbol has no spread".

> Where are the biggest perp price gaps right now?

## `hl_perp_top_traders` [#hl_perp_top_traders]

**2 credits.** Rank Hyperliquid perp wallets within a time window, by one of six metrics, with
three floors on top. Backed by the same pipeline as vike.io/perps/wallets.

| Parameter      | Type    | Default | Notes                                                         |
| -------------- | ------- | ------- | ------------------------------------------------------------- |
| `window`       | enum    | `30d`   | `1d`, `7d`, `30d`, `all`                                      |
| `sort`         | enum    | `pnl`   | `pnl`, `roi`, `win_rate`, `volume`, `trade_count`, `drawdown` |
| `order`        | enum    | `desc`  | `asc` or `desc`                                               |
| `min_trades`   | integer | `3`     | Minimum trade count                                           |
| `min_win_rate` | number  | `0`     | Minimum win rate as percent 0–100; `0` means no filter        |
| `min_volume`   | number  | `0`     | Minimum volume USD; `0` means no filter                       |
| `size`         | integer | `10`    | Results per page, max 20                                      |

**Returns** per trader: address, total realized PnL, ROI percent, win rate percent — overall
plus long-side and short-side separately — win, loss and trade counts, total volume, the PnL
split between longs and shorts, max drawdown percent, account value and average leverage,
alongside a `total` count for the filtered population.

Three things about the filters. Win rate is a **percent, not a fraction**: a wallet winning
three trades in four is `75`, so `min_win_rate: 0.75` filters out almost nobody rather than
almost everybody. `min_trades` has a **floor of 3** — a lower value is raised to it, so
single-trade wallets with spectacular ROI cannot be surfaced at all. And `size` caps at 20 with
no page parameter, so the ranking is the first page or nothing; narrow with the floors rather
than paging.

The numeric parameters accept a string as well as a number, so an agent that stringifies its
arguments is not a problem here.

> Top Hyperliquid traders by ROI over the last 7 days with a win rate above 75%.

> Which HL wallets have the largest realized PnL this month?

## `hl_position_match` [#hl_position_match]

**2 credits.** Reverse-lookup: given what a Hyperliquid share card shows — coin, side, leverage
and entry price — return the wallet or wallets holding a matching **open** position, ranked by
price proximity.

| Parameter     | Type    | Default    | Notes                                                                          |
| ------------- | ------- | ---------- | ------------------------------------------------------------------------------ |
| `coin`        | string  | *required* | Asset symbol, e.g. `BTC`, `ETH`, `SOL`                                         |
| `side`        | enum    | *required* | `long` or `short`                                                              |
| `leverage`    | number  | *required* | Leverage from the share card, e.g. `5`, `10`, `25`                             |
| `entry_price` | number  | *required* | Entry price from the share card                                                |
| `mark_price`  | number  | —          | Current mark price; sharpens the tie-break when several wallets share an entry |
| `limit`       | integer | `10`       | Max matches, max 50                                                            |

**Returns** per match: address, coin, side, snapshot timestamp, position size in tokens and in
USD, entry and mark price, leverage, liquidation price, unrealized PnL, and the entry distance
as a percent. Alongside the matches come `match_count`, the `query` you sent back as an echo,
and `tolerance_used` — the band that actually answered, which is the field that tells you how
confident the identification is.

Matching walks three widening entry-price bands — &#x2A;*tight ±0.05%**, then &#x2A;*loose ±0.5%**, then a
&#x2A;*fallback ±1.0%*&#x2A; — stopping at the first that produces matches, and leverage must land within
**±0.5** in every band. Results are ordered by mark-price distance first and entry distance
second. Omitting `mark_price` is not an error; it falls back to the entry price, which simply
makes the tie-break less discriminating when a popular round-number entry is crowded.

It reads open positions from the latest snapshot, gated to the canonical **15-minute freshness
window**. So an empty result means no *currently open* position matches, not that nobody ever
held one — a card screenshotted yesterday and closed since will find nothing, and that is the
tool working correctly rather than a miss.

> Whose share card is this — 25x ETH long opened at $3,200?

> Who has a 10x BTC short open near $91,500?


# Polymarket (/docs/ai/data/polymarket)



Four tools over Polymarket. The usual path runs left to right: list markets, drill into one,
check where the cohort's money is going, then profile the wallets behind it.

**"Smart money" here has a definition**, used by both `polymarket_smart_money` and the cohort
figures inside `polymarket_market_detail`: wallets with at least $1,000 of realized PnL across
five or more resolved markets. It is a track-record filter, not a label anyone applied by hand.

## `polymarket_markets` [#polymarket_markets]

**1 credit.** Trending Polymarket events ranked by 24-hour volume.

| Parameter  | Type    | Default | Notes                                                           |
| ---------- | ------- | ------- | --------------------------------------------------------------- |
| `category` | string  | `all`   | `Crypto`, `Sports`, `Politics`, `Pop-Culture`, `Tech`, or `all` |
| `limit`    | integer | `10`    | Max markets, max 30                                             |

**Returns** per market: title, slug, category, current Yes/No mid quotes, 24h volume, and
`end_date`.

> What is hot on Polymarket right now?

> Top 20 politics markets by volume today.

## `polymarket_market_detail` [#polymarket_market_detail]

**2 credits.** Everything about one market, keyed by its `condition_id`: the question,
category, outcomes, current quotes, 24h volume, smart-money cohort flows, the top wallets
active in it, and resolution status.

| Parameter      | Type   | Required | Notes                            |
| -------------- | ------ | :------: | -------------------------------- |
| `condition_id` | string |    yes   | Market condition id (hex string) |

The `condition_id` comes from `polymarket_markets`, which is why the two are normally called in
sequence — an agent that has only a market title should list first and match, not guess an id.

> Tell me everything about this market, including who is on each side.

## `polymarket_smart_money` [#polymarket_smart_money]

**2 credits.** Two distinct signals behind one `mode` switch.

| Parameter  | Type    | Default | Notes                    |
| ---------- | ------- | ------- | ------------------------ |
| `mode`     | enum    | `flows` | `flows` or `mispricings` |
| `hours`    | integer | `24`    | Lookback window in hours |
| `category` | string  | `all`   | Category filter          |
| `limit`    | integer | `10`    | Max rows, max 20         |

* **`flows`** — markets with the largest net cohort inflow over the lookback. This is "where
  the money went".
* **`mispricings`** — markets where the cohort bought meaningfully below the current mid, i.e.
  a position that is already in profit on paper. This is "where the money looks early".

Note the window is in **hours**, not a window enum, so a week is `hours: 168`.

> Which Polymarket markets have smart money bought into over the last 6 hours?

> Show me cohort mispricings in crypto markets today.

## `polymarket_wallet` [#polymarket_wallet]

**2 credits.** Profile one Polymarket trader: realized P\&L over 24h / 7d / 30d / all-time,
hit-rate on resolved markets, total volume, top categories traded, and recent positions.

| Parameter | Type   | Default    | Notes                                                   |
| --------- | ------ | ---------- | ------------------------------------------------------- |
| `address` | string | *required* | Polymarket wallet address (0x-prefixed)                 |
| `window`  | enum   | `all`      | `24h`, `7d`, `30d`, `all` — scopes the windowed metrics |

Hit-rate is computed on **resolved** markets only, so a wallet holding large open positions can
show a thin record until those markets settle.

> Profile this Polymarket wallet — is its record any good?


# Tokens (/docs/ai/data/tokens)



Four tools covering the token side of the on-chain data: find a token, screen the universe by
activity, then look at who holds it and who has been trading it. All four work on Ethereum, BSC
and Base.

There are no per-contract price candles — see [Candles](/docs/ai/data/candles). The four tools below
read our own transfer index.

Token tools other than `token_search` are keyed by **contract address**, not symbol — start
with a search when the user gives you a ticker.

## `token_search` [#token_search]

**Free — 0 credits.** Search tokens by name or symbol.

| Parameter | Type    | Default    | Notes                        |
| --------- | ------- | ---------- | ---------------------------- |
| `query`   | string  | *required* | Search term (symbol or name) |
| `chain`   | enum    | `ethereum` | `ethereum`, `bsc`, `base`    |
| `limit`   | integer | `10`       | Max results                  |

**Returns** matching symbols, names, addresses and logos. Because it costs nothing, it is the
natural first hop for every other tool on this page.

> Find the PEPE token on Ethereum.

## `token_screener` [#token_screener]

**3 credits.** Discover tokens by activity inside a window, ranked by one of four metrics, with
three filters on top. This is the "what is happening today" tool.

| Parameter          | Type    | Default    | Notes                                             |
| ------------------ | ------- | ---------- | ------------------------------------------------- |
| `chain`            | enum    | `ethereum` | `ethereum`, `bsc`, `base`                         |
| `window`           | enum    | `24h`      | `24h`, `7d`, `30d`, `90d`                         |
| `sort`             | enum    | `volume`   | `volume`, `net_inflow`, `holders`, `smart_inflow` |
| `limit`            | integer | `20`       | Max tokens, max 100                               |
| `min_volume_usd`   | number  | —          | Drop tokens below this 24h volume                 |
| `min_holders`      | integer | —          | Drop tokens below this holder count               |
| `smart_money_only` | boolean | `false`    | Restrict to smart-money cohort flows              |

`smart_inflow` and `smart_money_only` are two different knobs: the first *ranks* by cohort
inflow, the second *filters* the universe to cohort flows. Combining them narrows hard.

> What tokens have smart money been accumulating on Base this week?

## `token_holders` [#token_holders]

**2 credits.** Top holders of an ERC-20 token, ranked by cumulative net inflow USD.

| Parameter       | Type    | Default    | Notes                                 |
| --------------- | ------- | ---------- | ------------------------------------- |
| `token_address` | string  | *required* | ERC-20 contract address (0x-prefixed) |
| `chain`         | enum    | `ethereum` | `ethereum`, `bsc`, `base`             |
| `limit`         | integer | `10`       | Max holders, max 50                   |

**Returns** per holder: wallet, net flow USD, volume USD, transaction count, first and last
seen dates, and known labels.

The ranking is by net inflow measured from transfer history, so it answers "who accumulated the
most" rather than "who holds the largest balance on chain right now".

> Show me the top 25 holders of this token, with labels.

## `token_transfers` [#token_transfers]

**2 credits.** Who bought and who sold a token in a period, with quantities and USD values.

| Parameter       | Type   | Default    | Notes                                   |
| --------------- | ------ | ---------- | --------------------------------------- |
| `token_address` | string | *required* | Contract address (0x-prefixed)          |
| `period`        | enum   | `24h`      | `1h`, `24h`, `7d`, `30d`                |
| `tab`           | enum   | `sold`     | `bought` for buyers, `sold` for sellers |
| `chain`         | enum   | `ethereum` | `ethereum`, `bsc`, `base`, `all`        |

Two things to know. The default `tab` is `sold`, so a question about buyers needs `bought`
passed explicitly. And the result size is fixed at the top 10 in the handler — there is no
`limit` parameter to raise.

> Who has been buying LINK in the last 24 hours?


# Wallets (/docs/ai/data/wallets)



Eleven tools for wallet analytics on Ethereum, BSC and Base. They divide into three jobs:
**describe one wallet** (`wallet_summary`, `wallet_transactions`, `wallet_token_balances`,
`wallet_pnl_history`), **find or connect wallets** (`wallet_discover`, `wallet_counterparties`,
`wallet_trace`, `wallet_compare`), and **name them** (`wallet_ens`, `wallet_batch_labels`,
`wallet_label_provenance`).

Addresses are 0x-prefixed EVM hex throughout. Numeric parameters accept either a number or its
string spelling — an agent that passes `"30"` instead of `30` is coerced, not rejected.

## `wallet_summary` [#wallet_summary]

**2 credits.** A wallet's aggregate metrics: volume, inflow, outflow, net flow, transaction
count and tokens traded, across the 24h / 7d / 30d / 90d / all windows. There is no window
parameter — one call returns every window.

| Parameter | Type   | Required | Notes                            |
| --------- | ------ | :------: | -------------------------------- |
| `address` | string |    yes   | Wallet address (0x-prefixed hex) |

> What has 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 been doing lately?

## `wallet_discover` [#wallet_discover]

**2 credits.** Top wallets ranked by a metric you choose — volume, inflow, outflow, net flow,
transaction count, or realized PnL.

| Parameter | Type    | Default    | Notes                                                        |
| --------- | ------- | ---------- | ------------------------------------------------------------ |
| `window`  | enum    | `30d`      | `24h`, `7d`, `30d`, `90d`, `all`                             |
| `sort`    | enum    | `volume`   | `volume`, `inflow`, `outflow`, `net_flow`, `tx_count`, `pnl` |
| `order`   | enum    | `desc`     | `asc` or `desc`                                              |
| `chain`   | enum    | `ethereum` | `ethereum` or `bsc`                                          |
| `size`    | integer | `10`       | Results per page, capped at 20                               |

**Returns** `{"wallets": [...], "total": n}`. Each row carries `address`, `volume`, `inflow`,
`outflow`, `net_flow`, `tx_count`, `tokens_traded`, `first_seen`, `last_active`,
`realized_pnl`, `tokens_profitable` and `pnl_available` — the USD columns already converted to
whole dollars.

> Top 20 BSC wallets by realized PnL over the last 7 days.

## `wallet_transactions` [#wallet_transactions]

**2 credits.** The raw per-wallet transfer list — single transactions, not aggregates. This is
the forensic tool: use it when the question is "show me the actual transfers", not "how much
did this wallet do".

| Parameter       | Type    | Default    | Notes                          |
| --------------- | ------- | ---------- | ------------------------------ |
| `address`       | string  | *required* | Wallet address (0x-prefixed)   |
| `chain`         | enum    | `ethereum` | `ethereum`, `bsc`, `base`      |
| `direction`     | enum    | `all`      | `in`, `out`, `all`             |
| `days`          | integer | `30`       | Days back, max 365             |
| `limit`         | integer | `50`       | Max transactions, max 500      |
| `min_usd`       | number  | `0`        | Drop dust below this USD value |
| `token_address` | string  | —          | Restrict to one token          |

**Returns** per transfer: `time`, `tx_hash`, `from`, `to`, `token_address`, `value_usd`,
`direction`, `block`.

> List the last 100 outgoing transfers over $10k from 0xabc… on Base.

## `wallet_token_balances` [#wallet_token_balances]

**3 credits.** Current ERC-20 balances for a wallet across major EVM chains, sourced from
Moralis. Dust below $1 is filtered by default.

| Parameter | Type   | Default                                       | Notes                              |
| --------- | ------ | --------------------------------------------- | ---------------------------------- |
| `address` | string | *required*                                    | Wallet address (0x-prefixed)       |
| `chains`  | array  | `eth, bsc, base, arbitrum, polygon, optimism` | Chains to scan                     |
| `min_usd` | number | `1.0`                                         | Drop holdings below this USD value |

**Returns** one row per holding: chain, symbol, balance, USD value, USD price.

Pair it with `wallet_label_provenance` for institutional context.

> What tokens does this wallet hold right now, across all chains?

## `wallet_pnl_history` [#wallet_pnl_history]

**2 credits.** A daily net-flow series for a wallet — per-day net inflow USD, plus cumulative
net flow, gross volume and transaction count.

| Parameter | Type    | Default    | Notes                        |
| --------- | ------- | ---------- | ---------------------------- |
| `address` | string  | *required* | Wallet address (0x-prefixed) |
| `chain`   | enum    | `ethereum` | `ethereum`, `bsc`, `base`    |
| `days`    | integer | `30`       | Days back, max 365           |

<Callout type="warn" title="This is net inflow, not realized PnL">
  The tool's own description says so: true realized PnL would need weighted-average-cost
  accounting per token, which this series does not do. Read it as a directional indicator of
  whether a wallet has been accumulating or distributing, not as a profit figure.
</Callout>

> Plot the daily net flow of 0xabc… over the last 90 days.

## `wallet_counterparties` [#wallet_counterparties]

**2 credits.** Top trading partners of a wallet by combined transfer volume.

| Parameter | Type    | Default    | Notes                                    |
| --------- | ------- | ---------- | ---------------------------------------- |
| `address` | string  | *required* | Wallet address (0x-prefixed)             |
| `chain`   | enum    | `ethereum` | `ethereum`, `bsc`, `base`                |
| `window`  | enum    | `30d`      | `24h`, `7d`, `30d`, `90d`, `180d`, `all` |
| `limit`   | integer | `10`       | Max counterparties, max 50               |

**Returns** per counterparty: address, total volume, amount sent and received, transaction
count, first and last seen, and labels where known.

> Who does this wallet trade with most?

## `wallet_trace` [#wallet_trace]

**4 credits — the most expensive tool in the catalogue.** Follows a wallet's money outward:
at each hop it expands to the top N counterparties by USD volume and repeats, returning the
nodes and edges of the resulting graph.

| Parameter | Type    | Default    | Notes                              |
| --------- | ------- | ---------- | ---------------------------------- |
| `address` | string  | *required* | Root wallet to trace from          |
| `chain`   | enum    | `ethereum` | `ethereum`, `bsc`, `base`          |
| `depth`   | integer | `2`        | Hops to follow, 1–5                |
| `width`   | integer | `5`        | Top N counterparties per hop, 1–10 |
| `window`  | enum    | `30d`      | `24h`, `7d`, `30d`, `90d`, `all`   |
| `min_usd` | number  | `10000`    | Minimum USD per transfer to follow |

Cost grows with `depth` × `width`, and so does noise. Lowering `min_usd` on a busy wallet
widens the graph fast; the $10k floor exists to keep a trace legible.

> Follow the money three hops out from 0xabc…, top 5 counterparties per hop.

## `wallet_compare` [#wallet_compare]

**3 credits.** Asks whether two wallets are related, by intersecting what they touched: shared
counterparties (addresses both wallets transacted with) and shared tokens (tokens both wallets
traded) inside one window.

| Parameter   | Type    | Default    | Notes                                    |
| ----------- | ------- | ---------- | ---------------------------------------- |
| `address_a` | string  | *required* | First wallet                             |
| `address_b` | string  | *required* | Second wallet                            |
| `chain`     | enum    | `ethereum` | `ethereum`, `bsc`, `base`                |
| `window`    | enum    | `30d`      | `24h`, `7d`, `30d`, `90d`, `180d`, `all` |
| `limit`     | integer | `10`       | Max shared items per category, max 50    |

An overlap is evidence, not proof — two wallets that both used a large exchange share that
counterparty with everyone else.

> Are 0xaaa… and 0xbbb… related? Compare them over 90 days.

## `wallet_ens` [#wallet_ens]

**1 credit.** Reverse ENS lookup: an address in, a name like `vitalik.eth` out, or `null` when
the address has no ENS name set.

| Parameter | Type   | Required | Notes                               |
| --------- | ------ | :------: | ----------------------------------- |
| `address` | string |    yes   | EVM address (0x-prefixed, 42 chars) |

> What is the ENS name for 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?

## `wallet_batch_labels` [#wallet_batch_labels]

**2 credits.** Bulk enrichment: labels plus a 30-day summary for many addresses in one call.
Rows come back in input order, so a pasted CSV keeps its shape.

| Parameter   | Type  | Default    | Notes                                   |
| ----------- | ----- | ---------- | --------------------------------------- |
| `addresses` | array | *required* | Wallet addresses (0x-prefixed), max 100 |
| `chain`     | enum  | `ethereum` | `ethereum`, `bsc`, `base`               |

**Returns** one row per input address: `entity`, `wallet_type`, `risk_flag`, 30-day net flow,
30-day volume, 30-day transaction count.

> Here are 60 addresses — label them and tell me which ones moved money this month.

## `wallet_label_provenance` [#wallet_label_provenance]

**1 credit.** The full label cascade for one Ethereum wallet, with per-source attribution:
Arkham, OLI, Blockscout, Dune, the MEW darklist, Etherscan, and Vike's heuristic classifier,
plus a consensus entity and type.

| Parameter | Type   | Required | Notes                            |
| --------- | ------ | :------: | -------------------------------- |
| `address` | string |    yes   | Wallet address (0x-prefixed hex) |

Use this when the answer matters enough that *who says so* matters: a single consensus label
hides whether seven sources agreed or one source guessed.

> Who labeled this address, and do the sources agree?


# Data API changelog (/docs/changelog/data)



This page records changes a **caller** can see: `/v1` REST routes added and removed, MCP tools
added and fixed, response fields that appeared or changed meaning, error and rate-limit behaviour,
and the auth and metering rules on the bulk Parquet archive. Newest first.

It does not cover the Vike trading platform — that is the [Trader changelog](/docs/changelog/trader) —
nor the website's own `/api/*` and HTML routes, nor internal plumbing no key-holder can call.

**The API is versioned by path prefix.** `/v1` is the only version that has ever been published,
and, as the marked entries below record, routes have been removed and parameters have started
returning `400` *inside* that prefix rather than behind a new one. Do not assume `/v1` is frozen —
scan the markers.

<Callout type="warn" title="⚠ BREAKING marks an entry that required a caller to change something">
  An entry tagged **⚠ BREAKING** removed an endpoint, made a parameter start returning `400`, changed
  the shape of a response, or added a credential requirement where there was none. Everything else is
  additive, or a fix to an answer that was wrong.
</Callout>

Entries are written from the change that actually landed rather than from probing the deployed
API, so a fix is dated when it shipped, not when someone noticed it.

## 2026-10 [#2026-10]

* **2026-10-16 · `GET /v1/polymarket/wallets/{address}` and `GET /v1/polymarket/smart_money` added** —
  the two Polymarket trader tools that existed only over MCP (`polymarket_wallet`,
  `polymarket_smart_money`) now have REST routes that run the same code, so the two surfaces return
  the same payload. They read the on-chain trade tape, not the recorded book. The polymarket
  namespace is now 11 routes (68 across the API). Additive; nothing changed on the nine existing
  routes.

* **2026-10-16 · ⚠ BREAKING · MCP `options_flow`, `web_search` and `web_fetch` are removed** —
  `tools/list` now returns 31 tools. `options_flow` (Deribit call/put flow) had 1 call in the
  previous 90 days; the two web tools are a proxy to a third-party search service rather than Vike
  data, and `web_fetch` fetched arbitrary URLs from our servers. A `tools/call` for any of the
  three now returns the unknown-tool error. Nothing replaces them.

* **2026-10-16 · ⚠ BREAKING · `fund_holdings` and `GET /v1/onchain/funds/holdings` are removed** —
  the labelled fund / market-maker / treasury / CEX leaderboard is no longer offered on any
  surface. The MCP tool is gone from `tools/list` (34 tools remain), the route answers `404`, and
  the `/data` dataset page and its panel are gone with it. Callers of the REST route or the tool
  have to drop the call; nothing replaces it.

## 2026-09 [#2026-09]

* **2026-09-21 · ⚠ BREAKING · MCP `token_chart` removed; `ohlcv` replaced by `hl_ohlcv` and
  `polymarket_ohlcv`** — both tools read the merged centralised-exchange candle engine. `ohlcv`
  read it directly; `token_chart` resolved an ERC-20 contract to a canonical symbol and read the
  same engine behind it, which is why a per-contract chart could answer for a token that trades
  nowhere on chain. Vike redistributes market data only from venues whose data is itself on
  chain — Hyperliquid and Polymarket — so the candle tools are scoped to those two rather than
  filtered venue by venue.

  `tools/call` with either retired name returns `-32601`. `hl_ohlcv` serves Hyperliquid candles
  and `polymarket_ohlcv` serves Polymarket candles; there is no replacement for a candle on a
  centralised venue, and no candle tool takes a contract address. The REST candle routes are
  unaffected by this entry — `/v1/hyperliquid/ohlcv(/export)` and `/v1/polymarket/ohlcv` already
  serve the same two venues.

* **2026-09-04 · ⚠ BREAKING · `/v1/onchain/wallets/{address}/balances` reads the chain, and covers
  two chains instead of six** — balances are now `balanceOf` calls against our own Ethereum and BSC
  nodes, with the candidate token list drawn from our transfer index. `base`, `arbitrum`, `polygon`
  and `optimism` are **no longer scanned**: they come back named in `chain_errors` rather than
  silently contributing nothing.

  Two response fields are new — `balance_raw` (the contract's integer, as a string, for callers
  that need exactness) and `name`. `usd_value` and `usd_price` are now `null` on a holding we
  cannot price, and the holding is still listed; `total_usd` sums only the priced ones and should
  be read as a floor. The previous provider filtered unpriced holdings out entirely.

  The route no longer answers `200` with an empty `holdings` array when the lookup fails. That was
  the old shape and it read exactly like an empty wallet.

* **2026-09-04 · ⚠ BREAKING · `GET /v1/onchain/wallets/{address}/defi` is removed** — decoded
  DeFi protocol positions, and the `defi_positions` MCP tool beside it. The route was served by an
  upstream vendor whose free tier was withdrawn on 2026-09-03, and it cannot be rebuilt from our
  own data: we record `Transfer` events, and a lending position is not a transfer. It recorded
  **4 calls in its entire history**, so it was retired rather than replaced. `fund_holdings` is
  unaffected. Calls now return `404`.

* **2026-09-04 · `/v1/onchain/wallets/{address}/ens` resolves against our own node** — the
  fallback for an address our pre-resolved table has not seen was an external API; it is now two
  `eth_call`s to the ENS registry over our own Ethereum RPC. No behaviour change for a caller
  beyond the obvious one: the fallback works again, where since 2026-09-03 it returned nothing.
  The name is forward-verified before it is returned — a reverse record is written by the address
  itself and means nothing until resolving it forward lands back on the same address — so a
  spoofed record answers `null` rather than somebody else's name.

* **2026-09-03 · ⚠ BREAKING · the flat Polymarket paths were retired** — `/v1/markets`,
  `/v1/markets/{condition_id}`, `/v1/market_stats`, `/v1/ohlcv`, `/v1/orderbook`,
  `/v1/settlements/{condition_id}` and `/v1/events` now return `404`. They predated the
  `/v1/polymarket/` namespace and answered alongside it for compatibility. Add `/polymarket`
  after `/v1` and nothing else changes — same handlers, same responses. Retired because the usage
  record showed no caller: 28 requests across their entire history, all from the account that
  owns the platform.

* **2026-09-03 · Polymarket moved to the same service as every other namespace** — the nine
  endpoints were served by a separate process and are now served by the same application as
  `onchain` and `hyperliquid`. No path, parameter or response shape changed. What did change is
  below.

* **2026-09-03 · ⚠ BREAKING · market state is real** — `active` and `closed` were CONSTANTS: every
  market reported `active=1, closed=0`, so `?active=0` returned nothing at all and `?closed=1`
  returned open markets with a `200`. State is now derived from on-chain resolutions and the
  venue's own flag, either of which alone misses thousands. &#x2A;*119,047 of 121,275 markets report
  closed where none did before.** ⚠ If you filtered on these fields, your results change — that is
  the fix, not a regression. `closed` is also accepted now as the complement of `active`; passing
  both is refused rather than silently resolved.

* **2026-09-02 · Archive downloads no longer spend the hourly request budget** — a ranged `GET`
  against `/archive/` is still authenticated and still writes its usage row, but it no longer
  consumes the hourly request allowance. Bulk Parquet readers (pyarrow, DuckDB, fsspec) fetch a
  footer and then one ranged `GET` per column chunk, each of which cost a unit: one 1.26 GB
  partition measured **20,237 usage rows**, more than the whole 20,000/hour ceiling for a single
  file, and almost every rate-limit rejection recorded in the platform's whole history was an
  archive download. `/v1` and `/mcp` still meter normally, and the counter's periodic reseed excludes
  `archive_download` rows too, so the skip is not erased 30 seconds later.

* **⚠ BREAKING · 2026-09-02 · Rate-limit rejections speak one dialect on every surface** — a
  throttled request now returns `429` with `Retry-After: 60` and
  `{"error": {"code": "RATE_LIMITED", ...}}`. Previously `/v1` raised `{"detail": ...}`, the archive
  gate hand-built `{"error": "rate limited"}`, and `/mcp` answered `200` with a JSON-RPC error — so
  a client could not detect throttling by status code at all. `/mcp` still returns a valid JSON-RPC
  body and carries the envelope in `error.data`.

* **2026-09-02 · The published OpenAPI spec declares `X-API-KEY`** — the `/v1` spec carried no
  `securitySchemes` and no `security`, so a client generated from it omitted the API-key header and
  `401`'d on every call. The schemes are injected into the generated spec itself, so the live spec
  and the exported file cannot disagree; ReDoc moved under `/v1/` at the same time.

* **⚠ BREAKING · 2026-09-02 · The website app stopped publishing its route table** —
  `/openapi.json` (283 paths), `/docs` and `/redoc` are switched off on the website app. Only the
  data API publishes a schema, scoped under `/v1/`. No `/v1` route changed.

* **⚠ BREAKING · 2026-09-02 · `/v1/etf/*` and `/v1/marketdata/ohlcv(/export)` removed** — the ETF
  router is no longer mounted and the marketdata candle routes are deleted; both now `404` for an
  authenticated caller, a closure pinned by a regression test so it cannot quietly come back.
  Public candles remain at `/v1/hyperliquid/ohlcv(/export)`. Usage showed exactly one key had ever
  called each surface, last on Aug 17 and Aug 6.

* **2026-09-02 · New docs site at vike.io/docs/data** — replaces the MkDocs site, which documented
  8 of the 36 MCP tools the server exposes and quoted rate limits wrong by more than an order of
  magnitude. It covers getting started, authentication, rate limits, errors, the full 36-tool MCP
  reference generated from what the registry's `tools/list` actually serves, per-client setup
  (Claude Desktop and Code, Cursor, Gemini CLI, VS Code, raw HTTP), the `/v1` REST overview and the
  archive; the [Polymarket REST reference](/docs/data/reference/polymarket) landed the same day.
  `PRs #852 · 0b032622`, `#855 · a0afdb91`, `#856 · ecf9a730`

* **2026-09-01 · Non-finite floats serialize as `null` instead of failing the request** — a single
  `NaN` or `Infinity` anywhere in a payload previously produced a `503` through the error handler
  or a `500` on `/v1`, losing the entire response; the field is now `null` and the rest of the body
  arrives. It is also a large latency win on bulk pages: a 5,000-candle page went
  **44.14 ms to 1.41 ms**, and NDJSON export lines **3.35 µs to 0.30 µs**.

## 2026-08 [#2026-08]

* **2026-08-22 · MCP `hl_position_match` stopped returning closed positions** — the tool read a
  latest-known-position view with no recency filter, and that view keeps a wallet's last-seen row
  forever (**89.8% of rows more than a day stale**, the oldest from 2026-04-02), so
  "who has a 25x ETH long open at $3,200" could answer with a position closed in April while the
  tool card promised `<5 min` staleness. Results are now gated on the newest snapshot batch for the
  asset.
* **⚠ BREAKING · 2026-08-19 · `/v1/hyperliquid/coins/{coin}/metrics` refuses `labelBasis` and
  declares its contamination** — the route filters every historical hour by *today's* wallet
  grading, resolved at request time rather than as of the hour being reported. Measured on the
  2026-04-20T12:00Z BTC "3x smart" cohort: &#x2A;*938,495,920.6 against a point-in-time
  861,706,562.3 — 8.91% inflated.** It
  used to answer `200` to a request for honest labels; it now returns `400` for the parameter and
  points at `/cohort-metrics`.
* **2026-08-19 · `grading=` on `/v1/hyperliquid/coins/{coin}/cohort-metrics`, and responses declare
  when the label was computed** — one parameter selects among `realized`, `realized-pit` and
  `unrealized`, which previously took three different spellings (`axis=pnl` plus `labelBasis`, a
  separate axis, and no parameter at all). Every response now carries `label_computed` on the
  envelope and `grading` on every row.
* **2026-08-19 · `freshness` object added to cohort-metrics responses** — windows reaching the
  present now carry `freshness: {newest_ts, age_seconds, settled_lag_ceiling_seconds, stale}`.
  Before this, `?grading=realized-pit&hours=1` with no `start` returned its own newest bucket —
  measured **63 hours old** and identical in shape to a live one, with nothing in the payload
  letting a program tell them apart. `stale` is the precomputed verdict, so a caller need not
  re-derive the rollup cadence. (figure corrected in)
* **2026-08-18 · New endpoint: `GET /v1/hyperliquid/ohlcv` (and `/export`)** — minute-resolution
  Hyperliquid candles built from executed fills, mirroring `/v1/marketdata/ohlcv`'s parameters and
  envelope. Two parameters are Hyperliquid-specific: `dex` (HL core versus builder-deployed HIP-3
  perp DEXs) and tick intervals such as `15t`.
* **2026-08-17 · New cohort axis: `axis=pnl_unrealized`** — grades a wallet by unrealized PnL on
  open positions as a share of account value, a different signal from the realized ladder:
  &#x2A;*44% of wallets change unrealized rung day over day, against 2.4% on realized.** Point-in-time by
  construction, and not reachable through the API at all before this.
* **⚠ BREAKING · 2026-08-16 · `/v1/marketdata/orderbook` removed** — the L1/L2 recorder behind it
  was retired and its stored datasets dropped (quotes 1.376B rows, book events 531M, trades 296M,
  among others; \~51 GiB reclaimed). The route was their only consumer, so it goes with them rather
  than becoming a permanent `503`. There is no orderbook surface.
* **2026-08-15 · New namespace: `/v1/etf/*` (physical-ETF holdings)** — 23 funds, 19 of them with a
  daily measured source; `quantity` is a measured count in the fund's own unit, never assets divided
  by a price. ⚠ This namespace was closed again on 2026-09-02.
* **2026-08-12 · Repeated identical `/v1` requests return byte-identical bodies** — the query
  engine reduces `sum()` in an unpinned parallel order and f64 addition is not associative, so the
  last digits of a nine-figure notional were reduction noise: &#x2A;*one URL executed six times
  returned six distinct bodies, with 24–35% of values differing pairwise.** Values are now snapped
  to 10 significant digits at the serialization boundary with a midpoint nudge, which took one research
  pipeline's content-addressed cache from broken to working; consumers no longer need to
  canonicalize floats themselves.
* **⚠ BREAKING · 2026-08-11 · One canonical position-size ladder; retired labels now `400`; new
  `GET /v1/hyperliquid/cohorts`** — the position-size axis had four vocabularies (the site's
  dollar-range ladder, a stored `micro`..`mega` tier vocabulary, and two reconstruction
  vocabularies). The dollar-range ladder wins: `axis=tier`, `/coins/{coin}/size-breakdown` and
  `/segments` `trade_size` all derive the bucket from `size_usd` and serve the same canonical ten
  labels, largest first, and a retired label in a cohort filter returns `400` naming the canon. The
  new flat taxonomy endpoint `GET /v1/hyperliquid/cohorts` publishes all three ladders.
* **2026-08-11 · New cohort axis: `axis=tier` on `/coins/{coin}/cohort-metrics`** — the per-position
  size ladder as the third matrix axis. It is rejected on the per-wallet aggregates (heatmap,
  segment summary) because a wallet straddles tiers, and the refusal names where the axis *is*
  valid; a conflicting `labelBasis` is a `400` rather than a silent downgrade.
* **2026-08-06 · `labelBasis=point_in_time` on `axis=pnl` — the pnl axis had lookahead** —
  `axis=pnl` resolved the cohort at query time, so a historical row came back with today's grading
  and a backtest was told which wallets eventually became rankable. Measured on BTC over 3 days:
  **0 of 852 cells exact before, 852 of 852 after** (max relative error 5.45e-16), and hourly totals
  from 4.37% mean error to 0.000000%. The frozen source costs five fields — no position count, no
  unrealized PnL, no token-denominated size — which come back `null` rather than `0` and are named
  in `unavailable_fields`; every row and the envelope carry `label_basis`.
* **2026-08-06 · New endpoint: `GET /v1/hyperliquid/coins/{coin}/cohort-metrics`** — returns the
  full coin-by-cohort matrix in one request instead of one request per bucket (12 for size, 13 for
  pnl). Measured on BTC over 24 hours: &#x2A;*0.25–0.44 s per axis against \~12 s for the equivalent
  loop.** Paginated by hour rather than by row, so a page never lands mid-bucket.
* **2026-08-06 · `provisional` flag on `/coins/{coin}/metrics` rows** — the endpoint reads an hourly
  rollup that does not write hour H until H+1:00 to H+1:30; measured, **the newest row was 114
  minutes old** and a client polling for "current positioning" had no way to know. Rows now carry
  `provisional`, true on at most one row (the unsettled right edge), and the live row cuts staleness
  to roughly 5 minutes.
* **2026-08-06 · `/segments` rows carry `groupable`; axis error messages fixed** — `/segments`
  published four axes but only three were valid as `?axis=` (`trade_size` buckets a position, not a
  wallet), with nothing in the payload saying so; every row now carries `groupable` so a generated
  client can filter. Refusals name where the axis is valid, and the "forgot the axis" case no longer
  reports the server's own default back at the caller.
* **2026-08-04 · The `/v1` data API goes live on data.vike.io** — 34 routes across four namespaces
  under one host: `marketdata`, `onchain`, `hyperliquid` and `polymarket`. The error contract from
  day one: `400` for caller input, `503` for upstream, never a `200` with an empty body. The same
  work made archive authentication independent of the website, so a website deploy can no longer
  `500` an archive download — the mechanism of the 2026-07-31 outage.
  `PRs #574 · af98d88d`, `#584 · 638a6d93`
* **2026-08-04 · `/v1/hyperliquid` expands from 2 endpoints to 22** — new: cohort catalogue,
  per-cohort summary and coin-by-cohort heatmap; position list and history, market-wide OI, hourly
  coin metrics, trade-size breakdown; trader leaderboard with the full risk-metric set, and
  per-wallet summary, trades, trade-stats, fills, funding and ledger; liquidation fills, a
  price-binned liquidation heatmap and liquidation risk by asset; ecosystem stats, perp volume and
  HYPE holders. Pagination is keyset throughout.
* **2026-08-04 · New: `/v1/hyperliquid/builders/*` (6 routes)** — leaderboard, builder profile, that
  builder's traders, raw fills, a per-bucket time series, and the reverse lookup of which builders a
  wallet routes through. Schema note for consumers: `builder_fee` and `deployer_fee` are USD, but
  `fee` is denominated in `fee_token` (**1.04% of rows pay in something else**), so fee aggregates
  are USD-only and the profile reports what it excluded.
* **2026-08-04 · New: `GET /v1/hyperliquid/builders/stats`, plus richer builder fields** —
  leaderboard rows gain `revenue_per_user`, `taker_pct`, `market_share_pct` and
  `first_seen_lifetime`; the profile gains `profitable_users(_pct)`, `biggest_day`,
  `market_share_pct`, a lifetime block and `user_volume_distribution` (volume deciles).
  `/builders/stats` returns ecosystem totals, all-time builder revenue and a daily series. The same
  change fixes a keyset pagination bug that could drop or repeat rows.
* **2026-08-04 · `axis=pnl_abs`, a position-age filter, and `/leaderboard/flow-adjusted`
  re-enabled** — the board was withheld in #588 and now ranks on **total realized PnL**
  (closed round-trips), because the upstream ledger records sends one-sided: over 30 days,
  **1,010,263 negative against 835,295 positive send rows, netting -$1.27B**, so an outflow was
  recorded while the matching inflow was invisible and booked as profit. The attributed figures ship
  under their own `attributed` key with a `flow_unbalanced` flag.
* **2026-08-04 · `/v1/marketdata/options/chain` returned settled contracts, not the live chain** —
  the query had no time bound: it aggregated the whole recorded history and returned the oldest
  expiries first, so a BTC chain request came back with contracts that had **settled eight weeks
  earlier** while the live chain was three expiries inside the next 72 hours.
  The read is now bounded to one snapshot.

## 2026-07 [#2026-07]

* **2026-07-29 · Hourly rate limit raised from 2,000 to 20,000 requests per key** — the 2,000
  ceiling was sized for the MCP and AI-chat surface and inherited by the data routes, where it was
  far too low: &#x2A;*a real hour measured 2,543 calls with 558 rejected.** It is one shared ceiling
  across `/v1`, `/mcp` and the archive, not a per-surface number — see
  [Rate limits](/docs/data/rate-limits).
* **⚠ BREAKING · 2026-07-29 · The Parquet archive became credential-gated and metered, and usage is
  labeled per surface** — `/archive/` downloads are now validated at the edge through the same
  API-key and OAuth auth, the same hourly limit and the same metering as `/mcp`, so an
  unauthenticated download stops working. Usage rows are labeled from the request URI rather than
  hardcoded — `/archive/...` to `archive_download`, `/v1/<route>...` to `api_<route>`, `/mcp` to
  `mcp`, anything else to `api_other`. Auth and rate-limit *decision* logic elsewhere was unchanged;
  only the label.

## 2026-06 [#2026-06]

* **2026-06-16 · MCP `perp_funding(symbol=...)` fixed — it errored on every call** — any
  symbol-scoped request returned an error instead of data; only the unscoped call worked. The
  symbol path was rewritten.

## 2026-05 [#2026-05]

* **2026-05-30 · New: a historical OHLCV API (REST + MCP)** — API-key-gated historical candles
  built on a canonical 1-minute base and correct at any timeframe from `1m` to `1w`: UTC
  left-aligned buckets, partial buckets excluded so the series is look-ahead-safe, and
  deterministic cursor pagination. Shares MCP auth, the hourly rate limit and usage logging.
  ⚠ This surface is no longer documented — see the note at the foot of this page — and its MCP
  tool was removed on 2026-09-21.
* **2026-05-30 · `include_partial` flag on `ohlcv` (REST + MCP); `token_chart` returns real
  candles** — `include_partial` is off by default (look-ahead-safe); switched on, it includes the
  in-progress current candle. `token_chart` was a stub and now resolves a token address to a
  canonical symbol and serves real candles through the ohlcv engine, with the legacy `5`/`30`/`120`
  values mapping to `5m`/`30m`/`2h`. ⚠ Both tools were removed on 2026-09-21.
* **2026-05-26 · New MCP tool: `hl_position_match`** — reverse-lookup of Hyperliquid share cards.
  `72bafc07`
* **2026-05-25 · Hourly per-key cap raised from 100 to 2,000** — headroom for agent workloads, where
  one skill workflow can call 5–15 tools per turn. `da4c744d`
* **2026-05-25 · 5 new MCP tools (v0.7)** — `wallet_transactions`, `wallet_compare`, `wallet_trace`,
  `wallet_batch_labels`, `token_screener`. `fdc32aad`
* **2026-05-25 · 4 new MCP tools (v0.5.0)** — `alerts_register_webhook`, `wallet_counterparties`,
  `wallet_pnl_history`, `wallet_token_balances`. `2832bb04`
* **2026-05-25 · New MCP tool `wallet_ens`; `defi_positions` repointed from DeBank to Moralis** —
  the provider swap changes the data source behind an existing tool. `00cfc5ce`
* **2026-05-25 · 2 new MCP tools** — `web_search`, `web_fetch`. `e2143e3f`
* **2026-05-25 · 4 new MCP tools (v0.3.0)** — `fund_holdings`, `wallet_label_provenance`,
  `token_holders`, `defi_positions`. `65a51900`
* **2026-05-25 · 4 new Polymarket MCP tools** — `polymarket_markets`, `polymarket_market_detail`,
  `polymarket_wallet`, `polymarket_smart_money`. `57d327c1`

## 2026-04 [#2026-04]

* **2026-04-20 · New MCP tool: `hl_perp_top_traders`** — `138e9234`
* **2026-04-19 · OAuth 2.1 and Dynamic Client Registration on `/mcp`** — the MCP endpoint accepts
  `Authorization: Bearer` alongside `X-API-KEY`, with RFC 8414 discovery, RFC 7591 dynamic client
  registration, Authorization Code + PKCE S256, refresh-token rotation and RFC 7009 revocation — so
  Claude Desktop's "Add custom connector" dialog works with no `mcp-remote` and no JSON config. The
  rate limit stays per credential: per `api_key_id` for API keys, pooled per `user_id` for OAuth.
  `72774187`
* **2026-04-16 · MCP server launches: `POST /mcp`, JSON-RPC 2.0, `X-API-KEY` auth, 9 tools** —
  initial tools: token search, wallet summary, wallet discover, transfers, chart, perps leaderboard,
  funding, spreads, options flow. Per-tool credit costs, hourly rate limiting and usage tracking
  ship with it. `7d9bec99`

## What this page cannot see [#what-this-page-cannot-see]

Entries are derived from the repository's own history — read from the commit diff, not the subject
line — rather than from probing the deployed API. Four gaps are structural, and it is better to name
them than to let the page imply completeness:

* **`/v1/polymarket/*` has no dated history here.** Those routes are served by a separate system
  with its own history, and were frozen at the `/v1` cutover on 2026-08-04. The current surface is
  documented in [Polymarket REST](/docs/data/reference/polymarket); its change history is not on this
  page.
* **Some surfaces this history records are no longer documented.*&#x2A; Entries above describe
  endpoints and MCP tools that shipped and are not in the current reference — the CEX candle,
  perp and options surfaces. ⚠ They carry no **⚠ BREAKING** entry deliberately, because that
  marker means a caller had to change something and nothing here was withdrawn from callers: the
  documentation was withdrawn, not the routes. Treating an undocumented surface as a supported
  one is the mistake this note exists to prevent.
* **Edge configuration is applied outside this history.** Routing, edge caching, throughput caps,
  compression and which paths are gated can change without a commit to record, so an edge-only
  change is invisible here.
* **The archive's dataset inventory is generated on the host, not committed.** There are no
  "dataset added to the archive" entries above, and that is absence of evidence rather than evidence
  of absence — the open `manifest.json` is the live answer for what the archive holds today.


# Authoring (/docs/ai/trader/authoring)



Four tools for writing a strategy, and none of them touches a server: they run entirely inside
the `vike-cli` process, so they work with no `--addr`, no `--node` and no keys. Two compile a
script (`validate_strategy`, `discover_params`), two answer "what may I write" (`list_templates`,
`list_indicators`).

Strategies are [Rhai](https://rhai.rs/) scripts. Tunable knobs are declared with
`param(name, default)` at the top level; the trading logic lives in `fn on_bar()`.

## `validate_strategy` [#validate_strategy]

Compile a Rhai strategy — compile *is* validation. The check runs through
`crates/vike-script/src/strategy.rs`'s `discover_params`, which compiles the script and runs its
top level exactly once, with no broker attached. That is the same error surface you get from
mounting the strategy for real: the daemon mounts through `RhaiStrategy::compile_with_params`
(`resolve_script` in `crates/vike-tradehub/src/config.rs` is the call site), and that performs the
same one-time top-level run.

`discover_params` is a **public** entry point, so the same broker-free check is callable from your
own Rust code and not only through this tool.

| Parameter | Type   | Required | Notes                |
| --------- | ------ | :------: | -------------------- |
| `script`  | string |    yes   | Rhai strategy source |

**Returns** `ok: true`, or `ok: false` with the compiler's `error` string. A bad script is an
*answer*, not a tool failure — the agent reads the error and fixes the script. Only a missing
`script` argument is an `isError` result.

> Does this strategy compile?

## `discover_params` [#discover_params]

Read back the tunable `param(name, default)` knobs a script declares — the exact keys a profile's
`[strategy.params]` or a `[sweep]` table can override, in declaration order.

| Parameter | Type   | Required | Notes                |
| --------- | ------ | :------: | -------------------- |
| `script`  | string |    yes   | Rhai strategy source |

**Returns** `params`, one row per knob: `name` and its `default`.

Note the deliberate asymmetry with the tool above: both call the same compile path, but a compile
error here *is* a tool error (`rhai compile error: …`), because there are no parameters to report.

Call it on a script you just wrote, not only on one you were handed. `validate_strategy` answers
`ok: true` and says nothing about params, and this tool runs the top level only — so a `param()`
reached from inside `on_bar()` is reported by neither, which makes it exactly as invisible to the
author as to a reader. The tool's own description says so now (`tools_spec` in
`crates/vike-cli/src/cmd/mcp.rs`), because an agent that skipped this step and answered from its
own authorship is what the change was measured against.

> What knobs does this strategy expose, and what are their defaults?

## `list_templates` [#list_templates]

The starter strategies, as `{name, code}` rows: **SMA cross**, **RSI reversion** and **Donchian
breakout**. Each is parameterized via `param()`, so a template drops straight into `run_sweep`
without editing. The sources are static data in `crates/vike-cli/src/cmd/mcp.rs`'s `TEMPLATES`,
copied verbatim from `vike_studio_core::templates`.

That is a hand copy, not a shared import, and there is **no cross-crate drift gate** — the two
copies must be edited together. They are identical today, and nothing but that convention keeps
them so; each side carries its own execution gate over its own copy instead.

This tool takes no arguments.

Two tests stand behind the list, and the second is the one that matters: one *compiles* every
template, and `every_shipped_template_reaches_the_broker` *runs* each one over 80 bars against a
broker double and asserts an order actually arrives. Compiling is the wrong bar for a surface an
agent copies from — a strategy whose every call sits inside `fn on_bar()` compiles perfectly and
can still fail on every single bar (see the callout below).

<Callout type="warn" title="Read the Donchian starter's body before trusting its name">
  It stands in with `sma`, symmetrically, because a bare `donchian(len)` is not bound. `bare_name_binds`
  in `crates/vike-script/src/engine.rs` binds a bare name when the indicator has one output or when its
  first line is the namesake, and donchian's first line is `upper`. Its per-line accessors —
  `donchian_upper()`, `donchian_mid()`, `donchian_lower()` — are all callable, so the bare call is a
  function-not-found on the first bar rather than a silent upper-band read. The template's own comment
  says "multi-output indicators are not bound", which is wider than the rule the host applies.
</Callout>

> Show me the vike strategy templates and explain what each one trades.

## `list_indicators` [#list_indicators]

The **host-bound** callable set — what the Rhai engine actually registers, joined onto the
indicator catalogue's own metadata (`vike_indicators::registry()`). This is deliberately not the
whole catalogue: it is filtered to what a script can really call.

That question is `vike_script::is_callable`, and it has two arms — an indicator qualifies under
its bare name *or* through at least one per-line accessor. `bollinger` has no bare call and three
accessors, so it is listed and you reach it as `bollinger_mid(20)`.

The filter and the rows both live in `crates/vike-cli/src/cmd/indicators.rs`, which also feeds the
human `vike-cli indicators` listing, so the two surfaces cannot disagree about the built-in
catalogue. An indicator installed from `user_data/indicators` shows up in that listing and in no
answer this tool gives.

The answer is tiered, because the bound set is now most of the catalogue and a full dump would
spend an agent's context on indicators it will never use.

| Parameter   | Type   | Default | Notes                                                                        |
| ----------- | ------ | ------- | ---------------------------------------------------------------------------- |
| `name`      | string | *omit*  | One indicator in full: its parameters with defaults and the value it returns |
| `category`  | string | *omit*  | One family in full; matched case-insensitively                               |
| *(neither)* | —      | —       | The compact roster: `name` + `category` per indicator                        |

**Returns** `indicators` plus a `count`. The compact roster also carries a `note` explaining how
to pull detail. A `name` or `category` nobody can serve is an `isError` result, not an empty list
— an empty answer reads as "that family is empty in this build" and sends the reader hunting
through a config. For a catalogued indicator the host deliberately holds back, the error quotes
the host's own reason (`vike_script::unbound_reason`) verbatim rather than paraphrasing it. That
arm fires only for a name callable under NO spelling — a Rhai reserved word, a host-function
collision, a batch-only indicator, or one with more parameters than the host binds. A name whose
bare call is refused but whose accessors work, like `bollinger`, never reaches it: it comes back
as an ordinary catalogue row.

<Callout type="warn" title="An unbound name compiles and then fails on every bar">
  Rhai resolves a registered function when the line *runs*, not at compile time, and the compile
  path only runs a script's top level. So a misspelled indicator or a wrong arity compiles cleanly,
  then raises `ErrorFunctionNotFound` on every bar. Argument type is the exception:
  `register_arity_forms` binds every arity with `rhai::Dynamic` parameters, so `sma(5.0)` resolves
  just like `sma(5)`, and only a non-numeric argument (`sma("20")`) fails — as a named runtime error
  rather than function-not-found.
  `crates/vike-script/src/strategy.rs`'s `RhaiStrategy` swallows each one fail-safe (zero orders
  that bar) and, after 10 consecutive errors, disables the strategy outright. It looks mounted and
  never trades. Check names against this tool, not against memory.
</Callout>

> Which indicators can a vike Rhai strategy call, and what parameters does `rsi` take?


# Backtesting (/docs/ai/trader/backtesting)



Five tools that run against a `vike-datahub` server at `--addr` (default `127.0.0.1:7878`). Three
of them run a strategy over history (`run_backtest`, `run_sweep`, `run_walk_forward`); two answer
what the server has to run it *with* (`list_strategies`, `list_series`). All five are read-only —
a backtest mutates nothing — and all five report an unreachable server as a clean tool error
(`cannot connect to datahub at …`), never a panic.

The three run tools take the same input: a **backtest profile TOML**, optionally with a Rhai
script injected into it. Unless you pass `script`, which makes the client parse and re-serialize
the TOML to inject it (`inject_script_src`), the profile is shipped to the server *verbatim*; and
either way the server is the only thing that reads its shape
(`crates/vike-backtest/src/harness/profile.rs`'s `from_toml_str`, which parses and validates in one
step) — which means a profile-shape error (no `[sweep]` table, a bad range, an unknown strategy)
surfaces from the server after the connect, not before it. One schema, one error source.

```toml
[data]
venue = "binance"
symbols = ["BTCUSDT"]
kind = "bar"
from = "0"
to = "100000"

[strategy]
name = "buy_hold"

[sweep]
fast = [5, 10]
```

## `run_backtest` [#run_backtest]

Run one backtest on the datahub from a profile TOML and return the report.

| Parameter | Type   | Required | Notes                                                                  |
| --------- | ------ | :------: | ---------------------------------------------------------------------- |
| `profile` | string |    yes   | Backtest profile TOML: `[data]`, `[strategy]`, optional `[engine]`     |
| `script`  | string |    no    | Rhai source, injected as `[strategy.params].src` (`inject_script_src`) |

**Returns** `report` — the `BacktestReport` JSON as the server produced it.

The `script` argument is what lets an agent test a strategy it just wrote without ever writing a
file: author, `validate_strategy`, then hand the same source straight to this tool. An
unparsable profile is caught locally by the injection step; everything else is the server's answer.

> Backtest this SMA-cross script on BTCUSDT bars and show me the report.

## `run_sweep` [#run_sweep]

Run a parameter-grid sweep. The profile carries a `[sweep]` table whose every key overrides
`strategy.params.<key>` across a grid of values, and the server ranks the results.

| Parameter | Type   | Required | Notes                                                                    |
| --------- | ------ | :------: | ------------------------------------------------------------------------ |
| `profile` | string |    yes   | Profile TOML with `[data]`, `[strategy]` and `[sweep]`                   |
| `script`  | string |    no    | Rhai source, injected as `[strategy.params].src`                         |
| `rank_by` | string |    no    | `sharpe` (default), `return`, `max_dd` or `equity` — applied server-side |

**Returns** `sweep` — the `SweepReport` JSON: one row per grid point, each carrying its own
`BacktestReport`, best first. Rows whose run failed always sort last, so the head of the list is
always a real result.

> Sweep fast over 5, 10, 20 and slow over 50, 100 and rank by Sharpe.

## `run_walk_forward` [#run_walk_forward]

Run an anchored out-of-sample walk-forward. The split count rides in the profile's
`[walkforward]` table (`n_splits`), not in an argument.

| Parameter | Type   | Required | Notes                                                        |
| --------- | ------ | :------: | ------------------------------------------------------------ |
| `profile` | string |    yes   | Profile TOML with `[data]`, `[strategy]` and `[walkforward]` |
| `script`  | string |    no    | Rhai source, injected as `[strategy.params].src`             |

**Returns** `walkforward` — the stitched `WalkForwardReport` JSON: the OOS windows plus
`oos_sharpe` and `wf_consistency`.

The mode is always anchored (`vike_backtest`'s `run_walkforward`). Each window runs fresh at
`engine.cash` and the out-of-sample curves are rebased onto one running equity by the
`walk_forward_strategy` stitch. It is bar-mode over a single series by construction — a tick-mode
or multi-symbol profile comes back as a clean validation error, never a silent fall back to the
first symbol.

Run this before believing a sweep. A grid search returns its best row whether or not the edge
survives out of sample; this is the tool that asks.

> Walk this strategy forward over 6 anchored splits and tell me if the edge holds out of sample.

## `list_strategies` [#list_strategies]

The compiled **native** backtest strategies the server offers — the names a profile's
`strategy.name` can resolve (`vike_backtest::harness::STRATEGIES`, served over RPC). The list comes
from the server itself, so it reflects that build rather than this page. Takes no arguments.

**Returns** `strategies`, a list of names.

Native strategies and Rhai scripts are two different routes to the same engine: this tool answers
the first, `list_templates` the second.

> Which built-in strategies can I name in a profile?

## `list_series` [#list_series]

Every stored data series the server holds, with its coverage — what a profile's `[data]` table can
actually name. Takes no arguments. It reads the datahub's `Inventory` verb, the coverage-carrying
superset of a plain series list, so an agent can pick a `from`/`to` range instead of guessing one.

**Returns** `series`, one row per series: `kind`, `venue`, `symbol`, `interval`, `first_ts`,
`last_ts` and `rows`.

> What data do we have for BTCUSDT, and over what range?


# Drive Vike Trader from Claude (/docs/ai/trader/drive-vike-from-claude)



Every response on this page is copied verbatim from two captured sessions against
`vike-cli mcp`, driven over stdio with newline-delimited JSON-RPC 2.0. A local `vike-datahub` at
`127.0.0.1:7878` served the backtest. Nothing is illustrative: where a number looks unflattering,
it is the number the run produced. The one exception is the handshake below, which is re-rendered
whenever the server's `initialize` result gains a field — that result is fixed text assembled from
constants rather than anything a run produces, so a stale capture of it is simply a wrong payload.
It is pretty-printed here and arrives on one line; the key order is not a presentation choice —
the server builds its objects with `serde_json`'s default map, so the block below is in the order
the wire has it (sorted) rather than the order the code writes the fields.

[Client setup](/docs/ai/trader/setup) has the launch entry for your client. This page is what happens
after it launches.

## The handshake [#the-handshake]

```json
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"docs-capture","version":"1"}}}
```

```json
{
  "capabilities": {
    "prompts": {},
    "resources": {},
    "tools": {}
  },
  "instructions": "This is `vike-cli`'s agent surface: ... \n\n ... Never invent a tool name, and never report an operator-side command as something you ran.",
  "protocolVersion": "2024-11-05",
  "serverInfo": {
    "name": "vike-cli",
    "version": "0.1.0"
  }
}
```

Four things the server just told the client:

* `serverInfo.name` is `vike-cli`. The MCP server is not a separate binary — it is a subcommand of
  the same CLI you use at a prompt, and the version is that crate's own.
* `capabilities` advertises `tools`, `resources` and `prompts`. No sampling to negotiate: the
  server asks the client for nothing.
* The `protocolVersion` came back echoed, because the client declared one.
* `instructions` is a paragraph the client puts in front of the model — elided here, and the only
  part of the handshake aimed at the model rather than at the client. It says this server is one
  surface of a larger system and names the commands an **operator** runs for the rest: record a
  tape with `vike-recorder`, get bars in with `vike-cli data fetch`, backtest with no server at all
  with `vike-cli backtest --local`, and see which venue keys this box holds with
  `vike-cli secrets list`. None of those is a tool, and the text says so — the point is that an
  agent asked for one of them can now name the command instead of refusing blind.

⚠ &#x2A;*The instructions grant nothing.** Nothing in that paragraph is callable, and the roster below
is unchanged by it; it is also scoped by the same `ToolAccess` that decides the roster, so a
session launched `--profile read-only` is told less than this one — no preview gate, because it has
no write tool to gate. [`vike-cli mcp`](/docs/trader/reference/cli/mcp) has the scoping rule and what
each profile's text drops.

A `notifications/initialized` follows, carries no `id`, and gets no response.

## What the server offers [#what-the-server-offers]

`tools/list` returned the whole registry in one message — 9,859 characters, because every tool
ships its full `inputSchema` alongside its description. The names, in the order they arrived:

```text
validate_strategy   discover_params    list_templates     list_indicators
run_backtest        run_sweep          run_walk_forward   list_strategies
list_series         node_snapshot      submit_order       cancel_order
modify              flatten            market_exit        mass_cancel
set_trading_state
```

Ten read-only, seven that write to a node. [Authoring](/docs/ai/trader/authoring),
[backtesting](/docs/ai/trader/backtesting) and [trading](/docs/ai/trader/trading) are the reference pages
for the three groups.

Those 9,859 characters are a real cost: they land in the model's context whether a tool is called
or not. It is why the descriptions are terse, and why `list_indicators` — whose bound set is most
of the indicator catalog — names none of that set in its own description and makes you ask.

Terseness has a price of its own, though, and the number above is a floor rather than a budget: two
descriptions have been deliberately lengthened since this capture, each paid for by a measured
mistake. `discover_params` read as a tool for inspecting somebody else's script, so an agent that
had just written one answered "which parameters can I tune" from authorship instead of calling it;
`set_trading_state` said only "the kill switch", and an agent reached for it to put a venue live.
Both now say what the tool is *not* — the change is in `tools_spec`
(`crates/vike-cli/src/cmd/mcp.rs`), and it is a straight trade of context bytes for a failure that
had already happened.

## Starting from a template [#starting-from-a-template]

```json
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_templates","arguments":{}}}
```

Three starters came back, each a row of two fields — a name and its source:

* SMA cross
* RSI reversion
* Donchian breakout

The first, verbatim:

```rust
let fast = param("fast", 5.0);
let slow = param("slow", 20.0);
fn on_bar() {
    let f = sma(fast.to_int()); let s = sma(slow.to_int());
    if s.is_nan() { return; }
    let target = if f > s { 1.0 } else { -1.0 };
    let delta = target - position();
    if abs(delta) > 1e-12 { market(if delta > 0.0 { 1 } else { -1 }, abs(delta)); }
}
```

The third template ships a comment worth more than the strategy it belongs to. It uses an SMA as a
symmetric proxy, and says why:

> `donchian` is NOT bound: it is multi-output (upper/mid/lower) and the bridge binds single-output
> indicators only, so `donchian(len)` is a function-not-found at the first call rather than a
> silent upper-band read.

That is the failure mode the offline tools exist to catch. Rhai resolves a function name when the
line runs, so a script naming an unbound indicator compiles perfectly and then fails on every
single bar. See [list\_templates](/docs/ai/trader/tools/list_templates).

## The script this session wrote [#the-script-this-session-wrote]

```rust
// quiet_breakout — buy a breakout, but only out of a quiet bar.
//
// Two user indicators do the work: breakout_level for the level the bar has to clear, and
// range_pct to insist the bar that clears it is not already a wide, over-extended one.
let lookback = param("lookback", 48.0);
let calm = param("calm", 3.0);
let qty = param("qty", 0.05);

fn on_bar() {
    // Read both every bar, before any branch — an indicator only advances when it is called.
    let level = breakout_level(lookback.to_int());
    let rng = range_pct();
    if level.is_nan() || rng.is_nan() { return; }

    if close() > level && rng < calm && position() <= 0.0 { market(1, qty); }
    if close() < level * 0.97 && position() > 0.0 { market(-1, position()); }
}
```

Passed to `validate_strategy` — the wire form carries it as a JSON string with escaped newlines,
one message per line — the answer was two words long:

```json
{
  "ok": true
}
```

`ok: true` is a narrower claim than it looks. The check runs through
`vike_script::discover_params`, the broker-free compile path: it compiles the script and runs its
top level *exactly once*, the same error surface as mounting the strategy. So the three `param()`
lines ran. The body of `fn on_bar()` did not.

`breakout_level` and `range_pct` are not built-ins. They are the author's own files, loaded from
`user_data/indicators/` and installed process-wide before any strategy compiles
(`install_user_indicators` in `crates/vike-script/src/engine.rs`). No compile check can vouch for
them; the backtest further down is what actually proved those two calls resolve.

One thing to carry into that backtest: the install that binds a name is the install on the box that
*compiles* the script. `validate_strategy` compiles in the CLI, so the CLI's set answers. A
`run_backtest` compiles on the datahub, so the *server's* set answers — `install_user_indicators` in
`crates/vike-datahub/src/datahub_cli.rs` reads that box's own `user_data/indicators/`, and its doc
says a client script binds to whatever the server holds there. Here the two agreed because the
datahub was the same machine.
[Writing an indicator](/docs/trader/scripting/writing-an-indicator) and
[loading indicators](/docs/trader/scripting/loading-indicators) cover that half.

## The knobs [#the-knobs]

`discover_params` on the same script:

```json
{
  "params": [
    {
      "default": 48.0,
      "name": "lookback"
    },
    {
      "default": 3.0,
      "name": "calm"
    },
    {
      "default": 0.05,
      "name": "qty"
    }
  ]
}
```

Those three names are exactly what a profile's `[strategy.params]` or a `[sweep]` table may
override. Same compile path as the tool above, opposite disposition on failure: a broken script is
an `ok: false` *answer* from `validate_strategy` and a tool *error* from `discover_params`,
because there are no parameters left to report.

## What a compile error looks like [#what-a-compile-error-looks-like]

A second session opened by handing over a deliberately broken script:

```json
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"validate_strategy","arguments":{"script":"fn on_bar( { market(1 0.5) }"}}}
```

```json
{
  "error": "Expecting ')' to close the parameters list of function 'on_bar' (line 1, position 12)",
  "ok": false
}
```

That is the Rhai compiler's own message, passed through with the position it reported. It arrives
as an ordinary successful result — not a JSON-RPC error, not an `isError` result — so an agent
reads it, fixes the script and calls again. That loop is what
[validate\_strategy](/docs/ai/trader/tools/validate_strategy) is for.

## Asking about one indicator [#asking-about-one-indicator]

```json
{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"list_indicators","arguments":{"name":"rsi"}}}
```

```json
{
  "count": 1,
  "indicators": [
    {
      "accessors": [],
      "bare_call": true,
      "category": "Momentum",
      "name": "rsi",
      "outputs": [
        "rsi"
      ],
      "params": [
        {
          "default": 14.0,
          "max": 1000.0,
          "min": 1.0,
          "name": "length"
        }
      ],
      "pretty": "RSI"
    }
  ]
}
```

Called with no arguments the tool returns the compact roster — name and category only — and detail
is pulled one `name` or one `category` at a time. The tiering is deliberate: the bound set was
three names when the tool was written and is nearly the whole catalog now.

The reason the tool exists at all is that the host-bound set is **not** the registry.
`crates/vike-cli/src/cmd/indicators.rs`'s `find_bound` separates the two ways a name can miss — a
typo, which gets "no indicator named `x`", and a real registry entry the host holds back, which
gets the host's own reason for holding it back. Different mistakes, different repairs.

## The call that failed [#the-call-that-failed]

Now the honest part of the session. The agent had a script, had its knobs, and asked for a
backtest by assembling arguments that *looked* like a backtest. The wire form was one line; the
script argument is elided here for length:

```json
{"name":"run_backtest","arguments":{
  "script":   "// quiet_breakout …",
  "venue":    "binance",
  "symbol":   "BTCUSDT",
  "interval": "1h",
  "from":     "2025-01-01T00",
  "to":       "2026-01-01T00",
  "cash":     10000,
  "fee_rate": 0.001,
  "params":   {"lookback":48,"calm":3,"qty":0.05}
}}
```

Every one of those keys is plausible. Only `script` is real: the other eight are ignored, and the
call failed on the one argument the agent never sent. The answer:

```text
run_backtest requires a `profile` string argument
```

The real `inputSchema`, which had been sitting in the `tools/list` response the whole time:

```json
{
  "properties": {
    "profile": {
      "type": "string"
    },
    "script": {
      "type": "string"
    }
  },
  "required": [
    "profile"
  ],
  "type": "object"
}
```

Two strings. Venue, symbol, interval, range, cash, fees and params all live *inside* the profile
TOML, because the server's own `BacktestProfile::from_toml_str` is what reads them. With no `script`
argument the profile crosses the wire byte for byte. With one, the client parses the TOML once to
inject the script and re-serializes it — but it still reads none of those fields, and the server
remains the only thing that interprets the profile.

<Callout type="info" title="Leave this failure in your transcript">
  Guessing an argument list is what any agent does when it pattern-matches a tool name instead of
  reading its schema. What makes it cheap here is the answer: one line, naming the missing argument,
  so the retry is obvious and costs one round trip. A tool error worth shipping is one an agent can
  act on without a human.
</Callout>

## The corrected call [#the-corrected-call]

Same tool, same script, arguments rebuilt around the profile:

```toml
name = "quiet_breakout — BTCUSDT 1h"

[data]
kind = "bar"
interval = "1h"
venue = "binance"
symbols = ["BTCUSDT"]
from = "2025-01-01T00"
to = "2026-01-01T00"

[engine]
cash = 10000.0
fee_rate = 0.001
slippage = 0.0

[strategy]
name = "rhai"

[strategy.params]
lookback = 48.0
calm = 3.0
qty = 0.05
```

The script rides in the optional second argument and is injected as `[strategy.params].src`. Note
`strategy.name = "rhai"` — that is the one arm which reads an injected `src`, and getting it wrong
runs a built-in strategy while carrying the script along as an unread parameter.
[Run profiles](/docs/trader/backtesting/run-profiles) documents the file.

The report, verbatim:

```json
{
  "report": {
    "final_equity": 8334.568427500006,
    "funding_paid": 0.0,
    "max_drawdown": 0.1839635835571801,
    "n_trades": 48,
    "name": "quiet_breakout — BTCUSDT 1h",
    "per_symbol_pnl": [
      [
        "BTCUSDT",
        -1180.6035000000015
      ]
    ],
    "profit_factor": 0.687335413608655,
    "sharpe": -1.0475904521415624,
    "total_return": -0.16654315724999946,
    "win_rate": 0.3125
  }
}
```

Forty-eight trades, a win rate of 0.3125, a profit factor below one, a Sharpe of −1.05 and a total
return of −0.167. A losing run, reported plainly. The profile *requested* a year of hourly bars; the
report carries no bar count or coverage field, so how much of that year the store actually held is
not something this capture states.
[Read a report](/docs/trader/guides/read-a-report) walks the numbers;
[the report](/docs/trader/analytics/report) defines each field.

## Why the agent's report is checkable [#why-the-agents-report-is-checkable]

The report above is not an MCP-flavoured summary of a run. It is the run.

* One function does the script injection — `inject_script_src` in
  `crates/vike-cli/src/cmd/backtest.rs` — and the `backtest` subcommand and this tool both reach
  it. So do `run_sweep` and `run_walk_forward`, through `crates/vike-cli/src/cmd/mcp.rs`'s shared
  `profile_from_args`.
* Both then ship the resulting TOML text verbatim to `DatahubClient::run_backtest`.
* The server parses it once with `BacktestProfile::from_toml_str` and returns the report JSON,
  which the tool wraps under `report` and hands back untouched.

So `vike-cli backtest` with the same profile and script, against the same `vike-datahub`, returns
the same numbers. The agent surface performs no arithmetic of its own, and that is the property
which makes it trustworthy: anything an agent quotes back to you can be reproduced at a prompt, by
you, without the agent.

## The half this session does not show [#the-half-this-session-does-not-show]

Seven of the seventeen tools write to a node. Six of them place, change or cancel orders —
`submit_order`, `cancel_order`, `modify`, `flatten`, `market_exit` and `mass_cancel` — and the
seventh, `set_trading_state`, places no order at all: it moves the account's trading state, the kill
switch. &#x2A;*This session called none of them.** No `vike-tradehub` node was running.

That absence does not, on its own, stop a call. Called the ordinary way — without `confirm: true` —
a write tool returns its preview, and with no node configured it opens no socket; the connection is
attempted only once a call has cleared the write gate, which is where the error naming the missing
`--node` arrives.

There is therefore no captured paper `submit_order` into `flatten` pair to show here, and
fabricating one would defeat the purpose of the page. What holds for those tools regardless:

* A write tool **executes nothing** until a call carries **both** `confirm: true` **and** the
  `preview_token` that tool's own preview returned. Anything less returns a preview — the resolved
  wire command, a client-side guardrail check, the node's own dry-run when there is a node to ask,
  a note, and a fresh token — which the agent and the human watching it can both read before
  anything is sent. The token fires once, expires after 60 seconds and is bound to the command it
  previewed, so the two calls cannot be about two different orders. ⚠ Failing the gate is **not**
  an error: a `confirm: true` with no token comes back as another preview, so `will_execute` is the
  field to read, not the absence of `isError`.
* To *execute*, they need a running node named by `--node`, plus `VIKE_TRADEHUB_CONTROL_KEY`. The
  read-only `node_snapshot` needs that same `--node`, with `VIKE_TRADEHUB_OBSERVE_KEY` in place of
  the control key — and unlike a preview, it has nothing to answer with until the node is there.
* Nothing an MCP tool does can arm a venue. A venue with no credentials mounts as paper, and the
  per-venue ceiling `policy.venues.<venue>` defaults to `paper` and can only ever refuse.

Read [submit\_order](/docs/ai/trader/tools/submit_order) and [flatten](/docs/ai/trader/tools/flatten) for the
argument shapes, and [trading](/docs/ai/trader/trading) for the preview gate and how outcomes are
reported.

## Next [#next]

* [Connect an agent](/docs/trader/guides/connect-an-agent) — the same loop as a narrative, from zero.
* [Authoring](/docs/ai/trader/authoring) — the four offline tools in full.
* [Backtesting](/docs/ai/trader/backtesting) — sweeps and walk-forwards, which take the same profile.
* [Client setup](/docs/ai/trader/setup) — the launch entry, per client.


# Trader MCP server (/docs/ai/trader)



`vike-cli mcp` is a local [Model Context Protocol](https://modelcontextprotocol.io/) server that
exposes the Vike trading platform as 17 tools. It is a binary on your own machine speaking
newline-delimited JSON-RPC 2.0 over stdio — your MCP client launches it as a subprocess, the same
way it would any other local server.

Ten tools are read-only: compile a Rhai strategy, discover its knobs and the indicators it may
call, run backtests, sweeps and walk-forwards against a `vike-datahub` server, and read a running
`vike-tradehub` node's live state. Seven write to that node: six place, change or cancel orders
and the seventh sets its trading state. Each one previews first, and the preview is not a
convention it can skip: a write tool executes only against a `preview_token` this server issued —
unexpired, and bound to the same command — so a first-and-only call returns the command it *would*
send, plus the token that would confirm it.

## Who this is for [#who-this-is-for]

Anyone running the Vike trading platform who would rather describe a strategy than write one, and
who wants the loop — author, compile, backtest, sweep, read the OOS windows, adjust — to happen
in a conversation instead of across six terminal invocations. [Connect an
agent](/docs/trader/guides/connect-an-agent) is the narrative walkthrough; this page and its three
siblings are the reference.

**No Vike account is involved.** Nothing here contacts `vike.io`; the server talks only to
services you run, and the credentials it uses are the HMAC keys of your own trading daemon. If you
do not have the platform yet, [Install with Docker](/docs/trader/getting-started/install-docker) is the
one-container route and [Quickstart: first backtest](/docs/trader/getting-started/quickstart-backtest)
gets a backtest running with zero credentials.

## Connect [#connect]

| Property        | Value                                                                                                                                            |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Command         | `vike-cli mcp [--addr <host:port>] [--node <host:port>] [--profile <ring>] [--deny-tool <name>]… [--trace]`                                      |
| Transport       | stdio, newline-delimited JSON-RPC 2.0 — hand-rolled over `serde_json`, no MCP SDK                                                                |
| Server identity | `serverInfo.name` = `vike-cli`, version = the version of the binary you installed                                                                |
| MCP version     | the client's `protocolVersion`, echoed back; `2024-11-05` when the client declares none                                                          |
| Capabilities    | `tools`, `resources`, `prompts`                                                                                                                  |
| Methods         | `initialize`, `notifications/initialized`, `ping`, `tools/list`, `tools/call`, `resources/list`, `resources/read`, `prompts/list`, `prompts/get` |
| Guidance        | an `instructions` string in the `initialize` result — see below                                                                                  |

Any other method carrying an `id` is a `-32601`; a notification naming one gets no response line at
all, because there is no id to answer. An unparsable line is a `-32700` that answers rather than
killing the session. `tools/list` returns the registry in one response — every tool this server's
scope admits, with no pagination and no cursor.

Every successful tool result carries the same shape: the payload as pretty-printed JSON in one
`text` content block, plus the same value as `structuredContent`. A tool *failure* is an ordinary
result with `isError: true` and the message as text — not a JSON-RPC error — so the agent reads it
and retries. Even a tool that crashes internally arrives that way: `Server::handle`
(`crates/vike-cli/src/cmd/mcp.rs`) wraps every tool call in `catch_unwind`, so a panic comes back
as a tool error rather than taking the session down with it.

**[Client setup](/docs/ai/trader/setup)** has the exact entry per client — Claude Desktop, Claude Code,
Cursor, Gemini CLI, VS Code, Codex CLI, Amazon Q Developer CLI and Windsurf — plus the raw stdio
protocol for scripting or for diagnosing a client that will not launch the binary.

## What the server says about itself [#what-the-server-says-about-itself]

The `initialize` result carries an `instructions` string, and a client shows it to the model as
guidance about this server. It is the one channel that reaches the model **unasked** — in front of
the session, before any call — and it carries a fact a tool description cannot: a description
describes *its* tool, so "there is no tool for this, and the command is `vike-recorder`" — a fact
about the **absence** of a tool — has nowhere in a roster to live. (The prompts below say a related
thing, but only to a client that asks for one.)
Its content is one line saying this server is part of a larger system, one line each for the things
that live outside it — recording a tape, getting bars into the history store, backtesting with no
data service, and which venue keys the box holds — each naming the command an **operator** types,
and two rules: invent no tool name, and never report an operator-side command as something you ran.

⚠ &#x2A;*It is guidance, not capability.** Nothing in that text is callable and no gate on this page
moves because of it; an agent gains only the ability to say what an operator should run when the
answer is that no tool here does it. It is also &#x2A;*profile-scoped by the same `ToolAccess`** as the
roster — `read-only` sends no preview-gate sentence, `offline` also drops the one naming
`list_series` — because prose that names a withheld tool advertises a withheld tool.
[`vike-cli mcp`](/docs/trader/reference/cli/mcp#what-initialize-tells-the-model) is the reference, and
[Raw JSON-RPC](/docs/ai/trader/setup/raw-http#the-handshake) shows where the field sits in the response.

## Two flags decide what the tools can reach [#two-flags-decide-what-the-tools-can-reach]

| Flag     | Default          | What it reaches                                                                         |
| -------- | ---------------- | --------------------------------------------------------------------------------------- |
| `--addr` | `127.0.0.1:7878` | the `vike-datahub` server the backtest and inventory tools run against                  |
| `--node` | *none*           | the running `vike-tradehub` node the snapshot and order-write tools observe and control |

`--node` has no default on purpose. Without it the nine authoring and backtesting tools work
exactly as they do with it, and `node_snapshot` returns a clean error naming the flag: the check
runs before any socket is opened, so you get an immediate answer rather than a connection timeout.
A write tool is quieter about it — a call that fails the two-call gate returns a preview whatever
the flag says, and even a *confirming* one only reaches the connection error after its
`preview_token` has been accepted. &#x2A;*So no preview is evidence the flag arrived; a node snapshot
is.**

## Two more decide which tools exist at all [#two-more-decide-which-tools-exist-at-all]

The preview gate makes a write take two calls. `--profile` answers the prior question — whether this
server offers the write tools in the first place — and only the operator can answer it, in the MCP
client's launch command.

| Profile                      | Serves | Withheld                                                                                                     |
| ---------------------------- | ------ | ------------------------------------------------------------------------------------------------------------ |
| `full&#x60; &#x2A;(default)* | all 17 | nothing — byte-identical to the surface that shipped before the flag existed                                 |
| `read-only`                  | 10     | the seven order-write tools                                                                                  |
| `offline`                    | 4      | everything that opens a socket: the write seven, the five datahub tools, `node_snapshot`, and both resources |

`--deny-tool NAME` subtracts one more tool from whatever the profile allows, and is repeatable. An
unknown profile name or an unknown deny name is a usage error naming the valid set, never a fallback
to something wider.

**A withheld tool is absent from `tools/list` as well as refused by `tools/call`**, and the two
cannot disagree because they are one derivation: `ToolAccess::new`
(`crates/vike-cli/src/cmd/mcp.rs`) makes a single pass over the registry and produces two
complements — the advertised set and its withheld complement. Each ring is a predicate over data
that already existed rather than a second roster: `read-only` is the negation of `is_write_tool`,
the same `WRITE_TOOLS` array the preview gate routes on, and `offline` is each tool's own
`openWorldHint` annotation read back, with a tool that declares nothing withheld rather than
admitted.

The two **resources** follow the same predicate, because a resource is a second way *in* to a tool's
implementation rather than a second source — `vike://node/snapshot` routes into `node_snapshot`, so
an unscoped resource list would hand back a withheld tool's answer through a URI. Neither is a
write, so `read-only` withholds neither; `offline` withholds both. The **prompts** are re-worded
instead of withheld, because a prompt executes nothing and a sheet that vanishes teaches an agent
less than one saying the tools are not served here: a session admitting no write opens every prompt
with a banner saying so, and renders no two-call instructions for tools it has just said are absent.
The `initialize` **instructions** above answer to the same predicate, but by subtraction rather than
re-wording: a scoped session is simply sent fewer clauses, losing the sentence that names whatever
it cannot reach. Either way, every channel that reaches the model is a place a withheld tool could
otherwise be advertised.

A refusal names the profile, lists what *is* served, and says plainly that only the operator can
widen it — otherwise an agent spends its next three turns hunting for the flag that turns the tool
on.

## The agent transcript [#the-agent-transcript]

`--trace` (or `--trace-dir <dir>`) appends one JSON Lines record per `tools/call`:
the tool, whether it is a write, the profile, the arguments, the verdict, and for a gated write the
preview token's identity. It is **off unless you ask for it** — no flag, no file, no directory
created. `crates/vike-cli/src/cmd/mcp_trace.rs` is the writer.

The verdict is `ok`, `preview`, `refused` or `error&#x60;, and **`refused` is the half no other record
holds**: a refusal never reaches the node's audit trail, because it was refused before a byte left
this process. `preview` is kept apart from `ok` for the same kind of reason — "the agent called
`submit_order`" and "an order left this process" are different facts.

Nothing secret is written. Argument values are redacted through the workspace's one credential-name
authority, applied both to object keys and to credential-shaped SHOUTING\_CASE identifiers inside
string values, so a `reason` quoting an API-key name has the whole value replaced. The `preview_token` **argument** is
redacted by that first rule like any other token-shaped key; what the record carries instead is its
own `token` field holding the token's **identity** — `pv-3`, the per-session counter — plus whether
this call minted it or presented it. That is a sequence rather than an authorization, which is
exactly why there is nothing there to withhold. Records land beside the change journal, under
`<project>/settings/state/agent/`, one file per month, pruned to the newest 24.

## Running it on a schedule [#running-it-on-a-schedule]

Nothing about this server requires a human in the conversation. `vike-agent-run` — a second binary,
`crates/vike-agent-eval/src/bin/vike-agent-run.rs` — stands the same server up against your own
node, hands one prompt to one model, bounds the session, and writes a record of what happened. It
is &#x2A;*read-only unless you pass `--allow-writes`**, and the ring it asked for is cross-checked
against the roster the server advertised back before the model is asked anything. Scheduling itself
is delegated outright to the operating system — systemd unit and timer templates ship, and the
timer deliberately does not replay a firing missed while the box was down, because a review of a
moment that has passed is a record about nothing. No account, no hosted agent, nothing on a Vike
machine: your box, your node, your schedule.
[Unattended runs](/docs/ai/trader/unattended) is the page.

## Node keys, and what is disabled without them [#node-keys-and-what-is-disabled-without-them]

The node tools authenticate with two HMAC keys, resolved from the **process environment first**
and then from the same credential store the daemon itself reads
(`<project>/settings/secrets.env`) — `resolve` in `crates/vike-cli/src/cmd/nodekeys.rs` is the
whole rule:

| Key                         | Grants | Used by                     | Absent means     |
| --------------------------- | ------ | --------------------------- | ---------------- |
| `VIKE_TRADEHUB_OBSERVE_KEY` | read   | `node_snapshot`             | 1 tool disabled  |
| `VIKE_TRADEHUB_CONTROL_KEY` | write  | the seven order-write tools | 7 tools disabled |

Each is resolved independently, so the two halves fail separately: an observe key with no control
key gives an agent a read-only view of the live node and no way to touch it, which is a reasonable
configuration to run on purpose. **Neither key affects the other nine tools** — authoring and
backtesting never open a node connection.

An `export` wins over the store because it is the narrower, more deliberate source — that is what
makes "point at a different node for one command" possible. Values are trimmed on both sides — the
daemon trims too — so a key with a trailing newline would otherwise fail the handshake as an opaque
`AuthDenied`. The daemon's own reader is `from_vars` in `crates/vike-tradehub-client/src/auth.rs`,
and `values_are_trimmed_to_match_the_servers_own_reader` in `nodekeys.rs` holds the two readers to
the same bytes from the same map.

A key that is in neither place produces an error naming *both* places — run `vike-cli secrets
path` to see which store this project resolves to and `vike-cli secrets list` to see whether the
key is in it (names only, never values). The two scopes are separate at the node as well as here:
an observe-scoped connection that sends a command is refused outright by the daemon, so an
observe key can never be escalated into a write. `observe_scope_command_is_denied` in
`crates/vike-tradehub/tests/control_roundtrip.rs` is that refusal under test: it authenticates as
observe against a node whose control key *is* enabled, sends a cancel, and requires the denial.

<Callout title="A GUI-launched client inherits none of your shell's exports">
  Claude Desktop, Cursor and VS Code start the server as a child of the *application*, not of your
  terminal, so an `export VIKE_TRADEHUB_CONTROL_KEY=...` in your shell profile is invisible to it.
  Put the keys in the credential store, or set them in the client's own config where it supports an
  `env` block. The store is also where the daemon reads them, so one copy serves both halves.
</Callout>

## The 17 tools [#the-17-tools]

| Tool                                         | Plane     | Reaches                       |
| -------------------------------------------- | --------- | ----------------------------- |
| [`validate_strategy`](/docs/ai/trader/authoring)  | read      | nothing — offline             |
| [`discover_params`](/docs/ai/trader/authoring)    | read      | nothing — offline             |
| [`list_templates`](/docs/ai/trader/authoring)     | read      | nothing — offline             |
| [`list_indicators`](/docs/ai/trader/authoring)    | read      | nothing — offline             |
| [`run_backtest`](/docs/ai/trader/backtesting)     | read      | datahub (`--addr`)            |
| [`run_sweep`](/docs/ai/trader/backtesting)        | read      | datahub (`--addr`)            |
| [`run_walk_forward`](/docs/ai/trader/backtesting) | read      | datahub (`--addr`)            |
| [`list_strategies`](/docs/ai/trader/backtesting)  | read      | datahub (`--addr`)            |
| [`list_series`](/docs/ai/trader/backtesting)      | read      | datahub (`--addr`)            |
| [`node_snapshot`](/docs/ai/trader/trading)        | read      | node (`--node` + observe key) |
| [`submit_order`](/docs/ai/trader/trading)         | **write** | node (`--node` + control key) |
| [`cancel_order`](/docs/ai/trader/trading)         | **write** | node (`--node` + control key) |
| [`modify`](/docs/ai/trader/trading)               | **write** | node (`--node` + control key) |
| [`flatten`](/docs/ai/trader/trading)              | **write** | node (`--node` + control key) |
| [`market_exit`](/docs/ai/trader/trading)          | **write** | node (`--node` + control key) |
| [`mass_cancel`](/docs/ai/trader/trading)          | **write** | node (`--node` + control key) |
| [`set_trading_state`](/docs/ai/trader/trading)    | **write** | node (`--node` + control key) |

<Cards>
  <Card title="Authoring — 4 tools" href="/docs/ai/trader/authoring" description="Compile a Rhai strategy, list its param() knobs, read the starter templates and the host-bound indicator roster. All offline." />

  <Card title="Backtesting — 5 tools" href="/docs/ai/trader/backtesting" description="Backtest, parameter sweep and anchored walk-forward on the datahub, plus the strategy roster and the stored-series inventory." />

  <Card title="Live node — 8 tools" href="/docs/ai/trader/trading" description="One read tool for the node's live state, and the seven order-write verbs behind the mandatory preview gate." />
</Cards>

## Read or write [#read-or-write]

The split is exactly ten and seven, and it is machine-pinned rather than conventional: every
read-only tool carries `readOnlyHint: true` and every write tool carries `destructiveHint: true`
in `tools/list`, and `tools_list_has_read_and_write_tools_with_correct_hints`
(`crates/vike-cli/src/cmd/mcp.rs`) walks every advertised tool and fails if one falls on the wrong
side — it also requires each write tool's description to mention `confirm`. The seven write tools
are exactly the write verbs of the human `trade` REPL, and both surfaces build their wire commands
through one construction site (`Verb::to_wire_command` in `crates/vike-cli/src/cmd/verbs.rs`, which
the tools reach through `wire_command_for` — JSON arguments resolved into the same `Verb` the REPL
parses a typed line into), so the two cannot drift apart.

Three properties follow from that, and they are what makes handing these tools to an agent
defensible:

* **A write executes only against a `preview_token`.** `confirm: true` is one half of the gate and
  the token this tool's own preview returned is the other; either one missing returns a preview —
  the resolved wire command, a client-side guardrail check, the node's own dry-run when there is a
  node to ask, the rationale that would be recorded, and a fresh token. The token fires once,
  expires after 60 seconds, and is bound to the command it previewed, so a preview of one order
  cannot confirm another.
* **The client never enforces.** The preview's guardrail is advisory UX. What refuses an oversized
  or too-frequent command is server-side on the node — `ControlLimits::vet` in
  `crates/vike-tradehub/src/server.rs`, a per-order notional ceiling plus a command rate limiter —
  and beneath it the execution core's `RiskGate` (`crates/vike-exec/src/risk.rs`). Nothing an agent
  sends from here can loosen either. Both names come back in the tools' own output — every preview
  and every accepted response names them as the enforcing gate.
* **Each write reports its own command's fate.** The server waits on the ticket its own send
  returned (`execute` in `crates/vike-cli/src/cmd/mcp.rs`), so `accepted` / a named refusal /
  `unknown` always describes the command just issued, never a neighbouring one.

<Callout type="warn" title="Failing the gate is silent — read `will_execute`">
  Every way of failing this gate produces a **preview**, not an error: a missing `preview_token`, a
  `confirm` that is the string `"true"` rather than the JSON boolean (or `1`, or `"yes"`), or both.
  Nothing is sent, which is the safe outcome, but nothing says so either — an agent that believes it
  confirmed and reads back `will_execute: false` has not. Only a token that is unknown, already used,
  expired or bound to a different command comes back flagged.
</Callout>

The mechanics — the preview payload field by field, what the node's two limits actually reach,
client-order-id handling, and what `unknown` obliges a caller to do — are on
[Live node](/docs/ai/trader/trading).


# Live node (/docs/ai/trader/trading)



Eight tools that need `--node <host:port>` and a key. One reads the node's live state
(`node_snapshot`, observe key); the other seven write to it (control key) — six place, change or
cancel orders, and `set_trading_state` moves the account's trading state. Every write tool previews
by default: a first call resolves the command, shows it, and sends nothing. Executing takes a
second call carrying **both** `confirm: true` **and** the `preview_token` that first call returned
— anything less is another preview.

Everything on this page travels to the node over a wire that is authenticated but **not encrypted**,
and the HMAC covers the connection rather than each frame — so orders, positions and symbols are
readable by anyone who can read the traffic, and a remote node belongs behind an ssh tunnel or a
VPN. [Client setup](/docs/ai/trader/setup) states the limit in full;
[Remote node](/docs/ai/trader/setup/remote-node) is the tunnel recipe.

The seven are the full write-verb roster of the human `trade` REPL, and both surfaces build their
commands at one site — `crates/vike-cli/src/cmd/verbs.rs`'s `Verb::to_wire_command`, which the MCP
tools reach through `wire_command_for`: JSON arguments in, the same wire command the REPL would
build out. An agent and an operator are issuing literally the same commands.

Nothing holds the count at seven at build time. What holds it is a unit test over the advertised
tool list — `tools_list_has_read_and_write_tools_with_correct_hints` in
`crates/vike-cli/src/cmd/mcp.rs` — which requires every tool outside its seven-name roster to carry
`readOnlyHint`. An eighth write verb turns that test red until somebody widens the roster
deliberately.

<Callout title="A session can be given none of the seven">
  The gate below is what a write costs when the tools are served. Whether they are served at all is
  the operator's call, at launch: `vike-cli mcp --profile read-only` serves the ten read tools and
  withholds all seven of these, which are then &#x2A;*absent from `tools/list`** as well as refused by
  `tools/call` — `ToolAccess::new` (`crates/vike-cli/src/cmd/mcp.rs`) derives the advertised roster
  and the routing gate from one pass, so they cannot disagree. `--deny-tool NAME` withholds one more,
  repeatably; `--profile offline` leaves only the four authoring tools and withholds both resources
  too, since each routes into a tool that opens a socket. The prompts stay, re-worded: a session with
  no admitted write opens each one with a banner saying so instead of teaching a two-call procedure
  whose first call would be a refusal. Nothing an agent sends can widen this, and the refusal says so.
  [Client setup](/docs/ai/trader/setup#the-command-and-its-flags) has the config entry.
</Callout>

## `node_snapshot` [#node_snapshot]

The running node's live state: open orders, positions, per-venue equity and recent events. Takes
no arguments; needs `--node` and `VIKE_TRADEHUB_OBSERVE_KEY`.

**Returns** the node's snapshot frame — `WireSnapshot`, in
`crates/vike-tradehub-client/src/wire.rs` — serialized as-is, so the response's field set is that
struct's.

The observe connection is opened lazily and kept open — it stays subscribed so the node keeps
pushing frames. A freshly-subscribed connection answers with an empty placeholder (`seq` 0) until
the first coalesced frame lands, so the tool waits up to about two seconds for a real one before
returning.

This is also the tool that settles an ambiguous write. See [Outcomes](#outcomes).

> Show me the node snapshot — what is open and where is the equity?

## How a write call works [#how-a-write-call-works]

Two calls, deliberately — and the second one carries **two** things, not one.

**Call one — the preview.** The server builds the wire command from your arguments, mints a client
order id if one is needed, asks the node what it would do with that command, and returns the answer
having sent nothing. The payload itself is assembled by `preview_of` in
`crates/vike-cli/src/cmd/mcp.rs`, which is pure — the node question happens before it, in
`Server::node_preview` — and it emits exactly these fields:

| Field              | What it holds                                                                                  |
| ------------------ | ---------------------------------------------------------------------------------------------- |
| `will_execute`     | always `false` on this path                                                                    |
| `tool`             | the tool name being previewed                                                                  |
| `wire_command`     | the fully resolved command, exactly as it would go on the wire                                 |
| `guardrail`        | the client-side advisory check (below)                                                         |
| `node_verdict`     | the node's own dry-run, or `null` when there was no node address or no control key to ask with |
| `verified_by_node` | whether the node was *asked*                                                                   |
| `preview_token`    | **the token that confirms this exact command**                                                 |
| `reason`           | the rationale that would be recorded — trimmed, `null` when blank or absent                    |
| `note`             | what a confirming call needs, the client-order-id rule, and where enforcement actually lives   |

**Call two — the execution.** The same arguments plus **both** `confirm: true` **and** the
`preview_token` the preview handed back. Either one missing returns another preview and sends
nothing:

```json
{ "venue": "binance", "symbol": "BTCUSDT", "side": 1, "qty": 0.01,
  "confirm": true, "preview_token": "pv-1" }
```

<Callout type="warn" title="verified_by_node means asked, not answered">
  `verified_by_node` is `true` as soon as there was a node address and a control key to ask with — it
  does **not** promise the node replied. A handshake or transport fault is not a verdict, so
  `node_verdict.checked_by` is the field that settles it: `"node"` means the node answered and
  `accepted` is its own judgement, `"none"` means it could not be reached and `reason` names the
  fault. An absent verdict must never be read as an approving one, which is also why the preview's
  `note` says in words that the guardrail is an unverified client-side estimate whenever the node was
  not asked (`a_preview_with_no_node_says_it_was_not_verified` pins that wording).
</Callout>

### What the token is, and what it is not [#what-the-token-is-and-what-it-is-not]

The token is `pv-<counter>`, minted by `PendingPreviews::issue` and bound to the command it
previewed. It is **not a secret and does not need to be** — this is a stdio server, and the only
party that can send it a request is the agent already holding both ends of the pipe, so there is no
third party to withhold it from. What it proves is that a preview *happened for this exact
command*: it encodes a sequence, not an authorization. `PendingPreviews`' own doc argues that at
length, and a counter is all the property needs.

Four rules follow, and each is enforced rather than advised:

* **It fires once.** `PendingPreviews::take` removes the entry *before* the command is executed, so
  a duplicated call finds nothing and gets `unknown or already used`. Pinned by
  `a_preview_token_fires_at_most_once`.
* **It expires after 60 seconds** — `PREVIEW_WINDOW`, the same window the Telegram surface uses —
  because a preview priced against one book must not be confirmable against a moved one. An expired
  token is consumed as it is rejected, so there is no second attempt at it either.
* **It is bound to its own command.** `same_intent` compares the whole wire command and ignores
  exactly one field, the freshly minted `client_order_id`. Confirming a *different* command with a
  live token is refused — and consumes it. Pinned by
  `a_preview_token_is_bound_to_the_command_it_previewed`.
* **It dies with the session.** The store is in-process memory, so a token from a previous
  `vike-cli mcp` run confirms nothing.

What actually reaches the venue is the **stored** command, not the one the confirming call rebuilt.
They express the same intent — that was just checked — but only the stored one carries the client
order id the preview displayed and the node dry-ran, so what is sent is exactly what was shown.

<Callout type="warn" title="confirm: true on its own is not an error — it is a preview">
  Sending `confirm: true` without a `preview_token` does **not** fail. It returns a fresh preview,
  `will_execute: false`, a new token, and nothing on the wire. An agent that treats a confirming call
  as evidence it traded — without reading `will_execute` — will believe it placed an order that does
  not exist. `confirm_alone_no_longer_executes_it_returns_a_preview` is that behaviour under test.
</Callout>

<Callout type="warn" title="`confirm` must be the JSON boolean true">
  `confirm` is read as a JSON boolean and nothing else, so the string `"true"` — and `1`, and `"yes"`
  — fall through to the preview. That failure is safe (nothing is sent), but it is silent: check
  `will_execute` in the response rather than assuming.
</Callout>

An **unknown**, **expired** or **mismatched** token is the one shape that is loud: those three are
tool errors carrying the reason, not previews. So the quiet answer always means "nothing happened",
and the noisy one always tells you why.

### The rationale [#the-rationale]

Every write tool takes an optional `reason` string — why the agent is issuing this command. It
rides *beside* the command on the wire, never inside it: `reason_from_tool_args`
(`crates/vike-cli/src/cmd/verbs.rs`) reads it separately from the arguments the command is built
from, so no `reason` you pass can change what gets sent.

It is echoed in the preview, sanitized on the node by `sanitize_reason`
(`crates/vike-tradehub/src/audit.rs`), and lands in the node's audit trail: control characters are
stripped and the text is capped at 512 characters (`MAX_REASON_CHARS`). It never reaches the order,
the core fold, the journal or a venue.

### What the node's trail cannot hold, and where it goes instead [#what-the-nodes-trail-cannot-hold-and-where-it-goes-instead]

That trail records one line per **accepted** command, which leaves out the half an operator wants
after a bad night: what the agent *tried*. A refusal never reaches it at all — it was refused before
a byte left the MCP process. `vike-cli mcp --trace` is the record that does hold it
(`crates/vike-cli/src/cmd/mcp_trace.rs`): one appended JSONL entry per tool call, carrying the tool,
the write bit, the profile, the arguments and a verdict of `ok`, `preview`, `refused` or `error` —
with `preview` kept apart from `ok`, because "the agent called `submit_order`" and "an order left
this process" are different facts. For a gated write it records the preview token's **identity** in a
field of its own — `pv-3`, the same per-session counter this page argues is a sequence and not an
authorization — plus whether this call minted or presented it. The `preview_token` *argument* is
redacted, along with every credential-shaped key and every credential-shaped SHOUTING\_CASE
identifier appearing inside a string value, so a `reason` quoting an API-key name has the whole
value replaced.
It is **off unless the flag is given** — no file, no directory — and writes under
`<project>/settings/state/agent/`, beside the change journal.

## What actually enforces [#what-actually-enforces]

The preview's `guardrail` is **advisory UX computed on your machine** — `guardrail_check` in
`crates/vike-cli/src/cmd/verbs.rs`. Only a submit has a size to check; every other verb reports
`within_limits: true` with a note saying there was nothing to size. Its two caps come from
different places: `max_qty` from `VIKE_MAX_ORDER_QTY` (a local typo-catcher with no enforcing
counterpart anywhere) and `max_notional` from *this machine's* `policy.toml`
(`max_notional_per_order`). A market order carries no price, so its notional is `null` and cannot
be checked client-side at all.

What refuses a command is server-side, on the node, and an agent cannot reach it. The first two are
one function — `ControlLimits::vet` in `crates/vike-tradehub/src/server.rs`, which takes a rate
token before it sizes anything:

| Gate         | Where                                                              | Reach                                                                                                                                                                                                                                                                   |
| ------------ | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Rate limiter | `vet`, at the node's control edge                                  | a token is consumed on **every** command, per control connection; the rate comes from `VIKE_TRADEHUB_CONTROL_RATE`                                                                                                                                                      |
| Notional cap | `vet`'s notional half, same edge                                   | **only** order-increasing verbs carrying a price: `submit_order`, and `modify` when it names both a new qty and a new price. The ceiling is the *node's* `max_notional_per_order`, **unset by default** — a node whose `policy.toml` sets none skips this half entirely |
| Risk gate    | `RiskGate`, in the execution core (`crates/vike-exec/src/risk.rs`) | beneath both, and the gate that resolves a resting order's terms                                                                                                                                                                                                        |

So `flatten`, `mass_cancel`, `market_exit`, `cancel_order` and `set_trading_state` are rate-limited
but never size-checked — they only reduce exposure, which is the right way round.

One shape fails closed rather than passing: on a node that sets a notional ceiling, a `modify` that
names a new quantity but **no** price is refused, because the control edge holds no order registry
and cannot price the projected order — and "I cannot evaluate this ceiling" must never render as
"the ceiling passed". Re-send the modify with an explicit price. (Before that arm existed, a small
in-cap order could be modified straight past the node's one order-size ceiling.)

Nothing an MCP tool does can arm a venue, either: a venue with no credentials mounts as paper, and
the per-venue ceiling `policy.venues.<venue>` defaults to `paper` and can only ever refuse — it
lowers what credentials would otherwise allow and can never raise it. That fold is
`vike_config::VenueMode::cap` (`crates/vike-config/src/venue_mode.rs`), a minimum and never a
maximum. The [Connect an agent](/docs/trader/guides/connect-an-agent) guide states that half of the
model.

## Outcomes [#outcomes]

A confirmed write reports **its own command's** fate — the server waits for the acknowledgement of
the exact command it sent, so an answer can never describe some earlier command. It waits two
seconds — `ACK_WAIT` in `crates/vike-cli/src/cmd/mcp.rs` — which is a deadline and not a sleep: the
answer returns the instant the node's reply lands.

| What happened      | Shape                                                              | What to do                                                                                      |
| ------------------ | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| Node accepted      | result with `sent: true`, `outcome: "accepted"`, `client_order_id` | call `node_snapshot` to watch the result. An empty `client_order_id` means an account-wide verb |
| Node refused       | `isError` — `node rejected the command: <reason>`                  | read the reason; it is the node's, usually a rate or notional refusal                           |
| No answer in 2s    | result with `sent: true`, `outcome: "unknown"`                     | **may still execute.** Call `node_snapshot` **before** retrying                                 |
| Connection dropped | `isError` naming the outcome as unknown                            | **may have executed.** Call `node_snapshot` **before** retrying                                 |

<Callout type="warn" title="The dropped connection is an error string, not a structured unknown">
  The two ambiguous cases arrive in two different shapes. A timeout is a *successful* tool result
  carrying `outcome: "unknown"`; a dropped control connection is an `isError` result whose text says
  the outcome is unknown and that it may have executed. An agent that only inspects `outcome` will
  see the first and miss the second — treat both as "check the node before retrying".
</Callout>

## Client order ids [#client-order-ids]

The node refuses a remote submit with an empty `client_order_id` — proven against a running node by
`submit_with_empty_coid_is_rejected` in `crates/vike-tradehub/tests/control_roundtrip.rs`. So when
the agent omits the argument this server mints one, off the same generator and wire form the live
core uses, *before* the preview renders: `fill_client_order_id`
(`crates/vike-cli/src/cmd/verbs.rs`), the one mint on this side of the wire. The preview therefore
shows a real id.

**The id the preview showed is the id that gets sent**, and you do not have to pass it back. A
confirming call does mint a fresh one while rebuilding the command — `fill_client_order_id` mints
on every call — but that rebuilt command is only ever compared, never executed: `same_intent`
excludes the id precisely so a confirm can match, and the server then sends the **stored** command.
So the id the node dry-ran and the preview displayed is the one that reaches the venue. The
`client_order_id` in the accepted response is still the authoritative one to hold on to.

Sending the same id twice is not a "did it land" test, and not free: the node acknowledges each
send, and the core registry is coid-keyed, so the snapshot shows exactly one order
(`duplicate_coid_is_idempotent`, in that same test file — it counts snapshot rows, not venue
orders). The second submit still reaches the client, so on a paper mount two orders rest.

## `submit_order` [#submit_order]

Submit an order. Requires `--node` and the control key.

| Parameter         | Type    | Required | Notes                                                                                                            |
| ----------------- | ------- | :------: | ---------------------------------------------------------------------------------------------------------------- |
| `venue`           | string  |    yes   | Venue id                                                                                                         |
| `symbol`          | string  |    yes   | Instrument symbol                                                                                                |
| `side`            | integer |    yes   | `1` buy, `-1` sell                                                                                               |
| `qty`             | number  |    yes   | Order quantity                                                                                                   |
| `order_type`      | string  |    no    | `market` (default), `limit`, `stop`, `take_profit`                                                               |
| `price`           | number  |    no    | Limit price                                                                                                      |
| `trigger_price`   | number  |    no    | Stop / take-profit trigger                                                                                       |
| `reduce_only`     | boolean |    no    | Defaults to `false`                                                                                              |
| `client_order_id` | string  |    no    | Accepted by the builder though not advertised in the tool's schema; minted when absent                           |
| `reason`          | string  |    no    | Recorded in the node's audit trail                                                                               |
| `confirm`         | boolean |    no    | Must be the JSON boolean `true` **and** be accompanied by `preview_token` — either one missing returns a preview |
| `preview_token`   | string  |    no    | The token this tool's preview returned. Fires once, expires after 60s, bound to the command it previewed         |

A missing required field is a tool error before anything is built.

> Preview a limit buy of 0.5 BTCUSDT at 60,000 on binance.

## `cancel_order` [#cancel_order]

Cancel one resting order by client order id.

| Parameter         | Type    | Required | Notes                                                                                                            |
| ----------------- | ------- | :------: | ---------------------------------------------------------------------------------------------------------------- |
| `client_order_id` | string  |    yes   | The id to cancel                                                                                                 |
| `reason`          | string  |    no    | Recorded in the node's audit trail                                                                               |
| `confirm`         | boolean |    no    | Must be the JSON boolean `true` **and** be accompanied by `preview_token` — either one missing returns a preview |
| `preview_token`   | string  |    no    | The token this tool's preview returned. Fires once, expires after 60s, bound to the command it previewed         |

> Cancel order a1b2c3d4-7 — it is stale after the feed gap.

## `modify` [#modify]

Change one resting order's quantity and/or price. At least one of `new_qty` / `new_price` is
required; a modify that changes nothing is an authoring mistake, and the tool says so.

| Parameter         | Type    | Required | Notes                                                                                                            |
| ----------------- | ------- | :------: | ---------------------------------------------------------------------------------------------------------------- |
| `client_order_id` | string  |    yes   | The order to modify                                                                                              |
| `new_qty`         | number  |    no    | New quantity                                                                                                     |
| `new_price`       | number  |    no    | New price                                                                                                        |
| `reason`          | string  |    no    | Recorded in the node's audit trail                                                                               |
| `confirm`         | boolean |    no    | Must be the JSON boolean `true` **and** be accompanied by `preview_token` — either one missing returns a preview |
| `preview_token`   | string  |    no    | The token this tool's preview returned. Fires once, expires after 60s, bound to the command it previewed         |

Name a price whenever you name a new quantity — on a node with a notional ceiling, a qty-naming
modify with no price is refused, as described above.

> Move my resting bid to 59,800 and cut the size to 0.2.

## `flatten` [#flatten]

Close one `(venue, symbol)` net position with a reduce-only market order.

| Parameter       | Type    | Required | Notes                                                                                                            |
| --------------- | ------- | :------: | ---------------------------------------------------------------------------------------------------------------- |
| `venue`         | string  |    yes   | Venue id                                                                                                         |
| `symbol`        | string  |    yes   | Instrument symbol                                                                                                |
| `reason`        | string  |    no    | Recorded in the node's audit trail                                                                               |
| `confirm`       | boolean |    no    | Must be the JSON boolean `true` **and** be accompanied by `preview_token` — either one missing returns a preview |
| `preview_token` | string  |    no    | The token this tool's preview returned. Fires once, expires after 60s, bound to the command it previewed         |

> Flatten the BTCUSDT position on binance.

## `mass_cancel` [#mass_cancel]

Cancel every live order, optionally scoped. Omit `venue` for every venue and `symbol` for every
symbol — omitting both is the whole account, and the preview shows exactly that (both fields
`null` in the wire command).

| Parameter       | Type    | Required | Notes                                                                                                            |
| --------------- | ------- | :------: | ---------------------------------------------------------------------------------------------------------------- |
| `venue`         | string  |    no    | Omit for every venue                                                                                             |
| `symbol`        | string  |    no    | Omit for every symbol                                                                                            |
| `reason`        | string  |    no    | Recorded in the node's audit trail                                                                               |
| `confirm`       | boolean |    no    | Must be the JSON boolean `true` **and** be accompanied by `preview_token` — either one missing returns a preview |
| `preview_token` | string  |    no    | The token this tool's preview returned. Fires once, expires after 60s, bound to the command it previewed         |

> Cancel all resting orders on okx.

## `set_trading_state` [#set_trading_state]

Set the account trading state — the kill switch. It is **not** a venue arming control and cannot
move a venue off the paper simulator: that is `policy.venues.<venue>` under `[venues]` in
`<project>/settings/policy.toml`, a file a human edits on the box and that nothing on this server
can change. The tool's own description carries that sentence, because this is the one name on the
roster that reads like "go live" — [`set_trading_state`](/docs/ai/trader/tools/set_trading_state) has
the argument, and [Arm one venue](/docs/trader/guides/arm-a-venue) is where arming is actually done.

| Parameter       | Type    | Required | Notes                                                                                                            |
| --------------- | ------- | :------: | ---------------------------------------------------------------------------------------------------------------- |
| `state`         | string  |    yes   | `active`, `reducing` or `halted`; anything else is a tool error naming the three                                 |
| `reason`        | string  |    no    | Recorded in the node's audit trail                                                                               |
| `confirm`       | boolean |    no    | Must be the JSON boolean `true` **and** be accompanied by `preview_token` — either one missing returns a preview |
| `preview_token` | string  |    no    | The token this tool's preview returned. Fires once, expires after 60s, bound to the command it previewed         |

> Halt trading — I want to look at the last hour before anything else goes out.

## `market_exit` [#market_exit]

Cancel every live order and then flatten every one-way position, optionally scoped to one venue —
hedge-mode `LONG`/`SHORT` legs are skipped.

| Parameter       | Type    | Required | Notes                                                                                                            |
| --------------- | ------- | :------: | ---------------------------------------------------------------------------------------------------------------- |
| `venue`         | string  |    no    | Omit for every engine                                                                                            |
| `reason`        | string  |    no    | Recorded in the node's audit trail                                                                               |
| `confirm`       | boolean |    no    | Must be the JSON boolean `true` **and** be accompanied by `preview_token` — either one missing returns a preview |
| `preview_token` | string  |    no    | The token this tool's preview returned. Fires once, expires after 60s, bound to the command it previewed         |

<Callout type="warn" title="This is the panic button">
  `market_exit` is preview-gated like every other write tool, and its own description calls it the
  panic button. Treat it as the incident tool it is: it is the one verb that empties the book and the
  one-way positions in a single command.
</Callout>

> Market exit everything on binance, right now — reason: feed outage.


# Unattended runs (/docs/ai/trader/unattended)



`vike-agent-run` runs **one** agent session against a node *you* are running, and exits. It is the
local answer to "look at my node while I sleep": there is no account, no hosted agent, no
deployment and no control plane, and nothing runs on a Vike machine — the only thing that leaves
your box is the request to whichever model endpoint you chose.

```sh
vike-agent-run run \
  --task node-review \
  --node 127.0.0.1:7879 \
  --record-dir /srv/vike-agent-run/settings/state/agent \
  --budget 900
```

That is the whole product. The runner stands up the same [`vike-cli
mcp`](/docs/trader/reference/cli/mcp) server your MCP client would launch, hands one prompt to one
model, bounds the session, and writes down what happened
(`crates/vike-agent-eval/src/bin/vike-agent-run.rs` is the binary,
`crates/vike-agent-eval/src/unattended.rs` the session it drives).

It works against **your** node because it is pointed at it: `--node` is the address of your running
[`vike-tradehub`](/docs/trader/reference/binaries/vike-tradehub), and the node's observe and control
keys are resolved by `vike-cli` exactly as they always are — process environment first, then
`<project>/settings/secrets.env`. The runner opens no credential store of its own and holds no
venue key. `--settings-dir DIR` steers the child's project resolution when the working directory
would not answer.

<Callout type="warn" title="A review on a schedule is not an alert on a condition">
  Whatever cadence you pick, this notices things the morning after. What has to be noticed in seconds
  — a dropped venue link, a stuck order, a breached ceiling — belongs to the daemon's own kill
  switches and [dead-man's switch](/docs/trader/concepts/dead-mans-switch), and none of it is delegated
  here. Read that page before treating a nightly agent review as coverage of anything.
</Callout>

## Read-only by default, and the default is hard to lose [#read-only-by-default-and-the-default-is-hard-to-lose]

A scheduled agent that can place an order is a different product from one that can read. This is
the second unless you go out of your way, and three separate mechanisms hold it there rather than
one:

1. **There is no `--profile` flag on this binary.** The scope is a boolean — `--allow-writes`, off
   — which `crates/vike-agent-eval/src/unattended.rs`'s `profile_for` turns into the server's
   `read-only` or `full` ring. A flag that parses a *name* has a wrong-value branch, and a
   wrong-value branch that falls back instead of refusing is how a ring silently widens. A boolean
   has no unknown value.
2. **The profile is passed explicitly on every launch.** The MCP server's own default is `full` —
   deliberately, so that an absent flag there is the surface that shipped before profiles existed —
   so a runner that merely *omitted* it would arm every write tool. `mcp_argv`, in the same file,
   never omits it.
3. **The roster the server advertised back is cross-checked before the model sees it.**
   `refuse_write_tools` reads each advertised tool's own `destructiveHint` annotation and aborts —
   outcome `refused`, exit status 4, nothing driven — if a write tool is on it. An **empty** roster
   is refused the same way: a session that could do nothing would otherwise "pass" a check about
   what it was denied. Asking for a ring and *having* one are different facts, and this is what
   turns the first into the second.

Widening is one flag and it is loud: `--allow-writes` prints a banner to stderr naming the node it
is about to be able to trade on, and every record stamps the flag and the profile, so a run that
*could* have written stays distinguishable from one that could not.

The [preview gate](/docs/ai/trader/trading) is untouched underneath all of it. Even with
`--allow-writes`, a write executes only against a `preview_token` the same server minted for the
same command — so an unattended agent that decides to trade still makes two calls, and both are in
the transcript below.

## The record [#the-record]

Two halves in the one directory `--record-dir` names, and only the second is new:

| file                            | written by          | what it holds                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mcp-YYYY-MM.jsonl`             | the MCP server      | one line per `tools/call` — the tool, whether it is a write, the redacted arguments, the verdict **including every refusal**, the preview token's identity. The runner passes `--trace-dir`, so this is the same writer, caps and redaction table [`--trace`](/docs/trader/reference/cli/mcp) gives an interactive session (`crates/vike-cli/src/cmd/mcp_trace.rs`) |
| `run-<UTC stamp>-<pid>.json`    | `vike-agent-run`    | the per-run header a per-call stream cannot carry: when, which task and prompt, which driver, how many model turns and tool calls, what the agent concluded, and the outcome                                                                                                                                                                                   |
| `run-<UTC stamp>-<pid>.mcp.err` | the server's stderr | that run's server diagnostics, named as a sibling so the pairing shows in a directory listing. Not part of the record                                                                                                                                                                                                                                          |

**Every run leaves one, on every path.** `run` returns a summary and never an error precisely so
that the caller has no branch on which a session happened and nothing was written down. A per-run
document is its own file rather than a line appended to a shared one: one record is produced at the
end of one run, so opening it `create_new` makes atomicity structural instead of bought with the
lock the per-call writer needs. Nothing here ever opens an existing record for writing, rewrites
one, or deletes one.

```sh
# every run, newest last
jq -r '[.started_utc, .task, .outcome, .conclusion] | @tsv' <record-dir>/run-*.json

# only the nights something went wrong
jq -r 'select(.outcome != "ok") | [.started_utc, .outcome, .detail] | @tsv' <record-dir>/run-*.json
```

`write_tools_offered` in a record is the evidence the ring held: it is what the *server* advertised,
not what this process asked for.

<Callout title="The redaction is exactly as wide as it is stated">
  The writer is handed the model credential values this process holds and walks every string of the
  document replacing them with `<redacted>`, so a conclusion in which a model echoed its own token
  back cannot land on disk. That covers the secrets this process has. A bare high-entropy string a
  model invented is not detectable here, any more than it is in the per-call transcript — the same
  residual, in the same terms.
</Callout>

## Outcomes, and what a non-zero status means [#outcomes-and-what-a-non-zero-status-means]

| outcome         | exit | meaning                                                                           |
| --------------- | :--: | --------------------------------------------------------------------------------- |
| `ok`            |   0  | the agent answered within its budget                                              |
| `failed`        |   1  | the run could not be stood up, or the driver failed                               |
| *(usage error)* |   2  | a bad argument, or a model credential that is unset — never a silent skip         |
| `timeout`       |   3  | the wall-clock budget was reached; the session was ended and recorded             |
| `refused`       |   4  | the server advertised a roster the requested ring forbids. **Nothing was driven** |

Every non-zero status puts a `Type=oneshot` unit into the FAILED state, which is what an
`OnFailure=` notifier keys on.

**A run cannot hang.** Three bounds compose and none is this binary's invention: every JSON-RPC
request is bounded by the MCP client's response timeout, every model turn by its driver, and the
whole run by `--budget` (default 900s), checked at every tool call and re-checked when the driver
returns. The overshoot is stated rather than assumed away — the budget is checked *between* waits,
never inside one, so a run can exceed it by at most one model turn already in flight, and by zero
under `--driver claude-cli`, whose own kill the runner sets to the same instant. What cannot happen
is an unbounded wait, and what is recorded either way is a `timeout`.

## Scheduling is the operating system's job [#scheduling-is-the-operating-systems-job]

There is no cron expression in the binary, no daemon mode, no catch-up and no retry: a scheduler
here would be a second place the cadence is written down, and systemd already does missed firings,
jitter and failure notification. `deploy/vike-agent-run@.service` and
`deploy/vike-agent-run@.timer` are templates whose instance name is the task, installed the way
[the daemon's own unit](/docs/trader/getting-started/install-linux) is:

```sh
R=/your/project/root
sed "s,/srv/vike-agent-run,$R,g" deploy/vike-agent-run@.service > /tmp/u.service
grep -n /srv/vike-agent-run /tmp/u.service      # must print NOTHING
$EDITOR /tmp/u.service                          # …then set --node to your daemon's address
sudo install -Dm644 /tmp/u.service /etc/systemd/system/vike-agent-run@.service
sudo install -Dm644 deploy/vike-agent-run@.timer /etc/systemd/system/vike-agent-run@.timer
sudo systemctl daemon-reload
sudo systemctl enable --now vike-agent-run@node-review.timer
```

Read the unit's header before installing it. Three things there are not boilerplate: the write
grant is `<project>/settings/state` and must stay that narrow — anything writable by the unit must
be data, never the settings that configure the trading daemon beside it; `ExecStartPre` runs
`vike-cli config check`, so a settings tree that resolves to nothing fails the firing instead of
recording a night of refusals that look like an outage; and the sandbox was measured against Rust
binaries, which is why the shipped `ExecStart` names `--driver api` rather than taking the
binary's default implicitly.

The timer defaults to 05:40 UTC with a five-minute spread, and **omits `Persistent=`
deliberately** — the one line where it differs from every other unit in that directory. Replaying a
firing missed while the box was down would spend a model to file a record, stamped today, about a
moment that has passed. A missed review is a review that did not happen, and the honest record of
it is its absence.

cron and Windows Task Scheduler work the same way; the binary does not care what started it. The
model credential has to reach the process environment in every one of them.

## Tasks and drivers [#tasks-and-drivers]

`vike-agent-run tasks` prints the built-in prompts — `node-review` and `risk-review` today.
Deliberately few: a long list of canned prompts rots without anybody noticing, because nothing can
gate whether a prompt is still a good one. `--prompt TEXT` and `--prompt-file PATH` cover everything
else, and the record names whichever you used.

| `--driver`   | what it is                                                                                          | what it costs            |
| ------------ | --------------------------------------------------------------------------------------------------- | ------------------------ |
| `api`        | the Anthropic Messages API in an ordinary agent loop — the default, and what the shipped unit names | API credits              |
| `claude-cli` | the locally-installed Claude Code CLI in headless mode, driving the same surface                    | a subscription allowance |
| `scripted`   | a canned probe — one `node_snapshot`, then an answer. No model at all                               | nothing                  |

`--driver scripted` is a real operator tool rather than only a test fixture: scheduled, it is a
daily proof that the agent surface still stands up against your node, for no model spend.

The model credential is read from the process environment by the binary and nowhere else —
`ANTHROPIC_API_KEY` for `api`, `CLAUDE_CODE_OAUTH_TOKEN` for `claude-cli`. It is not a venue
credential and nothing looks for it in the credential store; the runner **removes both names from
the environment of the `vike-cli mcp` server it spawns**, so the token never sits inside the process
holding the node connection. An absent one is a refusal naming the variable, not a skip: a
scheduled run that quietly measured nothing and exited 0 would go unnoticed until somebody wondered
why the record directory was empty.

## What it deliberately does not do [#what-it-deliberately-does-not-do]

* **No cloud, no account, no hosted agent.** Nothing here phones anywhere except the model endpoint
  you chose.
* **No remote control.** The runner opens no listening socket. Nothing can ask it to run; it runs
  when your operating system starts it.
* **No trading by default,** and never without `--allow-writes` on the command line of whatever
  started it.
* **No grading.** There is no expected answer to "is anything wrong with my node this morning", so
  the record is evidence for you to judge, never a verdict.
* **No default for `--record-dir`.** It is required, because every default available to it would be
  a second project walk that could answer with a different project than the credentials came from.
  One line in a unit file, one argument at a prompt.

## Residuals [#residuals]

* **It is not a release asset yet.** Build and install it beside `vike-cli` — the unit fails with
  `status=203/EXEC` without both, and it finds `vike-cli` beside its own executable, one directory
  up, or wherever `--vike-cli PATH` names.
* **Nothing prunes the per-run records.** The per-call transcript prunes its monthly files; the
  per-run documents accumulate one small file per firing. A daily task is \~365 files a year — fine
  for years, and still a bound nobody armed.
* **The `claude-cli` driver has not been measured under the shipped sandbox.** That driver spawns a
  JIT runtime that reads its configuration out of your home directory, and two of the unit's
  hardening lines are hostile to it. The unit's header says which, and says so rather than shipping
  a guess.


# Downloading (/docs/data/archive/downloading)



There is one rule for the bulk archive:

<Callout type="warn" title="Download the file, then read it locally">
  Downloading a 7 GB partition is **one** HTTP request. Reading a few columns out of that same file
  over HTTP is **thousands**, because every Range request the reader issues is a separate request
  over a connection capped at 50 MB/s. Neither spends your hourly budget — archive downloads stopped
  counting against it on 2026-09-02 ([Rate limits](/docs/data/rate-limits)) — but only one of them is
  fast.
</Callout>

## Why, exactly [#why-exactly]

Every request to a gated `/archive/` path is authorised on its own: the credential is validated and
one usage row is written under the `archive_download` label. That happens **per HTTP request**.
The hourly counter is **not** checked, so no number of archive requests can rate-limit you; the row
is there so your usage view shows what you downloaded.

A Parquet reader working over HTTP fetches the footer, reads the metadata, then fetches each column
chunk of each row group it needs as its own `Range:` request. Columns multiply by row groups, and a
large partition has many of both.

**Measured on the live archive:** one **1.26 GB** partition, read remotely, produced **20,237**
requests — more than an entire hour's ceiling, for a single file. Before 2026-09-02 every one of
them counted against that ceiling, and of **573** rate-limit rejections in the platform's history,
**572** were archive downloads. That is why the archive stopped spending the budget. It is not a
reason to read remotely: each of those requests is still a round trip.

The contrast is the whole of this page:

| Approach                                     | Requests for one 1.26 GB partition |
| -------------------------------------------- | ---------------------------------- |
| `curl` the whole file, parse locally         | **1**                              |
| Point `pyarrow`/`duckdb`/`polars` at the URL | **\~20,000**                       |

A complete pull of every date and every stream in the archive is roughly **120 whole-file
requests** for hundreds of gigabytes.

## Do this [#do-this]

### curl [#curl]

```sh
# 1. The manifest is open — no key, and it lists every partition with size and row count.
curl -s https://data.vike.io/archive/manifest.json -o manifest.json

# 2. One whole file, one request.
curl -H "X-API-Key: $VIKE_API_KEY" \
     -o polymarket-trades-2026-09-01.parquet \
     "https://data.vike.io/archive/venue=polymarket/date=2026-09-01/trades.parquet"

# 3. A multi-gigabyte file, resumable. `-C -` sends one Range request to pick up where the
#    partial file stopped, so each resume is one more request -- not thousands.
curl -H "X-API-Key: $VIKE_API_KEY" -C - --retry 5 --retry-delay 10 \
     -o polymarket-book-2026-09-01.parquet \
     "https://data.vike.io/archive/venue=polymarket/date=2026-09-01/book_events.parquet"
```

Use `-o` with an explicit name, not `-O`. The last path segment is `trades.parquet` for every
date, so `-O` overwrites the previous day's file with the next one.

A bounded fan-out is fine — it is one request per file either way:

```sh
jq -r '.dates[].date' manifest.json | \
  xargs -P 4 -I{} curl -sS -H "X-API-Key: $VIKE_API_KEY" \
    -o "l1-{}.parquet" \
    "https://data.vike.io/archive/venue=polymarket/date={}/l1_quotes.parquet"
```

### Python [#python]

```python
import requests
import pyarrow.parquet as pq

KEY = "vk_..."
URL = "https://data.vike.io/archive/venue=polymarket/date=2026-09-01/trades.parquet"
LOCAL = "polymarket-trades-2026-09-01.parquet"

# Download: ONE request, streamed to disk so a multi-GB file never has to fit in memory.
with requests.get(URL, headers={"X-API-Key": KEY}, stream=True, timeout=300) as r:
    r.raise_for_status()
    with open(LOCAL, "wb") as f:
        for chunk in r.iter_content(chunk_size=1 << 20):
            f.write(chunk)

# Parse: LOCAL path, so column pruning and predicate pushdown cost nothing at all.
table = pq.read_table(LOCAL, columns=["ts", "token_id", "price", "size", "side"])
```

Verify what landed against the manifest's own `bytes` for that partition before parsing — a
truncated download is a valid-looking file until the footer read fails.

### DuckDB, polars, pandas [#duckdb-polars-pandas]

Same shape: fetch first, then open the local path.

```sql
-- Right: the files are already on disk.
SELECT token_id, count(*) FROM read_parquet('polymarket-trades-*.parquet') GROUP BY 1;
```

## Do not do this [#do-not-do-this]

```python
# WRONG. Every column chunk of every row group becomes its own Range request over the network.
table = pq.read_table("https://data.vike.io/archive/venue=polymarket/date=2026-09-01/book_events.parquet")
```

```sql
-- WRONG, for the same reason: httpfs turns one query into thousands of requests.
INSTALL httpfs; LOAD httpfs;
SELECT * FROM read_parquet('https://data.vike.io/archive/venue=polymarket/date=.../book_events.parquet');
```

The files do advertise `Accept-Ranges: bytes`, and the manifest sets `range_requests: true`. That
is there so an interrupted **download** can resume — not so a query engine can page a remote file.

## Fetch less by choosing a smaller file [#fetch-less-by-choosing-a-smaller-file]

The supported way to narrow a pull is to pick a narrower **file**, never a byte range inside a
wide one:

* **Only need the tape?** Take `trades.parquet` — around 14 MB a day, against several gigabytes of
  full L2.
* **Only need top-of-book?** Take `l1_quotes.parquet`, a few hundred megabytes a day.
* **Only need one crypto up/down family?** Use the family layout —
  `venue=polymarket/asset=btc/tenor=5m/date=YYYY-MM-DD/…` — where a day is tens to hundreds of
  megabytes instead of gigabytes. The layouts and their caveats are on
  [Bulk archive](/docs/data/archive#two-layouts).
* **Only need one day?** Partitions are per UTC day already; ask the manifest which dates exist
  rather than probing for them.

Every one of those is still one request per file.

## If you get a 429 or a 401 [#if-you-get-a-429-or-a-401]

The archive never returns a rate-limit **429**: an `/archive/` request is not checked against the
hourly counter. A missing or invalid credential is a **401**. The budget the same key's `/v1` and
MCP calls share is unaffected by downloads, and those calls are what a 429 comes from; see
[Rate limits](/docs/data/rate-limits) and [Errors](/docs/data/errors).


# Bulk archive (/docs/data/archive)



The bulk archive is research-scale Polymarket history as Parquet, served as static files from
`https://data.vike.io/archive/`. It is the whole Polymarket universe — crypto up/down, sports,
politics — not a curated subset, and it is where **full L2 book history** is published in bulk:
every book event as recorded, rather than a window or an aggregate over one.

<Callout type="warn" title="Read the download guidance before you point a tool at it">
  Archive downloads do not spend your hourly budget, but a Parquet reader pointed at an archive URL
  issues thousands of Range requests for one file, each a round trip over a bandwidth-capped
  connection. Download whole files and read them locally —
  [Downloading](/docs/data/archive/downloading) is the page that shows how.
</Callout>

## The three streams [#the-three-streams]

Every partition holds up to three files, one per stream:

| Stream                | What it is                                                                                                           |
| --------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `book_events.parquet` | **Full L2.** Book snapshots, `price_change` deltas, trade prints, tick-size changes and status markers, in sequence. |
| `trades.parquet`      | The **taker tape** alone — the trade prints, without the book.                                                       |
| `l1_quotes.parquet`   | **Derived top-of-book**: bid, ask and both sizes, one row per change.                                                |

`trades` and `l1_quotes` are derivable from `book_events` and are published separately because
they are two to three orders of magnitude smaller. If top-of-book is all you need, take
`l1_quotes` — a day of it is hundreds of megabytes against several gigabytes of full L2.

## Two layouts [#two-layouts]

The archive is Hive-partitioned, and there are two partitionings of the same data. The manifest
carries both, under `partitioning` and `family_partitioning`.

**By date** — the primary layout, one UTC day per partition, every market in it:

```
/archive/venue=polymarket/date=YYYY-MM-DD/book_events.parquet
/archive/venue=polymarket/date=YYYY-MM-DD/trades.parquet
/archive/venue=polymarket/date=YYYY-MM-DD/l1_quotes.parquet
```

**By family** — an additive alternative that groups the crypto up/down families (asset × tenor)
into their own much smaller files, so a single-family customer does not download a whole
token-sorted day:

```
/archive/venue=polymarket/asset=btc/tenor=5m/date=YYYY-MM-DD/book_events.parquet
```

As of this writing the manifest lists `asset` values `btc, eth, sol, xrp, doge, bnb, hype` and
`other`, with `tenor` values `5m, 15m, 4h` and `other&#x60;. **`asset=other/tenor=other` is the
catch-all** for every market that is not a recognised up/down family — sports, politics, one-off
events — so nothing is silently dropped by choosing this layout.

Two caveats. The manifest states the first outright: **a family with zero rows in a stream on a
given day has no file for that stream**, so a missing object is a legitimate answer, not an
error. The second is visible in the manifest's own entries: the family layout is *additive*, and
it does not currently cover every date the `date=` layout does. Enumerate `families[]` rather
than assuming a date exists in both.

**Choosing a narrower file is the supported way to fetch less data.** Reading a byte range out of
a wide one is not — see [Downloading](/docs/data/archive/downloading).

## The manifest is the authority [#the-manifest-is-the-authority]

```sh
curl -s https://data.vike.io/archive/manifest.json -o manifest.json
```

`manifest.json` needs **no key**. It is regenerated daily and carries `generated_at`, both
partitioning patterns, the inline column schemas, the auth scheme, and one entry per partition
with byte size and row count. Anything below is a snapshot; the manifest is what is true today.

As of `generated_at` **2026-09-02T00:38:00Z**:

|                                     |                                                                 |
| ----------------------------------- | --------------------------------------------------------------- |
| Coverage (`date=` layout)           | 39 consecutive UTC days, 2026-07-25 through 2026-09-01, no gaps |
| Coverage (`asset=`/`tenor=` layout) | 29 of those days, 2026-07-26 through 2026-09-01                 |
| Total size                          | \~248 GB across all streams and dates                           |
| `book_events`                       | 4.2–7.7 GB per day (median 5.8 GB); median \~364M rows/day      |
| `l1_quotes`                         | 328–669 MB per day (median 464 MB); median \~42.8M rows/day     |
| `trades`                            | 12–19 MB per day (median 14 MB); median \~1.14M rows/day        |
| Largest family file                 | `asset=other/tenor=other` book events, \~2.9 GB/day median      |
| Smallest family files               | the `4h` tenors, 1.6–11.5 MB/day median                         |

The three oldest partitions carry byte sizes but a `null` row count — treat `rows` as optional
when parsing, not as a guaranteed field.

## Column schemas [#column-schemas]

The manifest carries these inline, under `schema`. They are spelled in the source store's own type
vocabulary — `Decimal(p,s)`, `Enum8(...)`, `LowCardinality(String)` — not in Parquet's, so what
your reader hands back does not always match the spelling character for character. The two places
where that matters are noted below.

### `book_events` [#book_events]

| Column                 | Type                                                               | Notes                                                     |
| ---------------------- | ------------------------------------------------------------------ | --------------------------------------------------------- |
| `token_id`             | `String`                                                           | The outcome token. A market has one per outcome.          |
| `condition_id`         | `String`                                                           | The market. `0x`-prefixed.                                |
| `ts`                   | `Int64`                                                            | Event time, epoch **milliseconds** UTC, as published.     |
| `local_ts`             | `Int64`                                                            | Recorder receive time, epoch ms. Never earlier than `ts`. |
| `seq`                  | `UInt64`                                                           | Feed sequence number.                                     |
| `event_type`           | `Enum8('book','price_change','trade','tick_size_change','status')` |                                                           |
| `is_snapshot`          | `UInt8`                                                            | `1` on a full-book row, `0` on a delta.                   |
| `side`                 | `Enum8('none','buy','sell')`                                       |                                                           |
| `price`, `size`        | `Decimal(9,4)`, `Decimal(18,6)`                                    | The changed level, on a delta.                            |
| `best_bid`, `best_ask` | `Decimal(9,4)`                                                     | Present in the schema; use `l1_quotes` for top-of-book.   |
| `bids`, `asks`         | `String`                                                           | JSON arrays of `[price, size]` pairs.                     |
| `tick_size`            | `Decimal(9,4)`                                                     |                                                           |
| `status`               | `LowCardinality(String)`                                           | Empty on ordinary rows.                                   |

Two things about that table are easy to get wrong, both checked against the current free sample:

* **`bids`/`asks` carry only the side that changed.** On a `book` snapshot row both hold the whole
  ladder. On a `price_change` only the column matching `side` is populated and the other is an
  empty string — `side = buy` fills `bids`, `side = sell` fills `asks`. `trade` and `status` rows
  populate neither.
* **The two `Enum8` columns arrive as bytes, not strings.** They are written as the Parquet ENUM
  logical type, so `pyarrow` types them `binary` and you read `b'price_change'`, not
  `'price_change'`. Decode before comparing, or the filter silently matches nothing.

### `trades` [#trades]

`token_id`, `condition_id` (`String`), `ts`, `local_ts` (`Int64`), `seq` (`UInt64`), `price`,
`size` (`Float64`), `side` (`String` — `buy` or `sell`).

Note the type differences from `book_events`: `trades` carries `price`/`size` as `Float64` and
`side` as a plain `String` — not a `Decimal` and an `Enum8` — so the decoding note above does not
apply here. `seq` is `0` on every row of the current sample; order on `ts`, not on `seq`. Do not
assume one schema across streams.

### `l1_quotes` [#l1_quotes]

`token_id`, `condition_id` (`String`), `ts`, `local_ts` (`Int64`), `bid`, `ask` (`Decimal(9,4)`),
`bid_size`, `ask_size` (`Decimal(18,6)`).

### Two properties worth relying on [#two-properties-worth-relying-on]

**Files are token-sorted.** Rows for one `token_id` are contiguous and ascend by `ts` within that
run. That is what makes the family layout worth having, and it means a single-token extraction is
a contiguous scan once the file is local.

**Recorder gaps are marked, not hidden.** `status` carries `gap_start` and `live_resume` markers
where the recorder lost and regained the feed. Filter on them before treating a stretch of the
book as continuous — silence in a full-L2 stream is otherwise indistinguishable from a quiet
market.

## Free samples [#free-samples]

`/archive/samples/` needs **no key** and is a real slice of the full archive, not a synthetic or
truncated demo: one complete crypto up/down 5-minute market — the busiest of its kind that day by
`book_events` row count — with all three streams for **both** outcome tokens across the market's
entire lifecycle, open through resolution.

```sh
curl -s -O https://data.vike.io/archive/samples/README.txt
curl -s -O https://data.vike.io/archive/samples/book_events.parquet
curl -s -O https://data.vike.io/archive/samples/trades.parquet
curl -s -O https://data.vike.io/archive/samples/l1_quotes.parquet
```

The samples are regenerated daily from a recent real day, so the market slug, `condition_id` and
sizes change; `README.txt` names the market and date of the current one. Same column schema as the
full archive, at a few megabytes rather than a few gigabytes — the right place to write and debug
a parser before you create a key.

## Authentication [#authentication]

Everything under `/archive/` except `manifest.json` and `/archive/samples/` needs a credential:

```sh
curl -H "X-API-Key: $VIKE_API_KEY" -o trades-2026-09-01.parquet \
  "https://data.vike.io/archive/venue=polymarket/date=2026-09-01/trades.parquet"
```

The manifest names the header as `X-API-Key`; the REST API's spec spells it `X-API-KEY`. HTTP
header names are case-insensitive, so these are the same header and the same key —
[the same one](/docs/data/reference#authenticate) that gates `data.vike.io/v1` and MCP. Unlike those,
an archive download does **not** spend [the hourly budget](/docs/data/rate-limits); it is recorded in
your usage view and nothing more. An unauthenticated request to a gated object is a **401**, not a
404: the path resolved, the credential did not.

Gated responses carry `Cache-Control: private, no-store`, so the CDN never caches an
authenticated file — caching one would bypass both the gate and the usage record.


# Trader changelog (/docs/changelog/trader)



Seventeen versions have shipped, from **0.1.0 on 2026-07-08** to **0.1.16 on 2026-09-02**. This
page is the user-facing record: per version, what a user of the platform gets, what changes
behaviour on an existing install, and the numbers behind a fix where a number exists.

Versioning is [SemVer](https://semver.org/), and the platform is **pre-1.0 — a patch bump may
include a breaking change**. Two of the seventeen change behaviour on a box that is already
running, and one moves a directory: [0.1.1](#011--2026-08-18) (settings, credentials and state
move into one project folder), [0.1.9](#019--2026-08-24) (credential presence stops arming a
venue) and [0.1.15](#0115--2026-08-31) (`<project>/data` becomes `<project>/market_data`). Read
those three before upgrading across them.

Each version is a git tag. The release pipeline builds every binary from that tagged commit on a
Linux runner, embeds an SBOM into each one with `cargo auditable`, and publishes a `SHA256SUMS`
manifest covering every asset — binaries, the Dukascopy sidecar jar and the pinned LightGBM tool
alike. Since 0.1.15 the container images are built *from those published assets*, verified against
that same manifest before anything is copied in, so "the image is the release" is checked rather
than assumed. [Install with Docker](/docs/trader/getting-started/install-docker) is the current install
path.

<Callout title="Where these entries come from">
  The platform's source repository is private, so there are no public release-note pages to link to.
  Each entry below was written from the project's own curated changelog and from the merged
  pull requests in each tag's span — the same two sources a maintainer would re-check. Measurements
  quoted here are taken from those records rather than restated from memory.
</Callout>

## 0.1.16 — 2026-09-02 [#0116--2026-09-02]

**The platform got a licence.** Until this version the tree carried none at all — signed trading
binaries were shipping to end users under no terms. It is now **FSL-1.1-ALv2** (`LICENSE.md`):
source-available today, with each version irrevocably becoming Apache-2.0 on the second
anniversary of its own release, and paid support and consulting explicitly permitted — the reason
it was chosen over Commons Clause, which bans exactly that.

**One executable instead of seven.** The new `vike` binary carries every headless tool —
`vike-cli`, `vike-tradehub`, `backtest`, `vike-datahub`, `vike-recorder`, `vike-study`,
`tearsheet` — dispatched by `argv[0]` (an installed symlink) or by `vike <tool>`. Measured: the
three DataFusion-linked binaries were 128 + 106 + 107 MB,
each carrying its own static copy of the same query engine; the multicall is **128 MB**, the size
of the largest tool it replaces. Every old binary name is kept as a thin shim, so an existing
`ExecStart=` or installed path still resolves.

**The container image became a channel people can actually pull.** It now carries the whole
headless product — one binary and seven symlinks, **128 MB against roughly 500** — and is pushed to
Docker Hub (`vikeio/vike-tradehub`) and GHCR (`ghcr.io/vike-io/vike-tradehub`). There is no
floating `latest`: each image is tagged with its release version alone.

`vike-cli secrets template` prints a starter credential grid — every roster venue × SIM/DEMO/LIVE ×
the credential suffixes plus that venue's attribution keys, the legacy `MAINNET` tier and the
bespoke per-venue shapes deliberately absent — with empty values, derived from the venue roster so
a new venue appears the day its bridge lands. It prints to **stdout only**; a `--out` flag was
deliberately not added, because the moment the command owns a path it can truncate a live store.

⚠ &#x2A;*FXCM still does not trade from the published image.** The ForexConnect runtime libraries are
*in* the image, but the multicall's release build never enables `fxcm`: enabling it links
`libForexConnect`, and the resulting executable dies at exec wherever that SDK is absent — which
would break every non-FXCM user of the same binary. The separate `vike-tradehub-fxcm` release
asset remains the FXCM path.

Also fixed: three of the eight binaries the image roster named had never built at all, because the
roster named a library package and a file name rather than real cargo bin targets — and every text
check agreed with it.

## 0.1.15 — 2026-08-31 [#0115--2026-08-31]

⚠ &#x2A;*The Linux desktop GUI had never actually run.** The GUI loaded every font face from a
`C:\Windows\Fonts\…` path, so off Windows the named families were never bound and the app panicked
on the title bar in frame one — while the release had been publishing a Linux GUI asset since
0.1.14. Compilation checks and the PNG-export lane could not see it: they render the chart and
Studio *examples*, not this binary. Found by running it in a container.

**Windows GUI assets.** `vike-app.exe` and `vike-app-thin.exe` are now cross-built on the Linux
release runner and published. ⚠ They are `x86_64-pc-windows-gnu`, not `-msvc` — the msvc target
needs the MSVC linker and Windows SDK, which no Linux runner has. `vike-app-thin` (Linux,
observe-only) also joined, at 51 MB against the fat build's 152 MB.

**Two container images**, `vike-tradehub` (the daemon) and `vike-thin` (the observe-only GUI), both
built from the assets the release already published and verified against its own `SHA256SUMS`.

⚠ &#x2A;*`<project>/data` is now `<project>/market_data`.** It sat beside `<project>/user_data` and the
pair read as one concept split in half. The one configuration that moves is a deployment naming no
store root — and **a store does not merge**: the old one is simply no longer read, and a run
reports zero rows rather than failing, so check where your store resolved before assuming.

**`vike-tradehub` gained the `ibkr` feature.** Before this the GUI could mount IBKR live while the
headless daemon fell through to paper **in silence** — the daemon crate had never carried the
feature the GUI forwarded.

Fixed: an absent observe key was signed with `""` and the node answered `bad mac`, so "no key"
reached the operator as "wrong key". And a `--observe` build warned that "this chart will stay
empty" while the chart filled from the node protocol — measured while it logged on repeat against
five hours of live candles.

## 0.1.14 — 2026-08-29 [#0114--2026-08-29]

⚠ &#x2A;*A limit price sitting exactly on the venue's tick grid could reach the wire a whole tick low.**
Rounding a price to `n` steps computes `n · fl(step)`; where a step's f64 image sits below its
decimal value, that product lands one ULP under the grid point and the wire quantizer's truncation
then drops a whole step — `5 · fl(1e-6)` reached the venue as `"0.000004"`. Measured against live
public instrument
grids: **477 order-placing markets carry an exposed tick** (binance spot 96, binance perp 124,
bybit linear 124, okx swap 47, aster 85, deribit 1), and across the 96 exposed binance-spot symbols
one tick is worth a **mean of 8.45 bps and a max of 51.8 bps (ATOMBTC), on about 30% of prices**.
Truncation biases every limit price toward zero: a sell gives up value and can cross into a taker
fee, a buy loses queue position. The paper exchange never truncated, so live and backtest diverged
by a full tick on exactly those markets. The quantity axis was nearly harmless — the first loss is
at `n = 5`, so at least four steps always reached the wire.

⚠ &#x2A;*The market maker quoted different prices on Windows and Linux.** Seven of nine measured rows in
`vike-mm` differed bit-for-bit between Windows/MSVC and Linux/glibc, including the
Avellaneda-Stoikov optimal half-spread and the LMSR reservation price; the two rows that agreed are
the control that makes it a finding rather than a broken harness. Cause: the platform's own `libm`
for `exp`, `ln` and `powf`. Cure: the `libm` crate at those sites, so a quote is the same number on
both boxes. The geometric order ladder had the same divergence in `ratio.powi(k)` and was converted
with it.

**The desktop GUI became a release asset** — `vike-app-fat` for Linux x86-64, with its SBOM
embedded and its line in `SHA256SUMS`. Obtaining the GUI used to mean compiling the workspace.
**Thirteen of the fourteen venues can now express a second account**, and the credential editor can
create one. Also fixed: 44,840 leaked temporary directories, and four venues whose credential dots
and forms read key names no bridge reads.

## 0.1.13 — 2026-08-25 [#0113--2026-08-25]

Two fixes, both found on a live box after the previous deploy. **A reconcile pass that changed
nothing logged anyway**, once per pass carrying alerts — about 1,440 lines a day per venue, and
wholly redundant when nothing moved. A pass that folds events still logs every time, and a venue
with nothing held stays silent exactly as before.

**Deribit's post-reconnect history replay stopped forever on the first socket close, in silence.**
The resync transport connected once and nothing re-dialled it, so a venue-side close ended the
replay of order and trade history across reconnect gaps for the life of the process, with every
error swallowed. It was the last of three never-heals sockets in that bridge; the other two were
fixed in 0.1.11. An outage is now bracketed by one warning naming the consequence and one recovery
line, and the latch re-arms — a latch that fires only once makes a broken lane look healthier the
longer it stays broken.

## 0.1.12 — 2026-08-25 [#0112--2026-08-25]

**A venue can mount several accounts.** The mount now creates one engine per *active*
account — its per-account ceiling permits it, its credentials load, the venue's arm can address an
account at all, and no symbol collision refuses it. Account selection and the Data Manager's
Effective column are one function, so the screen cannot disagree with the mount, and a
default-account box is byte-identical (measured: one engine per roster venue, an empty live-venue
set, and a ledger record with no account key at all).

⚠ Only binance, bybit, okx and deribit consume the account-aware credential loader. A labelled
account is **refused** elsewhere rather than half-supported — arming one would otherwise have built
a live client on the first account's credentials.

Also: the live journal's p99.9 tail is gone rather than reduced — **37,150 → 3,342 ns**, an 11×
improvement over interleaved medians of eight repetitions, landing where the journal-less baseline
already sat.

## 0.1.11 — 2026-08-25 [#0111--2026-08-25]

**Security — a Rhai strategy, and a user indicator, could read any file on disk.** Fixed.

⚠ &#x2A;*IG's fill lane had never worked, for any account, demo or live.** The trade stream sent
`LS_cid: "vike-trader-rust"` where Lightstreamer's client-type licensing field must carry the
TLCP-2.1.0 mandated value, and IG answered `CONERR,71 License not valid for this Client type` on
every dial since the day it was written. The market-data lane always sent the correct value, which
is why feeds worked while fills did not — and why the split read as an account-permissions problem
for weeks. Proven on the wire against the demo gateway with one login and two client ids,
everything else held constant.

**A Deribit socket closing mid-submit reported an order rejected that the venue may have
accepted.** Only a response timeout was treated as ambiguous, so a mid-request close — the common
first error on a dying socket — synthesized a terminal reject for a possibly-live order, stranding
a phantom position. Resolution is now re-dial then re-query, never re-send. Separately, a Deribit
reconcile lane died on its first socket close and never recovered: 795 identical failures in a day
while the daemon reported healthy.

**Two log floods that could hide a real event.** A permanently refused IG stream wrote an error
line every second forever — 53,160 lines and 23 MB in one day from one loop, 99.5% of that box's
entire error volume. And a held reconcile divergence re-announced itself every interval with an
unbounded alert store: 396 warnings in a day for one bybit divergence, with a genuinely new one
indistinguishable among them. A held divergence is now a **state** — announced on entering and on
clearing, with a slow backlog summary and one stored row per distinct identity.

Added: perpetual funding premium is no longer discarded, and is recorded as `kind=perp_metrics`;
and a study can be run from the Studio GUI, either tier, with one results surface.

## 0.1.10 — 2026-08-24 [#0110--2026-08-24]

Small, and both entries are consequences of watching the previous release run. **A held reconcile
divergence now reaches the log**, not only an in-memory ring: the shipped daemon's control channel
is off, so `reconcile pass folded venue=bybit events=0 alerts=2` repeated every 60 seconds for
hours with nothing at WARN or above, and no way for anyone reading logs to learn *which* two
divergences were being held. The raise path now emits a warning carrying the divergence kind, venue
and detail; the refresh path stays silent on purpose, because a divergence held for a day would
otherwise re-raise 1,440 times. The second fix is a release-blocking test flake, not a product
change.

## 0.1.9 — 2026-08-24 [#019--2026-08-24]

⚠ &#x2A;*Breaking behaviour: credential presence stops arming a venue.** Per-venue arming is now a
setting — `policy.toml`'s `[venues]` table, `paper` / `demo` / `live`, defaulting to `paper` — and
it is read *above* the credential read, so a disarmed venue loads no credential, fetches no
instrument grid and opens no socket. The ceiling can only ever refuse; a `live` line arms nothing
by itself. Measured on a live box beforehand: a daemon profile that mounted **one** venue printed
**nine** live authenticated exec sessions, aster among them — a venue with no testnet, whose keys
reach the real account.

**A box with no `[venues]` table therefore mounts everything on paper**, whatever its credential
store holds. That is loud rather than silent: the daemon warns once at startup naming the file, the
key and every venue it refused, rather than refusing to start. The GUI's Data Manager gained the
matching screen — what is live, and why not.

Also in this version: the live **change journal** records what each venue was *asked* to be and
what it *became*; Polymarket answers its own geoblock **before** the mount instead of one 403 at a
time, and a cancel batch survives to the venue so the flatten reserve's bulk arm is no longer dead
code; the REST rate gate became FIFO, so a heavy caller is no longer starved by light ones inside
quota; and the first (additive, locally built) backend container image landed, with the project
folder mounted rather than baked in.

## 0.1.8 — 2026-08-22 [#018--2026-08-22]

⚠ &#x2A;*The two runtime tools became obtainable.** A release now attaches the Dukascopy JForex sidecar
jar and the pinned LightGBM binary — with the `PROVENANCE` file vike refuses to run without —
covered by the same `SHA256SUMS` as the binaries, and they are downloaded, verified and installed
into `<project>/bin/<tool>/`. Before this, a research run hard-failed on a fresh install because
nothing shipped LightGBM, and Dukascopy worked only because a 43 MB jar was committed into the
source tree.

⚠ &#x2A;*The jar is no longer committed, so an offline clone no longer gets one.** `JFOREX_BRIDGE_JAR`
names one outright, and the provisioning script's `--rebuild` still builds one from source. Its CI
gate became a *reproducibility* gate instead: the jar is built twice from a cleaned directory and
the two must be byte-identical, which is what lets anyone re-derive a published digest from the
tag.

Fixed: the startup preflight's clock budget was a flat constant sized against six venue reads, and
the roster outgrew it — 5,973 ms needed against 5,000 available, so eight venues reported their
clock "not read". It is now derived from how many venues are actually read, sized to absorb one
dead venue and still read the rest.

## 0.1.7 — 2026-08-22 [#017--2026-08-22]

⚠ &#x2A;*The startup preflight's clock budget was being spent by credential probes.** The two legs
interleave per venue, and a credential probe is a blocking authenticated read — so one unreachable
venue sat about 20 s on a TCP connect and cost alpaca, aster and hyperliquid their clock checks,
while the log blamed "an earlier venue's clock read" and sent operators to inspect rows that were
all fast and healthy. Each probe is now measured and the deadline pushed out by its cost, so the
budget bounds the clock leg and only the clock leg.

**OKX options were never in the catalog.** The listing was fetched as a bare `instType=OPTION`,
which the venue refuses with `400`/`50015`, while okx's advertised asset classes included options
and the picker received zero. Now fetched once per underlying: **okx 2,004 → 5,162 instruments**.

**Alpaca reported a transport failure as `HTTP 401`** — answering a network condition with a
credential rotation. A token mint that answered and refused is now separated from one that was
never reached. And the GUI can now be launched with no credentials in scope, so every venue stays
paper by construction: on a populated box the obvious "just look at a chart" run could not start at
all, because a live mount refuses without an operator risk budget.

## 0.1.6 — 2026-08-19 [#016--2026-08-19]

**Five more venues joined the daemon's live-wired set** — alpaca, ctrader, oanda, deribit and ig —
each mounting a credentialed market-data lane the way binance and friends already did. Deribit,
oanda and ig also gained their first *live* market-data adapters: oanda's chunked-HTTP pricing
stream, and ig's Lightstreamer TLCP spoken raw over the shared transport stack. ⚠ IG serves no
depth, which its adapter says outright rather than reporting an empty book.

**The datahub authenticates.** It had served history reads, backtest compute over client-supplied
Rhai and — in a backfill-serve build — writes into the store, to anything that could reach the
socket. It now speaks the node handshake with scoped reads and writes; **keys absent serves exactly
as before**, so an existing single-user install is unchanged.

**Settings hot-reload for the classified-safe subset**: the console and file log levels apply on a
running daemon, every other key answers `restart_required`, and `policy.toml` is *structurally*
excluded, so no future key can make a risk ceiling hot-appliable. Runtime strategy mounts now
survive a restart — a mount is remembered as daemon state, and only an explicit unmount forgets
one. `vike-cli strategy-status` asks a running node what it is running (human table, or the wire
payload verbatim under `--json`); asking used to mean compiling a throwaway probe.

A cluster of fixes with one shape — **a capability gap was answering as data**: a history store
that cannot serve depth now refuses instead of returning an empty read, a failed Studio scan
stopped rendering as an empty store, oanda's live tier refuses instead of vanishing, and an FXCM
login that *failed* reddens its smoke test instead of being reported green.

## 0.1.5 — 2026-08-19 [#015--2026-08-19]

**Aster joins the daemon's live-wired venues** — ⚠ capability only, and the mainnet warning travels
with it: no aster testnet credentials exist, so an armed aster lane reaches the real account.

**Backends are managed from the GUI** — add, edit and delete backend records in place, with
key-name hygiene on the credential names each record points at. **Settings became writable over the
wire**, behind the control scope and a typed confirmation: the would-be file is validated with the
same loader that will read it back, edited comment-preservingly (untouched lines stay untouched
bytes) and landed atomically. `policy.toml` is special-cased — a risk ceiling is not a remote edit.

## 0.1.4 — 2026-08-18 [#014--2026-08-18]

**One daemon, N strategies, N venues.** Strategies mount and unmount at runtime off the fold, and
two new wire verbs — a read-only `StrategyStatus` and a control-scoped `UpdateParams` — let you
inspect and retune a mounted strategy without restarting the daemon.

**A third GUI mode**: observe a backend while taking venue market data directly rather than through
that backend. **Backfill-on-demand over the datahub wire** — the backend fetches a bounded kline
range once, writes it through to the store, and replies only after the served handle reads it back;
it is capability-negotiated, so a client refuses locally against a server that does not advertise
it, and remote-mode chart gaps backfill through the same path.

Reconciliation gained **EXTERNAL-tagged divergences and an opt-in hold-first policy**
(`external-quarantine`), so a foreign account's activity needs an operator claim instead of being
folded blind. Hyperliquid and aster grew **feeds-only builds**: the market-data plane compiles
without the order signer.

## 0.1.3 — 2026-08-18 [#013--2026-08-18]

**Rhai strategies mount live.** `[strategy] rhai = "<path>"` in a daemon profile compiles the
script through the same engine builder the backtest arm uses and mounts it on the same paper or
live core, with the script's audit hash logged at mount.

The GUI gained a **persisted backend registry** (records, key resolution, and the control arming
gate) and **runtime backend switching** — one active backend, total state clear on switch — with
both status surfaces naming the connected daemon and whether it is LIVE or paper. Studio moved onto
the `HistStore` trait, so it can browse a served store rather than only a local one.

## 0.1.2 — 2026-08-18 [#012--2026-08-18]

The split-plane safety trio. **`LiveLock` — one live process per venue account**, so two live
traders can no longer silently rewrite each other's positions through reconciliation. **A Windows
console-ctrl graceful stop**: Ctrl-C and window-close now run the same bounded teardown as the unix
SIGTERM arm. And **the observe snapshot names its daemon** — profile name, mounted strategy,
paper-vs-live and build identity — so a client can tell which node it is looking at.

## 0.1.1 — 2026-08-18 [#011--2026-08-18]

The largest release by a wide margin: **1,062 merged pull requests over six weeks**, and the one
that reshapes an existing install.

⚠ &#x2A;*Breaking — settings unification.** Every setting the typed settings model reads from a file,
every credential and the state the program writes for itself now live in one project-owned
directory:

```text
<project>/settings/policy.toml  config.toml  preferences.toml  flags.toml
<project>/settings/secrets.env                 every API key, every venue
<project>/settings/state/…                     program-written files
```

Credentials moved from `<repo>/.env`. Absent credentials **are** the live gate, so a leftover
`.env` used to mean every venue silently on paper with nothing in any log; an absent store with a
`.env` beside it now warns on every credential read, naming both paths — a finding, never a
refusal, because `.env` is also a legitimate systemd `EnvironmentFile`, and nothing reads, prints
or moves its contents. `<project>` is resolved at runtime by walking up for a project marker;
`VIKE_SETTINGS_DIR` names it outright and skips the walk, which is what a deployment should set.

⚠ &#x2A;*Three environment variables are refused at startup, not ignored.** `VIKE_MAX_ORDER_NOTIONAL`
and `VIKE_TRADEHUB_MAX_ORDER_NOTIONAL` became `policy.toml`'s `max_notional_per_order`, because a
ceiling any exported variable can raise is not a ceiling; `VIKE_SECRETS_PASSPHRASE` is refused
because nothing consumes it. A set, non-empty value is a hard startup failure naming the file, the
key and a paste-ready replacement line — an operator who set one believes a ceiling is armed, and a
build that quietly ignored it would trade uncapped.

**What else is in it.** Five venue bridges — **hyperliquid, aster, ibkr, alpaca and ctrader** —
taking the roster to fourteen. The headless daemon `vike-tradehub`, with an authenticated
observe/control wire and a thin `--observe` GUI client for it. The unified `vike-cli`: `backtest`,
`sweep`, `walkforward`, a human `trade` REPL, `config show` (every setting, its value, and where it
came from), and `mcp` — the agent surface. The **live reconciliation engine** behind
`VIKE_RECONCILE`, off by default. `vike-datahub`, the compute-to-data backtest server, and a Studio
that can drive it locally or remotely. An alerting engine inside the daemon, and an optional
confirm-gated Telegram control channel.

If you are upgrading an install made before this version, start the binary and read what it
prints: every leftover from the old layout is handled explicitly — silently, with a warning, with
a refusal naming the replacement, or by migrating itself — and the startup output names which.

## 0.1.0 — 2026-07-08 [#010--2026-07-08]

The first tagged release, at 389 commits. **One execution core behind a unified Strategy/Broker
seam**, so a strategy written once runs in backtest and live. **Nine venue bridges** — binance,
bybit, okx, deribit, oanda, ig, fxcm, dukascopy and polymarket — each speaking one
`ExecutionClient` contract, with live market data on the tick and L2 lanes. The **DataFusion +
Parquet history store**, with date partitioning, background compaction and retention, WAL crash
recovery and bounded-memory streaming scans. The accounting upgrade: a buying-power gate, margin
call, `order_target`, and multi-symbol, cross-venue mounts. A chart with log and percent scales,
panes and persisted workspaces. Tracing-native structured logging across the workspace.

The **error-lane closure** the venue contract still rests on landed here: no order may silently
vanish, a submit timeout re-queries rather than assuming an outcome, and post-reconnect history
replay recovers terminals and fills that landed inside a gap — across binance spot and perp, bybit,
okx, deribit and polymarket.

And the machinery that makes every later entry on this page checkable: the tag-triggered release
pipeline, a `cargo-deny` supply-chain gate, SHA-pinned CI actions with least-privilege tokens, a
pinned toolchain, and a workspace-wide `unsafe_code = "forbid"` lint.


# REST API (/docs/data/reference)



The REST base URL is:

```
https://data.vike.io
```

That is what the live OpenAPI document's own `servers` array declares, so a generated client picks
it up without configuration.

**This page is not the endpoint list.** The full endpoint reference is
[API endpoints](/docs/endpoints/data) — **68 endpoints across 6 namespaces**, one page per endpoint,
grouped by namespace. ⚠ One of those 68 is **not** on the base URL above: the WebSocket
`wss://vike.io/v1/stream` answers on `vike.io` rather than `data.vike.io`, so following the base
URL cannot reach it. It still validates the same credential and spends the same hourly counter.

What stays here is the set of conventions that hold **across** the `/v1` namespaces, so the
namespace pages do not restate them: how you authenticate, how identity and time windows are
spelled, what a failure looks like, how a call is labelled, and why a payload is byte-stable.

<Callout type="warn" title="Polymarket is the one /v1 namespace these conventions do not cover">
  `onchain` and `hyperliquid` share one request path, so no route in either can quietly diverge from
  what follows — the same auth, the same rate limiting, the same error mapping and the same usage
  metering apply to every one of them.

  `/v1/polymarket/*` is the exception. It answers on the same host, behind the same credential and
  the same hourly budget, and it carries the same edge behaviour — the same key gate, the same
  `Cache-Control` header — but none of the conventions below are guaranteed to hold there, and its
  parameter spellings differ (`from`/`to` rather than `start`/`end`, for one). Read
  [Polymarket](/docs/endpoints/data/polymarket) for its own.
</Callout>

## Authenticate [#authenticate]

Two credentials are accepted, and either one alone is enough:

```sh
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/onchain/tokens/search?q=USDC&limit=3"
```

```sh
curl -H "Authorization: Bearer $VIKE_OAUTH_TOKEN" \
  "https://data.vike.io/v1/onchain/tokens/search?q=USDC&limit=3"
```

* **API key** — `X-API-Key: vk_...`. Create and revoke keys at
  [vike.io/account](https://vike.io/account?tab=api-keys). HTTP header names are
  case-insensitive, so the `X-API-KEY` spelling in the OpenAPI spec is the same header.
* **OAuth 2.1 bearer** — `Authorization: Bearer vk_oat_...`, discovery at
  `https://vike.io/.well-known/oauth-authorization-server`.

The bearer is tried first, and a request **falls through** to the API-key header when the bearer is
invalid — including when that rejection came from cache — so a request may carry either or both,
and both reach the same account. The spec models this as a *list* of single-key requirements, which
in OpenAPI means OR, not AND.

Every call is counted against one hourly budget shared by MCP and REST; archive downloads are
authenticated with the same credential but do not spend it — see [Rate limits](/docs/data/rate-limits). Nothing under `/v1/` is reachable without a credential, the spec
and the interactive docs included: there is no exemption for a schema surface.

⚠ That gate is **header-only**. Exactly two headers can carry a credential — `Authorization` and
`X-API-KEY` — and nothing else is consulted. No cookie, no session and no `?token=` query parameter
authenticates a request to this host, so being signed in to vike.io in the same browser does
nothing here.

Key lifecycle, the OAuth discovery document and the revocation window:
[Authentication](/docs/data/authentication).

## Conventions [#conventions]

### Identity [#identity]

⚠ &#x2A;*There is no API-wide identifier.** Each namespace addresses its subject in its own vocabulary,
and the spelling is not interchangeable: `hyperliquid` takes a `coin`, `onchain` takes an
`address`, and `polymarket` takes a `token_id` — the outcome token, never the `condition_id`.

A response echoes the identity it resolved, so a client can pin what it was given rather than
re-deriving it.

### Time [#time]

Windows are **half-open** — `start` inclusive, `end` exclusive — across `onchain` and
`hyperliquid` alike: the filter is `ts >= start` and `ts < end`, so consecutive windows tile
without double-counting a boundary row. Both bounds accept ISO-8601 UTC or epoch milliseconds.
Timestamps in responses are epoch milliseconds, UTC.

⚠ Polymarket does not follow this. Its window parameters are `from`/`to` and its upper bound is
**inclusive** — see [Polymarket](/docs/endpoints/data/polymarket).

### Errors [#errors]

Branch on the status code, not the body. The mapping is deliberate: **400** for input the query
engine rejected, **401** for a bad or missing credential, **429** for the hourly limit (with
`Retry-After`), **503** for an upstream failure. A store outage is never reported as a 200 with an
empty body — a silent empty list is indistinguishable from "no data", which is how bad backfills
get built on top of an outage.

Full envelope shapes, and the 422 that comes from parameter validation before the query runs at
all: [Errors](/docs/data/errors).

### Metering [#metering]

Every call is recorded under a per-surface label, so archive downloads, REST calls and MCP calls
meter separately instead of all landing under one name. Two things produce those labels, and they
do not share one vocabulary:

* **One is derived from the request path.** `/v1/<ns>/<resource>` becomes `api_<ns>_<resource>`,
  `/archive/...` becomes `archive_download`, and `/mcp` becomes `mcp`. Only the first two path
  segments after `/v1/` are read, and an over-long segment is rejected rather than labelled — so a
  wallet address or a token id can never reach a usage row.
* **Some routes report a shorter name of their own** — `api_onchain_wallets`, `api_hl_positions`.
  `/v1/hyperliquid/positions` is `api_hl_positions` under that vocabulary and
  `api_hyperliquid_positions` under the path-derived one, so do not assume one name per endpoint
  when reading usage rows back.

**A rate-limited request is logged too**, with zero credits — a client hammering past its ceiling
would otherwise appear, in usage analytics, to have simply stopped calling. What the budget is, and
which surface stopped spending it on 2026-09-02, are on [Rate limits](/docs/data/rate-limits).

### Determinism and caching [#determinism-and-caching]

Aggregated floats in a successful payload are snapped to a fixed precision on the way out — once,
after the query has run, rather than inside each individual query. The query engine reduces a
`sum()` in an unpinned parallel order, so two executions of one byte-identical query return values
differing in their last digits; snapping is what lets a client cache, diff or content-address a
response at all.

Every gated response carries `Cache-Control: private, no-store`. The CDN in front of
`data.vike.io` must not cache an authenticated response — that would bypass both the gate and the
metering.

## The OpenAPI spec [#the-openapi-spec]

| Surface    | URL                                    |
| ---------- | -------------------------------------- |
| Spec       | `https://data.vike.io/v1/openapi.json` |
| Swagger UI | `https://data.vike.io/v1/docs`         |
| ReDoc      | `https://data.vike.io/v1/redoc`        |

All three sit under `/v1/` and behind the same key gate as the operations they describe, so a
browser cannot open Swagger UI or ReDoc without injecting a header. Fetch the spec with a client
that can set one, and read it locally:

```sh
curl -H "X-API-Key: $VIKE_API_KEY" https://data.vike.io/v1/openapi.json -o openapi.json
```

<Callout type="warn" title="The spec will not carry a code generator">
  It is generated from the `/v1` namespaces it describes, and `polymarket` is not one of them — nor
  is the WebSocket, which appears in no spec at all. What it does describe, it describes thinly — it
  declares **no response schemas at all**: `components.schemas` holds two entries and both are error
  types, so every 200 in the document is an undeclared `{}`.
  [Schema and spec](/docs/endpoints/data/schema) has the full accounting.
</Callout>

## Related surfaces [#related-surfaces]

* **[Hyperliquid OHLCV](/docs/endpoints/data/hyperliquid/ohlcv)** — price candles now have one home,
  Hyperliquid's own, read from HL's fill stream and served on the base URL above. Polymarket's
  [`/v1/polymarket/ohlcv`](/docs/endpoints/data/polymarket/ohlcv) is a different thing under the same
  word: one outcome token, priced in probability rather than currency.
* **[Polymarket REST](/docs/data/reference/polymarket)** — the hand-written reference for that
  namespace, superseded for completeness by [Polymarket](/docs/endpoints/data/polymarket).
* **[Bulk history](/docs/data/archive)** is not a REST concern. Research-scale Polymarket data is the
  Parquet archive: downloads do not spend the hourly budget, and you should fetch whole files.
* **One MCP server, two hosts.** `https://vike.io/mcp` is the canonical URL — see
  [Data tools](/docs/ai/data). `https://data.vike.io/mcp` reaches the same server with the same tools
  and the same API key; OAuth clients such as Claude Desktop should use `vike.io/mcp`.


# Polymarket REST (/docs/data/reference/polymarket)



Polymarket has its own REST surface under `/v1/polymarket/`. It answers on the same host, behind
the same API key and the same hourly budget as everything else — but it does **not** share the
conventions of the other namespaces on the [REST overview](/docs/data/reference), and that is why it is
documented by hand here rather than generated from the spec.

<Callout title="Why it is not in the OpenAPI spec">
  The spec is generated from the namespaces on the [REST overview](/docs/data/reference), and this
  namespace is not one of them — it publishes no schema of its own: no `/openapi.json`, no `/docs`.
  So every endpoint on this page is absent from the spec. The endpoints are public product;
  only the *machine description* is missing, and this page plus
  [Polymarket endpoints](/docs/endpoints/data/polymarket) is what stands in for it.
</Callout>

## One spelling [#one-spelling]

`/v1/polymarket/markets` is the only form. The older flat paths — `/v1/markets`,
`/v1/market_stats`, `/v1/ohlcv`, `/v1/orderbook`, `/v1/events` and `/v1/settlements` — were
retired on **2026-09-03** and return `404`. Add `/polymarket` after `/v1` and nothing else
changes.

## Endpoints [#endpoints]

### `GET /v1/polymarket/markets` [#get-v1polymarketmarkets]

The market directory. Returns an array; no parameter is required.

```sh
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/polymarket/markets?limit=1"
```

```json
[
  {
    "active": 1,
    "closed": 0,
    "condition_id": "0x553a941e8a11cac22eb746b6bbea0530695ee3e1b0693d80433d7b943c91cab7",
    "end_date": 1863561600000,
    "neg_risk": 1,
    "slug": "will-trump-be-impeached-before-his-term-ends",
    "tick_size": 0.01,
    "token_ids": [
      "99020283867209289889119738709824148614345922887757122199903300146152690995270",
      "93407877955114874013681720453737167910717495090774867631160491764908235156561"
    ]
  }
]
```

`token_ids` holds the two outcome tokens of a binary market, and a &#x2A;*token id — not the
`condition_id` — is what every other endpoint here takes.** `tick_size` is the venue's minimum
price increment for that market; `neg_risk` marks membership of a negative-risk set (a group of
mutually exclusive outcomes priced together).

### `GET /v1/polymarket/market_stats` [#get-v1polymarketmarket_stats]

Summary statistics for one outcome token. &#x2A;*Requires `token_id`** — without it the service answers
`400 {"error":"market_stats requires token_id"}`.

### `GET /v1/polymarket/ohlcv` [#get-v1polymarketohlcv]

Candles for one outcome token. &#x2A;*Requires `token_id`.**

<Callout type="warn">
  This is a different endpoint from
  [`/v1/hyperliquid/ohlcv`](/docs/endpoints/data/hyperliquid/ohlcv), which serves Hyperliquid's price
  candles from a different store. Same word, different data: this one is priced in probability
  (0–1), not in currency.
</Callout>

### `GET /v1/polymarket/orderbook` [#get-v1polymarketorderbook]

An order-book **snapshot** for one outcome token. &#x2A;*Requires `token_id`.** For history rather than
a snapshot, the [archive](/docs/data/archive) carries every book event, and it is the cheaper surface —
see the metering warning below.

### `GET /v1/polymarket/events` [#get-v1polymarketevents]

Settlement and lifecycle events. &#x2A;*Requires `token_id` or `token_ids`** (the plural form accepts a
comma-separated list).

### `/v1/settlements` — retired [#v1settlements--retired]

Both the bare path and the id-carrying form were retired on 2026-09-03 along with the other flat
spellings, and now return `404`.

⚠ The settlement **capability** is real, and this section previously said it was not. Only the
bare path is dead — the id-carrying form answers, and returns a populated row:
use [`GET /v1/polymarket/settlements/{condition_id}`](/docs/endpoints/data/polymarket/settlements-condition-id),
documented there with a live response, its one parameter, and the trap that on-chain settlement can
disagree with the market row's own `active`/`closed` flags.

## Metering [#metering]

Every call here spends one unit of the same hourly budget as MCP and the other `/v1` namespaces —
see [Rate limits](/docs/data/rate-limits). Archive downloads do not spend it. If you want book *history*
rather than a snapshot, download the archive partitions whole and read them locally: paging the
same history through these endpoints spends the budget, and reading the files remotely with a
Parquet client issues a request per column chunk.

## Related [#related]

* [Polymarket endpoints](/docs/endpoints/data/polymarket) — every endpoint of this namespace,
  one `###` heading each, with the parameters read off the service and the settlement row
  above documented in full.
* [MCP Polymarket tools](/docs/ai/data/polymarket) — the same data, agent-shaped: markets, market
  detail, wallets and smart money.
* [Archive](/docs/data/archive) — full L2 book events, the taker tape and derived top-of-book as bulk
  Parquet.


# Endpoint Overview (/docs/endpoints/data)



The Vike Data API is **68 endpoints across 6 namespaces**. This page carries the rules that hold
across all of them — where they live, how you authenticate, how they are metered, how they page —
and then hands off. It lists no endpoints itself; each namespace page below does that, with one
`###` heading per endpoint.

## The base URL [#the-base-url]

```
https://data.vike.io
```

That is what the live OpenAPI document's own `servers` array declares, and it is the only host that
answers the `/v1` namespaces. The same `/v1` path under `https://vike.io` returns **404** —
measured, not inferred.

<Callout type="warn" title="One endpoint is NOT on the base URL">
  One of the 68 lives on &#x2A;*`vike.io`** and is served by a **different application**. Following the
  base URL cannot reach it:

  | Endpoint               | Host            |
  | ---------------------- | --------------- |
  | `WEBSOCKET /v1/stream` | `wss://vike.io` |

  It is the sharpest edge on this reference: it is spelled `/v1/stream`, which looks like the `/v1`
  base, but `data.vike.io`'s `/v1/` prefix is served by an application with no such route. It exists
  only on `vike.io`.

  It is not a separate product. It validates the same credential and spends the same hourly counter
  as everything under `/v1`.
</Callout>

## Authentication [#authentication]

Every endpoint on this reference is credential-gated. There is no keyless tier and no query-string
form — the credential always travels in a header.

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/onchain/tokens/search?q=USDC&limit=3"
```

Two credential types are accepted, and either alone is enough:

* **API key** — `X-API-KEY: vk_...`. Header names are case-insensitive, so `X-API-Key` and
  `X-API-KEY` are the same header.
* **OAuth 2.1 bearer** — `Authorization: Bearer vk_oat_...`.

One implementation validates both credentials on every surface. It tries the bearer first and
**falls through** to the API-key header if the bearer is invalid, so a request may carry either or
both. Both reach the same account.

The exception to "credential-gated" is two archive paths served outside the gate —
`/archive/manifest.json` and `/archive/samples/`. Those are on [Archive](/docs/endpoints/data/archive).

Key creation, the OAuth discovery document, and the caching window that makes revocation take a few
seconds: [Authentication](/docs/data/authentication).

## Metering [#metering]

**One hourly counter per credential, shared by every metered surface.** MCP calls and REST calls
draw from the same budget — the usage labels separate your analytics, not your allowance. There is
one value, and it is stated once, on [Rate limits](/docs/data/rate-limits), rather than copied here
where it would rot.

Two properties worth carrying before you get there:

* **Archive downloads are authenticated and recorded but do not spend the budget** (since
  2026-09-02). Every other endpoint on this reference costs one unit per HTTP request.
* **The counter is per key, not per account.** A second API key is a legitimate way to keep a bulk
  job from starving an interactive client. OAuth works the other way round: every OAuth token you
  own shares one pooled counter.

## Errors [#errors]

Branch on the **status code**, not the body. Every `/v1` route maps errors the same way, and that
mapping is fixed: caller input the API rejected is a **400**, an upstream failure is a **503** —
deliberately never a 200 with an empty body, because a silent empty list is indistinguishable from
"no data".

The full table of status codes, the JSON envelope, and the one surface where an auth failure arrives
as HTTP 200: [Errors](/docs/data/errors).

<Callout title="422 is a real status the errors page does not list">
  Parameter bounds are declared on the route itself — a `limit` ceiling and its siblings — and
  nothing intercepts a validation failure, so an out-of-range or malformed parameter gets the
  framework's default **422**, not the 400 an engine rejection produces. This is also why the
  published spec's `components.schemas` holds `HTTPValidationError` and `ValidationError`: a
  validation failure is the only response on the whole API whose body the spec actually describes.
</Callout>

## Pagination [#pagination]

⚠ &#x2A;*There is no single convention.** Three different ones are in use, and the difference is not
cosmetic — a client written against one will silently truncate against another. Verified endpoint
by endpoint:

| Surface                                   | Pagination                                                | Field to pass back |
| ----------------------------------------- | --------------------------------------------------------- | ------------------ |
| `/v1/hyperliquid/*` — 18 of its 35 routes | keyset cursor                                             | **`nextCursor`**   |
| `/v1/onchain/*`                           | **none** — `limit` only, one page                         | —                  |
| `/v1/polymarket/*`                        | `/events` only, with its own cursor format — see its page | —                  |

**Hyperliquid pages by keyset, not offset**, for two reasons: the tables behind it hold billions of
rows, so `OFFSET n` re-reads and discards every skipped row, and a concurrent insert shifts rows
across page boundaries. The cursor is a base64url-encoded JSON object — **opaque; pass it back
verbatim**. Do not parse it, and do not construct one.

**`onchain` does not paginate at all.** The namespace declares a cursor on no route. Its routes take
a `limit` with a per-route ceiling and return one page. If you need more than the ceiling, narrow
the window — there is no second page to ask for.

**`nextCursor` is the only cursor spelling on the base URL.** Polymarket's `/events` tape pages too, but with its
own field name and its own cursor format —
[its page](/docs/endpoints/data/polymarket) states the convention. The two are not interchangeable, and a
client that assumes one field name silently stops after the first page against the other.

<Callout type="warn" title="Two cursor traps">
  **A cursor is bound to the query that produced it.** It carries that query's own mode and filters,
  and handing one to a different endpoint — or reusing it after changing `start`/`end` — is refused
  with a 400, not silently honoured. The message says which: `nextCursor belongs to a different
  endpoint`, or — when `start`/`end` moved — `nextCursor belongs to a different query mode`, telling
  you to restart pagination without a cursor. Change a filter, restart paging.

  **A non-null cursor does not mean there is more data.** The cursor is emitted whenever the page came
  back *full* — exactly `limit` rows — so a result set that divides evenly by your `limit` hands you a
  final cursor whose next fetch returns nothing. Stop when the cursor is `null` **or** the page is
  empty — not on the cursor alone.
</Callout>

## The namespaces [#the-namespaces]

| Namespace                                  | Endpoints | What it covers                                                                                                                                                                          |
| ------------------------------------------ | --------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [hyperliquid](/docs/endpoints/data/hyperliquid) |        35 | Per-wallet Hyperliquid perp analytics — wallets, builders, cohorts and segments, positions, liquidations, per-coin metrics, HL candles. Half of the whole reference.                    |
| [onchain](/docs/endpoints/data/onchain)         |        15 | Wallets, tracing, PnL and balances; token search, screening, holders and transfers; labels. Carries the API's **only non-GET route**.                                                   |
| [polymarket](/docs/endpoints/data/polymarket)   |        11 | Prediction-market directory, per-outcome probability candles, order books, event tape, settlements, archive discovery, and two trader routes (a wallet's profile, smart-money signals). |
| [archive](/docs/endpoints/data/archive)         |         3 | The bulk Parquet archive — the manifest, the free daily samples, and the gated store. Two of the three need **no credential**.                                                          |
| [schema](/docs/endpoints/data/schema)           |         3 | The live OpenAPI document, Swagger UI and ReDoc. All three under `/v1`; the bare paths 404 by design.                                                                                   |
| [stream](/docs/endpoints/data/stream)           |         1 | A credential-gated live bar WebSocket. ⚠ **Different host** (`wss://vike.io`), and invisible to the spec — OpenAPI has no WebSocket operation to emit.                                  |

Six namespaces, 68 endpoints. Two of the six are documentation buckets rather than URL prefixes:
there is no `/v1/schema/` and no `/v1/stream/` under the base URL. Those pages group surfaces that
exist; they do not name a path segment.

The counts are load-bearing, so every one of them was re-counted rather than carried over:
`hyperliquid` 35 and `onchain` 15 are the routes each `/v1` namespace declares; `archive` 3 is the
three archive paths; `schema` 3 is the OpenAPI document plus its two rendered views; `stream` 1 is
the WebSocket on `vike.io`. `polymarket` 11 is the routes it declares: nine over the recorded CLOB and two trader routes.

## What this reference can and cannot do [#what-this-reference-can-and-cannot-do]

<Callout type="warn" title="You cannot generate a client from the published spec">
  `GET https://data.vike.io/v1/openapi.json` is real and current, but it will not carry a code
  generator, for three reasons that compound:

  * **It covers 61 of the 68 endpoints.** It is the framework's own document for the application that
    serves the three `/v1` namespaces on this reference, and it sees nothing else here — not the
    WebSocket on the other host, not the file-served archive.
  * **It declares no response schemas.** No `/v1` route declares a response model, so every 200 in the
    document is an undeclared `{}`. `components.schemas` holds exactly two entries, and both are error
    types.
  * **It is behind the key gate.** The credential check covers the whole `/v1/` prefix,
    `/v1/openapi.json` included, so a prospective user cannot read the spec before holding a
    credential.

  The spec describes **parameters** well and **payloads** not at all. Where a namespace page states a
  response field, it was read from a real response; where a page does not state one, we did not have
  one to show you. That is why these pages print few example bodies.
</Callout>

So this reference is hand-written — one page per namespace, one `###` heading per endpoint. Each
heading carries the method and full path, what the endpoint returns and when you would call it, and
its parameters where the route signature determines them. Where a signature does not determine them,
the page says so rather than guessing.


# Live stream (WebSocket) (/docs/endpoints/data/stream)



One endpoint: a credential-gated WebSocket that pushes **closed** OHLCV bars for the
subscriptions you hold. Those bars are **Hyperliquid's**, read from HL's own fill stream, and
they are the only series this endpoint carries. It runs in the `vike.io` application, not the
one that serves every `/v1` namespace on `data.vike.io`.

<Callout type="warn" title="It is spelled /v1/stream but it is not on the /v1 base URL">
  The REST base URL is `https://data.vike.io&#x60;. This endpoint is &#x2A;*`wss://vike.io/v1/stream`**.
  A client that follows the documented base and connects to `wss://data.vike.io/v1/stream`
  cannot reach it: that host's `/v1/` prefix is served by an application with no such route.
  The path segment is the same word; the host is not.

  This is a known inconsistency, and it now costs you two hosts rather than one: the REST
  endpoint you backfill a gap from — [`/v1/hyperliquid/ohlcv`](/docs/endpoints/data/hyperliquid/ohlcv),
  the same series this stream polls — **is** on `data.vike.io`. Moving the stream onto
  `data.vike.io` is worth doing and has not been done; until it is, point the socket at `vike.io`
  and the backfill at `data.vike.io`.
</Callout>

<Callout type="warn" title="This page describes behaviour, not captured traffic">
  This endpoint is invisible to the OpenAPI spec — OpenAPI has no WebSocket operation to emit —
  and it cannot be confirmed by probing (see [Why you cannot probe it](#why-you-cannot-probe-it)).
  Everything below describes how the running service behaves, including the refused intervals,
  the four-field subscription key and the closed-window boundary, all of which are covered by
  tests. No frame on this page was captured from the live endpoint, and where the behaviour is
  not settled, this page says so rather than guessing.
</Callout>

## Endpoint [#endpoint]

### `wss://vike.io/v1/stream` [#wssvikeiov1stream]

```
WEBSOCKET wss://vike.io/v1/stream
```

Subscribe to one or more Hyperliquid series and receive a `bar` frame each time a candle
closes. Use it when you want to be told a bar has completed without polling
`GET https://data.vike.io/v1/hyperliquid/ohlcv` on a timer; use REST for history, for warm-up,
and for backfilling a gap.

The handshake takes one optional query parameter. Everything else is negotiated over the
socket after it opens.

<Params>
  <Param name="token" loc="query">
    API key, for clients that cannot set request headers. Ignored when an 

    `X-API-KEY`

     header is present, or when an 

    `Authorization`

     bearer validates. An 

    `Authorization`

     header that does 

    **not**

     validate — malformed, revoked, expired, or not a bearer at all — falls through, and the 

    `token`

     is read and honoured. See 

    [Authenticating](#authenticating-the-handshake)

    .
  </Param>
</Params>

The edge allows the WebSocket upgrade and drops a connection that goes **300 seconds** without
data. The server's \~15-second heartbeat keeps traffic well inside that window.

## What it streams: Hyperliquid, from our own node [#what-it-streams-hyperliquid-from-our-own-node]

The feed is driven by the same engine behind
[`/v1/hyperliquid/ohlcv`](/docs/endpoints/data/hyperliquid/ohlcv), reading one-minute and one-hour
rollups built from Hyperliquid fills captured by a node Vike runs itself. That is the whole
source: one venue, our own node, and the same series the REST endpoint serves. The one-minute
rollup trails wall clock by **18 seconds**, measured 2026-09-03, which is the lag the
15-second poll cadence is sized for.

<Callout type="warn" title="Exchange-pair symbols are not on this stream, and they fail silently">
  `BTCUSDT`, `ETHUSDT`, a `_PERP` suffix, anything shaped like an exchange pair: a `subscribe`
  carrying one is **accepted** — nothing validates the symbol against HL's asset list — and then
  streams nothing, forever, because Hyperliquid has no such asset. You cannot tell that apart
  from a quiet market.

  There is no second series behind this endpoint to fall back to. Subscribe with the HL asset —
  a perp ticker (`BTC`), a spot token (`HYPE`) or a raw spot index (`@107`) — and resolve it over
  [REST](/docs/endpoints/data/hyperliquid/ohlcv) first if you are not sure it trades.
</Callout>

### Which markets and DEXs are reachable [#which-markets-and-dexs-are-reachable]

An HL bar is not identified by symbol alone, so the subscription carries two more fields:

| Field    | Values                                                                                                                                     | Default |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| `market` | `perp` or `spot`. Lower-cased before use, so `"PERP"` is accepted.                                                                         | `perp`  |
| `dex`    | The core venue `HL`, or a HIP-3 builder-deployed perp DEX. 1–16 alphanumeric characters, upper-cased before use, so `"hl"` is the default. | `HL`    |

Symbols follow the REST endpoint: a perp ticker (`BTC`), a spot token (`HYPE`) or a raw spot
index (`@107`). Whatever you send is stripped and upper-cased before use.

<Callout type="warn" title="Do not hard-code the dex list">
  Builder DEXs deploy permissionlessly. The live set is read from the data and cached for 10
  minutes, falling back to a fixed nine-name list only when that read fails — and an earlier
  three-hour sample of that fallback saw only five of the nine actually trading. Subscribe with
  the dex you want and read the error message, which **names the known set**. Note also that spot
  lives on the core venue only (HL is perp *and* spot; the rest are perp DEXs), so
  `market: "spot"` with a builder `dex` is a well-formed subscription that will never produce a
  bar.
</Callout>

### What changed for a client, and what did not [#what-changed-for-a-client-and-what-did-not]

The wire protocol is unchanged: `subscribe`/`unsubscribe`/`pong`, the `bar` frame shape, the
monotonic `seq`, the `closed` flag, the \~15-second `ping`, the bounded outbound queue and the
seq-gap-then-backfill recovery path are all exactly as they were. A client written against the
published spec still connects, still subscribes with `{symbol, interval}`, and still parses
every frame. Since **2026-09-03** the data behind those frames is Hyperliquid's, so a client
written before that date sees three differences:

* **Symbols are HL assets** (see the callout above). The venue is pinned by construction — it
  is Hyperliquid — and `market`/`dex` select within it.
* **Six intervals are gone.** `3m`, `2h`, `6h`, `8h`, `12h` and `1w` are not in HL's set. A
  subscription to one is now an error frame, not silence.
* **`funding` is still always `null`**, for a new reason: HL candle rows carry `volume_usd` and
  `n_trades`, never a funding rate.

## Authenticating the handshake [#authenticating-the-handshake]

The handshake tries three credential sources **in this order** and stops at the first that
produces an identity:

| Order | Source                  | Form                                                                                                                     |
| ----- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| 1     | `Authorization` header  | `Bearer vk_oat_...` — an OAuth 2.1 access token. Requires the `vk_oat_` prefix; revoked and expired tokens are rejected. |
| 2     | `X-API-KEY` header      | `vk_...` — matched against an active API key.                                                                            |
| 3     | `token` query parameter | The same API key, in the URL: `wss://vike.io/v1/stream?token=vk_...`                                                     |

Both header forms reach the same account — the same rule as the REST surface, see
[Authentication](/docs/data/authentication).

<Callout type="warn" title="The query parameter exists because browsers force it">
  The browser `WebSocket` constructor cannot set request headers, so `?token=` is the only
  way a page can authenticate. It puts a live credential in a URL. Prefer a header from any
  client that can send one, and treat a key used this way as more exposed than one that is
  not.
</Callout>

### What a refusal looks like [#what-a-refusal-looks-like]

If no source yields an identity the connection is closed with code **4401**, and it is closed
**before** the handshake completes. Most clients surface that as an HTTP **403** on the upgrade
rather than as close code 4401.

<Callout type="warn" title="403 does not tell you what was wrong">
  The server answers 403 identically for a connection refused before the handshake completes and
  for a WebSocket path that matches no route. A 403 therefore cannot distinguish *your key was
  refused* from *your URL was wrong* — `/v1/stream`, `/v1/stream-bogus` and `/v1/nope` all
  look the same from outside. Check the URL by hand before concluding the credential failed.
</Callout>

## Subscribing [#subscribing]

After the socket opens, send JSON **text** frames. Exactly three values of `action` are
accepted:

| Field      | Required                  | Notes                                                                                                                                                 |
| ---------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action`   | Yes                       | `subscribe`, `unsubscribe` or `pong`. Anything else is an error frame.                                                                                |
| `symbol`   | For subscribe/unsubscribe | HL perp ticker (`BTC`), spot token (`HYPE`) or raw index (`@107`). Stripped and upper-cased by the server before use.                                 |
| `interval` | For subscribe/unsubscribe | One of the seven below.                                                                                                                               |
| `market`   | No                        | `perp` or `spot`. Default `perp`.                                                                                                                     |
| `dex`      | No                        | `HL` or a builder DEX. Default `HL`.                                                                                                                  |
| `channel`  | No                        | Accepted and **never read** — nothing on the server inspects it, so `"channel": "bars"` is decoration. Bars are the only thing this endpoint streams. |

```json title="Subscribe frames"
{"action": "subscribe",   "channel": "bars", "symbol": "BTC",  "interval": "1m"}
{"action": "subscribe",   "channel": "bars", "symbol": "HYPE", "interval": "5m", "market": "spot"}
{"action": "subscribe",   "channel": "bars", "symbol": "BTC",  "interval": "1m", "dex": "XYZ"}
{"action": "unsubscribe", "channel": "bars", "symbol": "BTC",  "interval": "1m"}
{"action": "pong"}
```

Intervals are the HL engine's **time** intervals:

```
1m  5m  15m  30m  1h  4h  1d
```

<Callout type="warn" title="Tick intervals are refused, on purpose">
  The REST endpoint accepts `Nt` bars (`15t` = 15 trades per bar). This one does not, for two
  independent reasons, either sufficient:

  * A tick bar has no wall-clock bucket, so *which bars have closed* — the only question this
    poller is built to answer — has no tick analogue.
  * Tick bars are not stable across polls. Trades are counted off from the start of the
    **requested window**, so the bar boundaries are anchored to that window. The poller advances
    its window every cycle, which re-partitions the same trades into different bars: the same
    `ts` would come back with different OHLC, and a monotonic `seq` over contradictory bars is
    worse than no bars at all.

  A tick stream needs trade arrival to drive it, not a wider validator. Ask for tick bars over
  [REST](/docs/endpoints/data/hyperliquid/ohlcv).
</Callout>

### The subscription key [#the-subscription-key]

A subscription is &#x2A;*`(symbol, interval, market, dex)`** — all four fields, and everything the
server does with a subscription (registering it, attaching, detaching, tearing it down) keys on
all four. Consequences:

* `BTC/1m` perp and `BTC/1m` spot are two independent subscriptions with two independent feeds
  and two independent `seq` counters. They never collide, and neither do two builder DEXs.
* **Unsubscribe with the same four fields you subscribed with.** The key is re-derived from the
  `unsubscribe` message, so unsubscribing `{symbol, interval}` does not cancel a `spot`
  subscription — the keys differ, and the call is a silent no-op.
* Subscribing to a key you already hold on that connection is a no-op; so is unsubscribing
  from one you do not hold.

<Callout type="warn" title="A successful subscribe is answered with silence">
  There is no `subscribed` acknowledgement frame. The server replies to a valid `subscribe`
  with nothing at all, and the next thing you receive is either a heartbeat `ping` or the
  first `bar` — which for a `1d` subscription is up to a day away. Do not wait for an ack;
  treat the absence of an `error` frame as acceptance.
</Callout>

### The error frame [#the-error-frame]

Every client-side rejection uses the same shape and, today, the same `code`:

```json title="The error frame"
{"type": "error", "code": "bad_subscription", "message": "unknown action 'frobnicate'"}
```

`message` is the only field that varies, and it now diagnoses rather than gestures — each fault
has its own message, checked in this order:

| What you got wrong                       | `message`                                                       |
| ---------------------------------------- | --------------------------------------------------------------- |
| No `symbol`, or a blank one              | `symbol is required`                                            |
| An interval outside the seven            | `unknown interval '12h'; allowed: 1m, 5m, 15m, 30m, 1h, 4h, 1d` |
| A `market` that is neither               | `market must be one of perp, spot; got 'futures'`               |
| A malformed `dex`                        | `dex must be 1-16 alphanumeric characters; got 'not a dex'`     |
| A well-formed `dex` that is not deployed | `unknown dex 'ZZZ'; known: ...` — the live set, named           |

Malformed JSON, a non-object payload and an unknown `action` are caught earlier still, before
the subscription is built, and arrive with the same `code`. The socket stays open in every
case; a rejected message is discarded and the connection continues.

<Callout type="warn" title="Only the last row costs a round trip, and it is the one that can be skipped">
  The format checks are free. The **membership** check — is this dex actually deployed — needs a
  database round trip, and it runs &#x2A;*only when `dex` is not `HL`**: the core venue is always
  known and can never be the unknown one, so an ordinary subscription never pays for it. That
  check is also deliberately permissive: if the lookup itself fails, the subscription proceeds.
  It is there to catch typos, not to be a gate.
</Callout>

## Server frames [#server-frames]

Two frame types reach the client in normal operation — `bar` and `ping` — plus the `error`
frame above.

### `bar` [#bar]

The frame shape is fixed, and a test holds it that way:

| Field                          | Meaning                                                                                                                                                                                                                                                       |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`                         | Always `"bar"`.                                                                                                                                                                                                                                               |
| `symbol`                       | The symbol as you subscribed it, stripped and upper-cased. Not the resolved HL asset — a spot subscription for `HYPE` reports `HYPE`, not `@107`.                                                                                                             |
| `interval`                     | The subscribed interval.                                                                                                                                                                                                                                      |
| `ts`                           | Candle **open** time, epoch **milliseconds**, UTC, left-aligned to the interval — the same convention as the REST candle. A bar covers `[ts, ts+interval)`.                                                                                                   |
| `open`, `high`, `low`, `close` | The candle.                                                                                                                                                                                                                                                   |
| `volume`                       | **Base-asset, taker-side** volume. Hyperliquid reports two rows per trade, one per side; the taker side is the figure venues publish, and counting both legs doubles it (24h BTC measured at $3.34B unfiltered against a per-trade-exact $1.67B, 2026-08-18). |
| `funding`                      | Always `null`, see below.                                                                                                                                                                                                                                     |
| `closed`                       | `true`. Always, today — see below.                                                                                                                                                                                                                            |
| `market`                       | `"spot"`. &#x2A;*Present only when the subscription is not the default `perp`.**                                                                                                                                                                              |
| `dex`                          | The builder DEX name. &#x2A;*Present only when the subscription is not the default `HL`.**                                                                                                                                                                    |
| `seq`                          | Monotonic counter, **per subscription key**, incremented once per emitted frame. See [Sequence numbers and gaps](#sequence-numbers-and-gaps).                                                                                                                 |

The shape — the numbers are illustrative, and `BTCUSDT` here is a placeholder the server never
inspects, not a symbol that would return bars from HL:

```json title="The bar frame"
{
  "type": "bar", "symbol": "BTCUSDT", "interval": "1m",
  "ts": 1738411260000, "open": 1.0, "high": 2.0, "low": 0.5,
  "close": 1.5, "volume": 10.0, "funding": null, "closed": true, "seq": 5
}
```

<Callout type="warn" title="market and dex appear only when they are not the default">
  A subscription is keyed by four fields, but a default (perp/HL) frame names two — so it stays
  byte-identical to the published spec and an existing client is unaffected. The cost is real and
  worth planning for: **two subscriptions on one connection differing only by `market` or `dex`
  produce frames you cannot tell apart** unless the non-default one is present, and `seq` cannot
  demultiplex them either — it is per-subscription, and both start at 1. If you hold BTC-perp and
  BTC-spot on one socket, route on the presence of the `market` key; do not route on `symbol`
  alone.
</Callout>

<Callout type="warn" title="funding is always null, and closed is always true">
  An HL candle carries `ts, open, high, low, close, volume, volume_usd, n_trades` and no funding
  rate, so `funding` is present and null on every frame. The two extra HL columns are **not** in
  the frame at all: `volume_usd` and `n_trades` exist on the REST response and are dropped here,
  because adding fields would change a published shape. Fetch them over
  [REST](/docs/endpoints/data/hyperliquid/ohlcv) if you need them.

  `closed` is likewise fixed: every frame is built with `closed: true`, and the poll only ever
  asks for a window ending at the last **completed** bucket. Both fields exist for a
  live-forming-bar upgrade — a live trade feed driving the same wire protocol and emitting
  `closed: false` frames — that is not shipped, so do not branch on either field expecting
  variation today.
</Callout>

### `ping` [#ping]

```json title="The ping frame"
{"type": "ping"}
```

## Heartbeat [#heartbeat]

The server sends `{"type": "ping"}` every **15 seconds**. The client must answer with a `pong`
message, which resets the miss counter to zero.

<Callout type="warn" title="Reply with a JSON pong, not a protocol pong">
  This is an **application-level** heartbeat carried in a JSON text frame. A WebSocket
  protocol-level pong frame — what most libraries send automatically in response to a
  protocol ping — never reaches the application and does not reset the counter. You must
  send the literal `pong` action as a text message.
</Callout>

The counter is incremented immediately before each ping is sent, and the connection is
closed with code **1011** once it exceeds **3** missed pongs. A client that never ponged is
therefore dropped on the fourth heartbeat tick, roughly **60 seconds** after the socket
opened.

Note also that the server reads text frames only. Binary messages are not part of this
protocol.

## Sequence numbers and gaps [#sequence-numbers-and-gaps]

`seq` is what tells you a frame went missing, and its scope is the part that surprises
people: &#x2A;*it belongs to the `(symbol, interval, market, dex)` feed, not to your connection.**

There is one shared feed per active key on the server, with one poller serving every
subscriber. Its counter starts at 0 when the feed is created — that is, when the *first*
client anywhere subscribes to that key — and the feed is torn down when its *last* subscriber
leaves.

The consequences worth planning for:

* If you subscribe to a key somebody else is already watching, your **first frame's `seq`
  is not 1**. It is wherever that feed had got to.
* If you are the only subscriber and you unsubscribe and resubscribe, the feed is destroyed
  and rebuilt, and `seq` **restarts at 0**. A `seq` you saw before is not comparable with a
  `seq` you see after.
* `seq` does not survive a server restart, and it is per-process.

Use `seq` for what it is designed for — detecting a **gap within one continuous
subscription** — and not as a durable cursor.

### Backpressure [#backpressure]

Each connection has a bounded outbound queue of **1000** frames. When a slow consumer's queue
is full the server counts the drop and moves on: the feed never blocks on one slow client. You
observe the loss as a jump in `seq`, and the documented recovery is to backfill the missing
window over REST — `GET https://data.vike.io/v1/hyperliquid/ohlcv` with the same `symbol`,
`interval`, `market` and `dex`, over the `ts` range you missed
([Hyperliquid OHLCV](/docs/endpoints/data/hyperliquid/ohlcv)). That is the same series the feed
polls, so the backfilled bars are the same bars.

<Callout type="warn" title="It drops the newest frame, not the oldest">
  A full queue is not drained to make room: the server discards the frame it could not enqueue.
  Either way you see a `seq` gap, but the bars you lose are
  the **most recent** ones, and the queue you are draining is stale. If your client falls
  1000 frames behind, backfill from the last `seq` you received rather than assuming what you
  are still reading is current.
</Callout>

## What closes the connection [#what-closes-the-connection]

| Cause                                             | Code    | Notes                                                                                   |
| ------------------------------------------------- | ------- | --------------------------------------------------------------------------------------- |
| No valid credential                               | `4401`  | Sent before the handshake completes, so it fails; clients usually see HTTP 403 instead. |
| Four heartbeat ticks with no `pong`               | `1011`  | \~60 s after the last `pong`.                                                           |
| The client disconnects                            | —       | Handled quietly.                                                                        |
| Any unhandled server-side error on the connection | default | The socket is closed.                                                                   |

On every one of these, all of that connection's subscriptions are detached, which tears down
any feed left with no subscribers.

## Freshness, and what the bars actually are [#freshness-and-what-the-bars-actually-are]

Each feed polls the HL series once every **15 seconds** and broadcasts whatever closed bars are
new since its last poll. The one-minute rollup behind it trails wall clock by **18 seconds**,
measured 2026-09-03.

**These are closed bars only. There is no live forming candle**, and the 18 seconds is not
delivery latency at the bucket boundary — it is how long after the boundary the bar becomes
readable at all. Stack the poll cadence on top and a closed bar reaches you somewhere in the
region of 18 to 33 seconds after it closed, depending on where the boundary falls between two
polls. That range is arithmetic over two constants, not an end-to-end measurement; nobody has
timed a frame on the wire (see [Known gaps](#known-gaps-in-this-page)).

Two mechanics behind that, both visible from outside:

* **The poller floors its own window.** It asks only for buckets that have already closed,
  explicitly ending the window at the open of the forming bucket — otherwise it would ship a
  partial bar stamped `closed: true` that nothing would ever correct. So a subscription never
  emits the bar that was forming when you subscribed until it closes, and never emits a partial
  bar at all.
* **A fresh subscription is quiet until the next boundary.** A new feed starts just before the
  forming bucket's open, so its closed window is empty and it queries nothing until a bucket
  closes. On `1m` bars at 15-second polls that is up to three silent cycles; on `1d` it is up to
  a day. Warm-up history comes from REST, not from the stream.

<Callout type="warn" title="Every data-plane fault on this endpoint looks like silence">
  A subscribe is validated for shape, not for existence. Everything past that point degrades to
  nothing-arrives:

  * **A symbol HL does not trade** (an exchange pair, a typo) returns an empty candle list,
    forever.
  * **A spot symbol the venue does not list** makes the poll itself fail; the server retries next
    cycle and the client is told nothing.
  * **A well-formed but undeployed `dex`** is normally caught at subscribe time, but that check
    is permissive when the database is unreachable, so it can reach the poller and land in the
    same place.

  No error frame is emitted from the feed — only from `subscribe`/`unsubscribe` handling. Emitting
  one is a deliberate non-change, not an oversight. **Resolve a symbol over
  [REST](/docs/endpoints/data/hyperliquid/ohlcv) before you subscribe to it**, or you cannot tell a
  typo from a quiet market.
</Callout>

## Load, and what a connection costs [#load-and-what-a-connection-costs]

Fan-out is per subscription key, not per connection: 1,000 clients watching `BTC/1m` on the
core perp produce one engine query per 15-second cycle, delivered 1,000 ways. Cost scales with
the number of **distinct keys** subscribed across the whole process, not with the number of
connections.

<Callout type="warn" title="A spot subscription costs an extra query per poll">
  A `market: "spot"` poll resolves the spot-token map on every call, to turn `HYPE` into `@107`.
  That is one additional query per feed per 15-second cycle, for as long as the subscription is
  held. It is pre-existing behaviour of the underlying query rather than something the stream
  added, but the stream is what turns it into a standing cost. The dex list is not in that class
  — it caches for 10 minutes.
</Callout>

On metering: today this endpoint runs no rate-limit check and writes no usage record —
authenticating the handshake is the entire gate, and there is no second gate at the edge. That
is current behaviour, not a published allowance, so do not design around a stream being free.
The hourly budget and its documented home are on [Rate limits](/docs/data/rate-limits).

## Why you cannot probe it [#why-you-cannot-probe-it]

This endpoint cannot be confirmed or refuted by curling it, which is a large part of why it
went undocumented for so long:

* The server answers **403** identically for an unmatched WebSocket path and for a connection
  refused before the handshake completes. `/v1/stream` and `/v1/nope` are indistinguishable
  from outside.
* The edge behaves differently by protocol. Over HTTP/2, `Connection: Upgrade` is rejected
  outright — measured as a **400**. Over `--http1.1` the request reaches the application and
  returns 403. A probe run over h2 will look like proof the endpoint does not exist.

The only positive confirmation is a completed connection: open the socket over HTTP/1.1 with a
valid credential, subscribe to a symbol you know trades on HL, and wait for a bar.

## Known gaps in this page [#known-gaps-in-this-page]

* **No observed traffic.** No bar on this page was captured from the live endpoint, and the
  18-to-33-second delivery window above is arithmetic over the measured data lag and the poll
  cadence, not a timing anyone has taken on the wire.
* **Multi-worker behaviour is not specified.** A feed is per-process, and single-process
  operation is what is assumed today. What `seq` would do across several processes is not
  settled, so this page does not claim it.


# Benchmark (/docs/trader/analytics/benchmark)



`crates/vike-analytics/src/benchmark.rs` answers one question: how did a strategy's equity curve
behave *relative to* another curve — an index, a buy-and-hold, a second strategy. Every function
takes two curves, `strat_eq` and `bench_eq`, and most take the annualization factor
(`periods_per_year`, the same one the [report](/docs/trader/analytics/report) uses) and a risk-free
rate `rf`.

## The one rule: the curves must be the same length [#the-one-rule-the-curves-must-be-the-same-length]

Every public function begins by asserting the two curves have equal length and panics with
`equity curves must be the same length (got a vs b)` when they do not. The doc on `beta` records
where that came from: the ported module raised a `ValueError` there, and the panic mirrors it. The
module header is careful about what "port of" means now — *provenance, not a standing
obligation*: the old implementation is retired, no exporter survives, and no test in this crate
compares these functions against it. The [parity gate](/docs/trader/concepts/parity-gate) page carries
that decision.

So align first. The module's internal per-step `returns` is *length-preserving*: it pads a
zero-denominator step with `0.0` rather than skipping it, and its doc says why — unlike
`metrics::returns`, benchmark comparisons pair two curves element-wise and must not shorten.

## The statistics [#the-statistics]

| function                       | definition (from its doc)                                                    | degenerate answer                                              |
| ------------------------------ | ---------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `beta(s, b)`                   | `cov(rs, rb) / var(rb)`                                                      | `0.0` when the benchmark has zero variance                     |
| `alpha(s, b, ppy, rf)`         | annualised Jensen's alpha: `CAGR_s − [rf + β · (CAGR_b − rf)]`               | —                                                              |
| `correlation(s, b)`            | Pearson correlation of per-step returns                                      | `0.0` when either series has zero variance                     |
| `r_squared(s, b)`              | `correlation²`                                                               | —                                                              |
| `tracking_error(s, b, ppy)`    | annualised standard deviation of the return differential `rs − rb`           | `0.0` below 2 returns                                          |
| `information_ratio(s, b, ppy)` | annualised `mean(rs − rb) / std(rs − rb)`                                    | `0.0` when tracking error is zero                              |
| `up_capture(s, b)`             | mean of `rs` on the bars where `rb > 0`, over the mean of `rb` on those bars | `0.0` when the benchmark has no positive-return bars           |
| `down_capture(s, b)`           | mean of `rs` on the bars where `rb < 0`, over the mean of `rb` on those bars | `0.0` when the benchmark has no negative-return bars           |
| `treynor_ratio(s, b, ppy, rf)` | `(annualized_return − rf_annual) / β`                                        | `0.0` below 2 aligned returns, non-positive growth, or `β = 0` |

`benchmark_stats(s, b, ppy, rf)` computes the first eight in one pass and returns them as a
`BenchmarkStats` struct with one field per statistic — `beta`, `alpha`, `correlation`,
`r_squared`, `tracking_error`, `information_ratio`, `up_capture`, `down_capture`. Treynor is a
separate call.

The variance under `beta`, `correlation` and the tracking-error family is the same
`metrics::mean_variance` the rest of the crate uses (sample variance, `ddof = 1`), and the
covariance folds through `vike_model::py_sum`, so the summation discipline on the
[metrics](/docs/trader/analytics/metrics) page applies here unchanged.

## Treynor, stated fully [#treynor-stated-fully]

`treynor_ratio`'s doc spells out its terms because they differ from the others'. The numerator's
`annualized_return` is the *geometric* annualization of the strategy's own per-step returns — the
product of `1 + r` over the aligned returns, raised to `periods_per_year / n` — and
`rf_annual = (1 + rf)^periods_per_year − 1`. A `β` of zero (a flat or degenerate benchmark) is the
sentinel case, returning `0.0` rather than dividing.

<Callout type="warn" title="rf is not one unit across the module">
  Read each doc's formula before passing a rate. `alpha` places `rf` directly beside `CAGR_s` and
  `CAGR_b`, both annual figures. `treynor_ratio` compounds it — `(1 + rf)^periods_per_year − 1` —
  so there it is a per-period rate. The two functions are documented independently and neither
  converts for you; a rate that is right for one is wrong for the other by a factor of the
  annualization.
</Callout>

## Portability [#portability]

The header names the three sites that reach a power — `cagr`, `r_squared`, `treynor_ratio` — and
states that each is `libm::pow`, never `f64::powf`, citing the decision record that made the
`libm` crate the source of every transcendental. It also draws the conclusion that follows for
this module in particular: because these numbers no longer track the platform library the retired
implementation computed with, even the *spirit* of a cross-implementation comparison is gone here,
not just the mechanism. The [analytics index](/docs/trader/analytics) carries what the portability
costs and the gate that holds it.

## What this is not [#what-this-is-not]

These are curve-versus-curve statistics over two *equity* series. The two-series indicators —
spread, correlation and the rest computed bar by bar over two *price* series — live behind their
own seam in the indicator crate; the [pairs](/docs/trader/indicators/pairs) page covers them.


# Excursions (/docs/trader/analytics/excursions)



A trade's *maximum adverse excursion* is how far price moved against it before it closed; its
*maximum favourable excursion* is how far price moved in its favour. `crates/vike-analytics/src/
excursions.rs`'s header defines the module as pure functions over the trade list and OHLC bars,
with MAE and MFE derived by scanning the bars between each trade's entry and exit timestamps.

## Direction is inferred, and the field that looks like a side test is not one [#direction-is-inferred-and-the-field-that-looks-like-a-side-test-is-not-one]

`trade_direction(trade)` returns `+1` for long and `−1` for short, and its doc calls itself *the
single source of truth* for that inference. The reason it has to exist: `Trade.size` is recorded
as an absolute value — side is lost at the engine level — so `size >= 0` is not a side test. The
rule is that a profit on a price rise is a long and a profit on a price fall is a short; the
degenerate case, `pnl == 0` or `exit == entry`, defaults to long.

## MAE and MFE [#mae-and-mfe]

`mae_mfe(trade, bars, direction)` returns `(mae, mfe)` as positive fractions of entry price over
the trade's bar window — every bar with `entry_ts <= ts <= exit_ts`, inclusive. `direction` is an
optional override; `None` means infer it as above. For a long, adverse is the lowest low below
entry and favourable the highest high above it; for a short the two are mirrored. A zero entry
price or an empty window returns `(0.0, 0.0)`.

That last case matters more than it looks, because it is how the two fields on the trade itself
behave. `vike_model::Trade` carries `mae` and `mfe` as fractions of entry price, and its field
doc says *portfolio mode only; 0.0 = untracked*. There are two ways those fields get a value:

* **During a portfolio backtest**, the engine's bar loop folds each bar's high and low into the
  running extremes of every open position — this bar's high/low, no look-ahead — and the
  simulator's fill path resets those extremes to the fill price when a position opens or flips,
  then writes the excursions at the moment a reduce, close or flip closes a trade, using the
  prior sign of the position for direction. The per-bar fold is in
  `crates/vike-backtest/src/engine.rs`'s `run` loop; the reset and the write are in
  `crates/vike-backtest/src/engine/sim_broker.rs`'s `fold_fill`; the
  [sim broker](/docs/trader/backtesting/sim-broker) page carries the rest of it.
* **After the fact, from a bar series**, through this module. `crates/vike-report/src/
  excursions.rs`'s `backfill_excursions` is the worked example: a bare fill stream carries no
  intrabar path, so a trade reconstructed from the live journal leaves `mae`/`mfe` at `0.0` —
  correct, not a shortcut. When a bar series for the traded symbol exists in a history store, it
  loads the bars spanning `[entry_ts, exit_ts]` and hands them to `mae_mfe` — which its header
  calls *the one excursion primitive; no math is reimplemented here*. It is best-effort: an empty
  window or a load error leaves that trade at `0.0` rather than failing the tearsheet, because
  the store is an enrichment, not a hard dependency. The
  [tearsheet](/docs/trader/reference/binaries/tearsheet) binary opens the concrete store behind its
  `hist` feature and passes it in as a trait object.

<Callout title="Two direction sources">
  The simulator writes excursions using `is_long`, the opening side it recorded. `mae_mfe` with
  `direction = None` infers the side from `pnl` and the price change. Because `Trade.pnl` is gross
  price PnL, the two agree for any trade with a non-zero PnL; for the degenerate zero-PnL trade the
  inference defaults to long. Pass `Some(direction)` when you hold the recorded side and want it honoured.
</Callout>

## The edge ratio [#the-edge-ratio]

`edge_ratio(trades, bars)` is mean MFE over mean MAE across the trades, computed through
`mae_mfe` for each — its doc frames it as *entry quality*: a value above 1 favours profitable
excursions. The sentinels follow the crate convention: `0.0` with no trades, `inf` when mean MAE
is zero and mean MFE is positive (a trade set that never went against you).

## Running trade metrics [#running-trade-metrics]

`expanding_trade_metrics(trades)` produces one `ExpandingMetric` row per trade, in order, each
carrying the state *after* that trade: `n`, `win_rate`, `profit_factor` and `avg_pnl`. It is the
series a "metrics as the run progressed" chart is drawn from. `profit_factor` is `inf` while there
are no losing trades and gross profit is positive — the same rule as the
[metrics](/docs/trader/analytics/metrics) catalog's whole-sample version, applied at every prefix.

## What to read alongside [#what-to-read-alongside]

The [result type](/docs/trader/analytics/result) page describes the `Trade` fields these functions
read; the metrics page carries the sentinel convention the ratios share.


# Analytics (/docs/trader/analytics)



Vike Trader's analytics live in one crate, `vike-analytics`, whose header states the design in a
sentence: &#x2A;the pure performance-analytics cluster, extracted verbatim out of `vike-backtest`*.
Nothing in it runs a simulation, signs an order or opens a store. It takes an equity curve and a
trade list and returns numbers — and because the backtest runner and the live tearsheet both call
the same functions, a backtest number and a live number over the same fills are the same number.

## Why it is a crate of its own [#why-it-is-a-crate-of-its-own]

`crates/vike-analytics/src/lib.rs`'s header carries the measurement that justified the split.
`vike-report`, the reader that renders a tearsheet from the live journal, reimplements no metric:
every figure it prints is a call into this catalog. While the catalog lived inside `vike-backtest`,
that reader compiled **32,259 lines to reach about 3,900** — 89% of what it built it could not
call, including the simulator, the paper exchange and the whole feature-gated harness tree. The
seam was already there: these modules name `vike_model` and nothing else (the one `vike_exec`
mention in the cluster was a doc comment in `result.rs`). Splitting on it lets a consumer take the
numbers without the machine that produced them. The header is explicit that the extraction *moved
code, not behaviour*.

## The rule the crate holds [#the-rule-the-crate-holds]

**`vike-model` is the only Vike dependency** — no `vike-exec`, no `vike-core`, no `vike-data`.
The header calls that the property the split exists to create, and says a would-be dependency on
any of the three is a signal that the item belongs in `vike-backtest`, not here. The manifest says
the same thing structurally: `crates/vike-analytics/Cargo.toml` declares `layer = 20` under
`[package.metadata.vike]`, the *domain* tier ("one hop over the vocabulary: a single-purpose pure
core"), and the layer gate fails any normal dependency that does not sit strictly lower. The
[architecture](/docs/trader/concepts/architecture) page carries the tiers.

The non-Vike dependencies are few, and each carries its reason in the manifest: `serde` (the
report and the zero-trade report serialize), `chrono` (calendar bucketing), `indexmap` (insertion
order where it affects a floating-point sum), `rand` (seeded resampling), `libm` (the manifest's
row names what first brought it in — the `erfc` normal CDF and the inverse normal CDF in
`overfit.rs`; the rule that every transcendental in the crate now goes through it is the header's,
below).

## What is in it [#what-is-in-it]

| module                      | page                                                                                           | what it is                                                                                                          |
| --------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `metrics`                   | [Metrics](/docs/trader/analytics/metrics)                                                           | the catalog — sharpe, sortino, drawdown, CAGR, VaR, ES, SQN and the rest; the one home for every performance number |
| `result`                    | [The result type](/docs/trader/analytics/result)                                                    | `BacktestResult`, the run's raw output                                                                              |
| `report`                    | [The report](/docs/trader/analytics/report)                                                         | `BacktestReport`, the flat serializable summary composed from it by `metrics::` calls only                          |
| `periods`                   | [Periods](/docs/trader/analytics/periods)                                                           | calendar bucketing, the monthly matrix, the drawdown table                                                          |
| `benchmark`                 | [Benchmark](/docs/trader/analytics/benchmark)                                                       | benchmark-relative statistics over two aligned curves                                                               |
| `excursions`                | [Excursions](/docs/trader/analytics/excursions)                                                     | MAE/MFE per trade, the edge ratio, running trade metrics                                                            |
| `montecarlo`                | [Monte Carlo](/docs/trader/analytics/monte-carlo)                                                   | seeded resampling of trade P\&L                                                                                     |
| `overfit`                   | [Overfitting](/docs/trader/analytics/overfitting)                                                   | PBO and the deflated Sharpe                                                                                         |
| `stability`                 | [Stability](/docs/trader/analytics/stability)                                                       | rolling parameter-stability scoring                                                                                 |
| `validation`                | [Validation](/docs/trader/analytics/validation)                                                     | walk-forward and purged k-fold split generators                                                                     |
| `stats`                     | [Survival statistics](/docs/trader/analytics/survival-stats)                                        | the autocorrelation-robust t-statistic                                                                              |
| `signal`, `signal_backtest` | [Signals](/docs/trader/analytics/signals), [The signal backtest](/docs/trader/analytics/signal-backtest) | probability to position; the vectorized signal backtest                                                             |
| `sizing`, `zero_trade`      | [Sizing, and zero-trade diagnosis](/docs/trader/analytics/sizing-and-zero-trade)                    | the `PositionSizer` registry (eight sizers); the zero-trade cause analyzer                                          |

A last module, `binutil`, is the pure argv glue the analytics-family binaries share; the header
notes that `store_root`, the one function that reads the environment, deliberately stayed in
`vike-backtest`.

## Numbers that do not depend on the box [#numbers-that-do-not-depend-on-the-box]

The header's "Cross-platform determinism" section is the part of this crate most worth carrying
into your own reading of a report. **Every transcendental in the crate is the `libm` crate, never
`f64`'s inherent method** — `libm::pow`, `libm::log`, `libm::exp`, `libm::erfc`. IEEE 754 does not
require `pow`, `log` or `exp` to be correctly rounded, so `f64::powf` is whatever the platform's
maths library does: the MSVC CRT on the Windows desktop, glibc on the Linux servers. The two
disagree by up to one ulp, and the equity curve produced by `signal_backtest::equity_from_pnl` was
measurably among the casualties, so a backtest's headline number depended on which machine ran it.
`crates/vike-analytics/tests/libm_platform_probe.rs` is the measurement that established it, and
`converted_functions_are_platform_invariant` in that file is the gate that now holds it. The
decision record behind the rule is dated 2026-08-25 and accepted.

Two refinements the header states because each was once got wrong: `sqrt` stays `f64::sqrt`,
because IEEE 754 *does* require it correctly rounded; and `powi` is banned at every arity, because
on MSVC in a `dev` build it becomes the CRT's `pow()` — the cure is a plain multiplication.

<Callout type="warn" title="What the portability costs">
  The header states the trade rather than hiding it: the `libm` crate does not agree with glibc
  either (the probe measures 0.07%–10% of samples differing per domain), so the conversion moved
  values on Linux too — where CI and live trading run. The numbers also no longer track the platform
  library the retired reference implementation computed with. That is a deliberate choice of
  reproducibility over bit-parity with an oracle that no longer exists; the
  [parity gate](/docs/trader/concepts/parity-gate) page carries what retiring that oracle did and did
  not license.
</Callout>

The parity rules the crate inherited are unchanged: `f64` end to end, the same expression order,
no fused multiply-add or fast-math; `%` on timestamps is floor-mod (`rem_euclid`); `IndexMap`
wherever insertion order affects the order of a floating-point sum.

## Two conventions you will meet on every page [#two-conventions-you-will-meet-on-every-page]

**Degenerate inputs return a sentinel, not `NaN`.** A ratio with nothing to divide is `0.0`, and
a ratio whose denominator is zero while the numerator is positive is `f64::INFINITY` —
`profit_factor` with no losing trades is the canonical case. The [report](/docs/trader/analytics/report)
page shows how that sentinel reaches JSON.

**One percentile.** Everything that quotes a quantile — VaR, the tail ratio, the Monte Carlo
bands — goes through `metrics::percentile`, and `metrics::PERCENTILE_METHOD` (`"numpy_linear"`)
names that convention wherever an artifact has to say which percentile produced its numbers.

## Where the numbers surface [#where-the-numbers-surface]

The standalone `backtest` binary prints a `BacktestReport` and ranks sweeps on it; the
[read a report](/docs/trader/guides/read-a-report) guide walks one. The
[tearsheet](/docs/trader/reference/binaries/tearsheet) binary builds a `BacktestResult` from
reconstructed live trades and fills its `LiveTearsheet` from the same catalog. And `vike-backtest`
re-exports `metrics`, `overfit`, `periods`, `report`, `result`, `sizing`, `validation` and
`zero_trade` at its own root so every pre-split path still resolves — while `benchmark`,
`excursions`, `montecarlo` and `stability` are deliberately *not* re-exported, because, as
`crates/vike-backtest/src/lib.rs`'s header records, no path of either spelling ever resolved
through that crate.


# Metrics (/docs/trader/analytics/metrics)



`crates/vike-analytics/src/metrics.rs` is the metrics catalog. The crate header calls it *the ONE
home for every performance number*: `vike-report` (the live tearsheet reader) and `vike-backtest`
both call it, so a live and a backtest tearsheet cannot drift. The module header describes it as an
exact port of the retired Python app's `analysis/metrics.py` — pure functions over slices. Two
inputs cover the whole catalog: an equity curve, `&[f64]`, and a trade list, `&[Trade]`.
`vike_model::Trade` is *a completed round-trip*; its doc fixes that `pnl` is gross price PnL,
`fees` is the round-trip cost, and `is_long` is true when the opening side was a buy. Where a metric
takes `periods_per_year`, the caller supplies it: the [report](/docs/trader/analytics/report) module
holds the two constants and passes the value through, and `BacktestReport::from_result`'s doc has
the `backtest` binary pick it from the profile's data kind and interval, since the result itself
does not carry that information. `DAILY_PERIODS_PER_YEAR` is 252 for daily bars, and
`DEFAULT_PERIODS_PER_YEAR` — the fallback its doc gives for non-daily and tick runs, a tick stream
having no fixed period — is kept equal to it so the Sharpe scale is at least consistent.

## Four conventions [#four-conventions]

**Sentinels, never NaN.** A metric with nothing to compute returns `0.0` — an empty trade list, a
curve shorter than two points, zero dispersion, too few returns for the estimator. A quotient whose
denominator is zero while its numerator is positive returns `f64::INFINITY`: `profit_factor` with
no losing trades, `recovery_factor` with no drawdown, `omega` with gains and no losses, and
`calmar`, `mar_ratio` and `ulcer_performance_index` with positive growth and no drawdown. The
module's tests name this the house `0.0`-sentinel convention, in place of NaN for degenerate
inputs. The report's `ser_f64_null_when_nonfinite` pins how `inf` reaches a `--json` consumer: as
JSON `null`, an explicit "no meaningful ratio" rather than a number.

**Compensated sums.** `mean_variance` is the shared core of every mean/std pair in the crate —
its doc names `sharpe`, `risk_return_ratio`, `returns_volatility`, `returns_skewness`,
`returns_kurtosis`, `sqn` and `benchmark::variance`, and the
[signal backtest](/docs/trader/analytics/signal-backtest)'s `sharpe_from_bar_pnl` and
`neg_sharpe_mini_backtest` reach it too — folding both moments through `vike_model::py_sum`, which is
Neumaier-compensated to match CPython's builtin `sum()`. Every current caller passes `ddof = 1.0`
(sample variance); the guards differ per caller and stay at each call site. Its doc records the one
reason it is `pub`: `vike_backtest::impact`, the [market-impact](/docs/trader/backtesting/market-impact)
model, folds its return series through the same function so the two cannot drift on summation
discipline.

**Transcendentals from the `libm` crate.** The header states the parity classes: metrics composed
of `+ − × ÷ abs compare` are bit-gated, while anything through `sqrt`/`pow`/`log` — `sharpe`,
`sortino`, `calmar`, `cagr`, `ulcer`, `mar`, `k_ratio` — is gated at ≤1e-12 relative, and a Python
`x ** 2` is mirrored as a `pow` call, never `x*x`. That call is `libm::pow`, and every `ln`/`exp` is
`libm::log`/`libm::exp`, never `f64::powf` or `ln`: `f64`'s transcendentals are the platform's libm,
which IEEE 754 does not require to be correctly rounded, so the same curve produced different
numbers on Windows and Linux. `crates/vike-analytics/tests/libm_platform_probe.rs` measured it —
before the conversion three of fourteen functions diverged across platforms over 600 curves each,
two of them here, `k_ratio` and `returns_skewness` — and its `converted_functions_are_platform_invariant`
holds the fix with hashes recorded by running on both boxes. `sqrt` stays `f64::sqrt` because the
standard *does* require it correctly rounded. The cost, stated in the crate header: the `libm`
crate does not agree with glibc either (0.07%–10% of samples per domain), so values moved on Linux
too — reproducibility chosen over oracle bit-parity, the rule the [parity gate](/docs/trader/concepts/parity-gate)
page carries.

**One percentile**, below.

## The curve-based catalog [#the-curve-based-catalog]

`returns` is the canonical primitive behind the ratios: per-bar simple returns `e[i]/e[i-1] − 1`,
*skipping* any step whose denominator is zero. Definitions are quoted from each function's doc
comment. A fraction of 0.01 is 1%; ratios are dimensionless; "ppy" is `periods_per_year`.

| function                  | inputs                | definition                                                                                                                                                      | unit                  |
| ------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `total_return`            | curve                 | return from the first to the last equity point                                                                                                                  | fraction              |
| `returns`                 | curve                 | per-bar simple returns, zero-denominator steps skipped                                                                                                          | fraction, one per bar |
| `max_drawdown`            | curve                 | largest peak-to-trough drop as a positive fraction of the peak (0.2 = 20%)                                                                                      | fraction              |
| `sharpe`                  | curve, ppy            | annualized Sharpe of per-bar returns, risk-free 0; `0.0` if variance is 0                                                                                       | annualized ratio      |
| `sortino`                 | curve, ppy            | annualized Sortino, target 0, risk-free 0                                                                                                                       | annualized ratio      |
| `calmar`                  | curve, ppy            | annualized return (CAGR) divided by max drawdown                                                                                                                | ratio                 |
| `mar_ratio`               | curve, ppy            | CAGR / max drawdown — its doc defines the same quotient as `calmar`                                                                                             | ratio                 |
| `omega`                   | curve, threshold      | gains above the threshold / losses below it                                                                                                                     | ratio                 |
| `cagr`                    | curve, ppy            | `(final/first)^(ppy/n) − 1`; `0.0` for flat, short, non-positive or overflowing input                                                                           | annualized fraction   |
| `ulcer_index`             | curve                 | `sqrt(mean(drawdown_pct²))`, the drawdowns taken in percent                                                                                                     | percentage points     |
| `ulcer_performance_index` | curve, ppy            | the Martin ratio, CAGR / Ulcer Index — penalized by drawdown depth *and* duration rather than max drawdown alone; `inf` with positive CAGR and zero Ulcer Index | ratio                 |
| `recovery_factor`         | curve                 | total return / max drawdown; `inf` with no drawdown                                                                                                             | ratio                 |
| `k_ratio`                 | curve                 | Kestner's K-ratio: slope / standard error of an OLS fit of log-equity against bar index                                                                         | ratio                 |
| `risk_return_ratio`       | curve                 | mean / std of returns (ddof 1), *not* annualized — Sharpe without the `sqrt(ppy)` factor                                                                        | ratio                 |
| `returns_volatility`      | curve, ppy            | annualized standard deviation of per-bar returns (ddof 1)                                                                                                       | annualized fraction   |
| `returns_skewness`        | curve                 | bias-corrected sample skewness (adjusted Fisher–Pearson, matching `pandas.Series.skew`); `0.0` below 3 returns or zero dispersion                               | dimensionless         |
| `returns_kurtosis`        | curve                 | bias-corrected excess kurtosis (matching `pandas.Series.kurt`; 0 for a normal distribution); `0.0` below 4 returns or zero dispersion                           | dimensionless         |
| `tail_ratio`              | curve                 | `abs(p95 / p5)` of returns — above 1 means a heavier upside tail; `0.0` for a zero or non-finite 5th percentile                                                 | ratio                 |
| `value_at_risk`           | curve, confidence     | historical VaR: the `1 − confidence` empirical quantile of returns, more negative = greater risk                                                                | per-bar return        |
| `expected_shortfall`      | curve, confidence     | historical CVaR: the mean of the returns at or below the VaR threshold; always ≤ the VaR                                                                        | per-bar return        |
| `exposure`                | curve, position sizes | fraction of bars with a non-zero position; `0.0` if the slices are empty or differ in length                                                                    | fraction              |

## The trade-based catalog [#the-trade-based-catalog]

PnL units are whatever `Trade::pnl` is denominated in.

| function                                                 | definition                                                                                                            | unit      |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | --------- |
| `win_rate`                                               | fraction of trades with positive PnL                                                                                  | fraction  |
| `profit_factor`                                          | gross profit / gross loss; `inf` with gross profit and no losing trades                                               | ratio     |
| `expected_payoff`                                        | average gross PnL per trade; `0.0` with no trades                                                                     | PnL units |
| `payoff_ratio`                                           | average win / abs(average loss); `0.0` with no wins or no losses                                                      | ratio     |
| `sqn`                                                    | Van Tharp's System Quality Number, `sqrt(n) · mean(pnl) / std(pnl)` (ddof 1); `0.0` below 2 trades or zero dispersion | ratio     |
| `long_ratio`                                             | fraction of trades whose opening side was long; `0.0` for an empty list                                               | fraction  |
| `net_profit`, `gross_profit`, `gross_loss`, `total_fees` | the sum of every `pnl`; of the positive ones; of the negative ones, sign flipped to a positive loss; of every `fees`  | PnL units |
| `avg_win`, `avg_loss`                                    | the mean of the positive, or of the negative, `pnl`s; `0.0` when that side is empty                                   | PnL units |
| `largest_win`, `largest_loss`                            | the largest positive and the most negative `pnl`; `0.0` when that side is empty                                       | PnL units |
| `consecutive_wins`, `consecutive_losses`                 | the longest run of winning, or of losing, trades                                                                      | count     |

The last four rows carry no doc comment in the source; their definitions are read from the
function bodies: the sums and averages fold through `py_sum`, the two extremes are a plain
`max`/`min` fold over the winning or losing `pnl`s, and the run counts come from `max_run`, an
integer run counter with no summation in it. The run counts are the catalog's only `usize`
results; every other row returns an `f64`, except `returns`, which returns the `Vec<f64>` the
curve table lists.

`long_ratio`'s doc carries a provenance note for anyone comparing against old numbers:
`Trade::is_long` is populated by both the event-driven engine and the vectorized kernel, each
computing it from the position's prior sign before the closing fill overwrites it, so it is always
meaningful for trades this platform produced — which was not true of the Python app it was ported
from, whose legacy vectorized kernels defaulted the field to `false`. That is why old numbers read
`0.0`; nothing still compares the two.

## The one percentile [#the-one-percentile]

`percentile(sorted_vals, q)` is *the workspace's ONE percentile*: the `q`-th quantile by linear
interpolation between closest ranks, matching `numpy.percentile`'s default; `0.0` for an empty
slice, and `n == 1` needs no special case because the formula falls through to the single element
bit-identically. Its doc records why it went `pub`: a second implementation had already been
written in a research binary, computing a *nearest-rank* answer — always an observed sample, never
an interpolant — and printing it under the same `p10`…`p90` names an operator sizes positions from.
The two agree only where `(n − 1)·q` lands on an integer or the two neighbours are equal; on
`[0, 1, 2, 3]` at `q = 0.5` nearest-rank reads `2.0` against this function's `1.5`. The doc's
instruction: reach for this one; do not write a third.

<Callout type="warn" title="Sorting is the caller's job, and the comparator is part of the contract">
  The body does no comparison at all, so it cannot detect an unsorted slice — it will silently
  interpolate between two arbitrary neighbours. Sort with `f64::total_cmp`, as `tail_ratio` and
  `value_at_risk` do, never with `partial_cmp().unwrap_or(Equal)`: only the former is a total order,
  so only the former actually leaves the slice sorted when a NaN is present.
</Callout>

`PERCENTILE_METHOD` (`"numpy_linear"`) is the *name* of that convention — what an artifact writes
down to say which percentile produced its numbers. It lives beside the body so the string and the
algorithm cannot come to disagree, and its doc asks that it change in the same edit that changes
`percentile` and in no other. A name rather than a version number, because the discriminating fact
is *which algorithm* and the tree holds more than two: the nearest-rank body above, a `len / 2`
median a research binary used to spell, and the latency gate's floor-rank percentile over integers,
deliberately a convention of its own. A third convention is a third name, visible in every artifact
carrying it; a version number would only have said that *something* changed.

## Where else the catalog runs [#where-else-the-catalog-runs]

The [report](/docs/trader/analytics/report) does no metric math of its own — every field is a
pass-through from the [result](/docs/trader/analytics/result) or a single `metrics::` call — and is
deliberately compact: a caller wanting the long-form catalog composes it for the shared fields and
adds its own from `metrics::`, `vike_report::LiveTearsheet` being the worked example.
[Monte Carlo](/docs/trader/analytics/monte-carlo) folds each resampled curve through `max_drawdown` and
its bands through `percentile`, its own copies of both having been deduplicated into this catalog;
the [survival statistics](/docs/trader/analytics/survival-stats) share `percentile`; the
[benchmark](/docs/trader/analytics/benchmark) statistics take their variance from `mean_variance` while
keeping a length-preserving returns series of their own, unlike `returns` here, because a
comparison pairs two curves.


# Monte Carlo (/docs/trader/analytics/monte-carlo)



One backtest gives one equity path — the order the trades happened to land in. `crates/
vike-analytics/src/montecarlo.rs` characterises how much of the result was that ordering: its
header describes the module as building many synthetic equity paths from the observed trade list
to characterise outcome dispersion. The [Monte Carlo and overfitting](/docs/trader/tutorials/monte-carlo-and-overfitting)
tutorial runs it end to end over a finished run.

## Two resampling methods [#two-resampling-methods]

`ResampleMethod` has two variants, each documented by what it preserves:

* **`Shuffle`** reorders the trade list, preserving the exact multiset of P\&Ls per path. Every
  path therefore ends at the same terminal equity — start equity plus the sum of the original
  P\&Ls — and what varies is the *path*: the sequence, and so the drawdown.
* **`Bootstrap`** samples with replacement, so a path may draw one trade several times and another
  never. Terminal equity varies as well as the path.

## Running it [#running-it]

`mc_resample(trade_pnls, start_equity, n_sims, seed, method)` runs `n_sims` paths. Each path is
built by adding the resampled P\&Ls to `start_equity` cumulatively — the curve has one more point
than there are trades. The `McResample` it returns carries:

* `terminal` — the final equity of each path
* `max_drawdowns` — the max-drawdown fraction of each path, computed by `metrics::max_drawdown`
  (the module's own copy was byte-identical and was removed in its favour)
* `curves_sample` — a representative sample of full curves, up to 20 paths spread evenly across
  the simulations, for plotting

`confidence_bands(curves, qs)` then turns equal-length curves into per-step percentile bands: for
each requested quantile, a series of the value at that quantile across all paths at each step,
returned as `(quantile, values)` pairs in the order of `qs`. The percentile is
`metrics::percentile` — the workspace's one percentile, linear interpolation, named
`numpy_linear` on the [metrics](/docs/trader/analytics/metrics) page.

`risk_of_ruin(terminal_equities, ruin_level)` is the fraction of paths that end at or below the
level; `0.0` for an empty input.

## The summary [#the-summary]

`mc_summary(trade_pnls, start_equity, n_sims, seed, ruin_pct)` runs the shuffle method and
reduces the result to a `McSummary`:

| field                                         | meaning                                                                                     |
| --------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `terminal_p5`, `terminal_p50`, `terminal_p95` | the 5th, 50th and 95th percentiles of terminal equity                                       |
| `max_dd_p50`, `max_dd_p95`                    | the median and 95th-percentile max drawdown across paths                                    |
| `prob_loss`                                   | the fraction of paths ending at or below `start_equity`                                     |
| `risk_of_ruin`                                | the fraction ending at or below `ruin_pct · start_equity` — ruin is defined by that product |

Because the summary uses the shuffle method, every path's terminal equity is the same and the
terminal percentiles collapse to it; the drawdown percentiles are the informative rows, and they
are exactly the question a shuffle asks — how bad could the sequence have been.

## The seed, and why this module is the worked example [#the-seed-and-why-this-module-is-the-worked-example]

The header states the reproducibility contract: seeded, so the same seed gives the same output
run to run within this implementation. The generator is `rand`'s `StdRng` seeded from the `u64`
you pass, and the manifest notes the dependency exists for *seeded resampling — statistical, not
bit, parity*.

<Callout title="A seed that is a parameter is an input">
  The workspace's determinism gate, in `crates/vike-ops/tests/clock_pin.rs`, refuses any RNG
  dependency inside the crates that must replay deterministically — and its doc names
  `vike_analytics::montecarlo` as *the worked example* of the acceptable shape: a seeded generator
  whose seed is a caller-supplied parameter is an input, not hidden state, and the code lives
  outside the replay-critical scope. What the gate refuses is the dependency arriving inside the
  fold at all, because the difference between `StdRng::seed_from_u64(seed)` and a thread-local
  generator is one line in a diff nobody is looking at. The [replay](/docs/trader/concepts/journal/replay)
  page is the other side of that rule.
</Callout>

## What is not pinned, and why [#what-is-not-pinned-and-why]

<Callout type="warn" title="There is no golden fixture for this module">
  The header is explicit. Porting the retired implementation's exact random generator — its
  Mersenne Twister plus its specific shuffle and range-draw routines — was ruled out as not worth it
  for this one file, so no fixture was ever frozen and no test replays one. What survives is the
  provenance of that decision: when the two implementations were run side by side, the same seed
  produced *statistically equivalent, not bit-identical*, resampled paths. The tests here pin the
  invariants instead — a shuffle path's terminal equals start plus the sum of P\&Ls exactly, the same
  seed is deterministic, different seeds differ, a bootstrap path's steps are all drawn from the
  original P\&Ls, and the summary's percentiles are ordered with its probabilities bounded in
  `[0, 1]`.
</Callout>

## Read with [#read-with]

The [overfitting](/docs/trader/analytics/overfitting) page is the other half of asking whether a result
is real: resampling tells you how much the ordering mattered, the anti-overfitting statistics tell
you how much the *selection* did.


# Overfitting (/docs/trader/analytics/overfitting)



A Sharpe ratio is a number; whether it means anything is a different question. `crates/vike-analytics/src/overfit.rs` answers it three ways, each accounting for something the raw figure ignores: track-record length and the non-normality of returns (the probabilistic Sharpe), the number of configurations that were tried (the deflated Sharpe), and whether the configuration that won in-sample keeps winning out of it (the probability of backtest overfitting). A fourth function folds two of them — the deflated Sharpe and the probability of backtest overfitting — together with an optional walk-forward consistency, into a verdict. The module is a port of the statistics in *Advances in Financial ML*, and every entry point is pure over an equity curve or a trial matrix.

## One derivation feeds everything [#one-derivation-feeds-everything]

Every function on this page takes the same four inputs, and there is exactly one sanctioned way to produce them: `overfit::sharpe_moments`, which turns an equity curve into a `SharpeMoments` — `sr_per_obs`, `n_obs`, `skew`, `kurt`. The struct exists because two unit conventions each carry a footgun, and one of the two has already shipped as a real bug.

<Callout type="warn" title="The Sharpe that reaches overfit:: is per-period, never annualized">
  The textbook PSR is `Φ((sr − sr*)·√(n−1) / denom)` with no periods-per-year factor, and `denom = √(1 − skew·sr + (kurt−1)/4·sr²)` uses `sr` directly. Feed it an annualized Sharpe and annualization is counted twice — once through `√(n−1)`, again inside `denom` — which saturates PSR and DSR to about 1.0 and makes any significance test vacuous. `sharpe_moments` therefore computes `sr_per_obs` with `metrics::risk_return_ratio` (plain `mean/std`), the per-period twin of the `metrics::sharpe` you display. The two are different quantities for different consumers; only the first may reach this module. `sharpe_moments`'s own doc names the pin that caught the bug in production code.
</Callout>

The second convention is kurtosis. `metrics::returns_kurtosis` reports *excess* kurtosis (the pandas convention, normal = 0) while the PSR formula wants the non-excess form (normal = 3), so `sharpe_moments` rebases by `+3.0` exactly once, there. `n_obs` is deliberately left unclamped: a curve with fewer than two returns yields `n_obs < 2`, and `probabilistic_sharpe_ratio`'s own guard turns that into an honest `0.0` rather than a number derived from a degenerate curve.

## The three statistics [#the-three-statistics]

**`probabilistic_sharpe_ratio(sr, n, sr_star, skew, kurt)`** is the probability that the true Sharpe exceeds `sr_star`, given the observed per-period Sharpe over `n` observations. With `sr_star = 0` it is the single-run question — is this edge distinguishable from zero — and that is exactly what the Studio results pane shows for one run (`vike-studio/src/results.rs`'s `validation_rows`, which also prints the annualized Sharpe as a separate display row).

**`deflated_sharpe_ratio(observed_sr, trial_sharpes, n_obs, skew, kurt)`** is the PSR benchmarked not against zero but against `expected_max_sharpe(var_trials, n_trials)` — the maximum Sharpe you would expect from that many independent trials with that much spread between them, which is what a search produces from pure noise. `expected_max_sharpe` returns `0.0` for fewer than two trials or non-positive variance, and that detail matters below. `deflated_sharpe_with_effective_n` is the same test with the trial count replaced by `effective_n_trials(trial_return_series)`: `N / (1 + (N−1)·max(mean_corr, 0))`, clamped to `[1, N]`, computed from pairwise Pearson correlation of the trials' return series. Perfectly correlated trials collapse to about one effective trial; uncorrelated or anti-correlated ones stay near `N`.

**`pbo_cscv(matrix, n_splits)`** is the probability of backtest overfitting by combinatorially symmetric cross-validation. `matrix` is `T` observations by `N` trials of per-observation performance. The observations are cut into `n_splits` groups (which must be even — an odd count panics); for every way of choosing half the groups as in-sample, the in-sample best column is found (first-argmax, mirroring the oracle), its out-of-sample rank among all columns becomes a logit, and PBO is the share of logits at or below zero — the fraction of paths on which the in-sample winner ranked at or below the out-of-sample median. A non-finite value anywhere in the matrix, or an empty one, returns `NaN`: uncomputable and honest, never `0.0`, which would read as "no overfit".

## The verdict [#the-verdict]

`overfit_verdict(pbo, deflated_sr, wf_consistency)` scores points and returns a `Verdict` with an `OverfitLevel` and a list of reasons. PBO above 0.5 scores two points, above 0.2 one; a deflated Sharpe below 0.5 scores two, below 0.9 one; a walk-forward consistency below 0.5 — the fraction of windows profitable out-of-sample, which `vike_backtest::walkforward::WalkForwardReport::wf_consistency` supplies (see [walk-forward](/docs/trader/backtesting/walk-forward)) — scores one. Three or more points is `High`, one or two `Medium`, none `Low`, with "No major overfitting flags." as the sole reason. A `NaN` PBO adds a "not assessed" reason and no points, so an unassessed PBO is neither a pass nor a vote toward low risk.

In the Studio, `vike-studio-core/src/run.rs`'s `run_sweep_slice` computes a sweep's DSR with the effective trial count over every trial, and its PBO with `N_SPLITS = 16` — `C(16, 8) = 12,870` combinations, off the UI thread — only when there are at least two trials and sixteen observations, leaving the PBO `NaN` otherwise; the sweep's ranking sort is deliberately the *annualized* Sharpe, a display quantity that never reaches this module. `validation_verdict_rows` renders the verdict, with a `NaN` PBO shown as "—".

## The selection audit [#the-selection-audit]

`audit_selection` exists because the gates above are only as good as the trial count they are given, and the wrong count is easy to supply.

<Callout type="warn" title="Feed the full candidate set, never the survivor">
  `effective_n_trials` derives its count from the trials it is fed, and `pbo_cscv`'s columns must be the full candidate set. Pick the best pair out of fifty, hand its curve alone to `deflated_sharpe_ratio`, and you read a reassuring number: a single trial has zero trial variance, so `expected_max_sharpe` benchmarks the winner against `0` rather than against the best-of-fifty a selection implies. `audit_selection` takes the full `trial_sharpes` and `trial_returns` plus the selected index precisely so the mistake is visible — a survivors-only call reports `n_candidates == 1` and appends "Only ONE candidate was audited" to the verdict. The module's own test demonstrates it: twenty candidates, one with a small drift, and the survivor-only audit reports a materially higher deflated Sharpe than the full audit.
</Callout>

The returned `SelectionAudit` carries `n_candidates`, `effective_trials`, `selected_sharpe`, `deflated_sr`, `pbo`, the `verdict`, and `selected_trades`. The trade count rides alongside Sharpe on purpose: a mean-reversion family dies by starvation — too few divergences — before it dies by unprofitability, and a Sharpe-ranked sweep cannot see that. Inconsistent inputs (an empty set, a length mismatch, an out-of-range index) return `None`: an unauditable selection is not a passing one.

It matters most for pair selection, a maximum over `N(N−1)/2` correlated candidate spreads — a search larger than any parameter sweep, and one that happens before it. The doc cites published work measuring the probability that an in-sample cointegrated pair is still cointegrated out-of-sample at about 4.9% against a 5.0% unconditional base rate: indistinguishable from a 5%-level test's false-positive rate. Pair search is exactly where a spurious winner enters.

## Related [#related]

[Survival statistics](/docs/trader/analytics/survival-stats) answers the same selection question by bootstrap, for signal panels rather than equity curves; [stability](/docs/trader/analytics/stability) scores the parameter neighbourhood of a sweep's optimum; [validation](/docs/trader/analytics/validation) supplies the splitters and the `combinations` helper `pbo_cscv` iterates.


# Periods (/docs/trader/analytics/periods)



`crates/vike-analytics/src/periods.rs` turns an equity curve plus its timestamps into the three
calendar views a tearsheet shows: returns per period, a year × month heatmap, and a table of the
worst drawdown episodes. Its header lists exactly those three entry points — `periodic_returns`,
`monthly_return_matrix` and `drawdown_table` — and everything on this page is one of them or the
label function underneath.

All three take the curve and a parallel `timestamps` slice in epoch milliseconds, UTC. On a
[result](/docs/trader/analytics/result) that is `equity_curve` and `equity_ts`, and `equity_ts` is empty
when a run did not track it — so calendar bucketing is only available for a run that carried its
timestamps. All three panic when the two slices differ in length; each one's `# Panics` section
states it.

## The period label [#the-period-label]

`period_key(ts_ms, period)` produces a comparable label for the calendar period containing a
timestamp. `period` is one of five strings and the doc gives the shape of each:

| `period`      | label                 |
| ------------- | --------------------- |
| `"daily"`     | `2024-03-15`          |
| `"weekly"`    | `2024-W11` — ISO week |
| `"monthly"`   | `2024-03`             |
| `"quarterly"` | `2024-Q1`             |
| `"yearly"`    | `2024`                |

Anything else panics. The doc records that as inherited behaviour — the ported module raised a
`ValueError` — and adds that it is provenance only: nothing compares this function against the
old implementation any more.

<Callout title="The daily bucket is the store's day">
  The `"daily"` arm does not derive year-month-day locally. It delegates to
  `vike_model::time::epoch_ms_to_utc_date`, the workspace's one day-law home, so this bucket key can
  never drift from the [history store](/docs/trader/concepts/hist-store)'s `date=` partition math or the
  end-of-day day-floor. The output is identical — the same `YYYY-MM-DD` off the same UTC calendar
  day — and a test in the module proves the two ways of computing it agree across pre-1970
  timestamps, the epoch boundary, a leap day and the millisecond either side of midnight.
</Callout>

## Periodic returns [#periodic-returns]

`periodic_returns(equity_curve, timestamps, period)` returns `(label, return_fraction)` pairs
grouped by calendar period, in chronological order. The doc defines the return as
`last_equity_in_period / first_equity_at_start_of_period − 1`, and the body makes "start of
period" precise: a bucket's entry equity is the last equity point *before* the bucket opened (the
previous period's closing value), except for the first bucket, which starts from the curve's first
point. A period whose entry equity is zero reports `0.0`. Insertion order is kept with an
`IndexMap`, mirroring the insertion-ordered dictionary of the port so the output order is the
order the periods were first seen.

## The monthly matrix [#the-monthly-matrix]

`monthly_return_matrix(equity_curve, timestamps)` builds the `MonthlyReturnMatrix` a heatmap
renders from: `years` (ascending), `matrix` (year → month → `Option<f64>`, present only for months
the curve touched) and `annual` (year → return). The annual figure is compounded from the months
present — the product of `1 + r` over them, minus one — not summed.

This is the structure the [tearsheet](/docs/trader/reference/binaries/tearsheet) binary's HTML output
renders as its monthly-returns table. `crates/vike-report/src/html.rs`'s header states the
arrangement: the table reuses `monthly_return_matrix` over the *same* equity curve and timestamps
the sheet was built from, nothing is re-derived, the table appears only when timestamps align one
to one with the curve, and a non-finite monthly cell renders as the empty marker rather than a
`+NaN%`.

## The drawdown table [#the-drawdown-table]

`drawdown_table(equity_curve, timestamps, top_n)` finds the top-N drawdown episodes sorted by
depth, worst first. Each `DrawdownEpisode` carries:

* `depth` — the fractional drawdown from peak, positive (0.20 = 20%)
* `peak_ts`, `trough_ts` — the timestamps of the peak and the trough
* `recovery_ts` — `None` if the curve never recovered
* `length` — bars from peak to trough
* `recovery` — bars from trough to recovery, `None` if not recovered

The scan is a single pass. A new peak (equity at or above the running peak) closes any open
episode with that bar as its recovery point; while below the peak the trough is tracked; an
episode still open when the curve ends is closed with no recovery and included. Episodes of zero
depth are dropped, so a monotonically rising curve yields an empty table, and the result is
truncated to `top_n` after sorting. The single worst episode's depth is the same number
`metrics::max_drawdown` reports on the [metrics](/docs/trader/analytics/metrics) page; this table adds
the where and the how long.

## Where it fits [#where-it-fits]

A `BacktestReport` does not carry any of these — it is deliberately compact, and the
[report](/docs/trader/analytics/report) page says so. Calendar views are composed by the caller that
has timestamps in hand: the HTML tearsheet today. A backtest that wants them calls these
functions over `equity_curve` and `equity_ts` directly.


# The report (/docs/trader/analytics/report)



`BacktestReport` is what the standalone `backtest` binary prints, what `--json` emits, and what a
sweep ranks on. `crates/vike-analytics/src/report.rs`'s header defines it by what it does *not*
do: the module *does no metric math of its own* — every number is a direct pass-through from the
[result](/docs/trader/analytics/result) or a single `metrics::` call, so a divergence here is a wiring
bug, not a math bug. The `matches_direct_metrics_calls` test holds that, asserting field-for-field
equality against calling `metrics::` directly on the same inputs.

## Why it lives outside the harness [#why-it-lives-outside-the-harness]

The header calls the module *feature-free by design*. The backtest harness sits behind
`vike-backtest`'s `hist-replay` feature, which pulls the optional data layer; the report needs
nothing but `serde` and the [metrics](/docs/trader/analytics/metrics), so it lives in the
`vike-model`-only crate instead, and the DataFusion-free leaf crates build the *same* summary
rather than re-assembling their own. `vike-report`'s `LiveTearsheet` composes this struct for the
fields the two share, so a live tearsheet and a backtest tearsheet cannot drift apart. The
harness's own `report` module re-exports everything and adds only the one piece that needs the
gated profile parser — `periods_per_year`, below.

## Deliberately compact [#deliberately-compact]

The struct doc is explicit that this is *not an everything-drawer*: it is the `backtest` binary's
human table and `--json` schema and the sweep's ranking source. A caller that wants the long-form
catalog — Sortino, Calmar, CAGR, SQN, VaR — composes this for the shared fields and adds its own
from `metrics::`; `LiveTearsheet` is named as the worked example.

| field                                                        | source                                                                                                  |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `name`                                                       | the profile's free-form `name`, if it had one                                                           |
| `final_equity`, `n_trades`, `per_symbol_pnl`, `funding_paid` | copied from the result                                                                                  |
| `total_return`                                               | `metrics::total_return` — fractional, first to last equity point                                        |
| `win_rate`                                                   | `metrics::win_rate` — fraction of trades with positive PnL                                              |
| `sharpe`                                                     | `metrics::sharpe` — annualized, per-bar or per-tick returns                                             |
| `max_drawdown`                                               | `metrics::max_drawdown` — largest peak-to-trough drop as a positive fraction of the peak                |
| `profit_factor`                                              | `metrics::profit_factor` — gross profit / gross loss                                                    |
| `zero_trade`                                                 | `ZeroTradeReport::analyze` — `Some` only for a run that closed no trades *and* whose equity never moved |

## The human table [#the-human-table]

`Display` prints a fixed row set. The field docs are careful about which rows exist, because the
table's shape predates two of the fields and stays byte-identical for a run that does not use
them. The rows below are the module's own test fixture — a 1000 → 1010 → 990 → 1005 curve with
one winning and one losing trade — with the Sharpe row left as its label, since that value depends
on the annualization factor passed in:

```text
name:          demo
final_equity:  1005.00
total_return:  0.5000%
n_trades:      2
win_rate:      50.0000%
sharpe:        <annualized Sharpe>
max_drawdown:  1.9802%
per_symbol_pnl:
  BTCUSDT: 5.00
```

* **`profit_factor` is not printed.** Its doc says the human table's row set predates the field;
  it exists for ranking [objectives](/docs/trader/backtesting/objectives) and JSON consumers.
* **`funding_paid` prints only when nonzero**, so a spot backtest's table is unchanged; it is
  always present in `--json`.
* **A zero-trade run prints its diagnosis instead of the table.** When `zero_trade` is `Some`,
  `Display` writes `final_equity`, `n_trades: 0` and then the ranked causes from the
  [zero-trade analyzer](/docs/trader/analytics/sizing-and-zero-trade) in place of the all-zero metric
  rows. For any run with trades the field is `None`, skipped on serialization and absent from the
  table.

## The JSON contract for the sentinel [#the-json-contract-for-the-sentinel]

`profit_factor` carries the house sentinel: `f64::INFINITY` when there are no losing trades but
some profit, `0.0` when there is neither. In `--json` it is serialized as `null` when non-finite,
so a consumer sees an explicit "no meaningful ratio" rather than a number.

<Callout title="A pin, not a rescue">
  `ser_f64_null_when_nonfinite`'s doc is precise about what it buys. `serde_json` maps a non-finite
  float to `null` on its own (only float map *keys* are an error there), so the custom serializer is
  not rescuing a failure — it pins the mapping as the documented contract, independent of the
  serializer backend, so a format that hard-errors on non-finite floats could not break `--json` on
  a degenerate run.
</Callout>

## Annualization: derived from the interval, not matched against a string [#annualization-derived-from-the-interval-not-matched-against-a-string]

`BacktestReport::from_result(name, result, periods_per_year)` takes the factor `metrics::sharpe`
needs, because the result itself does not carry it. Two constants live beside the struct:
`DAILY_PERIODS_PER_YEAR = 252.0`, the 252-trading-day equity convention for `1d` bars, and
`DEFAULT_PERIODS_PER_YEAR = 252.0`, the fallback for tick runs, kept equal so the Sharpe scale is
at least consistent.

The caller — the `backtest` binary — picks the factor through
`crates/vike-backtest/src/harness/report.rs`'s `periods_per_year(&BacktestProfile)`, the single
source of truth so the single-run binary and the [sweep](/docs/trader/backtesting/sweeps) rank the same
profile on the same Sharpe scale. Its doc records why it is *derived*: Sharpe annualizes by
`sqrt(periods_per_year)`, where the count must be the number of return observations a year
produces — one per bar. It used to return 252 for every interval, so a one-minute run was
annualized as though its bars were daily, understating every intraday Sharpe by
`sqrt(1440) ≈ 37.9×` — silently, because the number still looked like a Sharpe — and making
`--rank-by sharpe` incoherent across a sweep whose points differ in interval.

<Callout type="warn" title="What the rule is now, and its two stated limits">
  The daily anchor is preserved exactly (`1d` still returns the daily constant, so no existing daily
  report moves by a bit) and every other bar interval scales off it by how many of that interval fit
  in a day: `252 · (86_400_000 / interval_ms)` — `1h` gives 6,048 and `1m` gives 362,880. Two limits
  the doc states rather than hides: 252 is the equity convention while these markets trade 24/7, so
  a defensible crypto anchor would be 365 — changing it would move every daily report and is a
  separate decision, so 252 stays and intraday values inherit it. And a tick profile still gets the
  default, because a tick stream has no fixed period. An interval that cannot parse falls back to
  the default rather than fabricating a scale; the [run profile](/docs/trader/backtesting/run-profiles)
  parser is what rejects a malformed interval.
</Callout>

## Reading one [#reading-one]

The [read a backtest report](/docs/trader/guides/read-a-report) guide walks a real table;
[runs on disk](/docs/trader/backtesting/runs-on-disk) covers what else a run leaves behind. The
[tearsheet](/docs/trader/reference/binaries/tearsheet) binary is the live equivalent — it renders the
journal, not a backtest, from the same catalog with a wider field set.


# The result type (/docs/trader/analytics/result)



Every backtest in Vike Trader ends in one type. `crates/vike-analytics/src/result.rs`'s header
calls `BacktestResult` *the one backtest result type*: it unifies the former `RunResult`,
`MultiSymbolResult`, `FastResult` and `PortfolioFastResult` into a flat superset where each
producer fills what it has and leaves the rest empty or zero — decision A of the
engine-unification spec. The [portfolio engine](/docs/trader/backtesting/portfolio-engine), the
[vector engine](/docs/trader/backtesting/vector-engine) and the live tearsheet's reconstruction all
produce this shape, and everything downstream — the [report](/docs/trader/analytics/report), the
[metrics](/docs/trader/analytics/metrics), the zero-trade diagnoser — reads it.

## The core fields [#the-core-fields]

* **`trades`** — the closed trades, as `vike_model::Trade` values. Empty when a kernel runs with
  `build_trades = false`.
* **`equity_curve`*&#x2A; — equity after each bar. &#x2A;*`equity_ts`** carries the bar timestamps aligned
  to it, and is empty when not tracked; the calendar analytics on the
  [periods](/docs/trader/analytics/periods) page need it.
* **`final_equity`*&#x2A; and &#x2A;*`n_trades`** — copied straight into the report.
* **`per_symbol_pnl`*&#x2A; and &#x2A;*`per_symbol_curves`** — multi-symbol event runs only (PnL per
  symbol, and the cumulative curve per symbol); single-symbol and vector runs leave them empty.
* **`intrabar_both_hit`** — event engines only: how many bars saw both the stop-loss and the
  take-profit hit. Kernels leave it at 0. The adverse-first ordering that resolves such a bar is on the
  [fill resolution](/docs/trader/backtesting/fill-resolution) page.

### What a `Trade` is [#what-a-trade-is]

`crates/vike-model/src/position.rs`'s `Trade` is a completed round-trip: `pnl` is *gross price
PnL* and `fees` is the round-trip cost, kept separate. `entry_ts` and `exit_ts` are the fill
timestamps of the opening and closing orders; `symbol` is the originating symbol (empty for the
single-symbol engine); `is_long` is true when the opening side was a buy. `mae` and `mfe` are the
maximum adverse and favourable excursions as fractions of entry price — *portfolio mode only; 0.0
means untracked*. The [excursions](/docs/trader/analytics/excursions) page covers how they are filled
and how they are recomputed from bars when they were not.

## The diagnostic counters, and why they ride on the result [#the-diagnostic-counters-and-why-they-ride-on-the-result]

Several fields exist for one reason the field docs state repeatedly: the `harness` and
`backtest`-bin entry points **drop the engine** once a run finishes, so anything a caller might
need in order to tell "zero trades because the strategy never traded" apart from "zero trades for
a mechanical reason" has to travel on the result. Each is a single copy taken *after* the fold
loop — never new counting on the hot path.

* **`stale_deferrals`** — how many times the opt-in stale-price wait discipline
  (`vike_backtest::EngineParams::max_price_staleness_ms`, the
  [staleness](/docs/trader/backtesting/staleness) page) *deferred* a market order instead of filling
  it against stale data. Always 0 when that knob is `None` (the default) and for every
  vector-kernel run. It separates "the tape never printed" from "the strategy never traded".
* **`session_deferrals`** — how many times the opt-in session gate
  (`EngineParams::session_gate`, the [sessions](/docs/trader/concepts/instruments/sessions) law)
  refused a fill because the venue was closed: resting orders deferred plus tagged-maker and
  armed protective-stop passes skipped. Same defaults, same purpose: "few trades because the venue
  was shut most of the tape" stays distinguishable.
* **`dropped`** — the engine's gate-drop channel (`vike_backtest::SimBroker::dropped`) mirrored
  off the engine at end of run: `(symbol, reason, size, weight)` for every order a gate refused.
  The reasons are the live `RiskGate`'s own strings (`"insufficient-margin"`, `"below-min-qty"`,
  …), order-kind cash-gate drops, `"volume_cap"` and `"latency_reject"`. Empty for every
  vector-kernel run and for any run where nothing was dropped. This is what the
  [zero-trade analyzer](/docs/trader/analytics/sizing-and-zero-trade) reads to say "every order was
  denied".
* **`warmup`** — the strategy's `Strategy::warmup()` requirement, in bars or ticks, captured
  once at end of run; 0 for a strategy with no warm-up and for every vector run. It lets a
  zero-trade run say "the strategy stayed in warm-up the whole window (lookback > bars)".
* **`funding_paid`** — the *net* perp funding cashflow over the run, received-positive and
  paid-negative: the backtest twin of `vike_exec::Account.funding_paid`, broken out of
  `final_equity` because a funding-carry strategy's P\&L is mostly funding and seeing it separately
  matters. `0.0` when no funding was charged, for the tick path (the field doc notes
  `run_ticks` does not yet accrue funding), and for a run whose funding netted to zero. It is
  summed as Σ `MirrorFunding.amount`, the same quantity the R4 parity reconciles against the live
  [account](/docs/trader/concepts/account).

## The one counter that is a measurement, not a channel [#the-one-counter-that-is-a-measurement-not-a-channel]

<Callout type="warn" title="below_min_reversals is expected to stay zero">
  `below_min_reversals` counts fills this backtest executed that the *live* gate would have
  denied — the field doc calls it a measurement of the one known live-vs-backtest divergence still
  open, not a refusal channel. The condition is a below-minimum reversal: an order that opposes the
  position, exceeds it (so it flips through flat), and falls below a venue floor. The simulator's
  opening/closing split is direction-only, so it calls the whole thing closing and executes it; the
  live `RiskGate` requires coverage and refuses.

  Why it should read zero: a flip must exceed the position, so the condition needs
  `|position| < flip < min_qty` — the position must already be below the floor, which an opening
  order cannot produce. Against the real venue grids (the doc cites a `min_notional` of 5.0 for binance
  and bybit and 1.0 for okx) that means reversing a position worth under about $5.
  The counter exists so that reasoning is *falsifiable*: a non-zero reading on a real profile means
  the argument is wrong. It does not need fixing — the obvious repair would change fill decisions
  and, worse, would not converge the two engines. The source is `SimBroker::below_min_reversals`,
  and the "KNOWN RESIDUAL DIVERGENCE" note lives with the live gate in `vike-exec`'s `risk.rs`; the
  [risk and arming](/docs/trader/concepts/risk-and-arming) page carries that side.
</Callout>

## Consumers [#consumers]

`BacktestReport::from_result` composes the [report](/docs/trader/analytics/report) from a result and an
annualization factor. On the live side, the [tearsheet](/docs/trader/reference/binaries/tearsheet)
binary's `LiveTearsheet` builds a `BacktestResult` from reconstructed trades and an aligned equity
curve so that the same functions run over the same shape — the reason the type lives in an
engine-free crate.


# The signal backtest (/docs/trader/analytics/signal-backtest)



`crates/vike-analytics/src/signal_backtest.rs` is about a hundred lines of arithmetic. The event-driven simulator in [backtesting](/docs/trader/backtesting) — orders, a broker, real fee, slippage and adverse-fill semantics — produces the more honest number, and the header says it is the wrong tool for sweeping hundreds of signal variants: reaching a hundred lines should not cost 32,000 lines of simulator.

## The one invariant [#the-one-invariant]

`pnl[t] = position[t − 1] · log_ret[t]`. The position must be the one held *before* the return was known. The header states it as the line everything else rests on: every lookahead bug in a signal backtest is a violation of it.

## The kernels [#the-kernels]

**`apply_min_hold(positions, n_bars)`** locks a position in for `n_bars` after every entry or flip. When the position becomes non-zero at bar `i` — from flat, or by changing sign — bars `i ..= i + n_bars − 1` are forced to that value and any signal change inside the window is ignored, including a flip to the opposite sign; a minimum hold that any opposite signal could break would not be a minimum hold. The comparison against the previous bar reads the already-overwritten output, not the input — deliberate, matching the oracle: a bar forced by a lock is, for detecting the next entry, the position that was actually held.

**`bar_pnl(positions, log_ret, slippage_bps)`** applies the invariant and subtracts `slippage_bps` on every position change. The series starts flat, so entering at bar 0 is charged; so is an exit to flat. A NaN return is `0.0` PnL for that bar, and a change on that bar is still charged. A flip — long straight to short — costs exactly one slippage unit, not two; the doc says that is faithful to the oracle's 0/1 change indicator and is not a bug to "fix". Mismatched lengths truncate to the shorter.

**`equity_from_pnl(pnl)`** is `exp(cumsum(pnl))` from `1.0` at the first bar. A NaN contributes `0.0`, a declared divergence from the pandas oracle at that one bar — pandas emits a hole and resumes; this emits a finite, stale value — reachable only from a hand-built series, since `bar_pnl` never emits NaN. The exponentiation is `libm::exp`, and the crate header records why: the platform's own `exp` differs between the Windows desktop and the Linux boxes by up to one ulp, and this function — the equity curve — was measurably among the casualties, so a backtest's headline number depended on which box ran it.

**`trade_stats(positions, pnl)`** returns a `SignalTradeStats`: `n_trades` counts entries and flips (an exit to flat is not a new trade), `avg_holding_bars` is the mean run length of consecutive identical non-zero positions, and `win_rate` and `avg_pnl` are over non-flat bars only. Pass same-length slices: the first two walk the full position series while the last two walk a zip that truncates to the shorter, so a mismatch computes the two halves over different horizons with no error.

## Two numbers that look like ones you already have [#two-numbers-that-look-like-ones-you-already-have]

<Callout type="warn" title="sharpe_from_bar_pnl is not metrics::sharpe, and max_drawdown_signed is not metrics::max_drawdown">
  `sharpe_from_bar_pnl(pnl, periods_per_year)` is `mean / sd · √periods_per_year` over the PnL directly, with the *sample* standard deviation (`ddof = 1`), and it never exponentiates. `metrics::sharpe` takes an equity curve and derives simple per-bar returns from it. Both are correct in their own vocabulary and they disagree numerically, so the input is in the name — and a test exists solely so that substituting one for the other fails loudly instead of silently moving the headline. `ddof = 1` is load-bearing: it reproduces the oracle's `Series.std()` default, and the survival gate compares the result against a fixed threshold. Fewer than two non-NaN observations, or a zero or non-finite deviation, return `0.0` — zero fails every threshold. `max_drawdown_signed(equity)` is the same story: it returns the oracle's `dd.min()`, negative, and is what the [parity gate](/docs/trader/concepts/parity-gate) compares against 271 stored runs, while `metrics::max_drawdown` returns the positive magnitude the tearsheet renders. Do not unify them: the sign of the second is user-visible.
</Callout>

## The scorer a model search ranks by [#the-scorer-a-model-search-ranks-by]

`SharpeObjective` bundles `bar_returns`, `bands`, `min_hold_bars`, `slippage_bps` and `periods_per_year`; `neg_sharpe_mini_backtest(proba, &objective)` runs the frictioned pipeline verbatim — [`hysteresis`](/docs/trader/analytics/signals) → `apply_min_hold` → `bar_pnl` → `sharpe_from_bar_pnl` — and negates it, so a model search can argmin. It ranks a candidate [model](/docs/trader/research/models) by the Sharpe of a backtest of its own out-of-sample probabilities rather than by calibration against labels, in the frictioned shape so a churny candidate pays for its churn at selection time exactly as it would out of sample. Pass the same `periods_per_year` the reported backtest uses, or the two Sharpes cannot be compared.

<Callout type="warn" title="No evidence scores worst, explicitly">
  A candidate is ranked by its Sharpe only when the mini-backtest produced evidence: it must trade (at least one non-flat bar after the min-hold), and its PnL must have a defined sample Sharpe (at least two bars, positive finite variance). Anything else scores `INFINITY`, the worst an argmin can receive. This cannot be left to `sharpe_from_bar_pnl`, which answers `0.0` for exactly these cases — right for threshold callers, and exactly wrong for an argmin, where `0.0` ranks a candidate that never opened a position above every negative-Sharpe candidate that traded. Not an edge case: with the default 0.75/0.25 entry bands over a hundred-odd-row slice, an all-flat candidate is common, and a search without this rule keeps answering "the model that never trades". A single-trade slice is not degenerate — one entry then holding gives `n − 1` market bars and a defined variance.
</Callout>

Two artifacts a caller accepts by ranking with it, identical for every candidate and so fair across them: the fold starts flat at the slice's first row, and the slice is scored as one series even where it crosses a seam such as an asset boundary. The caller's own per-span folding is the reported backtest; this is a ranking device. The [Rust study](/docs/trader/research/rust-studies) contract honours the rule from the other side: `vike-user-research`'s `StudyOutcome::metric` accepts a non-finite value precisely because this scorer deliberately scores a degenerate slice `INFINITY`, and rounding it to zero would turn a gap into an observation.

## Why the scorer lives here and not with the learner [#why-the-scorer-lives-here-and-not-with-the-learner]

`neg_sharpe_mini_backtest` ranks a model, so `vike-ml` looks like its home. It cannot go there, and the header says that is a merge gate rather than a judgement call: the body names only symbols from this crate and both crates declare `layer = 20`, while `crates/vike-ops/tests/layer_gate.rs` demands a strictly lower layer for every normal `vike-*` dependency (see [architecture](/docs/trader/concepts/architecture)). Which is the right answer anyway — the scorer is arithmetic over a position series and a return series, which is exactly what this module is. The learner side keeps only the choice of which score ranks its candidates.

The [survival statistics](/docs/trader/analytics/survival-stats) take this module's per-bar PnL as their input.


# Signals (/docs/trader/analytics/signals)



A model emits a probability per bar; a strategy holds a position. `crates/vike-analytics/src/signal.rs` is the conversion between them, and the reason it is a shared module rather than a helper inside one study is stated in its header: the offline research converts a concatenated out-of-sample probability series, while a live strategy converts one probability per bar. If those two ever disagree, a forward test silently stops testing what the research measured. So there is one `(state, p) -> state` function and two callers — the same argument that puts the [signal backtest](/docs/trader/analytics/signal-backtest) beside it.

## The bands [#the-bands]

`HysteresisBands` carries four thresholds, and its `Default` is the locked research constants: `entry_long = 0.75`, `entry_short = 0.25`, `exit_long = 0.55`, `exit_short = 0.34`. Entry and exit are deliberately different numbers. Entering long needs `p >= 0.75`, but staying long only needs `p >= 0.55`, so a position does not churn on noise around a single threshold; the gap between them is a dead zone in which the current state is simply held.

## The step [#the-step]

`hysteresis_step(state, p, b)` is one transition. `state` and the result are `-1` (short), `0` (flat) or `+1` (long):

* **From flat:** long if `p >= entry_long`, short if `p <= entry_short`, otherwise flat.
* **From long:** straight to short if `p <= entry_short` — the position does not transit through flat — flat if `p < exit_long`, otherwise still long. At `exit_long` itself the position is held.
* **From short:** straight to long if `p >= entry_long`, flat if `p > exit_short`, otherwise still short. At `exit_short` itself the position is held.

<Callout title="A NaN probability holds the current state">
  NaN means "no estimate this bar" — feature warm-up — and flattening on it would turn missing information into a trade. So a NaN returns `state` unchanged, from every state.
</Callout>

`state` is a bare `i8`, not an enum, so a caller can pass a value outside `{-1, 0, 1}`. Any such value falls into the short arm, mirroring the oracle's `else` branch, rather than being treated as an error or as flat; the contract is that callers only ever pass back a value the function itself returned.

`hysteresis(probs, b)` folds the step over a series, starting flat. State is carried across the whole slice and never reset, so a caller with several assets must call it once per asset or one asset's position leaks into the next. The module's test fixes the reading: `[0.80, 0.60, 0.60, 0.50, 0.20]` with the default bands yields `[1, 1, 1, 0, -1]` — enter at `0.80`, hold through `0.60` twice, exit at `0.50` (below `exit_long`), enter short at `0.20`.

## The other half of the handoff [#the-other-half-of-the-handoff]

This module is the last step of the study-to-strategy handoff, and its header is explicit that the first step has the same hazard. A probability only means what the research measured if the *features* behind it do — and a live strategy computes those per bar while the study computed them as a matrix. That seam is `crates/vike-indicators/src/feature.rs`'s `ColumnFeature`, one layer down, and `crates/vike-indicators/src/test_support.rs`'s `assert_stream_matches_batch` is its gate.

<Callout type="warn" title="Nothing here can detect a feature that drifted">
  A wrong input produces a perfectly well-formed probability. The signal step cannot tell a probability computed from the features the model was trained on from one computed from a subtly different streaming version of them. The feature seam takes the same approach as this one — a single arithmetic, so that disagreement is not expressible: `feature.rs`'s header describes the batch form of a feature as the reference and the streaming form as the batch kernel re-run over a bounded retained tail, and names the one number left to get wrong, `ColumnFeature::reach`, how many trailing values the streaming form must retain. Declared too small, the streamed value is computed from a truncated history — silently, and past a threshold no short test reaches. That header records six indicators shipping with exactly that defect, green because the parity gate ran 400 bars while the trim first fired at 512. The [indicators](/docs/trader/indicators) catalog carries the streaming-equals-batch guarantee that now holds.
</Callout>

## Where it is used [#where-it-is-used]

The step is what a probability-driven strategy calls per bar after [inference](/docs/trader/research/inference); the fold is what a study calls over its out-of-sample series, and what the [signal backtest](/docs/trader/analytics/signal-backtest)'s model-selection scorer runs first, before the minimum hold and the per-bar PnL. Both callers reach the same function, which is the whole point.


# Sizing, and zero-trade diagnosis (/docs/trader/analytics/sizing-and-zero-trade)



Two modules of `vike-analytics` that serve the simulator rather than the tearsheet: `sizing.rs`, the sizer a backtest applies to every opening entry, and `zero_trade.rs`, the diagnosis a report prints when a run did nothing at all.

## Sizing [#sizing]

`crates/vike-analytics/src/sizing.rs` is the swappable sizer framework, an exact port of the original `core/sizing.py`. A sizer implements `PositionSizer` — one method, `size(&self, ctx: &SizeContext) -> f64`, returning the quantity (at or above zero) to open for one entry intent. The trait is `Send`-bounded so a `Box<dyn PositionSizer>` can ride inside `EngineParams` onto a worker thread; every shipped sizer is plain data, so that costs nothing.

`SizeContext` is the live portfolio context handed in for one entry: `symbol`, `side` (`+1` buy, `-1` sell), `intent` (the raw size the strategy passed — used only by the pass-through sizer), `basis_price` (the current close), `equity`, `cash`, `multiplier`, `atr` (recent average true range, `0` when unavailable), `drawdown` (the account drawdown fraction, `0..1`), `risk_stop` (the protective stop for this entry, which the risk sizers need), and `open_risk` (the dollar risk already open across the book, for portfolio-heat caps).

The eight sizers:

| sizer                                                | quantity                                                                                                                                                                                                                         |
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PassThroughSizer`                                   | `intent`, unchanged — the default                                                                                                                                                                                                |
| `FixedDollarSizer { amount }`                        | `amount / (basis_price · multiplier)`; `0` when the denominator is zero (a negative one is allowed, as in the port)                                                                                                              |
| `FixedSharesSizer { shares }`                        | `shares`                                                                                                                                                                                                                         |
| `PctEquitySizer { pct }`                             | `pct · equity / (basis_price · multiplier)`                                                                                                                                                                                      |
| `PctVolatilitySizer { pct }`                         | `pct · equity / (atr · multiplier)` so the position's ATR-risk is `pct` of equity; the percent-equity formula when ATR is `0`                                                                                                    |
| `MaxRiskPctSizer { pct }`                            | `pct · equity / risk_per_unit` with `risk_per_unit = abs(basis_price − stop) · multiplier`; `0` without a stop                                                                                                                   |
| `PortfolioHeatSizer { base, max_heat }`              | wraps a base sizer and caps total open risk to `max_heat · equity`: the budget is `max_heat · equity − open_risk`, `0` if exhausted, and the base quantity is clipped to `budget / risk_per_unit`; passes through without a stop |
| `DrawdownThrottleSizer { base, sensitivity, floor }` | wraps a base sizer and scales by `max(floor, 1 − sensitivity · drawdown)`                                                                                                                                                        |

The two pure unit converters — `units_from_percent` and `units_from_value` — are not here: they moved to `vike_model::sizing` so the live `order_target_*` verbs share the one sizing law with the backtest engines, and call sites spell `vike_model::` directly.

**Where it runs.** `vike_backtest::EngineParams::sizer` is an `Option<Box<dyn PositionSizer>>`; when it is `None` the engine installs `PassThroughSizer`. `SimBroker::size_entry` runs the sizer on opening or increasing entries only and passes the size through when the submission is raw or reducing, building the context from the current price, the 14-bar ATR, `drawdown = max(0, 1 − equity/peak)` and the summed open risk. The [sim broker](/docs/trader/backtesting/sim-broker) page covers the fill side.

<Callout type="warn" title="The sizer is an engine-only concept. Live has nothing for it to be portable to.">
  `crates/vike-backtest/src/ref_strategies.rs` lists the sizer first among the concepts that bind a strategy permanently to the simulator: it lives in `SimBroker::submit`'s `raw = false` arm, and the live path is always raw. Its `CapsSizersMask` reference strategy submits a size of `999.0` as a sentinel, relying on a `DrawdownThrottleSizer { base: PctEquitySizer }` to ignore `intent` entirely; submitted through the portable `Broker::submit_market`, which is `raw = true`, that sentinel would be taken literally. A strategy that leans on a sizer is a [simulator-only strategy](/docs/trader/strategies/simulator-only) by construction.
</Callout>

`crates/vike-analytics/tests/sizing_props.rs` holds the sizers to their contract with property tests over random but valid inputs — positive prices and multipliers, non-negative equity, fractional percentages — after finding that `size` had zero direct tests and only one golden run touched it. Every sizer must return a finite, non-negative quantity, and the two cap properties carry only a few-ULP round-trip epsilon, never a fudge factor. See [property tests](/docs/trader/developer/testing/property-tests).

## Zero-trade diagnosis [#zero-trade-diagnosis]

When a run closes zero trades and its equity curve never moves off the starting cash, the bare metrics table — total return 0%, Sharpe NaN, drawdown 0% — says nothing about *why*. `crates/vike-analytics/src/zero_trade.rs` is a pure, report-side composition over diagnostic counters the engine already accumulates on the [result](/docs/trader/analytics/result); it adds no counting to any fill lane.

**The trigger.** `ZeroTradeReport::analyze(&result)` returns `None` for any run that closed a trade or moved equity — "flat" is exact equality with the first value, which is correct because an idle run's equity is cash bit-for-bit every step, and an empty curve counts as flat. So a buy-and-hold run, with zero *closed* trades but a real marked position, is deliberately not flagged: its equity moved. The [report](/docs/trader/analytics/report) carries the result as `BacktestReport::zero_trade`, skipped on serialization when `None`, and its `Display` prints the diagnosis *instead of* the all-zero metrics table — a normal report is byte-identical to before the field existed.

**The inputs.** `ZeroTradeInputs` mirrors five things the run already recorded: `steps` (the equity-curve length — bars or ticks processed), `stale_deferrals` and `session_deferrals` (`BacktestResult`'s counters from the [stale-price wait](/docs/trader/backtesting/staleness) and the session gate), `denials` (the gate-drop channel `BacktestResult::dropped`, aggregated by reason in first-seen order by `aggregate_denials` — the live `RiskGate`'s own reason strings, cash-gate drops by order kind, `"volume_cap"`, `"latency_reject"`), and `warmup` (the strategy's warm-up requirement).

**The ranking.** `rank_causes` is deterministic, does no I/O, and always returns at least one cause, most probable first. Structural certainties lead with sentinel weights: `no-data` when `steps == 0`, else `warmup-shortfall` when `warmup >= steps` — the dispatch gate never opened, so `on_bar`/`on_tick` ran zero times; the default warm-up of `0` can never trip it. Then the "tried but was blocked" signals, each weighted by how many orders it blocked: `orders-denied`, with the reasons rendered largest-first; `stale-price`; `session-closed`. Ties keep that push order, because the sort is stable. When nothing fired, the single catch-all `no-orders` says so and carries the one hint the result cannot disambiguate: the strategy most likely never submitted, and in bar mode `snap_to_properties` re-tags bars as `SYMBOL.VENUE`, which a strategy routing on the bare symbol will miss.

<Callout title="A vector-kernel run can only ever be no-data or no-orders">
  `BacktestResult`'s doc states that `stale_deferrals`, `session_deferrals`, `dropped` and `warmup` are all zero or empty for every vector-kernel run. The [vector engine](/docs/trader/backtesting/vector-engine) therefore hands the analyzer nothing but a step count, and a flat vector run diagnoses as `no-data` when the slice was empty and as the catch-all otherwise.
</Callout>

Each `ZeroTradeCause` carries a stable kebab-case `code`, a one-line `headline` and an actionable `detail`; the `Display` form numbers them under "no trades executed - probable cause(s), most likely first:", and the JSON form serializes `causes` as an array.


# Stability (/docs/trader/analytics/stability)



An optimizer returns the best point. A parameter-stability graph shows what surrounds it: a broad plateau where the neighbouring configurations perform nearly as well, or a lonely spike where one configuration wins and its neighbours do not. The plateau is robust and the spike is fragile — a spike is the signature of a parameter fitted to the noise of one sample. `crates/vike-analytics/src/stability.rs` quantifies that reading into one number and one word.

## The score [#the-score]

`parameter_stability(scores, top_frac)` takes the trial scores of a sweep, in any order, and returns a value in `[0, 1]`. Only a plain score list is needed — no optimizer, no trial-generation machinery, nothing about which parameters produced which score. Any sweep that yields a scalar per point is an input; a [sweep](/docs/trader/backtesting/sweeps) ranked by an [objective](/docs/trader/backtesting/objectives) is the natural one.

The procedure, from the module header:

1. Sort the scores best-first.
2. Take the top `top_frac` fraction of trials as the neighbourhood of the optimum — at least one trial, however small the fraction.
3. Compute the plateau ratio: `mean(top scores) / best_score`.
4. Clamp to `[0, 1]`.

A ratio of `1.0` means every score in the neighbourhood equals the best — a flat plateau. A ratio near `0.0` means the neighbourhood averages far below its peak — an isolated spike. Zero or one trial returns `1.0`, since there is no evidence of spikiness to report. The module's own tests fix the reading: `[10, 10, 9.9, 9.8, 9.7, 1.0]` at `top_frac = 0.25` scores at least `0.9`, while `[10, 1, 1, 1, 1, 1, 1, 1]` at `top_frac = 0.5` takes the top four — `[10, 1, 1, 1]`, mean `3.25` — for a ratio of `0.325`.

Negative scores are handled by sign: the ratio is inverted as well as negated — `(−best) / (−mean)` — so that "least negative" reads as best, and a negative plateau such as `[−1, −1.1, −1.2, −1.3, −10, −20]` still scores at or above `0.8`. A best score of exactly zero returns `1.0` when the neighbourhood mean is also zero and `0.0` otherwise, and never divides.

<Callout title="The neighbourhood count is rounded the oracle's way">
  `k = round(n · top_frac)` is computed with the module's `round_half_even` — round-half-to-even, the behaviour of Python's `round()` — not with `f64::round`, which rounds half away from zero. The doc is explicit about why: `k` must match exactly, or the number of trials entering the "top" neighbourhood silently diverges from the oracle the port was verified against. `2.5` rounds to `2`; `1.5` rounds to `2`; `0.75` rounds to `1`.
</Callout>

## The label [#the-label]

`stability_label(stability)` turns the score into a word: `"plateau"` at or above `0.8` (a broad, robust optimum), `"ridge"` at or above `0.5` (moderate sensitivity), and `"spike"` below that (a fragile, likely overfit optimum). The boundaries are inclusive at the top of each band — `0.8` is a plateau, `0.79` a ridge, `0.5` a ridge, `0.49` a spike.

## How to read it beside the other gates [#how-to-read-it-beside-the-other-gates]

Stability is a statement about the *shape of the sweep*, not about the significance of any one result. A plateau says the strategy's behaviour does not hinge on a precise parameter value; it does not say the plateau is above zero. That is the job of the [deflated Sharpe and the probability of backtest overfitting](/docs/trader/analytics/overfitting), which take the same sweep and ask whether its winner beats what a search of that size produces from noise. Read them together: stability says whether the result depends on hitting one parameter value, and the deflated Sharpe says whether the result is distinguishable from what the search would have found in noise.


# Survival statistics (/docs/trader/analytics/survival-stats)



The [metrics catalog](/docs/trader/analytics/metrics) answers "what was the Sharpe". `crates/vike-analytics/src/stats.rs` answers the question that catalog cannot: would this Sharpe survive its own autocorrelation, and the fact that it was selected as the best of many? Four pure functions over `&[f64]`, written for signal research — where hundreds of variants are swept and the survivors need to be more than lucky.

## The t-statistic [#the-t-statistic]

`newey_west_tstat(x, lag)` is the Bartlett-kernel Newey–West t-statistic for the mean of an autocorrelated series: `V = γ₀ + 2 Σ (1 − k/(L+1)) γₖ` over lags `1..L`, then `t = mean / √(V/n)`, with `L = min(lag, n − 1)`. A per-bar PnL series is autocorrelated by construction — a position held for many bars earns correlated returns — so the ordinary t-statistic overstates significance. This is the correction, and `lag` should be at least the holding horizon. NaNs are dropped, not propagated. A degenerate input (fewer than two observations, or a non-positive long-run variance) returns `0.0` rather than a NaN or an infinity: callers compare against a threshold, and zero fails every threshold, which is the safe direction. The test pins the arithmetic: `[1, 2, 3, 4]` at lag `1` gives exactly `4.0`.

`two_sided_p(tstat)` converts it: `2 · (1 − Φ(|t|))`, using the normal rather than Student's t because these series are thousands of bars long, where the two agree to well past any threshold anyone gates on. A NaN statistic maps to `1.0`; `1.96` lands on the familiar `0.05`.

## The false-discovery correction [#the-false-discovery-correction]

<Callout type="warn" title="Sweep 300 variants at a 0.05 p-value and you keep about fifteen from noise alone">
  `bh_fdr(pvalues, q)` is the Benjamini–Hochberg step-up procedure. It controls the expected false-discovery rate — the share of rejections that are wrong — at `q`, and returns a rejection mask in the caller's order. Step-up is the part worth understanding: it finds the largest rank `k` whose sorted p-value is at or below `q·k/n`, then rejects every hypothesis at rank `k` and below. A middling p-value can therefore be rejected on the strength of the ones beneath it. The doc says so directly: that is the intended behaviour and not a bug to "fix". The test pins it — `[0.001, 0.08, 0.09]` at `q = 0.10` rejects all three, where rank two fails its own threshold and rank three passes.
</Callout>

## The block bootstrap [#the-block-bootstrap]

`block_bootstrap_sharpe(pnl, block_len, n_resamples, periods_per_year, seed)` returns the 5th and 95th percentiles of the annualized Sharpe over resamples built from fixed-length contiguous blocks — Kunsch's moving block bootstrap. Resampling individual bars would destroy the autocorrelation that makes a signal's Sharpe uncertain in the first place and would report a falsely tight interval; contiguous blocks of `block_len` bars preserve the local dependence structure. The test makes the point concrete: an alternating `±1bp` series resampled in blocks of two has every block summing to exactly zero, so every resample's Sharpe is `0.0`, which a per-bar bootstrap could not do 200 times. A series shorter than one block plus a bar returns `(0.0, 0.0)`: there is nothing to resample, and inventing an interval would be worse than declaring none.

Two honesty notes from the doc itself. The stationary bootstrap is a different procedure — geometric block lengths, wrapping at the series end — and is not what this function does; the name was corrected rather than reused. And the Sharpe inside the resample uses the *population* standard deviation, while [`sharpe_from_bar_pnl`](/docs/trader/analytics/signal-backtest) uses the sample form: not an inconsistency to fix, because one is a point compared against stored oracle numbers and the other is an interval that was never required to match anything.

## The reality check [#the-reality-check]

`hansens_spa(pnl_matrix, n_resamples, block_len, seed)` answers what a per-signal t-statistic cannot: given that the best of `k` candidates was *selected* as the best, is its performance still surprising? `pnl_matrix` is column-major, one inner vector per candidate, rows aligned by bar; shorter columns are truncated to the shortest. Each column is centred at its own mean, making the null "every candidate has zero expected PnL"; the maximum Sharpe across candidates is redrawn under that null by block bootstrap; and the p-value is the share of draws whose maximum matches or beats the observed one. An empty panel or a series shorter than one block returns `1.0` — reject nothing.

<Callout title="One index sequence, shared by every column">
  Candidates are resampled in lockstep. Independent per-column draws would destroy the cross-sectional dependence between candidates, make the maximum over columns stochastically larger, inflate the null distribution and cost the test power. The test pins it by duplicating a column: the p-value does not move.
</Callout>

What this computes is the recentred bootstrap max-statistic test — White's Reality Check on the maximum Sharpe — not the studentized variant, which standardizes each candidate by its own bootstrap variance before taking the maximum. The doc keeps the name because it is the module's public API, not because it promises the studentized form.

## Reproducibility [#reproducibility]

Seeded streams here reproduce run to run within this implementation, and are deliberately not required to match any other library's generator: reproducing an exact stream buys nothing a confidence interval consumes. Consumers use the interval, not its last digits. Cross-platform determinism is a separate matter and was a real defect: `crates/vike-analytics/tests/libm_platform_probe.rs` records that the variance folds in `block_bootstrap_sharpe` and `hansens_spa` were written as `powi(2)`, which one toolchain lowers to a platform `pow()` call in a `dev` build, so the same input hashed differently on two boxes. They are explicit multiplications now, and the two functions carry rows in that probe's `PLATFORM_INVARIANT` table.

## Related [#related]

The [deflated Sharpe](/docs/trader/analytics/overfitting) is the closed-form answer to the same selection question, for equity curves rather than signal panels. [Monte Carlo](/docs/trader/analytics/monte-carlo) resamples trade P\&L rather than bar blocks. The per-bar PnL these functions consume comes from the [signal backtest](/docs/trader/analytics/signal-backtest).


# Validation (/docs/trader/analytics/validation)



Ordinary cross-validation shuffles observations. On a time series that is a way of training on the future, so `crates/vike-analytics/src/validation.rs` provides the splitters that respect time: walk-forward windows, purged k-fold, and combinatorial purged paths, ported from chapter 7 of *Advances in Financial ML*. Every splitter returns index ranges over a series of length `n`; nothing here touches bars or returns. They are the machinery behind [walk-forward](/docs/trader/backtesting/walk-forward) and the [probability of backtest overfitting](/docs/trader/analytics/overfitting).

## The embargo, and which side of the block it sits on [#the-embargo-and-which-side-of-the-block-it-sits-on]

The header states the one modelling decision that shapes every purged splitter, and states only that: the embargo removes a window *after* each test block from training, because the observations are point-in-time, so there is no label overlap reaching backwards and no pre-block purge. Why the window sits on that side at all is not something the module says; the usual reason for an embargo is that a serially correlated series would otherwise leak the test period's information into a "future" training row, and that is the reading this page takes.

## Walk-forward by count [#walk-forward-by-count]

`walk_forward_splits(n, n_splits, mode)` divides the series into `n_splits + 1` chunks of `n / (n_splits + 1)` and returns one `Split` per test chunk from the second chunk on; the last split's test window runs to `n`. A `Split` is four indices with half-open semantics — train is `[train_start, train_end)`, test is `[test_start, test_end)`, and `train_end == test_start`. `WalkMode` picks the training window: `Anchored` is the expanding window, with `train_start` always `0`; `Rolling` is a fixed-width window of exactly one chunk immediately preceding the test window.

The module's test pins the shape: `n = 100`, four splits, chunk `20`. The first split trains on `[0, 20)` and tests on `[20, 40)`; the last anchored split trains on `[0, 80)` and tests on `[80, 100)`, while the last rolling split trains on `[60, 80)`. This is the splitter `vike_backtest::walkforward::walk_forward_strategy` calls to run a strategy over each out-of-sample window and stitch the windows into one equity curve; its `WalkForwardReport::wf_consistency` — the fraction of windows profitable out-of-sample — is the walk-forward input to `overfit_verdict`.

## Walk-forward by duration [#walk-forward-by-duration]

`purged_walk_forward_hours(n_hours, train_hours, val_hours, step_hours, purge_hours, expanding)` is the sibling parameterised by duration rather than by split count, because a research protocol is specified that way — "train on 14 days, validate the next 24 hours, step a day" — and converting that to a count depends on how much history happens to exist. It returns the same half-open `Split`.

<Callout type="warn" title="purge_hours must cover the forecast horizon">
  `purge_hours` is the gap between the end of training and the start of validation, and it exists because the labels are forward-looking: a row at time `t` carries the return realised at `t + H`, so the last `H` hours of any training window have labels that reach into the validation window. Without the gap the model is trained on the answer. Set `purge_hours` to at least the horizon. Because the boundaries are half-open, `test_start − train_end == purge_hours` exactly; a `purge_hours` of `0` leaves train and test contiguous with no skipped row, matching `walk_forward_splits`.
</Callout>

`expanding` anchors `train_start` at `0` and grows the window; otherwise the window slides at a fixed length. The doc's own reading: sliding is the more honest form for "the model adapts to the recent regime"; expanding gives later folds more history. Edge cases are stated rather than left to chance: a zero `n_hours`, `train_hours`, `val_hours` or `step_hours` yields an empty vector instead of a panic or an endless loop, and a trailing validation window that would run past `n_hours` is dropped rather than truncated. The pinned example is `(100, 24, 10, 10, 5, false)`: seven splits, the first `{0, 24, 29, 39}` and the last `{60, 84, 89, 99}`.

## Purged k-fold [#purged-k-fold]

`purged_kfold_indices(n, k, embargo)` cuts the series into `k` contiguous test folds and, for each, returns `(train, test)` index lists where train excludes the test fold and an embargo window of `embargo` observations after it. The test pins `n = 10`, `k = 2`, `embargo = 1`: fold 0 tests on `0..5`, and its training set is `[6, 7, 8, 9]` — index `5` is the embargo.

## Combinatorial purged paths [#combinatorial-purged-paths]

`combinatorial_purged_splits(n, n_groups, n_test_groups, embargo)` generates every way of choosing `n_test_groups` of `n_groups` contiguous groups as the test set — `C(n_groups, n_test_groups)` paths, six for `C(4, 2)` — with a per-test-group embargo applied after each chosen group. The enumeration comes from the module's `combinations(n, k)`, which yields all index combinations of `0..n` in lexicographic order (`k = 0` gives one empty combination, `k > n` none) and is the same helper `overfit::pbo_cscv` iterates for its in-sample/out-of-sample paths.

## Choosing among them [#choosing-among-them]

By count when a fixed number of out-of-sample windows is what you want reported; by duration when the protocol is written in hours and the series length should not change the fold geometry. Purged k-fold and the combinatorial paths take everything outside the fold and its embargo as training, so most of their folds train on rows both before and after the test window — the pinned `n = 10`, `k = 2` example trains fold 0 on `[6, 7, 8, 9]`, rows later than its test block. Only the last fold (and the one combinatorial path whose test groups are the final ones) tests on a window strictly later than all of its training data. They yield many train/test paths from one series; walk-forward yields one per window, each trained only on what came before it. `walkforward.rs`'s header calls the walk-forward form "the honest way to backtest" a strategy without comparing it to the other two, so that contrast is this page's reading, not the header's.


# The cost model (/docs/trader/backtesting/cost-model)



`crates/vike-fills/src/broker_sim.rs` is, in its own words, the canonical cost model: **one**
definition of fills, fees and funding, an exact port of the Python oracle's `core/broker_sim.py`.
Three functions, three conventions, and one floor. The [sim broker](/docs/trader/backtesting/sim-broker)
and the [vector engine](/docs/trader/backtesting/vector-engine) charge through all three; the
[paper exchange](/docs/trader/concepts/paper-exchange) charges through the adverse fill price and the
fee only, and has no funding path at all. One shared definition behind all three consumers is why
the scalars live in `vike-fills` — a crate below both the simulator and the paper client rather
than a copy in each.

The conventions come from the header: `side_sign` is `+1` for a buy and `−1` for a sell;
`multiplier` scales every notional term; slippage is **adverse** — buys fill up, sells fill down.

## The three scalars [#the-three-scalars]

**`adverse_fill_price(raw_price, side_sign, slippage)`** is multiplicative:
`raw × (1 + side_sign × slippage)`, with the factor floored at `MIN_ADVERSE_FACTOR` so it can
never carry the price through zero.

**`fee(size, price, rate, multiplier)`** is `rate` on the multiplier-scaled notional:
`size × price × rate × multiplier`.

**`funding_charge(pos_size, mark_price, funding_rate, multiplier)`** is the perp funding cash
flow for a held position, `pos_size × mark_price × funding_rate × multiplier` — longs pay
positive funding, shorts receive.

## Where the slippage number comes from [#where-the-slippage-number-comes-from]

The engine hands `adverse_fill_price` a fraction, and `SimBroker::slippage_for` is the site that
decides it. Its doc promises a byte-identical default: with no impact model configured it returns
the `slippage` field itself — the same `f64`, with no arithmetic performed on it — because adding
a zero is not the identity on `−0.0`, and a parity gate is not the place to find that out. With a
[market-impact model](/docs/trader/backtesting/market-impact) configured, the size-dependent estimate
is **added** to the flat `slippage` for taker fills. Maker fills are exempt from the addend: an
order that rested and got hit was supplying liquidity, and charging it impact would fill a
resting limit through its own limit price. The flat `slippage` still applies to makers exactly as
it did.

Fees have their own precedence on `EngineParams`: `maker_fee` and `taker_fee` fall back to the
flat `fee_rate`, and an optional `fee_schedule` overrides that whole chain — with one shape,
`ProbabilityScaled`, routed to the exact per-fill `FeeSchedule::commission` because it has no
flat equivalent. A [run profile](/docs/trader/backtesting/run-profiles) refuses `[engine.fee]` beside
a non-zero `fee_rate`: two cost models would be configured and only one could win.

## The one deviation from the port [#the-one-deviation-from-the-port]

The header devotes most of its length to a single change, because it is the only place the Rust
arithmetic departs from the Python original. The original bounded neither operand of the
multiplication, and an adverse fraction at or past `1.0` on the losing side does not saturate —
it **inverts**: a sell of a positive quote comes back negative (raw `100`, `side_sign −1`,
slippage `1.5` → `−50`). `vike_model::round_to` preserves the sign, and the wrong-signed price
then flows into the notional floor, the fee, the cash flow, the position's average price and the
equity curve. Nothing downstream re-checks it.

<Callout type="warn" title="That regime is reachable, not hypothetical">
  `SimBroker::slippage_for` returns `slippage + impact_frac(..)`, and the impact addend is bounded
  below — a cost is never negative — but never above. The header quotes the measurement: the
  Almgren–Chriss model crosses `1.0` at roughly **18× the window's mean bar volume** once the
  measured per-bar sigma reaches &#x2A;*20 %**, and a thin resampled series produces both halves of that
  routinely.
</Callout>

The fix is a floor on the **factor**: `MIN_ADVERSE_FACTOR = 0.01`, the smallest factor the
function will ever multiply a quoted price by, so the adverse move saturates once it has consumed
99 % of the price. Its doc says which property is load-bearing — it is strictly positive, which
is the whole reason the fill cannot change sign — and that the magnitude is a policy choice: far
above any move that could still be economically meaningful, so it binds only on an estimate that
has already stopped meaning anything, and far enough from zero that the saturated fill is a
usable double rather than dust that would silently re-route through `SimBroker::apply_fill`'s
min-notional floor and turn a saturation into a dropped order.

The floor lives here and nowhere upstream because this is the only function that holds both
operands of the inversion, and every producer of a slippage number funnels through it — the flat
field, `slippage_for`'s impact sum, the engine's cash pre-check, the vector kernel and the paper
exchange. A floor inside an impact model could not work at all: a model never sees the flat
`slippage` it is added to, nor the side that decides which way the move points.

## What the floor does and does not do [#what-the-floor-does-and-does-not-do]

It **saturates rather than repairs**. A run that reaches the floor has a cost model whose output
stopped being a cost, and the fill it then books — 1 % of the quote — should look ruinous,
because it is. `SimBroker::slippage_saturations` counts the fills where the floor bound, so such
a run can say so; its doc notes that the counter is not yet mirrored onto `BacktestResult` the
way the deferral counters are, so the harness and the `backtest` bin cannot read it — a strategy
reads it off its context.

It floors the factor, **not the price**, so the fill keeps the sign of the quote it was priced
off: a genuinely negative quoted price — this workspace ships futures and EOD backfills, and
`vike_model::gross_notional` refuses to `.abs()` such prices away — passes through untouched.
It is byte-identical wherever it does not bind: the same two `f64` operations in the same order,
never contracted into a fused multiply-add, with the branch taken only where the frozen path
produced a zero or sign-flipped fill. And NaN is deliberately not caught — `factor <= 0.0` is
false for NaN, so a NaN slippage still yields a NaN price, because a NaN is a different defect
from an inversion and swallowing it would reintroduce the silent behaviour the floor exists to
remove. `adverse_move_saturates` exposes the predicate so a caller can count a saturation without
re-spelling the factor.


# Fill models (/docs/trader/backtesting/fill-models)



A fill model answers one question: given a resting order and the event that just arrived, at what
raw price does it fill, if at all. `crates/vike-fills/src/fill_model.rs` ships three tiers,
selected by the data available, and its header states the boundary every tier respects: each
returns a **raw** price, and the engine still applies `adverse_fill_price` slippage and routes the
fill through `compute_fill`, so parity is preserved. The models live in `vike-fills` rather than
in the backtester because the [paper exchange](/docs/trader/concepts/paper-exchange) is built from the
same primitives.

## The three tiers [#the-three-tiers]

**`BarFillModel`** — no ticks. It delegates to `order_fill_price`, the fill-trigger oracle in
`vike-model` that the live conditional-order emulator shares, and is the pre-tick behaviour.

**`TickFillModel`** — L1 quote bars. Market orders cross the real spread — buy at the ask, sell at
the bid — whenever the bar carries bid and ask; single-quote-tick bars (`high == low`) trigger
resting orders off the quote side; consolidated bars delegate to the bar oracle.

**`L2BookFillModel`** — L1 plus an L2 book. A taker is priced by **consuming the resting book**,
not by reading one tick price. The header calls it the R8 tier the sim-broker docs had named as
the follow-up since the queue model landed.

## Why the book tier exists [#why-the-book-tier-exists]

The header argues it as an engine defect, not one strategy's bug. Every tier above the L2 one
prices a taker at a price **nobody was offering**: `TickFillModel` fills a market buy at
`bar.ask` — the top of book, at any size — and on a trade-tick tape with no quotes it falls
through to the print, the price at which somebody *else* already took the liquidity. A taker can
obtain neither. The error is one-directional, always in the strategy's favour, and it scales with
size, because top-of-book is exactly the cheapest share on the ladder.

The measurement: on the Polymarket `btc-updown-5m` tape over 835 entries (`cheap_np_depth`), the
tape print averaged **0.2683** while the resting best ask at the same instant averaged **0.3063**,
and in 738 of 835 cases there was no resting ask at the printed price at all — roughly 4 cents
per share on a strategy whose whole edge bar is 5.5 cents. Any strategy that takes liquidity on
the tick path is mispriced the same way, which is why the fix lives in the engine.

## What the L2 tier changes, and what it deliberately does not [#what-the-l2-tier-changes-and-what-it-deliberately-does-not]

`L2BookFillModel`'s doc splits the question in two. **When** an order fills is unchanged:
`TickFillModel` decides it, including the stop and trailing trigger arithmetic and its `extreme`
bookkeeping. **What price** it fills at is re-derived by `book_taker_price`: the VWAP of
consuming the resting book for the order's own size, best level outward. A resting limit
additionally caps the walk at its own limit price, so it can only be filled by liquidity it
would genuinely have crossed.

Two properties follow. *No book, no change*: with no book this tier **is** `TickFillModel`, byte
for byte, so mixing a book-carrying symbol and a bookless one in a single run is well-defined
rather than silently lossy. And *insufficient depth does not fill*: when the displayed book
cannot cover the order's size — within its limit, if it has one — the order does not fill on
this event and stays resting, waiting for liquidity. That is the one behavioural difference a
strategy will notice, and the honest one; the alternative is to fill size the market never
showed. It also gives the tier the venue semantics it was built for: an order that is marketable
when the strategy decides and no longer marketable when the matching engine looks at it **rests
on the book** rather than filling or vanishing. Composed with a
[latency model](/docs/trader/backtesting/latency-models), the "decide at T, match at T + Δ" rule falls
out of machinery that already exists.

`book_taker_price` itself is hoisted to `vike_model::book_taker_price`. Its doc gives the
reason: the taker-price law is a property of an order book, not of a simulation, and the live
path needs the same rule — pre-trade sizing, a paper executor on a live feed, comparing realised
fills against the model. `vike-backtest` is a sibling of the live path, not below it, so the
shared home in `vike-model` is what lets both sides share one definition instead of drifting
apart silently.

## Selecting a tier [#selecting-a-tier]

`FillModelKind` in `crates/vike-backtest/src/engine/sim_broker.rs` is the selector: `Bar` (the
`EngineParams` default), `Tick`, and `L2Book`. The `L2Book` variant's doc states its requirement
and its guarantee: it needs a tape carrying `Tick::Book` events, degrades to `Tick` wherever no
book exists, and is reached only by asking for it, so selecting `Bar` or `Tick` is byte-identical
to the engine before the variant existed. The book it prices from is `SimBroker`'s per-symbol
replay book, which is empty except while `run_ticks` replays a tape carrying book events and is
folded under `L2Book`'s delta law — see [tick replay](/docs/trader/backtesting/tick-replay).

<Callout type="warn" title="Pair the book walk with zero flat slippage">
  The walk **is** the slippage. `FillModelKind::L2Book`'s doc and `EngineCfg::fill_model`'s both
  say to set `slippage = 0.0` beside it: stacking the flat `adverse_fill_price` haircut on top
  would charge the same cost twice.
</Callout>

In a [run profile](/docs/trader/backtesting/run-profiles) the knob is `fill_model = "l2book"` in
`[engine]` — the one accepted value, case-insensitive, tick mode only. Absent means `Tick`,
byte-identical. `EngineCfg::fill_model_kind` treats any other spelling as a fail-fast validation
error at load, for a reason its doc names: a typo like `"l2_book"` must not silently select the
optimistic `Tick` model and undo the depth-cap it was meant to enable. Whether a resting limit
at a touched price has actually reached the front of the queue is a separate opt-in on the same
lane — [the queue lane](/docs/trader/backtesting/queue-lane).


# Fill resolution (/docs/trader/backtesting/fill-resolution)



OHLC cannot reveal the sequence inside a bar. When several resting orders trigger on the same
bar, the engine has to choose an order to apply them in, and the choice changes the result: a
stop and a take-profit that both lie inside the bar's range cannot both have filled against one
position. `crates/vike-fills/src/fill_resolution.rs` is the one shared answer — an exact port of
the Python oracle's `resolve_intrabar_fills` — and its header states the two rules.

## Adverse first [#adverse-first]

Apply **adverse** fills (stop and trailing) before **favourable** fills (limit). That is the
pessimistic ordering: when the data cannot say which side of the range the price reached first,
the engine assumes the side that hurts. `resolve_intrabar_fills` takes the `(order, fill_price)`
pairs that triggered this bar together with the position size **before** any of them, and
returns the pairs sorted adverse-first.

## The bracket cap [#the-bracket-cap]

When more than one order **reduces** the current position in the same bar — an SL + TP bracket —
the total reduction is capped to the position size, adverse-first, so the profit target cannot
also fill after the stop has already flattened the position. The returned sizes are the
bracket-capped ones.

The ambiguous bar is not silently resolved. The function returns `both_hit` — `1` when the cap
applied this bar — and the header says why: it is surfaced on the result for honesty.
`BacktestResult::intrabar_both_hit` in `crates/vike-analytics/src/result.rs` is the counter,
described there as event-engine only; the vectorized kernel leaves it at `0`. A run whose stops
and targets kept landing in the same bar is a run whose bar interval is too coarse for its
brackets, and the count is how you find that out from the [result](/docs/trader/analytics/result).

## Where it runs [#where-it-runs]

The step is part of every event-engine fill pass. `fill_pending_tick_queued`'s doc gives the
shape of the tick lanes as trigger → **resolve** → dispatch → tagged lane, the resolve being this
function; the [queue lane](/docs/trader/backtesting/queue-lane) inherits it unchanged from the frozen
path it mirrors. The [paper exchange](/docs/trader/concepts/paper-exchange) is built from the same
`vike-fills` primitives, which is the point of the function living there: one definition of what
happens on an ambiguous bar, on both sides of the backtest-equals-paper law.

<Callout title="Frozen arithmetic">
  `vike-fills` was extracted verbatim from the backtester — a pure relocation with no behaviour
  change — and the crate header's parity rules apply: `f64` end to end, the same expression order
  as the oracle, no fused multiply-add or fast-math. See [the parity
  gate](/docs/trader/concepts/parity-gate) for why none of that is relaxed to make a test pass.
</Callout>


# The harness registry (/docs/trader/backtesting/harness-registry)



A profile's `[strategy] name` resolves through `crates/vike-backtest/src/harness/registry.rs`'s
`strategy_by_name`: a registry name plus its TOML `params` table becomes a
`Box<dyn Strategy<SimBroker>>`. An unknown name is a validation error at load time — the harness
fails the profile fast rather than silently no-opping on a typo. Dispatch through the box is
deliberately dynamic: the harness runs one strategy per profile, so a single vtable indirection
per bar or tick is noise next to loading and replaying the data slice.

## Two halves of one registry [#two-halves-of-one-registry]

This file is the **simulator half**. The portable half moved down to
`crates/vike-strategy/src/registry.rs`, whose `strategy_by_name<B: HftBroker>` is generic over the
broker so the same table serves the backtest simulator and the live daemon. The reason is a
dependency one: a return type naming `SimBroker` made "run the strategy I backtested" impossible
for the headless daemon without depending on `vike-backtest`, which would drag the whole
simulator — and, under the DataFusion feature, the Arrow tree — into the binary that signs real
orders.

What stays here is what genuinely cannot leave: five reference strategies implemented against
`SimBroker` by design, two portable strategies that reach this crate's own internal modules, and
the `rhai` arm, whose `vike-script` dependency sits at the same layer rank as `vike-strategy` and
so cannot be named from there. Everything else falls through to the portable registry,
monomorphised at `SimBroker`.

`STRATEGIES` is the union of both halves, in this order:

```
buy_hold  rotation_top_k  bracket_per_symbol  gated_weights  caps_sizers_mask
tick_pair_mse  cheap_catch_updown_fair_value  sport_copy_follower  grid
dca_accumulate  spread_maker  gueant_maker  trailing_scalper  momentum
funding_carry  funding_capture  pairs_zscore
```

The order is wire-visible — the data service's strategy listing documents "in its declared
order" — so the split kept it byte-identical rather than grouping the halves. Every name on it
resolves with default params; `backtest --list` prints it, and the Studio consumes it as its
native-strategy list. The ten portable names each have a page of their own, from
[`buy_hold`](/docs/trader/strategies/templates/buy-hold) to
[`pairs_zscore`](/docs/trader/strategies/templates/pairs-zscore); the registry they come from is
[the portable registry](/docs/trader/strategies/the-registry).

## The seven simulator-only names [#the-seven-simulator-only-names]

`vike_strategy::registry`'s `SIMULATOR_ONLY` carries, as data any consumer can read, the names that
cannot leave `vike-backtest` and the reason for each — so a daemon refusing one can say why
rather than "unknown strategy". Two distinct reasons, and the distinction matters:

| name                            | why it stays                                                                                                                  |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `rotation_top_k`                | simulator-bound: reads the `SimBroker` `symbols`/`schedule` fields directly                                                   |
| `bracket_per_symbol`            | simulator-bound: measures the attached protective `stop` the `SimBroker` fill loop resolves                                   |
| `gated_weights`                 | simulator-bound: drives the `SimBroker` cash-gate `weight` submit argument                                                    |
| `caps_sizers_mask`              | simulator-bound: drives the position sizer via `SimBroker`'s `raw=false` submit path (a `999.0` sentinel size)                |
| `tick_pair_mse`                 | simulator-bound: measures `SimBroker::position_of` against the engine's latency shadow                                        |
| `cheap_catch_updown_fair_value` | lives in the simulator crate: reaches its internal `cheap_np_ask`/`fair_value` modules — portable in principle, not yet moved |
| `sport_copy_follower`           | lives in the simulator crate: reads a signal series the replay harness synthesizes — portable in principle, not yet moved     |

The first five name simulator machinery that no registry work makes live; the last two are
genuinely portable `impl<B: Broker>` strategies that merely live here, and moving them is future
work rather than a law. The backtest side asserts the table names exactly its retained arms, so
the two cannot drift. The same table renders
[simulator-only strategies](/docs/trader/strategies/simulator-only).

## The `rhai` arm [#the-rhai-arm]

`rhai` resolves here and is deliberately **absent** from `STRATEGIES`: it requires a `src` param —
the inline script source — so it is not default-resolvable, and listing it would break every
consumer that enumerates the roster and resolves each name with empty params. A missing `src` is
a fail-fast validation error; every other numeric param is a `param(name, default)` override,
the same knobs a `[sweep]` varies, baked into the script scope at compile through
`RhaiStrategy::compile_with_params`. A Rhai parse or compile error surfaces as a validation error
at load, not a mid-backtest panic. Integers and floats are both accepted for a numeric knob, so
`size = 1` reads the same as `size = 1.0`.

<Callout title="Scripts do mount live — by path, not by this name">
  `vike_strategy::registry`'s `SCRIPT_ONLY` classifies the *name*, not the script path. The daemon
  links `vike-script` directly and mounts a script by path, `[strategy] rhai = "<path>"`, never
  through this registry; the inline-`src` arm here remains the backtest spelling. That scripts mount
  live at all is a recorded architecture verdict, and the `SCRIPT_ONLY` row carries it as the reason
  a refusal on the *name* redirects to the path spelling rather than claiming the strategy does not
  exist. See [writing a strategy](/docs/trader/scripting/writing-a-strategy).
</Callout>

## User strategies, consulted last [#user-strategies-consulted-last]

When neither half knows a name, the resolver consults the user registry —
`vike_user_strategies::user_strategy_by_name`, compiled from `user_data/strategies/rust` and empty
in any checkout without one — before giving up. Built-in arms are tried first, so a user folder
can never shadow a registry name. The final error names both rosters, the built-ins and the
user's, so an operator can tell "not compiled in" from "typo'd a built-in". Authoring one is
[authoring in Rust](/docs/trader/strategies/authoring-rust).

The five reference strategies are `#[derive(Default)]` with no harness-tunable knobs today —
`Default::default()` is their documented constructor. `cheap_catch_updown_fair_value` and
`sport_copy_follower` are genuinely param-driven and read their tables the way `buy_hold` does.


# Backtesting (/docs/trader/backtesting)



Vike Trader's backtester is the `vike-backtest` crate, and it offers exactly two simulation APIs.
`crates/vike-backtest/src/lib.rs`'s module header states the unification: `engine` holds **the one
event engine** (`StrategyEngine` over `SimBroker`, any number of symbols) and `vector_engine` holds
**the one vectorized kernel** (`VectorBacktestEngine`, any number of symbols); the older
`SingleSymbolEngine` and `fast_backtest` are retired. Both return the same `BacktestResult`, which
lives one crate down in `vike-analytics` and is re-exported here — the numbers are the same type
whichever engine produced them.

## The two engines, and which to reach for [#the-two-engines-and-which-to-reach-for]

**The event engine** is the general one. It steps aligned per-symbol bar series timestamp by
timestamp — or, in tick mode, k-way-merges recorded quote, trade and book events — and hands each
event to a strategy written against `vike_model`'s `Strategy<B: Broker>` trait, the same trait that
runs live (`crates/vike-model/src/strategy/mod.rs`'s `Strategy`, whose `on_bar` doc
names both firing points: once per symbol per step in a backtest, once per closed bar of the
mounted series live). Everything with a resting order, a stop, a bracket,
a cash gate, a margin call, a sizer or a maker quote goes here. Read [the portfolio
engine](/docs/trader/backtesting/portfolio-engine) for the step loop and [the sim
broker](/docs/trader/backtesting/sim-broker) for the fill engine it drives.

**The vectorized kernel** is deliberately narrow. `crates/vike-backtest/src/vector_engine.rs`'s
header draws the boundary: the `cash_gate=False`, market-order, target-weight path only —
next-open fills, column-order shared-cash application, taker fees, slippage, funding, cost-basis
averaging — and names what is out of scope: stops and brackets, the cash gate, volume and
position caps, leverage capping, membership masks, liquidation, sub-bars and sizers. If your
strategy is a T×S matrix of target weights and nothing else, it is the fast path. Read [the vector
engine](/docs/trader/backtesting/vector-engine).

The two are reconciliation partners, not alternatives that may drift: engine-versus-kernel
agreement is a second oracle, gated as a test in `crates/vike-backtest/tests/parity/engine_kernel_parity.rs`,
whose header requires the same trade count and a bit-identical final equity, and says never to
widen that to a tolerance.

## What a fill is, defined once [#what-a-fill-is-defined-once]

Neither engine owns its cost model. `crates/vike-fills/src/lib.rs` is the shared fill cluster —
`broker_sim` (the three canonical cost scalars), `fill_model` (the bar, L1 tick and L2 book-walk
tiers), `fill_resolution` (adverse-first intrabar ordering with the SL/TP bracket cap) and
`staleness` (the opt-in stale-price wait) — and `vike-backtest` re-exports all four at its root.
The reason it is a separate crate is the reason it matters to a reader of a report: the paper
exchange mounted on a live feed must charge exactly what `SimBroker` charges, or "backtest ==
paper == live" stops being checkable. The primitives are documented under [fill
models](/docs/trader/backtesting/fill-models), [fill resolution](/docs/trader/backtesting/fill-resolution),
[the cost model](/docs/trader/backtesting/cost-model) and [staleness](/docs/trader/backtesting/staleness);
the equivalence they buy is [the paper exchange](/docs/trader/concepts/paper-exchange).

The arithmetic is held to the parity rules `lib.rs` restates from `vike-model`: `f64` end to end,
the same expression order, no `mul_add` or fast-math, and Python floor-mod on timestamps. That is
what lets [the parity gate](/docs/trader/concepts/parity-gate) compare bit patterns rather than
tolerances.

## The harness: from a TOML file to a result [#the-harness-from-a-toml-file-to-a-result]

Nobody constructs an `EngineParams` by hand to run a backtest. `crates/vike-backtest/src/harness/mod.rs`
is the config-driven end-to-end runner: `profile` parses and validates a `BacktestProfile`,
`registry` resolves `strategy.name` to a boxed strategy over `SimBroker`, `run` dispatches the
profile to bar mode (`StrategyEngine`) or tick mode (the `hist_replay` loader), and `report`
composes the metrics into a printable `BacktestReport`. The multi-run siblings — `sweep`,
`walkforward`, `euler` and `tpe` — all take the same `(&BacktestProfile, Arc<dyn HistStore>)`
shape and read their own profile section.

The harness is gated behind the `hist-replay` feature and compiles against the `HistStore`
**trait** only; the concrete DataFusion store that the `backtest` binary actually opens sits
behind a separate `datafusion-store` feature (`crates/vike-backtest/Cargo.toml`'s `hist-replay`
and `datafusion-store` entries state both halves). Depending on the
harness therefore does not pull the Arrow tree, which is what lets `vike-datahub`'s default build
be DataFusion-free — a trait-only library, with the real server binary behind its own feature.

<Callout title="Reading order">
  Start with [run profiles](/docs/trader/backtesting/run-profiles) — the TOML is the whole user-facing
  surface — then [running a backtest](/docs/trader/backtesting/running) for the two ways a profile is
  executed, [the harness registry](/docs/trader/backtesting/harness-registry) for what `strategy.name`
  may say, and [runs on disk](/docs/trader/backtesting/runs-on-disk) for what a finished run leaves
  behind. The engine pages after that explain the number you got.
</Callout>

## The rest of the tree [#the-rest-of-the-tree]

The opt-in realism knobs each have a page: [the queue lane](/docs/trader/backtesting/queue-lane) and
[queue models](/docs/trader/backtesting/queue-models) for resting maker limits, [market
impact](/docs/trader/backtesting/market-impact) for bar mode, [latency models](/docs/trader/backtesting/latency-models)
for the tick path, [tick replay](/docs/trader/backtesting/tick-replay) for how store rows become a
replay stream, [timeframes](/docs/trader/backtesting/timeframes) and [scheduling](/docs/trader/backtesting/scheduling)
for the strategy-facing clock. Search over a profile's grid is [sweeps](/docs/trader/backtesting/sweeps),
[search](/docs/trader/backtesting/search) and [objectives](/docs/trader/backtesting/objectives);
out-of-sample stitching is [walk-forward](/docs/trader/backtesting/walk-forward). The statistics a
report is made of live under [analytics](/docs/trader/analytics).


# Latency models (/docs/trader/backtesting/latency-models)



Without a latency model a simulated order is submitted, matched and cancelled with **zero**
delay. `crates/vike-backtest/src/latency.rs` states the consequence in its header: the strategy
sees a tick and its order is already resting at the matching engine on that same tick, and a
cancel issued on the tick that would have filled it always wins. That gives a maker impossible
reflexes and is, the header says, the single largest source of optimism left in the replay path
after the [queue model](/docs/trader/backtesting/queue-models), its natural partner.

It is opt-in and replay-only: `EngineParams::latency_model = Some(kind)` arms it, `None` (the
default) means no in-flight queue is ever built and every code path is byte-identical, and only
`StrategyEngine::run_ticks` arms it — `SimBroker::latency`'s doc says the gate is installed for
the duration of a tick replay and taken out at the end, which is what structurally guarantees the
bar engine and the vector kernel can never consult one.

## Two legs [#two-legs]

* **Entry latency** — a local submit at `T` becomes visible to the matching logic at
  `T + entry()`. Everything the strategy sends — new orders, cancels, amends — is held in an
  in-flight queue keyed by that delivery timestamp.
* **Response latency** — an exchange-side event at `exch_ts` reaches the strategy at
  `exch_ts + response()`. Fills are delivered to `Strategy::on_fill` late.

Both are signed nanoseconds, while the engine's own timestamps are epoch **milliseconds**. The
wire-in keys its queue in nanoseconds (`ts_ms × 1 000 000 + latency_ns`) so a sub-millisecond
latency is not silently truncated; it simply means the action lands on the next tick whose
millisecond stamp has caught up. A **negative** entry latency encodes a recorded rejection: the
request never reached the matching engine, so the engine drops the action outright and records it
in `SimBroker::dropped` under `"latency_reject"` — the channel the
[zero-trade analyzer](/docs/trader/analytics/sizing-and-zero-trade) reads, so a calibrated series
with a rejection burst cannot silently swallow a maker's orders and leave "why did my maker stop
quoting" undiagnosable.

## The two shipped models [#the-two-shipped-models]

`LatencyModel` is the seam — `entry(ts, order)` and `response(ts, order)`, pure functions with
no I/O, no clock and no interior mutation, so a replay is reproducible. `LatencyOrder` is the
deliberately tiny descriptor a model may condition on: side, quantity, optional price.

**`ConstantLatency`** is fixed nanoseconds on both legs, the calibration-free baseline. Its doc
draws a distinction worth keeping: `entry_ns: 0` / `response_ns: 0` reproduces zero-latency
behaviour while still exercising the in-flight queue, so it is **not** the same thing as
`latency_model: None` — an action submitted at `T` still applies only at the next drain, the
next tick at `ts >= T`.

**`IntpOrderLatency`** interpolates from a recorded series of round trips —
`LatencyRow { req_ts, exch_ts, resp_ts }` in epoch nanoseconds, `exch_ts <= 0` marking a
rejection. Lookup is a binary search for the bracketing pair and a linear interpolation between
them, along a different abscissa per leg: the entry leg in `req_ts` over every row, the response
leg in `exch_ts` over a second index with rejection rows excluded. Outside the series the nearest
end row's latency is used, never an extrapolation, and rejections are not interpolated across —
if either bracketing row is one, the nearer row's latency is returned verbatim, so a recorded
rejection is never blended into a merely slow accept. An empty series is inert.

## The in-flight queue [#the-in-flight-queue]

`LatencyGate` holds the built model and the queue. Every price tick drains everything whose
delivery stamp has arrived, so the queue only ever holds the actions issued within one latency
window; the due slice is sorted by `(delivery_ns, seq)`, where `seq` is a monotonic submission
counter that keeps a batch sharing one delivery stamp in the order the strategy issued it — a
cancel then a re-submit must not swap. `InFlight::seq`'s doc names the precondition: both shipped
models ignore the order descriptor, so that holds; a user model that gives a bare cancel a
different entry latency than the sized re-submit after it can legitimately reorder the pair, and
a maker whose requote's cancel lands last is left with its tag pulled rather than re-priced.

There is deliberately no end-of-run flush of the order queue: an action undelivered when the
tape ends never reached the venue and must not retroactively apply. The **response** leg is
flushed — `flush_deferred_fills` delivers every still-held fill, because a backtest must not end
with fills the strategy was never told about.

<Callout type="warn" title="What the response leg delays, precisely">
  Only the strategy's **view** is delayed, never the exchange's own state. `SimBroker::apply_fill`
  folds a fill into the position, cash and the equity curve the instant it matches, and
  `BacktestResult` is computed from that truth. What the response leg holds back is the
  `Strategy::on_fill` callback and the strategy-visible **shadow position** — a per-symbol signed
  size advanced only by delivered fills, which `Broker::position` and `HftBroker::position` read
  while the gate is armed. `SimBroker::shadow_pos`'s doc says why it exists: a maker that polls its
  inventory rather than accumulating it in `on_fill` used to see every fill with zero latency,
  which made the leg inert for the [spread maker](/docs/trader/market-making), whose inventory skew and
  reservation price are driven by exactly that poll.

  Still bypassing the model, by design: `SimBroker::position_of`, `pending_of`, `equity_now` /
  `Broker::equity`, `drawdown_now` and the target-percent verbs read exchange truth
  synchronously — they are the accounting surface, and shadowing them would make `on_stop` disagree
  with the result. A strategy that sizes off `equity()` still reacts to a fill with zero response
  latency.
</Callout>

An order in flight is invisible to `pending_of` until delivered. `SimBroker::in_flight_of(symbol)`
is the read that sees it — always `0` when the gate is not armed — so a strategy checks
`pending_of(s).is_empty() && in_flight_of(s) == 0` rather than re-firing a duplicate on every
tick of the entry-latency window. The pre-trade leverage cap does count in-flight market orders
(`LatencyGate::in_flight_market_signed`): a local risk check must model the local view, or every
submit inside one latency window would be granted the full leverage room in exactly the regime
the model exists to make pessimistic.

## Venue-enforced holds [#venue-enforced-holds]

Some delays are venue rules, not network estimates. `VENUE_HOLD_POLYMARKET_UPDOWN_MS` is 250 ms,
verified against the venue's published order-lifecycle documentation on 2026-07-23: on exactly
the crypto up/down markets the venue holds the order, validates it again, and only then matches
or books it. `VENUE_HOLD_POLYMARKET_SPORTS_GAME_MS` is 3 000 ms, an independent mechanism
measured live the same day — 400 of 400 open sports markets carrying a `game_start_time`
declared `seconds_delay: 3` — and its doc warns it is not universal, a later sweep having found
the esports book declaring 1 000 ms. Both literals are owned by `vike_model::venue_hold`.

`LatencyModelKind::venue_hold_ms(ms)` models a hold on the entry leg only — a hold delays when
the venue acts, not when the strategy hears about it — and a deployment pays it **on top of** its
wire round trip. Better than a constant, since the hold is a per-market property and one tape
can carry both kinds: `SimBroker::taker_hold_table_ns` resolves each symbol's
`SymbolProperties::taker_hold_ms` once at run start through the same point-in-time
[properties](/docs/trader/concepts/instruments/symbol-properties) seam the fill grid uses, and
`LatencyGate::submit` adds it to the model's entry leg; an empty or all-zero table is
byte-identical to no table. Paired with the [L2 fill model](/docs/trader/backtesting/fill-models), the
venue's "matched or booked" second validation falls out: decided on the book at `T`, delivered
at `T + hold`, matched against the book as it then stands, resting if it no longer crosses.

## In a profile [#in-a-profile]

A [run profile](/docs/trader/backtesting/run-profiles) exposes the constant model as two millisecond
knobs in `[engine]`, tick mode only: `order_latency_ms` is the entry leg on every order action —
place, modify, cancel — and `fill_latency_ms` the response leg before the strategy learns of a
fill. Either `> 0` builds a `LatencyModelKind::constant`; both `0` is `None`, byte-identical. A
recorded series is reached through `EngineParams` directly.


# Market impact (/docs/trader/backtesting/market-impact)



The frozen cost model applies one **flat** adverse move per fill: a 5 bp `slippage` costs the
same whether the order is one share or 10 % of the day's volume. `crates/vike-backtest/src/impact.rs`
opens by naming the direction of that error — it flatters a backtest, because size is exactly
what a real book charges for — and supplies the missing size-dependent cost for the lanes where
**no book exists**, estimated from bar OHLCV alone. Where L2 depth is recorded the engine already
does better than any model — `run_ticks` walks the real replayed book and
[the queue lane](/docs/trader/backtesting/queue-lane) gates resting makers — which is why a
[run profile](/docs/trader/backtesting/run-profiles) that sets `[engine.impact]` in tick mode is
rejected at validation rather than ignored.

It is opt-in through `EngineParams::impact = Some(model)`. With `None` the wire-in site,
`SimBroker::slippage_for`, returns the flat `slippage` field unchanged with no arithmetic
performed on it, so every parity and golden fixture is untouched. With a model, the estimate is
**added** to `slippage` for each taker fill and the sum goes to `adverse_fill_price` —
[the cost model](/docs/trader/backtesting/cost-model).

## Taker-only [#taker-only]

The estimate is charged on aggressive fills only. A resting limit that was hit **supplied** the
liquidity this cost pays for, so `slippage_for` returns the flat `slippage` alone for maker
fills — charging otherwise would execute a maker through its own limit price. The gate lives at
the wire-in site, not in the models, so every `ImpactModel` inherits it; `EngineParams::impact`'s
doc draws the consequence that the knob is safe to leave on for a maker strategy: it prices the
aggressive legs and leaves the passive ones alone.

## The model [#the-model]

`AlmgrenChriss` ports the published cost function of Almgren, Thum, Hauptmann and Li (2005),
*Direct Estimation of Equity Market Impact* — an empirical calibration fit to roughly 700 k US
equity orders, which is why its coefficients are quoted rather than tuned. Two additive terms,
both a fraction of price:

```text
nu        = qty / (exec_time * avg_volume)              -- participation rate
permanent = gamma * sigma * (nu * exec_time)^alpha      == gamma * sigma * (qty/avg_volume)^alpha
temporary = eta   * sigma * nu^beta
impact    = permanent + temporary
```

with the published exponents `alpha = 0.891`, `beta = 0.600` and coefficients `gamma = 0.314`,
`eta = 0.142` (`AC_ALPHA`, `AC_BETA`, `AC_GAMMA`, `AC_ETA`). Permanent impact is the shift the
order leaves in the market after it is done; temporary impact is the concession paid for
demanding liquidity now, and decays once trading stops. The header flags where `exec_time` does
and does not appear, because it is the term a transcription slip reaches for: the permanent term
is a function of the total fraction of volume traded and is **horizon-independent** — working an
order more slowly does not change the footprint it leaves — while only the temporary term sees
the horizon, through the participation rate.

One term of the paper is deliberately omitted: the fundamental-data liquidity adjustment on the
temporary term, `(shares_outstanding / avg_volume)^delta` with `delta = 0.267` (`AC_DELTA`,
recorded for provenance and read by nothing). It needs a per-issuer shares-outstanding series
this workspace has no source for and that does not exist at all for crypto and perp symbols; its
absence makes the temporary term the paper's value at the calibration sample's median liquidity.

<Callout type="warn" title="Units — read this before trusting a number">
  The published coefficients are calibrated on **daily** units: `sigma` is a daily return
  volatility and `avg_volume` a daily share volume, so `exec_time` is measured in days.
  `window_stats` derives both from the bar series being backtested, which means the calibration is
  literally right only on daily bars. On finer bars the shape — monotone in size, concave in
  participation — still holds, but the absolute level is a per-bar quantity: treat it as a tunable
  cost, not a published estimate, and scale `exec_time` accordingly.
</Callout>

## The market context [#the-market-context]

`ImpactInputs` is what one fill is priced against: `qty`, an absolute order size in the same unit
as `avg_volume`; `avg_volume`, the average traded volume per period; `sigma`, a fractional return
volatility over that same period. `window_stats(bars, window)` measures the last two over the
last `window` bars — the sample standard deviation of simple returns and the mean volume, both
summed through `py_sum` so the result is independent of how the window was sliced — and returns
`None` when the window cannot support an estimate: fewer than three bars, a non-positive close,
or non-positive mean volume. `DEFAULT_IMPACT_WINDOW` is 21 bars, one trading month of daily
bars: long enough that a single outlier cannot dominate the volatility estimate, short enough to
track a regime change.

`slippage_for`'s doc pins the window free of lookahead on all three bar lanes: the context is
measured over the bars that **closed before** the fill's timestamp, excluding the bar the
timestamp falls inside, because its own close and volume are not knowable at the moment the
order prices and its volume would in part be this very order. A window too short or degenerate
to measure charges the flat slippage alone rather than guessing.

## What a model must promise, and what it need not [#what-a-model-must-promise-and-what-it-need-not]

`ImpactModel::impact_frac` must return a finite, non-negative fraction, non-decreasing in `qty` —
bigger orders never cost less — and a model with insufficient or degenerate inputs must return
`0.0` rather than a NaN or infinity that would poison the equity curve; `AlmgrenChriss` charges
nothing on a non-positive or non-finite sigma or a participation rate the inputs cannot support.

No upper bound is required, and the trait doc calls that a decision rather than an omission. A
fraction of `1.0` means the move ate the whole price, and past it the multiplicative haircut
inverts the sign — but a model cannot see the two things that decide whether that happens: the
flat `slippage` it is added to (a per-model cap of `1.0` would still let `0.5 + 0.9` cross) and
the side the engine will point the move in. The bound lives where both operands are in hand,
`adverse_fill_price`'s `MIN_ADVERSE_FACTOR`, and the fill site counts each saturation in
`SimBroker::slippage_saturations`.

Both `^` in the formula are `libm::pow`, never `f64::powf`: base and exponent are arbitrary
runtime `f64`s, the platform's libm decides the last bit of such a power, and the number is
multiplied into a fill price — two boxes replaying one tape must not report different PnL.

## In a profile [#in-a-profile]

```toml
[engine.impact]
model = "almgren_chriss"   # the only model name today
exec_time = 1.0            # execution horizon, in bar-periods
window = 21                # rolling sigma/volume lookback, in bars
```

`ImpactCfg::build` fails the profile on an unknown model name, a non-positive or non-finite
`exec_time`, or a `window` under 3 — a typo must fail loudly rather than silently price fills at
zero impact. The [vector engine](/docs/trader/backtesting/vector-engine) has no per-fill market
context and never consults the model, so engine-versus-kernel reconciliation is meaningful only
with `impact: None`, which is what the parity gate runs. This is the *backtest* cost estimate;
the live pre-trade **veto** against displayed liquidity is a different primitive,
`vike_model::impact`, which walks a real book and denies rather than prices.


# Objectives (/docs/trader/backtesting/objectives)



Every ranked search — the grid, successive halving, TPE — ends by sorting rows on one number. `crates/vike-backtest/src/objective.rs` defines that number: an `Objective` is a boxed `Fn(&BacktestReport) -> f64`, higher is better, and `run_sweep_with` ranks a sweep's rows by any of them, stamping each successful row's `score`. The module is feature-free by design, like the report it scores: nothing in it names the gated profile parser or the DataFusion tree, so leaf crates reuse the same objectives and its tests run in the default lane.

## The built-in objectives [#the-built-in-objectives]

The four classic `--rank-by` metrics are exposed as objective constructors through `RankMetric::objective` in `crates/vike-backtest/src/harness/sweep.rs`, with direction folded in — `MaxDrawdown` becomes `−max_drawdown`, the other three pass through — so ranking by `Sharpe.objective()` through `run_sweep_with` orders rows exactly as the classic comparator does, `NaN`-last included; `metric_objectives_rank_identically_to_cmp_reports` gates it. The classic `run_sweep` keeps its own comparator untouched, so the default output stays byte-identical and a `SweepReport`'s `rank_by` serialises as the same bare metric string; an objective-ranked report carries its label instead, e.g. `"multi"`.

## Two laws [#two-laws]

Both are property-tested, because a sweep's first row feeds downstream selection and "degenerate points cannot be crowned" has to be provable rather than intended.

**`NaN` is unrankable.** A `NaN` score is legal and means the row cannot be ranked; `cmp_scores_desc` — the one best-first comparator every score-ranked sort in and out of the crate goes through — puts it after every finite score, and `sort_scored_rows` puts rows with no score at all (failures) last, stably. Every `multi_metric` input that is `NaN` poisons the score rather than being substituted, and a non-finite score serialises as `null`.

**The sign law.** Every losing run scores strictly below every profitable one, whatever its other statistics say. Only `multi_metric` can violate it, so only it is bound by it: its shaping terms are factors that mostly sit under 1, and applied multiplicatively to a negative base they would shrink a loss toward zero — reward it — and rank the most catastrophic point first on an all-losing grid, the common case when tuning a bad strategy.

## The multi-metric score [#the-multi-metric-score]

`multi_metric(params)` builds the composite objective; `--rank-by multi` uses the default `MultiMetricParams`. The formula, as the type's doc states it:

```text
base    = total_return - max_drawdown
shape   = ln(1 + profit_factor)            // profit_factor clamped to profit_factor_cap
        * winrate_coeff                    // winrate_floor + (1 - winrate_floor) * win_rate
        * trade_count_penalty(n_trades)
        -> clamped into [0, shape_max],  shape_max = ln(1 + profit_factor_cap)
quality = shape / shape_max

score   = if base > 0 { base * shape }
          else        { base * (1 + loss_quality_weight * (1 - quality)) }
```

So the zero point means "did nothing": above it a quality-shaped profit, below it a quality-amplified loss, and exactly zero a breakeven, no-trade or no-winner run there is nothing to rank. The defaults: `target_trades` 50 (the statistical-significance knee, at and above which `trade_count_penalty` is exactly 1.0 and below which it falls linearly), `penalty_floor` 0.1 (so a thin profitable point stays visible), `winrate_floor` 0.0, `profit_factor_cap` 100.0 and `loss_quality_weight` 1.0 — the worst-quality loss counts double, which keeps loss size the dominant term; only losses within 2× of each other can be reordered by quality, `0.0` disables the shaping, and a negative weight is treated as zero because it could flip a loss positive. The cap exists because `metrics::profit_factor` returns the house `f64::INFINITY` sentinel for a run with no losing trades — unclamped, every all-win point would score infinite and rank first — and `ln(101) ≈ 4.6` leaves any realistic profit factor untouched.

<Callout title="A 0% win rate lands on the zero plateau">
  Under the default `winrate_floor` of 0.0 the coefficient is the plain win rate, so a profitable run with no winning trade collapses onto the zero plateau and a winnerless loser takes the full amplification. Raise the floor above zero to keep the profitable regime strictly ordered, or to soften the term for a low-win-rate, high-payoff style.
</Callout>

The clamp on `shape` is what makes the sign law hold by construction rather than by trusting the report's provenance: a hand-built report or an exotic floor could otherwise make `shape` negative and flip a profitable run below a losing one, and `f64::clamp` passes `NaN` through unchanged so a `NaN` metric still poisons the score instead of being laundered into a number.

## Why the logarithm is not `f64::ln` [#why-the-logarithm-is-not-f64ln]

Every `ln` in the module is `libm::log`. IEEE 754 requires `+ − × ÷` and `sqrt` correctly rounded and requires nothing of `ln`, so the method spelling resolves to whatever libm the platform ships, and two platforms differ in the last bit. Here that decides a ranking: `shape_max` is the normaliser of the losing regime's quality term and the upper clamp of `shape`, so two boxes could order two near-tied rows differently and crown a different winning config off the same data. `libm` is one pure-Rust implementation compiled into the binary, so both boxes run the same code. What the module deliberately does not claim: this is not a live order path and not even the sweep's default ranking — `multi` is opt-in, and with the flag absent the binary takes `RankMetric::default()`, which is Sharpe, and nothing in the module is called. The exposure is a research one, and worth closing for exactly that reason rather than by inflating it into a trading hazard.

The metrics themselves are on [metrics](/docs/trader/analytics/metrics) and [the report](/docs/trader/analytics/report); [overfitting](/docs/trader/analytics/overfitting) is what a crowned row is tested against next.


# The portfolio engine (/docs/trader/backtesting/portfolio-engine)



`crates/vike-backtest/src/engine.rs`'s `StrategyEngine` is multi-asset backtesting on one shared
cash account — an exact port of the Python `core/multi_symbol_engine.py::StrategyEngine`, kept
line-for-line so that parity beats idiom. Aligned per-symbol bar series are stepped timestamp by
timestamp; an order submitted during a step fills at each symbol's **next** bar open, so there is
no look-ahead; equity is `cash + Σ pos·price·mult`.

The engine is generic over `S: Strategy<SimBroker>`. Handlers receive `&mut SimBroker` — the
context every verb and read lives on ([the sim broker](/docs/trader/backtesting/sim-broker)) — and the
fill dispatchers are engine methods rather than broker methods so that `on_fill` fires
synchronously after each applied fill, the Python engine's exact firing point.

## Construction [#construction]

`StrategyEngine::new` asserts every series has the same length — they must be aligned — and
pre-tags each bar's `symbol` once with `format_instrument(default_venue, symbol)`: `SYMBOL.VENUE`
when a venue is set, the bare symbol otherwise. Per symbol it builds the higher-timeframe
aggregates named in `timeframes` ([timeframes](/docs/trader/backtesting/timeframes)), buckets granular
sub-bars into their coarse step, resolves the contract multiplier once so hot paths index a vector
rather than scanning by string, resolves the session calendar if the gate is on, and mounts the
pre-trade risk gate. The queue tracker and the latency model are created here and consulted only
by the tick path.

## One step of the bar loop [#one-step-of-the-bar-loop]

`StrategyEngine::run` executes the same sequence for every bar index:

1. **Terminal settlements.** The opt-in binary-resolution and option-expiry checks run before
   anything can fill, so a symbol that resolved on this step can neither fill resting orders nor
   keep a position past resolution.
2. **Freshness bookkeeping**, when the stale-price wait is configured, so a bar that is itself a
   fresh print has age zero and fills on the spot.
3. **Protective stops**, per symbol, against the bar's open/low/high — except a symbol whose
   sub-bars drive its own fill pass this step; its stops are checked per sub-bar inside step 4
   instead. A breach closes at the shared trigger oracle's price — a bar that gaps through the stop
   fills at the gapped open — and cancels the fired stop's OCO sibling exits, on every lane.
4. **The fill phase.** With the cash gate off, each symbol runs its own pass — `fill_pending`, or
   `fill_pending_granular` when sub-bars exist for this step. With it on, `fill_step_gated` runs
   across all symbols: reductions and closes fill first and are never gated, opens and adds fill in
   descending weight order (ties by trigger order), and an order the shared cash cannot fund is
   dropped and recorded.
5. **Price, funding and excursions.** The last price becomes the close; a held position is charged
   funding when a rate exists — a recorded `Bar.funding` wins, else the opt-in funding source — and
   the running high and low since entry advance for MAE/MFE.
6. **Variation-margin settlement** when a cadence is configured, then the forced close at the open
   of any symbol that left the active mask, then the **margin call**.
7. **The strategy.** Past warmup, `on_bar` fires per symbol in symbols order, then any due
   scheduled callbacks ([scheduling](/docs/trader/backtesting/scheduling)).
8. **The equity sample**: one per bar, plus a per-symbol realized-plus-unrealized curve.

Every untagged fill lane runs one per-order gate sequence through `gate_pending` — session,
staleness, the emulator stop-release, then the trigger price. Each lane used to spell those calls
inline, which is why the two wait disciplines had to be written five times and kept in sync by
hand. Orders that trigger together on one bar are ordered by the shared adverse-first resolver
([fill resolution](/docs/trader/backtesting/fill-resolution)).

After the loop, an end-of-run resolution sweep and option-expiry sweep run once — a real
prediction-market tape stops at the trading halt and the resolution posts later, so without the
sweep a position held to expiry would be marked at its last traded price instead of the payout —
then `on_stop`, then the `BacktestResult`.

<Callout title="The resolution probe sentinel">
  With no explicit `resolution_end_ts`, the end-of-run sweep asks the resolution source "did this
  market ever resolve?" at `RESOLUTION_PROBE_SENTINEL`, which is `i64::MAX / 4` rather than
  `i64::MAX`. The source is caller code, and the natural way to write one does windowed arithmetic
  on the probe timestamp; with `i64::MAX` any addition overflows — a debug panic, a silently wrong
  wrap in release. The sentinel sits about 2.3 million years past the epoch: after every real
  resolution, with three quarters of the range left as headroom.
</Callout>

## Liquidation [#liquidation]

`check_liquidation` runs when `maint_margin` is positive, judging the whole account at the bar's
intrabar adverse marks. The default is the shared scope-parameterized law in
`vike_model::liquidation` — the same `pool_breached` and `cross_liquidation_plan` the live watchdog
runs: breach when maintenance exceeds pool equity by the `liq_buffer` grace line (default `0.10`,
the watchdog's own buffer), then close the biggest losers first, only the excess over the line,
stopping once healthy. That is a real behaviour change for margined backtests, which previously
wiped the whole account at the bare trigger; the old model is preserved bit-for-bit behind the
opt-in `venue_style_liquidation` stress knob. The live half is [margin
calls](/docs/trader/concepts/margin-call).

## The tick path [#the-tick-path]

`StrategyEngine::run_ticks` replays recorded events: a stable k-way merge by timestamp across the
per-symbol streams, ties broken by stream order, each tick routed to its symbol slot by name.
`on_bar` does **not** fire — the strategy sees `on_quote_tick`, `on_trade_tick` and
`on_order_book`. A recorded book event folds into the symbol's replay book under the shared
`L2Book::delta_decision` law with strict sequencing: a delta applies only when it is the next
sequence number, and a gap, an orphan or a recorded gap marker drops the book until the next
snapshot re-anchors it — identical to what the live consumer knew at the time. Book events advance
the clock and settle a just-resolved symbol but never fill or bump the warmup index; quotes and
trades own price semantics. How store rows become that stream is [tick
replay](/docs/trader/backtesting/tick-replay).

The tick path is the only place the latency model is armed — `run_ticks` installs the gate for
the replay and removes it afterwards, so the bar path and the vector kernel structurally cannot
consult one ([latency models](/docs/trader/backtesting/latency-models)) — the only lane that consults
the queue tracker ([the queue lane](/docs/trader/backtesting/queue-lane)), and the only one that honours
`EquitySampling`. It takes two equity samples per tick on purpose: the peak is stamped before the
strategy callback so a `drawdown_now` read inside it already includes this tick's mark, and the
curve after, because `SimBroker` exposes `cash` and `sym` as public fields and a strategy can move
equity in-callback.

## What comes out [#what-comes-out]

`BacktestResult` carries the trade list and count, the equity curve and its timestamps, final
equity, per-symbol PnL and curves, the strategy's warmup, net funding paid, and the diagnostics
the broker accumulated: `dropped` (every refused fill with its reason), `intrabar_both_hit`,
`stale_deferrals`, `session_deferrals` and `below_min_reversals`. The zero-trade analyzer reads
the first of those to explain why orders did not fill ([sizing and zero-trade
diagnosis](/docs/trader/analytics/sizing-and-zero-trade)).


# The queue lane (/docs/trader/backtesting/queue-lane)



The frozen tick-replay fill pass fills a resting limit the instant price touches it. The queue
lane is the opt-in alternative: the same pass, with every resting limit — a tagged maker quote
included — additionally gated by an estimate of how much size sits ahead of it at its price.
`crates/vike-backtest/src/engine/queued.rs` is the lane; the estimators it consults are
[queue models](/docs/trader/backtesting/queue-models), and this page is about the lane rather than
the arithmetic.

## When it runs [#when-it-runs]

The lane is reached **only** when `EngineParams::queue_model` is `Some`. Its module header
states the contract the rest of this page rests on: a default run never enters the module at
all, and the frozen `fill_pending_tick` / `fill_tagged` lanes it mirrors stay byte-identical.
From a [run profile](/docs/trader/backtesting/run-profiles) that is `queue_model = "…"` in `[engine]`,
which `EngineCfg::queue_model`'s doc marks **tick mode only** — the lane is consulted exclusively
by `run_ticks`, so a bar-mode profile that sets it is rejected by `BacktestProfile::validate`
rather than silently doing nothing.

The module is a separate file for a reason its header gives: the queued twins used to sit some
700 lines from the code they mirror, in a 2 200-line file — a hand-synced duplication no reader
could check without scrolling between two ends of the file.

## What is shared and what is genuinely different [#what-is-shared-and-what-is-genuinely-different]

The per-order gate sequence is not duplicated here. Session → staleness → emulator stop-release
→ trigger price lives in one function on the parent module, `StrategyEngine::gate_pending`,
which this lane's **taker** branch calls like every other lane; the maker-lane session gate lives
in `StrategyEngine::defer_tagged_session`. What the header lists as staying in `queued.rs` is
only what makes the twin a twin: queue-state identity and sync (`WorkingOrder::qid`), the
`queue_gate` verdict layered on top of the frozen price law, partial-fill remainder bookkeeping,
and the maker straddle and min-hold guards. The one gate the lane still runs by hand is
`StrategyEngine::defer_session`, on its price-conditional branch.

`fill_pending_tick_queued`'s doc gives the shape: the same structure as the frozen path —
trigger → resolve → dispatch → tagged lane — with resting `Limit` / `LimitClose` orders
additionally gated by their queue-position estimate. Non-limit kinds (market, market-close,
stop, trailing) are takers and pass through unchanged: a taker crosses the book, it never rests
in it.

## The verdict [#the-verdict]

`queue_gate` judges one resting limit against the **raw** tick, because the derived `Bar` shape
cannot distinguish a trade from a quote. It is computed only after the existing fill model has
already said the price condition holds — the gate composes on top of the frozen price logic and
never replaces it. Three outcomes, `QueueVerdict::{Rest, Fill, Partial}`:

* a **strict price cross** — traded or quoted *through* the level — fills in full, because the
  whole level, queue ahead included, was consumed;
* a **trade at the price** consumes the front first, and only its excess beyond the front
  fills — in full when that excess covers the whole order, partially otherwise, the remainder
  resting;
* a **quote touch** fills only once the front is already cleared — there is no trade proof
  otherwise.

Book events never reach the price/fill path, so a `Tick::Book` always rests. Two simplifications
are declared on the function rather than hidden: trades are not filtered by aggressor side, and
simulated orders never consume each other's queue — each order is gated independently, the
standard shadow-order convention.

## Identity, not fingerprints [#identity-not-fingerprints]

Queue state is keyed by the order's engine-local identity, `WorkingOrder::qid`, stamped the
first time the lane sees an order — never by a `(side, price)` fingerprint. The doc gives the
case that rule exists for: the maker re-quote pattern `cancel_all` + re-submit at the same price
correctly re-seeds at the **back** of the level instead of inheriting the cancelled order's
advanced front. States whose order vanished since the last pass — `cancel_all`, an OCO
sibling-cancel, a fill — are dropped by that pass's rebuild.

The tagged (HFT maker) lane, `fill_tagged_queued`, is the queue-gated twin of `fill_tagged` and
keys differently, because a tag names a quote **slot**, not a resting order: its sync keys on the
tag plus the slot's current side, price and `qid`. Its doc lists what forfeits priority — a
re-priced tag, a re-submit over a live tag (`submit_limit_tagged` replaces the resting order), a
`cancel_tagged` + re-submit, and a `modify_tagged` quantity **increase** all re-seed at the back
of the level, each being a new order on a real venue. An amend-down keeps its place, as venues
do. Gone tags drop their state; partial fills shrink the resting tag in place instead of retiring
it.

## The maker guards [#the-maker-guards]

The min-hold guard is `EngineParams::queue_min_hold_ms` (`queue_min_hold_ms` in the profile,
read only when `queue_model` is set): on the **tagged** maker lane, a fill that would **reduce**
the current position — the closing side of a maker round-trip — is deferred until at least that
long after the position was opened, so a maker cannot book a physically impossible
same-millisecond or sub-second round-trip. `0`, the default, disables it, and the untagged
queued-limit lane runs no such check at any setting. The field's doc says where to calibrate it
from — real market-maker behaviour — and quotes Polymarket BTC-5m market-maker wallets flipping
at roughly a 2 s p10 and an 11 s median. The straddle guard is the other guard the header names;
its mechanics are documented at its call site in the lane.

The session gate reaches this lane too. `EngineParams::session_gate`'s doc is explicit that a
closed market crosses no resting limit and no maker quote, *queued or not*: resting orders, the
tagged maker lane and protective stops are gated on the frozen fill lanes and on their opt-in
`queue_model` tick twins alike.

<Callout title="What to feed it">
  `EngineCfg::queue_model`'s doc closes with the data requirement: for a real maker backtest, feed
  the **trade** tape, and — for true size-ahead seeding — the **book**. Without a book the seed
  falls back to the last L1 quote and then to `queue_seed_depth`; [queue
  models](/docs/trader/backtesting/queue-models) carries that chain. The natural partner is a
  [latency model](/docs/trader/backtesting/latency-models): the queue removes the "always first in
  line" optimism, latency removes the "reacts on the same tick" optimism, and
  `crates/vike-backtest/src/latency.rs`'s header names the two as partners.
</Callout>


# Queue models (/docs/trader/backtesting/queue-models)



`crates/vike-backtest/src/queue_model.rs` opens with the defect it exists to fix: the frozen
crossing model fills a resting limit the instant price touches it — as if the order were always
**first** in the queue. That over-fills makers. On a real venue an order at price P fills only
after the resting size *ahead* of it at P has been consumed by trades, and this module supplies
that missing estimate — an independent reimplementation of a mechanism common to queue-aware
simulators, with no code taken from any of them.

It is **opt-in and replay-only**: `EngineParams::queue_model = Some(kind)` activates it, `None`
(the default) leaves every existing path byte-identical, and when active it gates only the
`run_ticks` tick/book replay lanes. The bar path never consults it. The lane that consumes these
estimators is [the queue lane](/docs/trader/backtesting/queue-lane); this page is the estimators.

## The composition rule [#the-composition-rule]

The header states the rule the engine wire-in enforces, and every model below lives inside it:

* the **existing fill model** still decides the price condition — limit crossed or touched;
* a **strict price cross** (a trade or quote through the level) fills in full — everyone at the
  level, the queue ahead included, was consumed;
* a **touch** (an event exactly at the order's price) is queue-gated: a trade at P first consumes
  the estimated front, and only its excess beyond the front fills the order — in full when that
  excess covers the whole order, partially otherwise; a quote touch fills only once the front is
  already cleared;
* recorded L2 `BookUpdate`s drive `on_depth_change` at each tracked level, so cancellations
  ahead of the order shorten — or, for the probabilistic model, statistically shorten — the wait.
  That is exactly the depth-consumption channel the crossing model ignored.

## The state and the seam [#the-state-and-the-seam]

`QueueState` is two numbers. `front_qty` is the estimated resting quantity **ahead** of the
order — the simulated order itself is never part of the market book. `cum_trade_qty` accumulates
trade quantity already applied to the front so that a later observed depth *decrease* at the
level is not double-counted, because the venue's book update reflecting those same trades
arrives after the trade prints. Only the probabilistic model consumes it, and it is cleared once
the echo is netted out by a decrease or superseded by an increase — a level that grew past its
pre-trade size has demonstrably already absorbed the print.

`QueueModel` is the estimator seam, and its verbs are pure `f64` state folds with no I/O and no
clock: `on_new_order` — a new order joins the **back** of the level, so everything currently
resting is ahead of it; `on_trade` — a trade at the order's price consumed liquidity from the
front; `on_depth_change` — the level's resting quantity changed from `old_qty` to `new_qty`,
where increases join the back and decreases are attributed front-versus-back per the model after
netting out `cum_trade_qty`; and `is_front_cleared`, true when nothing is left ahead.

## Two estimators [#two-estimators]

**`RiskAdverseQueueModel`** is the conservative bound. Its doc: the front shrinks **only on hard
evidence** — trades at the order's price, or the level itself shrinking below the current front
estimate, since a depth decrease can never leave more ahead of the order than the whole level.
Cancellations behind the order are never credited to the front, so this is the pessimistic,
slowest-fill bound.

**`ProbQueueModel`** splits a net depth decrease `chg` — the observed decrease minus the
`cum_trade_qty` already applied by trades — between the queue ahead and behind by
`prob = f(back) / (f(back) + f(front))`, the probability the cancellation came from behind. The
front estimate becomes `front − (1 − prob)·chg + min(back − prob·chg, 0)` — the last term folds
back-overflow, change the back could not have supplied, into the front — clamped to
`[0, new_level_qty]`. `ProbFunc` is the weight: `Power(n)` is `f(x) = x^n`, where `n = 1` splits
pro-rata by size and a larger `n` biases attribution toward the usually larger back of the
queue; `Log` is `f(x) = ln(1 + x)`, sub-linear, so large backs saturate.

<Callout type="warn" title="The probabilistic arm calls libm, not the platform">
  `ProbFunc::f`'s doc is a hazard note. IEEE 754 requires `+ − × ÷` and `sqrt` to be correctly
  rounded and requires nothing of `pow` or `log`, so the method spellings call the platform's own
  libm, and two operating systems disagree in the last bit. Here that last bit decides a **fill**:
  `f` weights the front-versus-back attribution, which moves the estimated queue ahead of a resting
  maker, which moves whether a trade's excess reaches the order at all — a backtest could fill on
  one box and not on the other. So both arms spell `libm::pow` / `libm::log`. The default
  `"prob_power"` (`Power(1.0)`) escapes because that `pow` returns `x` unchanged, but `"prob_log"`
  and any `"prob_power:N"` with `N ≠ 1` would otherwise diverge unconditionally — and a site
  portable only for one value of its parameter is portable by accident, not by design.
</Callout>

## Selecting one [#selecting-one]

`QueueModelKind` is the `EngineParams` selector — `RiskAdverse`, `ProbPower(f64)`, `ProbLog` —
and `build` constructs the model once, held by the tracker for the whole replay. In a
[run profile](/docs/trader/backtesting/run-profiles) the spellings, case-insensitive, are
`"risk_adverse"`, `"prob_power"` / `"prob_power:N"` (default `N = 1`) and `"prob_log"`; an
unknown string fails the profile at load.

## Seeding a new order [#seeding-a-new-order]

`QueueTracker` is the replay-scoped queue engine — one model plus per-symbol state, built by
`StrategyEngine::new` when `queue_model` is `Some` and absent otherwise. `QueueTracker::seed`'s
doc gives the chain for a new order: the replayed book's level quantity at its price → the
matching side of the last L1 quote → the configured `seed_depth`. The quote match is a
**tick-grid** compare, not bit-exact equality: `same_level` quantizes with round-half-to-even and
compares tick indices, so a strategy price computed arithmetically — `mid − k·tick` accumulating
an ulp — still matches the level it sits on; with no grid at all it falls back to a few-ulp
relative epsilon. `EngineParams::queue_seed_depth`'s default of `0.0` seeds an empty queue, so
an order with no observed size-ahead starts at the front — the old optimistic behaviour, for
that one order.

Book events are folded through two calls: `pre_depth` snapshots the tracked levels' resting
quantity **before** a book event is applied, and `apply_depth` folds the applied event into every
tracked state. A dropped book — a gap marker — leaves states untouched; an unknown old quantity
with a known new one applies the conservative clamp `front = min(front, new)`, because a fresh
anchor after a gap can only bound the front.

`SymQueue`'s doc carries the identity rule both lanes share: states are keyed by real per-order
identity — `WorkingOrder::qid` for untagged orders, the tag plus its current `qid` for maker
quotes — never by a `(side, price)` fingerprint, so a `cancel_all` followed by a re-submit at the
same price re-seeds at the back rather than adopting the cancelled order's advanced front.


# Run profiles (/docs/trader/backtesting/run-profiles)



A backtest is described by one TOML file. `crates/vike-backtest/src/harness/profile.rs`'s
`BacktestProfile` names a venue/symbol/interval data slice, an engine cost and cash
configuration, and a strategy by registry name plus arbitrary TOML params. Unknown top-level keys
are a hard parse error — the struct is `deny_unknown_fields` — so a misspelt section cannot
silently no-op.

```toml
name = "bar-demo"                      # a free-form label; logs and report titles only

[data]
venue = "binance"
symbols = ["BTCUSDT", "ETHUSDT"]
kind = "bar"                           # "bar" or "tick"
interval = "1h"                        # bars only; defaults to "1d"
from = "2026-01-01T00"                 # epoch-ms as a string, or YYYY-MM-DDTHH UTC
to   = "2026-01-02T00"

[engine]
cash = 100000.0
fee_rate = 0.001
slippage = 0.0

[strategy]
name = "buy_hold"
[strategy.params]
size = 1.0
```

`from` and `to` accept a bare epoch-millisecond integer written as a string or a `YYYY-MM-DDTHH`
UTC hour label; `BacktestProfile::range` resolves both to an inclusive range, and `validate`
rejects `from > to`.

## The data slice, in one of two forms [#the-data-slice-in-one-of-two-forms]

`DataCfg` accepts **either** the single-venue pair `venue = "…"` plus `symbols = [ … ]` **or** an
`[[data.series]]` array whose entries each carry their own `venue`, `symbol` and — in tick mode —
lane `kind`. Exactly one form must be present; mixing them is a validation error, not a
precedence rule. The array form is the cross-venue one, and its order is meaningful: the header's
example puts a spot reference series first so that, on an equal-timestamp tie in the tick merge,
the reference sample is delivered before the print it should inform.

Symbols must be unique across the resolved series — the engine routes events to a symbol slot by
name, and two series sharing one symbol would silently land in one slot. A bar-mode profile may
not set a series `kind`: a bar series has no quote/trade/book lanes to filter.

## The engine table [#the-engine-table]

`EngineCfg` carries `cash` (must be `> 0`), a flat `fee_rate`, a flat `slippage`, and opt-in knobs
whose absence is byte-identical to the profile that never mentioned them. Several are
**mode-bound**, and for five of them — `attach_funding`, `[engine.impact]`, `feed_latency`,
`queue_model` and `equity_sample_every` — `BacktestProfile::validate` rejects a profile that sets
one in the wrong mode rather than ignoring it. The other tick-only knobs carry no such check:
`run_backtest`'s bar arm never reads them, so a bar profile that sets one runs as if it had not.

| key                                     | mode                        | what it does                                                                                                                                 |
| --------------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `attach_funding`                        | bar only — rejected on tick | window-joins the stored `funding` series onto the price bars, one rate per bar whose window contains the event — never forward-filled        |
| `[engine.impact]`                       | bar only — rejected on tick | market-impact slippage on top of the flat `slippage`; the tick lane replays a real book and needs no model                                   |
| `feed_latency`                          | tick only — rejected on bar | deliver ticks in recorded arrival order while matching stays on venue time                                                                   |
| `order_latency_ms`, `fill_latency_ms`   | tick only — inert on bar    | the entry leg and the response leg of order latency, in milliseconds; either `> 0` arms the model                                            |
| `fill_model = "l2book"`                 | tick only — inert on bar    | the depth-capped book-walk fill instead of the default L1 `Tick` model; pair with `slippage = 0.0`                                           |
| `queue_model`                           | tick only — rejected on bar | `"risk_adverse"`, `"prob_power"` / `"prob_power:N"` or `"prob_log"` — a resting limit fills only once flow has consumed the size ahead of it |
| `queue_seed_depth`, `queue_min_hold_ms` | tick only — inert on bar    | the queue lane's seed depth, and a minimum-hold floor on the tagged maker lane's closing fills; both read only when `queue_model` is set     |
| `equity_sample_every`                   | tick only — rejected on bar | thin the equity curve to one sample per `N` ticks (`0` records nothing)                                                                      |

The string-valued knobs are resolved strictly. `EngineCfg::fill_model_kind` accepts exactly one
spelling, case-insensitively, and anything else is a fail-fast validation error — the earlier
lenience let a typo like `"l2_book"` quietly select the optimistic `Tick` model and undo the
depth-cap it was meant to enable. `queue_model_kind` follows the same rule.

<Callout type="warn" title="Thinning the equity curve changes the report">
  `equity_sample_every` exists for a sweep over a very long tape — the curve costs 16 bytes per
  priced tick, so a 100M-tick replay carries 1.6 GB of samples per run whether or not anything reads
  them. But every curve-derived figure (max drawdown, Sharpe, the return series) becomes an
  approximation, and `0` degenerates them entirely. `final_equity`, `n_trades`, the trade log and
  `per_symbol_pnl` never move.
</Callout>

Three sub-tables have their own pages. `[engine.fee]` selects a `vike_model::FeeSchedule` — one
`kind` today, `"probability_scaled"`, the prediction-market curve `qty × rate × p(1−p)` that a flat
rate cannot express; setting it beside a non-zero `fee_rate` is a validation error, because two
cost models would be configured and only one could win ([the cost
model](/docs/trader/backtesting/cost-model)). `[engine.resolution]` builds the binary-outcome settlement
source ([the sim broker](/docs/trader/backtesting/sim-broker)). `[engine.impact]` names the
`"almgren_chriss"` model with its `exec_time` and `window` ([market
impact](/docs/trader/backtesting/market-impact)).

`emulator_release_stops&#x60; defaults to &#x2A;*`true`** in the harness — a fired conditional stop is
released as a market order that fills the next event, as the live emulator does — even though the
low-level `EngineParams` default is `false`, so a profile run reproduces live fill timing without
an explicit knob. `snap_to_properties` wires the store's point-in-time instrument grid into the fill
path and is single-venue only: the grid is looked up under one default venue, so `validate` refuses
it beside a cross-venue slice rather than snapping every series to the first series' venue.

<Callout type="warn" title="Snapping re-tags your bars">
  With `snap_to_properties` on, bar-mode bars are re-tagged `SYMBOL.VENUE` for the grid lookup, so a
  symbol-inferring strategy — `buy_hold` reading `bar.symbol` is the example
  `crates/vike-backtest/src/harness/run.rs`'s
  `bar_engine_params` gives — needs an explicit `strategy.params.symbol` to route.
</Callout>

## Strategy, risk, sweep, walk-forward [#strategy-risk-sweep-walk-forward]

`[strategy]` is a `name` and a `params` table the strategy's own constructor interprets; which
names resolve is [the harness registry](/docs/trader/backtesting/harness-registry).

`[risk]` carries the **same** schema and the **same** compile-checked converter
(`vike_exec::ProfileRisk::to_risk_limits`) the live run profile uses, so a limit proven here by a
real `SimBroker` denial carries unchanged into paper and live. It is the only way a harness
profile arms the pre-trade gate — `[engine]` has no `leverage` knob. One field is rejected:
`risk.max_orders_per_window` is a wall-clock order-rate throttle, and a replayed month can execute
in under a second.

`[paramscan]` turns the profile into a grid — each key a `strategy.params` field, each value an
array to cross-product over; absent or empty means "not a search". ⚠ **The table is named
`paramscan`, and `sweep` is an ALIAS of it** — a permanent one, because the profile is
`deny_unknown_fields` and every file written before the rename would otherwise stop loading. Both
spellings work; `paramscan` is the field.

`[walkforward]` turns it into a sequence of train/validate windows. Both tables live in the profile
rather than on the wire because a `deny_unknown_fields` profile must parse for the whole TOML to be
shippable verbatim to a remote runner, and both are inert for a plain single run.

⚠ **This paragraph said `[walkforward]` "carries one knob, `n_splits >= 1`" — it carries nine
fields**, and two of them (`purge`, `embargo`) are legal on one of its two window forms only. That
sentence was true when it was written, which is why the table is no longer described by hand here:
[`backtest --profile`](/docs/trader/reference/cli/research/backtest-profile) renders every key, default,
accepted value and refusal from the Rust types that declare them. See also
[sweeps](/docs/trader/backtesting/sweeps) and [walk-forward](/docs/trader/backtesting/walk-forward) for what
the two tables are FOR.

When a profile is loaded from a file, `BacktestProfile::from_path` records the file's directory as
`base_dir`, and relative paths inside the profile — today `[engine.resolution].path` — resolve
against it rather than the caller's working directory, so a profile and its sidecar move together.


# Running a backtest (/docs/trader/backtesting/running)



There is one function that turns a profile into a result, and two front ends that reach it.
`crates/vike-backtest/src/harness/run.rs`'s `run_backtest` loads a `BacktestProfile`'s data slice
from an `Arc<dyn HistStore>` — any backend that implements the trait: the DataFusion store in
production, the ClickHouse-reading store the `poly_ch_backtest` bin feeds through the same
dispatcher, an in-memory store in tests — resolves the strategy by name, and runs it in **bar
mode** (`StrategyEngine`) or **tick mode** (`replay_ticks`) according to `profile.data.kind`.

Both modes load the profile's *resolved* series, so a cross-venue `[[data.series]]` slice and the
single-venue pair take the same code path. The fee schedule and the resolution source are built
once for both. The bar arm's engine parameters and bar loading are factored into
`bar_engine_params` and `load_profile_bars` so the walk-forward runner builds identical parameters
and loads identical bars — the divergent-default bug shape this workspace keeps paying for, closed
by construction. One difference is load-bearing: in bar mode nothing else would wire the
point-in-time instrument grid, so `run_backtest` sets it itself when `snap_to_properties` is on;
in tick mode the flag goes to the replay loader, which wires it from its own closure.

## The `backtest` binary [#the-backtest-binary]

`crates/vike-backtest/src/bin/backtest.rs` is a thin shim over `crates/vike-backtest/src/backtest_cli.rs`'s
`run`. The shim is the composition root and holds the two things a library may not: the one
`std::env::vars()` sweep, and the clock. Its usage:

```
backtest --help | --version
backtest --list
backtest --seed-demo [--store DIR]
backtest --profile run.toml [--store DIR] [--json]
backtest --profile sweep.toml [--rank-by sharpe|return|max_dd|equity|multi]
                              [--search grid|euler] [--euler-depth N]
                              [--optimizer tpe [--trials N] [--seed S]]
backtest --fetch VENUE:SYMBOL:INTERVAL (--days N | --from LABEL --to LABEL) [--store DIR]
backtest --fetch-starter [--store DIR]
backtest --export VENUE:SYMBOL:INTERVAL --out FILE [--from LABEL --to LABEL] [--store DIR]
```

`--store` picks the history-store root. Without it the binary resolves `$VIKE_HIST_STORE`, then
`<project>/market_data/hist` for a project `$VIKE_SETTINGS_DIR` declares outright, then
`<repo>/market_data/hist` while the checkout that built the binary still exists, then the project
the working directory sits in, and finally a per-user data directory — logging the root it chose
and the rung that chose it. See [the history store](/docs/trader/concepts/hist-store). `--list` prints
every registered strategy name and exits, needing no store and no profile. `--json` prints the
`BacktestReport` — or, for a sweep, the `SweepReport` — as pretty JSON instead of the human table,
and that stream is a machine contract: every diagnostic goes to stderr so stdout stays parseable.
`--help` and `--version` are answered before the log subscriber is initialised, so neither creates
a log directory.

A profile with a `[sweep]` table runs `run_sweep` instead of a single run; `--rank-by` picks the
ranking metric (default `sharpe`, `multi` for the composite objective), `--search euler` replaces
the exhaustive grid with a bounded successive-halving refinement, and `--optimizer tpe` is the
Bayesian search, which takes precedence over `--search` and is reproducible under `--seed`. See
[sweeps](/docs/trader/backtesting/sweeps), [search](/docs/trader/backtesting/search) and
[objectives](/docs/trader/backtesting/objectives).

<Callout title="The empty-store answer">
  A clean install has an empty history store, so the shipped example profile reports a run with no
  trades, and nothing distinguishes that from a strategy that never fired. `backtest data seed-demo`
  writes a **synthetic** tape under the venue `demo` — a closed-form curve, not market data — which
  is the slice the shipped `user_data/profiles/backtest.toml` names, so a fresh install can run it
  immediately; re-running writes nothing. `backtest data fetch-starter` downloads a published starter
  dataset over plain HTTPS, for a box a venue cannot be reached from at all. Both need the
  `venue-fetch` feature, which the release binary and the container image have; a build without it
  refuses by name rather than silently doing nothing.

  ⚠ **These were FLAGS — `--seed-demo`, `--fetch`, `--fetch-starter`, `--export`, `--rm-series` — and
  they are subcommands now** (`crates/vike-backtest/src/backtest_cli.rs`'s `RETIRED_DATA_FLAGS&#x60;
  refuses each old spelling by name and prints the new one). ⚠ **`--fetch` did not move, it was
  deleted**: `crates/vike-backfill/src/kline_source.rs` records that its venue roster was retired on
  2026-09-19 *by deleting the producer*, because that verb reached a venue directly from the compute
  plane. Fetching real bars is `vike-cli data hist fetch`, which asks a datahub that dispatches
  through the kline registry — one place that knows which venues serve bars, instead of a second
  roster inside the backtester.
</Callout>

Before the profile is loaded, the binary installs the user's own Rhai indicators from `user_data`
(honouring `VIKE_USER_DATA_DIR`), because a `rhai` strategy compiled later may call them and
nothing else installs them; a rejected file is reported on stderr and is never fatal. After a
**single** run prints, the binary persists it to `<project>/user_data/runs/<run_id>/` — after
printing, never changing the exit code; a sweep, a euler refinement or a TPE run writes nothing.
See [runs on disk](/docs/trader/backtesting/runs-on-disk).

## `vike-cli backtest`: the remote path [#vike-cli-backtest-the-remote-path]

`crates/vike-cli/src/cmd/backtest.rs` is a different path, not a wrapper. It runs a real backtest
against a `vike-datahub` server from a machine with **no** DataFusion in its build: it reads a
profile's TOML text locally, ships that text verbatim, and prints the compact report the server
returns. The history never crosses the wire, and the server is the only thing that parses the
profile, with `BacktestProfile::from_toml_str`.

```
vike-cli backtest --profile <run.toml> [--preset <p.toml>] [--script <s.rhai>] [--addr 127.0.0.1:7878] [--json]
vike-cli backtest --list-params --script <s.rhai>
```

`--addr` defaults to `127.0.0.1:7878`; the server refuses a non-loopback bind unless it is
explicitly opted into with node keys configured, so a remote one is reached over an SSH tunnel.
The exit code is `0` when a report comes back and `1` on any failure — bad arguments, an
unreadable file, a transport error, or a server-side error — with the message on stderr. `--json`
prints the server's JSON verbatim; without it the JSON is pretty-printed.

Two client-side rewrites happen before the request. `--script` injects a Rhai file's source into
`[strategy.params].src`, so an authored strategy ships self-contained to a server that cannot see
the client's filesystem. `--preset` merges a flat table of knobs into `[strategy.params]`,
last-wins — resolved **here** rather than named in the profile, because a `preset = "fast"` field
would be resolved against the server's `user_data`, not the author's. Two preset shapes are
refused because accepting them would do nothing visible: a `[params]` wrapper (the strategy would
receive one parameter called `params` that no reader looks at) and a `src` key (a script smuggled
past `--script`). `--list-params` is offline — it prints a script's `param(name, default)` knobs
and opens no connection. `vike-cli sweep` and `vike-cli walkforward` take the same compute-to-data
shape (`crates/vike-backtest/src/harness/sweep.rs` and `crates/vike-cli/src/cmd/walkforward.rs`).

<Callout type="warn" title="The profile is shipped as bytes, not re-parsed">
  `crates/vike-backtest/src/harness/sweep.rs`'s module doc records why: `sweep` and `walkforward` once
  re-parsed the profile into client-side DTOs, and the mapping silently dropped `[engine]` costs,
  `[risk]`, tick slices and cross-venue slices — so a sweep ran under different costs than the same
  profile's `backtest`. Only the `--script` and `--preset` rewrites touch the TOML, each a targeted
  edit of `[strategy.params]`.
</Callout>

The [quickstart](/docs/trader/getting-started/quickstart-backtest) walks this path end to end; the flag
tables are on [the CLI reference](/docs/trader/reference/cli/research/backtest) and [the `backtest` binary
page](/docs/trader/reference/binaries/backtest), and the server on
[`vike-datahub`](/docs/trader/reference/binaries/vike-datahub).


# Runs on disk (/docs/trader/backtesting/runs-on-disk)



A backtest that only prints has no history: nothing to list, nothing to compare a second run
against, nothing a UI could show. `crates/vike-model/src/runs.rs` is where that stops being
true. Every finished single run gets one directory under `<project>/user_data/runs/` — the
`vike_model::state_path::RUNS_SUBDIR` location — holding two files:

```
user_data/runs/<run_id>/
  report.json      this run's BacktestReport — the same JSON `backtest --json` prints
  manifest.json    the common, kind-agnostic manifest
```

The report is the kind-specific half; only its file name is common. The manifest is the
load-bearing half, and its shape is an argument.

## Why the manifest is common [#why-the-manifest-is-common]

A listing must be able to render a row without a parser per kind. Run kinds differ in what their
results contain, not in what a listing needs to say about them, so those fields sit at the **top
level** of `RunManifest`, identical for every producer, and everything kind-specific nests below
them in `detail`:

| field                       | meaning                                                                                                                                                                                            |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `run_id`                    | the directory name, duplicated into the file so a copied manifest still says which run it is                                                                                                       |
| `kind`                      | `"backtest"` here — the one field a reader may branch on; a plain string because the set of kinds grows in crates that cannot see each other                                                       |
| `produced_by`               | the binary, spelled literally: `"backtest"`, not the package name                                                                                                                                  |
| `started_at`, `finished_at` | RFC-3339 UTC to the second; `finished_at` is read before printing, so it measures the run and not the terminal                                                                                     |
| `git_sha`                   | **always serialized, `null` included**, so "could not name a build" is distinguishable from "written before the field existed"; `backtest` writes `null` because it takes no build-info dependency |
| `config`                    | `path` as the operator spelled it on the command line — deliberately not canonicalized, since that is what they can paste back — and `name`, the profile's label                                   |
| `detail`                    | everything kind-specific, nested so a reader that does not recognise `kind` still renders a complete row                                                                                           |

A kind-specific field placed beside those is the defect the shape exists to refuse: every reader
would then need to know which kind it holds before reading the first key. There is no
constructor and every field is public, so a new common field stops every producer compiling until
it decides what to put there.

## The write order is a completion marker [#the-write-order-is-a-completion-marker]

`write_run` writes the report **first** and the manifest **last**. The report is the irreplaceable
half, so a disk that fills between the writes costs the metadata rather than the result — and the
order hands a reader a completion marker: a directory holding `manifest.json` finished writing,
so a listing can skip a half-written run without a lock file or a rename dance.

The reader honours that. `read_manifest`'s `RunReadError::Missing` is deliberately distinct from
`RunReadError::Read`: a missing manifest means a run being written right now or a process that
died between the two writes; an unreadable one is a file that exists and cannot be opened. A
listing renders them as different rows because they have different fixes — wait, versus go and
look. The reader lives beside the writer because a reader written up the dependency graph would
be a second definition of a common manifest, the one outcome the shape cannot survive.
`crates/vike-studio-core/src/listing.rs`'s `list_runs` is its first consumer.

## The run id, and why the filesystem guarantees it [#the-run-id-and-why-the-filesystem-guarantees-it]

The id is `<unix-seconds>-<pid>-<seq>`: seconds say when, the pid says which process, `seq` breaks
the rest. None of the three is the guarantee. `create_run_dir` mints the id by **creating the
directory** — `create_dir` is atomic and fails with `AlreadyExists` rather than opening what is
there, so the first creator owns an id and every later one advances to the next `seq`. The id is
not checked and then used; creating is the check. It gives up after 1,000 attempts, which in
practice means a runs directory refusing creation rather than a flood.

<Callout title="Persisting is additive, never a new way to fail">
  `crates/vike-backtest/src/backtest_cli.rs`'s `persist_run` runs **after** the report has reached
  stdout and never changes the exit code; a run whose directory cannot be created has still
  computed its numbers, and the failure is named on stderr. Only the single-run path persists — a
  sweep, a euler refinement or a TPE run answers with a `SweepReport`, a different run kind, and
  writes nothing. The runs directory is resolved by the binary through
  `vike_model::state_path::user_runs_dir`, so a run cannot land in one project while its strategy
  was read from another.
</Callout>

One residual is declared on `persist_run`: `VIKE_USER_DATA_DIR` redirects the `user_data` root for
the indicator load but does **not** move the runs directory. Time, like the path, is an input —
nothing in the module reads a clock — and a second producer has already taken the intended
branch: `crates/vike-studio-core/src/study_run.rs`'s `run_study` persists a study run by calling
`create_run_dir` and `write_run`.

## The report, and its annualization [#the-report-and-its-annualization]

`report.json` is `harness::BacktestReport`, a re-export of `vike_analytics::report::BacktestReport`
— the struct lives outside the feature gate so a DataFusion-free consumer need not reassemble its
own copy. Its fields are on [the report](/docs/trader/analytics/report); the one piece that stays in
the harness is `crates/vike-backtest/src/harness/report.rs`'s `periods_per_year`, because it needs
the profile.

Sharpe annualizes by `sqrt(periods_per_year)`, where the count must be the number of return
observations a year produces — one per bar. This used to return the daily 252 for every interval,
so a one-minute run was annualized as though its bars were daily, understating every intraday
Sharpe by `sqrt(1440) ≈ 37.9x` — silently, because the number still looked like a Sharpe — and
making `--rank-by sharpe` incoherent across a sweep whose points differ in interval. Now the daily
anchor is preserved exactly (`"1d"` returns `DAILY_PERIODS_PER_YEAR`, so no daily report moves by
a bit) and every other interval scales off it: `252 · (86_400_000 / interval_ms)`, so `1h` gives
6,048 and `1m` gives 362,880. Two limits are stated rather than hidden: 252 is an equity
convention and these markets trade every day, so 365 would be defensible, but changing it would
move every existing daily report; and a tick profile still gets `DEFAULT_PERIODS_PER_YEAR`,
because a tick stream has no fixed period. An unparseable interval falls back to the default
rather than fabricating a scale.


# Scheduling (/docs/trader/backtesting/scheduling)



A backtest strategy can ask to be called back on a schedule — the first bar of a new month, every twenty bars, 08:00 UTC each day — and `crates/vike-backtest/src/schedule.rs` fires those callbacks at bar boundaries. It ports the original `core/schedule.py` together with `analysis/periods.py`'s `period_key`, with one Rust adaptation: Python registered arbitrary closures, but a stored closure capturing the strategy cannot coexist with the engine's `&mut` borrow of it, so a rule is registered with a string **tag** and the engine fires `Strategy::on_schedule(ctx, tag)` for each due rule. The firing points and cadence are identical.

## Rules [#rules]

`DateRule` is the question "should a scheduled callback fire at this bar?", in three shapes:

* `PeriodStart { period }` fires on the first bar of each new calendar period. `period_key` labels the period containing a timestamp — `"2024-03-15"` daily, `"2024-W11"` weekly (ISO), `"2024-03"` monthly, `"2024-Q1"` quarterly, `"2024"` yearly — and the rule fires when the label changes. `DateRule::month_start`, `week_start`, `quarter_start` and `year_start` are the constructors. The label delegates to `vike_analytics::periods::period_key`: the two used to be hand-maintained twins, one chrono-free and one chrono, a divergence foot-gun, and the backtest is off the latency-gated path so the shared implementation is fine here.
* `EveryNBars { n }` fires when `bar_index % n == 0`; `every_n_bars(n)` asserts `n >= 1`.
* `Time { rule }` wraps a wall-clock `TimeRule` and fires on the first bar at or after each scheduled instant, latching the last instant so it fires once per instant.

`Schedule` is the registry of `(rule, tag)` pairs. `Schedule::on(rule, tag)` registers; `check_due(ts, bar_index)` returns the tags due at this bar, firing each rule at most once per `bar_index`. In `crates/vike-backtest/src/engine.rs`'s step loop the engine fans `on_bar` out per symbol, then calls `check_due` and fires `on_schedule` per tag — and only once the step index has reached `warmup()`, the gate this loop puts in front of `on_bar` and `on_schedule` and the tick lane in front of `on_quote_tick` and `on_trade_tick`. `on_fill` is not behind it (`fire_on_fill` applies no warmup test), and neither is `on_order_book`: book events deliberately do not advance the warmup index and are delivered as soon as a valid book exists.

`schedule` is a public field on `SimBroker`, and the broker's `impl Broker` doc lists it with the other backtest-rich verbs that stay inherent on the concrete broker. Registering a rule therefore takes an `impl Strategy<SimBroker>`; `vike_model::strategy`'s module doc names the bar-count schedule as one of the five simulator-only concepts — `every_n_bars` has no wall-clock meaning, and the live schedule takes wall-clock rules as mount configuration, unreachable from a strategy's `on_start`. See [simulator-only strategies](/docs/trader/strategies/simulator-only).

## The shared wall-clock rule [#the-shared-wall-clock-rule]

`TimeRule` lives in `crates/vike-model/src/schedule.rs`, and its home is the point. It is a pure, allocation-free, clock-free `Copy` value type in the domain model, so both consumers reach it down-only: the live runtime fires it off the deadline timer wheel at the drain-loop boundary and keeps the `LiveSchedule` registry that owns a mount's rules, while the backtest drops the same `TimeRule` into `DateRule::Time` and checks it per bar. One rule, one law — `TimeRule::last_instant_at_or_before` is the single crossing primitive both paths call, so a rule computes byte-identical fire instants whether it is driven by bar timestamps or by the injected boundary clock. It is not on the hot path: the live registry is consulted only at the drain-loop boundary, never per market message. [Timers](/docs/trader/concepts/timers) describes the wheel.

A rule fires at `minute_of_day` (0 to 1439) in a fixed-offset timezone on a weekday bitmask (bit 0 Monday through bit 6 Sunday; `0` never fires). The constructors are `daily_at_utc(hour, minute)`, `daily_at(hour, minute, tz_offset_min)`, `on_days(hour, minute, tz_offset_min, weekdays)` — which panics on an out-of-range HH:MM, a programmer error — and `session_offset(anchor_minute_of_day, offset_min, tz_offset_min, weekdays)` for a market-open or market-close offset, wrapping into the day: "5 minutes before the 16:00 close" is `session_offset(960, -5, tz, TimeRule::WEEKDAYS)`, which is 15:55. `TimeRule::ALL_DAYS` and `TimeRule::WEEKDAYS` are the two shipped masks.

<Callout title="The timezone model is deliberately DST-unaware">
  `tz_offset_min` is a fixed offset from UTC in minutes — UTC is `0`, UTC+2 is `120`, UTC−5 is `−300`. That covers the 00:00 UTC and 08:00 UTC expiry cases and any fixed-offset market; an IANA, DST-aware variant is named as a future extension because it needs a calendar dependency this pure core avoids.
</Callout>

## The latch [#the-latch]

`TimeRule::crossed(now_ms, last)` advances a per-rule latch and reports whether a new instant was crossed. The first call establishes the latch at the most recent past instant **without firing**, so a schedule mounted — or restored after a restart — mid-period fires at the next instant, never a spurious catch-up of the one that already passed. Thereafter it fires only when the most recent instant has advanced, coalescing any instants skipped across an idle gap into a single fire of the latest. `DateRule::Time` calls that same `crossed`, from the same definition, which is what makes a rule fire at byte-identical points on both stacks.


# Search (/docs/trader/backtesting/search)



A cartesian [sweep](/docs/trader/backtesting/sweeps) evaluates every point of every axis, so resolution costs exponentially. Two search lanes buy resolution cheaper, both over the same `[sweep]` table, both returning the same ranked `SweepReport`, both scoring through the same [objective](/docs/trader/backtesting/objectives) seam. Neither reimplements scoring or backtesting.

## Successive halving [#successive-halving]

`crates/vike-backtest/src/search.rs` is the pure, store-free core of Euler search. Evaluate the coarse grid once; then, up to `max_depth` times, halve every axis's step and evaluate the `{best − step, best, best + step}` neighbourhood of the incumbent — at most `3^d − 1` new points per depth, clamped to each axis's box and deduplicated against everything already seen. After `D` halvings the effective step is `step / 2^D`, the resolution of a grid with `2^D·(n_i − 1) + 1` values per axis. The module's own arithmetic: a two-axis 5×5 grid at depth 3 costs at most 25 + 24 = 49 evaluations against 33×33 = 1,089 for the equal-resolution grid.

A halving that fails to improve the incumbent is not a stop condition — it is the signal to shrink again, since only a smaller step can reach the points between the incumbent and the ones just rejected. The search runs its full depth budget and stops early only when a depth produces no unseen candidate at all. `SearchTrace::depth_reached` therefore reports the resolution actually attained, and `EulerConfig` caps depth at `MAX_DEPTH_CAP` of 16 (already 65,536× the coarse resolution), with `DEFAULT_MAX_DEPTH` of 3; depth 0 evaluates exactly the grid. A `SearchAxis` refines at its own smallest existing gap, an integral axis rounds every candidate and stops once its step falls below 1, and a single-valued axis stays pinned. Scoring follows the objective convention: higher is better, `NaN` is unrankable and can never displace a finite incumbent — it is only ever the incumbent while nothing finite has been evaluated.

<Callout type="warn" title="It is a local refinement">
  Successive halving can only descend into the basin its coarse grid already found; a grid too sparse to see a narrow optimum refines the wrong peak, pinned by `refinement_stays_in_the_basin_the_coarse_grid_chose`. Keep the coarse grid wide, the depth bounded, and treat this as a refinement of a grid, not a replacement for one.
</Callout>

`crates/vike-backtest/src/harness/euler.rs` is the store-backed wrapper, reached with `--search euler`; the default `--search grid` is untouched. `run_sweep_euler` returns the grid path's `SweepReport` — only evaluated points appear as rows, which is the saving, and a failed backtest scores `NaN`, which can never displace a finite incumbent as the refinement centre — plus an `EulerBudget` whose `equivalent_grid` is computed at the depth **actually** reached, never the requested `max_depth`, so an early-stopped run cannot advertise a saving it did not buy. It prints as `euler: N evaluations at depth d/D (grid at the depth reached would be G)`; `equivalent_grid_evaluations` states its precondition, a uniformly spaced axis, and that a non-uniform axis overstates what the search covered. Every `[sweep]` axis must be numeric and type-homogeneous: a mixed `[1, 2.5]` axis would silently change the TOML type the strategy receives versus the grid path, so a non-numeric or mixed axis is a `HarnessError::Validation` pointing at `--search grid`, and `MAX_AXES` of 8 is where the `3^d` neighbourhood stops being cheaper than the grid. Points within one depth are independent backtests and run on the bounded sweep pool; depths stay sequential, and the trace, rows, budget and ranking are identical to the one-at-a-time path.

## TPE Bayesian optimization [#tpe-bayesian-optimization]

`crates/vike-backtest/src/harness/tpe.rs` is the ask/tell alternative: it converges on good `strategy.params` by modelling which regions of the space produce good scores and proposing there. It is a clean-room implementation of the mathematics of Bergstra, Bardenet, Bengio and Kégl, *Algorithms for Hyper-Parameter Optimization* (NeurIPS 2011), §4, restated for the maximise convention. The history is split at the `gamma` quantile of score into good and bad; per parameter, independently, two Parzen densities `l(x)` and `g(x)` are built; expected improvement is monotone in `l(x)/g(x)`, so a continuous parameter draws `n_candidates` samples from `l` and proposes the argmax of the ratio, while a discrete parameter samples its next category from `l` directly, because an argmax over a small category set would lock onto the incumbent. A continuous parameter uses an adaptive Parzen estimator — one Gaussian per observation plus a broad prior at the domain midpoint, each bandwidth the maximum distance to its sorted neighbours, clipped — and a discrete one a prior-smoothed frequency histogram. The first `n_startup` asks are random, to seed the model.

`TpeConfig` carries `n_trials` (`DEFAULT_TRIALS` 64), `seed`, `gamma` (0.25), `n_startup` (10) and `n_candidates` (24). A profile's `[sweep]` axes become continuous ranges bounded by each axis's minimum and maximum, integral axes staying whole — TPE explores between the grid points, the same philosophy as successive halving — through the same `numeric_sweep_axes` reader and the same rejection of non-numeric or mixed axes. `run_tpe` asks, runs the proposal through `run_backtest`, scores it and tells the result back, for `n_trials` trials; the loop is inherently sequential because each proposal reads the whole history, so there is no rayon fan-out and determinism rests entirely on the seed.

<Callout type="warn" title="Same seed, same proposals — now on every platform">
  Every stochastic step draws from a seeded `SplitMix64` the optimizer owns, chosen over a library generator because its ten lines are fixed forever. The module records a correction dated 2026-08-28: the contract claimed byte-for-byte reproducibility and did not hold across platforms. The integer stream was never the leak; the two float transforms on top of it were — a Box–Muller `ln` and `cos`, and the density's `exp` — because IEEE 754 requires nothing of those functions, so an `f64` method call reaches the platform's libm and two boxes disagree in the last bit. One perturbed draw moves a candidate, which moves the argmax, which moves every later proposal: the sequences fork. All three now call the `libm` crate, one pure-Rust implementation compiled into the binary; `.sqrt()` stays a method because IEEE 754 does require it correctly rounded. `same_seed_same_proposals` pins within-box determinism only.
</Callout>

## From the command line [#from-the-command-line]

`backtest --profile sweep.toml --search euler [--euler-depth N]` (default 3, capped at 16) writes a one-line budget summary to stderr; `--optimizer tpe [--trials N] [--seed S]` (defaults 64 and 0) takes precedence over `--search`. Both reuse `--rank-by` as the objective and stamp a `score` on every row whose backtest succeeded; a failed row carries none. The [TPE parameter search](/docs/trader/tutorials/tpe-parameter-search) tutorial runs both over one profile.


# The sim broker (/docs/trader/backtesting/sim-broker)



`crates/vike-backtest/src/engine/sim_broker.rs` holds `SimBroker`: the engine state plus the
strategy-facing verbs and reads — the `ctx` every `Strategy` handler receives. It was split out of
`engine.rs` with behaviour byte-identical, and it carries the two types a run is configured with:
`EngineParams`, the cost and knob surface, and `SymbolState`, the mutable state kept once per
symbol.

## Per-symbol state [#per-symbol-state]

Each symbol owns a `SymbolState`: the `Position`, the untagged `pending` orders, realized PnL, the
armed protective `stop`, entry fee and timestamp, the last seen `price`, the running high and low
since entry (for MAE/MFE), the higher-timeframe aggregates, the granular sub-bars, and the
`tagged` map — resting tagged limit orders for the maker lane, keyed by the strategy's stable tag.
That map is an `IndexMap` so fill order is deterministic insertion order, and it is kept separate
from `pending` so the parity-gated untagged paths are untouched: it is empty for every non-maker
strategy. A filled or cancelled tag is removed, which reproduces the live tag registry's
observable semantics.

## The parameters [#the-parameters]

`EngineParams::default()` is a fee-free, slippage-free run with `10_000.0` cash, multiplier `1.0`,
the `Bar` fill model and every opt-in knob off; each knob's absence is byte-identical to the
engine before it existed. The ones you meet first:

* `fee_rate`, `maker_fee`, `taker_fee`, `fee_schedule`. A schedule overrides the flat chain by its
  `maker_taker_rates()` — except the probability-scaled prediction-market curve, which has no flat
  equivalent and is routed to the exact per-fill `FeeSchedule::commission` rather than silently
  charging nothing.
* `fill_model`: `Bar` (default), `Tick` (L1 spread-crossing) or `L2Book` (a taker consumes the
  replayed book for its own size; degrades to `Tick` where no book exists — pair it with
  `slippage: 0.0`, the walk is the slippage). See [fill models](/docs/trader/backtesting/fill-models).
* `leverage`, `risk_limits`, `clamp_to_leverage` — the pre-trade gate, below.
* `maint_margin`, `liq_buffer` (default `0.10`), `venue_style_liquidation` — the margin call.
* `cash_gate`, `active_mask`, the three open-position caps, `volume_limit` and `sizer`.
* `properties`: an optional point-in-time grid lookup `(venue, symbol, ts) → grid`, a plain
  closure the harness builds over the store.
* The tick-lane knobs (`queue_model`, `latency_model`, `equity_sampling`), the settlement lanes
  (`resolution`, `option_specs`, `settlement_period_ms`), `max_price_staleness_ms`, `session_gate`
  and `emulator_release_stops`.

## Every verb but one crosses the same gate [#every-verb-but-one-crosses-the-same-gate]

The intake verbs are `submit`, `submit_close`, `submit_limit`, `submit_stop`, `submit_trailing`,
`submit_market_close`, `submit_limit_close`, `cancel_all`, and `strategy_order_target_percent`,
which sizes through `vike_model::units_from_percent` — the same converter the live target verb
uses, so a multiplier-bearing instrument sizes identically live and in backtest.

Every opening verb runs the sizer first (`size_entry`, opening or increasing entries only, passed
through when `raw`), then `gate_order`. The default gate **is the literal live gate**: the order
crosses `vike_exec::RiskGate::check` over a `RiskContext` built from the engine's own state,
mirroring the live construction field for field, and a refusal is whole — zero fill — recorded in
`dropped` under the gate's own reason string, so a backtest denial is the live denial.
`build_risk_gate` mounts it once: explicit `risk_limits` verbatim; else `leverage: Some(L)` mapped
to an initial-margin requirement of `1/L` (the doc carries the equivalence to the retired
leverage-room formula and its limits); else no gate and a submit path byte-identical to the
pre-gate engine. The mounted gate always has `max_orders_per_window` disarmed, because sim time
is not wall time. `clamp_to_leverage = true` is the escape hatch: `cap_to_leverage` truncates the
order to the remaining room and executes it silently, and the gate is never consulted.

<Callout type="warn" title="Limits were once ungated">
  `gate_order` was `gate_market_order` and ran for the two market verbs alone; the limit, stop,
  trailing and tagged maker submits faced no pre-trade gate, so a backtest of a limit strategy ran
  with the operator's `[risk]` budget effectively off while live gated all of them — the backtest was
  the permissive side. Every order-submitting verb but `submit_close` is gated now. A covered
  reducing order bypasses the floors, the collar and buying power — on a bankrupt account
  included — but still faces the per-order notional and projected-exposure caps. The live half is
  [risk and arming](/docs/trader/concepts/risk-and-arming).
</Callout>

## One fill-application path [#one-fill-application-path]

Every fill dispatcher ends in `apply_fill`. It prices the adverse move through `slippage_for` —
the flat `slippage`, plus the size-dependent impact addend for taker fills only, because an order
that rested and got hit was supplying liquidity and charging it impact would fill a resting limit
through its own price — then snaps to the point-in-time grid when one is configured, price to the
tick and size to the step through `vike_model::round_to`. An **opening** fill below `min_qty` or
`min_notional` is rejected under that reason; a **closing** fill always executes, falling back to
the raw size if step-rounding zeroed a remainder, so a position is never stranded below the
minimum. `is_maker` is decided by order kind — a `Limit` books as a maker fill even when
marketable — and the fee is the flat fold or the exact schedule commission. The post-cost fold is
shared with `settle_at_payout`, the fee-free, slippage-free, grid-free settlement a resolved
market or expired option closes through.

The opening/closing split is direction-only, while the live gate's floor bypass requires
coverage, so a below-minimum **reversal** executes whole here and is denied live;
`below_min_reversals` counts it. The field's doc argues the divergence is unreachable above dust
at real venue floors — reversing a position worth under about five dollars — and that fixing it
would change fill decisions without converging the engines, so the counter stays as a claim a run
can contradict.

## Reads, and the diagnostics [#reads-and-the-diagnostics]

The reads a strategy steers on: `position_of`, `price_of`, `equity_now` (cash plus signed
notional, folded in symbols order with the compensated sum), `drawdown_now`, `pending_of`,
`protective_stop_of`, `in_flight_of`, `is_resolved`, `price_is_stale`, `symbol_is_open`, and the
higher-timeframe `bars_for` / `forming_for`. The predicates are total — an unknown symbol answers
the permissive default (`false` for `is_resolved` and `price_is_stale`, `true` for `symbol_is_open`)
rather than panicking inside a callback — while the write verbs fail loudly on one.

<Callout type="warn" title="Under the latency gate, an in-flight order is invisible">
  With a latency model armed, a submitted order still in flight is in neither `pending_of` nor the
  position. The idiom `if pending_of(s).is_empty() { submit(..) }` re-fires on every tick of the
  entry window; write it as `pending_of(s).is_empty() && in_flight_of(s) == 0`. The tagged maker
  lane is immune — an insert under an existing tag replaces it. See [latency
  models](/docs/trader/backtesting/latency-models).
</Callout>

What a run leaves on the broker: `dropped` — `(symbol, reason, size, weight)` for every refused
fill, with reasons including the order kind for cash-gate drops, `"volume_cap"`,
`"latency_reject"`, `"min_qty"` / `"min_notional"` and the live gate's own strings;
`stale_deferrals` and `session_deferrals`, so a run with few trades can say "the venue was shut"
rather than "the strategy never traded"; `slippage_saturations`, fills priced on the adverse-move
floor; `intrabar_both_hit`; `settlements` and `variation_settlements`; and the trade list. The
open-position caps count positions, never resting or in-flight orders, at fill time. Under
`settlement_period_ms` each period's mark-to-market is booked into realized and the cost basis
reset, with equity invariant by construction.


# Staleness (/docs/trader/backtesting/staleness)



A repeated last price is not a tradeable price. `crates/vike-fills/src/staleness.rs` opens with
the case: on sparse feeds — Polymarket especially, where an outcome token can go minutes without
a trade — a resampled series emits flat, forward-filled bars, and a market order that fills
against one manufactures edge that never existed. The discipline this module supplies makes such
an order **wait** for a fresh print.

It is enabled only by `EngineParams::max_price_staleness_ms`. `None`, the default, means the
module is never consulted and every fill lane is byte-identical to the pre-feature engine; the
header lists the parity and golden suites that all run with `None`. A
[run profile](/docs/trader/backtesting/run-profiles)'s `[engine]` table carries no key for it — the
knob is set on `EngineParams` by a caller building the engine directly.

## The three rules [#the-three-rules]

The header states them once, and each is one function.

1. **What counts as a fresh print** — `is_fresh_print`. An event carrying genuine current price
   evidence: `volume > 0.0` (a real transaction happened in this event or period) **or** a live
   two-sided quote (`bid` and `ask` both present — resting liquidity you can actually cross). A
   zero-volume, quote-less bar is precisely the fill-forward shape, and is the thing this
   discipline exists to refuse. A one-sided quote is not crossable and is not a print.
2. **Which orders defer** — `defers`. `Market` and `MarketClose` **only**. Those resolve at
   "whatever the current price is", so a stale price silently becomes their fill price. `Limit`,
   `LimitClose`, `Stop`, `Trailing` and the protective-stop lane are price-conditional: a repeated
   stale price cannot spuriously satisfy a condition it did not already satisfy, and gating a
   protective stop would strand live risk. They pass through untouched.
3. **When a price is stale** — `is_stale`. The age of the symbol's last fresh print, measured
   against the event clock, **strictly** exceeds the bound. Age `0` — this very event is a
   print — therefore always fills. A symbol that has not printed at all yet is stale by
   definition: there is no evidence of a tradeable price, so its market orders keep waiting.

Because the comparison is strict, `Some(0)` is the tightest useful setting — fill only on an
event that is itself a fresh print. A negative bound is clamped to `0` rather than taken
literally: read literally, `age > −1` would make even age `0` stale and nothing could ever fill,
a silent total freeze from a plausible typo. A negative age — an out-of-order event stamped
before the last print — is never stale.

## What a deferral is [#what-a-deferral-is]

A deferred order is not cancelled and not rejected, and it is never lost. It stays in `pending`
exactly as it was and is retried on the very next event for that symbol, so it fills on the next
fresh print, at that print's price. The only way a deferred order stops resting is the way any
resting order does: the strategy cancels it, or an opt-in resolution or expiry lane retires it.

`SimBroker::stale_deferrals` counts how often a deferral happened, and it is mirrored onto
`BacktestResult::stale_deferrals` by both `run` and `run_ticks`, so callers that drop the
engine — the harness and the `backtest` bin — can read it too. The
[result](/docs/trader/analytics/result) carries it for one reason: "zero trades because the tape never
printed" must stay distinguishable from "zero trades because the strategy never traded". The
[zero-trade analyzer](/docs/trader/analytics/sizing-and-zero-trade) turns a non-zero count into a
named cause, `stale-price`, whose detail says the tape never printed fresh data within the bound
and may be forward-filled or zero-volume across the window.

A strategy can also ask before it sends. `SimBroker::price_is_stale(symbol)` is the read-only
surface — a maker can check it before sending a taker order it knows would be deferred. It
answers `false` when the discipline is off and on an unknown symbol, and on the bar path it
measures against **that symbol's own current bar timestamp** rather than the engine clock, so
that on a ragged multi-symbol tape the predicate agrees with the engine's actual deferral
decision.

## The clock is event time [#the-clock-is-event-time]

Every age is `event_ts − last_print_ts`, both drawn from the tape. Nothing reads a system clock,
so a replay of the same tape yields the same deferrals on any machine at any speed — the
determinism the golden and parity suites depend on.

## Which tier it actually bites [#which-tier-it-actually-bites]

<Callout title="The target is the bar tier">
  Forward-filled and no-trade bars are real on `StrategyEngine::run`, including the cash-gated
  lane: a resampled sparse series emits flat zero-volume bars, and without this knob a market order
  fills against them. Freshness is recorded once per symbol per step from that step's coarse bar,
  immediately before the fill phase, so a bar that is itself a print has age `0` and fills on the
  spot.
</Callout>

On the granular sub-bar lane each sub-bar is a first-class print: it is recorded before its own
fill pass and the age is measured at the sub-bar's timestamp, because recording only the coarse
bar while measuring at sub-bar time would make every later sub-bar of a fully fresh step
spuriously stale. A fully printing granular step never defers; a quiet stretch within a step
does, which is the point of the finer tier.

The tick tier is inert **by construction**, and the header says that is correct: each fill event
there is the symbol's own just-arrived tick, recorded as a print immediately before the fill
phase, so the age is always `0`. Freshness there is decided from the tick kind — a `Tick::Trade`
counts as a print regardless of its reported size, since some venues emit zero-size index prints
that would project to zero volume with no quote. The tick path already waits for fresh data
structurally, because an order rests until the symbol's next tick arrives; the gate is still
wired into it so the policy has one definition rather than two. Book events never reach the
price/fill path at all, so there is nothing to gate.

The knob composes with the other bar-lane knobs. `crates/vike-backtest/tests/fills/knob_composition.rs`
arms [impact](/docs/trader/backtesting/market-impact), staleness and variation-margin settlement on
one run and proves each stays individually observable while the others are on — staleness there
pushes a fill one bar out, onto a bar whose open is a different price.


# Sweeps (/docs/trader/backtesting/sweeps)



A sweep is a [run profile](/docs/trader/backtesting/run-profiles) with a `[sweep]` table. Each key names a `strategy.params` field and each value is a TOML array of values to cross-product over; `crates/vike-backtest/src/harness/sweep.rs`'s `expand_sweep` turns the profile into the cartesian product of single-run profiles, each with its params overridden per point and its own `sweep` field cleared, so every expanded point is itself a plain runnable profile. A profile with no `[sweep]` table, or an empty one, expands to exactly one point with no overrides — the non-sweep path is unchanged.

Two rules apply at expansion, each a `HarnessError::Validation`: every entry must be a non-empty array (`sweep_axis_array`), and the product is returned in a deterministic order — axes sorted by key, values in array order, the last axis varying fastest. The grid keeps each raw `toml::Value`, so a string or boolean axis is fine here; the [search](/docs/trader/backtesting/search) lanes narrow the same table to numeric axes.

## Running and ranking [#running-and-ranking]

`run_sweep` runs every `SweepPoint` through `run_backtest` — the same dispatcher a single run uses — and collects a `BacktestReport`, or the error string, per point. A per-point failure does not fail the sweep; it is recorded as that row's `error` so the report still shows every point and which ones failed. Successful rows are ranked by a `RankMetric` — `sharpe` (the default), `return`, `max_dd` or `equity` — with failed rows last. `RankMetric::cmp_reports` orders a `NaN` sort key last rather than first, so a Sharpe over a zero-variance curve cannot win the sweep and feed downstream selection. `run_sweep_with` ranks the same rows by any [objective](/docs/trader/backtesting/objectives) instead, stamping each row's `score`.

The result is a `SweepReport { rows, rank_by }`, each `SweepRow` carrying its `overrides`, its `report` or `error` — never both — and an optional `score`. A non-finite score serialises as `"score": null`, which the module pins as the documented meaning of "unrankable" independent of the serialiser. Sharpe is annualised through `harness::report::periods_per_year` for the single run and every sweep row alike, so both rank on the same scale.

## Parallel by default, byte-identical either way [#parallel-by-default-byte-identical-either-way]

Every expanded point is an independent single run over one shared `Arc<dyn HistStore>`, so the points run on a rayon pool. Determinism does not rest on scheduling: `par_iter().map().collect::<Vec<_>>()` is order-preserving, so rows come back in `expand_sweep` order regardless of which point finished first, and the ranking sort is `slice::sort_by`, which is stable, over that same order — the identical bytes the one-at-a-time loop produced, pinned by `parallel_and_sequential_sweeps_are_byte_identical`. `crates/vike-backtest/src/harness/sweep.rs`'s `sort_scored_rows` names the stable sort as part of what keeps the parallel and sequential execution paths byte-identical, and its `SweepExec` doc calls the choice purely an execution-strategy knob: swap either property for an unordered collect or an unstable sort and byte-identical output dies.

<Callout type="warn" title="Parallelism multiplies the data slice, so it is bounded">
  The shared `Arc` shares the store handle, not the loaded data: each point calls `run_backtest`, which re-scans and materialises its own `Vec<Bar>` or `Vec<Tick>`. Peak RSS and store I/O are `N_threads × slice`, not `1 × slice`, and these sweeps run on boxes that also host live trading. The points therefore never run on rayon's global pool: `install_bounded` builds a pool of `sweep_threads` workers — `VIKE_SWEEP_THREADS` when it parses to a positive integer, else `min(4, available_parallelism())`, with `DEFAULT_SWEEP_THREADS` of 4 kept small on purpose and never zero, because rayon reads zero as one worker per core. Size the variable against the slice, not the core count.
</Callout>

A pool that fails to build — the OS refusing a thread spawn — is logged and the work runs on the ambient pool instead; the results are identical, only the bound is lost. `VIKE_SWEEP_SEQUENTIAL=1` (the exact string `"1"`) pins the whole process to the one-at-a-time loop, and every entry point has an `_exec` twin taking `SweepExec` explicitly, which is what the determinism tests use so they never touch the process environment. `map_bounded` is the public front door for another crate's sweep — `crates/vike-studio-core/src/run.rs`'s `run_sweep_slice` reaches the same bounded pool through it without taking a rayon dependency of its own.

On a long tick tape the equity curve is the other memory multiplier. `EngineCfg::equity_sample_every` exists as the sweep knob for it: the curve costs 16 bytes per priced tick, so a 100M-tick replay carries 1.6 GB of samples per run, paid by every point whether or not anything reads them — at the price of making every curve-derived figure an approximation. It is tick-mode only and rejected on a bar profile.

## Shared optimizer glue [#shared-optimizer-glue]

This module also owns the per-point plumbing the search lanes fold through instead of re-rolling it: `numeric_sweep_axes` (the one `[sweep]` reader, adding the numeric and type-homogeneity narrowing), `profile_with_overrides` (base plus overrides into the single-run profile every point becomes), `eval_scored_point` (point to scored row plus steering score) and `sort_scored_rows` (the best-first ordering over `cmp_scores_desc`). One implementation means the grid, successive halving and TPE cannot drift apart on validation, evaluation or ranking, regression-gated by `euler_and_tpe_rank_rows_exactly_like_run_sweep_with`.

## From the command line [#from-the-command-line]

`backtest --profile sweep.toml [--rank-by sharpe|return|max_dd|equity|multi] [--search grid|euler] [--optimizer tpe [--trials N] [--seed S]]` — the standalone `backtest` binary detects the `[sweep]` table itself; `--rank-by` is ignored, not an error, on a non-sweep profile. A sweep prints a ranked table (or `SweepReport` JSON under `--json`) and, unlike a single run, writes nothing under `user_data/runs/` — it is a different document and a different run kind, deliberately not smuggled into the manifest yet. See [runs on disk](/docs/trader/backtesting/runs-on-disk), the `vike-cli` [sweep verb](/docs/trader/reference/cli/sweep), [running a sweep on the data service](/docs/trader/guides/sweep-on-the-service), and the [sweep and walk-forward](/docs/trader/tutorials/sweep-and-walk-forward) tutorial.


# Tick replay (/docs/trader/backtesting/tick-replay)



Tick replay is the offline twin of the live tick recorder. `crates/vike-backtest/src/hist_replay.rs` turns the quote, trade and book rows a `HistStore` recorded into the input of `StrategyEngine::run_ticks` and hands back the same `BacktestResult` a bar run produces. The whole module sits behind the `hist-replay` Cargo feature, compiles against the `HistStore` trait alone and names no DataFusion type; only `replay_ticks_streaming`, gated a step further behind `datafusion-store`, opens the concrete `DataFusionHist`.

## From store rows to one stream [#from-store-rows-to-one-stream]

The pure core is `merge_ticks`: a linear three-way step over one symbol's already ts-ascending quotes, trades and book events into a single ts-ordered `Vec<Tick>`. At an equal timestamp the tie-break is **Book, then Quote, then Trade** — book first because a live derived quote follows the book application that produced it, quote before trade because that was the original documented policy. `crates/vike-backtest/src/hist_replay.rs`'s `merge_ticks` states the consequence: reordering that tie-break breaks live/replay parity.

`replay_ticks` is the bounded reference loader. For each symbol it scans `scan_quotes`, `scan_trades` and `scan_book_updates` over the configured range, merges them, optionally seeds closed-bar context in process through `vike_model::consolidate_quotes` (or `consolidate_trades` when no quotes exist — book events never seed bars), and calls the existing `run_ticks` with no engine changes. A symbol with zero rows of all three kinds is skipped with a `tracing::warn!` rather than an error, so an all-sparse window degrades to an empty-but-valid result. `replay_ticks_streaming` obtains quotes and trades through `DataFusionHist`'s row-group streams instead; in its current scope each stream is still collected into a `Vec` before the merge, so the loader is not O(batch) end to end — its point is API shape plus bit-identical output against `replay_ticks`, pinned by `streaming_equals_bounded_bit_eq`. Both entry points share `replay_ticks_core` and differ only in how a symbol's rows are obtained.

Inside the engine, `run_ticks` k-way merges the per-symbol streams by timestamp (ties by stream order) and routes each tick by its own payload symbol. `on_bar` never fires on this path; a strategy sees `on_quote_tick`, `on_trade_tick` and `on_order_book`.

## The book integrity rule [#the-book-integrity-rule]

A recorded book chain is feed-local contiguous, and the replay treats it exactly as the live consumer did. `crates/vike-backtest/src/engine.rs`'s `apply_book_event` anchors a per-symbol book on a `Snapshot`, and applies a `Delta` only when the shared `L2Book::delta_decision` law answers Apply under `SeqPolicy::Strict` — `seq == last_seq + 1`, the same decision the live depth fold consults. Anything else — a gap, an orphan, a recorded gap-start or stale marker — drops the book until the next snapshot re-anchors it. `on_order_book` is delivered only on a state-changing apply. The books live on the broker, so the `L2Book` fill tier and a strategy's `quote_vwap` and `depth_within_price` reads answer from the same state the loop maintains.

## What the config controls [#what-the-config-controls]

`TickReplayConfig` carries the run's default `venue`, its `symbols`, the `range`, and `params` — the caller's cash, fees and sizer, with `fill_model` and `default_venue` overwritten by the loader, since a tick replay only makes sense under the L1 spread-crossing tier tagged to one venue (an explicit `L2Book` choice is respected — see [fill models](/docs/trader/backtesting/fill-models)). Three opt-ins default off and are byte-identical when off:

* `seed_bar_interval_ms` seeds closed bars. It must be positive (`ReplayError::InvalidBarInterval` otherwise), and with several symbols the per-symbol bar counts must agree, or the loader returns `ReplayError::MisalignedSeededBars` instead of driving `StrategyEngine::new`'s length assertion into a panic — bar-seeded replay is single-symbol in this phase.
* `snap_to_properties` wires `HistStore::properties_as_of` into `EngineParams.properties`, so a fill rounds price to tick and size to step and an opening fill is gated against the grid in effect at that tick's timestamp. It is single-venue, because the grid is looked up under one `default_venue`.
* `series` replaces the `venue × symbols` expansion with an explicit list of `SeriesRef`s, each naming its own venue and a `SeriesKind` lane filter (`tick`, `quote`, `trade`, `book`), so a Polymarket outcome token's trade tape can ride beside a spot quote series. Symbols must stay unique across the list, and `BacktestProfile::validate` refuses `snap_to_properties` alongside a series list naming more than one venue, for the single-venue reason above.

A profile reaches all of this with `data.kind = "tick"`: `crates/vike-backtest/src/harness/run.rs`'s `run_backtest` builds the config from `[engine]`, and `[[data.series]]` maps 1:1 onto `SeriesRef`. Series order matters — the k-way merge breaks an equal-timestamp tie by stream order, so a reference series listed first is delivered before the print it should inform. Three of the tick-only knobs (`feed_latency`, `queue_model`, `equity_sample_every`) are rejected at validation on a bar profile rather than ignored; `order_latency_ms` and `fill_latency_ms` are read only by `run_backtest`'s tick arm, so a bar profile that sets either runs as if it had not.

## Feed-latency replay [#feed-latency-replay]

<Callout type="warn" title="Venue order flatters every backtest on a proxied feed">
  Recorded ticks carry two clocks: the venue's `ts` and the machine's `local_ts`. The default replay orders by the venue clock, so the strategy sees each event the instant the venue stamped it — earlier than any real consumer could. On a proxied feed that systematically flatters the result: the strategy reacts to prints it could not yet have had.
</Callout>

`feed_latency: true` orders each symbol's merged stream by `tick_arrival_ts` instead: `max(local_ts, ts)`, with an unstamped `local_ts <= 0` falling back to the venue stamp and clock skew clamped up, so the modelled latency is never negative. Nothing is retagged — every tick keeps its venue `ts`, which remains the only clock `run_ticks` matches resting orders, advances `core.now` and stamps the equity curve with. Only delivery order moves, through a stable sort, so an unstamped tape replays byte-identically in either mode. Two limits are stated in the module rather than hidden: the re-order is per symbol, so on a multi-symbol replay the cross-symbol interleaving stays venue-ordered; and a genuinely lagging tape makes the per-tick clock non-monotonic, which is the honest shape of "the consumer saw it later" — combining this mode with the opt-in latency, resolution or settlement arms is out of scope.

See [latency models](/docs/trader/backtesting/latency-models) for order latency on this path, [queue models](/docs/trader/backtesting/queue-models) for resting maker fills, and the [record-and-replay](/docs/trader/tutorials/record-and-replay) tutorial for a run end to end.


# Timeframes (/docs/trader/backtesting/timeframes)



A backtest runs on one base stream per symbol. Every coarser timeframe a strategy reads is synthesised from it, in process, by `crates/vike-backtest/src/timeframe.rs` — an exact port of the original `core/timeframe.py` — and served through a buffer that is look-ahead-safe by construction: a coarse bar becomes visible only once its window has fully elapsed, and the engine enforces that visibility.

## The interval vocabulary [#the-interval-vocabulary]

`parse_timeframe` accepts a string like `"30s"`, `"1m"`, `"4h"` or `"1d"` and returns milliseconds. It delegates to the single interval vocabulary in `vike_model::time::interval_ms`: an integer count followed by exactly one unit character — `s`, `m`, `h` or `d` — with anything malformed rejected. That delegation is why seconds work: the module's own test pins `"30s"` to 30,000 ms, `"1m"` to 60,000 and `"4h"` to 14,400,000, and records that a `"30s"` series which loaded fine from the history store used to be an invalid backtest timeframe before the vocabulary was unified.

The interval also sets the report's annualisation. `crates/vike-backtest/src/harness/report.rs`'s `periods_per_year` derives the number of return observations a year produces from the interval — `252 · (86,400,000 / interval_ms)`, so `1h` gives 6,048 and `1m` 362,880 — with the `1d` anchor preserved bit for bit. It used to return 252 for every interval, which understated every intraday Sharpe by `sqrt(1440) ≈ 37.9x`. See [the report](/docs/trader/analytics/report).

## Resampling [#resampling]

`resample(bars, target_ms)` aggregates fine bars into coarse ones aligned to epoch windows of `target_ms`. A bar's window start is `ts − ts.rem_euclid(target_ms)` (Python's floor-mod), and one coarse bar is emitted per window in chronological order: open from the first fine bar, high and low folded across the window, close from the last, volume summed. The final window may be partial. `funding`, `bid`, `ask` and `symbol` are `None` on a resampled bar.

## The buffer [#the-buffer]

`crates/vike-backtest/src/bar_buffer.rs`'s `BarSeriesBuffer` is the shared multi-timeframe buffer, ported from `core/bar_buffer.py` with `bisect` becoming `partition_point`. Where the Python shared its base list by reference between engine and buffer, here the buffer owns the base-bar `Vec` and the engine reads through it — one owner, same observable behaviour. `BarSeriesBuffer::new(bars, timeframes)` resamples every registered timeframe up front; `add_live_bar` appends a base bar and refreshes each aggregate, the forward mode.

Two reads answer the strategy, both keyed on `now`:

* `bars_for(tf, now)` returns the completed higher-timeframe bars visible at `now` — deliver-on-complete, no look-ahead: the coarse list up to but not including the window that contains `now`. Asking for an unregistered timeframe panics with `timeframe … not registered`.
* `forming_for(tf, now)` returns the still-forming coarse bar up to `now`, or `None` when no base bar has started the current window. Its volume is summed with `vike_model::py_sum`, because the Python it ports used the builtin `sum()`, and its high and low are folded in order — the rule from [the parity gate](/docs/trader/concepts/parity-gate).

## In the engine [#in-the-engine]

The portfolio engine carries the same aggregates per symbol. `EngineParams.timeframes` (`crates/vike-backtest/src/engine/sim_broker.rs`, default empty) names the timeframes to register, and each `SymbolState` holds its `tf` list — "(tf, target\_ms, coarse bars)". `SimBroker::bars_for(symbol, tf)` and `SimBroker::forming_for(symbol, tf)` mirror the single-engine buffer per symbol, cutting the coarse list at the window containing `self.now` and building the forming bar from the live base series, so the reads a strategy makes inside `on_bar` see exactly what the buffer would have shown.

<Callout type="warn" title="Multi-timeframe reads are simulator-only">
  `vike_model::strategy`'s module doc lists multi-timeframe reads among the powers a strategy takes by being written against the concrete `SimBroker` — `impl Strategy<SimBroker>` — rather than the portable `impl<B: Broker> Strategy<B>`. The type system then documents that the strategy is not live-portable. The portable `Broker::bars` read is the closed base bars up to and including the current step, nothing coarser.
</Callout>

The [multi-timeframe strategy](/docs/trader/tutorials/multi-timeframe-strategy) tutorial reads two synthesised timeframes from one base stream; [the portfolio engine](/docs/trader/backtesting/portfolio-engine) describes the step loop these reads are answered inside, and [authoring in Rust](/docs/trader/strategies/authoring-rust) covers the two forms a strategy can take.


# The vector engine (/docs/trader/backtesting/vector-engine)



`crates/vike-backtest/src/vector_engine.rs` is the multi-asset time×symbol portfolio kernel: the
vectorized fast path for cross-sectional and target-weight strategies, an exact port of the Python
`core/portfolio_fastsim.py::_portfolio_kernel` and `fast_portfolio_backtest`. Where the event
engine steps a strategy object through callbacks, this kernel takes matrices and runs one pass.

## The scope is the parity boundary [#the-scope-is-the-parity-boundary]

The header draws the line deliberately narrowly. In scope is the `cash_gate=False`, market-order,
target-weight path **only**: next-open fills, column-order shared-cash application — cash may go
negative; there is no gate, no reduce-first, no weight priority — taker fees, slippage, funding
and cost-basis averaging. Out of scope, and the reason to use the event engine instead: stops and
brackets, the cash gate, volume and position caps, leverage capping, membership masks,
liquidation, sub-bars and sizers.

The inputs are row-major `Matrix` values of shape (T, S): `opens`, `closes`, `funding` and
`target_weights`, plus the timestamp vector, the fee and slippage scalars, initial cash and one
contract multiplier. `VectorBacktestEngine::run` is the one public entry point; the free function
`fast_portfolio_backtest` is the implementation detail and the parity-gate target. `S = 1` is the
single-symbol case — there is no separate single engine.

## The target-weights contract [#the-target-weights-contract]

`weights[t, s]` is the weight **decided** at bar `t`, from closes up to and including `t`, and
**realized** at `t+1`'s open. `NaN` means "no rebalance decided" for that symbol and bar — nothing
is queued. A weight of `0.0` for a held symbol drives a full close. The last bar's row is never
acted on, because there is no next open to fill at.

Per bar `t`, the kernel does four things in order:

1. **Fill** the deltas queued at `t−1` at `opens[t, s]`, in column order, on the shared cash: the
   fill price is the adverse-moved open, the fee is charged on the filled notional, the signed
   notional moves cash, and the shared `TradeFold` steps this symbol's cost basis and emits a
   closed-portion `Trade` on a reduce, close or flip.
2. **Charge funding** on held positions, marked at the close.
3. **Mark equity** once — a single shared snapshot used for both the curve and the next sizing
   decision.
4. **Decide** the next deltas from this bar's target weights: `w · eq / close − pos`, with a
   dead-band of `1e-12` below which nothing is queued, and a `close == 0.0` guard mirroring the
   Python `_engine_target`'s non-positive-price guard. Skipped on the last bar.

The output is the shared `BacktestResult`: the equity curve, final equity, the trade count and,
when `build_trades` is set, the trade list, plus net funding paid.

## The maker/taker law, and a dead parameter [#the-makertaker-law-and-a-dead-parameter]

Every fill this kernel produces is a rebalance crossing the market at the next bar's open. There
is no resting-limit path, so `is_maker` is always `false` and every fill is charged `taker_fee`.
That agrees with the event engine's own classification — maker if and only if the order kind is
`Limit` — for the same strategy verb this kernel mirrors, `SimBroker::strategy_order_target_percent`,
which only ever submits market rebalances. The two engines are reconciliation partners precisely
because neither has a maker-classified fill on this path.

<Callout title="maker_fee is threaded through and dead">
  `crates/vike-backtest/src/vector_engine.rs`'s `fast_portfolio_backtest` records it as a local trap:
  the kernel classifies every fill as taker, so its `maker_fee` parameter is dead at every call site.
  It exists so a future maker path must consciously wire it rather than silently defaulting to
  `taker_fee` by omission. The engine-kernel parity test's fee-schedule-armed row proves the two
  engines agree bit-for-bit under a schedule with maker ≠ taker precisely because this kernel never
  reads its maker side.
</Callout>

## Reconciliation with the event engine [#reconciliation-with-the-event-engine]

Engine-versus-kernel agreement is a second oracle, gated as a test in
`crates/vike-backtest/tests/parity/engine_kernel_parity.rs`. The kernel shares the event engine's
cost primitives — `adverse_fill_price`, `fee` and `funding_charge` from
[the cost model](/docs/trader/backtesting/cost-model) — and the same `TradeFold`, so the comparison is
of two loops over one arithmetic, not two implementations of it.

The equivalence holds only on the path both engines have. `crates/vike-backtest/src/engine/sim_broker.rs`'s
`EngineParams` documentation names, knob by knob, what the kernel does not consult: the market
impact model (it has no per-fill market context), the funding source closure (it takes funding
as a fully materialized matrix), the binary-resolution and option-expiry settlement sources, the
variation-margin cadence and the latency model. Reconciliation is meaningful only with every one of
those left at its default, which is what the parity gate runs.

## When to reach for it [#when-to-reach-for-it]

If the strategy is a matrix of weights — a rotation, a cross-sectional rank, a fixed allocation
rebalanced on a schedule — and you already hold the aligned open/close/funding matrices, this
kernel answers with one pass and no callbacks. The moment the strategy needs to see a fill, rest
an order, protect a position with a stop, or be told it cannot afford a trade, it belongs on
[the portfolio engine](/docs/trader/backtesting/portfolio-engine).


# Walk-forward (/docs/trader/backtesting/walk-forward)



Walk-forward evaluation runs a strategy on each out-of-sample window of a series and stitches those windows into one equity curve — "the honest way to backtest", in the words of `crates/vike-backtest/src/walkforward.rs`, which is the strategy twin of the original `ml/walkforward.py`: that one wrapped a model, this one wraps any `Strategy` through a caller-supplied `run_window` closure.

## The runner [#the-runner]

`walk_forward_strategy(bars, n_splits, mode, cash, periods_per_year, run_window)` asks `vike_analytics::validation::walk_forward_splits` for the windows, runs `run_window` over each window's test range, and rebases the resulting curves onto one running equity. Each window starts fresh at `cash`; its curve is scaled by `start × (v / cash)` and the running equity advances by `final_equity / cash`, mirroring the Python stitch. The contract, held by a `debug_assert`, is that every window's result starts its equity curve at exactly `cash`.

The report is a `WalkForwardReport`: one `WfWindow { test_range, oos_return }` per window, the stitched `oos_equity_curve`, the overall `oos_return`, `oos_sharpe` over the stitched curve at the supplied annualisation, and `wf_consistency` — the fraction of windows profitable out of sample, the input to the [overfitting](/docs/trader/analytics/overfitting) verdict. Both types are `Serialize` and deliberately not `Deserialize`, so the compute-to-data `RunWalkforwardProfile` verb can return the report as JSON text exactly as `BacktestReport` and `SweepReport` already cross the data-service wire, without coupling the wire schema to this crate's serde surface.

<Callout type="warn" title="Nothing is re-fitted">
  Each `Split` carries a train range as well as a test range, and the runner never reads the train half: `walk_forward_strategy` slices `bars[test_start..test_end]` and nothing else. The harness closure constructs the strategy fresh for every window from the same `strategy.name` and `strategy.params` the profile names, so what walks forward is one fixed parameter set evaluated on successive unseen windows. To have the parameters chosen on the earlier data, choose them with a [sweep](/docs/trader/backtesting/sweeps) first and walk the winner forward — the shape the [sweep and walk-forward](/docs/trader/tutorials/sweep-and-walk-forward) tutorial follows.
</Callout>

## The splits [#the-splits]

`crates/vike-analytics/src/validation.rs` ports the time-series cross-validation splitters of the original `analysis/validation.py` (López de Prado, *Advances in Financial Machine Learning*, chapter 7). `walk_forward_splits(n, n_splits, mode)` divides the series into chunks of `n / (n_splits + 1)` bars: window `s` tests `[s·chunk, (s+1)·chunk)`, the last extending to the end of the series, and train ends where test starts. `WalkMode::Anchored` is the expanding window — `train_start` is always 0 — and `WalkMode::Rolling` a fixed-width train of one chunk immediately preceding the test window. A profile selects between them with `walkforward.mode`, and `anchored` is what an absent key means (this line read "the profile path always uses `Anchored`", which was the default mistaken for the only option). The wider splitter family — purged k-fold, combinatorial purged splits and the duration-parameterised `purged_walk_forward_hours` — is on [validation](/docs/trader/analytics/validation).

## From a profile [#from-a-profile]

A `[walkforward]` table makes a [run profile](/docs/trader/backtesting/run-profiles) walkable, and it must declare **exactly one window form**: a split COUNT (`n_splits`), or DURATIONS (`train` with `test`, and optionally `step`). Declaring neither is refused by name, and so is declaring both — a count is defined by the range and moves when the range moves, while a duration does not, so the two cannot be reconciled by a precedence rule. `crates/vike-backtest/src/harness/walkforward.rs`'s `run_walkforward` walks whichever form the table declares. The module doc calls it assembly rather than new engine code: it resolves the strategy through the same `strategy_by_name` registry, builds the same bar-lane `EngineParams` through `bar_engine_params`, and loads the same bars through `load_profile_bars` as a plain `run_backtest` of that profile — so a walk-forward can never disagree with a single run about what the profile's `[engine]` means. That buys the whole `[engine]` surface — the fee schedule, `[engine.impact]`, `[engine.resolution]`, `[risk]`, `snap_to_properties`, `attach_funding` — where the Studio's DTO-shaped walk-forward (`vike_studio_core::run_walkforward_slice`, served by the `RunWalkforward` wire verb) carries only the three flat `cash`, `fee_rate` and `slippage` scalars.

⚠ &#x2A;*This paragraph read "Only the split count is configurable, deliberately. The mode is always `Anchored` … one knob" and every clause of that is now false.** The table carries **nine** fields: the two window forms above, plus `purge` and `embargo` (legal on the DURATION form only — the split-count walk stays gap-free, [decision 0046](/docs/trader/backtesting/run-profiles)), `mode` (`anchored` | `rolling`; absent = `anchored`, which is where the old claim came from — it is the DEFAULT, not the only value), `search` (`none` | `sweep`; absent = `none`, and `"sweep"` without a grid table is refused rather than silently selecting the one parameter set the profile already has) and `rank_by` (`sharpe` | `return` | `max_dd` | `equity`; absent = `sharpe`). Every one of those, with its default and the sentence that refuses a bad value, is rendered from the type itself on [`backtest --profile`](/docs/trader/reference/cli/research/backtest-profile) — which is why this page no longer lists them by hand.

What still holds: `n_splits` must be at least 1 (`BacktestProfile::validate` rejects 0), the section is `deny_unknown_fields` so a typo fails at load, and an absent section is byte-identical to every profile written before it existed — `run_backtest` and `run_sweep` ignore it exactly as they ignore a `[paramscan]` table they were not asked to expand. It lives in the profile rather than on a wire field because the profile is `deny_unknown_fields`: a TOML carrying `[walkforward]` must parse for the whole file to be shippable verbatim to a remote runner, which is the point of the compute-to-data verb.

The runner is bar mode over one series: `walk_forward_strategy` splits a single `&[Bar]` by index, which a tick replay does not produce, so a tick-mode or multi-series profile is a clean `HarnessError::Validation`, never a silent first-symbol fallback. Every other failure — no `[walkforward]` table, an unresolvable strategy, a store failure, an empty bar slice — is checked before the window loop, because the loop's closure cannot return an error. `EngineParams` is rebuilt per window because it is not `Clone` (it can carry a sizer box and a properties closure), and each window needs a fresh strategy.

The `vike-cli` [walkforward verb](/docs/trader/reference/cli/walkforward) ships a profile to a [data service](/docs/trader/reference/binaries/vike-datahub); [remote runs](/docs/trader/gui/studio/remote-runs) is the Studio's dispatch of the same job.


# A first session (/docs/trader/cli/a-session)



This page is one session, start to finish, on a machine that has just unpacked a release. Nothing
here needs a venue credential. Each step says what it proves as well as what it does, because half
of a first session is establishing that the binary is reading the files you think it is.

## Which binary is this [#which-binary-is-this]

```sh
vike-cli --version
```

prints `<name> <version> (<build identity>)` — the shape every `--version` on the box already
prints, with this build's provenance appended by `vike_buildinfo::version_line`. The parenthesised
half answers the question a bare version number cannot: &#x2A;which commit is this?* A release binary
was once built from a clone four commits behind and nearly installed on a live recorder, which is
why every `--version` in this workspace answers it.

`vike-cli --help` lists the ten verbs. Both exit **0** and print to **stdout**, which is not a given
— four verbs used to route `--help` through their usage-error arm and exit 1 with `help requested`
on stderr. `crates/vike-cli/src/cmd/args.rs`'s `exit_for_parse_error` is now the one place that
decision is made.

## Scaffold the project [#scaffold-the-project]

```sh
vike-cli init
```

`init` creates `<project>/user_data` — the half of the project a program must never author — fills
every folder with a runnable example, and prints the map:

```text
user_data: /srv/vike/user_data

user_data/               your work — nothing here is ever overwritten once you have edited it
  strategies/rhai/       interpreted strategies: edit, save, backtest. No toolchain needed.
  strategies/rust/       compiled strategies. SOURCE CHECKOUT ONLY — a release binary cannot build them.
  indicators/            your own indicators, one <name>.rhai each. Callable from any strategy.
  profiles/              run profiles: which data, which costs, which strategy
  backtest_results/      saved reports. One sample ships, so the notebooks work before your first run.
  notebooks/             analysis over the results above
  logs/                  compile.log — every strategy load, pass and fail. Look here first.

  create   strategies/rhai/sma_cross/sma_cross.rhai
  ...
```

The map is printed on **every** run, including one that changed nothing, because this command is
also how you ask &#x2A;what is in here again?* — and an answer that only appears the first time is an
answer nobody sees twice. Files that were already in place are counted rather than listed, so on a
re-run the one line that changed is not buried.

Re-running is the ordinary case: a new version ships new examples, so the default writes only what
is **absent** and never touches a file you edited. `--dry-run` performs every comparison and writes
nothing.

`--reset` is the one loaded flag, and its boundary is narrower than "restore the samples" sounds.
It restores every shipped sample that is **missing or edited** — so it *does* overwrite your
changes to a shipped example, which is exactly what it is for. What it can never touch is a file
**you created**: `--reset` compares against one table of shipped files and writes nothing outside
it, and a strategy you wrote is not in that table, so no combination of flags here can delete it.
Reach for `--dry-run` first if you are unsure which of your files are shipped samples — it prints
the same report, marking each one created, restored or kept, and writes nothing. The
[`init` reference](/docs/trader/reference/cli/set-up/init) argues that boundary precisely.

## Prove which files are being read [#prove-which-files-are-being-read]

Two commands, and running them now saves an hour later. Both report on the **same** settings
directory the dispatcher resolved once at startup, taken as a parameter rather than re-derived, so
neither can name a file that nothing else opens.

```sh
vike-cli secrets path
```

```text
store:  /srv/vike/settings/secrets.env (present)
```

There is exactly one credential store and this is where it is. If it is absent, the command prints
the three lines that create one — a `mkdir -p`, an `$EDITOR`, and a
`chmod 600 … # it is plaintext credentials` — because creating that file is a person's job with an
editor, never a command's. If its mode grants anything to group or other, a warning goes to stderr;
a finding is never a refusal, so the exit code does not change.

```sh
vike-cli config show --section files
```

prints the settings directory, one line per settings file with whether it was read, and then a
table of every setting with its effective value, the layer that set it, the compiled-in default,
and a `READ` column saying whether anything actually reads it. `--section files` is worth typing:
the environment half is several hundred rows, and the question that motivated the files half —
&#x2A;did my `policy.toml` get read?* — should not require scrolling past them.

Provenance here is exact rather than inferred: an origin is decided by a key's **presence** in a
parsed layer, so a file that sets a key to the same number as the code default still reports the
file. Until this existed, nothing anywhere printed whether a `policy.toml` had been read at all,
and a typo'd filename produced a silently uncapped node.

## Ask what a strategy may call [#ask-what-a-strategy-may-call]

```sh
vike-cli indicators
vike-cli indicators --name rsi
```

This prints the indicators a Rhai strategy can actually **call** — every row is a name the script
host binds, joined onto its catalog metadata for the label, the parameters and the output lines. The
distinction matters more than it sounds: Rhai resolves a function name when the line *runs*, so a
script naming an unbound indicator compiles cleanly, raises on every bar, and self-disables after
the consecutive-error cap. It looks mounted and silently never trades. A name absent from this
listing is a name that fails exactly that way.

Your own `user_data/indicators/*.rhai` appear in their own block, under their own heading, with no
category — they are a different kind of thing, authored on this box with a file behind them, and
listing only the built-ins told an author their own indicator did not exist. The verb is offline: no
store, no settings, no credential.

## Run a backtest [#run-a-backtest]

A backtest needs no keys. What it needs is a `vike-datahub` server with a history store behind it —
that is the whole compute-to-data trade: the profile's **text** crosses the wire and the tape never
does.

```sh
vike-cli backtest --list-params --script user_data/strategies/rhai/sma_cross/sma_cross.rhai
```

is the offline half — it compiles the script and prints one `name = default` line per
`param(name, default)` call it declares, with no profile, no connection and no server. A script
declaring none says so in one line rather than printing nothing.

Then the run:

```sh
vike-cli backtest --profile user_data/profiles/backtest.toml --addr 127.0.0.1:7878
```

`--addr` defaults to `127.0.0.1:7878`. The server binds loopback, so a remote one is reached over
`ssh -L 7878:localhost:7878 <host>` and the command line does not change. The profile is read
locally and shipped verbatim; the **server** parses and validates it, which is what keeps exactly
one profile parser in the workspace.

Two flags rewrite the profile on the way out, in a fixed order: `--preset` merges a flat table of
knobs into `[strategy.params]` first, then `--script` injects an authored script's source into
`[strategy.params].src`, so the file on disk always wins over a stale `src` left in the profile.

The report comes back as JSON, pretty-printed for a person. With `--json` the server's bytes are
printed exactly as they arrived — that is the shape a wrapper should consume, and
[Scripting it](/docs/trader/cli/scripting) is the page about consuming it. What each field means is on
[the report](/docs/trader/analytics/report); the profile's own tables are on
[run profiles](/docs/trader/backtesting/run-profiles).

<Callout title="An empty store is not an error, and that is the trap">
  A profile naming a slice the store does not hold completes and reports no trades, which is
  indistinguishable from a strategy that never fired. `init`'s own closing lines say so and name the
  fix — the `backtest` binary's `--seed-demo` writes a synthetic tape, `--fetch-starter` pulls a
  published dataset that needs no venue. `vike-cli` cannot seed a store itself: writing one needs
  DataFusion, and this binary has none by construction.
</Callout>

`sweep` and `walkforward` are the same offload over the same wire — a parameter grid and an
anchored out-of-sample validation, both ranked and stitched server-side. From here, the
[trade REPL](/docs/trader/cli/repl) is the other half of the surface, and
[Quickstart: first backtest](/docs/trader/getting-started/quickstart-backtest) is this same path written
as a tutorial with the data-seeding steps in line.


# The daemon and the app (/docs/trader/cli/daemon-and-app)



The thing that trades is [`vike-tradehub`](/docs/trader/reference/binaries/vike-tradehub): a headless
daemon on a server, run as a systemd unit, holding the live core, the venue mounts and the risk
gate. It survives an SSH disconnect because it is not attached to your login session. Everything on
this page is a **client** of that daemon, and none of them holds any authority the daemon does not
grant.

That is the frame worth carrying into the rest of the platform: &#x2A;the node is the trading process;
the app, the CLI and the agent surface are three ways of looking at it and asking it for things.*

## One node, three clients [#one-node-three-clients]

| client                                   | how it attaches                                           | best at                                                                                                             |
| ---------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `vike-desktop --observe <addr>`          | the node's observe server, plus local keyless venue feeds | watching. Charts, the DOM ladder, positions and the trade panel over a remote daemon's account plane                |
| `vike-cli trade --node <addr>`           | observe **and** control, from a terminal                  | acting, over SSH, on a box with no display — and being able to paste exactly what you did into an incident write-up |
| `vike-cli strategy-status --node <addr>` | observe only, one short-lived connection                  | answering &#x2A;what is that daemon actually running?* in one line of shell                                         |
| `vike-cli mcp --node <addr>`             | observe and control, exposed as MCP tools                 | handing the same vocabulary to an agent, behind a preview gate                                                      |

The desktop app's remote mode is worth a sentence of its own, because it is not simply "the app,
read-only". `vike-desktop`'s split-plane model divides its data in two: the **account plane** — orders,
positions, equity, bar history — belongs to the backend and arrives as wire snapshots over the
observe bridge, while the **market-data plane** — books, the trade tape, order-flow series — belongs
to the venue and is subscribed directly and keylessly. In `--observe` mode on a full build you get a
remote daemon's account plane beside local feeds, with no local core and no execution engines at
all. [Observe mode](/docs/trader/gui/observe-mode) is that page.

## Two scopes, two keys [#two-scopes-two-keys]

Every one of those attachments authenticates, and the protocol has exactly two scopes.
`VIKE_TRADEHUB_OBSERVE_KEY` opens a read connection; `VIKE_TRADEHUB_CONTROL_KEY` opens a write one.
The node verifies **each scope against its own key**, so a control key cannot stand in for an
observe key — which is why `strategy-status`, a read verb, asks specifically for the observe half
and reports the observe-specific absent-key message rather than a vaguer "no key" line.

Both keys are resolved once, by the dispatcher, for the three node-facing verbs only:

```text
process environment  →  <project>/settings/secrets.env  →  nothing
```

The second rung is the same store the daemon itself loads them from, which is the whole point:
before it existed, a box configured exactly as the daemon documents answered *nothing to do*. The
first rung wins because an `export` is ephemeral, narrow and deliberate — it is what makes "point at
a different node for one command" possible — while the store is the box's standing configuration.
`crates/vike-cli/src/cmd/nodekeys.rs` carries that argument, including why this is **not** the
`policy.toml` case: a node key is a credential, not a risk limit, and presenting a different key
cannot widen what an authenticated peer may do. The worst an exported key achieves is failing the
handshake.

Which keys this box holds is answered by [`vike-cli secrets`](/docs/trader/reference/cli/set-up/secrets), by
name and never by value.

## What `strategy-status` reads [#what-strategy-status-reads]

`strategy-status` is the shell-level answer to &#x2A;what is that daemon running?* It opens one
short-lived observe connection, sends one request, and prints what came back
(`crates/vike-cli/src/cmd/trade_status.rs`). Three things:

```text
node hub-a — paper — build vike-tradehub 0.1.0 (abc1234, clean)
params: spread=0.01 size=20

  STRATEGY      MODE   PARAMS
  spread_maker  paper  venue=polymarket symbol=TOK-A spread=0.01
  np            LIVE   venue=polymarket symbol=TOK-B edge=0.02
```

The **identity line** names the node and the build it is running, down to the commit and whether
that tree was dirty — the same provenance every `--version` in the workspace answers, asked
remotely. The **effective-params line** is what the daemon resolved, not what a file says. And then
one row per mounted strategy, with its mode and its parameters.

The mode cell is uppercase exactly when it matters: `LIVE` shouts, `paper` is the quiet default.
Column widths come from the data, headers included, so a long strategy name cannot shear the params
column. `--json` prints the wire payload verbatim instead — a machine consumer gets the protocol's
own schema rather than a second hand-maintained shape that could drift from it.

Until this verb existed the only way to ask that question from a shell was to compile a throwaway
probe, which is a thing people did.

<Callout type="warn" title="A node too old to answer is refused on this side">
  The verb is feature-negotiated: against a node whose handshake advertises no strategy-verbs
  capability, the client sends **nothing** after the handshake and refuses locally. That is
  deliberate — an older node's deserializer cannot decode the frame, so sending it would produce an
  opaque decode error at the node instead of a diagnosis here. The message names the missing
  capability and the one action that fixes it: upgrade that node.
</Callout>

## Choosing between them [#choosing-between-them]

They overlap on purpose, and the useful question is not *which is most powerful* but *what does
this moment need*.

**Take the app** when the question is visual and the answer is a shape — is this fill where the
chart says it is, is the book thinning out, does this indicator behave the way it did in the
backtest. Nothing at a terminal replaces looking at a chart.

**Take the CLI** when the answer has to survive being written down. A `strategy-status --json` in a
cron job, a `trade` session pasted into an incident review with the `--reason` you typed on each
line, a deploy script that refuses to start a unit — none of those have a GUI shape. It is also the
only one of the three that works over an SSH connection to a box with no display, which describes
most trading servers.

**Take the agent surface** when the loop is author, compile, backtest, adjust and you would rather
describe the change than type it. It speaks the same write vocabulary as the REPL — the same
construction site, the same client-order-id mint, the same guardrail — so a verb added to one is
visibly missing from the other rather than silently absent.

Whichever you take, the node's own control limits and risk gate are the enforcing backstop, and the
per-venue arming ceiling in [`policy.toml`](/docs/trader/reference/settings/policy) sits above even the
credential read. A client can only ever ask. See
[the control boundary](/docs/trader/concepts/control-boundary),
[risk and arming](/docs/trader/concepts/risk-and-arming) and
[the node protocol](/docs/trader/concepts/node-protocol) for what the daemon does with what it is asked.


# The command line (/docs/trader/cli)



`vike-cli` is one binary with ten verbs. It scaffolds a project, discloses what this box's settings
resolved to, inspects the credential store, lists what a strategy may call, ships backtests to a
data service, drives a running trading daemon from a terminal, and serves the same trading
vocabulary to an agent over MCP. Every verb is a sibling module under `cmd` exposing a
`run(args) -> ExitCode`, and the dispatcher in `crates/vike-cli/src/lib.rs` never grows command
logic — it only routes.

This section is the narrative half. It says what working at the command line is like and which verb
answers which question; [the CLI reference](/docs/trader/reference/cli) is the authority for every flag,
every exit path and every error string, one page per verb.

## The identity is negative [#the-identity-is-negative]

The most useful sentence about this binary is a list of what is not in it. `vike-cli` links **no
DataFusion and no venue transport stack** — no `ureq`, no `tungstenite`, no `rustls`, no signer.
That is not an accident of what has been written so far; it is the test every dependency in
`crates/vike-cli/Cargo.toml` is argued against, edge by edge, on the manifest row itself.

Three of those arguments are worth carrying, because they explain shapes you will meet later:

* `vike-ops` and `vike-bridge-core` are both taken `default-features = false`. Their default `full`
  features carry the venue transport and signing stack, and restoring either would drag it into a
  laptop binary that never opens a venue socket.
* the credential store is read through `vike-secrets`, a crate with **zero** dependencies, rather
  than through `vike-bridge-core`, the reader's historical home. A `KEY=VALUE` parser is not worth
  a TLS stack.
* the client-order-id generator comes from `vike-model` rather than `vike-exec`, its historical
  home. `vike-exec` would have added a multi-threaded async runtime and core-affinity to a binary
  whose whole identity is being light.

The consequence is the shape of everything else here: &#x2A;*`vike-cli` asks services, it does not run
engines.** A backtest is not computed in this process — the profile's TOML text is shipped to a
[`vike-datahub`](/docs/trader/reference/binaries/vike-datahub) server sitting next to the tape, which
runs it and returns a compact report. Live orders are not placed by this process either — they are
commands sent to a running [`vike-tradehub`](/docs/trader/reference/binaries/vike-tradehub) node, whose
own control limits and risk gate are what actually enforce anything. The heavy history and the
authority both stay where they belong.

## The ten verbs, by the job they do [#the-ten-verbs-by-the-job-they-do]

`crates/vike-cli/src/lib.rs`'s `COMMANDS` is the single source of truth for both the help text and
the unknown-command hint, so a new verb appears in `--help` for free. Grouped by what you are
trying to do rather than alphabetically:

| job            | verbs                                                                                                                                                                                                                                                                                                                                                                 |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| set the box up | `init` scaffolds `user_data/`; `config show` discloses every setting and where its value came from; `config check` judges the same tree and makes the exit code the product; `secrets` inspects the one credential store, and `secrets set` upserts one named key into it — the CLI's only credential writer, value from stdin or an environment variable, never argv |
| do research    | `indicators` prints what a Rhai strategy can actually call; `backtest`, `sweep` and `walkforward` ship a profile to a data service and print what came back                                                                                                                                                                                                           |
| run and watch  | `trade` is the interactive REPL over a live node; `strategy-status` asks that node what it is running, read-only; `mcp` serves the same vocabulary to an agent                                                                                                                                                                                                        |

Ten verbs is the whole surface. There is no `clap` dependency behind it: the flag grammar is
hand-rolled in `crates/vike-cli/src/cmd/args.rs` and shared by every verb, which is why
`--flag value` and `--flag=value` work everywhere and why a token beginning `--` is a flag and
never a value everywhere. [Global flags](/docs/trader/reference/cli/global-flags) is that grammar's page.

## What happens before any verb runs [#what-happens-before-any-verb-runs]

Typing any subcommand runs the same three steps first — the first two inside
`crates/vike-cli/src/lib.rs`'s `resolve_policy`, the third in `run`, which calls
`install_user_indicators` only once `resolve_policy` has returned. The order is load-bearing: a
refusal in step 1 returns before an indicator is ever compiled. Together they explain most of what
a fresh install does:

1. **A removed environment variable is refused.** `vike_config::refuse_removed_env` fails the
   process, naming the variable, the file that replaces it and the exact TOML line to write. It
   fires for every verb, including read-only ones — a stale variable is stale regardless of what
   you typed, and an operator who still exports `VIKE_MAX_ORDER_NOTIONAL` believes a ceiling is
   armed that nothing reads.
2. **`<project>/settings` is resolved once**, through the workspace's one startup sequence
   (`vike_boot::boot`). Every project-relative path any verb uses is derived from that single
   answer, so `secrets path`, `config show` and a daemon on the same box cannot disagree about
   which project they are in.
3. **Your own indicators are installed process-wide.** `install_user_indicators` compiles
   `user_data/indicators/*.rhai` before dispatch, so a script run by any verb can call them. A file
   that fails to load is reported on stderr and never fails the command.

The credential store is the deliberate exception to &#x2A;"resolved once, up front"*: the **dispatcher**
opens it lazily and only for the three node-facing verbs — `trade`, `mcp` and `strategy-status` —
inside their own arms, through `node_keyring`, because those are the three that authenticate to a
node. A backtest has no business opening the file that holds every venue key on the box.

That is a statement about the dispatcher, not about the binary. Two verbs open the store because
the file **is** their subject, and they do it themselves rather than through the deferred boot:
`secrets` reads it directly (`vike_secrets::resolve` for `list`, a `stat` and a permissions check
for `path`, and `set` writes one key through the workspace's one upsert), and `config` does too — `crates/vike-cli/src/cmd/config.rs`'s `execute` loads it before
it prints anything, to report the key COUNT, and `config check&#x60; classifies whether it is present,
absent or unreadable. So the honest answer to &#x2A;"which invocations touch `secrets.env`?"* is: the
three node-facing verbs, plus the two whose job is to tell you about the file.

<Callout type="warn" title="Diagnostics go to stderr, always">
  `vike-cli mcp`'s stdout is a JSON-RPC protocol stream, and one stray line on it corrupts the
  session. So every warning, every settings resolution and every rejected indicator goes to stderr —
  in every verb, not just that one. It is also why `vike-config` returns its resolutions as data
  rather than logging them: a library that writes to its caller's stderr cannot be linked by a binary
  whose stdout is a protocol.
</Callout>

## Which of the three surfaces [#which-of-the-three-surfaces]

The platform has three faces over the same core concepts, and they are not ranked — each is best at
something the others are bad at.

<Cards>
  <Card title="The desktop app" href="/docs/trader/gui" description="Charts, the DOM ladder, click-to-trade and the Studio — the surface for looking at something." />

  <Card title="The command line" href="/docs/trader/cli/a-session" description="Reproducible, pipeable, scriptable, and the only one that runs over SSH on a box with no display." />

  <Card title="The agent surface" href="/docs/ai/trader" description="The same trading vocabulary as MCP tools, for describing what you want instead of typing it." />
</Cards>

Reach for the app when the question is visual — is this fill where I think it is, does this
indicator look right on this chart. Reach for the CLI when the answer has to be repeatable, put in
a shell script, or reached across an SSH connection to a server with no GUI. Reach for the agent
surface when the loop is author, compile, backtest, adjust, and you would rather describe the
strategy than write it. All three end up talking to the same daemon over the same authenticated
protocol, and [The daemon and the app](/docs/trader/cli/daemon-and-app) is the page about that.

<Cards>
  <Card title="A first session" href="/docs/trader/cli/a-session" description="Empty install to a backtest report, one command at a time." />

  <Card title="The trade REPL" href="/docs/trader/cli/repl" description="Short verbs over a live node, with a preview in front of every write." />

  <Card title="The agent door" href="/docs/trader/cli/mcp-door" description="What vike-cli mcp is, and where the tool reference lives." />

  <Card title="Scripting it" href="/docs/trader/cli/scripting" description="--json, exit codes, and branching on them in a shell script." />

  <Card title="When it goes wrong" href="/docs/trader/cli/troubleshooting" description="The failures a fresh install actually hits, and what each one means." />
</Cards>


# The agent door (/docs/trader/cli/mcp-door)



`vike-cli mcp` is the tenth verb and the odd one out. Every other verb answers a question and exits;
this one stays running and serves the platform as [Model Context
Protocol](https://modelcontextprotocol.io/) tools over stdio, so an agent can drive the same loop
you would drive by hand.

This page is a **door**, not a duplicate. The tool-by-tool reference — every schema, a runnable call
and a captured response — lives under [the Trader MCP server](/docs/ai/trader), and this page
deliberately restates none of it. What belongs here is the part that is a property of the *CLI*:
where the verb sits among the other nine, what it shares with the REPL, and what it refuses to do.

<Cards>
  <Card title="The Trader MCP server" href="/docs/ai/trader" description="The 17 tools, what each one is for, and what the server is." />

  <Card title="The tool reference" href="/docs/ai/trader/tools" description="One page per tool — schema, a real call, the response it returns." />

  <Card title="Client setup" href="/docs/ai/trader/setup" description="The config block your MCP client needs, per client." />

  <Card title="Connect an agent" href="/docs/trader/guides/connect-an-agent" description="The narrative walkthrough, end to end." />
</Cards>

## It is a local subprocess, not a service [#it-is-a-local-subprocess-not-a-service]

```
usage: vike-cli mcp [--addr 127.0.0.1:7878] [--node <host:port>] \
                    [--profile full|read-only|offline] [--deny-tool NAME]... \
                    [--trace | --trace-dir <dir>]
```

Your MCP client launches this binary as a child process and talks to it over stdin and stdout.
Nothing is listening on a port, nothing is published, and nothing contacts a Vike server — the two
addresses are **your** [`vike-datahub`](/docs/trader/reference/binaries/vike-datahub) and **your**
[`vike-tradehub`](/docs/trader/reference/binaries/vike-tradehub). Omit `--node` and the create-and-
backtest tools still work; the live tools then return a clean error instead.

Something other than an MCP client can be the thing that launches it, and that is how an unattended
session works: `vike-agent-run` starts this same server against your node, hands one prompt to one
model, and leaves a record — read-only unless it is told otherwise, and scheduled by your operating
system rather than by any mode of this verb. It is a separate binary precisely so that `mcp` stays
a subprocess and never grows a scheduler. See [Unattended runs](/docs/ai/trader/unattended).

The transport is hand-rolled over `serde_json`: JSON-RPC 2.0 framed as newline-delimited JSON, one
message per line. That is the same "no async, no new transport stack, stdio-JSON" convention the
rest of this workspace's sidecars use, and it is why an MCP SDK is not a dependency here — it would
drag a second async stack into a binary whose whole identity is being light.

<Callout type="warn" title="This is the reason every vike-cli verb writes diagnostics to stderr">
  Under `mcp`, **stdout is a protocol**. One stray line on it corrupts the JSON-RPC stream and the
  session with it. So the rule is enforced across the whole binary rather than in this one file: the
  settings loader returns its resolutions as data instead of logging them, the dispatcher prints them
  to stderr, and a rejected user indicator is reported to stderr too. A library that wrote to its
  caller's stdout could not be linked here at all.
</Callout>

## One vocabulary, two surfaces [#one-vocabulary-two-surfaces]

Ten of the seventeen tools are read-only — compile a Rhai strategy, discover its knobs, list the
indicators the host binds, run a backtest, a sweep or a walk-forward against a data service, list
what that service holds, and read a live node's snapshot. Seven write to a node: six place, change
or cancel orders and the seventh sets its trading state.

Those seven resolve through the **same** construction site as the [`trade` REPL](/docs/trader/cli/repl):
the same args-to-command mapping, the same client-order-id mint, the same client-side guardrail
(`crates/vike-cli/src/cmd/verbs.rs`). That is structural rather than a convention. Both surfaces
used to build wire commands independently and had already drifted — the REPL supported `modify` and
`mass-cancel` while the agent surface did not, and each carried its own copy of the guardrail. A new
write verb is now visibly missing from whichever surface forgets to expose it, instead of silently
absent from one.

The same is true of the read side: `list_indicators` and the human
[`indicators` verb](/docs/trader/reference/cli/research/indicators) print from the same derivation, so the human
surface and the machine surface cannot disagree about what a script may call — which is the only
property that matters there, because the cost of being wrong is a strategy that mounts and silently
never trades.

## The preview gate fails closed [#the-preview-gate-fails-closed]

Every write tool previews. Calling one returns the resolved command, a guardrail check, the node's
own dry-run verdict where the node can be reached, and a `preview_token` — and sends nothing.

Executing needs a second call carrying `confirm: true` **and** that exact token. The token fires at
most once, expires after sixty seconds, and is **bound to the command it previewed**. Any other
shape — no token, an unknown token, an expired one, a token issued for a different command, or
`confirm: true` on its own — returns a preview and sends nothing.

<Callout type="warn" title="That gate was documented before it existed">
  `confirm: true` used to be the whole test, on that call, so a first-and-only call executed. Nothing
  correlated a confirm with the preview it claimed to confirm, so previewing `qty: 0.5` and confirming
  `qty: 50` was accepted. And the client-side guardrail it showed cannot price a **market** order —
  there is no price to size against — which is the default order type, so the advertised protection
  was absent on exactly the path most likely to be taken. The preview now also asks the node for its
  own dry-run, and when the node cannot be reached it **says** the verdict is an unverified
  client-side estimate rather than presenting an absence as approval.
</Callout>

The node's server-side control limits and the core risk gate remain the enforcing backstop
regardless. The preview is UX; the node gate is truth. See
[the control boundary](/docs/trader/concepts/control-boundary).

## …and a scope that removes the write tools entirely [#and-a-scope-that-removes-the-write-tools-entirely]

The gate above is what a write costs. `--profile` is the prior question — whether this server offers
one at all — and it is a property of the launch command rather than of the conversation. `read-only`
serves the ten read tools and withholds the seven writes; `offline` serves only the four that open
no socket. `--deny-tool NAME` takes out one more, repeatably. A withheld tool is &#x2A;*absent from
`tools/list`** as well as refused, because the advertised roster and the routing gate are two
complements of one pass over the registry (`ToolAccess` in `crates/vike-cli/src/cmd/mcp.rs`) rather
than two lists that could disagree. An unknown profile or deny name is a usage error naming the
valid set — never a quiet widening.

`--trace` is the other half of handing the tools out: one appended JSONL record per tool call under
`<project>/settings/state/agent`, carrying the tool, the redacted arguments and the verdict —
including the **refusals**, which reach no node audit trail because they were refused before a byte
left this process. Off unless asked for, and it records no secret and no token bytes; the
[verb reference](/docs/trader/reference/cli/mcp) has the shape.

## Keys, and what an agent can reach [#keys-and-what-an-agent-can-reach]

The live tools need the same two HMAC keys everything else does, resolved the same way — process
environment first, then the credential store the daemon itself reads. Absent from both, the trade
tools return a clean error naming both places and the create-and-backtest tools keep working, which
is the right degrade: an agent that cannot reach a node can still author and backtest.

What an agent may arm is not an agent question at all. `policy.venues.<venue>` is a per-venue
ceiling consulted above the credential read, defaulting to `paper` for every venue — so a box with
no `[venues]` table mounts all paper whatever its store holds, and no tool call changes that. See
[`policy.toml`](/docs/trader/reference/settings/policy) and
[risk and arming](/docs/trader/concepts/risk-and-arming).


# The trade REPL (/docs/trader/cli/repl)



`vike-cli trade --node <host:port>` attaches a terminal to a running
[`vike-tradehub`](/docs/trader/reference/binaries/vike-tradehub) node. You type short verbs — `submit`,
`cancel`, `flatten`, `orders`, `positions`, `state` — and they become authenticated commands on the
node's wire. This page is about the experience: what the prompt does, what the confirmation gate is
for, and where the authority actually sits. The [`trade` reference](/docs/trader/reference/cli/trade/trade) is
the verb-by-verb grammar.

## Two connections, opened separately [#two-connections-opened-separately]

The REPL opens **two** connections, and either can be missing. Reads go over an `OBSERVE` handle
subscribed to the node's pushed snapshot stream; writes go over a `CONTROL` handle. Each is gated on
its own HMAC key, and the node verifies each scope against its own key — a control key cannot stand
in for an observe one.

Startup says which halves came up, and where each key came from:

```text
connected: OBSERVE (read) to 10.0.0.5:9200 [key from the credential store]
connected: CONTROL (write) to 10.0.0.5:9200 [key from the process env]
type `help` for commands, `quit` (or Ctrl-D) to exit
vike>
```

The keys are resolved once by the dispatcher, &#x2A;*process environment first, then
`<project>/settings/secrets.env`** — the same store the daemon on the other end loads them from.
`crates/vike-cli/src/cmd/nodekeys.rs` argues that order: the fix is strictly additive, so an
operator who exports the keys today keeps exactly the behaviour they have, and an `export` is
ephemeral, narrow and typed on purpose while the store is the box's standing configuration. Before
that resolver existed this command read `std::env::var` and nothing else, so a box configured
exactly as the daemon documents — both keys in the store, `vike-cli secrets list` confirming them —
answered *nothing to do* and exited.

Values are trimmed on the way in because the server trims on the way out. A client that did not
would sign with `"secret\n"` against a server verifying `"secret"`, and an HMAC mismatch surfaces as
an opaque auth denial rather than as *your key file has a trailing newline*.

<Callout type="warn" title="Writes disabled is three different problems">
  With no control key you get observe-only. But a perfectly good key in the store can still leave
  writes off, because the **node** refused the control scope — its `tradehub_control` flag is off —
  and that refusal happened once, at connect time, before it scrolled away. The three cases are
  distinguished at connect and carried forward, so a later write names the true reason: no key
  resolved, the node refused the scope, or the connection could not be opened at all. Every message
  still ends in "nothing was sent", the one fact all three share.
</Callout>

## Every write previews first [#every-write-previews-first]

Typing a write verb does not send it. The REPL resolves the command, prints it, prints a guardrail
line, and asks:

```text
vike> buy binance BTCUSDT 0.1 @64000 --reason rebalancing the hedge
preview: SUBMIT buy binance BTCUSDT qty=0.1 limit @ 64000 coid=a1b2c3d41
  guardrail: qty=0.1 notional=6400 max_qty=- max_notional=250 → OVER LIMIT (the node will reject)
  reason (recorded in the node's audit trail): rebalancing the hedge
confirm? [y/N]
```

Only an explicit `y` or `yes` sends anything; Ctrl-C, Ctrl-D, a blank line and anything else are all
a no, which is the safe default for an order write. `--yes` skips the prompt — and note that the
preview still prints even then, so the human watching a scripted session sees exactly what went.

Two details in that preview are worth knowing about.

**The client order id was minted by this side.** A node refuses a remote submit whose
`client_order_id` is empty — a remote peer whose id the runtime minted has no stable handle to
cancel or deduplicate by — so every client of that protocol must pre-mint one. The generator is
session-scoped: an eight-hex prefix from OS entropy per process, then a counter, so two REPLs open
side by side, or one restarted while an order still rests at the venue, cannot collide. The id is
filled in **before** the preview renders, so the id you read is the id sent and the id you type back
at `cancel`. `submit … --coid <id>` pins one explicitly.

**The numbers are rendered, not dumped.** `0.4 * 3` is exactly `1.2000000000000002` in binary
floating point, and `f64::to_string` is obliged to print all of it. The preview instead prints the
shortest fixed-point rendering that still round-trips within a display tolerance, because a reader
who has learned to skip past seventeen digits of arithmetic noise is a reader who will skip past a
real discrepancy in the same position. The comparison itself is done on the raw values —
`crates/vike-cli/src/cmd/verbs.rs`'s `guardrail_check` never reads the string.

## What the guardrail is, and what it is not [#what-the-guardrail-is-and-what-it-is-not]

It is **advisory**. `guardrail_check` compares the order against two local caps: this box's
`max_notional_per_order` from [`policy.toml`](/docs/trader/reference/settings/policy), and
`VIKE_MAX_ORDER_QTY`, a local typo-catcher with no policy field and no enforcing counterpart
anywhere. An `OVER LIMIT` verdict does not stop the send — it warns you that the node will refuse
it.

The enforcing gate is on the node: its server-side control limits and the core risk gate. The
client preview is UX, the node gate is truth. See
[the control boundary](/docs/trader/concepts/control-boundary) and
[risk and arming](/docs/trader/concepts/risk-and-arming).

<Callout type="warn" title="A market order cannot be sized client-side">
  The default order type has no price, so there is no notional to compute and the notional half of
  the check is skipped. The quantity half still runs. This is the branch most likely to be taken and
  the one where a client-side estimate is weakest — another reason the node's own gate is the one
  that counts.
</Callout>

The notional cap deliberately does not come from the environment. It used to be
`VIKE_MAX_ORDER_NOTIONAL`, and that variable was removed rather than deprecated: a ceiling any
exported variable can raise is not a ceiling. Setting it now **refuses startup**, with a message
naming `policy.toml`, the key, and a paste-ready line carrying your own value.

## Each command reports its own outcome [#each-command-reports-its-own-outcome]

After sending, the REPL waits up to two seconds for the node's verdict on **that** command and
prints one of four things: accepted (with the coid), rejected with the node's reason, an explicit
*not confirmed — the connection dropped before the node answered*, or *sent, but the node has not
answered within 2s*. It is a deadline rather than a sleep: the answer returns the instant the reply
lands, which is sub-millisecond on loopback.

<Callout type="warn" title="Read an outcome from its own ticket, never a shared side-channel">
  This used to poll a handle-wide error field that **latches**. After one refusal every later write in
  the session printed that same refusal, including commands the node had accepted and executed. An
  operator who fat-fingered an order, got a correct refusal, then typed `market-exit` was told the
  panic button had been rejected when it had run. The outcome is now awaited on the ticket the send
  returned, which is that command's identity and no other's.
</Callout>

## The small comforts [#the-small-comforts]

`--reason <text to end of line>` may end any write line. It is split off before the verb grammar
sees it, shown in the preview, sent beside the command, and recorded in the node's audit trail — so
an incident review reads *why*, not just *what*. It never becomes part of the order, and the node
sanitizes it before recording.

Ctrl-C abandons the current line and keeps the session; Ctrl-D quits. Line history persists under
the settings directory's `state/` sub-directory, best-effort — with no project above the working
directory it is simply not persisted, which is a quiet degrade rather than an error.

`help` prints the verb reference, and it is the one place in the binary where `--help` does not
short-circuit through the usage-error channel: the REPL's help is a reference to an interactive
grammar rather than a usage line, so it is recorded and rendered instead.

The two procedures this REPL exists for are
[stop, liquidate, restart](/docs/trader/guides/stop-liquidate-restart) and
[triage a stuck order](/docs/trader/guides/triage-a-stuck-order). The read-only question — &#x2A;what is that
daemon running?* — has its own verb, on [The daemon and the app](/docs/trader/cli/daemon-and-app).


# Scripting it (/docs/trader/cli/scripting)



Nine of the ten verbs are non-interactive, which makes `vike-cli` a reasonable thing to put in a
cron job, a deploy script or a systemd unit. This page is the contract a wrapper can rely on: what
comes out, on which stream, and what the status code means.

## Six verbs speak JSON, across seven surfaces [#six-verbs-speak-json-across-seven-surfaces]

`--json` exists on `backtest`, `sweep`, `walkforward`, `strategy-status`, `indicators`, `config
show` and `config check` — seven places to type it, six of the ten verbs, because `config` carries
the flag twice, once on each subcommand. It is a bare boolean everywhere — `args::no_value` rejects
an inline value rather than reading `--json=1` as a silent true — and both flag spellings work on
every valued flag beside it, so `--addr 1.2.3.4:7878` and `--addr=1.2.3.4:7878` are the same thing.

What `--json` actually emits differs in a way worth knowing before you write a parser:

| verb                   | what you get                                                                                                                                |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `backtest`             | the **server's** report bytes, printed exactly as they arrived. Without `--json` the same JSON is re-parsed and pretty-printed for a person |
| `sweep`, `walkforward` | the server's ranked or stitched report JSON, same idiom                                                                                     |
| `strategy-status`      | the node's wire payload, serialized verbatim — `identity`, `effective_params`, `mounts`                                                     |
| `indicators`           | machine-readable rows instead of the grouped listing, with your own indicators under their own key and no `category` field                  |
| `config show`          | one object carrying the settings directory, the per-file status, both row sets and the loader's warnings                                    |
| `config check`         | one object with `settings_dir`, `settings_dir_origin`, `strict`, `ok`, `failures`, `warnings` and one entry per finding                     |

The pattern in the first three rows is the rule rather than a coincidence: where a server computed
the answer, the machine view is **that server's own schema**, not a second hand-maintained shape
that could drift from it. The same discipline is why no metric is recomputed on this side — ranking
and every printed statistic in a sweep are the server's numbers.

`config check --json` is the one that pre-computes its own verdict. `ok` is the exit code as a
boolean, deliberately: a reader must not have to re-implement the `--strict` promotion rule to learn
what the status was going to be.

Four verbs have no `--json`, and each absence is a decision. `secrets` prints key **names** and
never values, and its output is a disclosure meant to be read and pasted into an issue. `init`
prints a map for a human who has just installed something. `trade` is a REPL and `mcp` is already a
protocol.


## Two exit codes [#two-exit-codes]

Every verb exits **0** or **1**. There is no ladder of numeric codes to switch on, so a wrapper
branches on success and reads stderr for the rest.

| outcome              | code  | stream                                                |
| -------------------- | ----- | ----------------------------------------------------- |
| the verb did its job | 0     | the product on stdout                                 |
| `-h` / `--help`      | **0** | the usage on stdout                                   |
| `--version` / `-V`   | 0     | stdout                                                |
| a usage error        | 1     | `vike-cli <command>: <msg>` plus the usage, on stderr |
| the verb failed      | 1     | the message on stderr                                 |
| an unknown command   | 1     | the error on stderr, then the help                    |
| no subcommand at all | 1     | the help — there was nothing to do                    |

`crates/vike-cli/src/cmd/args.rs`'s `exit_for_parse_error` is the one place the help-versus-error
decision is made, which is not a detail: four verbs used to route the help short-circuit into their
usage-error arm and exit **1** with `help requested` printed to stderr as though it were a
diagnostic. A non-zero `--help` breaks every wrapper that checks a status, and `config` had already
been fixed at its verb level and not at its `show --help` level, in the same file. The shipped-binary
gate is `crates/vike-cli/tests/help_cli.rs`, which runs the real binary and asserts the status, the
stream, and that no internal token leaks.

## The stream split is a contract [#the-stream-split-is-a-contract]

**stdout is the product; stderr is everything else.** That holds in every verb, not only under
`mcp` where stdout is literally a JSON-RPC stream. The settings loader's non-fatal resolutions, a
credential-store permissions warning, a rejected user indicator, and every failure message go to
stderr.

So `vike-cli backtest --profile p.toml --json | jq '.sharpe'` is safe, and `2>/dev/null` around it
is safe in the narrow sense that stdout stays clean — but you will have thrown away the line that
tells you a preference was clamped or that your credential file is world-readable. Redirect stderr
to a log, not to the void.

## Branching on it [#branching-on-it]

The obvious use, and the one the shipped units actually make, is `config check` as a pre-flight:

```sh
if ! vike-cli config check; then
  echo "this box is misconfigured; not starting" >&2
  exit 1
fi
```

That is precisely what `ExecStartPre=` in the shipped service units runs. The exit code **is** the
product of that verb: a settings tree that fails to load, a removed environment variable still set,
or a `VIKE_SETTINGS_DIR` naming a path that is not a directory each fail it, while an absent
credential store — the ordinary live gate — does not.

Run it with `--strict` when *you* are asking whether the box is fully configured; never in a unit.
`--strict` promotes every **warning** to a failure, and a correctly installed box legitimately
carries warnings: a 0644 store, which `vike_secrets::PermissionWarning` argues must be reported
rather than refused, or the `<project>/.env` a shipped recorder unit uses as its `EnvironmentFile`,
which is the same file to `vike_secrets::legacy_store_warning` as a pre-one-store leftover. An
absent store is **not** one of them — `crates/vike-cli/src/cmd/config_check.rs` classifies it `ok`
outright, and `an_absent_credential_store_is_not_even_a_warning` pins that not even `--strict` may
fail a paper deployment over it.

A monitoring check over a live node is the other common shape:

```sh
vike-cli strategy-status --node "$NODE" --json |
  jq -e '[.mounts[] | select(.live)] | length > 0'
```

Each mount row carries `strategy`, `params` and a boolean `live`, and the identity block carries its
own `live` — the daemon's process-wide arming gate. Those two **disagreeing** is the normal,
informative case rather than a contradiction: the daemon is armed and this particular mount is not,
because its venue holds no credentials or its connect demoted it to paper. A monitor that reads only
one of them will eventually be surprised by the other.

and a nightly research run is the third:

```sh
vike-cli backtest --profile profiles/backtest.toml --json > "reports/$(date +%F).json"
```

<Callout type="warn" title="A stale environment variable fails every verb, not just the trading ones">
  `refuse_removed_env` runs before dispatch, so a script that exports `VIKE_MAX_ORDER_NOTIONAL`
  anywhere in its environment gets exit 1 out of `secrets path` as readily as out of `trade`. That is
  deliberate — a variable that is stale is stale regardless of the verb, and an operator who set it
  believes a ceiling is in force. The message names the file, the key and a paste-ready TOML line
  carrying their own value; the fix is to write that line and unset the variable.
</Callout>

## Two things that make a run reproducible [#two-things-that-make-a-run-reproducible]

`--profile` ships the file's **text**, so what ran is exactly what is on disk and in your version
control — there is no server-side profile library to drift from it. And `--list-params` is offline:

```sh
vike-cli backtest --list-params --script strategies/rhai/rsi_meanrev.rhai
```

compiles the script and prints one `name = default` line per tunable knob with no profile, no
connection and no server, which makes it cheap to assert in a pre-commit hook that a script still
declares the parameters a profile sets.

For what the report's fields mean, see [the report](/docs/trader/analytics/report); for the flag grammar
every verb shares, [global flags](/docs/trader/reference/cli/global-flags).


# When it goes wrong (/docs/trader/cli/troubleshooting)



Most `vike-cli` failures are one of three shapes, and all three are the binary telling you something
true about the box rather than about itself. This page takes them in the order a fresh install meets
them. The platform-wide symptom index is [Troubleshooting](/docs/trader/troubleshooting); this page is the
CLI's own.

Two rules explain the dispositions below. **Absent credentials are the live gate** — a venue with no
keys stays paper, silently, by design. And a misconfiguration splits two ways: **refuse** when a
silent difference would leave you believing a protection is armed when it is not, **degrade** when
"unconfigured" is a state you may legitimately have chosen.

## `no store found — every venue stays paper` [#no-store-found--every-venue-stays-paper]

```sh
vike-cli secrets path
```

```text
store:  /srv/vike/settings/secrets.env (absent)

nothing here reads any other location — create it to configure a venue:
  mkdir -p /srv/vike/settings
  $EDITOR /srv/vike/settings/secrets.env
  chmod 600 /srv/vike/settings/secrets.env   # it is plaintext credentials
```

This is the ordinary unconfigured state and it is deliberately not an error. What it usually means
on a box that *is* configured is that the walk resolved a different project than you expected: the
settings directory is found by walking **up** from the working directory, so the answer depends on
where you were standing. `VIKE_SETTINGS_DIR` names it outright and beats the walk. Nothing outside
that directory can supply a credential — no home directory is consulted under any variable.

<Callout type="warn" title="Absent has three answers, not two">
  `Path::exists` maps every error to `false`, so a project root the process cannot search once
  reported the store as *absent* and then printed the fresh-install advice for what was really a
  permissions problem. `crates/vike-cli/src/cmd/secrets.rs`'s `Presence` uses `Path::try_exists`
  instead, and the third state prints words the other two share none of, because an operator greps
  this line. It is a finding rather than a refusal: it names the path, says what was not established,
  and still exits 0 — `path` is what you run when something is already broken.
</Callout>

A store that **exists and cannot be read** is a different problem again, and one the platform treats
as an error rather than as "no credentials": those two states looking the same downstream is exactly
how a permissions bug wears the fresh-install answer while every venue drops to paper. For the
node-facing verbs the read is non-fatal — the error is reported on stderr and the store treated as
empty, because an exported key must still work when that file is broken — while
`vike-cli config check` escalates it to a **failure** on a box armed for live, and leaves it a
warning on one that is not.

## `cannot connect to datahub at 127.0.0.1:7878` [#cannot-connect-to-datahub-at-1270017878]

```text
vike-cli backtest: cannot connect to datahub at 127.0.0.1:7878: Connection refused (os error 111)
```

`backtest`, `sweep` and `walkforward` are clients. They compute nothing locally — the whole design is
that the profile's text crosses the wire and the tape does not — so with no server there is nothing
to fall back to. Three causes, in the order they happen:

1. **No `vike-datahub` is running.** Start one next to the history store.
2. **It is running somewhere else.** `--addr` defaults to `127.0.0.1:7878`; the server binds
   loopback and refuses a non-loopback bind unless it is explicitly allowed and a node key is set.
   Reach a remote one with `ssh -L 7878:localhost:7878 <host>` and leave the command line alone.
3. **The tunnel is up but the far end is not.** A refused connection through a forward looks
   identical to a refused local one.

A transport failure and a server-side error both arrive as the same kind of failure on this side, so
read the message: a server that answered and refused says so in its own words. A profile with no
`[sweep]` table, or a walk-forward over a tick or multi-symbol profile, are clean **server-side**
errors rather than silent fallbacks.

The other half of "it connected and did nothing useful" is an empty store: a profile naming a slice
the store does not hold completes and reports **no trades**, which is indistinguishable from a
strategy that never fired. That is not an error anywhere, and it is why `init`'s closing lines name
the seeding commands.

## A removed environment variable refuses startup [#a-removed-environment-variable-refuses-startup]

```text
vike-cli: VIKE_MAX_ORDER_NOTIONAL=250 is set, but VIKE_MAX_ORDER_NOTIONAL is NO LONGER READ —
removed in Phase 5 (settings unification), because an order-size ceiling any exported variable can
raise is not a ceiling.
Set it in <project>/settings/policy.toml instead:

    max_notional_per_order = 250

then unset VIKE_MAX_ORDER_NOTIONAL.
```

Every verb runs this check before dispatch, so `secrets path` fails on it exactly as `trade` does.
That is the point: a stale variable is stale regardless of what you typed, and quietly ignoring it
would let the box trade uncapped while the operator believed a ceiling was armed — worse than either
keeping the variable or refusing.

The message pastes back your own value when it is a value the key would accept, and a placeholder
when it is not, so the suggested line always works. A variable whose value is itself a secret is
named but never echoed. A **present but empty** value starts normally: it configured nothing under
the old reader either, so nobody can believe a ceiling was active from one.

`vike_config::REMOVED_ENV` is the table, and it currently holds `VIKE_MAX_ORDER_NOTIONAL`,
`VIKE_TRADEHUB_MAX_ORDER_NOTIONAL` and `VIKE_SECRETS_PASSPHRASE`.

## Node keys and scopes [#node-keys-and-scopes]

```text
vike-cli trade: no vike-tradehub node key found — nothing to do.
looked for VIKE_TRADEHUB_OBSERVE_KEY (read) and VIKE_TRADEHUB_CONTROL_KEY (write) in:
  1. the process environment (a shell `export`, a systemd `Environment=`)
  2. ...
set at least one to observe/control the node — `vike-cli secrets path` prints the store's location.
```

The message names **both** places it looked, which the old one did not — it claimed the keys were
"not set in the environment" while the daemon's own keys sat unread in the credential store. If you
are sure the keys are there, `vike-cli secrets list` prints the names it can see in the store, and
`secrets path` prints which store that is.

Three more shapes are worth recognising because they look like a key problem and are not:

* **`writes disabled: the node REFUSED the control scope at connect time`.** Your key is fine; it
  authenticated. The node is not accepting control connections at all — turn `tradehub_control` on
  in *its* `flags.toml` and restart it.
* **A read verb refusing while a control key resolved.** The node verifies each scope against its
  own key, so a control key cannot authenticate a read. `strategy-status` says so explicitly rather
  than printing the generic "no key found", because *the key is right there in the store* is exactly
  what you would otherwise conclude.
* **The node advertised no strategy-verbs capability.** That is a version gap refused on the client
  side before anything is sent, so the fix is to upgrade that node's `vike-tradehub`.

## Usage errors that name the wrong token [#usage-errors-that-name-the-wrong-token]

The flag grammar refuses to let a valued flag eat another flag. `vike-cli backtest --script --json`
does not silently take `--json` as the script path; the error names the unfed flag **and** the token
it would have eaten. `--profile` with nothing after it is `--profile requires a value`, and
`--json=1` is `--json takes no value` rather than a silent true. The test is `--`, not a bare `-`,
because a negative number is a real value — `--qty -5` resolves to `-5`.

One class of message is not an error at all: a line like `vike-cli: <file>: …` about an indicator is
`install_user_indicators` reporting a `user_data/indicators/*.rhai` it could not compile. It goes to
stderr and never fails the command, deliberately — one half-edited indicator blocking every
invocation, including the `init` that scaffolds the examples, would be worse than the report. But
from inside a strategy that indicator is indistinguishable from a typo in the call, so this is the
only place that says which.

For the whole box rather than one verb, `vike-cli config check` judges the settings tree and the
credential store together and makes the verdict its exit code — see
[Scripting it](/docs/trader/cli/scripting) and [`config`](/docs/trader/reference/cli/set-up/config).


# The account (/docs/trader/concepts/account)



`crates/vike-exec/src/account.rs`'s `Account` is the money-side read model of one venue account:
positions and realized PnL derived from the fill stream, plus cash, fees, funding and the mark
slot equity is valued at. Its header lists the contract in one block, and this page is that block
expanded.

## One writer, no cache, fixed fold order [#one-writer-no-cache-fixed-fold-order]

`Account` is per-venue — `apply_fill` asserts the fill's venue matches its own — and keys positions
on `(venue, symbol, position_side)`, with `Both` for one-way and spot and the side reserved for
hedge-mode perpetuals. A `PositionEntry` is a signed `size` and an `avg_px`, plus a margin-mode
carrier so a position *can* be isolated. `fold` is the **sole writer** of position and realized PnL:
both `apply_fill` and `apply_liquidation` route through it, and it delegates the arithmetic to
`vike_model::compute_fill` — the one cost-basis primitive, whose doc forbids reordering an
operation or "simplifying" an expression — so the backtest engines and the live read model can never
drift about what open, add, reduce, close and flip mean. A position opening from flat takes its
*asset's* ruling margin mode rather than the type default, because one venue publishes
isolated-only per asset and a bare default booked every new position cross with nothing downstream
ever correcting it.

There is **no equity cache anywhere** — the header names catastrophic cancellation as the risk —
so every read is a sparse full recompute. `equity_all` is mode-aware: under `BalanceMode::Delta`
it is seed + balance + realized + Σ unrealized; under `Authoritative`, set when a venue's
`AccountState` assigns the balance absolutely, it is balance + Σ unrealized, because the venue's
number already folds the rest in. The sum is `vike_model::py_sum` over positions in insertion
order, and that is why every map on this type is an `IndexMap` and &#x2A;*never a `HashMap`**: the
insertion order *is* the `f64` fold order the [parity gate](/docs/trader/concepts/parity-gate) pins
against `fixtures/r0/account_scenarios.json`. `margin_in_use` is the same discipline applied to
margin — one fold that had been hand-rolled four times and had drifted on the rate fallback; only
the rate policy differs per caller now.

## The mark slot has one writer and a precedence law [#the-mark-slot-has-one-writer-and-a-precedence-law]

`Account.marks` is a single untagged scalar per symbol, read by the pre-trade risk gate, the
[margin-call](/docs/trader/concepts/margin-call) law, the trailing-stop seed and what a mounted strategy
calls "the price". Several feeds write it at wildly different cadences, so `set_mark_from` — the
only way in; the field is private after the law was bypassed three times — carries the rule: while
a symbol's slot holds a genuine venue mark observed within its source's ownership window, a
bar-close or trade-tick write is dropped; otherwise last-write-wins. A streamed mark owns for
`DEFAULT_MARK_STALENESS_MS` (10 s, about ten missed ticks); a mark sampled by reconciliation owns
for `DEFAULT_RECONCILE_STALENESS_MS` (150 s, sized past the default reconcile interval so the slot
does not alternate between passes). The same writer is the hostile-venue guard: a non-finite mark
is refused, and the doc explains why `px > 0.0` is not that check — `+inf` passes it and turns
equity into NaN, where every risk comparison reads false. The concepts the resolver drops still
fill their own [price board](/docs/trader/concepts/price-board) slots.

## The fill-dedup ledger lives on the aggregate that owns the money [#the-fill-dedup-ledger-lives-on-the-aggregate-that-owns-the-money]

`apply_fill` moves money — commission out of cash, fees accrued per asset, the position fold,
realized PnL — so it is not safe to call twice for one venue execution. The header records why the
guard moved here from the engine: the number of paths that re-deliver an already-folded fill kept
growing, and each is a producer that *knows* it duplicates — bybit's fast-then-authoritative
execution pair, binance perp's early fill and its twin sharing one id, hyperliquid's whole
`userFills` snapshot re-sent on every reconnect, alpaca's `since_id` boundary, the resync and replay
lanes. `Account` owns the set, consults it before anything moves, and reports a `FillFold`:
`Applied`, `Duplicate` (nothing moved, `duplicate_fills_refused` advanced — a large value here is
*normal* on those venues), or `Collision`.

<Callout type="warn" title="Keyed on the bare trade id, with a fingerprint that makes the narrowness visible">
  Venue trade ids are per-symbol sequences on several venues, and the paper client's counter is
  per-client, so two different executions can carry the same id string. Widening the key would be
  the move that loses money: the reconciliation diff compares venue-reported ids as bare strings, so
  a composite key would stop matching there and an already-folded fill would come back as a
  `MissingFill` and be folded a second time — the exact double-count the ledger exists to prevent.
  So the key stays bare, and each entry stores an FNV-1a fingerprint over `(symbol, side, last_qty,
  last_px)`. Same id and same fingerprint is a re-delivery, refused silently. Same id and a
  **different** fingerprint is an id collision — a genuine fill about to be dropped — counted into
  `colliding_fills_refused` and logged at error naming both fills. It is still refused, because
  folding on a mismatch would make the guard depend on venue rounding being stable; any nonzero
  value on that counter is a fault, and it understates the position. Reconcile the venue.
</Callout>

Two properties of the set are deliberate. It is **unbounded**: every capped alternative re-admits a
duplicate the moment a replay window reaches back past the cap, and the widest window here is a
one-hour lookback plus row-count-bounded venue history endpoints, not a fill count. And it is a
**within-session** guarantee: `crates/vike-exec/src/account.rs`'s `seed_seen_fill_ids` records that
seeding is the caller's job and no shipped binary does it, so a fresh process starts empty and a
replay lane reaching before the restart re-folds prior sessions' fills; a replay lane's spawn-time
floor and this ledger are independent, so neither substitutes for the other. An empty trade id is
unrepresentable: `FillEvent::trade_id` is a `TradeId` whose constructor refuses the empty string.

## The other folds [#the-other-folds]

`apply_funding` nets a periodic funding cashflow into cash. `apply_account_state` sets the balance
**authoritatively** from a venue snapshot — the quote-asset row if present, else a single balance,
else the `py_sum` of all — and flips the mode. `apply_liquidation` closes `min(reported, held)` at
the liquidation price through `fold` — a reported qty of exactly `0.0` closes the WHOLE held size,
the Python truthiness it ports — clamped so an over-reported frame can never flip the position,
and deducts the fee. What each event carries is one page each under
[events](/docs/trader/concepts/events/); which divergences reconciliation folds back into this account
is under [reconciliation](/docs/trader/concepts/reconciliation/).

`snapshot` and `restore` round-trip the account for the journal's `Snap` record and for
[replay](/docs/trader/concepts/journal/replay). Five things are deliberately not restored: the
per-asset ruling margin-mode grid (mount configuration rather than folded state — every restored
position keeps its own margin mode, but an open-from-flat after a bare restore reads an empty grid,
so a live restore path has to re-apply it), the balance-sync realized-PnL baseline (cleared, so the
first reconcile pass re-adopts venue cash), mark provenance (a restored slot is unowned, and the
next writer takes it), the two refusal counters (live health signals, not folded state), and the
dedup ledger itself — its durable home is the engine snapshot's `seen_trade_ids`, seeded back
immediately after restore, which is what kept the journal wire and its `state_hash` fence
byte-identical when the set moved onto this type.


# Accounts (/docs/trader/concepts/accounts)



A venue used to have exactly one credential set per tier, because the key names said so: the
grammar is `{VENUE}_{TIER}{SUFFIX}` and there was no place in it for a second account.
`crates/vike-model/src/account_keys.rs` opens with the requirement that changed that — an operator
may hold twenty hyperliquid accounts, demo and live, and wants every one visible and independently
armable.

## The key grammar, and why the label goes at the end [#the-key-grammar-and-why-the-label-goes-at-the-end]

The obvious spelling, `{VENUE}_{TIER}_{LABEL}{SUFFIX}`, is unparseable against keys that already
exist: several bespoke suffixes are multi-word, so `OANDA_DEMO_ACCOUNT_ID` would read equally well
as tier `DEMO`, label `ACCOUNT`, suffix `_ID` — a real live-credential key silently reclassified as
somebody's account. So the label is appended after the whole of today's key, behind a separator the
existing grammar cannot produce:

```
{VENUE}_{TIER}{SUFFIX}            the DEFAULT account — unchanged, byte for byte
{VENUE}_{TIER}{SUFFIX}__{LABEL}   a LABELLED account
```

`ACCOUNT_SEPARATOR` is a double underscore. That no existing key contains one is checked rather
than assumed — `no_existing_credential_key_contains_the_separator` folds the enumerable key grid and
sweeps the bespoke literals out of every bridge's source — so the parse is total: split at the first
`__`, the left half is today's key verbatim, the right half is the label, and it stays correct for
a suffix invented tomorrow. A label is `[A-Z0-9]+`, at most `MAX_LABEL_LEN` (24) characters because
it becomes part of a lock filename, and `DEFAULT` is refused by name since it would be a second,
silent name for the account an unlabelled key already addresses. `AccountLabel::parse` is
case-sensitive and does not repair: `alt` is refused, not uppercased, because a spelling the loader
fixes is a spelling nobody learns.

`AccountRef::route_key` is the identity a process addresses an account by — the bare venue id for
the default account, exactly what `ExecutionEngine::new` already seeds, and `venue#LABEL` for a
labelled one. It is the engine's `route_key`, the name of the `LIVE-<route_key>.lock` sentinel
`vike_ops::live_lock` claims for one live process per venue account, and the key the journal
records; the tier is deliberately not in it. `accounts_in_store` derives every account from the key
names in the credential store, so the enumeration is never a list anybody maintains.

## The per-account ceiling inherits nothing [#the-per-account-ceiling-inherits-nothing]

`policy.toml` gains an `[accounts]` table beside `[venues]`, and `VenuePolicy::account` resolves an
account's ceiling as `min(the venue's line, the account's own line)`. The asymmetry between the two
defaults is the whole safety argument: the **default** account with no line of its own inherits the
venue line exactly, so today's files resolve unchanged; a **labelled** account with no line of its
own resolves `paper`. A `bybit = "live"` line was written when bybit had one account, and reading it
as consent for an account that did not exist then is precisely the silent escalation the
[ceiling](/docs/trader/concepts/risk-and-arming) exists to prevent. The venue line caps both cases, so
`bybit = "paper"` disarms every bybit account whatever their own lines say.

`vike_mount::venue_account_arming` is the per-account projection — the rows the Data Manager renders
and the selection the mount fans out from, one function so the "Effective" column cannot disagree
with what the mount does. `known_accounts` unions the credential store (which accounts exist) with
the `[accounts]` table (which have a stated ceiling): an account with keys and no line appears as
`ArmingBlock::AccountNotNamed`, which tells the operator how to arm it, and an account with a line
and no keys appears as `NoCredentials`, so a typo'd label cannot vanish. `ArmingBlock::NoAccountSupport`
names a venue whose mount arm cannot address a second account at all; `vike_mount`'s
`arm_addresses_accounts` is the authority for that set, and its doc says one venue remains,
dukascopy.

`make_engine_accounts` mounts one engine per active account. The default account is always mounted,
paper included; a labelled account is mounted only when its ceiling permits something above paper
**and** its credentials load — a paper engine for an account nobody armed would be a second local
book nobody asked for. Result order is a contract: default first, labels in order. Each account is
mounted on its own symbol, and a strategy mount names the account it trades on
(`vike_exec::MountSpec::account`, which crosses the wire and is persisted with the
[runtime topology](/docs/trader/concepts/mounting)); the default account is spelled as an absent field,
so an account-less mount's bytes are unchanged.

## The shared-book rule reports and never refuses [#the-shared-book-rule-reports-and-never-refuses]

`crates/vike-config/src/venue_accounts.rs` states a correction first: the symbol is **not** part of
the rule. An earlier version refused two active accounts armed on one symbol, and the thing it
refused is an ordinary spread — long on account A, short on account B. Two accounts are two wallets;
the venue nets nothing between them.

The real hazard is two of this process's engines pointed at the **same venue book** — an agent key
signing for a master whose own key is also configured, or one credential set pasted under two
labels. Each engine reads "I hold 1" while the venue holds 2, and reconcile's auto-applied
[`PositionDrift`](/docs/trader/concepts/reconciliation/position-drift) rewrites each onto a total that
includes the other's. `shared_books` finds every pair of distinct, active accounts of one venue
resolving to one book, and `make_engine_accounts` emits one warning per pair naming the venue, both
labels and the book — and mounts both. The operator wrote both credential sets by hand under
explicit labels; a refusal would strand a venue on paper over a configuration they may have meant,
while a line naming the two labels lets them recognise a paste error in seconds. `paper` is not
active, since the paper exchange fills locally; `demo` is, because a demo account is a real book
with real rejections.

<Callout title="Where the book cannot be determined, nothing is said">
  `vike_mount::book_identity` answers per venue. An EIP-712 venue derives its wallet address from the
  private key in the store, so the answer is exact and offline; a key/secret venue's store holds an
  HMAC key and nothing that names an account, so it contributes no `ArmedBook` and no pair can form —
  a placeholder would compare equal to every other unknown and manufacture a pair. The declared
  residual: the same api key and secret pasted under two labels on binance, bybit, okx or deribit is
  the same book and the table says nothing, because a row may only name values that are safe to log.
</Callout>

One more thing follows the account rather than the venue: `Event::AccountState` names no symbol, so
`account_event_sender` scopes each account's exec-event lane to its route key, and a second
account's balances land in its own book rather than the venue's default engine.


# Alerting (/docs/trader/concepts/alerting)



`vike-alerting` exists because of a loss. prod1 crashed and roughly six hours of recorded Polymarket
L2 tape were lost unnoticed; the wanted fix was a watchdog that pages when a recorder stops writing,
with no business linking the trading core. Inside `vike-ops` it would have had to link `vike-core`,
`vike-exec` and `vike-model` just to post a message, so the crate was split on the seam that was
already there. A default build has **zero** `vike-*` dependencies, and the gate is `cargo tree`,
not the feature list: the `alerting-standalone` lane builds the default configuration alone and
fails if any `vike-` line appears. Only the two inputs that name a vike type — a `CoreSnapshot` and
a typed `Event` — sit behind the `core` feature. The whole thing is an off-fold consumer of
published state: the headless daemon's summary thread hands the lossy snapshot to the engine once
per tick, and nothing here back-pressures or blocks the [core](/docs/trader/concepts/execution-core).

## Rules [#rules]

`rule.rs` is pure data and serde. An `AlertRule` has a stable `id` (the evaluation-state key, the
cooldown key and the delivery correlation id), a `name`, an `enabled` flag, a `trigger`, delivery
`targets`, a `cooldown_ms` and a `once` flag. `RuleTrigger` is internally tagged on `kind`; an
unknown kind from a newer build fails the whole parse, and the loader then ignores the file. The
kinds, by the input that evaluates them:

| input               | triggers                                                                                                                                                                                           |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| a snapshot          | `Price` — the published mark crosses a level; `Drawdown` — the daemon's own equity curve draws down from its session peak, latched; `ReconAlert` — a held reconcile divergence is present, latched |
| an indicator sample | `Indicator` — a streaming-indicator output crosses a threshold; the rule stores the registry key, output index and params, and the consumer computes the value                                     |
| a typed event       | `Fill`, optionally scoped; `OrderRejected` — a venue rejection or a `RiskGate` denial                                                                                                              |
| a status signal     | `Feed` (degraded or recovered), `FillRateBreaker`, `PolymarketResolution`, `SeriesStale`                                                                                                           |

Crossings are edge-triggered: `Above` fires on the transition from at-or-below to strictly above,
never every tick the value stays there. `Drawdown` deliberately tracks `Portfolio::drawdown_curve`
— configured capital plus the daemon's own P\&L — and not the cross-venue equity total, because the
total includes each live venue's wallet, which a third party can move; it is the quantity the core's
own liquidate-only latch uses, so the two cannot disagree. `SeriesStale` is the trigger the crate was
split for, and it is deliberately not `Feed`: feed health is venue-scoped and reports a transport
transition, while this one is series-scoped and reports an absence — the socket is established, the
subscription returned `Ok`, and there are no rows. Its scope is a prefix match on the recorder's
`kind/venue/symbol` key, because a Polymarket up/down family mints new token ids every five minutes
and the series an operator wants to watch does not exist yet when the rule is written.

## Evaluation [#evaluation]

`eval.rs` is the pure evaluator: `(rule + per-rule state + one input) -> Option<FiredAlert>`, with
no I/O, no clock (the caller passes `now_ms`) and no delivery, so every trigger's fire-or-not is
unit-tested with plain values. Each of the four entry points returns `None` for a rule whose trigger
belongs to a different input, so the engine hands every enabled rule to every entry point without
partitioning. `RuleState` holds the previous scalar sample — `None` until the first, so a rule can
never fire on its very first observation — the running drawdown peak, the latch, the last fire time
and the once flag; `maybe_fire` applies cooldown and once before building the alert. State is keyed
by rule id in an `IndexMap` so fire order is deterministic, and `set_rules` clears all of it: a rule
edit is a config change, and every latch re-arms.

## Delivery [#delivery]

An `AlertSink` is fire-and-forget: `deliver` must never block the caller for long and must never
panic, because the engine calls it inline while draining rules. Each sink self-filters on the
alert's `AlertTargets`, so routing lives in the alert rather than the dispatcher. `InProcessSink` is
an in-memory buffer for the toast surface a desktop app would drain on repaint, and no shipped
mount registers one. `WebhookSink` posts to Telegram or a generic JSON webhook over the workspace's
one `ureq` and rustls stack through an injected transport with a 10 s timeout, so the seam is
testable with a fake sender and never touches the network in CI. Webhook names in a rule resolve
against configs built from a **caller-supplied** credential map by `webhook_configs_from_env`; a
name with no config delivers nowhere, and the crate never opens the credential store itself.

<Callout type="warn" title="A Telegram URL embeds the token">
  `WebhookKind` holds the bot token or the webhook URL, so its `Debug` is manual and redacting and it
  is never serialized beside the rules. A failed delivery logs the target name and a coarse error
  category only — never the endpoint URL and never the raw transport error, whose display can echo
  the request target. A bare HTTP status carries no secret and is surfaced; everything else is
  "transport error".
</Callout>

## Persistence, and where `alerts.json` lives [#persistence-and-where-alertsjson-lives]

`persist.rs` reads no environment variable and resolves no path. `load_path` and `save_path` take a
caller-supplied `&Path`, and `ALERTS_FILE` — `alerts.json` — is the one thing the module states, so
the binary composing the directory does not re-spell the basename. An absent or unparseable file is
`None`, the off state, never an error. Every field but `id` and `trigger` is `#[serde(default)]`,
so an older file still loads, and `AlertRuleSet` carries a schema version, currently 1. The daemon
resolves `$VIKE_ALERTS`, falling back to `<project>/settings/state/alerts.json` — the
[settings page](/docs/trader/reference/settings/alerts) carries the file's shape.

In the [headless daemon](/docs/trader/reference/binaries/vike-tradehub), `maybe_mount` is the gate: no
file, a file with zero rules, or a file whose every rule is disabled all return `None`, and then
nothing is constructed — no engine, no sink, and no webhook token loaded into memory, because the
webhook configs are passed as a thunk the off path never calls. When it mounts, a `LogSink` is
always registered (a `tracing` warn record on the log file, never stdout, which stays the daemon's
protocol), and the engine is driven from the existing summary thread, one `on_snapshot` per tick.
That is the one input the daemon can feed today, so `Price`, `Drawdown` and `ReconAlert` fire
there; event, indicator and signal rules load, are counted, and never fire in the daemon —
`SeriesStale`'s producer lives in `vike-recorder`'s own alerts module. The window that edits rules
in the desktop app is an explicit follow-up.


# Architecture (/docs/trader/concepts/architecture)



Vike Trader is a Cargo workspace of small crates. Three things about its shape are load-bearing
and worth knowing before any other concept page: dependencies point in one direction only and a
test enforces it; every crate declares its own rank; and the five binaries that boot a process do
so through one shared sequence rather than five copies of it.

## Dependency direction is down only, and it is a gate [#dependency-direction-is-down-only-and-it-is-a-gate]

Every workspace member declares its rank in its own manifest:

```toml
[package.metadata.vike]
layer = 30
```

`crates/vike-ops/tests/layer_gate.rs`'s `every_normal_vike_dependency_goes_strictly_down` asserts
that for every **normal** (non-dev) `vike-*` dependency edge `c -> d`, `layer(d) < layer(c)`. It is
text-only over the manifests — no cargo invocation — and it fails a pull request rather than
producing a review comment. A dev-dependency may point upward, and the workspace does so on
purpose: `vike-mm` dev-depends on `vike-core` so its white-box tests can build a concrete
`LiveBroker`, and `vike-bridge-core` dev-depends on ten venue crates to run the shared conformance
harnesses. `dev_dependencies_genuinely_point_upward` in the same file asserts that the exemption is
still needed, so nobody can fold dev edges into the rule and have it pass for the wrong reason.
`[build-dependencies]` are not exempt.

The gate exists because of one edge that actually shipped. A single normal dependency from
`vike-tradehub` — the headless daemon that runs on the box that signs real orders — to
`vike-app-core` dragged the entire egui widget stack into that daemon, for three pure modules. The
cost was never CI minutes: it was daemon build time, binary size, and the
`cargo deny --all-features` supply-chain audit surface on a production trading node. It was found
by somebody noticing build times — no test, no gate, no diff comment. `vike-ops` exists because of
it.

### The tiers [#the-tiers]

The ranks were established by reading the real graph — all 275 normal `vike-*` edges in the tree
the gate was written against — not from a narrative order, and the tree had no violation to fix
when the gate landed. `layer_gate.rs`'s `TIERS` is the authority, and a crate's `layer` must be one
of its ranks, so a new rank costs a row with a written meaning; the gaps are deliberate, so a crate
can be slotted between tiers without renumbering the workspace.

| rank | tier            | what sits here                                                                    |
| ---- | --------------- | --------------------------------------------------------------------------------- |
| 10   | vocabulary      | `vike-model` itself — the shared domain vocabulary every other layer names        |
| 15   | leaf            | a pure leaf with no `vike-*` dependency of its own                                |
| 20   | domain          | one hop over the vocabulary: a single-purpose pure core                           |
| 25   | boot            | the composition-root startup sequence, below every binary that runs it            |
| 30   | engine          | a runtime, simulation or transport core over the domain crates                    |
| 35   | user-host       | a `build.rs` host that compiles user-authored code out of `user_data`             |
| 40   | venue           | a per-venue bridge built on `vike-bridge-core`                                    |
| 41   | venue-stacked   | a venue bridge built on a sibling venue's family driver                           |
| 45   | research        | an offline study crate that mounts no venue — vacant today, kept deliberately     |
| 50   | service         | a library composed over the engine crates                                         |
| 55   | service-stacked | a service composed over another service crate                                     |
| 60   | mount           | the venue composition root (`make_engine`)                                        |
| 62   | mount-stacked   | a composition root over `vike-mount`                                              |
| 65   | daemon          | a headless top-of-graph binary                                                    |
| 68   | multicall       | the multicall dispatcher: depends on every headless binary, nothing depends on it |
| 70   | ui-foundation   | the egui foundation leaf — everything above here links egui                       |
| 75   | ui-widget       | an egui widget or engine crate, no eframe/wgpu                                    |
| 80   | ui-shell        | an egui shell assembled from the widget crates                                    |
| 90   | app             | the desktop application: the outermost shell                                      |

<Callout type="warn" title="A rank is a total order; the architecture is a partial one">
  Where two families are genuinely incomparable the numbers still have to put one above the other,
  and the gate then permits the wrong-direction edge in whichever direction was chosen. Those choices
  are made toward the mistake that has actually happened. The whole UI stack is ranked **above**
  every headless daemon — which is what makes the motivating `vike-tradehub -> vike-app-core` edge
  fail; ranked by topological depth instead, it would pass. And venues (40) sit **below** the
  simulator (50), so a bridge crate that reaches for `vike-backtest` is red; the reverse edge is the
  one the numbers let through, because pulling the engine into a venue adapter is the "dragged the
  whole tree in" shape the gate exists for.
</Callout>

## The layering rule that keeps being re-learned [#the-layering-rule-that-keeps-being-re-learned]

When two sides must not disagree, the cure is a shared crate **below** both, not a shared crate
containing both. `vike-fills` (`crates/vike-fills/src/lib.rs`) is the worked example: one
definition of what a fill costs, when it happens and at what price, extracted verbatim out of the
backtest engine so that the paper exchange and the simulator share a *dependency* rather than a
crate. While both lived inside `vike-backtest` their agreement was true by co-location, and the
price was that every consumer wanting only the paper executor compiled the whole simulator to get
it. That is what lets `backtest == paper` be gated bit-for-bit rather than asserted — the
[paper exchange](/docs/trader/concepts/paper-exchange) page carries the law and its scope.

## One startup sequence, one owner [#one-startup-sequence-one-owner]

Five composition roots — `vike-desktop`, `vike-tradehub`, `vike-recorder`, `vike-cli` and
`vike-datahub` — used to run the same ordered steps from five copies: refuse a removed environment
variable, resolve `<project>/settings`, load the credentials (and refuse a credential file that
arms real money), load the settings, derive the project-relative paths and build the log
subscriber, then disclose what was resolved. `vike_boot::boot` (`crates/vike-boot/src/lib.rs`)
owns that order now, and `crates/vike-boot/tests/one_owner.rs` is the gate that a root may not
re-spell it: a call to a step of the sequence must be in `vike-boot` itself or in a declared
exception row carrying its reason, and a crate that boots may not call a project resolver anywhere
under its own `src/`. The exceptions today are re-reads rather than second startups — the CLI's
`config check` pre-flight, which re-runs a refusal in order to *report* it, and the daemon's
runtime hot-apply and the Data Manager's arming screen, which both re-read settings out of the
directory the boot already resolved and handed them.

Each root declares how it departs from the sequence with a `BootSpec` whose arms carry a reason —
`RemovedEnv::Ignore`, `SettingsLoad::Skip`, `Credentials::Deferred`, `LogHome::Elsewhere`,
`Disclosure::Skip` — never a `bool`. Turning a startup refusal off is exactly the change that
should have to justify itself in a diff. `vike-cli` runs the refusal for every subcommand but
builds no subscriber and defers the credential read; `vike-datahub` loads no settings at all.

The load-bearing property is not the order, which every root got right by copying. It is that
**one project walk decides per process**, and every project-relative path is derived from its
answer: the settings load, the state root (`Booted::state_dir`), the log home and the startup
disclosure. Before that, four sites reached a resolver that did not honour `$VIKE_SETTINGS_DIR` —
so the second answer was specifically the one that ignored the override, on exactly the
deployments that set it: a desktop whose rolling log file and startup block named two different
projects.

Two resolutions remain outside the boot, and neither can disagree with it. The credential store is
reached through the root's own loader (`Credentials::LoadWith`) over the same pure resolver and
the same override, so it is a duplicated cost, never a second answer. And the halt sentinel's
default location is memoized deep inside a library with no boot in reach, so the two booting
trading roots hand it `Booted::state_dir` as a parameter — with one declared residual: two mount
binaries in the tree never call `boot` at all, so their sentinel still walks, and nothing gates it
either way.

<Callout title="Three properties of the boot worth carrying">
  It runs the **arming refusal before the settings load** — a tree that arms real money and has a
  broken `policy.toml` must fail with the arming message, the more urgent of the two. It **logs
  nothing and prints nothing**, because it runs before `vike_log::init` and the log directory and
  both log levels are themselves settings; everything it would say comes back as data and the root
  emits it once a subscriber exists. And it **never opens the credential store** itself — the loader
  is a function the root supplies, so `vike-cli` can defer the read entirely and no consumer
  inherits the bridge crates' HTTP and TLS stack; measured on the tree the crate was written against,
  the one `vike-log` edge it refuses would add 43 packages to `vike-cli`.
</Callout>

A layering failure is read on the [structure gates](/docs/trader/developer/structure-gates) page; the
rule itself lives here.


# Contingent orders (/docs/trader/concepts/contingency)



A bracket is three orders with two relationships between them: the protective stop and the
take-profit are **held** until the entry fills (one-triggers-other), and once armed, whichever exit
fills **cancels** the other (one-cancels-other). `crates/vike-exec/src/contingency.rs` is the one
place those two relationships are resolved, and its header says why it had to be one place.

## The defect that made it one resolver [#the-defect-that-made-it-one-resolver]

Before this module the law lived lane-dependently. The paper book ran full one-cancels-other on
every fill, while the backtest `SimBroker` cancelled a fired protective stop's exit siblings only on
its granular sub-bar lane — its coarse and tick lanes left the take-profit limit resting on a flat
book, so one wide bar could fire the stop *and* the take-profit and open a spurious reversed
position. The paper book's own `apply_contingency` was the semantic template the module lifts.

The module owns only the **decision** — which children arm, which siblings cancel. Both callers
keep their own book mechanics: resting-order storage, event emission, the actual cancels. That
split is what makes the two lanes structurally unable to disagree again, and the
[paper exchange](/docs/trader/concepts/paper-exchange)'s r7 gate has a bracket row that proves it — the
backtest broker's entry-with-protective-stop plus resting take-profit fills bit-identically to the
live `submit_bracket`'s triple resting in the paper book, with both stops firing through the one
trigger oracle and both sides cancelling the surviving exit.

## Two linkage shapes, one law [#two-linkage-shapes-one-law]

**Coid-linked** — `ContingencyBook`. Explicit `parent` and `linked` client-order-ids ride on the
order request, which is what the bracket lowering `vike_model::build_bracket` emits: an entry with
no parent, linked to both exits; a stop whose parent is the entry, linked to the take-profit; a
take-profit whose parent is the entry, linked to the stop. Live, `OrderIntent::Bracket` is the verb
— the runtime mints the three ids and wires the links — and the paper book keys its own book by
those ids.

**Kind-linked** — `is_protective_exit_sibling`. The backtest `SimBroker` arms an id-less implicit
bracket through `WorkingOrder::stop`, so after a protective-stop fill flattens the position there is
no id to follow. Its siblings are identified *by kind*: a resting order is that stop's
one-cancels-other partner, and must cancel, if and only if it is a closing-side `Limit` or
`LimitClose` exit. Entries and adds on the opposite side never match, and neither do stop or
trailing kinds — a second protective layer is not a take-profit. The test pins both directions: a
long stopped out cancels sell limits and keeps a re-entry buy limit and a second stop; a short
stopped out mirrors it.

## What the book does on a fill [#what-the-book-does-on-a-fill]

`ContingencyBook::insert` records a leg's linkage. A held exit — one with a parent — starts
*inactive*; an entry starts active immediately. `is_held` is the question a fill pass asks before
letting an order fill: a held order must not, and every plain order, which is never inserted at
all, is never held. That absence is the byte-identical path for non-bracket runs — a book with no
brackets stays empty and every resolver call is a cheap no-op.

`on_fill` resolves one fill in two steps: arm every held child of the filled id, then return its
one-cancels-other siblings — its `linked` ids that are **not** its own children — in `linked` order.
The caller cancels whichever of those still rest in its book and calls `remove` for each one it
actually cancelled; a sibling already gone cancels nothing. The bracket test shows the shape: the
entry's fill arms both exits and cancels nothing, because the entry's linked ids are its own
children; the stop's fill then returns exactly the take-profit. A plain, unrecorded fill arms nothing
and returns empty.

`siblings_of` answers the same sibling question read-only, so a *dying* protective exit — cancelled
or expired rather than filled — resolves its surviving partner off the same linkage a fill would,
and the terminal-cancel and fill-cancel paths cannot disagree about who the sibling is.
`children_of` is the walk step of the expire/cancel cascade: a child whose parent terminated
without filling can never arm. `clear` is the mass-cancel twin.

<Callout title="Restarting with an armed bracket in flight">
  `insert` derives `active` from "has no parent", which is wrong for a child that was already armed by
  its parent's fill before a crash: re-inserting it would silently re-hold an armed exit. So the book
  exposes `snapshot` — every entry as `(coid, parent, linked, active)` in insertion order — for the
  journal's `Snap` record, and `insert_active` takes the flag explicitly for the restart re-seed.
  Neither is used on the live submit path; both exist so [replay](/docs/trader/concepts/journal/replay)
  reproduces the same arm and cancel iteration order the live book had, which is also why the book is
  an `IndexMap`: the arm sweep and `children_of` iterate the map, and insertion order keeps the event
  stream reproducible.
</Callout>

<Callout type="warn" title="Live, the drive is gated on the fold's verdict">
  On the venue ingest lane the runtime drives this resolver only when the
  [event bus](/docs/trader/concepts/event-bus) reports that the engine actually applied the fill. The
  `Fold` verdict was added for exactly this consumer: a fabricated `OrderFilled` on an unknown
  client-order-id used to cancel its sibling and arm its held children even though the engine had
  dropped the event — a naked position on the strength of a fill that never happened.
  `crates/vike-core/src/runtime/mod.rs`'s `pump_client` records that the in-process client seam is
  deliberately not gated the same way.
</Callout>

One boundary of the coid-linked shape is declared where it bites. The paper client's combo book
does not support contingency links *on* a multi-leg combo — a combo request carrying a parent or
linked ids is terminally rejected, because the hold and cascade machinery enforce against the
single-symbol resting book only — while a plain order may link a resting combo as a sibling, and a
combo's fill arms plain held children as any fill does. What each order kind means, and which venues
carry it natively, is under [orders](/docs/trader/concepts/orders/); a conditional the core emulates for
a venue without one is [emulated orders](/docs/trader/concepts/emulated-orders).


# The control boundary (/docs/trader/concepts/control-boundary)



`crates/vike-core/src/control.rs` names the external control boundary of the live core in one
place, and its contract fits in a sentence: `Command` and `OrderIntent` go **in** through
`CoreHandle::try_command` (non-blocking, the desktop app's path) or `CoreHandle::send_command`
(lossless, for session control and tests), and `CoreSnapshot` queries come **out** through the
snapshot's accessors — `orders_for`, `order`, `open_order`, `position`, `last_mark`, `equity`,
`trading_state`. The desktop app, the CLI and the MCP server are translators over that seam. Nothing
bypasses it.

## Why one seam matters: the risk gate is structural [#why-one-seam-matters-the-risk-gate-is-structural]

Every order-scoped verb is an `OrderIntent`, and every intent from every origin lowers through the
core's single `apply_intent` site: mint a client-order-id, route, run the `RiskGate`, hand the order
to the venue client. `crates/vike-core/src/runtime/apply.rs` lists the origins it serves — the
external command path, a mounted strategy's drain, a conditional order firing, a margin-call
liquidation — and notes that a source-scan test in the control-boundary suite enforces that no engine
submit call lives outside that file. The consequence for a reader is that there is no path by which
a front end can place an order that the [risk gate](/docs/trader/concepts/risk-and-arming) did not see. It
is a property of the code's shape, not a convention each caller has to remember.

## Fire-and-forget [#fire-and-forget]

Commands have no synchronous reply. The core is a [single-writer fold](/docs/trader/concepts/execution-core),
and a synchronous order handle was considered and rejected. A caller that must know its
client-order-id pre-mints it: a non-empty `client_order_id` on the request is respected, and an
empty one asks the core to mint. Outcomes are observed through the snapshot — `rejected_commands`
counts queue rejections, and a `RiskGate` veto surfaces as an `OrderDenied` event in
`recent_events`. Everything about an order's later life arrives as venue events and is read from the
[published snapshot](/docs/trader/concepts/portfolio-and-snapshot), which is how the
[order lifecycle](/docs/trader/concepts/order-lifecycle) is meant to be watched.

The two entry points differ only in what happens when the ingest lane is full.
`CoreHandle::try_command` is a `try_send`: it never blocks, a full queue returns
`CommandRejected::Busy` and increments the same rejected counter the snapshot surfaces, and a closed
lane — the core has exited — returns `CommandRejected::Gone`. `CoreHandle::send_command` is a
`blocking_send` into the same lane: every command queued ahead of it still folds first, and a closed
lane is ignored, matching `shutdown_and_join`.

<Callout title="Why the GUI path may drop and the session path may not">
  `crates/vike-core/src/runtime/mod.rs` pins the ingest design: one dedicated thread owns all mutable
  trading state and reaches it through one totally-ordered queue. Exec events from venues are lossless
  and back-pressure the venue task — never the GUI. Commands from the GUI use `try_send` so the GUI
  thread never blocks, and a full-queue rejection is returned to the caller **and** counted in the
  snapshot, so it cannot be silent. Market data rides a latest-wins conflation slot with at most one
  marker in flight. The two command paths are the same lane with two policies for the full case.
</Callout>

## The out-of-process write half [#the-out-of-process-write-half]

`CoreHandle::command_sink` hands out a `CommandSink`: a narrow, cloneable capability holding only
the ingest lane and the shared rejected counter. It is what the headless daemon's control server
holds, and it lowers a remote `Scope::Control` peer's order command into the same `apply_intent`
seam — carrying no snapshot read, no market slot and no join handle, so a connection can neither
read state nor shut the core down. Its `try_command` is, by its own doc, the exact body of
`CoreHandle::try_command`, so mint → `RiskGate` → client stays structural on the network path too.

The sink also carries `send_blocking`, the lossless twin, for the operator's own stdio loop — a human
at a terminal may wait for their typed order. The remote server path deliberately keeps
`try_command`: a network peer must never be able to back-pressure a per-connection thread. How a
remote peer reaches the sink at all — keys, framing, the handshake — is the
[node protocol](/docs/trader/concepts/node-protocol).

## Building another front end [#building-another-front-end]

The module's own guidance for a new adapter is short. In-process — a headless mode or a REPL inside
the running core binary — holds the `CoreHandle` and the snapshot cell directly; no transport is
needed. `Command` is already `serde`, so the recommended first cut for anything else is newline-JSON
over stdio. Out-of-process additionally needs a transport and `Serialize` on the snapshot view
types; that layer was parked until a real consumer existed, and the write half of it now does, as
the `CommandSink` above. The [CLI's trade verb](/docs/trader/reference/cli/trade/trade) and the
[agent tools](/docs/ai/trader/) are both translators in exactly this sense: they compose commands, submit
them, and read the snapshot.


# The data model (/docs/trader/concepts/data-model)



`vike-model` is rank 10 in the [layering](/docs/trader/concepts/architecture): the vocabulary every
other crate names and depends on. Almost all of it is pure value types; the exceptions touch disk —
`crates/vike-model/src/state_path.rs`, `store_path.rs` and `tick_store_path.rs` probe the filesystem
to answer where a project, its settings and its store root are, and `change_journal.rs` and
`scratch.rs` write under the answer. The crate header carries the parity rules every port in it
obeys — `f64` end to end, expressions in the same order as the source they were ported from, no
fused multiply-add, exact-zero flat checks kept as `== 0.0`, timestamps as epoch-millisecond `i64`.
This page is the handful of its types a reader meets on every other page.

## Bars and ticks [#bars-and-ticks]

`crates/vike-marketdata/src/bar.rs`'s `Bar` is one OHLCV candle, resolution-agnostic: a timestamped
price event with `ts`, `open`/`high`/`low`/`close`, `volume`, and four optionals — `funding` (a
perpetual's rate at this bar, if available), `bid` and `ask` (the opening best quote of the bar's
window, tick-derived and `None` for plain OHLCV bars), and `symbol`, the fully-qualified
`SYMBOL.VENUE` id the engine dispatch attaches. `QuoteTick` and `TradeTick` are the two tick
shapes, and both carry `local_ts` beside `ts`: the machine receive time, captured so feed latency
can later be *replayed* rather than modelled — it cannot be captured retroactively, and `0` means
the row was never stamped (a fixture, a backfill).

Ticks become bars in `crates/vike-marketdata/src/consolidator.rs`: a quote bar takes OHLC from the mid,
`volume` as the tick count, and the bucket's *opening* best bid and ask — what a next-open market
order fills against — while a trade bar takes OHLC from price, `volume` as summed size, and no
quote. Two shapes live there: the batch `consolidate_*` functions, hex-pinned against frozen
fixture bytes by the [parity gate](/docs/trader/concepts/parity-gate), and `BarConsolidator`, the
streaming twin for live folds where ticks arrive one at a time.

## The L2 book, and its one delta-apply law [#the-l2-book-and-its-one-delta-apply-law]

`crates/vike-marketdata/src/orderbook.rs`'s `L2Book` is the in-core reducer: venue tasks decode depth
deltas, the book folds them, and a strategy reads the result through `on_order_book`. Prices are
quantized to integer ticks — `price / tick`, rounded half to even — so levels live in a
`BTreeMap<i64, f64>` keyed by tick: exact equality with no float-key hazard, ordered for O(log n)
best bid and ask. A delta whose quantity is zero removes the level, by venue convention. All its
arithmetic is add, subtract, multiply, divide and compare, so it is bit-parity eligible.

Whether an incoming delta folds, is dropped as stale, or means frames were lost is **one**
decision, `L2Book::delta_decision`, with two policies, so that live consumers and replay can never
diverge:

| `SeqPolicy` | applies when          | stale when                                                                          | gap when                                                                                                                          |
| ----------- | --------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `Monotonic` | `seq > last_seq`      | `seq <= last_seq` (except the "no seq supplied" sentinel `0`, which always applies) | never — a jump is normal on these streams, and gap detection is the bridge's own upstream rule                                    |
| `Strict`    | `seq == last_seq + 1` | `seq == last_seq`                                                                   | anything else: a forward jump (dropped frames) or a regression (a venue restart) — the consumer must resync from a fresh snapshot |

`Strict` is the rule for streams whose sequence increments by exactly one per applied event, and
for the recorded `BookUpdate` chain every feed emits — which is what gives
[tick replay](/docs/trader/backtesting/tick-replay) its integrity rule.

<Callout title="The walk-the-book helpers are upper bounds, not execution guarantees">
  `avg_px_for_quantity`, `quantity_for_price`, `simulate_fill`, `can_fill` and `fill_ratio` are pure,
  read-only estimates against **displayed** liquidity. Hidden flow, latency and queue dynamics only
  make the real fill worse. Their intended consumers are the risk gate's opt-in impact veto and the
  DOM ladder's cost-to-fill display, and degenerate inputs — a NaN, a crossed book — degrade rather
  than panic.
</Callout>

## SymbolProperties — the per-symbol placement grid [#symbolproperties--the-per-symbol-placement-grid]

`crates/vike-model/src/instrument.rs`'s `SymbolProperties` holds the venue-neutral order-placement
bounds every venue's REST parser fills from its own instrument endpoint: `tick_size`, `step_size`,
`min_qty`, `max_qty`, `min_notional`, and the later arrivals `contract_size` (how much underlying
one unit of quantity controls — a Deribit BTC option is one BTC per contract) and an optional
tiered `tick_scheme`. It lives in `vike-model` rather than in the bridge crates because it is pure
domain data consumed on the venue-neutral side of the seam; the per-venue parse functions stay
with their venues. An absent property is `0.0` — "the venue did not constrain this" — and the
[risk gate](/docs/trader/concepts/risk-and-arming)'s limits are built from this grid at mount. The
struct grows, and its doc says to construct it with functional-update syntax for that reason: one
added field once broke construction across fourteen crates. Its own page in the
[instruments](/docs/trader/concepts/instruments/symbol-properties) tree goes deeper.

## The fill primitive [#the-fill-primitive]

`crates/vike-model/src/fill.rs`'s `compute_fill` is the **one** cost-basis primitive: how a fill
transitions a position — open, add, reduce, close, or flip — returning a `FillOutcome` with the new
size and average price, the closing quantity, the realized PnL on it and the leftover opened on the
far side of a flip. Callers keep their own cash, fee and trade-record bookkeeping and delegate only
this shared arithmetic, which is what stops the backtest engines and the live read-model drifting
from each other. Its branch math mirrors a frozen fixture bit for bit, and its own documentation
says not to reorder an operation, introduce a fused multiply-add, or "simplify" an expression.

## The Event enum [#the-event-enum]

`crates/vike-model/src/events.rs` defines the immutable order, fill, position and account events.
Every one is a plain value struct — `Clone`, no interior references — so events are copy-safe
across the channel boundary between a venue thread and the core. `Event` is the tagged union the
core loop consumes, serialized with a `"type"` tag, and it has twenty variants:

`AccountState` · `Fill` · `Funding` · `OrderAccepted` · `OrderCancelRejected` · `OrderCanceled` ·
`OrderDenied` · `OrderExpired` · `OrderFilled` · `OrderLiquidated` · `OrderModified` ·
`OrderModifyRejected` · `OrderPartiallyFilled` · `OrderRejected` · `OrderSubmitted` ·
`OrderTriggered` · `PositionChanged` · `PositionClosed` · `PositionLiquidated` · `PositionOpened`

Each has its own page under [events](/docs/trader/concepts/events/), generated from the enum so the
list cannot drift. The [order lifecycle](/docs/trader/concepts/order-lifecycle) page is where the order
events meet the state machine; `OrderRequest`, in the same crate, is the submission intent
itself — what a strategy, a manual ticket or a bracket builder constructs, with every field's Rust
`Default` pinned equal to its `#[serde(default)]`.

## The interning rule [#the-interning-rule]

`venue` and `symbol` on every event are interned strings — 8-byte `Copy`, pointer-equality,
serde-transparent. The interner **never frees** an entry, so interning is only sound for a field
whose set of distinct values over a process lifetime is bounded. That holds for a venue (about ten
values ever) and a symbol (bounded by the distinct instruments subscribed per session — even a
prediction-market token id is minted per market and reused on every tick of it, so the interned
set is hundreds to low thousands of markets, not the trade count).

<Callout type="warn" title="trade_id is deliberately NOT interned, and cannot be empty">
  It is minted **per fill**, unbounded, so an interned trade id would leak without bound. It is a
  `TradeId` newtype over a compact stack string instead. The newtype also closes a measured defect:
  `trade_id` is the dedup key for the whole money lane, and an empty id did not dedup badly — it
  skipped dedup entirely, so a re-applied fill double-booked commission and realized PnL on a live
  daemon. `TradeId` implements no `Default`, so the `unwrap_or_default()` that produced those
  empties is a compile error; `TradeId::new` refuses `""` and hands the venue mapper the decision.
  The rule generalises: only bounded, repeated label fields are interned; high-cardinality per-event
  ids are not; and secrets are never interned, because an interned string cannot be zeroized.
</Callout>


# The dead-man's switches (/docs/trader/concepts/dead-mans-switch)



A dead-man's switch is the automatic counterpart to the manual [halt](/docs/trader/concepts/halt)
sentinel: when nobody is in front of the daemon, something cancels the resting orders anyway. Vike
Trader ships **two of them**, and one sentence separates them — *what each one accepts as evidence
that the daemon has lost the market*:

* **The connection dead-man** reads the link state a venue's own bridge discloses. A feed reported
  `Disconnected` for longer than `policy.toml`'s `link_deadman_grace_ms` cancels **that venue's**
  resting orders. **The key absent means ARMED**, at two minutes.
* **The silence dead-man** reads ingest. No venue event, tick, bar, quote, trade or book update on
  *any* venue for longer than `deadman_timeout_ms` cancels **every** resting order. **The key
  absent means OFF**, with one warning at mount.

The defaults point in opposite directions because a market that **closes** is silence and is not a
disconnect. The connection switch cannot see a close, so it may be armed by default; the silence
switch cannot tell one from an outage, so it may not.

|                      | connection dead-man                                     | silence dead-man                          |
| -------------------- | ------------------------------------------------------- | ----------------------------------------- |
| key in `policy.toml` | `link_deadman_grace_ms`                                 | `deadman_timeout_ms`                      |
| absent               | armed at `DEFAULT_LINK_DEADMAN_GRACE_MS` — 120 000 ms   | off, warned about once                    |
| off is spelled       | `= 0`, the only off                                     | `= 0`, or left out                        |
| evidence             | `FeedStatus::Disconnected` per (venue, symbol)          | nothing arrived, anywhere                 |
| a session close      | invisible — a close reads `Stale`, which never counts   | trips it                                  |
| a trip cancels       | the venue whose link died                               | every venue                               |
| where it arms        | a per-venue table *and* a disclosing lane in this mount | wherever the key is written               |
| authority            | `crates/vike-core/src/runtime/link_deadman.rs`          | `crates/vike-core/src/runtime/deadman.rs` |

They are independent: either, both or neither may be on. They are separate `CoreConfig` fields, and
they share exactly one setting — `deadman_action`, because *what a trip does* is the same question
for both and a second key would be a second answer to it. Both are folded from `policy.toml` by
`crates/vike-tradehub/src/tradehub_cli.rs`'s `live_mount_with` and by nothing else: the daemon's own
paper rehearsal arm constructs neither, and neither does `vike-desktop` or
`crates/vike-run/src/bin/ibkr_mount.rs`.

## The connection dead-man [#the-connection-dead-man]

The signal is the per-(venue, symbol) `FeedStatus` the bridges disclose. It reaches the core through
two seams that the latch cannot tell apart: a feed that owns a `LiveDataSink` maps the data layer's
`StreamStatus` 1:1 by `crates/vike-core/src/core_sink.rs`'s `stream_status`, and a feed that owns no
sink — the HFT tick pumps, which take a bare `vike_exec::TickSender` — pushes a `FeedStatus` onto
the tick lane directly, through the one map in
`crates/vike-bridge-core/src/stream_health.rs`'s `HealthEvent::feed_status`. Both land on the same
`Ingest::StreamStatus` arm. `Disconnected` opens a grace window for that key; `Live` for the same
key closes it and re-arms the link; and `Stale` **never counts, in either direction**. That last line is the entire difference between this
switch and the one below. `Stale` means "no fresh price exists", which is an accurate disclosure of
a weekend on an FX venue and of a scheduled venue maintenance window — reacting to it would be the
silence switch wearing a new name.

A `Disconnected` opens the window whether or not that link was ever seen `Live`, and that is a
correction rather than a simplification: no bridge on this roster discloses a `Live` on a first
successful connect — `vike_bridge_core::stream_health`'s `StreamHealth::recover` returns nothing
when no gap is open, so `Live` exists only to *close* one. A gate on a prior `Live` would have made
the switch blind to the first socket death of a mount, which is the outage it exists for. The
startup dial-up is absorbed by the grace instead.

Recovery is disclosed on the **first frame back**, never at connect, and that difference is what
keeps a flapping venue disclosed down. A successful dial proves only that the venue accepted a
TCP+TLS handshake; an inbound frame — data, or a server ping the socket answers — proves the wire
carries traffic again. On a connect-time `Live`, a venue that accepts a connection and drops it in a
loop (a rate-limit ban, a half-dead edge) would emit `Live`/`Gap` on every cycle and reset the grace
window each time, so the switch could never trip on the outage it is most needed for. One
`Disconnected` per outage, for the mirror-image reason: each feed owns **one** `StreamHealth`
(`crates/vike-bridge-core/src/stream_health.rs`) across its whole lifetime, re-dials included, so a
venue that flaps for ten minutes discloses one disconnect and one recovery rather than three hundred.

`crates/vike-core/src/runtime/link_deadman.rs` is a clock-free latch — two fields per link, both
entry points taking an injected `now_ms` — evaluated at the drain-loop boundary on the
[timer wheel](/docs/trader/concepts/timers), on its own `LinkDeadManSweep` cadence of half the grace. An
entry exists only for a link that has actually been disclosed down at least once, and a status
change on an unarmed venue costs one set lookup and no allocation. The per-message fold has no
branch for the feature at all.

<Callout title="The bounds are refused by name, never clamped">
  `crates/vike-config/src/policy.rs` accepts absent, `0`, or `MIN_LINK_DEADMAN_GRACE_MS` (30 000 ms)
  through `MAX_LINK_DEADMAN_GRACE_MS` (3 600 000 ms). The floor is the measured worst *ordinary*
  reconnect across the lanes that report a dead link, which is the L2 depth driver: a bounded 10 s
  dial, a 10 s REST book seed and a 3 s backoff, 23 s end to end. It is the slowest of the three — the
  tick pumps a live `vike-tradehub` mount actually subscribes come in at 21 s and under — so anything
  under the floor makes the switch
  trip on the re-dial that follows an ordinary socket fault, which is the false-trip class the design
  exists to remove. Above the ceiling it is a switch that never fires. A value outside the range is
  rejected at load with the key and the file named, because a grace that was silently raised is a
  grace the operator believes they set and do not have.
</Callout>

## Which venues actually arm [#which-venues-actually-arm]

Arming needs **two** independent facts to be true, and the second one is a fact about your daemon
rather than about the venue.

**One: the venue's row.** `crates/vike-model/src/link_deadman.rs` carries one named row per roster
venue, each read from the emitter it cites, with three dispositions. `Armed` — the venue trades
continuously *and* its bridge discloses a disconnect: **binance, aster, bybit, okx** — each from
two emitters, both on a book socket: the DOM depth feed and the HFT quote/trade/book tick pump —
and **polymarket** (from its primary book feed). `SessionBounded` — the
bridge does disclose one, but the market has sessions and a close has not been observed to read as
`Stale` rather than as a gap: **oanda** and **ig**, off until somebody watches a weekend through.
`Inert` — the bridge hands a gap to the sink nowhere at all, so the switch could not fire even if it
were armed: **hyperliquid, deribit, alpaca, ibkr, ctrader, fxcm, dukascopy**. Each unarmed row
carries its reason verbatim, and the daemon prints it.

**Two: whether this mount subscribes a lane that carries the disclosure.** A row is a statement
about the *adapter*, never a promise about a *mount*. `crates/vike-tradehub/src/tradehub_cli.rs`'s
`mount_link_disclosure` is the reading, one arm per venue plan, and for a CEX venue the answer is
`Discloses`. That it is an answer at all is recent, and the history is the point: the daemon's
`VenuePlan::Cex` arm subscribes the kline lane and the quote/trade/book tick pump and deliberately
never `subscribe_depth` (`crates/vike-tradehub/src/feeds.rs`), and until 2026-09-06 neither of those
two lanes disclosed anything — the kline lane rides `vike_bridge_core::market_pump`, which carries
no link state at all, and the tick pump owns no `LiveDataSink`. The pump now discloses **its own
transport state onto the core tick lane it already writes ticks to**: `disclose_link` in
`crates/bridges/binance/src/family/depth.rs`'s `md_main`, and its twins in
`crates/bridges/bybit/src/market_data.rs` and `crates/bridges/okx/src/market_data.rs`.

Subscribing the DOM feed instead was the other way to close it, and it was rejected: that pump
already carries the venue's `@depth`-class book stream on the same host, so `subscribe_depth` would
open a second socket to the same stream, keep a second copy of the same book and add a periodic REST
re-seed — for a signal the first socket already has, delivered into `l2_snapshot`, which is a no-op
in every sink this daemon owns. The disclosure costs zero extra bytes on the wire this way, and the
core's per-message fold is unchanged: nothing new rides the tick, quote, trade, bar or book path,
only the occasional control event that was already there.

<Callout title="A default vike-tradehub daemon now arms four venues">
  Fold the two together. **binance, bybit, okx and aster arm on a default live mount**: the tick pump
  is the lane that mount subscribes, and it is the venue's book socket rather than a side channel.
  **Polymarket is a fifth, behind its Cargo feature** — its `subscribe_book` on every seated token
  feeds a `MakerSink` that forwards `stream_status`. Every session-bounded venue — the FX and equities
  mounts — stays off deliberately, because a market closing is not an outage: until a weekend has been
  watched through and seen to disclose `Stale` rather than a gap, the conservative row holds. Every
  `Inert` venue stays off because nothing in its bridge would reach the latch.

  **No row flipped direction.** This was a change of *reach*, not of classification: those four were
  always `Armed` in the venue table, and the mount simply could not hear them — so
  `link_deadman_config_from_policy` returned `None` and built no latch at all on the binary that signs
  real orders, whatever `policy.toml` said. A daemon mounting only session-bounded or `Inert` venues
  is still that case, and it is the ordinary state of an FX-only daemon: no latch, no timer, no
  cadence contributed, and no automatic stop for a dead link. Nothing in `policy.toml` changes which
  venues arm — that is a property of the bridge and of the lanes this mount subscribes.

  The mount says which it is rather than leaving it to be discovered: `link_deadman_arming_report`
  emits **one
  line per mounted venue** at startup, and it keeps apart the four ways a venue ends up unarmed — its
  market has sessions, its bridge discloses nothing, *this daemon subscribes no lane that carries it*,
  or the operator wrote `0`. Read those lines; they describe your daemon and this page does not. The
  mount-lane case is checked before the armed line is printed, which is the whole of the fix: an
  earlier version logged `LINK DEAD-MAN ARMED for binance` on a daemon where nothing could ever reach
  the latch.
</Callout>

## What an operator does about it [#what-an-operator-does-about-it]

There is no line that arms the connection switch, because leaving the key out arms it. The lines
that exist are the ones that change it:

```toml
# <project>/settings/policy.toml
link_deadman_grace_ms = 45000   # a tighter grace; legal range 30000..=3600000
link_deadman_grace_ms = 0       # OFF, for every venue — the only off
deadman_action = "cancel_all"   # a trip pulls the book and leaves the trading state alone
```

Neither key can be reached from the environment or the command line:
[`Policy`](/docs/trader/reference/settings/policy) implements neither `EnvOverride` nor `CliOverride` and
both traits are sealed, so an override is a compile error rather than a review comment. A stale
service-unit line cannot disarm a kill switch with no diff to review.

What this file cannot do is arm a venue. The row is a property of the bridge and of the mount, not a
preference: a venue whose feed hands the core no disconnect has nothing to observe, and a venue
whose only emitter is a lane this daemon does not subscribe has nothing to observe *here*. Both are
code changes, and the startup lines name which of the two you are looking at.

## The silence dead-man, and the morning it was default-on [#the-silence-dead-man-and-the-morning-it-was-default-on]

The older switch is `crates/vike-core/src/runtime/deadman.rs`: a four-field latch, deliberately
clock-free, whose `observe` records a monotonic maximum over every liveness message — venue events
and market data, never control or waker messages — so an out-of-order older frame cannot drag
freshness backward. `check` returns the action exactly once when the newest observed timestamp has
aged *strictly* past the threshold (`now − newest > timeout`; a lag equal to the timeout is still
fresh) and the switch has not already tripped this outage; fresh data clears the latch and re-arms
it. A core that has seen no data never trips, so pre-feed startup is silent rather than a nuisance.

<Callout type="warn" title="It shipped armed for one morning, and a closed market is what reversed it">
  The key shipped with a compiled-in 60 s default — armed unless an operator wrote `0` — and the
  ruling was reversed the same day, once review established what the switch actually observes. It
  counts ingest and deliberately nothing else: not a control command, not the periodic waker, and not
  the one message that says a socket is alive. A transport heartbeat never reaches the core at all. So
  it cannot tell a dead socket from a quiet market or a closed one, and an armed default bought three
  halts nobody asked for. **The session-close halt**, deterministic: on FX over the weekend and on
  equities every evening it trips about a minute after the last tick, at every close — cancelling a
  GTC deliberately left over the weekend, halting every engine, writing the sentinel, and opening the
  next session halted until an operator deletes the file. **The thin-market halt**, probabilistic: a
  live mount following one illiquid instrument goes sixty seconds without a tick in a quiet minute.
  And **the cap that could not be raised past the close**: the maximum timeout is one day and an FX
  weekend is about 48 hours, so the only legal settings on an FX venue were `0` or a switch that trips
  every Friday. `crates/vike-config/src/policy.rs`'s `Policy::deadman_timeout_ms` carries the record.
  The safety argument was right; the mechanism was the wrong one for it, and the connection switch
  above is the one it wanted.
</Callout>

So this key is now the **optional extra for a 24/7 mount** — a crypto perp venue that never closes
and always ticks — that also wants a silence detector. Absent is off; and because the daemon cannot
tell "the operator decided against it" from "the operator never heard of it", an absent key warns
once at mount. `deadman_timeout_ms = 0` is the only spelling that records the decision and silences
that warning:

```toml
# <project>/settings/policy.toml
deadman_timeout_ms = 60000   # arm it — the recommendation for a venue that never closes
deadman_timeout_ms = 0       # a deliberate no, and the only thing that silences the warning
```

Nothing arms it silently: 60 000 ms is `RECOMMENDED_DEADMAN_TIMEOUT_MS`, the number the warning
suggests, not one any binary applies. Accepted values are absent, `0`, or 1 000 ms through one day,
rejected by name rather than clamped for the same reason as the sibling's bounds. Raise it for a
thin symbol; leave it off on anything that closes.

## What a trip does [#what-a-trip-does]

Both switches act at the drain-loop boundary on the [timer wheel](/docs/trader/concepts/timers), never on
the per-message fold, each on its own cadence of half its window — so a deadline is evaluated at
least twice before it expires. `crates/vike-core/src/runtime/watchdog.rs` holds both acting halves,
`sweep_deadman` and `sweep_link_deadman`. On trip each one:

1. emits one `tracing::warn!` per outage or dead link — a fault transition, within the logging
   budget;
2. cancels through the one order-write vocabulary, `apply_intent` with `OrderIntent::MassCancel`, so
   nothing bypasses mint, route or gate — and that verb also clears every armed
   [conditional book](/docs/trader/concepts/emulated-orders), because a dead-man pulls all exposure. The
   cancel is tagged `CancelIntent::RiskOff`: a cancel issued because the market was lost must not be
   shed by a venue's own cancel budget;
3. under `DeadManAction::CancelAllAndHalt` — the default `deadman_action` — halts every engine
   in-process and then writes the sentinel best-effort, a failed write logged rather than panicking
   the core, since the in-process gate has already stopped new orders;
4. pushes a line into the recent-events ring and marks the snapshot dirty.

The **scope** is where they differ. The silence switch cancels with `venue: None, symbol: None` —
everything. The connection switch scopes the cancel to the venue whose link died, across **every
engine of that exchange**, so a two-account binance mount has both books pulled and a bybit socket
death leaves the binance book resting. One cancel pass per venue rather than per link: two symbols
of one venue expiring in the same sweep are one exchange fact.

HALT is the exception to that scoping and is deliberately process-wide, because the sentinel is one
file by construction and a half-halted daemon is a state nobody asked for. It is the *same* file a
manual `touch HALT` writes and every venue's submit boundary checks — the path is supplied by the
binary through `vike_bridge_core::halt::halt_path_from_env`, because environment reads stay in
binaries and `vike-core` takes no bridge dependency — so the automatic trip and an operator's hand
reach one file. A recovered link re-arms its own latch for the next outage; `Halted` and the
sentinel do **not** clear, which is an operator's decision.

<Callout type="warn" title="It cancels; it does not flatten">
  A trip pulls resting orders and, at most, halts. It never sends a closing order, so a position open
  when the link died is still open after the trip. Getting out is the operator's `market-exit`, usable
  from a halted core precisely because a flatten leg is the position-covered reduce the halt admits —
  see [halt](/docs/trader/concepts/halt). And because the halt is engaged, the strategy cannot re-open risk
  when data returns until the operator clears it.
</Callout>

## What it costs replay [#what-it-costs-replay]

The boundary waker message is journaled only when a wall-clock sweep that mutates order state can
ride it, and there are now three such sweeps: the stuck-order [watchdog](/docs/trader/concepts/watchdog)
and both dead-man switches. That waker record is what makes `replay_from` return `Unsupported` for
the session: a trip is a wall-clock effect the journal cannot re-derive. A core with none of the
three on writes no waker record and replays normally; the rule is on the
[replay](/docs/trader/concepts/journal/replay) page.

In practice a live mount has already forfeited replay before either key is read — `live_mount_with`
sets a 30 s submit-acknowledgement timeout, which arms the same record — so arming either switch
forfeits nothing further. It is the paper and harness cores, which set no such timeout, where the
distinction is live.

Both switches are among the mechanisms that reach `Halted` on their own — the fold panic's
safe-state entry is another — which is why the halt policy has no mode that refuses a reducing
order: a switch that trips and then traps the operator in the position it just exposed would be
worse than no switch.


# Emulated orders (/docs/trader/concepts/emulated-orders)



`crates/vike-core/src/emulator.rs`'s `ConditionalBook` is the core-side emulation of
conditional orders — a fixed stop or a trailing stop — for venues, or strategies, without
native support. It is a port of the Python platform's conditional book, and its trigger
predicate is `vike_model::order_fill_price`, the same parity-pinned oracle the backtest engine
fires on, so an emulated stop triggers by exactly the law the
[backtest](/docs/trader/backtesting/fill-resolution) applies. This page is written from that module,
the `OrderIntent` arms in `crates/vike-exec/src/lanes.rs`, and the firing sites in
`crates/vike-core/src/runtime/strategy_drive.rs`.

## Arm, fire, disarm [#arm-fire-disarm]

Registration bypasses the gate; the fire goes through the one live path. `OrderIntent::
ArmConditional` carries a `ConditionalIntent` — venue, symbol, side, quantity, and either
`price` for a fixed stop trigger or `trail` for a trailing distance, whose extreme seeds from
the current mark at apply time and is refused into the recent-events ring when no mark exists.
The runtime mints an `arm_id` and inserts the arm; the book is keyed by that id, so a duplicate
is refused with the book unchanged and the resting arm is never silently replaced. Live ids
come from a monotone counter and cannot collide; the keying is the structural backstop.

When a check fires, each `FiredConditional` — arm id, side, quantity and the oracle's trigger
price, diagnostic only since the live fill is the venue's — is released by
`CoreThread::submit_fired` as a plain market request through `apply_intent`, so mint,
`RiskGate` and client stay structural on the release; a veto surfaces as `OrderDenied`.
`OrderIntent::DisarmConditional { arm_id }` drops exactly that arm; an unknown or stale id is a
loud no-op surfaced to recent-events, never a panic and never silent. Like arming, a disarm
bypasses the gate — removing a resting emulated arm is not an order reaching a venue.
`OrderIntent::MassCancel` with no venue and no symbol clears every conditional book along with
every resting order.

## The trigger law [#the-trigger-law]

A fixed stop fires when a bar crosses its price, under the gap-open adverse fill law: a bar
that gaps down through a sell-stop fills at the worse open, not the trigger. A trailing stop's
extreme ratchets in place on a no-fire bar, exactly as in the Python book and the backtest, and
the check runs against the *prior* extreme's trigger before ratcheting — so a new-high bar
cannot stop itself out. Fired arms are removed and returned; survivors keep their ratcheted
extremes. Walk and fire order is the book's insertion order, and a disarm in the middle does not
reorder the survivors (`shift_remove`, never `swap_remove`).

## Which price series fires it [#which-price-series-fires-it]

Each arm carries the `vike_model::TriggerBy` it was requested with, and every check names the
`PriceLane` its price came from; the two meet in `ArmedConditional::evaluates_on`. The type
exists because an unmodelled trigger source was a live-versus-backtest divergence: with last at
99 and mark at 101, a stop at 100 fires on a mark-triggering venue and on no last-triggering
one, and no emulator could reproduce the timing.

* `None` or `Last` arms evaluate on trade and bar prices — today's law, byte-identical.
  `check_bar` runs against every closed bar of the mount's series, *before* the strategy step,
  which is the oracle's firing order. With `CoreConfig::conditionals_on_ticks` (default
  `false`, oracle-faithful bar-close only) the book is also checked against each tick of the
  engine's series through a degenerate one-price bar — the intra-bar triggering the Python book
  explicitly lacks.
* `Mark` arms evaluate only on the mark lane. `check_mark` is fed from the conflated mark drain
  and is always on when a mark arm rests — deliberately not behind `conditionals_on_ticks`,
  because the mark lane has no bar-close equivalent and gating it would mean a mark arm could
  never fire. This is what lets the emulator reproduce a mark-triggering venue's timing. The
  no-mark-arm path costs one integer compare per conflated tick (`has_mark_arms`).
* `Index` matches no lane: the core has no index lane, so the runtime refuses such an arm at
  apply time, and one smuggled in anyway — a hand-edited journal — rests inert rather than
  firing off the wrong series.

Arms on the other lane are untouched by a check: not fired, not ratcheted — their price series
simply did not tick.

<Callout type="warn" title="The fire is journaled, or replay cannot reproduce it">
  A fire is a runtime reaction to a bar or tick, and market data is never journaled — so before
  the write-ahead `ConditionalFire` record existed, replay re-folded a fired session without its
  release and the determinism fence caught it as a hash mismatch. `submit_fired` now writes the
  decision, not the tick behind it, before `apply_intent`, with the request's client order id
  still empty; replay re-applies the recorded request through the same path and never
  re-evaluates a trigger, so a fire can neither double nor vanish. Arm and disarm are journaled
  the same way, and a restart re-arms the book exactly as it rested — a trailing arm's ratcheted
  extreme included — from the journal's `Snap`. See [replay](/docs/trader/concepts/journal/replay).
</Callout>

## Whose account fires [#whose-account-fires]

`conditional_books` is keyed by `(venue, symbol)` — an exchange fact — so two accounts of one
venue arm into one book and a fired conditional names no account. The runtime records which
engine armed each id and routes the release to that engine by index; lowering by the payload's
venue string once resolved the venue's default account, so a labelled mount's protective stop
sold into the default account's book and opened a naked position while the one it was armed to
close stayed open. A book seeded from a restored `Snap` carries no route key and keeps the
payload route — the declared residual on that field. Multi-account mounts are the
[accounts](/docs/trader/concepts/accounts) page's subject.

## What it is not [#what-it-is-not]

A venue that supports conditional orders natively receives the `trigger_price` and `TriggerBy`
on the [order request](/docs/trader/concepts/orders/) itself, and an adapter that cannot express the
requested source on its wire must synthesize a terminal `OrderRejected` rather than silently
substitute a different series. Bracket exits held off the venue until their entry fills are a
different mechanism — the [contingency](/docs/trader/concepts/contingency) page's OTO/OCO resolver.


# The event bus (/docs/trader/concepts/event-bus)



Every venue event the [execution core](/docs/trader/concepts/execution-core) folds passes through one
queue: `crates/vike-exec/src/bus.rs`'s `EventBus`. It is small, and its header states the one
property that makes it more than a `VecDeque`: **defer-and-deliver**. A publish appends to the
back of the FIFO; if a drain is already running the call returns and the event waits its turn;
otherwise the call drains, delivering each event in full before the next one starts. The ordering
is load-bearing rather than tidy — the example the header gives is a one-cancels-other bracket,
where the auto-cancel publishes `OrderCanceled` *while* `OrderFilled` is being delivered, and the
cancel must land after every subscriber has seen the fill.

## One writer, one outbox [#one-writer-one-outbox]

The single-writer core owns both the bus and its handler, so callback re-entrancy is impossible by
construction. Instead of publishing back into the bus mid-fold, a handler pushes follow-on events
into an `Outbox`, and the drain loop appends that outbox to the back of the same FIFO after the
fold returns. Follow-ons are therefore delivered after every already-queued event and never
recursively — byte-identical delivery order to the original semantics, and clean under the borrow
checker. The `draining` latch is kept as an explicit field even though the single-writer core can
never set it re-entrantly; the parity test's chained publisher exercises it, and the semantics stay
written down.

`EventHandler` is the bus's one subscriber type, and `ExecutionEngine` is the handler: its `on_event`
folds the venue stream through the order state machine and the [account](/docs/trader/concepts/account),
and — as `crates/vike-exec/src/execution_engine/mod.rs`'s header says — it *folds state only*;
durable persistence belongs to the runtime's [journal](/docs/trader/concepts/journal/index). Every
delivered event is also appended to the bus's `delivered` log, which the runtime takes each batch
and folds into its bounded recent-events ring — the seam the desktop app's event echo reads through
a lossy observer channel, and the seam the fixtures assert delivery order against.

## The fold reports a verdict [#the-fold-reports-a-verdict]

`on_event` returns a `Fold`: `Applied` when the event actually changed state, `Dropped` when the
handler refused it — an unknown client-order-id, an illegal transition in the
[order lifecycle](/docs/trader/concepts/order-lifecycle), a reconnect replay, an event for a symbol or
venue this engine does not own, or a non-finite venue number. "Invalid transitions are dropped" is
a core law of the order management system, and the `Fold` doc records why the verdict had to become
visible: before it existed `on_event` returned nothing, so a downstream reaction keyed off the
*event* rather than off the fold's acceptance of it, and fired for events the engine had refused.
The live one-triggers-other / one-cancels-other drive was exactly that — a fabricated `OrderFilled`
on an unknown client-order-id cancelled its sibling and armed its held children even though the
engine had dropped the event and counted it into `dropped_unknown_coid`.

`publish` returns the verdict for **the event it was handed**. Follow-on events drained by the same
call carry their own verdicts, which are not reported: no caller reacts to them, and the site that
published them is the one that would. `crates/vike-core/src/runtime/mod.rs`'s `dispatch` names the
consumer this exists for — the [contingency](/docs/trader/concepts/contingency) drive on the venue
ingest lane is gated on the fold's verdict, because without that gate a fabricated fill on one
bracket leg cancels its sibling and leaves a position naked. The in-process client seam is
deliberately *not* gated.

<Callout type="warn" title="The deferred branch answers Applied, and it is not for you">
  When `publish` finds a drain already running it returns `Fold::Applied` without knowing anything.
  That branch is structurally unreachable in the single-writer core — `draining` can only be set by a
  `publish` higher in the same call stack, and the engine publishes into its outbox rather than back
  into the bus — so it exists only for the parity test's chained publisher, and answering `Applied`
  there keeps that path byte-identical to its pre-verdict behaviour; answering `Dropped` would invent
  a new way to orphan a legitimate bracket on a path nobody exercises. A caller that genuinely needs
  the verdict of a deferred event must not use this seam.
</Callout>

## What a panic mid-fold does [#what-a-panic-mid-fold-does]

The drain is unwind-safe in the way a `try/finally` would be: a drop guard clears the `draining`
latch on the way out, so after the runtime's `catch_unwind` the next publish drains normally, with
every undelivered event still queued in order. The `publish` doc records the review finding that
put it there — without the guard, one in-drain panic would silently defer every later event
forever.

The same guard does a second job. The event being folded is held in an `in_flight` slot during
`on_event`; a clean return moves it into `delivered`, so anything still in the slot when the guard
drops was lost to a panic, and the guard pushes it into a `poisoned` list instead of letting it go.
The runtime drains `take_poisoned` after its `catch_unwind` fires and surfaces each as a lost
terminal in the recent-events ring, so a panic can never silently strand an order — the test
`panic_mid_fold_salvages_the_in_flight_event` pins that the salvaged event is recorded exactly once
and is *not* re-folded. This is the bus's half of the core's panic policy; the runtime's half is on
the [execution core](/docs/trader/concepts/execution-core) page.

<Callout title="Where the events come from">
  The bus consumes what the [ingest lanes](/docs/trader/concepts/ingest-lanes) deliver — the lossless
  `EventSender` every venue adapter holds pushes canonical events into the core's single ingest
  channel, and the drain loop publishes each one here. The variants themselves, who emits each and
  what the state machine does with it, are one page each under [events](/docs/trader/concepts/events/).
</Callout>


# The ExecutionClient seam (/docs/trader/concepts/execution-client-seam)



Every venue bridge implements one trait: `vike_exec::ExecutionClient`, declared in
`crates/vike-exec/src/execution_engine/client.rs` and isolated from the engine so the contract
reads on its own. The engine holds it type-erased — `Box<dyn ExecutionClient + Send>` — and never
knows which venue is behind it. That is the whole point: the core, the risk gate and the order
state machine are written once, and a venue's job is to translate. Each page under
[venues](/docs/trader/venues/) is one implementation of what this page describes.

## Two methods are required [#two-methods-are-required]

```rust
fn submit(&mut self, request: &OrderRequest);
fn cancel(&mut self, client_order_id: &str);
```

They are the only order-mutating calls that leave the core, and both are fire-and-forget. Neither
returns a result, because the venue's answer does not arrive on this call — it arrives later, as
an event, through the ingest lane the adapter was handed at construction. That is true of every
method on the trait: **every state change comes back as a venue event**, never as a return value.

## Everything else has a default [#everything-else-has-a-default]

| method                          | default behaviour                           | who overrides it, and why                                                                                                                                             |
| ------------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cancel_with_intent`            | drops the `CancelIntent` and calls `cancel` | a venue that meters its cancels. &#x2A;*The engine calls this, never `cancel`**, so an override sees every cancel the core issues                                     |
| `modify`                        | no-op — the order keeps its terms           | a venue with an in-place amend. Takes the whole resting `OrderRequest`, not just its id, because some venues need side, quantity and price together                   |
| `submit_batch` / `cancel_batch` | fan out to the per-order call               | a venue with a native batch endpoint                                                                                                                                  |
| `cancel_batch_with_intent`      | drops the intent and calls `cancel_batch`   | a venue that wants the whole batch, with its intent, as a single unit; Polymarket is the only declaration in the tree, for the latency of an emergency flatten        |
| `confirm`                       | no-op                                       | a venue with an order-status re-query. The stuck-order watchdog is its caller; on a client that cannot re-query, the watchdog's last-resort reject still backstops it |
| `detach`                        | no-op                                       | adapters with something to release                                                                                                                                    |
| `poll_events`                   | `None`                                      | in-process test clients only — a real adapter's events arrive over the ingest channel                                                                                 |
| `on_bar`                        | no-op                                       | the paper exchange, which fills its resting book on each closed bar before the strategy runs                                                                          |
| `amend_semantics`               | `None` — "ask the venue table"              | **the paper exchange only**, see below                                                                                                                                |

Two contracts hide in that table. `confirm` must run its re-query **off** the core fold thread, on
the adapter's own thread — it is the watchdog's way of prodding a wedged adapter into answering
rather than only waiting on it, and a blocking re-query here would stall the fold it exists to
protect. And the boxed impl delegates every method explicitly, because trait-object defaults would
otherwise shadow a concrete client's overrides: a boxed intent-aware client that fell through to a
default would silently report every cancel as unclassified.

### Why a cancel carries an intent [#why-a-cancel-carries-an-intent]

`CancelIntent` is the one cross-venue classification of *why* a cancel is being issued: `Routine`
(maker ladder churn), `RiskOff` (a declared flatten, market exit, dead-man trip or safe-state
sweep), or `Unspecified`. It exists because a venue-side cancel budget is a real liveness hazard —
a maker that spends its whole cancel bucket on requote churn is rate-limit-locked at the moment it
needs to pull a book — and holding a reserve back is only possible if the shedding decision can
tell the two apart.

<Callout type="warn" title="Unspecified is the flatten-safe default, not a don't-care">
  A caller that cannot classify its cancel gets the treatment an emergency gets — fire it, never
  hold it back — because the failure modes are not symmetric: shedding a routine cancel costs one
  stale quote for one refill window, while shedding an emergency one leaves a live order resting in
  the situation the operator was trying to get out of. `CancelIntent::may_be_shed` is the one place
  that says only `Routine` may ever be held back, so a venue never re-derives the rule from a
  `match` and is never one `_ =>` arm from inverting it. A venue that overrides `cancel_with_intent`
  must write `cancel` in terms of it, or a direct `cancel` call silently skips the override.
</Callout>

## Where the adapter runs [#where-the-adapter-runs]

The trait is synchronous and the venue is not, so an adapter owns a thread. The shared shape is
`crates/vike-bridge-core/src/exec_actor.rs`'s `ExecActor`: an mpsc channel plus a dedicated OS
thread draining submit, cancel and shutdown, with a `Drop`/`detach` that sends shutdown and joins
the thread — deterministic teardown, because a stranded feed thread is a crash on process exit.
Each venue supplies only its command loop, and for the REST-driven crypto venues even that loop is
shared. Venue replies are pushed back to the core with `EventSender::blocking_send`. Dukascopy is
the one adapter that owns a child process instead — there is no REST execution API for that venue,
so a Java sidecar drives execution over JSON lines on stdio. In both cases the core thread never
waits on the wire.

The actor is also where the operator [halt](/docs/trader/concepts/halt) bites first: `submit` and
`modify` consult the halt file sentinel before touching the command channel. While it exists, a
submit the caller has not flagged `reduce_only` is refused with a synthesized terminal
`OrderRejected`, and a `reduce_only` submit is admitted — and logged, because this boundary holds
no position book and can only trust the flag. `modify` is blocked either way, since it can add size
or chase price and reduce-only cannot be inferred from the request alone; nothing is synthesized
there, the resting order simply keeps its terms. A cancel is deliberately never gated, and a cancel
alone would not discharge the rule: it removes a resting *order*, whereas leaving a *position*
means sending one, so a halt must let an operator reduce or exit, never trap a position. It works
even when the runtime is wedged.

## The emitter split [#the-emitter-split]

Who emits which event is fixed, not a per-venue choice. The Rust side emits `OrderSubmitted`
synchronously at submit. The venue side emits `OrderAccepted`, `OrderRejected`, `OrderCanceled`,
`OrderFilled` and `OrderPartiallyFilled`. A dead venue path — a transport that died mid-order, a
sidecar that never answered — must synthesize a terminal `OrderRejected` rather than let the order
vanish. The [order lifecycle](/docs/trader/concepts/order-lifecycle) page carries the three rules and
the harness that machine-checks them against every venue's real decoder.

## The one method a venue adapter should never override [#the-one-method-a-venue-adapter-should-never-override]

`amend_semantics` answers "what does *my* `modify`'s quantity mean" — the new total, or the new
remaining size — which is the fact `ExecutionEngine::modify_order` needs before it may net a
partially filled order's executed lots out of the pre-trade projection. `None` means "consult
`vike_model::amend_semantics` for the engine's venue string", which is the right answer for every
real venue, because that table is where the per-venue fact is declared and tested.

It exists because the engine's venue string is a **label**, not a client. `vike_mount::make_engine`
builds the engine with the real venue id even when the arming ceiling or the absent-credentials
gate fell back to `vike_paper::PaperExecutionClient`, so a paper mount on a venue whose amend is
in-place-total looks up that row while the paper book's `modify` assigns the amend quantity to the
order's **remaining** size — netting there would let the gate assume `q − filled` while the book
executes `q`. Declaring the convention on the client means it travels with the object that
implements it and no mount can forget to pass it. The
[paper exchange](/docs/trader/concepts/paper-exchange) is therefore the only override in the tree, and
the method's own documentation says so.


# The execution core (/docs/trader/concepts/execution-core)



`vike-core` is the live core. One dedicated OS thread — `vt-core` — owns the `ExecutionEngine`
(account, order registry, risk gate, venue client) and is the **only** mutator of any of it.
Everything else in the process reaches that state through one ingest queue, totally ordered, and
reads it back through an immutable snapshot. The authority for this page is
`crates/vike-core/src/runtime/mod.rs`, whose own header calls this the pinned architecture.

## Three lanes into one queue [#three-lanes-into-one-queue]

Three kinds of message arrive, and each has a different contract with its producer:

* **Exec events** — fills, order transitions, account and funding updates, liquidations — are
  lossless. A venue adapter pushes them with `blocking_send`, so a slow core back-pressures the
  venue task and never the GUI.
* **Commands** from the GUI or a control surface use `try_send` into the same queue. The GUI
  thread never blocks. A full-queue rejection comes back to the caller as `CommandRejected::Busy`
  *and* is counted in the snapshot as `rejected_commands`, so it cannot be silent;
  `CommandRejected::Gone` means the core thread has exited.
* **Market data** goes through a latest-wins conflation slot plus a marker message. The producer
  overwrites the slot (a drop counter is surfaced) and at most one marker is ever in flight, so a
  slow core sees the freshest price without unbounded queueing.

On the core side the thread sits in `blocking_recv()` — there is no tokio runtime on the hot
thread — then drains opportunistically with a `try_recv` batch bounded by `CoreConfig::batch_max`
before publishing, which keeps latency bounded. The producer-side types for all three lanes live in
`crates/vike-exec/src/lanes.rs`, not in `vike-core`, so that a venue bridge depends on `vike-exec`
and never on the core above it; the [ingest lanes](/docs/trader/concepts/ingest-lanes) page is theirs.

## The snapshot is a lossy observer [#the-snapshot-is-a-lossy-observer]

The core publishes a `CoreSnapshot` into an `arc_swap` cell that the GUI reads on repaint. Publish
is dirty-flagged and coalesced: at least every `CoreConfig::snapshot_interval` while busy (about
16 ms by default — the one number on this page that is a live constant, held to the code by
`crates/vike-ops/tests/docs_constants_gate.rs`), and immediately when the queue goes idle. The
build never runs per-event *while busy*.

<Callout type="warn" title="On a quiet venue, publish is per-event work">
  The idle-path publish is ungated by the interval. On a venue whose events arrive sporadically the
  core is idle between them, so it publishes after every one. Anything `CoreSnapshot::build` does is
  therefore per-event work, not per-interval work — which is why deferring a render "to publish
  time" once turned out to be a pessimization rather than a saving: it relocated the work instead of
  avoiding it (p99 2039 ns deferred, against 606 ns rendered at push and a 481 ns baseline).
</Callout>

## The fold is latency-gated [#the-fold-is-latency-gated]

The drain loop is the thread the core-hop tail gate measures —
`crates/vike-core/tests/runtime_latency.rs`, run in CI on a runner whose cores are reserved for
it. Every ceiling in that file is a derived constant with its data on it, and only three of its
harnesses gate (`baseline`, `journal`, `journal-snap`); the rest measure, asserting no timing
beyond the snapshot build's pre-existing 1 ms sanity check, because calibrating one ceiling there
cost 98 CI attempts and an uncalibrated ceiling is a flaky gate, which teaches people to re-run
rather than read. The
[latency gate](/docs/trader/concepts/latency-gate) page is where a number is read.

Two consequences follow for anyone touching the core. Nothing on the fold path may log
per-message — instrument per-order boundaries and fault transitions only. And everything that can
run off the fold belongs in `vike-ops`, which exists to consume the published snapshot, event and
journal streams without ever sitting in this loop.

## What happens when a handler panics [#what-happens-when-a-handler-panics]

Every dispatch runs under `catch_unwind`. On a panic the core does **not** die and does **not**
keep trading. It enters safe-state: `trading_state` becomes `Halted`, so the risk gate denies
every new order; a best-effort cancel is issued for every non-terminal working order; and the
fault is surfaced in the snapshot. A possibly-inconsistent engine is never traded on again — only
read for display — until the process restarts, which is what makes wrapping it in
`AssertUnwindSafe` sound.

## The drain-loop boundary [#the-drain-loop-boundary]

Cold-path work does not ride the per-message dispatch. It is armed on a `DeadlineTimerWheel` and
runs at the boundary of a drain, and `runtime/mod.rs`'s `TimerKind` is the list of what may fire
there: the stuck-order watchdog sweep, the equity sampler, the periodic strategy-state save, the
two dead-man's-switch sweeps — one per switch, each on its own window — managed good-till-date
expiry, the periodic portfolio journal record, and the fast in-flight confirm — the reject-free
early rung of the stuck-order ladder, which only re-queries and never terminalizes. Every one is
opt-in through `CoreConfig`, and when none is configured the wheel stays empty and the boundary
advance is skipped. The [timers](/docs/trader/concepts/timers), [watchdog](/docs/trader/concepts/watchdog) and
[dead-man's switches](/docs/trader/concepts/dead-mans-switch) pages carry each.

Two more pieces sit around the loop. `JournalConfig` is the opt-in write-ahead command journal:
`None` — the default — opens nothing and leaves the fold path byte-identical, while `Some`
journals every exec-lane message before it folds, with the segment, flush and snapshot cadence the
`[sinks.journal]` profile section uses. And the live strategy mount is the path through which a
`Strategy` drives a `LiveBroker` — the same mount whether the venue behind it is paper or live.
Each has its own pages; this one is only the thread they all hand their work to, and the
[portfolio and snapshot](/docs/trader/concepts/portfolio-and-snapshot) page is what comes out the other
side.


# Halt (/docs/trader/concepts/halt)



A halt in Vike Trader is a file. While the sentinel exists on disk, every submit that would
open or add to a position is refused at the venue adapter's submit boundary. An operator
engages it with `touch <HALT file>` over ssh and the very next submit is refused — no IPC, no
running event loop, no responsive window, only a filesystem `exists()` check at the submit
seam. The sentinel is owned by `crates/vike-bridge-core/src/halt.rs`; the *decision* about what
a halt lets out is `crates/vike-exec/src/halt.rs`'s `halt_admits_submit`; the policy is
`crates/vike-model/src/halt_admit.rs`. This page is written from those three.

## Where the file is [#where-the-file-is]

The path resolves in three rungs: `VIKE_HALT_FILE` when set to a non-blank value; otherwise
`<project>/settings/state/HALT`, the one directory this workspace writes program-owned state
into, with *which* project taken from the composition root's own boot walk so a deployment that
names its settings directory moves the sentinel with it; and, only when no project resolves at
all, `<exe_dir>/HALT`. The resolution is probed once per process at mount time by
`halt_path_arming_error` — `error` when an operator could not create the file, `info` when
they could — because a kill switch that is not armed looks exactly like one that is, right up
until it is needed. Rung 3 is reported as a `warn` carrying `EXE_DIR_FALLBACK_ADVISORY`: in a
container the binary lives in the image while `<project>` is a bind mount, so a sentinel beside
the binary is armable and an operator touching the project's file on the host arms one this
process never reads.

## What an engaged halt lets out [#what-an-engaged-halt-lets-out]

* **A submit that opens or adds is blocked.** A terminal `OrderRejected` is synthesized through
  the normal event path with the exact reason `HALT_REJECT_REASON` = `halted: HALT file
  present`, so the intent never silently vanishes.
* **A submit that reduces is admitted.** Under the default policy the whole rule is
  `request.reduce_only`.
* **Cancel is always allowed.**
* **Modify is blocked** on every client: a modify can add size or chase price, and reduce-only
  cannot be inferred from the request alone. The exit path under halt is a cancel or a reducing
  submit, so blocking modify traps nobody.

The reducing arm exists because a cancel is not an exit. A cancel removes a resting *order*;
leaving a *position* requires sending one. `OrderIntent::Flatten` mints a `reduce_only` market
order for `|position|`, and until the exemption existed `market-exit` under a HALT file ran its
mass-cancel and then had every flatten leg rejected, leaving the operator halted with the
position still open. The promise the module doc states first is *halting cannot trap you*, and
it outranks *halting is airtight*.

`halt_admits_submit` is one shared function rather than an `if` in each client because several
independent implementations enforce the sentinel — the shared `ExecActor`, hyperliquid's
bespoke client and `vike_paper::PaperExecutionClient` — and the original pair had already
drifted once (both blocked `submit`, only one blocked `submit_batch`). It lives in `vike-exec`
because the paper client must refuse under a halt for the same reason a live one does — an
operator rehearses the switch on a paper daemon — and `vike-paper` may not grow a transport
dependency to reach it.

## Two mechanisms, one policy, different verification [#two-mechanisms-one-policy-different-verification]

The in-process twin is `vike_exec::RiskGate` under `TradingState::Halted`. It holds the
position book, so it admits only a *position-verified* reduce —
`crates/vike-model/src/scalar.rs`'s `is_covered_reduce`: the order must oppose a non-zero
position and be covered by it (`|position| >= |qty|`), or carry the flag *and* satisfy both
direction and coverage. A flat-book `reduce_only` order is an opening order there. The adapter
boundary holds no book — a command channel, an event lane and a sentinel path — so the
caller-asserted flag is the only evidence in existence, and `halt_admits_submit` takes it.

<Callout type="warn" title="The honest residual">
  A strategy bug that tags its entries `reduce_only` can open risk through a HALT file on a flat
  book, and nothing anywhere catches that. Three things bound it: every submit reaching the
  boundary was minted by the core and has already passed the `RiskGate`; the gate's own
  `Reducing` state trusts the same bare flag; and real perp venues reject a `reduce_only` order
  that would increase a position — but only where a position exists to check against. The
  admission is logged on every occurrence for exactly that reason.
</Callout>

## The `halt_admit` policy [#the-halt_admit-policy]

`policy.toml`'s `halt_admit` key (`vike_config::Policy::halt_admit`, on the
[policy settings](/docs/trader/reference/settings/policy) page) selects a `vike_model::HaltAdmit`
mode. `admit`, the default, is the flag-trusting rule above, byte-identical on every venue with
evidence ignored. `verify` is strictly tighter: still `reduce_only`, and additionally refused
when the venue's own position book *proves* the submit opens risk. `halt_admits_submit_under`
weighs a three-state `PositionEvidence` — `Unknown` with its reason, `Flat`, or
`Opposing(qty)` — and refuses only `Flat`. Every absence admits: never fetched, fetch failed,
an answer that could not be read in full or was for another account, socket dropped since,
poisoned lock, unresolvable symbol, and a book holding no position in the symbol at all.
`Opposing` admits at any magnitude, even smaller than the order, because the adapter caps an
oversized reduce and refusing it would deny a genuine partial exit. That `verify` admits only a
subset of what `admit` admits is pinned by `verify_is_a_subset_of_admit_over_every_input`.

`vike_model::halt_verify_support` says where `verify` is real. One venue answers `Real` today —
cTrader, the only adapter holding a position book at its halt boundary — and every other
roster venue degrades to `admit` with a written reason, reported once at mount by
`vike_mount::make_engine`; a cTrader mount that fell back to paper says so too, since the paper
client holds no book either. cTrader *extends* the predicate as `closes || admits`: a book is
evidence for a reduce and never against one, because it holds nothing until the venue answers a
reconcile, and a restarted daemon can have heard nothing about a position the account holds.

<Callout title="There is deliberately no third mode">
  A `refuse` mode with no exemption was the behaviour until 2026-08-06 and was removed because it
  trapped operators: halting denied `reduce_only` too, so the panic button was disarmed in exactly
  the situations that reach a halt on their own — a fold panic, either
  [dead-man's switch](/docs/trader/concepts/dead-mans-switch). `verify` degrades toward `admit` on
  every unknown, never toward refusal, and an unknown spelling is rejected at load by name.
</Callout>

## What else engages it [#what-else-engages-it]

The file is the manual switch. Its automatic twins are the two
[dead-man's switches](/docs/trader/concepts/dead-mans-switch) — the connection one, armed unless
`policy.toml` writes `link_deadman_grace_ms = 0`, and the silence one, off unless that file arms it.
Either sets `trading_state = Halted` on every engine under the default `cancel_all_and_halt` action
and writes that same HALT file, so this sentinel can appear with nobody having touched anything;
what a trip is scoped to differs, but the halt half is process-wide in both. The connection switch
arms only for a venue whose bridge discloses a dead link on a lane this daemon subscribes, which is
narrower than its default suggests — its own page carries the per-venue reading. The
[watchdog](/docs/trader/concepts/watchdog)'s safe-state entry halts in-process after a fold panic. `OrderIntent::MarketExit` — the panic button — is
usable from a halted core, because a flatten leg is exactly the position-covered reduce the gate
admits; the one leg it still refuses is a position sitting off the lot grid, whose `|position|`
rounds up on the wire and would flip it. The check runs only at the submit and modify boundary,
never per message, so the [latency gate](/docs/trader/concepts/latency-gate) is untouched.


# The history store (/docs/trader/concepts/hist-store)



Every historical series Vike Trader records, backfills or replays goes through one seam:
`HistStore`, in `crates/vike-data/src/hist.rs` — one store for bars *and* ticks. The trait is
always compiled and depends on `vike-model` only; the concrete backend, `DataFusionHist`, is
DataFusion over Parquet behind the `hist-datafusion` feature — no SQLite, no server — partitioned
by UTC day, with compaction, retention and a manifest file-index that also drives reads, so nothing
lists a directory. Ingest is idempotent by **commit key**, never by row value: a key names the
source batch, and a batch already ingested for a series appends nothing, because trades carry no
id and idempotency has to live at the batch level. The same crate owns the
[live mirror of this seam](/docs/trader/concepts/live-data-seam), so a strategy reads bars the same way
whether they came off a socket or off disk.

The authority for the rest of this page is `crates/vike-data/src/store_kind.rs`.

## Thirteen kinds, one declared row each [#thirteen-kinds-one-declared-row-each]

The on-disk layout is a contract between many producers — the live recorder, the backfill
collectors, the journal materializer, a bridge writing a derived series — and three consumer
families: tick replay in the backtester, served reads in the data service, and the inventory views
in Data Manager and Studio. Until `STORE_KINDS` existed no site named that contract; each end
learned it by reading another end, and several shipped defects were exactly a producer and a
consumer disagreeing about the shape — a kind missing from the coverage view while its rows sat on
disk, five Data Manager verbs silently operating on a series that did not exist, a part-name
collision overwriting live parts.

`STORE_KINDS` declares one row per `kind=` naming what both ends must agree on: the domain row
type, the Arrow columns today's writer emits (with the codec flavour that decides nullability and
old-part tolerance), the Parquet schema-metadata key, the partitioning, whether a grouped form
exists, what `venue` and `symbol` actually *mean* for that kind, and the commit-key shapes its
known producers use.

| kind           | grouped form | what it holds                                                                                                                                                             |
| -------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bar`          | no           | OHLCV bars, sub-partitioned by interval — the only kind that is                                                                                                           |
| `quote`        | yes          | top-of-book quotes                                                                                                                                                        |
| `trade`        | yes          | the market print tape                                                                                                                                                     |
| `book`         | yes          | the lossless L2 lane: every delta, snapshot anchors and stream-health markers, `seq` contiguous                                                                           |
| `depth`        | no           | the conflating L2 lane: periodic full snapshots with every intermediate state discarded — a different series on purpose, so a `book` reader never receives conflated data |
| `properties`   | no           | point-in-time `SymbolProperties` grids, about one row per symbol per day                                                                                                  |
| `equity`       | no           | equity-curve samples — `venue` is the fixed namespace `portfolio` and `symbol` is a venue name or the `TOTAL` rollup                                                      |
| `exec_fill`    | no           | the account's own fills, a distinct kind from `trade` so the two never collide                                                                                            |
| `exec_order`   | no           | the account's own orders, as lifecycle snapshots                                                                                                                          |
| `funding`      | no           | the account's realized funding payments, keyed by coin                                                                                                                    |
| `chain`        | no           | option-chain snapshots, hundreds of rows sharing one `ts`                                                                                                                 |
| `cohort`       | no           | a graded positioning panel from a metrics service                                                                                                                         |
| `perp_metrics` | no           | a perpetual's premium, plus open interest where a source supplies it — the narrowest kind in the store                                                                    |

Each kind has its own page under [data](/docs/trader/concepts/data/), generated from this table; what
fills them is the [data providers](/docs/trader/data-providers/) tree.

<Callout type="warn" title="Two disagreements are pinned, not fixed">
  `depth` is listed as groupable by the backfill crate's regroup table and has no grouped form
  anywhere in the store — and no backfill source serves it at all, so a depth gap can only ever be
  re-recorded live. And two unrelated series are both called *funding*: `kind=funding` is the
  **account's** realized payments, while the **market** funding-rate history is a `kind=bar` series
  under the reserved `interval=funding` label. Each is asserted by a test, so whoever resolves one is
  told to update the table rather than leaving a stale warning behind. That is the workspace's
  playbook for any per-thing capability table: declare today's reality first, byte-identical, and
  flip behaviour one row at a time.
</Callout>

## The gate derives the live set from the code [#the-gate-derives-the-live-set-from-the-code]

`crates/vike-data/tests/store_kind_gate.rs` does not trust the table. It derives the set of kinds
the code actually writes three independent ways, because each is blind to a different mistake:
the first argument of every path-helper call in the backend, the `kind` strings each compaction
dispatch accepts, and the `append_*` verbs on the trait. It fails until every derived kind has a
row, then checks each row's columns and schema-metadata key against the codec they were read from.
Adding a kind the ordinary way reddens the trait check first, before anything writes a directory.
Its residuals are declared on the gate rather than implied: it cannot see dataflow, so a literal
reaching a directory through a helper it does not follow is invisible, and every such site carries
a written reason.

## A partition holds many parts [#a-partition-holds-many-parts]

Parts are `date=`-partitioned identically for every kind, and a part never spans a UTC day. That
does **not** mean one file per day: a writer seals one part per commit, the live recorder commits
per buffer flush, and compaction merges the results alongside. Measured read-only on a live tape,
one day's `kind=book` partition held 103 Parquet files and the previous day's 130. A consumer built
for one-file-per-day mishandles the real case, which is why `a_date_partition_holds_many_parts`
pins both halves. One more trap for a reader of old parts: a column with an `_add` flavour may be
absent entirely from a part sealed before it existed, so a consumer must never assume it is
present.

## Where the store lives when nobody said [#where-the-store-lives-when-nobody-said]

`DataFusionHist::open` takes the root it is given and creates it — it has no opinion about where
data belongs. That question is answered one layer up by
`crates/vike-model/src/store_path.rs`'s `resolve_store_root`, the one precedence every binary
resolves through, born from a cleanup that found six stores scattered over three directories on
two disks. From the top: an explicit `--store` or a profile's `store =`; then `$VIKE_HIST_STORE`,
the box's standing answer; then `<project>/market_data/hist` for a project **declared** outright by
`$VIKE_SETTINGS_DIR`; then a developer's existing checkout store, if the checkout that built the
binary still exists; then `<project>/market_data/hist` for a project **discovered** by walking up
from the working directory — the same walk that finds `<project>/settings/`, so settings,
credentials and data can never disagree about which project this is, and the default a fresh
install gets; then a per-user data directory for a binary with no project above it at all. Every
answer comes back with the `StoreRootRung` that chose it, and every binary that resolves through it
logs both before opening anything — a tool handed a root outright, as `vike-study` and `tearsheet`
are by `--store`, opens it with no such line.

<Callout type="warn" title="Nothing validates that a root is the one you meant">
  Point a tool at an empty directory and it creates a fresh, valid, **empty** store; the run then
  reports zero rows, which is indistinguishable from "the backfill found nothing". A store does not
  merge — if the answer moves, the old one is simply no longer read. That is why the resolver never
  invents a path from the working directory, why every rung above the default is something a human
  stated, and why the declared project outranks the checkout hinge: a declaration must not lose to
  an inference. Under `systemd`'s `ProtectSystem=strict` a root outside `ReadWritePaths=` fails at
  open, and the error is decorated with those two words — a diagnosis, deliberately not a pre-flight
  probe.
</Callout>


# Concepts (/docs/trader/concepts)



The getting-started pages get you to a first backtest and a first paper mount without explaining
why anything is shaped the way it is. This section is the explanation. Every page states a
mechanism, names the code that is the authority for it, and says which test holds the invariant —
because on this platform most of the rules below are gates in CI rather than sentences in a
document, and a page that could not cite its claim was not written.

## Reading order [#reading-order]

The first eight pages build on each other and are best read in order:

1. [Architecture](/docs/trader/concepts/architecture) — a workspace whose dependency direction is
   machine-checked, and the one startup sequence every binary runs.
2. [The execution core](/docs/trader/concepts/execution-core) — one thread owns all mutable trading
   state; everything reaches it through one ordered queue.
3. [The ExecutionClient seam](/docs/trader/concepts/execution-client-seam) — the single trait a venue
   bridge implements, and which of its methods are actually required.
4. [Order lifecycle](/docs/trader/concepts/order-lifecycle) — the state machine every order folds
   through, and the three rules a venue may not break.
5. [Risk and arming](/docs/trader/concepts/risk-and-arming) — the arming ceiling read before any
   credential, the credential gate behind it, the pre-trade gate on every order, and the halt.
6. [The data model](/docs/trader/concepts/data-model) — the value types every crate shares, and the
   interning rule that decides which fields may be a pointer.
7. [The history store](/docs/trader/concepts/hist-store) — one Parquet store, thirteen declared
   layouts, and where it lives when nobody said.
8. The three proofs: [the paper exchange](/docs/trader/concepts/paper-exchange),
   [the parity gate](/docs/trader/concepts/parity-gate) and
   [the latency gate](/docs/trader/concepts/latency-gate) — what is checked bit-for-bit, and what is
   measured in microseconds.

## The rest of the section [#the-rest-of-the-section]

After that the pages stand alone, grouped by what they sit next to:

* **Inside the core thread** — [the event bus](/docs/trader/concepts/event-bus),
  [ingest lanes](/docs/trader/concepts/ingest-lanes), [timers](/docs/trader/concepts/timers),
  [portfolio and snapshot](/docs/trader/concepts/portfolio-and-snapshot),
  [the control boundary](/docs/trader/concepts/control-boundary),
  [the watchdog](/docs/trader/concepts/watchdog),
  [the dead-man's switches](/docs/trader/concepts/dead-mans-switch),
  [emulated orders](/docs/trader/concepts/emulated-orders).
* **Orders, money and stopping** — [the account](/docs/trader/concepts/account),
  [contingent orders](/docs/trader/concepts/contingency), [halt](/docs/trader/concepts/halt),
  [margin calls](/docs/trader/concepts/margin-call), [the price board](/docs/trader/concepts/price-board).
* **Mounting and startup** — [mounting](/docs/trader/concepts/mounting),
  [accounts](/docs/trader/concepts/accounts), [startup preflight](/docs/trader/concepts/startup-preflight),
  [settings](/docs/trader/concepts/settings), [the node protocol](/docs/trader/concepts/node-protocol).
* **Data in motion** — [the live data seam](/docs/trader/concepts/live-data-seam), the live mirror of
  the history store.
* **Venue-free cores** — [options](/docs/trader/concepts/options) and
  [alerting](/docs/trader/concepts/alerting).

Several rosters these pages mention are documented one member per page in their own sub-trees,
generated from the same CI-gated tables the runtime consults, so a page there cannot describe a
capability the code no longer has: [every event variant](/docs/trader/concepts/events/),
[every history store layout](/docs/trader/concepts/data/), [every order kind](/docs/trader/concepts/orders/),
[every asset class](/docs/trader/concepts/instruments/), and
[every reconciliation divergence kind](/docs/trader/concepts/reconciliation/). The command journal has a
hand-written sub-tree of its own.

<Callout title="How to read a citation on these pages">
  A claim is cited by **symbol** — a repo-relative path plus a named identifier, joined by `'s` —
  never by line number. `crates/vike-exec/src/order.rs`'s `ManagedOrder::apply` means: open that
  file, find that symbol, read its own documentation; it is the authority, and the page is the
  summary. The form is chosen because line numbers rot silently — when the product tree's own
  citation gate was written, 26 of its 33 line-number citations were already wrong, every one of
  them exactly right on the day it was authored — and that gate now rejects a `path:NNN` citation
  whose path resolves to exactly one file in the tree, deliberately leaving a shorthand path it
  cannot resolve alone.
</Callout>


# Ingest lanes (/docs/trader/concepts/ingest-lanes)



Everything that reaches the [execution core](/docs/trader/concepts/execution-core) arrives on one
ingest channel, and `crates/vike-exec/src/lanes.rs` owns the producer half of it: the sender
handles a venue adapter holds and the payload types they carry. The consumer — the single-writer
core thread — lives in `vike-core`. The header states why the split is where it is: venue bridges
depend on `vike-exec` but never on `vike-core`, so a bridge can push into the core without linking
the runtime that drains it.

## One message type, several disciplines [#one-message-type-several-disciplines]

`Ingest` is the one enum on the channel. Its variants sort into lanes by what losing a message
would mean:

* **`Event`** — a canonical venue event, the hot-path variant. It rides unboxed on purpose: the
  comment beside the enum records that boxing it would trade a 240-byte move for a per-event heap
  allocation on exactly the path the p99 \< 10 µs gate protects. Commands, which are rare, are boxed.
* **`Command`** — everything an outside thread may ask of the core, below.
* **`Market`** — a marker with no payload; the tick itself rides a conflation slot.
* **`BarSeed` / `BarClose`** — the bar lanes, lossless: a missed close is a hole in the series.
  Forming-bar updates conflate with the ticks instead.
* **`Quote` / `Trade` / `Book`** — the tick lanes, lossless and dispatched per update to a mounted
  strategy's tick handlers; they touch no parity-gated order-management fold path.
* **`Watchdog`** — the opt-in stuck-order sweep tick of the [watchdog](/docs/trader/concepts/watchdog).
* **`StreamStatus` / `Flow`** — occasional control events: a feed-health transition delivered to
  `Strategy::on_feed_status`, and a per-side flow-toxicity update delivered to `Strategy::on_flow`.
  Both fire on a transition or at their own cadence, never per market message; neither is journaled.

Every lossless sender returns `CoreGone` when the core thread has exited, so a producer learns the
channel is closed rather than blocking on it. The wait-free market lane reports nothing —
`MarketSender::publish` returns no result at all, and a marker that cannot be queued is simply
retried on the next publish.

## Lossless senders back-pressure the feed [#lossless-senders-back-pressure-the-feed]

`EventSender` is the lane every adapter pushes canonical events into — `send` from an async task,
`blocking_send` from a plain thread. Both back-pressure the producer and never drop. The handle
also carries an optional `route_key`, set by `EventSender::routed` at the mount: it stamps the key
onto the three venue-tagged payloads that carry no client-order-id — `AccountState`, `Funding` and
`PositionLiquidated` — so the core's router can fold them into the right engine when a venue runs
[more than one account](/docs/trader/concepts/accounts). `Fill` is deliberately left alone: it names its
order, which the router resolves exactly, and stamping it would put a second key on the one wire
shape the frozen parity fixtures pin. A key equal to the payload's own venue stamps nothing, which
keeps every single-account box's journal bytes identical. The stamp takes the event by `&mut`
because `blocking_send` sits inside the measured core hop — the
[latency gate](/docs/trader/concepts/latency-gate) feeds `Ingest::Event(Event::Fill)` through exactly
this call.

`BarSender` (`seed`, `close`) and `TickSender` (`quote`, `trade`, `book`, `stream_status`, `flow`)
are blocking-lossless for the same reason: each quote, trade or book update is a distinct event a
strategy may act on. The book rides behind an `Arc`, not by value — the `BookUpdate` doc records
the audit finding that carrying it by value deep-cloned two whole `BTreeMap`s (up to a 1000-level
seed) on the pump thread *and* paid the matching drop on the fold thread; with an `Arc` the send
is a refcount bump, a pump mutates its own standing copy through `Arc::make_mut`, and the wire
bytes are pinned identical to the pre-`Arc` shape.

## The market lane is latest-wins and wait-free [#the-market-lane-is-latest-wins-and-wait-free]

`MarketSender` is the exception, and the discipline inverts. A price tick for a (venue, symbol) is
written into a per-symbol slot — the newest overwrites, and an overwrite of a still-pending tick is
counted into `conflated_market_drops` — then at most one `Ingest::Market` marker is armed with
`try_send`. If the ingest queue is momentarily full the marker is not lost: `marker_in_flight`
stays false and the next publish retries it, and because ticks refresh continuously the slot can
never go stale while the feed is alive. The publish is wait-free and safe from tokio tasks and
plain threads alike. Three slot maps live under one lock — real venue marks, candle-close ticks and
forming bars — and marks and bar-closes are kept apart so a one-second mark stream can never
conflate away a kline feed's close for the same symbol; they fill different slots of the
[price board](/docs/trader/concepts/price-board) downstream.

## Commands, and the one write contract [#commands-and-the-one-write-contract]

`Command` is the session-control vocabulary: `Order`, `UpdateParams`, `SetTradingState`,
`SetMargin`, `ApplySnapshot`, `ReconcileReports`, `ConfirmRecon`, `MountStrategy`,
`UnmountStrategy`, `Shutdown`. These are control verbs rather than market messages, and
`UpdateParams`, `SetMargin`, `ReconcileReports` and the two mount verbs each say so in their own
doc — *occasional*, off the p99 event fold. The two mount verbs are deliberately not journaled,
because a mount-less replay core could never re-resolve a strategy. The
[control boundary](/docs/trader/concepts/control-boundary) is the surface these arrive through.

`Command::Order` wraps `OrderIntent` — **the one write contract**. Every order-scoped instruction,
whether from the external command path or from a mounted strategy's broker drain, lowers into the
core's single `apply_intent` site, so minting a client-order-id and crossing the risk gate are
structural on every order path. The verbs: `Submit`, `SubmitBatch`, `Cancel`, `CancelBatch`,
`Modify`, `Confirm`, `MassCancel`, `Flatten`, `MarketExit`, `Bracket`, `ArmConditional`,
`DisarmConditional` and `Combo` (declared on the wire; its own doc marks the lowering as pending).
Arming an [emulated conditional](/docs/trader/concepts/emulated-orders) bypasses the gate — only its
fire crosses it — and so does disarming one.

<Callout type="warn" title="The panic button works from a halted core, and it is not atomic">
  `MarketExit` is a compound verb: the runtime expands it at apply time into one `MassCancel` first,
  then one `Flatten` per non-flat `BOTH`-side position — a hedge-mode long or short leg would resolve
  a size of zero, so it is skipped — each lowered through the same `apply_intent` site. It has no
  precondition — a position-covered reduce is admitted under [halt](/docs/trader/concepts/halt), which is
  exactly the shape a flatten mints, unless the position sits off the lot grid, where the rounded-up
  size no longer covers it and that leg is denied under `Halted`. Its own doc records that this is
  the reverse of the rule the verb carried for its whole earlier life, when an operator had to
  un-halt in order to escape. It is also best-effort: against a real venue the mass-cancel is
  fire-and-forget over the adapter's actor thread, its acknowledgements may land after the flatten
  orders are already on the wire, and a resting order can still fill after a flatten leg. Re-issue
  the exit if the board is not flat afterwards.
</Callout>

Two test-support constructors ship with the lanes: `event_channel` hands back a raw `EventSender`
plus the receiver with no core behind it, so an adapter test can observe exactly what a client
pushes, and `market_data_channel` is its bar/market twin.


# The latency gate (/docs/trader/concepts/latency-gate)



The [execution core](/docs/trader/concepts/execution-core)'s drain loop is the one thread in the
platform with a latency budget, and the budget is enforced rather than aspired to:
`crates/vike-core/tests/runtime_latency.rs` runs in CI on a dedicated runner whose cores are
reserved for it, under real-time scheduling, and fails the run if the tail moves. This page is what
it measures, what it deliberately does not, and how to read a number from it without being misled.

## What is gated: the tail, on three variants [#what-is-gated-the-tail-on-three-variants]

Three tests assert derived ceilings — `baseline`, `journal` (the write-ahead append cost isolated,
no cadence snapshot) and `journal-snap` (the production journal configuration, snapshots included).
Each feeds `Ingest::Event(Event::Fill)` — the venue-reply lane — through the core 100 000 times and
asserts the whole **tail**, not a single p99. The harness header says why: until it did, the gate
computed p50, p99.9, max and the count of hops over 100 µs purely in order to *print* them, and a
reference run went green with a p99.9 of 37 741 ns and one 141.86 ms core hop. For a market maker
the tail is the number that costs money; p99 is the number that looks good.

Every ceiling is a derived constant with the measurements that produced it beside it in the
source. The reference row every constant descends from: baseline p50 271 ns, p99 551 ns, p99.9
2 104 ns, max 25 709 ns, zero hops over 100 µs. The baseline keeps the platform's long-standing
`P99_BUDGET_NS` of 10 µs, with `BASELINE_P999_NS` at 50 µs, `BASELINE_MAX_NS` at 2 ms — placed
between the shielded and un-shielded scheduling regimes, so it reddens if the shielding silently
stops applying — and `BASELINE_HOPS_OVER_100US` at 2. The two journal variants gate on a separately
calibrated `JOURNAL_P99_NS` of 20 µs: the 10 µs literal was never derived for them, and the main
branch itself measured 9 809 ns against it — 98.1 % of the bar, on code containing no change under
test. Deriving that one constant honestly took **98 CI attempts** harvested across 250 runs.

<Callout title="The journal ceilings are a ratchet, not a budget">
  `JOURNAL_P999_NS` (100 µs), `JOURNAL_MAX_NS` (10 ms) and `JOURNAL_HOPS_OVER_100US` (50) record
  today's measured tail so it stops being invisible; they are meant to be lowered as the journal's
  I/O policy improves, and they move together or not at all. They have been lowered once — from
  250 µs, 500 ms and 100 — after two fixes took blocking `msync` calls off the fold thread. The hop
  count is the one that catches that defect as arithmetic rather than weather: a run at the
  production `snapshot_every` takes 100 000 / 1024 = 97 cadence snapshots, and the pre-fix reps read
  102, 97, 101 and 120 hops over 100 µs — one per snapshot. Read that number first on any red, and
  read p50 before anything: a p50 that doubles means the box, not the code. The
  [sync policy](/docs/trader/concepts/journal/sync-policy) is where the fix lives.
</Callout>

<Callout type="warn" title="Only three variants gate on a derived budget">
  The order-submit lane, the book hop and the client-order-id variants are measured and assert
  nothing about timing at all. The snapshot publish is measured too, at three order counts — and
  keeps one pre-existing sanity assert, the 64-order build's p50 under 1 ms, roughly 100x above the
  \~10 µs it actually measures. That is a liveness check against the build doing something
  structurally different, not a derived budget. No ceiling here descends from a calibrated baseline,
  on purpose. An uncalibrated ceiling is a flaky gate, which is worse than no gate at all, because
  people learn to re-run it rather than read it. A measured, persisted, trendable series catches
  drift for an afternoon's work and leaves the ceiling as a later decision derived from a baseline
  instead of guessed. &#x2A;*A new measurement variant is not a budget in waiting; a ceiling means
  somebody derived one.**
</Callout>

One path is deliberately not measured, and the harness records why: the live recorder's flush is
a disk-bound Parquet write on its own thread, and the failure that actually cost \~110k rows was a
compactor holding the series lock while the sink discarded batches — which shows up in
`RecorderHandle`'s `dropped` and `discarded` **counters**, not as a slow flush.

## Two facts that mislead everyone once [#two-facts-that-mislead-everyone-once]

**Serial execution is load-bearing, not tidiness.** The harness runs under `--test-threads=1`,
and `crates/vike-core/tests/runtime_latency.rs`'s `SPIN_DEADLINE` carries the measurement: every
harness thread busy-spins waiting for its worker, and CI pins the binary to a small reserved core
set under real-time scheduling. Run in parallel, the spinners occupy every core and starve the
workers they are waiting on — priority inversion, not slowness, and a spin that never terminates is
a `SCHED_FIFO` process nothing can preempt: this gate's history holds a livelocked binary at
**380 % CPU** with no progress for over five minutes, during which a `/proc` scan on the same host
went from 53 ms to over 120 s and degraded everything else running there. Serial execution also
makes the numbers honest: run in parallel, these tests contend for the very cores whose tail they
report.

**Publish is per-event work on a quiet venue.** The core publishes its snapshot on a coalesced
cadence while busy and immediately when the queue goes idle. On a venue whose events arrive
sporadically, that is a publish after every event — so anything `CoreSnapshot::build` does is on
the per-event path this gate measures, and deferring work "to publish time" relocates it rather
than avoiding it. Not hypothetical: rendering the recent-events ring lazily at publish moved the
baseline p99 from 481 ns to 2 039 ns; rendering at push again brought it to 606 ns.

## Reading a number [#reading-a-number]

Every run — pass or fail — appends one JSON row per (run, attempt, variant) to a persisted series
on the CI box, keyed on commit, with the attempt's journal-free `baseline_p99_ns` denormalized onto
it. That baseline is the canary no journal change can move, and it is the field that separates a
disturbed box from a real regression. Two things to know before quoting a figure: across the
ordinary load range the median barely moves while the tail does — baseline p50 read 271–451 ns
across every load bucket measured — so a four- or six-figure "p50" quoted anywhere is a tail
percentile that has been mislabelled, and that same stability is what makes the doubled-p50 tell
above work, since it takes a genuinely disturbed box to shift a median load alone leaves alone (a
p50 that tracks the change under test is real signal, and the journal fixes moved it); and the
series is the answer, not the job log — before it existed, "is this creeping on main?" cost two
separate hand-harvests of the CI API.

<Callout title="What this means for a change to the core">
  Nothing on the fold path may log per-message — instrument per-order boundaries and fault
  transitions only. Everything that can run off the fold belongs in a crate that consumes the
  published [snapshot](/docs/trader/concepts/portfolio-and-snapshot), event and
  [journal](/docs/trader/concepts/journal/) streams without sitting in this loop. An honest A/B of a
  hot-path change is run on the reserved-core box, serially, interleaving the variants and taking
  medians of at least eight reps — single runs produced contradictory rankings all day. The
  procedure is on [running the latency gate](/docs/trader/developer/testing/latency).
</Callout>


# The live data seam (/docs/trader/concepts/live-data-seam)



`crates/vike-data/src/live.rs` is the live twin of the [history store](/docs/trader/concepts/hist-store):
`DataClient` is what a venue feed implements to start and stop streams, and `LiveDataSink` is where
everything a stream produces lands. The contract carried over from an earlier prototype is
**fire-and-forget**. `subscribe_bars`, `subscribe_quotes`, `subscribe_trades`, `subscribe_book` and
`subscribe_depth` start a stream and return a `SubscriptionId` immediately; they never carry data.
All data returns through the one sink handed to the client at construction — the trait methods take
no sink parameter, and there is no subscribe-with-a-callback shape. An `Err` from a subscribe call
means the stream could not be *started*; a disconnect, a reconnect or a resubscribe after a drop
surfaces on the feed's own status path, never through this trait. Reconnect is the feed's concern,
not the seam's.

## Capabilities, not obligations [#capabilities-not-obligations]

A client that cannot serve a verb returns `LiveDataError::Unsupported` rather than pretending to
subscribe. `require_live_verb` drives that refusal off the venue's declared `VenueCaps.live_data`
row, so a feed that calls it first in every `subscribe_*` verb cannot drift from the capability
matrix, and an unknown venue string refuses every verb. Most bridge feeds do call it; a few still
hand-roll their own decision — hyperliquid's snapshot-only `subscribe_book` and polymarket's
`subscribe_bars` are the ones left — and routing those through the seam is the noted follow-up.
`subscribe_depth` — the DOM's conflating snapshot lane, distinct from the lossless tick-lane
book — is `Unsupported` by default and only venues with a live depth feed override it.

## Two lanes, and which price verb a feed must use [#two-lanes-and-which-price-verb-a-feed-must-use]

Sink methods are called from feed worker threads on every closed bar, intrabar update and tick, so
they must be cheap and effectively non-blocking — a slow sink stalls the feed. Downstream is a
lossless bar lane, `seed_bars` and `close_bar`, where a missed close is a series hole, plus a
latest-wins conflating lane, `forming_bar`, `bar_close_tick` and `mark_tick`, where drops are fine
and only the newest snapshot matters.

The price verbs are not interchangeable, because each fills a different rung of the
[price board](/docs/trader/concepts/price-board)'s resolver chain, and that chain is strictly ordered:
`mark` above side-aware `bid`/`ask` above `last_trade` above `bar_close`. A feed choosing the wrong
verb does not mislabel a number; it re-ranks it against every other price for the symbol. The
mapping is fixed:

| verb             | what may call it                                                                                                                                               | rung                                                       |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `mark_tick`      | only a venue-published mark or index stream — binance-family `@markPrice@1s`, bybit `tickers.markPrice`, okx `mark-price`, hyperliquid `activeAssetCtx.markPx` | mark                                                       |
| `quote`          | a BBO or two-sided book top                                                                                                                                    | bid / ask                                                  |
| `trade`          | a real print                                                                                                                                                   | last trade                                                 |
| `bar_close_tick` | a kline feed's candle close, from every venue that serves klines                                                                                               | bar close — the lowest rung, up to one full interval stale |

Mark streams are default on for perps; aster's is default off, its grammar unverified, and opts in
with `VIKE_MARK_STREAMS_ASTER=1`; `VIKE_MARK_STREAMS=0` is the master kill. The classes overlap
freely: a venue with no mark stream still fills the quote and trade rungs whenever those
subscriptions are open, so such a symbol is valued at its live quote or last trade rather than its
candle close — the intended law.

The L2 verbs split the same way. `book` carries folded state behind an `Arc` — a pump keeping one
standing book hands out clones and mutates through `Arc::make_mut`, so an applied delta no longer
deep-clones two whole maps per emission — while `book_update` is the recordable twin carrying the
raw delta, snapshot anchor or status marker that only recording sinks opt into; today the polymarket
pump in book mode is the one feed that emits it. `l2_snapshot` carries the instrument's `tick_size`
so a book-consuming sink quantizes on the grid the feed used rather than re-inferring it from a
truncated level set.

## Stream health [#stream-health]

`stream_status` is a default no-op that a feed's idle watchdog and reconnect path fire. `GapStart`
says the stream can no longer be trusted from a timestamp: for tick lanes the data in the gap is
missing and unrecoverable, for the forming-bar lane it is stale, and the lossless bar lane is
repaired by the re-seed before `Live` fires. `Stale` is the case a socket-liveness watchdog cannot
see — the transport is alive, keepalives arrive, and no fresh data has come inside the
subscription's freshness threshold. Both can be true at once, and only the consumer can decide what
staleness means: flatten, re-arm, widen.

<Callout title="Teardown costs one timeout, not the sum of them">
  A feed thread learns it should stop on its next socket read timeout, 2 s on every on-driver venue.
  `DataClient::begin_shutdown` raises every stop flag and joins nothing, so a caller holding several
  clients runs that phase across all of them before any join; `shutdown` then joins. `vike-recorder`'s
  teardown used to stop one stream at a time, outside its bounded region, and its total stop time was
  on a collision course with the unit's `TimeoutStopSec=` as a profile grew — a binance subscription
  is two threads per symbol. `FeedRegistry` is the shared per-subscription registry behind that: one
  stop flag and one `JoinHandle` per stream, nothing ever detached, with an optional hook that runs on
  each spawned thread — the seam a venue threads its core-affinity pin through without this crate
  depending on `vike-exec`. Bybit, binance, okx, hyperliquid and polymarket use it, and so do
  deribit, ig and oanda.
</Callout>

`TeeSink` fans one feed's sink slot out to several destinations in order — the core ingest adapter
plus a tick-recording sink is the shipped composition — and must forward every verb explicitly:
inheriting a trait default for `bar_close_tick`, `l2_snapshot` or `book_update` would silently
drop candle-close ticks, depth snapshots or recordable book events. On the consuming side, the
desktop app's `CoreSinkAdapter` bridges the sink onto the core's bar and market
[ingest lanes](/docs/trader/concepts/ingest-lanes), and the `RecorderSink` writer actor behind the
`hist-datafusion` feature buffers live quotes, trades and book events into the store — the path
[recording a feed](/docs/trader/guides/record-a-feed) rides.


# Margin calls (/docs/trader/concepts/margin-call)



The margin-call model is `crates/vike-exec/src/margin_call.rs`'s `check_margin_call_priced`.
It is *pure*: it computes intents, and the caller — the core's
[watchdog](/docs/trader/concepts/watchdog), opted in through `CoreConfig::margin_call` — mints the
client order ids and submits through the normal gate path. A veto surfaces as `OrderDenied`; a
margin call can never bypass the `RiskGate`. The buying-power primitives are
`crates/vike-model/src/margin.rs`, and the breach law is `crates/vike-model/src/liquidation.rs`.
This page is written from those three modules.

## The three verdicts [#the-three-verdicts]

`MarginCallConfig` carries three fractions, defaulting to `mm_requirement: 0.05` (the
maintenance-margin fraction), `warn_fraction: 0.05` and `buffer: 0.10`. One sweep returns
`MarginCall::Healthy`; `Warning { margin_used, margin_remaining }` when remaining margin is at
or below `equity × warn_fraction` but nothing is liquidatable yet; or `Liquidate(intents)`. A
`LiquidationIntent` is a position-reducing market order — venue, symbol, position side, the
closing side opposite the position's sign, and a quantity. An unmarked position contributes no
margin and is never liquidated.

## One law, the pool is the parameter [#one-law-the-pool-is-the-parameter]

`vike_model::pool_breached` is the breach predicate for every pool: breached only when
`pool_maintenance > 0`, `pool_equity − pool_maintenance ≤ 0`, and
`pool_maintenance > pool_equity × (1 + buffer)`. A `NaN` anywhere reads as not breached — the
law refuses to liquidate on garbage inputs. It takes the folded maintenance product rather than
`(rate, notional)` because `Σ(|q|·mark·mult·rate)` and `rate·Σ(|q|·mark·mult)` differ in
`f64`, and the live verdict had to stay byte-identical to its pre-law behaviour.

Positions are partitioned by `vike_model::MarginMode` through `vike_model::partition_pools`:

* **Cross** positions — the default, every position today — share one pool. A breach runs
  `vike_model::cross_liquidation_plan`: sort by unrealized PnL ascending so the biggest losers
  go first (a stable sort, so ties keep insertion order), liquidate only the excess over the
  line position by position, and stop as soon as the pool is healthy. A cross-only account is
  byte-identical to the pre-partition sweep, pinned by
  `cross_only_verdicts_byte_identical_to_legacy`.
* **Isolated** positions each form their own pool — the walled-off wallet plus their own
  unrealized PnL, judged with a zero buffer. A breach closes that position only, full size, and
  can never drag the cross pool: its wallet and PnL are subtracted from the cross pool's equity.
  An isolated position with no reported wallet, or no mark, is skipped, and isolated pools have
  no `Warning` arm.
* **Cash** positions never liquidate; fully funded, they structurally cannot breach.

Intents come out cross plan first, then isolated closes — one deterministic release order for
the journal-then-submit loop.

<Callout title="One maintenance rate">
  `cfg.mm_requirement` prices every pool. A per-symbol venue-reported maintenance rate would take
  precedence when present, but no venue adapter parses one today, so the `SymbolProperties`
  carrier is a documented follow-up rather than a guessed wire field. The GUI's liquidation badge
  reads the same source — the operator's watchdog config when armed, else that config's default.
</Callout>

## Priced the way the operator sees it [#priced-the-way-the-operator-sees-it]

The live watchdog passes a resolver closure over the engine's
[price board](/docs/trader/concepts/price-board), so margin used shares the price basis of the
resolver-priced equity it is compared against: every price read in the sweep — the cross
margin-used fold, each pool's unrealized PnL, the isolated maintenance line, the cross
candidates — goes through the one `price_of`, and a stale mark can no longer overstate margin
against a fresh-quote equity or vice versa. The legacy `check_margin_call` prices at
`Account.marks` for callers with no board, such as tests and offline tools. The equity itself
is `ExecutionEngine::resolved_equity`, the scalar every decision path reads so an
auto-liquidation acts on exactly the number the snapshot displays.

<Callout type="warn" title="A known venue asymmetry: isolated mode without a wallet">
  A venue can report a position isolated while surfacing no per-position wallet. The sweep then
  subtracts only that position's unrealized PnL, skips its isolated judgment (never a spurious
  close), and leaves the unknown wallet folded inside the account balance — so the cross pool's
  equity is overstated by that wallet and a genuine cross breach is judged late. The venue itself
  still liquidates the isolated position. The module records a live probe of 2026-07-19 in which
  both isolation paths were refused on the demo account, so the field semantics stayed
  unverifiable and `isolated_margin: None` remains the pinned parse.
</Callout>

## When and where it runs [#when-and-where-it-runs]

The sweep runs once per closed bar of the engine's own series, where marks are fresh and the
path is the per-bar lane rather than the event fold, so the
[latency gate](/docs/trader/concepts/latency-gate) is untouched. `CoreThread::sweep_margin_call`
runs the model per engine: each account is checked at its own seed and its liquidations are
routed to that engine by index (`EngineRoute::Engine`) rather than by venue string — two
accounts of one exchange share a venue string, and routing by it once sent a reduce-only close
of account B's position to account A. A `Warning` lands in the recent-events ring; each
liquidation is a `reduce_only` market request journaled write-ahead
(`append_margin_call_liquidate`) before `apply_intent`, with no mount id, so its fill lands in
the [portfolio](/docs/trader/concepts/portfolio-and-snapshot)'s unattributed residual row. Without
that record a replay could not reproduce the liquidation, and the determinism fence caught it
as a hash mismatch.

## The buying-power primitives [#the-buying-power-primitives]

`crates/vike-model/src/margin.rs` is the venue-free core, as pure `f64` functions. Quantities
are signed, margins are in account currency, `rate` converts the quote currency to the account
currency (`1.0` when the same), and `im_req`/`mm_req` are fractions — `0.1` means 10×. Callers
own fee handling and pass a fee-adjusted requirement in.

* `initial_margin` — `rate × mult × price × qty × im_req`, signed, negative for shorts.
* `maintenance_margin` — `|qty| × price × mult × rate × mm_req`.
* `free_buying_power` — equity minus margin in use, plus the credit a direction-reversing order
  frees, minus the required-free haircut, floored at zero.
* `amount_to_order` — the signed quantity that lands the position's margin at or under a target
  on the lot grid; `0.0` on degenerate inputs or non-convergence, the safe verdict.
* `liquidation_price` — the isolated linear-perp mark: long `avg × (1 − im) / (1 − mm)`, short
  `avg × (1 + im) / (1 + mm)`; `0.0` means no liquidation by price.
* `clamp_leverage` — request and cap both floored at `1.0`, so a sub-unity cap can never pull
  effective leverage below one.

The snapshot's `VenueBlock` publishes `margin_used`, `free_bp` and `margin_ratio` from the same
primitives, computed only when the margin gate is armed; when it is off `free_bp` equals equity
and the ratio is zero. Each `PositionView::liq_price` uses `liquidation_price` for an isolated
position, `vike_model::cross_liquidation_price_est` for a cross one — the shared-pool line with
every other position frozen, advisory — and `0.0` for cash. The gate that admits orders in the
first place is the [risk and arming](/docs/trader/concepts/risk-and-arming) page's subject.


# Mounting (/docs/trader/concepts/mounting)



Three modules in `vike-core` answer three questions about a mounted strategy: what assembly it runs
inside (`crates/vike-core/src/run_profile.rs`), what it is called and where its durable state lives
(`crates/vike-core/src/strategy_state.rs`), and how a mount added at runtime comes back after a
restart (`crates/vike-core/src/mount_topology.rs`).

## The run profile [#the-run-profile]

`RunProfile` is the single TOML-deserializable artifact that names a full runtime assembly — event
source, broker, sinks, and the risk and guard stack — so that backtest, paper and live become one
auditable file instead of code-only `CoreConfig` construction by each binary. `mode` is `backtest`,
`paper` or `live`; `[event_source]` is `hist`, `replay` or `live_venue`; `[broker]` is `paper` or
`venue`. `RunProfile::validate` refuses the combinations that do not make sense — backtest needs a
paper broker and cannot take a live venue feed, live needs a venue broker and a live venue feed.
Every struct is `deny_unknown_fields`, so a typo'd key is a hard parse error rather than, in the
module's words, a silently ignored `max_levarage`.

The sections map onto real types and the mapping is compile-checked: `[risk]` becomes
`vike_exec::RiskLimits`, `[guards]` fills `CoreConfig` knobs — the stuck-order
[watchdog](/docs/trader/concepts/watchdog) timeouts, the drawdown latch, the margin-call config — and
`[sinks.journal]` becomes the [journal](/docs/trader/concepts/journal/) config.
`apply_guards_and_sinks` returns a `GuardsReport` naming every key that is set and still reaches
nothing, and evaluates the confirm-grace pairing on the final pair the mount will run with; that
check warns rather than refuses, and `ConfirmGraceHazard`'s doc argues why against the
degrade-versus-refuse record.

<Callout type="warn" title="The venue owns the instrument grid; the operator owns the risk budget">
  `RiskLimits` holds both concerns in one struct — `tick_size`/`lot_size`/`min_qty`/`min_notional`
  from the venue's fetched grid, and the notional, exposure, rate and leverage caps from the operator.
  `RunProfile::grid_source` derives which is allowed from `mode` alone: a `backtest`/`paper` profile
  never fetches a grid and may supply one, a `live` profile always fetches one and may not, and
  `validate` rejects a `live` profile whose `[risk]` sets any venue-owned field, unconditionally, at
  load. A live mount additionally refuses to start unless `max_notional_per_order` and
  `max_total_exposure` were supplied — `vike_mount::MountError::MissingRiskBudget` names every missing
  key in one message, because no universal safe default exists for an account-dependent cap.
</Callout>

`resolve_profile` takes an explicit path (a `--profile` flag) over `VIKE_RUN_PROFILE` from an
injected variables map, never the process environment, and a resolved path that fails to read, parse
or validate is an error rather than a silent fall-through to built-in defaults. Three sample
profiles ship as string constants under `run_profile::samples`, one per mode.

## Mount identity and the state sidecar [#mount-identity-and-the-state-sidecar]

`strategy_state::mount_id_of(venue, symbol, interval)` sanitizes each part (every non-alphanumeric
character becomes `_`) and joins them with `__` — `mount_id_of("binance", "BTC/USDT", "1m")` is
`binance__BTC_USDT__1m`. It is pure and total, so a restart derives the same id a prior run wrote.
`mount_id_with` adds the one thing the derivation cannot express: an explicit `controller_id`, when
the mount carries one, **is** the mount id, sanitized the same way — which is how two strategies can
sit on the same `(venue, symbol, interval)` triple without sharing one sidecar and one journal
identity. `None`, empty and whitespace-only ids fall back to the derivation verbatim.

The sidecar is `<state_dir>/<mount_id>.json`. The runtime loads it when a strategy is mounted
(`Strategy::load_state`) and writes it on a clean shutdown (`Strategy::save_state`), both gated
behind the opt-in `CoreConfig::state_dir` — `None` by default, in which case nothing in the module
is ever called. `write_json_atomic` writes a `.tmp` sibling, `fsync`s it, then renames over the
final path with a remove-then-retry fallback for platforms where `rename` refuses to replace.
`read_json` is fail-open: a missing or corrupt sidecar reads as "no saved state", never a load-time
crash. A periodic save also runs while any mount exists when `CoreConfig::state_save` is set — and
unlike the equity sampler it does not wait for an open position, because a breaker or an estimator
matters whether the book is flat or not.

## Runtime mounts survive a restart — through a sidecar, not the journal [#runtime-mounts-survive-a-restart--through-a-sidecar-not-the-journal]

A mount added over the wire (`WireCommand::MountStrategy`, behind the node's
`strategy-mount-verbs` feature) is not a journal record. `Command::MountStrategy` and
`Command::UnmountStrategy` are excluded from the journaled set, and `mount_topology.rs` explains why
the exclusion stands: the journal is the [replay](/docs/trader/concepts/journal/replay) determinism
fence, and the replay core spawns with no strategy factory — `vike-core` sits below the strategy
crates and can resolve nothing — so a journaled mount could only ever replay as a refusal note.
Topology is session state, not order state.

So it lives in `runtime_mounts.json` beside the state sidecars, under the same opt-in `state_dir`,
invisible to the state hash and the replay core. The daemon reads the file after its core spawns and
before feeds arm, and re-sends each record as an ordinary `Command::MountStrategy` through the same
command lane a wire mount takes, meeting the same refusals. A record holds the spec exactly as the
command carried it — what to ask the factory for, never what the factory answered — so a
resurrected mount meets today's registry, today's script and today's refusals.

The lifecycle is asymmetric on purpose. A successful mount upserts its record; an explicit unmount
removes it; a clean shutdown removes nothing, so a runtime mount survives `systemctl restart`
exactly as it survives a crash — "the operator said stop the daemon" is not "the operator said
unmount". Profile mounts never enter the file, because the profile re-creates them at every boot. An
absent file is the ordinary empty state; a file that exists but does not parse is warned about
loudly and read as empty, so a corrupt topology can never refuse a boot, and the next successful
mount rewrites the whole list.

<Callout title="Nothing locks these files">
  The only writer is the single-writer fold thread of one core. Two cores pointed at one `state_dir`
  already share and clobber each other's `<mount_id>.json` sidecars and would share the topology file
  the same way; the journal's [duplicate-instance interlock](/docs/trader/concepts/journal/locking) is what
  makes that deployment shape loud. An unmount over the wire cancels that mount's attributed live
  orders and saves its durable state before removal; positions are deliberately not flattened. Which
  [account](/docs/trader/concepts/accounts) a mount trades on is part of its spec and is persisted with it.
</Callout>


# The node protocol (/docs/trader/concepts/node-protocol)



`vike-tradehub-client` is the light crate a thin client links to reach a headless node. It carries
no server and no DataFusion; what it defines is the wire schema (`proto.rs`), the auth primitive
bound to this service (`auth.rs`), and standalone mirrors of the snapshot and command vocabulary
(`wire.rs`). The server half lives in the [daemon](/docs/trader/reference/binaries/vike-tradehub).

## Framing [#framing]

A frame is `[u32 len][len bytes of UTF-8 JSON]`, big-endian, and the codec is re-exported from
`vike_datahub_client::proto` rather than re-implemented: both localhost services — the
[data service](/docs/trader/reference/binaries/vike-datahub) and the live-core node — speak the identical
frame with the same pre-allocation guard, `MAX_FRAME_LEN`. Two primitives matter to a server.
`read_frame_raw` returns the framed body without decoding, so a well-framed body that fails to
decode into a known request is answered with `Response::Error` and the connection survives — a
decode error is a bad request, not a bad connection. `read_frame_raw_capped` reads pre-auth frames
under a ceiling far below `MAX_FRAME_LEN`, so an unauthenticated peer cannot make the node allocate
from a four-byte length prefix.

## The handshake [#the-handshake]

The core is a headless process that accepts orders, so an unauthenticated peer must never reach the
command path. The handshake is a nonce-challenge HMAC:

1. Client → `Request::Hello { proto_version }`.
2. Server → `Response::Welcome { proto_version, nonce, features }` — `nonce` is 32 fresh random
   bytes for this connection.
3. Client → `Request::Auth { scope, mac }`, where the tag is
   `auth::sign(key_for(scope), &nonce, proto_version, scope)`.
4. Server recomputes and compares in constant time: `AuthOk { scope }`, or `AuthDenied { reason }`
   with a reason that never leaks key material. Only after `AuthOk` may the client subscribe, ask
   for a snapshot, or — with `Scope::Control` — send a command.

The signed message is `b"vike-tradehub-auth\0"` (a 19-byte, NUL-terminated domain separator), the
protocol version as a big-endian `u32`, one scope byte (`Observe` 0x00, `Control` 0x01), and the
nonce; the tag is HMAC-SHA256. Each field buys a property. The separator makes the preimage disjoint
from every other HMAC the workspace signs — the venue request signers, and the data service's own
`vike-datahub-auth\0` — so a tag captured off one surface is useless at the other. The scope byte
binds capability **into** the signature. The nonce binds the tag to one connection, so a captured
transcript cannot be replayed. The version in the message means a client and server that disagree
on it can never produce a matching tag. Verification uses the `hmac` crate's constant-time
`verify_slice`, never a byte-wise `==`.

The two scopes sign under different keys. `Scope::Observe` is snapshots and subscriptions;
`Scope::Control` additionally admits commands; and because an observe-only key cannot produce a
valid control tag, capability is cryptographic rather than a claim the server trusts. The keys are
`VIKE_TRADEHUB_OBSERVE_KEY` and `VIKE_TRADEHUB_CONTROL_KEY`, read by `auth::from_vars` from the
credential-store map the binary already loaded — not the process environment, where a store-defined
key is invisible. Neither present means nothing to authenticate, the same credential-is-the-gate
idiom the venues use; an absent control key brings the node up observe-only, while an absent
observe key means the daemon starts no node server at all. `NodeKeys` redacts its `Debug`, and
`NodeKeys::key_id` yields a stable `nk-` plus sixteen hex characters fingerprint an audit record
can name a credential by.

<Callout type="warn" title="An empty key is not a closed gate">
  The `NodeKeys::key_for` doc records a claim that stood until 2026-08-29 — that verifying against an
  absent key always fails. It is false: HMAC accepts a zero-length key, so a peer signing with the
  empty key produces a tag that verifies. What closes the gate is `NodeKeys::has`, consulted before
  the key; both servers refuse an unkeyed scope without reaching `verify` at all. The handshake is
  also plaintext: it authenticates the connection, not each frame, and confidentiality still comes
  from the tunnel or VPN in front of it.
</Callout>

## Versions and features [#versions-and-features]

`NODE_PROTO_VERSION` is 4 — v2 added bounded bar tails to the snapshot, v3 the server-authoritative
`Preview` dry-run, v4 an optional rationale beside a command. Because the version is folded into the
signed tag, a bump fails the handshake against every running node, so every verb since v4 rides
`Welcome.features` instead: `strategy-verbs`, `settings-show`, `settings-write`,
`strategy-mount-verbs`, and the one value-carrying entry, `datahub=<addr>`, which advertises the
data service's dial address so an operator configures one address and the client dials the data
plane itself — advertisement, never proxying. A client must check for the feature before sending the
verb, so against an older server nothing goes on the wire and the caller gets "this node predates
settings-write" rather than an undecodable-request error.

## The vocabulary [#the-vocabulary]

Requests after auth: `Subscribe { topics }` over `Topic::{Orders, Positions, Events, All}`,
`Snapshot`, `Command { cmd, reason }`, `Preview(cmd)`, `Ping`, `StrategyStatus`, `SettingsShow`.
Responses: `SnapshotFrame`, `Ack { coid }`, `Preview { accepted, reason }`, `Error`, `Pong`,
`StrategyStatus`, `SettingsShow`, and `SettingsWritten { restart_required }` — the one accepted
command that is not an `Ack`, because nothing entered the core; `false` means the node hot-applied
the value, and policy keys never are. A command's `reason` is remote free text landing in the audit
trail: the node sanitizes it, and it never reaches the order request, the core fold, the journal or
a venue.

`wire.rs` re-declares the field shapes of the core's snapshot and command types rather than
depending on `vike-core`, for two reasons its header gives: weight, since the live-runtime tree
would otherwise ride into the thin client, and a stable contract, since an internal refactor of
`CoreSnapshot` cannot then silently change the wire. `WireCommand` is deliberately the
session-relevant subset — `Submit`, `Cancel`, `Modify`, `MassCancel`, `Flatten`, `MarketExit`,
`SetTradingState`, `UpdateParams`, `MountStrategy`, `UnmountStrategy`, `SetSetting` — and not the
reconcile and journal plumbing (`ApplySnapshot`, `ReconcileReports`, `ConfirmRecon`), which is never
a remote client's business. `UpdateParams` and `MountStrategy` carry their parameter tables as the
core's own serde JSON rather than a hand mirror that would drift within a release. The server lowers
each variant into the core's real command at its edge and hands it to the
[control boundary](/docs/trader/concepts/control-boundary)'s `CommandSink`.

Two handles wrap all of this. `RemoteCoreHandle` authenticates as `Observe`, subscribes, and
exposes the latest pushed snapshot off a local arc-swap cell — the read side
[observe mode](/docs/trader/gui/observe-mode) runs on. `RemoteControlHandle` authenticates as `Control`,
never subscribes, and offers a non-blocking `try_command` over a worker thread whose ticket resolves
to that command's outcome. Both run the one crate-private handshake; a version mismatch names both
numbers, and an `AuthDenied` surfaces as `PermissionDenied` carrying the server's reason.


# Options (/docs/trader/concepts/options)



`vike-options` is the pure core under the [options chain window](/docs/trader/gui/options-chain):
egui-free, I/O-free, and dependent on no other crate in the workspace. Three of its modules are a
faithful `f64` port of the Python oracle's options package and are gated by the
[parity fixtures](/docs/trader/concepts/parity-gate); three more are additive, with no Python twin, and
are verified by finite differences and self-consistency instead. The crate's contract draws one
line firmly: venue-specific fetching and parsing lives in the deribit bridge's `chain.rs`, order
entry stays on the [execution client seam](/docs/trader/concepts/execution-client-seam), and an option's
identity stays in its instrument-name string — no strike, expiry or kind fields on the order
request.

## The chain model [#the-chain-model]

`model.rs` holds the normalized types a provider translates into and the UI consumes without
knowing which feed produced them: `OptionChain` for one expiry's snapshot, `Expiry` with its ISO
date, days to expiry and label, `StrikeRow` as a call and a put at one strike, and `OptionQuote`.
Quote fields are `Option<f64>` — absent stays absent, never `0.0` — and rows are ascending by
strike. Expiries settle at 08:00 UTC through `expiry_ms`. `make_expiry` computes days to expiry as a
calendar-day difference of UTC dates rather than a floored elapsed-millisecond count: late in the
UTC day the floor rounded both today and tomorrow to zero and the expiry strip rendered two `0DTE`
pills. `limit_strikes` windows a chain to `n` strikes below the spot and `n` at or above it, so a
±3 view shows exactly three rows on each side of the spot band.

## Price, greeks and implied vol [#price-greeks-and-implied-vol]

`greeks.rs` derives Δ, Γ, Θ and V uniformly from a feed's implied vol, because feeds give IV but
not full greeks. The conventions are European exercise, continuous compounding, no dividends, theta
per calendar day, vega per one vol-point, and a 365-day year. The risk-free rate `r` is a plain
parameter — the Python twin read it from the environment at import with a default of zero, and
here the read stays in the consuming binary; pass `0.0` to match. `black_scholes_price` and
`black_scholes_greeks` share one `d1_d2` site, and every transcendental — `erf`, `exp` and `log` —
comes from the `libm` crate rather than the platform: IEEE 754 requires `+ - * /` and `sqrt`
correctly rounded and requires nothing of `exp` and `ln`, so the MSVC runtime and glibc are each
entitled to a different last bit. `sqrt` deliberately stays on `f64`. The module records that it was
half-converted for a while — `libm::erf` two lines above an `x.ln()` — and states the lesson: a
half-converted file is worse than an unconverted one, because a nearby `libm::` spelling is exactly
the evidence a reader uses to decide not to look.

`implied_vol` inverts the price by bisection over sigma in `[1e-4, 5.0]`: 64 fixed steps with a
`1e-6` absolute early exit, ported verbatim because the iteration shape is part of the oracle
contract, and `None` when the price sits outside the no-arbitrage band. `enrich_quote` fills a
quote's greeks from its IV and returns it unchanged when they are not computable.

<Callout type="warn" title="The parity tiers, and what may never be re-recorded">
  Pure-arithmetic sites — days to expiry, windowing, scaling, the non-theoretical columns, format
  strings — gate exact, as hex bits. Outputs derived through `erf`, `exp` or `log` gate at ≤1e-12
  relative against CPython-pinned bits. Neither tolerance is ever widened, and a pure-arithmetic site
  is never reclassified to the relative tier. The constants are the frozen oracle, and if one ever
  moves out of tier that is a stop to be argued, not a number to repaste.
</Callout>

## Second-order greeks [#second-order-greeks]

`second_order.rs` adds vanna, vomma, charm, veta and color on the same `d1`/`d2` and density
internals. It is not an oracle port — the Python twin stops at first order — so it is verified by
finite differences against the crate's own first-order greeks, ≤1e-6 relative for every greek,
calls and puts. Charm, veta and color are reported per calendar day as passage-of-time derivatives,
negative when the quantity decays as the clock runs, so veta reads negative for an at-the-money
option at `r = 0`; published tables mix that sign convention row by row, and the finite-difference
gate pins this one. Vanna and vomma are raw annualized sensitivities per 1.0 of sigma — divide by
100 for the per-point scale of the first-order vega. With no dividends the only kind-dependent terms
vanish, so every greek here is identical for calls and puts, and the equality is asserted in tests.

## Baskets [#baskets]

`basket.rs` is the multi-leg analytics: expiry payoff, break-evens, maximum profit and loss, net
greeks across both orders, and probability of profit and expected value under a lognormal terminal
law. A `Leg` carries a signed quantity — positive long, negative short — and a non-negative
per-unit premium, so `net_premium` is `Σ qty·premium` with positive meaning a debit paid.
`payoff_at` is P\&L at expiry per 1.0 of underlying; contract multipliers are the caller's business.
The domain is `S_T ∈ [0, ∞)`: a price cannot go below zero, so the downside is always bounded and
only the upward ray can be `PayoffBound::Unbounded`, decided by the slope beyond the highest strike.
Summation is a naive left fold in leg order, so `net_greeks` is bit-identical to summing the per-leg
calls in the same order; the expected-value integral is a fixed-grid composite Simpson, and the
whole module is deterministic — no RNG, no I/O, no clock.

## Realized vol and the IV–RV read [#realized-vol-and-the-ivrv-read]

`vol.rs` has no Python twin. `EwmaVol` is the RiskMetrics recursion with `λ = 0.94` for daily data,
seeding the variance at the first squared return rather than at zero; `RollingVol` is the sample
standard deviation over a window. Both stream `update(price)` / `value()` over log returns computed
with `libm::log`, ignore non-finite or non-positive prices so a bad tick cannot poison the fold, and
report per-period vol — annualize with `DAYS_PER_YEAR` (365, matching the greeks' basis; an
equities caller passes 252). `atm_iv` picks the strike nearest the forward `F = S·e^{rT}`, averaging
call and put IV where both are present; `iv_rv_spread` is the plain difference, positive when
implied trades rich. The module says its own materiality is low: nothing outside the file calls
these yet, and they were made portable before a consumer arrived because that is the cheap moment.


# Order lifecycle (/docs/trader/concepts/order-lifecycle)



An order in Vike Trader is a `ManagedOrder` — `crates/vike-exec/src/order.rs` — and its status is
a finite state machine. `ManagedOrder::apply` is the **only** mutator of order state: it looks the
transition up in a table, returns `InvalidOrderTransition` on an illegal edge, and accumulates
fills into `filled_qty` and a running volume-weighted `avg_fill_px`. The one other writer is
`ManagedOrder::resolve_pending_cancel`, documented as *the ONE restore*: the engine fold's
cancel-race guard calls it immediately before `apply` to recompute a `PendingCancel` order's
pre-cancel status from its own fill stream, and it is a no-op from every other state.

## The states [#the-states]

| state                                                     | meaning                                                               |
| --------------------------------------------------------- | --------------------------------------------------------------------- |
| `Initialized`                                             | built locally, not yet sent                                           |
| `Submitted`                                               | sent; emitted by the Rust side synchronously at submit                |
| `Accepted`                                                | the venue acknowledged a resting order                                |
| `Triggered`                                               | a conditional order's trigger condition was met                       |
| `PartiallyFilled`                                         | some quantity executed, some resting                                  |
| `PendingCancel`                                           | a cancel is in flight                                                 |
| `Emulated`                                                | a conditional order held client-side, for venues without a native one |
| `Released`                                                | an emulated conditional released to the venue                         |
| `Liquidated`                                              | a perpetual force-close — a live state, deliberately not a terminal   |
| `Filled` · `Canceled` · `Rejected` · `Denied` · `Expired` | the five **terminal** states                                          |

`Rejected` is the venue's refusal; `Denied` is the risk gate's veto, pre-venue.
`OrderStatus::is_terminal` names exactly those five, and once an order is in one of them any
further lifecycle event for it is an illegal transition — dropped idempotently at the engine's
fold, never applied. `Liquidated` is excluded from that set on purpose, yet `OrderStatus::is_live`
— the cancel-send gate, "is a cancel still worth sending?" — excludes it too; the two disagree on
that one state by design, and a test pins the disagreement.

## The transition table [#the-transition-table]

`order.rs`'s `transition` is the table, verbatim:

| event                  | allowed from                                                | to                |
| ---------------------- | ----------------------------------------------------------- | ----------------- |
| `OrderSubmitted`       | `Initialized`                                               | `Submitted`       |
| `OrderAccepted`        | `Submitted`                                                 | `Accepted`        |
| `OrderRejected`        | `Initialized`, `Submitted`                                  | `Rejected`        |
| `OrderDenied`          | `Initialized`                                               | `Denied`          |
| `OrderTriggered`       | `Accepted`                                                  | `Triggered`       |
| `OrderPartiallyFilled` | `Accepted`, `Triggered`, `PartiallyFilled`                  | `PartiallyFilled` |
| `OrderFilled`          | `Accepted`, `Triggered`, `PartiallyFilled`                  | `Filled`          |
| `OrderCanceled`        | `Accepted`, `Triggered`, `PartiallyFilled`, `PendingCancel` | `Canceled`        |
| `OrderExpired`         | `Accepted`, `Triggered`, `PartiallyFilled`                  | `Expired`         |
| `OrderLiquidated`      | `Accepted`, `Triggered`, `PartiallyFilled`                  | `Liquidated`      |

Two edges look wrong and are not: `PartiallyFilled → Canceled` and `Accepted → Canceled` are both
allowed, because a venue may cancel the sibling leg of a one-cancels-other pair server-side while
that leg has already partly filled. Three events are not transitions at all. `OrderModified` is a
self-transition legal only in the modifiable set (`Accepted`, `Triggered`, `PartiallyFilled`): it
rewrites the resting quantity and the limit or trigger price — whichever the order actually rests
on — and leaves the status alone. `OrderCancelRejected` and `OrderModifyRejected` are
non-terminal advisories: the order stays live and keeps its terms, and they are legal only while
the request they refuse could have been in flight.

<Callout title="Two sets that coincide today and are deliberately kept apart">
  `CAN_RECEIVE_CANCEL` answers "may this order receive `OrderCanceled`?" and `is_live` answers "is a
  cancel worth sending?", and they differ on `Submitted`: a cancel may be sent to a submitted order,
  yet a venue-honoured cancel of it returns an illegal transition and is dropped — masked in practice
  by in-order delivery, since the accept lands first. `CAN_RECEIVE_LIQUIDATION` exists because that
  question was once answered in two places that disagreed: the table spelled the set inline while
  the engine's liquidation picker selected by negation and admitted five states the FSM refuses, so
  the pick landed on an order `apply` then rejected. Both pairs are pinned by tests, so a coincidence
  of membership is observed rather than assumed.
</Callout>

## The three rules a venue may not break [#the-three-rules-a-venue-may-not-break]

The state machine is shared; what varies is the venue's decoder. Three rules pin what a decoder
must do, and they are the contract every bridge is held to:

1. **Emitter split.** The Rust side emits `OrderSubmitted` synchronously at submit. The venue side
   emits `OrderAccepted`, `OrderRejected`, `OrderCanceled`, `OrderFilled` and
   `OrderPartiallyFilled`.
2. **No silent vanish.** A dead venue path must synthesize a terminal `OrderRejected`. An order that
   was submitted and never heard from again is a bug, not a state.
3. **Exactly one terminal.** The state machine must reach exactly one terminal state. Illegal or
   out-of-order events — a late cancel replay after a fill, a duplicate fill on reconnect — are
   dropped without corrupting the terminal already reached.

## The harness that holds them [#the-harness-that-holds-them]

The rules used to be verified ad hoc, per venue. They are now one scenario table run against every
covered venue's **real** `event_mapper` plus the shared execution plumbing:
`crates/vike-bridge-core/tests/bridge_conformance.rs`. The invariant oracle is the real state
machine — `vike_exec::ManagedOrder::apply`, the same code the live core folds through — wrapped by
`ContractOrder`, which mirrors the engine's thin per-order policy: the bare `Fill` goes to the
account side and never touches the FSM, the wrapping `OrderPartiallyFilled`/`OrderFilled` advance
it deduplicated by `trade_id`, and a terminal event that fails to apply while the order is still
live is counted as a genuine loss. Each venue plugs in only its venue-native frames and its
fixture-tested decoder; the scenarios, the folds and the assertions are shared.

| scenario          | what it proves                                                                                                                                                             |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Lifecycle         | submit → accept → partial fill → full fill reaches `Filled`, one terminal                                                                                                  |
| TransportDeath    | a dead venue path still synthesizes a terminal, through the exact seam that venue uses — the command actor or the ambiguous-submit resolver                                |
| CancelAfterClose  | a late venue `OrderCanceled` replay and a late `OrderCancelRejected` after the order closed are both dropped without corrupting the terminal                               |
| ReconnectMidOrder | driven through the real shared pump with a scripted drop and reconnect that replays the mid-order partial: no duplicate terminal, no double-counted fill, no lost terminal |

<Callout title="Every roster venue is either covered or deferred with a reason">
  `conformance_roster_is_exhaustive` checks the covered and deferred lists against
  `vike_model::VENUES`, so a new bridge crate cannot join the roster and silently escape the harness
  — it reddens until it is wired in or deferred with a written reason. The crypto venues with a
  fixture-tested private-WS decoder run the cumulative-fill variant; the FX, CFD and equity venues
  run a whole-fill variant, because their decoders have no partial-fill path at all. One native-SDK
  venue has no wire: its fill and cancel envelopes are JSON a C++ shim builds, and its row says
  explicitly what a green result does *not* say about the SDK behind it, which no CI machine can
  compile. The harness prints the whole matrix, so no coverage fraction is written here.
</Callout>

## What comes next [#what-comes-next]

Each event the state machine consumes has its own page under
[events](/docs/trader/concepts/events/), generated from the `Event` enum so the list cannot drift from
the code. The [ExecutionClient seam](/docs/trader/concepts/execution-client-seam) is where those events
come from; [the account](/docs/trader/concepts/account) is where the bare fill goes instead; and the
[reconciliation](/docs/trader/concepts/reconciliation/) pages are what happens when the venue's view and
this state machine's view disagree.


# The paper exchange (/docs/trader/concepts/paper-exchange)



When a venue is mounted paper — the default under both [gates](/docs/trader/concepts/risk-and-arming),
an unset arming ceiling and absent credentials alike — the
[ExecutionClient](/docs/trader/concepts/execution-client-seam) behind the engine is
`vike_paper::PaperExecutionClient`. It is not a stub that acknowledges orders. Its own doc states
what it does: `submit` publishes `OrderSubmitted` and `OrderAccepted` and rests the order; `on_bar`,
driven by the core on each closed bar of the mounted series, fills the book with the engine's exact
semantics — next-open market fills, limit and stop triggers, adverse-first intrabar resolution,
slippage plus maker/taker fees. What it fills them *with* is the point of this page.

## Built from the engine's own primitives [#built-from-the-engines-own-primitives]

`crates/vike-paper/src/lib.rs`'s module header states the design: the paper client owns a resting
book and fills it with the **engine's own** public fill primitives —
`vike_fills::fill_model::BarFillModel::fill_price`,
`vike_fills::fill_resolution::resolve_intrabar_fills`, `vike_fills::broker_sim::adverse_fill_price`
and `vike_fills::broker_sim::fee`. `crates/vike-fills/src/lib.rs` says why those live where they do:
the paper exchange and the backtest engine are the *same cost model seen from two sides*, and a
paper client mounted on a live feed must charge exactly what `SimBroker` charges or
"backtest == paper == live" stops being checkable. There is one definition of what a fill costs
and when it happens, and both sides call it — so `backtest == paper` holds by construction rather
than by two implementations happening to agree. See
[fill models](/docs/trader/backtesting/fill-models), [fill resolution](/docs/trader/backtesting/fill-resolution)
and [the cost model](/docs/trader/backtesting/cost-model) for the primitives themselves.

That is possible because of the [layering rule](/docs/trader/concepts/architecture) this workspace keeps
re-learning: when two sides must not disagree, the cure is a shared crate **below** both. The paper
client's header carries the history: it was folded *into* the backtest crate precisely to guarantee
one fill definition, when co-location was the only way to guarantee it; once `vike-fills` existed,
the two could share a dependency instead of a crate, and `vike-paper` split back out. The payoff
is on the consumer side — `vike-mount` and `vike-run` had referenced the backtest crate for this
client and nothing else (12 and 4 sites), compiling the entire simulator to obtain an
`ExecutionClient`.

## The gate that proves it [#the-gate-that-proves-it]

`crates/vike-backtest/tests/r7_gate.rs` takes the same strategy and the same bars, runs them through
the backtest engine and through the live core in paper mode, and requires **bit-identical** fills
— timestamp, side, quantity, price, fee, maker flag — plus identical realized PnL, fees and final
position, every float compared through `to_bits`. The strategy logic is defined once, as a shared
signal function, and mounted through each runtime's own trait; so the gate proves the *runtimes*
agree, not that two copies of a strategy happen to. The gate stays in the backtest crate rather than
beside the client because it drives the engine *and* the live core, not the client alone.

It proves the conditional verbs too. The stop-verb row agrees when the engine is configured with
`EngineParams::emulator_release_stops = true` — the fired conditional releases as a market order
and fills at the next bar's open, which is what live always does through its emulated
`ConditionalBook`. The bracket row — an entry with a protective stop and a resting take-profit —
agrees through the paper book's one-triggers-other / one-cancels-other triple: both stops fill via
the one trigger oracle, and both sides cancel the surviving exit. The resolver those brackets share
is [contingent orders](/docs/trader/concepts/contingency).

<Callout title="The chain this closes">
  The frozen golden fixtures prove the Rust backtest has not changed its arithmetic unnoticed; this
  gate proves the Rust backtest equals the Rust paper core. Together, the paper mode a strategy is
  first run against is the same arithmetic its backtest report was computed with — see
  [the parity gate](/docs/trader/concepts/parity-gate).
</Callout>

## Where the equivalence stops, stated rather than implied [#where-the-equivalence-stops-stated-rather-than-implied]

The header scopes the law precisely. It holds for `Gtc`, `Ioc` and `Fok` — everything both sides
treat as "rests until filled or cancelled". It does **not** hold for the expiring time-in-forces,
`Gtd` and `Day`: the paper client enforces their resting deadline (`expire_due`), while
`StrategyEngine`/`SimBroker` ignore time-in-force entirely, so for such an order the engine keeps
resting and filling where paper expires. Nothing gates that divergence — the gate only exercises
`Gtc` — and nothing in the tree produces a non-`Gtc` order into either side today, so it is
unreachable from a strategy; the header names mirroring the sweep in `StrategyEngine::fill_pending`
as the follow-up that would close it. Two details of the paper side's own expiry are worth knowing
before reading a paper fill: `Ioc`/`Fok` are *not* enforced there and rest exactly like `Gtc`
(they are immediate-execution semantics, a change to the parity-gated fill pass, not a resting
deadline), and a `Day` order is scoped to the **UTC calendar day of the first bar it sees**, never
to the request's own timestamp, because nothing on the write path stamps one.

One more edge. The engine's *default* stop semantics — a same-bar fill at the trigger —
deliberately diverge from live, where a stop is always emulated and releases as a market order.
That divergence is pinned by its own law test in the backtester (`tests/laws/trigger_law.rs`), not
by this gate; the gate proves agreement under the configuration that matches live.

<Callout type="warn" title="A mount arms the halt sentinel; a simulation must not">
  `crates/vike-ops/tests/paper_mount_arming_gate.rs` classifies every file that constructs a
  `PaperExecutionClient`: a mount seam must arm the operator [halt](/docs/trader/concepts/halt) sentinel,
  and a simulation must not. The second half is not symmetry for its own sake — the r7 gate drives
  this same client, so a sentinel read on a simulation path would make backtest fills depend on a
  file lying around in `<project>/settings/state/` and redden the equivalence gate for a reason
  nobody would find. The gate exists because a documented "each mount seam asserts on this" claim
  was already false when it was written: a third seam existed, unarmed, and per-seam assertions are
  evidence about the seams that have them, never about the set.
</Callout>


# The parity gate (/docs/trader/concepts/parity-gate)



Vike Trader's pure cores — the fill primitive, the fill triggers, the consolidators, the cost
scalars, the event engine, the vectorized kernel, the sizing math, the account read-model — are
held to **bit-identical** `f64` results against committed fixtures. Not "close enough", not a
relative tolerance: the same IEEE-754 bit pattern. This page is what that means, why it is still
true after the thing the fixtures came from was retired, and the one rule that must survive any
future relaxation.

## The fixtures are frozen, and that is why the comparisons stay exact [#the-fixtures-are-frozen-and-that-is-why-the-comparisons-stay-exact]

`fixtures/r0..r6/` were exported from an earlier implementation of the platform; each carries a
`manifest.source_sha` pinning the commit that exported it. Every exporter was later deleted from
the tree, so — as `crates/vike-backtest/tests/parity.rs`'s header puts it — **the committed bytes
ARE the oracle**: there is no environment to regenerate from, no network, no external process, and
nothing to drift. Floats are stored as hex bit patterns and read back through
`vike_model::f64_from_hex_bits`; the `r1_parity`/`r3_parity`/`r4_parity` golden gates in that
binary compare them exactly. (Those three described themselves as "parity vs the Python oracle"
until 2026-08-28; the provenance is unchanged, the ongoing-comparison reading was never true after
the exporters went.)

What those gates prove is precise and worth stating precisely: that **this** code has not changed
its arithmetic unnoticed. They do not prove ongoing agreement with anything external, because
nothing external is run. The [decision record](/docs/trader/developer/decision-records) that retired the
oracle is explicit about the half that matters most:

<Callout type="warn" title="What retiring the oracle does NOT license">
  Every committed golden fixture keeps its exact comparison. The rule that dies is "a new port must
  reproduce the old implementation bit-for-bit" — new work needs no external twin. The rule that
  **survives** is "never widen a tolerance to make a failing test pass; investigate the divergence."
  It was never really about the old implementation. It is about a number that moved for a reason
  nobody has named yet, and it applies to every gate in the tree. Relaxing an existing assertion
  needs its own argument: name the mechanism, keep the comparison exact against a *stated function*
  of the reference rather than a tolerance band, bound the raw reference value too, and add a
  control that fails if the relaxation turns out to be a no-op.
</Callout>

## The hardest-won detail: `sum()` is not a fold [#the-hardest-won-detail-sum-is-not-a-fold]

`crates/vike-model/src/pysum.rs` records the single most instructive divergence the gates ever
caught: CPython 3.12 and later compute the builtin `sum()` over floats with **Neumaier compensated
summation**, not a naive left fold. A ported site that the original wrote as `sum(...)` must
therefore use `vike_model::py_sum`, while an explicit `acc += x` loop stays a naive fold — mirrored
per site. Getting it wrong is a guaranteed last-ulp divergence, caught by the bit-gates on
2026-07-03. The lesson generalises: bit parity is a property of *operation order*.
`crates/vike-model/src/fill.rs`'s `compute_fill` says it outright — do not reorder operations,
introduce `mul_add`, or "simplify" — and `vike-fills` carries the same rule for the cost scalars.
Even container choice is part of it: `crates/vike-exec/src/account.rs` keeps every map an
`IndexMap`, &#x2A;*never a `HashMap`**, because insertion order *is* the `f64` fold order the gate pins
against `fixtures/r0/account_scenarios.json`.

## Why the exactness is portable [#why-the-exactness-is-portable]

A pinned constant usually survives a platform change by luck — two platform maths libraries
agreeing on the inputs it happened to sample. `parity.rs`'s header argues that hazard does not
reach these gates, by construction: every module they drive reaches no transcendental function and
no integer power, only `+ - * /`, which IEEE 754 requires to be correctly rounded. It tells the
reader to grep those modules for a libm-class call before trusting the paragraph, because
introducing one is what would make the fixtures platform-sensitive and nothing else in the suite
would say so. Elsewhere in the tree, where transcendentals *are* needed, a separate decision record
routes them through the `libm` crate rather than the platform — the property bought is
**reproducibility, not accuracy**; the two platforms are differently wrong at the last bit, and
the change makes them identically wrong everywhere.

## The second oracle, and the third [#the-second-oracle-and-the-third]

Golden fixtures only pin examples. `engine_kernel_parity`, in the same binary, runs the event
engine (`StrategyEngine`) and the vectorized kernel (`VectorBacktestEngine`) on identical synthetic
bars and requires the same trade count and a **bit-identical final equity** — both are naive-fold
`f64` paths over the same inputs, and its own header says never to widen it to a tolerance. It is
the workspace's second oracle, and it keeps working as strategies are added because it compares two
things that both run rather than one thing against a frozen file. `rhai_parity` is the third: a
Rhai script and its Rust twin must produce a byte-identical `BacktestResult`.

<Callout title="Where this connects">
  The [paper exchange](/docs/trader/concepts/paper-exchange) carries the next link in the chain: the
  backtest engine equals the live paper core, bit-for-bit, under `r7_gate`. And the
  [indicator](/docs/trader/indicators/) crate holds a parity of its own —
  `crates/vike-indicators/tests/parity.rs` proves every registered indicator's streaming `on_bar`
  fold equals its batch `vectorize`, bitwise, with both-NaN counted equal; the three `batch_only`
  indicators that read future bars (`ichimoku`, `zigzag`, `williams_fractal`) are skipped by name,
  their output shape still gated.
</Callout>

## Committing a counterexample [#committing-a-counterexample]

Property tests randomize the pure cores where fixtures only pin examples —
[property tests](/docs/trader/developer/testing/property-tests) lists the suites. When one finds a
counterexample in CI, the generated regression seed is **committed**, so the failure reproduces on
every machine rather than depending on the random draw that found it. Adding a fixture, a property
suite or a seed is the procedure on [adding to the parity suite](/docs/trader/developer/testing/parity).


# Portfolio and snapshot (/docs/trader/concepts/portfolio-and-snapshot)



`crates/vike-core/src/snapshot.rs`'s `CoreSnapshot` is the immutable state view the core
publishes to the window through arc-swap. The GUI is a lossy downstream observer: it reads the
latest snapshot on repaint and can never back-pressure the core.
`crates/vike-core/src/portfolio.rs`'s `Portfolio` is the named cross-venue aggregator inside it,
and `crates/vike-core/src/runtime/publish.rs` is the publish. This page is written from those
three.

## When a snapshot is built [#when-a-snapshot-is-built]

Snapshots are built coalesced, never per event while busy: dirty-flagged, at most once per
`CoreConfig::snapshot_interval` while the queue is busy — the interval is a minimum spacing, not a
deadline — and immediately whenever the core is about to go idle — `if self.dirty` directly before
`blocking_recv`. On a venue whose events arrive sporadically that idle path publishes per event,
which is why anything `CoreSnapshot::build` does is per-event work; the
[execution core](/docs/trader/concepts/execution-core) page carries that consequence. `seq`
increments per publish for change detection, and the build cost is measured in the latency
harness.

`publish_guarded` wraps the build and the GUI's repaint hook in `catch_unwind`: neither may kill
the core thread. On a panic the engine is halted and a minimal fault snapshot is stored —
`trading_state: Halted`, `fault` set — so the window still sees terminal state, never a stale
active cell. The recent-events ring holds already-rendered lines, so publish is a refcount bump
per entry, and an opt-in memory-mapped counter mirror is written at this same cadence.

## What the snapshot carries [#what-the-snapshot-carries]

Beyond the primary engine's `trading_state`, `balance` and `balance_mode`, a snapshot holds
`portfolio`; `positions` and `marks`; `orders`, the registry in insertion order across every
engine; `held_exits`, the pending bracket exits held off the venue until their OTO parent fills,
which have no registered order and would otherwise be invisible; the core-owned `bars` cache,
shared by pointer; `mounts`; `recent_events`; `fault`; `conflated_market_drops` (latest-wins
working, not a bug) and `rejected_commands` (never silent); the `recon` block of held
divergences awaiting an operator confirm plus the last pass timestamp; and `recon_coin_deltas`,
populated only by a venue whose position report carries a delta — Deribit today — so the
greeks tool can fold a perp or future hedge leg.

Each `PositionView` carries the resolver-priced `unrealized` and the `mark_source` that priced
it (`None` means unpriceable), the effective `leverage`, an estimated `liq_price`, the
`margin_mode` and any `isolated_margin`. Each `VenueBlock` — one per engine, primary first —
carries balance, realized PnL, fees, funding, `balance_mode`, resolver-priced `equity` and
`unrealized`, the `missing_prices` count, `margin_used`, `free_bp` and `margin_ratio` (computed
only when the margin gate is armed, so the default path stays zero-cost), the effective
`fee_schedule`, the venue's `trading_state`, and the contract-multiplier grid shared with the
engine's account by `Arc` — the whole grid, because the window needs a multiplier for symbols
it holds no position in. `CoreSnapshot::build` does one resolve per engine through the
[price board](/docs/trader/concepts/price-board), so a block's equity, its unrealized total, its
missing count and every position's mark source come from the same read.

## The mount rows and the residual [#the-mount-rows-and-the-residual]

`mounts` holds one `MountView` per live strategy mount — venue, symbol, interval, `ready`, and
the per-mount attribution: net position, realized PnL net of fees, unrealized PnL, notional, any
budget and whether it latched. When any mount exists the vector carries one trailing row,
`MountRowKind::Residual`: the account's realized PnL net of fees minus the sum of every mount
row's. Attribution is keyed by client order id, an un-minted id is simply not attributed, and
nothing used to sum the two sides — so the mount rows and the account disagreed systematically
and silently. With the row, `Σ mount rows + residual == account realized (net)` is an invariant
anything can assert, and manual tickets, margin-call and budget-latch liquidations,
reconcile-adopted orders and fills whose mount could not be reconstructed across a restart all
land there visibly. Read `kind` before treating a row as a mount.

## The portfolio [#the-portfolio]

`Portfolio` groups what used to be loose scalars: `equity` (the primary engine,
resolver-priced), `equity_total`, `realized_pnl`, `fees_paid`, `funding_paid`,
`margin_used_total`, `capital_base`, `missing_prices_total`, the per-asset
`balances_by_asset` ledger, and the `venues` blocks. It is a naming reshape — no value changed —
with a read-only query surface over the blocks: `venue(name)`, `equity(venue)`,
`unrealized_pnl(venue)`, `net_position`, `gross_position`, `is_net_long`, `is_flat`,
`position_count` (rows, not open positions), and `missing_price_instruments`, which names the
`(venue, symbol)` pairs the count only counts. None of it runs on the fold.

<Callout type="warn" title="equity_total is heterogeneous — do not print it as one figure">
  A `VenueBlock`'s `equity` answers a different question depending on its `balance_mode`. A
  `Delta` block is the daemon's own book-keeping from a configured seed — `seed + own cash flow +
  realized + unrealized` — an assertion about this mount's trading, which is why it can be summed
  across venues. An `Authoritative` block is the venue's attested wallet for the whole account the
  credentials open, adopted verbatim by reconcile or an account-state push, and the daemon cannot
  tell whether that account is dedicated to it: cash is fetched account-wide while positions and
  fills are symbol-scoped. Measured on prod2 on 2026-08-17: nine paper mounts at 1000 seed each
  plus one bybit mount that had adopted a shared account's 53647 USDT wallet summed to a headline
  `equity_total` of 62647.10600813 — neither the account's cash nor the daemon's book. The value
  is unchanged; the honest split sits beside it as `equity_book_total` and `equity_wallet_total`,
  which partition it by mode, and `wallet_venues` names whose wallets were added. They do not sum
  back to `equity_total` bit-for-bit, because each is its own compensated sum over a subsequence.
</Callout>

<Callout type="warn" title="The scalar realized_pnl is the primary engine's only">
  `realized_pnl`, `fees_paid` and `funding_paid` on the portfolio are bound from the primary
  engine's account, so on a multi-venue core they answer about whichever venue is registered
  first. Measured on prod2: the daemon's summary line read `realized_pnl: 0.0` from an untraded
  binance primary while `equity_total` tracked a bybit mount's ten maker fills to eight decimals.
  A report that carries `equity_total` must fold `realized_pnl_total`, `fees_paid_total` and
  `funding_paid_total` — the same compensated sum over the same vector in the same order.
</Callout>

## The risk curve [#the-risk-curve]

`capital_base` is the operator's configured capital, `Σ seed_cash` in venue registration order:
a config constant, not an observation, identical across a restart and untouchable by a third
party moving money in a shared account. A portfolio built off the node wire reports `0.0`
there, which is honest — the observe path has no seeds and drives no alerting — and `0.0`
means unknown, never "no capital". `pnl_total` is the daemon's own profit and loss across every
venue, `realized − fees + funding + unrealized`, mode-blind and carrying no balance level, so a
wallet movement with no trading behind it does not move it. `drawdown_curve` is
`capital_base + pnl_total`: the quantity the [watchdog](/docs/trader/concepts/watchdog)'s drawdown
latch folds its high-water mark on and the [alerting](/docs/trader/concepts/alerting) drawdown rule
compares against, pinned bit-identical between the two. Use it, not `equity_total`, for any
drawdown fraction — and guard a non-positive value rather than divide by it.


# The price board (/docs/trader/concepts/price-board)



`crates/vike-exec/src/price_board.rs`'s `PriceBoard` is where every price the core hears is
kept, tagged by where it came from. Its write side sits on the hot fold and does nothing but
store; its read side runs only on cold paths — snapshot publish, sweeps, timers — and answers
one question: what is this position worth to me right now, if I had to act on it. The board is
deliberately not serialized: it sits outside `EngineSnapshot`, so the
[journal](/docs/trader/concepts/journal/)'s determinism-fence hash is untouched. This page is
written from that module and from `crates/vike-exec/src/account.rs`'s `MarkSource`.

## The cell [#the-cell]

A `PriceCell` holds five optional `(price, timestamp)` slots: `mark`, `bid`, `ask`,
`last_trade`, `bar_close`. The timestamp is the producer's where the lane carries one, else the
dispatch clock. Every write is unconditional and source-tagged by construction, so a candle
close and a venue mark both land without either destroying the other — which is why no
precedence question arises on the write side. A zero, negative or `NaN` price is ignored and
creates no slot; a quote with one dead side stores only the live side. Cells are keyed by
`(venue, symbol)` in insertion order.

## The valuation law [#the-valuation-law]

`PriceBoard::classify` walks the slots in a fixed order and returns at the first fresh one. The
ordering *is* the law — a rung is consulted only when every rung above it is absent or stale:

| rung | slot          | meaning                                                                                                                                                                            | who fills it                                                                                                                                                                                                                                                                                                                                              |
| ---- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1    | `mark`        | the venue's own mark or index price — what its liquidation and funding engines key off; the only price that answers "will I be liquidated"                                         | the crypto perps' mark streams (binance-family `@markPrice@1s`, bybit `tickers.markPrice`, okx `mark-price`, hyperliquid `activeAssetCtx.markPx`), each on by default; aster's is off until `VIKE_MARK_STREAMS_ASTER=1`, and `VIKE_MARK_STREAMS=0` turns them all off. On any venue, also a fill's `mark_price` and a reconcile pass's `position_mark_px` |
| 2    | `bid` / `ask` | the live top of book, read side-aware: a long at the bid, a short at the ask — the side it would have to cross to exit, so the spread is booked against the position, never for it | any venue with a quote or L2 feed (`set_quote`)                                                                                                                                                                                                                                                                                                           |
| 3    | `last_trade`  | the last price something actually traded at — real and recent, but one-sided and already stale when it lands                                                                       | any venue with a trade feed, including one subscribed only because a chart asked                                                                                                                                                                                                                                                                          |
| 4    | `bar_close`   | the close of the last completed candle — a minute old on a 1m chart, an hour on a 1h one                                                                                           | every kline feed, every venue                                                                                                                                                                                                                                                                                                                             |
| 5    | last-known    | not a slot: the same four rungs walked again with the freshness gate relaxed, taking the highest-priority slot holding any value however stale                                     | the freshest surviving slot                                                                                                                                                                                                                                                                                                                               |

`resolve` is a thin projection of `classify`: `Fresh` becomes `Resolution::Priced { px, source,
ts }`, `Missing` is a first-class answer, and rung 5 becomes `Resolution::Stale` only when the
caller opted into `PriceCfg::stale_fallback`, so a consumer valuing off it *knows* it is stale.
`classify` itself is independent of that knob and always reports fresh, stale or missing, so an
operator query can see "priced but stale" even when valuation will not fall back to it.

<Callout title="Freshness is off by default">
  Every `PriceCfg` max-age field defaults to `None` and `stale_fallback` to `false`, so a caller
  that has not opted into a window sees the pure priority order, nothing is ever stale, and rung 5
  is unreachable. A fresh venue mark early-returns at rung 1, so the common case pays for one
  slot check. `use_mark: false` drops the mark rung from both walks.
</Callout>

## Why the candle close is last [#why-the-candle-close-is-last]

Before the mark-slot split, every kline feed wrote its close into the `mark` slot, so a stale
candle outranked a live quote and a live trade on the same symbol. Putting the close at the tail
is a real, intended behaviour change on every venue that has no venue mark but does have a
quote or trade feed running — alpaca, IBKR, binance spot, an aster perp not opted into its mark
stream, any perp under `VIKE_MARK_STREAMS=0`: those positions are now valued at the live
side-aware quote or the last trade instead of the candle close. Valuation moves by up to the
spread, toward the price the position could actually be exited at.

## Missing prices [#missing-prices]

`PriceBoard::note` keeps a per-venue set of symbols whose resolution came back `Missing`. The
first insertion of an episode warns once — *no price for open position — subscribe to quotes,
trades or bars for continuous mark-to-market* — and a `Priced` or `Stale` resolution removes
the symbol, re-arming the warning for the next episode. The equity sampler (see
[timers](/docs/trader/concepts/timers)) notes every open position once per sample; the snapshot
surfaces the count as `VenueBlock::missing_prices` and each position's `mark_source: None`, and
`Portfolio::missing_price_instruments` names the pairs.

## The board is not the account mark slot [#the-board-is-not-the-account-mark-slot]

`Account.marks` is the opposite shape: one untagged scalar per symbol, written by the same lanes
and read by the pre-trade gate, the [margin-call](/docs/trader/concepts/margin-call) law and
`LiveBroker.price`. Its precedence rule lives in `vike_exec::MarkSource` and is enforced inside
`Account::set_mark_from`, the only door into that map. A genuine venue mark — streamed
(`VenueMark`) or reported by a reconcile snapshot (`ReconcileMark`, ranked equal) — owns the
slot for a window: `DEFAULT_MARK_STALENESS_MS` is 10 000 ms, about ten missed ticks of a 1s
stream, and `DEFAULT_RECONCILE_STALENESS_MS` is 150 000 ms, 2.5× the default reconcile
interval, so a reconciled stream-less venue's slot stays owned continuously between passes
rather than alternating with candle closes every minute. A mark stream that dies hands the slot
back after its window and closes resume, so valuation degrades to the previous rung instead of
freezing at a stale mark. The module doc is explicit that the board must not reimplement that
rule: a freshness predicate on the board is how an earlier round of the fix ended up bypassable
by every lane that did not happen to call it.

## Who reads it [#who-reads-it]

`ExecutionEngine::resolve_equity` builds a whole `ResolvedEquity` — equity, unrealized total,
the missing count and one `ResolvedPosition` per position — from one resolve per engine, so the
[snapshot](/docs/trader/concepts/portfolio-and-snapshot)'s `VenueBlock` and every `PositionView`
come from the same read. Its scalar twin `resolved_equity` is the decision-path entry point:
the liquidation watchdog, the drawdown latch, the armed margin gate, a strategy's `ctx.equity`
and the portfolio-snap journal all read equity through it, so an auto-liquidation acts on
exactly the number the operator sees. The readiness gate on a
[mount](/docs/trader/concepts/mounting) flips a pending mount to ready the moment either side of its
symbol resolves through its own engine's board.


# Risk and arming (/docs/trader/concepts/risk-and-arming)



Nothing in Vike Trader reaches a real venue by accident. Between an order and the wire there are
four checks, and the order they run in is the point. The first two decide whether a venue is
*mounted* live at all; the third runs on every order after that; the fourth is the operator's
stop. This page is written from `crates/vike-config/src/venue_mode.rs`,
`crates/vike-mount/src/lib.rs`, `crates/vike-exec/src/risk.rs` and `crates/vike-exec/src/halt.rs`,
each the authority for its own gate.

## Gate 1 — the arming ceiling, read before any credential [#gate-1--the-arming-ceiling-read-before-any-credential]

`<project>/settings/policy.toml` carries a `[venues]` table:

```toml
[venues]
binance = "demo"
bybit   = "live"
```

Each value is a `vike_config::VenueMode` — `paper` \< `demo` \< `live`, an ordering encoded in the
type's own variant declaration — and it is a **ceiling**. `vike_mount::make_engine`, the one entry
point that builds a venue's execution client, consults it **first**, above the credential read: a
`paper` venue returns the paper client having loaded no credential, fetched no instrument grid and
opened no socket.

The ceiling can only ever refuse. `VenueMode::cap` is `min`, never `max`, and it is a named method
rather than a `.min()` at each call site for one reason: `a.max(b)` is one character from
`a.min(b)` and reads just as plausible, while the two differ by "the file can only refuse" versus
"the file can arm real money".

```rust
// A `live` ceiling over a demo-credentialled venue stays DEMO — the ceiling never promotes.
assert_eq!(VenueMode::Live.cap(VenueMode::Demo), VenueMode::Demo);
// A `paper` ceiling over a live-credentialled venue REFUSES it down to paper.
assert_eq!(VenueMode::Paper.cap(VenueMode::Live), VenueMode::Paper);
```

So `bybit = "live"` does not put bybit live. It declines to stop bybit going live if its
credentials and its mainnet flag already say so. The measured defect it closes: a daemon whose run
profile mounted one venue logged nine authenticated live sessions, none of them asked for, all a
consequence of credential pairs sitting in one file.

<Callout type="warn" title="A box with no [venues] table mounts all paper">
  The default is a filled map, one `paper` per roster venue — including venues this build cannot
  mount, because a `policy.toml` must be portable between a GUI box and a daemon. It is the one
  settings default in the workspace that changes behaviour, and it is deliberate: absence of the
  file must be the safest answer. Because "everything at paper" and "nobody wrote the table" produce
  the same map, `VenuePolicy::is_declared` records whether a file ever named a venue, and
  `vike_mount::venue_arming_migration` warns once at startup — naming the file, the key and the
  venues it refused — rather than refusing to start.
</Callout>

The ceiling is also the only refusal that exists for a venue with no other switch: Aster's mount
tries its live keys first and has no mainnet flag to withhold, which is the measured hole this gate
was built to close. A second account on a venue gets its own line under `[accounts]`, and a
labelled account with no line resolves to `paper` — the [accounts](/docs/trader/concepts/accounts) page
carries that grammar. Every key on this page is documented on the
[policy settings reference](/docs/trader/reference/settings/policy).

## Gate 2 — absent credentials are the live gate [#gate-2--absent-credentials-are-the-live-gate]

Only once the ceiling allows it does the older rule apply. A venue whose `{VENUE}_DEMO_*` keys are
present in the credential store spawns a real, credential-gated execution client; otherwise it
stays paper — `vike_paper::PaperExecutionClient`, a resting book behind the same seam. Three
refinements sit on this gate, each at the venue that needs it:

* **Mainnet is an explicit flag.** `{VENUE}_MAINNET` is the exact string `"1"`, read from the
  process environment or the store with the process winning. For the three CEX venues
  `make_engine` resolves it exactly once per mount (`cex_mainnet_enabled`) and threads a `bool`
  into the grid pre-fetch, the exec spawn and the reconcile client, so no spawned thread re-reads
  global state and a mount can never sign mainnet credentials against demo hosts.
* **A withdraw-capable key is refused.** The binance live arm consults
  `vike_bridge_core::key_permissions` before arming (`arming::binance_withdraw_gate`), so a key
  known to carry withdraw permission degrades that venue to paper instead of being discovered at
  the first order.
* **A venue with no testnet is gated twice.** Polymarket's only tier is real money, so
  `POLY_EXEC=1` mounts its execution client and `POLY_RECONCILE=1` independently mounts its
  reconcile client; both are unset by default.

A live mount also refuses to start without an account-dependent risk budget:
`MountError::MissingRiskBudget` names every missing `[risk]` key, because no universal safe default
exists for `max_notional_per_order` or `max_total_exposure`. A paper mount never sees it. The
[startup preflight](/docs/trader/concepts/startup-preflight) is the go/no-go probe that runs once after
mounting.

## Gate 3 — the RiskGate, on every order [#gate-3--the-riskgate-on-every-order]

`vike_exec::RiskGate` is one extensible stage every order crosses. It is **pure**: it owns no bus
and publishes nothing; the engine acts on its verdict, which is what lets the same rules run
identically in backtest, paper and live — a veto is an `OrderDenied` event, terminal and
pre-venue, in every mode.

Its limits are built at mount from the venue's own fetched `SymbolProperties`
(`RiskLimits::from_properties` — tick, lot and the two floors; a `0.0` field means unconstrained)
and from the run profile's `[risk]` table:

| limit                                  | what it does                                                                                                                                                                                                                                     |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `tick_size`, `lot_size`                | round the order onto the venue grid, round-half-to-even                                                                                                                                                                                          |
| `min_qty`, `min_notional`              | floors — on **opening** orders only; a pure reduce is exempt, so a position can always be closed                                                                                                                                                 |
| `max_notional_per_order`               | the per-order notional ceiling. It lives in `policy.toml`, and `Policy` implements neither the env nor the CLI override trait, so raising it from the environment is a compile error rather than a review comment                                |
| `max_total_exposure`                   | a cap on projected open notional — see the warning below                                                                                                                                                                                         |
| `max_orders_per_window`, `window_ms`   | a submission-rate throttle                                                                                                                                                                                                                       |
| `max_leverage`                         | the operator's declared cap, recorded for audit; enforcement is `im_requirement`, derived as `1 / max_leverage` so the two cannot disagree                                                                                                       |
| `price_collar`                         | the fat-finger axis: an opening order whose limit or trigger price sits further from the mark than `max(pct × mark, abs_floor)` is denied. Both halves are required — a percentage is useless on a cheap instrument, a floor on an expensive one |
| `max_slippage_bps`, `require_fillable` | an opt-in walk-the-book veto; inert until a caller holds both the intent and a live book                                                                                                                                                         |

Notional includes the contract multiplier, exactly as the backtest fill gate computes it, so live
and backtest verdicts agree. A multi-leg combo crosses the gate as one atomic batch — all legs
pass or the whole combo yields a single denial naming the failing leg — and consumes one throttle
slot, because it is one venue order. A modify is judged against the *projected* order, the
resting request with the new terms folded in, never against the delta; its veto is non-terminal
and consumes no slot.

<Callout type="warn" title="max_total_exposure scopes to ONE symbol at ONE venue, despite its name">
  It is not account-wide, cross-symbol or cross-venue. The gate holds no cross-symbol position book,
  and `make_engine` builds one engine — so one gate, so one copy of this cap — per venue. An
  operator trading N symbols is protected by this number N times over, once each, and never once in
  aggregate: a value sized for a whole book is an N× weaker cap than they believe they set.
  `crates/vike-exec/tests/risk/risk_lane_completion.rs`'s
  `max_total_exposure_is_scoped_to_one_venue_and_one_symbol` pins the scope. The name is kept
  because it is also the operator-facing TOML key, the string in the live-mount refusal, and a serde
  key inside the journal's state hash.
</Callout>

## Gate 4 — the halt, and why it is deliberately strict [#gate-4--the-halt-and-why-it-is-deliberately-strict]

A manual halt — and the two [dead-man's switches](/docs/trader/concepts/dead-mans-switch) that engage one
automatically, one on a link the venue's bridge reports dead and one on a feed that has gone
silent — must stop opening risk without trapping anyone in a position. Two
mechanisms agree on that policy and differ in verification strength. The `RiskGate` under
`TradingState::Halted` admits only a position-verified reduce (`vike_model::is_covered_reduce`:
the order must oppose the position and be covered by it), because it holds the position book. The
`ExecutionClient` boundary does not, so `vike_exec::halt::halt_admits_submit` takes the caller's
`reduce_only` flag as the only evidence in existence. That is the default `HaltAdmit::Admit` mode,
in which a venue's own position report is ignored outright; the tighter `HaltAdmit::Verify` mode
still requires `reduce_only` and additionally refuses a submit the venue's book *proves* opens
risk — and there every unknown admits (never fetched, fetch failed, an answer for another
account), because the promise being kept is *halting cannot trap you*, not *halting is airtight*.
The [halt](/docs/trader/concepts/halt) page carries the per-venue admit table.


# Settings (/docs/trader/concepts/settings)



Nearly every setting Vike Trader reads lives under one directory, `<project>/settings/`, in five
files whose names say what kind of value each holds — a run profile's `[risk]` table, under
`<project>/user_data/profiles/`, sits outside it, and a live mount refuses to start without the two
caps it supplies:

```
<project>/settings/
├── secrets.env         credentials — the one store, nothing else can supply a key
├── policy.toml         hard ceilings — file only, no environment, no command line
├── config.toml         deployment wiring — store paths, log directory, listen addresses
├── preferences.toml    taste and tuning — log levels, chart style, sweep threads
└── flags.toml          operator toggles, each with an owner and a review date
```

The split is by **authority** — who is allowed to change a value and from where — not by
subsystem. `crates/vike-config/src/lib.rs` is the typed model and layered loader for the four TOML
files; `crates/vike-secrets/src/lib.rs` owns the credential store. The decision record behind the
shape opens with the problem it solved: settings had lived in eight mechanisms with no root and no
precedence order, and `max_leverage` was exactly as env-overridable as a chart colour.

## Policy has no environment layer, by construction [#policy-has-no-environment-layer-by-construction]

The precedence is one line and applies to everything: code defaults, then the file, then the
environment, then the command line. What differs per type is *which layers exist*. `Policy` —
leverage, per-order notional, the market-slippage band, halt admission, and the per-venue
[arming ceiling](/docs/trader/concepts/risk-and-arming) — is the one settings type that implements
neither `EnvOverride` nor `CliOverride`. `crates/vike-config/src/layers.rs` seals both traits, so
`settings.policy.apply_env(&env)` is not a discouraged call but a compile error, and a downstream
crate cannot bolt the impl on from outside. The command-line layer has no policy field either,
because arguments leak into process listings, shell history and CI logs. Anyone who can set an
environment variable on a box — a shell export, a stale service-unit line, an inherited parent
process — can no longer widen a live risk limit with no file changed and no diff.

<Callout type="warn" title="A removed setting is a hard startup failure, and that is the safe direction">
  When the per-order notional ceiling moved from two environment variables into
  `policy.max_notional_per_order`, deleting the reads was only half the job: an operator who still
  set the old variable believed a ceiling was armed, and a build that quietly ignored it would trade
  uncapped while they believed otherwise. So every settings-loading binary calls
  `vike_config::refuse_removed_env` first — before a window, a feed, a core or a venue mount — and a
  set, non-empty removed variable refuses to start, naming the file, the key, and the operator's own
  value as a paste-ready line.
  A present-but-empty value starts normally: it configured nothing under the old readers either.
  The same rule covers a removed *file*: a `<project>/vike.toml` override layer existed for one hour
  and is refused by name if found — and a path that cannot be probed refuses too, but says so rather
  than claiming a file is present.
</Callout>

## A key nothing reads is worse than a missing feature [#a-key-nothing-reads-is-worse-than-a-missing-feature]

A settings key that validates, is accepted by the loader, and is reported by `vike-cli config show`
as the origin of an effective value — while being read by nothing — hands the operator positive
confirmation of something false. `crates/vike-config/src/consumed.rs` records that it is not
hypothetical: a clean-install validation found `flags.tradehub_control`, `config.tradehub_addr`,
`config.log_dir`, `config.state_dir` and `preferences.log_file_level` all displayed as effective
while read by nothing — no control server, the log in the wrong directory, and a `trace` firehose
the operator believed they had capped, which once wrote 341 GB onto the disk hosting a live trading
node. `vike_config::CONSUMPTION` is the answer and the ratchet: one row per `config`, `preferences`
and `flags` key naming the file and the read itself, or a written admission of which reader still
owns the variable today. A test opens each claimed consumer and looks; a needle inside the config
crate is rejected, because parsing a field is not consuming it. `config show`'s `READ` column
prints the verdict per key, and names the binary where one program owns the read (a library
consumer, read by every binary that links it, prints `yes` instead). The policy ceilings have an
older twin of the same gate; both are on [settings gates](/docs/trader/developer/settings-gates).

Provenance is measured the same way: `crates/vike-config/src/provenance.rs` decides an origin by key
**presence in a parsed layer**, never by diffing values against defaults. Unknown keys are rejected
by name, a removed key is a tombstone whose error says where the concept lives now, and a truthy
typo on a flag (`VIKE_RECONCILE=true`) is an error rather than a silent `false`. Every flag defaults
to `false`, and `FLAG_REGISTRY` gives each an owner and a review date, gated in CI — a flag with no
owner is a flag nobody will ever delete.

## Where the project is [#where-the-project-is]

`<project>` is resolved at runtime by walking up from the working directory for a project marker —
never a compile-time path — and `VIKE_SETTINGS_DIR` beats the walk by naming `<project>/settings`
outright, the project being its parent; the shipped service units set it. The loader itself
resolves nothing: the settings directory and the environment map are parameters, so the whole load
is a pure function of its arguments, and a missing file is not an error — the layer below stands.
The three binaries that load settings do so **before** initialising logging, because the log
directory and both log levels are themselves settings. The
[architecture](/docs/trader/concepts/architecture) page carries the rule that one walk decides per
process.

## Credentials [#credentials]

`secrets.env` is the one store: no precedence, no second location, so "which file are my keys
coming from" has a one-line answer. Absent credentials *are* the live gate — no store means an
empty map, every venue loader returns `None`, and every venue stays paper. A store that **exists
and cannot be read** is the opposite case and errors, because "not configured" and "cannot open"
must never look the same to an operator. A permission finding on a group- or world-readable file
is reported, never enforced: refusing would strand somebody mid-setup with every venue on paper,
while reading it silently is worse still. Nothing ever regenerates, reorders or deletes the store;
the one sanctioned write is a byte-preserving upsert of named keys.

<Callout title="Files, not a database — and a journal beside them">
  The question "should settings live in SQLite, since they change often?" was asked and measured.
  Across the four TOML files there were three non-empty settings lines in total. The decisive
  argument against an embedded store is that the change journal has two live writers — the daemon
  and the desktop app — and an exclusive file lock would make the second fail to open it. So settings
  and credentials stay files, and the change history the question actually wanted is an append-only
  JSONL journal beside them, `vike_model::change_journal`, under `<project>/settings/state/changes/`.
  The record it replaces was a `tracing` line at `info` on a daemon whose file level was `warn`: a
  23 MB log held 53 160 error lines, 1 928 warnings and zero of the records.
</Callout>

Each file's keys, with their consumers, are on the [settings reference](/docs/trader/reference/settings/index);
the removed variables and the registry of every environment read are on
[environment variables](/docs/trader/reference/environment).


# Startup preflight (/docs/trader/concepts/startup-preflight)



`crates/vike-mount/src/preflight.rs` opens with the sentence that justifies it: on mainnet day the
first real order must not be the probe. A drifted host clock used to be discovered as a binance
`-1021 INVALID_TIMESTAMP` on the first signed order, a dead key at the first `submit`, a full disk
by the recorder and the journal dying in silence, a dead resolver by every reconnect failing at the
hostname step. The preflight turns each into a structured report an operator reads at t=0.

## Pure core, injected probes [#pure-core-injected-probes]

Nothing in `preflight.rs` performs I/O. Every observation arrives through `PreflightProbes`, a
four-method trait — local time, a venue's server time, a cheap authenticated read, free bytes under
a directory — so the whole decision surface is unit-testable with no network, venue or filesystem.
`crates/vike-mount/src/startup.rs` is the one production wiring: `run_startup_preflight` builds the
real probes and `vike_run::build_node` runs it at the top of the venue mount. An unwired leg returns
`NO_PROBE`, which never reads as a pass: the clock and disk legs warn — "could not measure" is not
evidence of a fault — while the credential leg **fails**, because "we could not prove these keys
work" must not mount a venue live.

## The clock leg [#the-clock-leg]

A clock reading has four outcomes. A measured skew is judged against that venue's own thresholds; a
venue that publishes a clock and did not answer warns; a venue declared to have no clock leg where a
drift costs it nothing is not-applicable and never a warning; and a venue with no leg whose auth
signs the clock into the order path warns as a disclosed gap — polymarket is the one such row.
`crate::server_time` is the roster-gated table that declares which is which.

The thresholds are per venue because one global number was measurably false. The binance and bybit
signers hard-code a 5000 ms `recv_window`, shared between local skew, one-way latency and venue
queueing, so `DEFAULT_CLOCK_FAIL_MS` is 2500 — half the budget, past which one ordinary latency
spike pushes orders outside the window — and `DEFAULT_CLOCK_WARN_MS` is 500. Only a venue that
rejects an order over drift may fail: deribit and ig stamp no timestamp and hyperliquid binds the
clock into a nonce valid for about a day, so they carry no fail threshold and warn at
`CANARY_CLOCK_WARN_MS`, 1000 ms. The measurement that forced the split, from an NTP-disciplined
prod2 on 2026-08-09: bybit read +9..23 ms, okx +10..37, aster +15..33 — while forty samples of
hyperliquid's testnet node inside three minutes ranged from -220 to -424 ms. That is the venue's
clock wandering, not the host's.

A reading is only as sharp as its round trip: the midpoint correction assumes a symmetric path, so
the verdict is taken from what the reading proves — `|skew| - rtt/2`, floored at zero. Bybit's demo
host once read 182 ms of apparent skew on a 549 ms round trip while every other sample read 13-23
ms; under the floor, a slow link cannot manufacture a warning. Up to `DEFAULT_CLOCK_SAMPLES` (3)
readings are taken, the smallest round trip wins, and resampling happens only while the band still
straddles a threshold — one call in every ordinary case.

<Callout type="warn" title="Every leg is bounded, and the bounds are derived">
  Each clock read is a blocking REST call before the first venue mounts: seven wired venues, three
  samples each, on the shared 30 s agent is 630 s of possible stall. Two bounds replace that — a 3 s
  per-read `CLOCK_READ_TIMEOUT`, and a leg-wide budget from `clock_budget_for` of 1200 ms per venue
  actually read, clamped between 5000 and 15000 ms — so the worst case is 18 s at the ceiling and
  11.4 s today. The fixed 5000 ms it replaced was sized against a six-read 1781 ms measurement; by
  2026-08-22 a healthy pass summed to 2973 ms, so one dead venue needed 5973 and eight venues went
  unread. The credential leg is bounded separately: `CREDENTIAL_PROBE_TIMEOUT` is 5 s per attempt,
  `CREDENTIAL_PROBE_ATTEMPTS` is two — one retry, spent only on a probe that answered with an error,
  never on a timeout — and `credential_budget_for` is 3000 ms per probed venue clamped between
  6000 and 20000.
</Callout>

## The credential leg, and why the demotion is enforced [#the-credential-leg-and-why-the-demotion-is-enforced]

One probe is built for each of five venues — binance, bybit and okx through `build_recon_client`,
plus alpaca and ctrader through their own bridge factories — whose credentials resolve and whose
ceiling arms them, each performing that venue's own cheap authenticated read through its reconcile
client. Every other reconciled venue builds its `ReconClient` inside its own mount arm, which this
pre-mount step never calls, so it is never probed — and preflight never demotes a venue it did not
check. ctrader authenticates during construction, so its probe defers construction into the
closure, because building it eagerly would turn a refused grant into no row at all. Every probe's
error names the host it could not reach.

For its whole life the report was advisory — a fail row was logged and the venue mounted live
anyway, because a transient timeout raised the same fail as a refusal. `CredentialGap` removes that
blocker. `Rejected` means the venue answered inside the bound and refused the signed
read — a fail, and the venue is mounted paper for the session. `Unanswered` means nothing came back
inside the bound — a warning, and the venue mounts as configured. The enforcement withholds every
`{VENUE}_`-prefixed key from the map the mount reads, so `make_engine` sees absent credentials and
lands on the paper fallback it always had: refused keys and absent keys are the same fact, and the
old behaviour mounted live precisely when the venue had just said the keys do not work. One residual
is stated: a fast non-auth error such as a `429` inside the bound reads as rejected and demotes; the
retry stops a single blip doing it, and paper is the safe side.

A per-venue fail never flips the go bit. Only a global check — no disk headroom, no network — makes
`PreflightReport::go` false, and even that does not ground the process: a daemon that refuses to
start under `Restart=on-failure` crash-loops, so a global fail is logged at `error` and the mount
proceeds.

## Disk, network, and what the arming ceiling gates [#disk-network-and-what-the-arming-ceiling-gates]

The disk leg was dark for a year because free space is not reachable from `std`; it is armed on
unix through a safe `rustix::fs::statvfs` and reports a declared reason on Windows, warning below
5 GiB and failing below 1 GiB over directories the caller passes — which is how it measures the
journal directory the mount actually built. The network leg spawns a `NetProbe` and waits at most
500 ms for its first round.

Every venue set is derived through `would_mount_live_under_policy` — the same predicate the mount
arms on, so preflight and mount cannot disagree about what is armed. Until that was threaded, a
deployment whose [policy](/docs/trader/reference/settings/policy) said `ig = "paper"` still had IG
contacted at every start, with a credentialed read. `policy: None` reads all-paper and contacts
nothing; a box with no credentials, or a full store under an all-paper policy, makes not one
network call. `VIKE_PREFLIGHT_SKIP=1` — the exact string, read from the real process environment —
removes every leg. Probe errors never carry a key, secret or passphrase, the report's lines read
`[FAIL] credentials (okx): … — remediation`, and the [arming ceiling](/docs/trader/concepts/risk-and-arming)
stays the gate consulted above all of this.


# Timers (/docs/trader/concepts/timers)



Everything periodic in the live core rides one facility: `crates/vike-core/src/timer_wheel.rs`'s
`DeadlineTimerWheel`, armed and advanced by `crates/vike-core/src/runtime/timers.rs` at the
drain-loop boundary. Consolidating the stuck-order watchdog, both dead-man switches, managed
expiry and the observers onto one wheel means none of them can touch the per-message fold: the
wheel is advanced once per drain batch, after the batch has folded, and an empty wheel costs a
single `is_empty` read. This page is written from those two modules and from the `TimerKind`
enum in `crates/vike-core/src/runtime/mod.rs`.

## The wheel [#the-wheel]

It is a hashed timing wheel over a slab. Deadlines are quantized to ticks of `tick_ms` and
hashed into a power-of-two number of slots, each an intrusive doubly-linked list carved out of
one pre-allocated node slab with a free list. Insert reuses a free node — no allocation on the
steady path; the slab grows only when more timers are concurrently armed than ever before —
and cancel is an O(1) unlink. A `TimerId` carries a generation, so a stale id whose slot has
since been reused is rejected rather than cancelling the wrong timer.

The boundary advance is O(1) in the common case: a monotonically maintained lower bound on all
armed deadlines (`min_tick`) makes "nothing is due yet" a single integer compare regardless of
how many timers are armed. When something is due, expiry walks only the crossed slots and the
bound is re-established by one slot scan; an advance that crosses a whole rotation — a long
idle gap — takes a full pass that sorts the due nodes so emission stays in nondecreasing
deadline order.

<Callout title="No wall clock inside">
  Every method that needs "now" takes it as an injected `now_ms`. The wheel is a pure function of
  its inserts, cancels and the values passed to `advance`, so a replay or harness driving it with
  recorded stamps reproduces the exact expiries. A deadline never fires early — it is quantized
  up to the next tick, so a coarser resolution only makes a timer fire up to one tick late — and
  time only moves forward: an advance to a `now_ms` at or behind the cursor is a no-op. A deadline
  already in the past is clamped to fire on the next advance rather than stranded in a slot the
  cursor has passed.
</Callout>

The runtime builds it as `DeadlineTimerWheel::new(50, 1024)`: 50 ms resolution times 1024
slots, about a 51 s rotation, which covers a typical watchdog half-timeout in the bounded
stepping path and falls back to the full-rotation pass for larger ones.

## Reaching the boundary when the core is idle [#reaching-the-boundary-when-the-core-is-idle]

The core parks in `blocking_recv` between messages, and a parked core never reaches the
boundary on its own. An OS waker thread injects an `Ingest::Watchdog` message on cadence whose
dispatch arm is empty — it exists purely to wake the loop so `drive_due_timers` runs. That
waker record is journaled only when a wall-clock sweep that mutates order state can ride it —
the stuck-order ladder or either [dead-man's switch](/docs/trader/concepts/dead-mans-switch) — and its
presence is what makes a session's
journal refuse replay; with neither on, the boundary can only run replay-neutral observers, the
waker is not written, and the session still replays. The rule is on the
[replay](/docs/trader/concepts/journal/replay) page.

## What is armed, and when [#what-is-armed-and-when]

`arm_boundary_timers` runs once at startup and arms the first six kinds below; each of them
re-arms itself when it fires. When nothing is opted in the wheel stays empty and the advance is
skipped, byte-identical to a wheel-free runtime.

| kind               | runs                                                                  | cadence                                                         | armed when                                                 |
| ------------------ | --------------------------------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------- |
| `StuckSweep`       | the [watchdog](/docs/trader/concepts/watchdog)'s stuck-order ladder        | `submit_ack_timeout / 2`, at least 50 ms                        | `submit_ack_timeout` is set                                |
| `DeadManSweep`     | the silence [dead-man's switch](/docs/trader/concepts/dead-mans-switch)    | `timeout / 2`, at least 50 ms — at least two checks per window  | `deadman` is set                                           |
| `LinkDeadManSweep` | the connection [dead-man's switch](/docs/trader/concepts/dead-mans-switch) | `grace / 2`, at least 50 ms — the same shape, on its own window | `link_deadman` is set                                      |
| `InflightConfirm`  | the reject-free early confirm                                         | the configured interval — it *is* the check rate                | `inflight_confirm` is set                                  |
| `GtdSweep`         | managed GTD/DAY expiry                                                | the configured interval                                         | `gtd_sweep` is set                                         |
| `PortfolioSnap`    | one compact equity-and-positions journal record                       | the configured interval                                         | `portfolio_snapshot_interval` *and* a journal are both set |
| `EquitySample`     | the equity sampler                                                    | the configured interval                                         | `equity_sample` is set and any position is open            |
| `StateSave`        | every mount's strategy-state save                                     | the configured interval                                         | `state_save` and `state_dir` are set and any mount exists  |

The self-rescheduling sweeps re-arm at `now + tick`, skipping missed ticks rather than
bursting catch-up sweeps after a long idle. `drive_due_timers` stamps the injected `now_ms` onto
every engine before acting, so a fired sweep sees the timestamp semantics the old per-message
dispatch gave it.

The last two rows are never armed at startup: `maintain_equity_timer` and
`maintain_state_save_timer` arm and disarm them at the boundary as their gate opens and closes,
and a fired one re-arms itself only while that gate still holds. The sampler stays armed while any
engine holds an open position and is cancelled the instant the book goes flat; `any_position_open`
tests `size != 0.0` rather than map emptiness, because a closed position leaves a zero-size entry
behind forever. The state save deliberately does not gate on open positions — a breaker's trip
count or an estimator's accumulator matters whether the book is flat or not — and is cancelled
the moment every mount is gone. Two more boundary probes have no timer at all and re-walk their
subject every pass: the per-mount readiness gate, which no-ops in O(1) once every mount has
priced, and the wall-clock strategy schedule, driven off the clock *value* because an injected
clock may not advance between passes.

## What the observers do [#what-the-observers-do]

`sample_equity` resolves each engine's equity through the same `resolve_equity` and
`CoreConfig::price_cfg` the snapshot uses, notes every open position's priced-or-missing state
on its engine's [price board](/docs/trader/concepts/price-board) so the warn-once set arms and
clears, and hands one row per engine plus a `"TOTAL"` cross-venue row (the same `py_sum` law as
`equity_total`) to the `on_equity_sample` sink — the core takes no data dependency, so the
caller wires persistence. `save_all_strategy_state` is the one save loop shared with clean
shutdown: each mount's `Strategy::save_state` runs under `catch_unwind`, a `Some` is written
atomically to its sidecar, and an error is logged and swallowed. `write_portfolio_snap` appends
a `PortfolioSample` — per-venue equity, balance, realized, and every open position — to the
[journal](/docs/trader/concepts/journal/) best-effort; it is replay-neutral and does not advance the
snapshot cadence counter.

<Callout type="warn" title="The portfolio record is cheap per row, not free per session">
  Because those records never bump the write-ahead counter that paces the replay-base `Snap`, an
  otherwise idle journaling core never reaches the snapshot threshold, so nothing is prunable
  until the shutdown `Snap`. A 1 s cadence on a silent weekend is about 86 000 unprunable records
  a day. Size the cadence for the session — seconds to minutes for a reporting series, never
  sub-second.
</Callout>


# The watchdog (/docs/trader/concepts/watchdog)



`crates/vike-core/src/runtime/watchdog.rs` holds the core's cold-path sweeps: the stuck-order
ladder, the fast in-flight confirm, managed good-till-date expiry, safe-state entry, the
margin-call sweep and the equity-drawdown latch. None runs on the per-message fold; the timed
ones fire from the [timer wheel](/docs/trader/concepts/timers) at the drain-loop boundary and the
others on a closed bar, so the [latency gate](/docs/trader/concepts/latency-gate) is untouched. This
page is written from that module and from the `CoreConfig` fields in
`crates/vike-core/src/runtime/mod.rs` that arm each sweep.

## The stuck-order ladder [#the-stuck-order-ladder]

`sweep_stuck_orders` is the last-resort backstop for an order stuck before acknowledgement
(`Initialized` or `Submitted`): an adapter that accepted `submit` but whose thread wedged before
emitting any terminal. It must never race a slow-but-real venue ack into a phantom reject — if
the venue actually accepted or filled the order, a synthesized `OrderRejected` strands a real
position, because the later real `OrderAccepted` or `OrderFilled` is an illegal transition from
`Rejected` and is dropped (counted as `stranded_terminal_drops`). So it is a ladder, armed by
`CoreConfig::submit_ack_timeout` (`None` by default) with `submit_ack_confirm_grace` (default
15 s):

* **Stage 1** — at `created + submit_ack_timeout`, soft-warn and actively `confirm` once: the
  venue is prodded into a status re-query whose authoritative terminal folds back on the normal
  event lane. Nothing is terminalized, and the time of the confirm is recorded.
* **Stage 2** — the plain reject deadline is `created + submit_ack_timeout + grace`, but a
  candidate whose stage-1 confirm is presumed in flight (it is still pre-ack) is deferred one
  further grace window, to `+ 2·grace`. Only past that, still pre-ack, is the `OrderRejected`
  synthesized, with the reason `watchdog: no venue ack within confirm-grace`. An order that
  reaches the deadline without ever passing stage 1 — a busy core skipped ticks, or the clock
  jumped — is confirmed now and deferred, so *no backstop reject without at least one active
  confirm plus its grace window* holds.

The core fold thread issues no network call: `confirm_order` is fire-and-forget onto the
adapter's own thread, and the sweep only waits for the terminal. Reconcile-seeded orders, which
carry no creation time, are never swept. The bookkeeping is pruned to still-pre-ack orders at
the end of every sweep.

<Callout type="warn" title="Sizing the two knobs">
  `submit_ack_timeout` must exceed the venue's worst-case order-visibility latency and the
  adapter's own submit-plus-requery budget; the doc suggests a conservative value such as 30 s for
  reconcile-less venues. The grace must clear the confirm's own round trip — the stated bound is
  `2·grace > submit_ack_timeout/2 + N·requery_timeout`, with a re-query timeout of about 5 s and
  `N` = 2 for Bybit (a realtime-then-history re-query, worst case about 10 s) or 1 for OKX. A
  zero grace collapses the ladder back to immediate reject and reintroduces exactly the
  phantom-reject risk the window exists to remove.
</Callout>

## The reject-free early rung [#the-reject-free-early-rung]

`sweep_inflight_confirms`, armed by `CoreConfig::inflight_confirm` (`None` by default,
suggested live value about 2 s), re-queries an order stuck pre-ack on a fast cadence, catching a
wedged adapter in seconds instead of waiting the conservative timeout for the ladder's first
confirm. Three guarantees make it safe: it calls only the publish-nothing `confirm_order` and
can strand nothing; it is band-limited to ages in `[inflight_confirm, submit_ack_timeout)`,
handing off the instant an order crosses the timeout so the two rungs never act on one order at
one age; and it keeps its own dedup map, re-confirming a still-stuck order at most once per
window. With the ladder off the band is unbounded and this becomes the only stuck-order signal
— still reject-free, because without a configured reject timeout the core must never invent a
terminal.

## Managed expiry [#managed-expiry]

`sweep_gtd_expiry`, armed by `CoreConfig::gtd_sweep`, cancels every resting order whose
time-in-force deadline has passed, for venues that do not expire GTD or DAY orders themselves.
The decision is `vike_model::tif_expired`, the one expiry law shared with the paper book; the
terminal vocabulary differs on purpose. The paper book owns its resting order and mints
`OrderExpired`; this sweep asks the real venue to cancel and lets the venue's authoritative
`OrderCanceled` fold back, because publishing `OrderExpired` locally would desync local state
from a venue order still live. Each expiry is journaled write-ahead as `GtdExpire` — a marker,
never re-applied on replay — and the cancel is fire-once per order.

## Safe-state entry [#safe-state-entry]

`enter_safe_state` is what a fold panic reaches. It logs the reason once at `error`, sets
`trading_state = Halted` on the primary and every extra engine so the risk gate denies every
new order, records the fault for the snapshot, and issues a best-effort cancel for every
non-terminal working order tagged `CancelIntent::RiskOff` — the core has faulted and is pulling
its whole book, so a venue metering its cancels must not hold any back. The sweep is itself
guarded: a client that panics during it cannot take the loop down. What the
[execution core](/docs/trader/concepts/execution-core) does afterwards — read for display, never
traded on again until restart — is that page's subject.

## The margin-call sweep and the drawdown latch [#the-margin-call-sweep-and-the-drawdown-latch]

Both run once per closed bar of the engine's own series, where marks are fresh, and both read
equity through the resolver the snapshot displays. `sweep_margin_call` runs the
[margin-call](/docs/trader/concepts/margin-call) model per engine and submits each liquidation as a
`reduce_only` market order through the normal gate, routed to the breaching engine by index.
`sweep_drawdown_latch`, armed by `CoreConfig::max_drawdown` (`None` or any value at or below
zero disables it), folds a high-water mark of the daemon's own equity curve and, when the drop
exceeds the threshold, sets every engine to `TradingState::Reducing` so only reduce-only orders
pass. It mints no orders, pushes one warning naming the mark, the curve and the drawdown into
the recent-events ring, and never un-latches on its own — recovery is a deliberate manual
`SetTradingState`.

<Callout type="warn" title="A fraction of what">
  The curve is `Σ seed_of(engine) + Σ resolved_own_pnl(engine)` — configured capital plus the
  daemon's own realized and unrealized P\&L — and deliberately not observed account equity, which
  on a venue-attested account is the wallet for the whole account the credentials open. Measured
  on prod2 on 2026-08-17: nine paper mounts at 1000 seed each plus one bybit mount carrying
  53647.10600813 of a shared demo wallet latched a high-water mark near 62647, where a third party
  withdrawing would trip liquidate-only with no trading at all, and a genuine 25% loss on the
  daemon's own \~9000 of book read as 3.6%. Across a restart the peak seeds to `max(capital base,
  curve)`, so the curve resumes underwater rather than forgiving earlier losses; a non-positive
  peak cannot express a fraction, so a profile with `max_drawdown` set is refused unless its seed
  cash is positive.
</Callout>

An operator facing an order that will not leave `Submitted` starts at
[triage a stuck order](/docs/trader/guides/triage-a-stuck-order); the venue-side truth the ladder
defers to is [reconciliation](/docs/trader/concepts/reconciliation/).


# Databento (/docs/trader/data-providers/databento)



`databento_backfill` is the crate's adapter for Databento's historical HTTP API. Its module,
`crates/vike-backfill/src/databento/mod.rs`, describes the lane in one sentence: intraday
bars/trades/quotes/L2-book from `hist.databento.com/v0/timeseries.get_range` in the raw CSV
encoding, into the `vike-data` hist store. It is a data source rather than an execution venue, which
is why it lives in vike-backfill and not under `crates/bridges/`. The bin is built only under the
`databento` feature (`crates/vike-backfill/Cargo.toml`), so the invocation is
`cargo run -p vike-backfill --features databento --bin databento_backfill`.

## What a run does [#what-a-run-does]

From `crates/vike-backfill/src/bin/databento_backfill.rs`'s usage text:

```
databento_backfill --dataset GLBX.MDP3 --symbol ESZ4 --schema trades \
    --start 2024-01-02T00:00:00 --end 2024-01-02T00:01:00 [--store DIR] [--venue NAME]
```

`--dataset` is the Databento dataset code, `--symbol` the instrument within it, and `--schema` one
of `trades`, `ohlcv-1m`, `ohlcv-1h`, `ohlcv-1d`, `mbp-1`, `mbp-10` — each mapping to a store series.
`--start`/`--end` are in Databento's own timestamp form. `--store` resolves through [the shared
ladder](/docs/trader/concepts/hist-store), where `$VIKE_HIST_STORE` and a project declared by
`$VIKE_SETTINGS_DIR` both outrank `<repo>/market_data/hist`, and `--venue` is the label the series is
stored under, defaulting to `databento`.

The transport (`crates/vike-backfill/src/databento/client.rs`) builds the `timeseries.get_range`
URL, authenticates with HTTP Basic — the API key as username, empty password — and streams the CSV
body to a temporary file rather than buffering it, because tick and book ranges are large. The
ingest (`crates/vike-backfill/src/databento/ingest.rs`) drives the parsers into the store under the
commit key `databento:{kind}:{symbol}:{start}-{end}`, so re-running the same window is a store
no-op.

## The parsers [#the-parsers]

`crates/vike-backfill/src/databento/parse.rs` is pure — no I/O, no clock, fixture-tested — and its
header carries the wire facts a reader of the stored rows needs: prices arrive as `1e-9` fixed-point
integers and are divided by `PX_SCALE`; timestamps are nanoseconds and are reduced to milliseconds;
the trade `side` is the aggressor, `A` meaning a sell aggressor (the buyer is the maker) and `B` a
buy aggressor. Columns are resolved by *name* through `crates/vike-backfill/src/csvutil.rs`'s
`Header`, which the two vendor parsers share, so column-order drift between schema versions is
tolerated. `csvutil` also explains why no CSV crate was pulled: both vendors emit a header row and
only numeric or string fields with no embedded commas, so a plain split is sufficient.

## Credentials [#credentials]

`DATABENTO_API_KEY` is read by the bin from the credential store — `<project>/settings/secrets.env`
— then the process environment, never argv (bin header). `client.rs`'s header records the
boundary: the key arrives as a plain `&str` parameter, and the module reads neither the environment
nor the workspace `.env`. It used to own an `api_key_from_env()` while its Tardis sibling already
had the bin do the read; the two premium-vendor adapters are now symmetric. The live smoke for this
adapter, `crates/vike-backfill/tests/databento_smoke.rs`, is `#[ignore]`d and self-skipping — its
ignore reason reads "live: needs DATABENTO\_API\_KEY, spends a tiny amount".

## Where it sits in the capability table [#where-it-sits-in-the-capability-table]

`crates/vike-backfill/src/caps.rs`'s Databento row is `NONE` for every roster venue, and the comment
on it is the point rather than a gap: the vendor has zero crypto coverage (verified in the vendor
study), so it is an equities and futures answer, keyed off its own vendor-namespaced venue label
rather than a roster venue — which is why no roster row is `true` for it, and why the `--venue`
default is `databento`. A gap plan over a roster venue will therefore never offer Databento; you
reach it by naming the dataset yourself.

<Callout type="warn" title="Overlapping windows are two commit keys">
  The key names `{start}-{end}`, so re-running the identical window is a no-op, but two runs over
  windows that overlap are two keys, and the store compares keys, never row values
  (`crates/vike-backfill/src/vikedata/ingest.rs` names this as the same contract
  `databento/ingest.rs` has). Schedule non-overlapping windows rather than widening a trailing one;
  where two writers already cover the same rows, the store's source-precedence policy on
  [the Data API page](/docs/trader/data-providers/vike-data-api) is the repair.
</Callout>

The store kinds a schema produces are documented under [concepts/data](/docs/trader/concepts/data); the
comparable crypto-only vendor lane is [Tardis](/docs/trader/data-providers/tardis).


# EOD, events and exec trades (/docs/trader/data-providers/eod-and-events)



These three `vike-backfill` bins share nothing but the store they write. Each takes `--store DIR`, resolved through the store's own ladder — `$VIKE_HIST_STORE` and a `$VIKE_SETTINGS_DIR`-declared project both above `<repo>/market_data/hist` — and each is idempotent through the store's commit-key append, so a repeated run is a no-op rather than a duplicate. What they fill is described on [the history store](/docs/trader/concepts/hist-store); the column shape of each kind is under [concepts/data](/docs/trader/concepts/data).

## `eod_backfill` — daily bars [#eod_backfill--daily-bars]

```
eod_backfill --source yahoo --symbols SPX=^GSPC,VIX=^VIX,NDX=^NDX,DJI=^DJI --years 10 [--venue V] [--store DIR]
```

Daily OHLCV for equity indices and stocks, ingested as `kind=bar` at interval `1d`, idempotent per run-day. `--symbols` is a comma list of `vikeSymbol=sourceTicker` pairs; a bare `SYM` means the source ticker equals the symbol. `--years` defaults to 10. `--venue` defaults to the source name, so provenance lives in the partition.

`crates/vike-backfill/src/eod/mod.rs` is explicit that these are read-only data sources, not execution venues, which is why they live in the backfill crate rather than under `crates/bridges/`. The extensibility point is the `EodSource` trait: a provider builds a URL, GETs it, and hands the body to a pure, fixture-tested parser — `parse_yahoo_json` for the one shipped provider. `vike_backfill::eod::SOURCES` is exactly `["yahoo"]`. A stooq provider was dropped after a live test found it fronting its CSV endpoint with a JavaScript proof-of-work wall a plain HTTP client cannot pass.

The Yahoo source (`crates/vike-backfill/src/eod/yahoo.rs`) requests `query1.finance.yahoo.com/v8/finance/chart/{ticker}?interval=1d&range={years}y`. It needs a `User-Agent` header — Yahoo answers 403 without one — and index tickers carry a `^` prefix (`^GSPC`, `^VIX`, `^NDX`, `^DJI`). A day with any `null` OHLC field is skipped, which is how Yahoo marks a no-trade day.

<Callout type="warn" title="Keyless, and unofficial">
  The module doc calls this source keyless but ToS-gray and best-effort: the official Yahoo API is retired, and the unofficial v8 endpoint can break without notice. The bin exits non-zero only when every symbol failed; a single failed ticker is logged and skipped.
</Callout>

## `events_api_backfill` — the live events API [#events_api_backfill--the-live-events-api]

```
events_api_backfill --from YYYY-MM-DD --to YYYY-MM-DD --tokens-file PATH [--tokens T1,T2,...]
    [--store DIR] [--base URL] [--kind book|trade|quote|all] [--concurrency N] [--dry-run]
```

This is the no-ClickHouse, no-multi-GB-download route to Polymarket L2 history: `GET https://data.vike.io/v1/events?token_id=...&from_ms=...&to_ms=...&limit=...[&cursor=...]`, paged JSON, one token at a time — the rows a customer wants for the one token they care about. Its bulk-Parquet sibling is `vike_archive_backfill` on [the Data API page](/docs/trader/data-providers/vike-data-api); the two share the `vike-archive` Cargo feature (this bin is built only under it) and the same `X-API-Key` credential, `VIKE_ARCHIVE_API_KEY`, which the bin reads from the credential store and passes into the library as a plain parameter — `vike_backfill::events_api` itself never touches the environment. Series land under `venue=polymarket` with commit key `eventsapi:{kind}:{token}:{day}`, keyed per token because the endpoint is fetched per token.

One (date, token) pair is one unit of work: the UTC calendar day `[midnight, next midnight)`, paged to completion by `EventsClient::fetch_all_single`. `--concurrency` (default 6) runs that many fetch loops on worker threads — the measured \~0.81 s per market round trip is latency-bound, so overlapping requests is the win — while every decode and store append happens on the main thread, single-writer. `--tokens` and `--tokens-file` (one id per line, `#` comments allowed) union into one list; giving neither is an error, since "no filter" has no meaning for a per-token endpoint. `--dry-run` prints the work-unit count and the base URL with no network call and no store opened.

`crates/vike-backfill/src/events_api.rs` documents three ways this endpoint differs from every sibling path, all verified against real traffic on 2026-07-28:

* A `price_change` delta row already carries its one-level ladder in `bids`/`asks`, including a zero-size removal, so book rows are parsed uniformly for snapshots and deltas.
* `best_bid`/`best_ask` are always `0.0` — more than 10,000 consecutive rows of an actively traded `btc-5m` market showed no non-zero value. `--kind quote` is therefore a harmless no-op lane, and an events-API-sourced store has no quote lane until the server populates those fields.
* No `tick_size` field exists on the wire. `book_update_from_row` defaults to `FALLBACK_TICK_SIZE` (`0.01`, the venue's standard tick) because `0.0` is actively harmful: `L2Book::new` falls back to `1.0` for a non-positive tick, quantizing a `[0.0, 1.0]` market into two buckets. Over a real 26-market slice every tick-sensitive maker config traded zero times while `trailing_scalper`, which prices off the trade tape, traded normally — the data was sound; the tick metadata was missing. A market on a genuinely finer or coarser tick is still misquantized.

Multi-token requests are detected, not assumed: with two or more tokens the bin makes one `probe_multi_token` call first. On 2026-07-28 the live endpoint still answered `HTTP 400`, so one unit per token is what actually runs; the decoder already parses a per-row `token_id`, so a batched response will decode the day it ships.

## `exec_trade_backfill` — your own fills [#exec_trade_backfill--your-own-fills]

```
exec_trade_backfill --file <myTrades.json> --symbol BTCUSDT [--venue binance] [--store DIR]
```

This one imports a venue account's trade-history export into the `kind=exec_fill` execution log — the offline twin of the live `JournalMaterializer`. Both write the same series, so live and historical fills converge into one queryable log. The v1 input is a Binance `myTrades` JSON export, which needs no credentials. The commit key embeds the fill window, so re-importing the same export is a store no-op.

`vike_backfill::exec_import::parse_binance_my_trades` is pure: no clock, no network. A malformed or short row is skipped rather than aborting a bulk import; numeric strings are taken in Binance's wire format; `side` is +1 for a buyer and −1 for a seller; `commission` is the positive charged fee; `isMaker` maps to `maker`/`taker` and, when absent from a minimal export, the liquidity side stays empty rather than guessed. An `ExecTradeSource` trait exists for a signed live-REST source per venue, but v1 registers none — the export file is the only path.


# Funding rates (/docs/trader/data-providers/funding-rates)



Two bins in `crates/vike-backfill` carry "funding" in their name, and
`crates/vike-backfill/src/funding_rate.rs`'s header draws the line between them before anything
else. `funding_rate_backfill` writes the **market** rate: the venue-wide, position-independent
funding schedule for a symbol — keyless, available for every perpetual whether or not you hold it,
and the *signal* a funding-capture strategy trades on. `hyperliquid_funding_backfill` writes an
**account's** realized funding: a wallet's `userFunding` payments, which is a different series with a
different store kind. Both sit behind the `venue-backfill` feature, and the second reason is not
obvious: `crates/vike-backfill/Cargo.toml` notes that `funding_rate_backfill` looks bridge-free but
routes through `crate::funding_rate`, which calls `vike-hyperliquid`.

## The market rate: `funding_rate_backfill` [#the-market-rate-funding_rate_backfill]

The collector fetches a venue's public funding-rate schedule and ingests it as `kind=bar`, the rate
riding on `vike_model::Bar::funding` with OHLCV and volume left `0.0` — so a backtest's
`funding_source` seam can replay the real per-interval rate off the stored column
(`funding_rate.rs` header). Two venues ship, each as an impl of the `FundingRateSource` trait — a
pure, fixture-tested parser over the venue's JSON plus a paged `fetch`:

* **Binance** — `GET https://fapi.binance.com/fapi/v1/fundingRate` with `symbol`, `startTime`,
  `endTime` and `limit=1000`; 8-hour cadence; a keyless GET over the crate's shared HTTP client.
* **Hyperliquid** — `POST /info` with `{"type":"fundingHistory", ...}`; 1-hour cadence; a keyless
  mainnet read over the bridge's own `HyperliquidTransport`.

Both venues cap responses at roughly 500–1000 rows, so `fetch` pages `startTime` forward until a
page comes back short or the cursor passes the end (`page_forward`, shared by both impls). The run
is idempotent per `(venue, symbol, [start, end])` window through `funding_rate_commit_key`.

From `crates/vike-backfill/src/bin/funding_rate_backfill.rs`'s usage: `--venue` selects the source
and names the store partition (`binance` | `hyperliquid`); `--symbols` is a comma list of
`vikeSymbol=sourceSymbol` pairs, bare `SYM` meaning the two coincide (Binance `BTCUSDT`, Hyperliquid
`BTC`); `--start`/`--end` are each an epoch-ms integer or a `YYYY-MM-DD` UTC date, `--end`
defaulting to now; `--interval` is the series interval label and defaults, for both venues, to the
cadence-agnostic namespace `funding` — `FundingRateSource::default_interval` is deliberately not a
cadence (`8h`/`1h`), because funding spacing varies by venue and by symbol, so the true cadence
lives in the data, in the spacing of the stored `Bar.ts`, and one stable label keeps this series in
its own keyspace where an OHLCV kline series can never interleave with it. An operator who wants a
cadence-tagged series passes `--interval`, as the second example below does. `--store` resolves
through [the store's ladder](/docs/trader/concepts/hist-store): `$VIKE_HIST_STORE`, then a project
declared by `$VIKE_SETTINGS_DIR`, then `<repo>/market_data/hist`.

```
funding_rate_backfill --venue binance --symbols BTCUSDT,ETHUSDT --start 2024-01-01
funding_rate_backfill --venue hyperliquid --symbols BTC=BTC,ETH=ETH --start 1704067200000 --interval 1h
```

<Callout title="Hyperliquid's response carries a second number, and it is kept">
  The `funding_rate.rs` header records that `premium` was parsed and discarded for as long as the
  file existed. It is the venue's funding premium for the same interval, not derivable from
  `fundingRate` (the venue folds an interest-rate term in and then clamps), and it is the input the
  cohort study's `premium_z_24h` feature needs. It is stored as its own kind — `kind=perp_metrics`,
  one `PerpMetricRow` per interval that had one — rather than on the funding `Bar`, which has no field
  for it. Binance sends no premium and therefore writes none. Open interest is deliberately not
  beside it: Hyperliquid serves OI only as a current snapshot, never as history, so no backfill can
  reconstruct a past value. The one producer that does fill `open_interest` is the vike.io hourly
  panel, on [the Data API page](/docs/trader/data-providers/vike-data-api).
</Callout>

## The account's payments: `hyperliquid_funding_backfill` [#the-accounts-payments-hyperliquid_funding_backfill]

`crates/vike-backfill/src/bin/hyperliquid_funding_backfill.rs` fetches a master account's keyless
`userFunding` `/info` history on mainnet — no credentials, just the address — over
`[--start, --end]` and ingests it as `kind=funding`/`venue=hyperliquid`/`symbol=<coin>`, split by
coin and idempotent per `(account, coin, window)`. It is the funding analog of
`hyperliquid_backfill`, and `crates/vike-backfill/src/hyperliquid.rs` owns both: the candle backfill
and `backfill_hyperliquid_funding` with its pure `funding_rows_by_coin`, persisting through
`vike_data::HistStore::append_funding`.

`--account` is the master account address funding is read against. The bin header is explicit about
the agent-wallet pitfall the bridge guards against elsewhere: it does not apply here, because funding
reads are keyless — pass the **master** address. `--start`/`--end` take the same epoch-ms-or-date
forms as the market-rate bin, and `--store` resolves the same way.

```
hyperliquid_funding_backfill --account 0x8f0a3e01d916486735a8f6a2ffc0685a3fa57bf5 --start 2024-01-01
```

## Which one you want [#which-one-you-want]

A funding-carry strategy backtest wants the market rate, on `Bar.funding`, from
`funding_rate_backfill` — that is the number the position would have paid or received per interval
regardless of who held it. A reconstruction of what one wallet actually received wants
`kind=funding` from `hyperliquid_funding_backfill`. `crates/vike-backfill/src/caps.rs` tracks the
first as bars and does not track the second at all, with the reason on the Hyperliquid row: realized
funding payments are not market data, and no coverage report asks for them. The kinds themselves
are documented under [concepts/data](/docs/trader/concepts/data); the tutorial that consumes the market
rate is [funding carry across two venues](/docs/trader/tutorials/funding-carry-two-venues).

<Callout type="warn" title="Two producers of one series double its hours">
  `vikedata_backfill --panel-funding` also writes funding-rate hours, and its usage text states that
  the panel's rate and `fundingHistory`'s settled rate are different series — a snapshot aggregate
  versus a settled interval rate, measured roughly 4× apart. The store's idempotency is batch-level on
  the commit key, two producers are two keys, and the hours they share land twice. One store takes one
  producer for a window.
</Callout>


# IBKR historical (/docs/trader/data-providers/ibkr-historical)



`ibkr_backfill` is the one venue-direct collector that needs a running desktop client rather than a
public endpoint. Its header (`crates/vike-backfill/src/bin/ibkr_backfill.rs`) states the shape:
it pages `vike_ibkr::HistoricalFetcher` — bounded below by the contract's `head_timestamp`, or an
explicit `--start` — for a symbol set and interval, and ingests each window as `kind=bar` under
`venue=ibkr`, idempotent per window. It needs a running TWS or IB Gateway, and the header adds why
that is enough: its login is the entitlement, and history is looser than realtime. The bin is built
only under the `ibkr` feature, which `crates/vike-backfill/Cargo.toml` enables together with
`vike-ibkr/ibkr-socket` — the vendored `ibapi` client — so a default build never compiles it.

```
cargo run -p vike-backfill --features ibkr --bin ibkr_backfill -- \
    --env demo --symbols AAPL=AAPL.SMART.USD,MSFT=MSFT.SMART.USD --interval 1d --years 5
```

## The flags [#the-flags]

From the bin's usage text:

* `--symbols` — a comma list of `vikeSymbol=ibkrContract` pairs, required; a bare `SYM` means the
  contract equals the symbol.
* `--env` — `demo` (which `paper` also spells) or `live`. The default is `demo`, and the bin's own
  test names that as the one default whose direction is a safety property: a forgotten `--env` must
  never reach a live account.
* `--interval` — `1d`, `1h`, `5m` or `1m` (default `1d`).
* `--years N` — how far back to page when `--start` is absent (default 5); it bounds the fetch when
  `head_timestamp` is unavailable.
* `--start` — an explicit lower bound, epoch milliseconds or `YYYY-MM-DD`.
* `--what` — IBKR's `whatToShow` field: `trades`, `midpoint`, `bid`, `ask` or `bidask` (default
  `TRADES`).
* `--store` — the hist-store root, resolved through [the store's ladder](/docs/trader/concepts/hist-store):
  `$VIKE_HIST_STORE`, then a `$VIKE_SETTINGS_DIR`-declared project, then `<repo>/market_data/hist`.
* `--pacing-ms N` — the sleep between window requests, to stay inside IBKR's historical pacing
  limits (default 10000).

Credentials come from the credential store: the usage text names `IBKR_{DEMO,LIVE}_ACCOUNT` in
`<project>/settings/secrets.env` as required beside the running gateway.

## How it is split [#how-it-is-split]

`crates/vike-backfill/src/ibkr.rs` is the pure planning half — window sizing, paging and commit
keys — fixture-tested with no network, mirroring the EOD and pmxt collectors' shape of one
fixture-tested planner file. The bin drives `HistoricalFetcher` over those plans and ingests each
window through `HistStore::append_bars`. The fetcher itself lives in the bridge:
`crates/bridges/vike-ibkr/src/historical.rs`'s header describes a public historical-bar seam that
owns a dedicated `ibapi` connection, pages `historical_data` bounded below by `head_timestamp`, and
returns `vike_model::Bar`s — so the collector never names an `ibapi` type — reusing the same
symbology, bar-size mapping and bar mapper as the live feed. It is behind `ibkr-socket`, where
`ibapi` exists.

The collector is the offline twin of the live feed, and it is **live-verified on paper**: the proof
vehicle is `crates/vike-backfill/tests/ibkr_backfill_smoke.rs`, whose header calls itself the human
vehicle to verify the historical wire shapes before a real backfill run. It is `#[ignore]`d and
self-skips without a config or a running Gateway, so nothing in CI ever runs it.

<Callout type="warn" title="One data client id, three consumers">
  Three call sites open a connection on `cfg.data_client_id`: the mount-time properties fetch
  (`crates/bridges/vike-ibkr/src/properties.rs`'s `fetch_ibkr_properties`), the live feed
  (`crates/bridges/vike-ibkr/src/market_feed/mod.rs`), and `HistoricalFetcher::connect`. Only the
  first pair is sequenced by construction — the properties doc records that its connection is a
  transient one-shot, "fully torn down before the live market-data feed … claims that same id, so it
  never contends the feed", and it says nothing about a backfill. A backfill run beside a live feed
  on the same configuration contends for the same id.
</Callout>

## Where it sits in the capability table [#where-it-sits-in-the-capability-table]

`crates/vike-backfill/src/caps.rs`'s row for `(Venue, "ibkr")` is `BARS_ONLY`, with the pipeline
written beside it: `HistoricalFetcher` → `vike_model::Bar` → `append_bars`. Like every venue-direct
source, it cannot repair a recorded trade or book gap; that is the finding the table's header
exists to make visible, and the reason the vendor lanes on [Databento](/docs/trader/data-providers/databento)
exist for equities and futures history at tick resolution.

The IBKR venue itself — the mount, the two transports, reconciliation — is documented under
[venues](/docs/trader/venues); the `ibkr_mount` binary that runs a real mount is on
[mount-bins](/docs/trader/reference/binaries/mount-bins). The bar kind this collector writes is under
[concepts/data](/docs/trader/concepts/data).


# Data providers (/docs/trader/data-providers)



Every backfilled series in the store was written by a collector, and every collector lives in
`crates/vike-backfill`. Its `crates/vike-backfill/src/lib.rs` header states the contract: venue
history *fetchers* live in the per-venue bridge crates, and what vike-backfill adds on top is the
historical backfill path — one-shot paged REST or `.bi5` pulls plus ingest into the `vike-data`
hist store, with commit-window bookkeeping — kept as its own crate so that machinery does not bloat
every bridge's live-feed code. Every collector is a **one-shot** binary an operator runs; the
long-running counterpart, `collector_supervisor`, dispatches the same `backfill_*` functions and
never a second implementation (`crates/vike-backfill/src/supervisor/mod.rs`'s contract). It has its
own page at [collector-supervisor](/docs/trader/reference/binaries/collector-supervisor).

Two facts shape everything below. Every bin here is a **composition root** — one of the few places
allowed to read the process environment and the credential store directly; that is the shape
`crates/vike-ops/src/settings.rs`'s `Layer::Binary` calls "the correct place to read process env",
and it is why each family's page names the variable its bin reads. And the crate is excluded from
CI's derived roster — `xtask/src/ci/tables.rs`'s `EXCLUDE_FROM_CI` carries it with the reason, that
it "only builds/tests under features" — so its families are compiled by the union `backfill`
feature lane rather than the default build.

## The families [#the-families]

| family                                                               | bins                                                                                                                               | feature                            |
| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| [Venue-direct](/docs/trader/data-providers/venue-direct)                  | `binance_backfill` `bybit_backfill` `okx_backfill` `aster_backfill` `deribit_backfill` `dukascopy_backfill` `hyperliquid_backfill` | `venue-backfill`                   |
| [Funding rates](/docs/trader/data-providers/funding-rates)                | `funding_rate_backfill` `hyperliquid_funding_backfill`                                                                             | `venue-backfill`                   |
| [Databento](/docs/trader/data-providers/databento)                        | `databento_backfill`                                                                                                               | `databento`                        |
| [Tardis](/docs/trader/data-providers/tardis)                              | `tardis_backfill`                                                                                                                  | `tardis`                           |
| [The vike.io Data API](/docs/trader/data-providers/vike-data-api)         | `vikedata_backfill` `vike_archive_backfill`                                                                                        | `vikedata` / `vike-archive`        |
| [IBKR historical](/docs/trader/data-providers/ibkr-historical)            | `ibkr_backfill`                                                                                                                    | `ibkr`                             |
| [Polymarket](/docs/trader/data-providers/polymarket)                      | `pmxt_backfill` `poly_reparse`                                                                                                     | default / `poly-reparse`           |
| [EOD, events and exec trades](/docs/trader/data-providers/eod-and-events) | `eod_backfill` `events_api_backfill` `exec_trade_backfill`                                                                         | default / `vike-archive` / default |
| [Store maintenance](/docs/trader/data-providers/store-maintenance)        | `migrate_to_group` `ingest_bench_bars`                                                                                             | default                            |

The feature column is not decoration. `crates/vike-backfill/Cargo.toml`'s `venue-backfill` note
explains why the venue collectors are off by default: every bin links the whole library, so while
the bridge crates were unconditional dependencies, all twenty-two bins compiled all of them —
including the fourteen that touch no venue at all. Each bin that needs a bridge now says so through
`required-features`. What cannot be gated is `vike-data/hist-datafusion`: every collector ingests
into the store, so DataFusion is the compile cost you always pay.

## What a source can and cannot serve [#what-a-source-can-and-cannot-serve]

`crates/vike-backfill/src/caps.rs` is the capability table, and its header opens with the finding
it exists to make visible: &#x2A;*no venue-direct backfill in this workspace serves `trade` or `book` at
all.** Every `*_backfill` bin that talks to a venue writes `kind=bar`, except Dukascopy, which
writes `kind=quote` from `.bi5` ticks and resamples bars from them. Trades and the L2 book come only
from archives and paid vendors — pmxt, `data.vike.io`, a local ClickHouse capture, Databento,
Tardis. That is exactly inverted from what "backfill from the venue" sounds like, and the
consequence is stated in the same header: the recorder writes `trade`/`quote`/`book`, so a hole in
a recorded tape generally **cannot** be repaired from the venue.

The table's `Source` enum names the five places a fill can come from, each with a one-line verdict
in its doc comment: `Venue` (the venue's own API — free, and only as complete as the venue exposes),
`Archive` (the `data.vike.io` / pmxt archives — paid per GB or keyless CC-BY, complete L2 plus
trades), `ClickHouse` (a local capture, prod-side), and the two paid vendors `Databento` and
`Tardis`. `backfill_caps(source, venue)` answers per pair; `sources_for(venue, kind)` is the Data
Manager's answer to a gap — which sources are even worth offering — and `is_unfillable` is the
honest empty result. Polymarket is the sharpest case and was verified rather than assumed: the
bridge implements no price-history endpoint, so its venue row is empty across every kind.

<Callout type="warn" title="A commit key dedups one writer against itself, never two writers against each other">
  `crates/vike-data/src/datafusion_hist/sources.rs`'s header: commit-key idempotency stops the same
  writer re-ingesting a window it already ingested. It does nothing about two different writers
  covering one window — a `live-…` key from the recorder and a `databento:…` key from a backfill are
  different keys, both accepted, and the store never dedups by row value. A `scan_trades` over that
  window returns both copies, and a backtest sees double the volume with nothing reporting a
  problem. `crates/vike-backfill/src/gapfill.rs`'s `plan_fill` exists so you do not create the
  overlap: it emits only the missing days, per kind, narrowed to what `caps` says the source can
  serve. Where the overlap already exists, the store's persisted `StoreSourcePolicy` resolves it —
  the ranked commit-key prefixes `_sources.json` holds, which build the call-time `SourceRankPolicy` —
  strict by default, skipping any series whose commit key matches no ranked prefix, and reporting
  every superseded row.
</Callout>

`plan_fill` is day-granular off the `date=`-partitioned file index, so a day the recorder covered
for six hours reads as present and is never planned; within-day trust is a different question,
answered by `vike_data::quality::DayQuality` over scanned rows (`gapfill.rs`'s header).

## What every bin shares [#what-every-bin-shares]

`crates/vike-backfill/src/cli.rs` is the harness the `*_backfill` bins used to re-implement, and
its `store_root` is the one resolution law for every bin that has a default to resolve — the five
klines bins and `dukascopy_backfill` take the root as a required argument, and `ingest_bench_bars`
resolves its own `market_data/bench_hist` on purpose. The ladder: an explicit `--store`, then
`$VIKE_HIST_STORE`, then `<project>/market_data/hist` when `$VIKE_SETTINGS_DIR` names that project
outright, then `<repo>/market_data/hist` when the box still has that checkout, then the project the
working directory sits in, then the per-user `…/vike-data` directory. The header
records why it had to become one function: the four "verbatim" bins honoured the environment
variable while pmxt/databento/tardis silently ignored it, so one operator variable routed half the
collectors to one store and half to another. The resolved root and the rung that produced it are
logged, because a store does not merge — if the default moves, the old store is simply no longer
read and a backfill reports zero rows into a fresh empty one.

Three more shared rules, each cited to `cli.rs`. `short_circuit` runs first: `--help` and
`--version` are answered on stdout with exit 0 before logging is initialised, before a store is
opened, before any network call — one bin's `--help` used to perform the entire ingest. `log_config`
sets every batch bin's file-log level to `warn` rather than vike-log's `trace` default, and the
measurement behind it is in the same doc: one hour of `pmxt_backfill` wrote 6.4 GB, and a long range
once wrote 341 GB. `VIKE_LOG_FILE_LEVEL` still wins over that default; [log volume](/docs/trader/data-providers/log-volume)
carries the rule for any long run. And every value flag refuses a token beginning with `--` as its
value (`is_flag_token`), so a mistyped command names the flag that went unfed rather than swallowing
the next one.

## Reaching a collector without a terminal [#reaching-a-collector-without-a-terminal]

Two crates depend back on vike-backfill through optional features (`lib.rs` header): the desktop
app — which took it under the deleted `fat` feature and calls nothing directly any more, its bulk
Backfill action now taking only `backfill_route`'s WIRE arm against the datahub's store — and
`vike-datahub`'s `backfill-serve` feature for backfill-on-demand. [Backfill from the
GUI](/docs/trader/gui/data-manager/backfill) covers the first; the store layouts every family writes into
are on [the hist store](/docs/trader/concepts/hist-store) and, kind by kind, under
[concepts/data](/docs/trader/concepts/data).


# Log volume (/docs/trader/data-providers/log-volume)



Every Vike Trader binary logs through `vike-log`: a console layer on stderr and a non-blocking JSON daily-rolling file layer. The two are filtered independently, and that independence is the whole hazard: `RUST_LOG` (aliased `VIKE_LOG`) filters the **console only**. The file layer defaults to `trace` and captures the `log`→`tracing` bridge, so a batch tool driving a chatty dependency — DataFusion, arrow, hyper — writes an enormous JSON file that no console setting can turn down.

<Callout type="warn" title="Measured, not hypothetical">
  `crates/vike-log/src/lib.rs`'s `file_level_directive` records the cost: one hour of `pmxt_backfill` wrote **6.4 GB**, and a long range once wrote **341 GB** and nearly filled the disk hosting a live trading node. The operator's half does not follow from the knob — set it, and on a long run still watch the log directory grow with `du -sh $VIKE_LOG_DIR`.
</Callout>

## `VIKE_LOG_FILE_LEVEL` [#vike_log_file_level]

The file layer's directive is `VIKE_LOG_FILE_LEVEL` first, then the configured `file_level`. `warn` keeps the file useful without the per-row firehose; `off` silences it entirely. An empty or whitespace value falls through to the configuration rather than widening the filter. The registry row in `vike_ops::settings::SETTINGS` lists the default as `trace`; the variable is one of the environment reads catalogued on [environment variables](/docs/trader/reference/environment).

Three places set the configured half:

* **The backfill bins.** `crates/vike-backfill/src/cli.rs`'s `log_config` builds every batch bin's `LogConfig` with `file_level` at `warn` instead of vike-log's `trace`, because these bins run long and unattended. `VIKE_LOG_FILE_LEVEL` still wins, so a one-off debug run can ask for `trace` without a code change.
* **The daemon and the desktop app.** `preferences.log_file_level` in `preferences.toml` (see [preferences](/docs/trader/reference/settings/preferences)) is the file-level knob for `vike-tradehub` and `vike-desktop`: `vike_config::CONSUMPTION` cites `crates/vike-tradehub/src/tradehub_cli.rs` as its consumer and notes `vike-desktop`'s `main` sets it identically. `crates/vike-config/src/preferences.rs`'s `DEFAULT_LOG_FILE_LEVEL` keeps it at `trace` so the crate changes nothing by itself; the field exists so a deployment can turn it down in a file instead of an environment variable. `preferences.log_level` is the console twin.
* **Everything else** inherits `LogConfig::default()`: console `info`, file `trace`.

`vike-tradehub` can apply a changed level without a restart: `vike_log::LogReloadHandles` recomposes the directive through the same pure functions `init` used, so a reload can never produce a filter a restart would not. `reload_file_level` returns an error when no file layer is installed, because a level applied to a layer that does not exist has been applied to nothing.

## Retention is the disk bound; the level is the write-rate bound [#retention-is-the-disk-bound-the-level-is-the-write-rate-bound]

Turning the level down bounds how much is written; nothing bounds how much is kept unless something deletes files. `LogConfig::file_max_files` — default `vike_log::DEFAULT_MAX_LOG_FILES`, which is 3 — prunes to the newest N daily files at `init`, so the count is a retention in days. Three is chosen against the failure it is for: a fault is diagnosed from the run that failed and the one before it. `None` restores keep-everything. It is deliberately a `LogConfig` field and not an environment variable: a retention only an operator can arm is a retention nobody has armed, which is exactly what `VIKE_LOG_FILE_LEVEL` had been.

Pruning matches `filename.starts_with(prefix)`, which is why `LogConfig::file_prefix` now defaults to empty, meaning "derive from this executable" (`effective_file_prefix`). The old shared default `"vike"` starts both `vike-desktop.<date>` and `vike-tradehub.<date>` in the one shared log directory, so a one-shot backfill would have deleted the GUI's and the live daemon's logs.

## The desktop client is its own firehose [#the-desktop-client-is-its-own-firehose]

A render loop logs at frame rate. `HIGH_VOLUME_TARGETS` pins `wgpu_core`, `wgpu_hal`, `naga` and the `eframe::native` subtree to `info` in the file, and its doc carries the measurement: a freshly installed Windows desktop client with no `VIKE_LOG_FILE_LEVEL` set wrote **5.8 GB in 4h10m** — about 1.4 GB an hour, roughly 11 GB overnight — of which Vike's own lines numbered about twenty-five; the rest was `wgpu_core` and `eframe::native`, tens of lines per frame. Retention cannot help there, because one day *is* the 5.8 GB. The pins keep wgpu's one-time adapter and device lines, which a GPU bug report needs, and drop the per-frame lifecycle. An explicit mention wins — `VIKE_LOG_FILE_LEVEL=wgpu_core=trace` restores the firehose when the renderer is what you are debugging — and a pin may only ever narrow: it is never appended to a directive already at `off`, `error` or `warn`.

<Callout title="Two targets are pinned for a different reason">
  `CREDENTIAL_BEARING_TARGETS` pins `ureq` and `tungstenite` to `info` even under `trace`, and this is not about volume. `ureq` prints a request's path and query only at trace — where a Telegram bot token sits in the URL path and other providers' API keys sit in query parameters — and `tungstenite` logs the full WebSocket URI at debug, including Binance's listenKey. The pins survive an operator-set `trace`; `VIKE_LOG_FILE_LEVEL=ureq=trace` is the typed-out opt-in. It is a denylist, so a newly added dependency that logs URLs would leak again.
</Callout>

## Where the file lands [#where-the-file-lands]

`vike_log::resolve_log_dir` has four layers, highest first: `$VIKE_LOG_DIR`; then a config file's `log_dir` or a `--log-dir` flag; then the project's own `<project>/settings/state/logs`, which every shipped binary passes; then `<exe_dir>/logs` as the last resort for a binary with no project above its working directory — `target/debug/logs/…` in a checkout, which `cargo clean` deletes. The file layer is best-effort: a destination that cannot be opened drops the layer with one line on stderr naming the directory and `VIKE_LOG_DIR`, and the console carries on. It used to panic the process with exit 101 for the sole reason that it could not open a log file; `crates/vike-log/tests/unwritable_log_dir.rs` is the gate.

The rule to carry: **set `VIKE_LOG_FILE_LEVEL` for any long backfill or replay run**, check the retention is armed, and treat a Vike-owned line count of twenty-five in a multi-gigabyte file as the signature of a missing pin rather than a busy system.


# Polymarket (/docs/trader/data-providers/polymarket)



`crates/vike-backfill/src/caps.rs` is unambiguous about this venue: verified rather than assumed,
the bridge implements no price-history endpoint — no `/prices-history`, no fidelity parameter — and
no L2 book history exists to fetch, so the venue row is empty across every kind. Every Polymarket
fill comes from an archive or a capture. Two collectors do that; two research bins read the same
sources in place, with no import step at all.

## `pmxt_backfill` — the pmxt archive [#pmxt_backfill--the-pmxt-archive]

The data source is the pmxt Polymarket order-book archive, licensed CC BY 4.0, published as
Parquet by pmxt (`r2v2.pmxt.dev`), which is not affiliated with this project — the attribution the
module carries in its own header (`crates/vike-backfill/src/pmxt/mod.rs`). The bin is a default
target: no feature is needed.

```
pmxt_backfill --from YYYY-MM-DDTHH --to YYYY-MM-DDTHH [--tokens T1,T2,...] [--tokens-file PATH]
              [--store DIR] [--dry-run] [--rate-ms N]
              [--clickhouse [--ch-bin BIN] [--min-local-ts MS] [--max-local-ts MS]]
```

From the bin header (`crates/vike-backfill/src/bin/pmxt_backfill.rs`): it iterates every UTC hour
in the inclusive range; for each it downloads that hour's Parquet part (a 404 means pmxt has not
published it — logged and skipped), decodes it a row group at a time (parts run 130–400 MB, so the
memory bound is the point), and appends the book, trade and quote events to the store. One bad
hour never aborts the range. `--tokens` and `--tokens-file` (one id per line, `#` comments allowed)
union into a filter — a real run's \~78k ids exceed the argv limit, hence the file. `--dry-run`
prints the hour range, the store root and each archive URL and touches nothing. The destination is
visible in `crates/vike-backfill/src/pmxt/ingest.rs`'s `ingest_file`, which appends under
`venue=polymarket` with the token id as the symbol: `kind=book` (snapshots plus deltas),
`kind=trade` and `kind=quote` (the venue's own `best_bid`/`best_ask` carried on `price_change`
rows — prices only, and per `crates/vike-backfill/src/pmxt/map.rs`'s `l1_from_row` the archive's
only complete record of the top of book, without which a delta replay is measurably wrong), the
same series shape the live feed writes, each under a `pmxt:{kind}:{asset}:{hour}` commit key — so
its doc can say re-runs of the same hour are a no-op. The pure mapper
(`crates/vike-backfill/src/pmxt/map.rs`) folds `book` rows to snapshots, `price_change` to
single-level deltas and `last_trade_price` to trades; `tick_size_change` updates per-asset state
that rides on the next book update, defaulting to `0.01` until one is seen.

<Callout type="warn" title="The --clickhouse write path is not idempotent">
  `--clickhouse` switches the target from the hist store to the `polymarket` ClickHouse tables the
  live L2 recorder writes, via `clickhouse-client` INSERTs. Unlike the hist-store path, re-running the
  same hour duplicates every row — track completed ranges yourself
  (`crates/vike-backfill/src/pmxt/ingest.rs`'s `ingest_file_clickhouse`). `--min-local-ts`/
  `--max-local-ts` exist for that reason: a recorder outage rarely starts on an hour boundary, so
  pass the outage's actual `[start, end]` in epoch-ms and only rows inside it are written, while every
  fetched hour is still decoded in full.
</Callout>

## `poly_reparse` — your own raw frames [#poly_reparse--your-own-raw-frames]

The bridge owns a raw-frame tap: `RawTap`/`TappedStream` tee verbatim WS frames plus the local
receive time to gzip files (`Feeds::with_raw_capture`, opt-in).
`crates/bridges/polymarket/src/raw_tap.rs`'s header states its disposition — raw capture is
strictly insurance, losing a frame is acceptable and affecting the live feed is not — and
`poly_reparse` is what re-parses that perishable capture back into the store.
`crates/vike-backfill/src/reparse.rs`'s `GzFileStream` replays those files as a
`vike_polymarket::MarketStream`, so `run_session` re-decodes them through the *same* pump as a live
session, and the captured receive time is restored as `local_ts`. The layout mirrors the writer:
`<root>/polymarket/<token>/date=YYYY-MM-DD/frames-*.jsonl.gz` (`gz_files_for`).

```
poly_reparse --raw-dir DIR --store DIR --token ID --from YYYY-MM-DD --to YYYY-MM-DD \
             --mode book|quotes|trades --tick-size F
```

`--tick-size` must match the value the live session used, or the book quantizes on a different
grid; the operator supplies it, because this offline tool makes no REST fetch (bin header). The bin
is built under the `poly-reparse` feature, which enables `vike-polymarket/feeds`
(`crates/vike-backfill/Cargo.toml`).

`archive_store.rs` notes the convention for whoever reconciles this store with another: it scopes a
range by `ts`, the venue clock, exactly as `DataFusionHist` does.

The archive download itself, and the events API, are on
[the Data API page](/docs/trader/data-providers/vike-data-api). Running the venue live is
[Polymarket operations](/docs/trader/venues/polymarket-operations); the queue models are under
[backtesting](/docs/trader/backtesting/queue-models) and the maker models under
[market making](/docs/trader/market-making).


# Store maintenance (/docs/trader/data-providers/store-maintenance)



Two `vike-backfill` bins maintain a history store rather than fill it from a source. The supervisor that keeps the collectors themselves running is a separate binary, documented at [collector-supervisor](/docs/trader/reference/binaries/collector-supervisor).

## Where the store is [#where-the-store-is]

Most bins in the crate resolve their root through `crates/vike-backfill/src/cli.rs`'s `store_root`, with one precedence: an explicit `--store`, then `$VIKE_HIST_STORE`, then the project's own `<project>/market_data/hist` when `$VIKE_SETTINGS_DIR` names that project outright, then the repo-root default `<repo>/market_data/hist` when that checkout exists on the box, then the `<project>/market_data/hist` found by walking up from the working directory, then the per-user `vike-data` directory. The resolution is logged — root and rung both — for a reason its doc states: a store does not merge. If the default moves, the old store is simply no longer read, and a backfill reports zero rows into a fresh empty one, indistinguishable from "the venue returned nothing" until somebody goes looking. `$VIKE_SETTINGS_DIR` is the override that pins the project, and the same resolver honours it.

## `migrate_to_group` [#migrate_to_group]

```
migrate_to_group --venue NAME [--store DIR] [--group NAME] [--dry-run]
```

Tick series have two layouts — one series per symbol, or one grouped series per family — and this bin folds stray per-symbol series into their family's grouped one. `crates/vike-backfill/src/bin/migrate_to_group.rs` names the two real causes of a store holding the same instrument in both layouts: a family recorded before grouping existed, and two recorder bugs, since fixed, that let rows escape (a max-rows flush that skipped the group resolver, and a rotation that unmapped a symbol while its rows were still buffered).

Such a store is not wrong: `scan_*` reads both layouts, so no row is lost or hidden. It is untidy in ways that cost later — the coverage report in the [Data Manager](/docs/trader/gui/data-manager) lists one instrument twice, maintenance treats them as unrelated series, and every scan opens both.

<Callout type="warn" title="It refuses when the target is ambiguous">
  The store cannot know which family a stray token belonged to — that knowledge lived in the recorder's in-memory membership map and was never persisted. So a fold happens only when the venue has **exactly one** grouped series for that kind. With none there is nothing to fold into; with several, picking one would write rows into the wrong family, which no later pass can untangle. `--group NAME` names the target explicitly for the several case.
</Callout>

`crates/vike-backfill/src/regroup.rs`'s `plan_regroup` is the pure half: per kind it yields `KindPlan::Fold`, `NoTarget` or `Ambiguous`, and kinds with no strays are absent. `GROUPABLE_KINDS` is `quote`, `trade`, `book` and `depth`; `bar` has no grouped append and never folds. A forced `--group` overrides the target for every kind, including a kind that had no group at all, which is what lets a fold into a brand-new group name work.

The I/O is `vike_data::DataFusionHist::migrate_series_to_group`, and its order is deliberate: copy, verify, then delete. Rows are appended under a `migrate:{kind}:{symbol}` commit key, so re-running is a no-op rather than a double-append; the grouped read is checked to contain them; only then is the per-symbol source removed. A failure anywhere before that leaves both copies — untidy, which is what it already was, never missing. One series failing never aborts the rest; the run prints series planned, rows moved and series skipped. `--dry-run` prints the plan and writes nothing.

## `ingest_bench_bars` [#ingest_bench_bars]

```
ingest_bench_bars
```

The seed for the two-engine benchmark, `cargo bench -p vike-backtest --features bench-hist`. It ingests a Python parquet bar cache into a self-contained bench store — the pure-Rust replacement for a retired Python exporter, with no venv, pandas or SQLite — and is idempotent by commit key (`bench:{sym}:{month}`), so a re-run is a no-op.

It takes no options; both paths are fixed at compile time. The source is `<vike-trader-app>/storage/parquet/<SYMBOL>/1m/<MONTH>.parquet` with columns `ts,open,high,low,close,volume`; the destination is `<this checkout>/market_data/bench_hist`, written as `kind=bar`, `venue=binance`, interval `1m`, and derived from the crate directory at compile time so the ingest writes into its own checkout from any worktree rather than a hardcoded absolute path. `SYMBOLS` is the five-symbol canonical order (`BTCUSDT`, `ETHUSDT`, `SOLUSDT`, `DOGEUSDT`, `ADAUSDT`; BTCUSDT doubles as the single-symbol bench series) and `MONTH` is `2026-06`.

<Callout title="The --help that ran the job">
  This bin once read no argv at all, so `ingest_bench_bars --help` opened a store, created a directory and wrote bars — the worst shape in the family, because `--help` is the safest-looking thing a person types first. The triage now runs before the log subscriber and before the store, and `crates/vike-backfill/tests/help_cli.rs` asserts both the exit status and that no store directory appeared. `crates/vike-backfill/src/cli.rs`'s `short_circuit` generalises the rule in its own doc — call it first, before `vike_log::init`, before opening a store, before any network call, because answering a question about the command line must not create a log file, create a store directory, spawn a subprocess or ingest anything.
</Callout>

Both bins log through the crate's shared `log_config`, which caps the JSON file at `warn`; see [Log volume](/docs/trader/data-providers/log-volume).


# Tardis (/docs/trader/data-providers/tardis)



`tardis_backfill` ingests Tardis's downloadable CSV datasets. `crates/vike-backfill/src/tardis/mod.rs`
states the lane: intraday trades, quotes and the L2 book — and bars via resample — from
`datasets.tardis.dev` into the `vike-data` hist store, a sibling of the pmxt and EOD collectors. It
is built only under the `tardis` feature (`crates/vike-backfill/Cargo.toml`), so the invocation is
`cargo run -p vike-backfill --features tardis --bin tardis_backfill`.

## What a run does [#what-a-run-does]

From `crates/vike-backfill/src/bin/tardis_backfill.rs`'s usage text:

```
tardis_backfill --exchange deribit --symbol BTC-PERPETUAL --data-type trades \
    --start 2024-03-01 --end 2024-03-03 [--store DIR] [--venue NAME]
tardis_backfill --exchange deribit --symbol BTC-PERPETUAL --data-type bars \
    --start 2024-03-01 --end 2024-03-03 --interval 5m
```

`--exchange` is the Tardis exchange id (`binance-futures`, `deribit`), `--symbol` the instrument on
that exchange, and `--data-type` one of `trades`, `quotes`, `incremental_book_L2` or `bars`.
`--start`/`--end` are inclusive `YYYY-MM-DD` days. `--store` resolves through the shared
`store_root` ladder — `$VIKE_HIST_STORE`, then a `$VIKE_SETTINGS_DIR`-declared
`<project>/market_data/hist`, then `<repo>/market_data/hist` when that checkout exists, then the
project the working directory sits in, then the per-user `vike-data` directory; `--venue` is the
label the series is stored under, defaulting to `tardis`.

`bars` is not something the vendor serves. The bin header is explicit: Tardis has no native OHLCV
series, so `--data-type bars` ingests trades and then resamples them into `--interval` OHLCV
(default `1m`) — real OHLCV with real trade volume — and the trades series is persisted too. The
resample is the store's own `resample_trades_to_bars`, called from the bin.

## Transport and ingest [#transport-and-ingest]

`crates/vike-backfill/src/tardis/client.rs` builds the per-day `.csv.gz` URL, authenticates with a
Bearer token, and downloads plus gzip-decompresses one day's file. A missing day — HTTP 404 — is
`Ok(None)`, not an error, mirroring the pmxt collector's `download_hour`.
`crates/vike-backfill/src/tardis/ingest.rs` drives the parsers one day at a time under the commit
key `tardis:{kind}:{symbol}:{YYYY-MM-DD}`; `backfill_range` iterates the requested days and skips the
absent ones. Because the unit is a whole UTC day, re-running a day is a store no-op.

## The parsers [#the-parsers]

`crates/vike-backfill/src/tardis/parse.rs` is pure and fixture-tested, and its header carries the
wire facts: timestamps are microseconds, reduced to milliseconds; trade `side` is `buy`/`sell`,
where a sell taker means the buyer is the maker. `incremental_book_L2` rows are single-level —
`is_snapshot` selects Snapshot over Delta, `side` routes the level to bids or asks, and `amount` is
the absolute size with `0` meaning the level was removed. A monotonic per-symbol `seq` is assigned in
file order so that `scan_book_updates` reproduces file order. Column lookup is by name through
`crates/vike-backfill/src/csvutil.rs`'s `Header`, the helper shared with the Databento parsers.

## Credentials [#credentials]

`TARDIS_API_KEY` is optional, and the reason is in the bin header: the first-of-month day is a free,
keyless sample, so a run over that day needs no key at all. The bin reads the key and passes it in;
the library takes it as a parameter (`crates/vike-backfill/src/databento/client.rs`'s header records
that the Tardis adapter always had the bin do the read, and that Databento was brought in line with
it). The live smoke is `#[ignore]`d and runs keyless for exactly that reason — it asks for the
first-of-month day (`crates/vike-backfill/tests/tardis_smoke.rs`'s
`tardis_trades_one_day_roundtrip`). Its Databento sibling has no free day to fall back on, so that
one self-skips when the key is absent (`crates/vike-backfill/tests/databento_smoke.rs`).

## Where it sits in the capability table [#where-it-sits-in-the-capability-table]

`crates/vike-backfill/src/caps.rs`'s Tardis row is `NONE` for every roster venue: the comment on it
says the vendor writes the tick lane — trades, quotes, `incremental_book_L2` — with bars by
resample, is crypto-only, and is vendor-namespaced rather than roster-keyed, the same shape as
Databento. A gap plan over a roster venue therefore never offers Tardis; you reach it by naming the
exchange and symbol yourself, and the `--venue` label decides which store partition the rows join.

<Callout type="warn" title="The vendor's exchange id and your venue label are two different strings">
  `--exchange binance-futures` chooses what Tardis serves; `--venue` (default `tardis`) chooses the
  store partition. Writing vendor rows under a roster venue's name puts them beside whatever the
  recorder captured there, and the store dedups by commit key rather than by row value
  (`crates/vike-data/src/datafusion_hist/sources.rs`), so a window both covered is doubled until a
  source-precedence policy resolves it. [The Data API page](/docs/trader/data-providers/vike-data-api)
  covers that policy.
</Callout>

The kinds these data types write are documented under [concepts/data](/docs/trader/concepts/data); the
equities-and-futures counterpart is [Databento](/docs/trader/data-providers/databento).


# Venue-direct (/docs/trader/data-providers/venue-direct)



Seven bins in `crates/vike-backfill` talk to a venue directly, and all seven sit behind the
`venue-backfill` feature (`crates/vike-backfill/Cargo.toml`): `binance_backfill`,
`bybit_backfill`, `okx_backfill`, `aster_backfill`, `deribit_backfill`, `dukascopy_backfill` and
`hyperliquid_backfill`. A default build has neither the module nor the bridge dependency, so the
invocation is `cargo run -p vike-backfill --features venue-backfill --bin <name>`. What they have
in common, from `crates/vike-backfill/src/caps.rs`: every one of them writes `kind=bar`, and
Dukascopy is the only venue-direct source that also serves a tick kind — quotes, never trades,
because `.bi5` is a quote feed. None of them can repair a recorded trade or book gap.

## The five klines bins [#the-five-klines-bins]

`binance`, `bybit`, `okx`, `aster` and `deribit` differ in nothing but the venue.
`crates/vike-backfill/src/klines.rs` is the one place their shape lives: `commit_key` is the
idempotency format, `backfill_klines` the fetch→ingest orchestration each venue binds with its own
`VENUE` constant and bridge fetcher, and `run_klines_backfill_cli` the CLI body every bin calls.
Its `klines_usage` text is what `--help` prints, and it is exact about the arguments:

```
<venue>_backfill <ROOT_DIR> <SYMBOL> <INTERVAL> <START_MS> <END_MS>
```

All five are required and positional, in that order, and the window is in epoch
**milliseconds** — the usage names seconds as the mistake that silently backfills 1970. Bars land
under `kind=bar/venue={venue}/symbol=SYMBOL/interval=INTERVAL`, re-running the same window writes
0 rows, and a still-forming final candle is dropped. The `crates/vike-backfill/src/lib.rs` header
gives the key's shape: `{venue}:{symbol}:{interval}:{start}-{end}`. There is no resample step —
klines are already bars.

Per venue, from each bin's own header:

* **Binance** (`crates/vike-backfill/src/bin/binance_backfill.rs`) pages the public REST endpoint
  at 1000 rows per request. It is the one bin of the family whose persisted pace actually
  steers, because Binance is the only venue of the five that publishes a `REQUEST_WEIGHT` budget
  for the pager to discover; the record is keyed `(binance, spot|perp)` because the two hosts
  publish different budgets (6000 vs 2400 weight per minute) and price `/klines` differently
  (weight 2 vs 5).
* **Bybit** (`bybit_backfill.rs`) pages 1000 rows per request, newest-first and reversed by the
  fetcher. `crates/vike-backfill/src/bybit.rs` warns that the endpoint is end-anchored — it
  ignores `start` once the window exceeds the cap and answers the newest 1000 rows with
  `retCode: 0` — so the bridge pages backward and a window wider than 1000 intervals is normal
  here, never silently clipped.
* **OKX** (`okx_backfill.rs`) pages the `history-candles` endpoint backward through its
  100-row cap via the `after` cursor. Its per-page cost was measured on prod2 on 2026-08-04 at
  476–486 ms, against a 200 ms delay nobody had ever checked.
* **Aster** (`aster_backfill.rs`) reads keyless public mainnet REST; a symbol carrying the `.P`
  suffix (`BTCUSDT.P`) fetches the USDⓈ-M perpetual and is stored under that suffixed key, a bare
  symbol fetches spot. `crates/vike-backfill/src/aster.rs` says why mainnet is not a risk decision
  here: klines are a keyless public read, so the standing rule to exclude Aster from validation
  runs — which is about authenticated account calls — does not reach this path.
* **Deribit** (`deribit_backfill.rs`) pages the venue's public, keyless chart-data JSON-RPC
  endpoint. `SYMBOL` is a Deribit instrument name passed through verbatim (`BTC-PERPETUAL`, a
  dated future) — there is no `.P` suffix on this venue, because the name is already
  unambiguous. The endpoint is end-anchored like Bybit's and is paged backward.

<Callout type="warn" title="A 24-month 1m pull on Deribit is a lot of requests and a lot of log">
  `deribit_backfill.rs`'s header: set `VIKE_LOG_FILE_LEVEL=warn` for it — the file layer is `trace`
  by default and does not listen to `RUST_LOG`. The rule for every long run is on
  [log volume](/docs/trader/data-providers/log-volume).
</Callout>

## The pace book [#the-pace-book]

`crates/vike-backfill/src/pace_book.rs` explains what the klines bins persist and why: every
backfill measures its own pace — the wall clock of a request, the weight one request costs — and
used to discard it at exit, so run N+1 opened on a pessimistic constant (on Binance spot, where a
page costs weight 2, the pacer's seed of 5 paced the first pages 2.5× slower than the venue
permits). The record is written down and the next run reads it. `run_klines_backfill_cli` resolves
the file through `crates/vike-backfill/src/cli.rs`'s `pace_book_path`: `$VIKE_PACE_BOOK`, then
`<project>/settings/state/pace.json`, then `<ROOT_DIR>/pace.json` for a binary with no project
above its working directory.

The file is a cache and follows a never-brick law: a missing, unreadable or unparseable file is
"no record", deleting it costs one run's opening pages and nothing else. And a record does not mean
a faster backfill. `run_klines_backfill_cli`'s doc is blunt: Binance's genuinely re-paces the first
page, while Bybit, OKX and Deribit's pagers answer their hardcoded `PAGE_DELAY` whatever is stored
— for them the record buys an ETA line from page zero and an operator-readable per-page cost.
Aster is the one bin that persists nothing at all, because its host is environment-resolved and the
bridge exposes no paced fetch to plumb a sample through (`aster_backfill.rs`).

## Dukascopy ticks [#dukascopy-ticks]

`crates/vike-backfill/src/bin/dukascopy_backfill.rs` takes a different argument shape:

```
dukascopy_backfill <ROOT_DIR> <SYMBOL> <START_MS> <END_MS> [INTERVAL]
```

It fetches tick history for a symbol such as `EURUSD` from Dukascopy's keyless `.bi5` datafeed,
appends the quotes, then — if `INTERVAL` is given — resamples the stored quotes into OHLCV bars.
`crates/vike-backfill/src/dukascopy.rs` names the pipeline: `fetch_ticks_range` → `tick_to_quote` →
`append_quotes` → `resample_quotes_to_bars`, the last being the parity-tested
`vike_model::consolidate_quotes`. It is history-only: Dukascopy publishes with a T+1 lag. This was
the crate's first collector, and `crates/vike-backfill/src/lib.rs`'s header still introduces it that
way — the first collector, keyless `.bi5` tick history to `QuoteTick`s to the store, plus a
quote-to-bar resample.

## Hyperliquid candles [#hyperliquid-candles]

`crates/vike-backfill/src/bin/hyperliquid_backfill.rs` pages the keyless `candleSnapshot` `/info`
endpoint on mainnet with named flags rather than positionals: `--symbols` is a comma list of
`vikeSymbol=coin` pairs (bare `SYM` means coin equals symbol — HL perps use the coin as the symbol,
`BTC`/`HYPE`), `--interval` is one of `1d`, `1h`, `5m`, `1m`, and `--start`/`--end` are each an
epoch-ms integer or a `YYYY-MM-DD` UTC date with `--end` defaulting to now. The fetcher pages
forward by advancing `startTime` past each page's last candle close
(`crates/vike-backfill/src/hyperliquid.rs`), and the one wrinkle is that the store symbol may
differ from the coin the fetch pages, so the commit key and append key on the symbol. Series land
as `kind=bar`/`venue=hyperliquid`, idempotent per window. The same module owns the realized-funding
backfill, which is on [funding rates](/docs/trader/data-providers/funding-rates).

The klines trio `backfill_{binance,bybit,okx}_klines` is also what the desktop app's bulk Backfill
action and `vike-datahub`'s backfill-on-demand call (`lib.rs` header) — see [Backfill from the
GUI](/docs/trader/gui/data-manager/backfill).


# The vike.io Data API (/docs/trader/data-providers/vike-data-api)



`data.vike.io` is one vendor reached two ways, and the two are different tools with different
features, keys and store kinds. `vikedata_backfill` reads the `/v1` REST API — cohort metrics and
the hourly asset panel — behind the `vikedata` feature. `vike_archive_backfill` reads the Polymarket
L2 Parquet archive behind the `vike-archive` feature. `crates/vike-backfill/Cargo.toml` explains why
they were deliberately not folded into one feature: the archive lane pulls a ranged-HTTP Parquet
reader and a worker pool that a cohort-metrics build would compile for nothing.

## Route one: `vikedata_backfill` and the `/v1` API [#route-one-vikedata_backfill-and-the-v1-api]

`crates/vike-backfill/src/vikedata/mod.rs` describes what it fetches: one
`(exchange, asset, axis, grading)` ladder over one hourly window from
`GET {base}/{exchange}/coins/{asset}/cohort-metrics`, paged by cursor — for each hour and each
cohort label, the long-side and total notional the grading service reported — landing as
`kind=cohort` rows through `vike_data::CohortRecorder`. The module builds no commit key of its own:
`crates/vike-data/src/cohort_rec.rs`'s `CohortFetch` is the one place
`cohort:{venue}:{asset}:{axis}:{grading}:{label_basis}:{start}-{end}` is spelled.

The bin header (`crates/vike-backfill/src/bin/vikedata_backfill.rs`) defines three run shapes, and
which one a timer may use:

```
vikedata_backfill --asset BTC --schedule --catch-up 3          # SCHEDULED — the only timer shape
vikedata_backfill --asset BTC --axis size --days 30            # periodic — MANUAL ONLY
vikedata_backfill --asset BTC --axis pnl --grading unrealized --start 2026-04-01 --end 2026-04-08
```

`--axis` is `size`, `pnl` or `tier` (default `size`); `--grading` is `realized`, `realized-pit` or
`unrealized` and is refused off the `pnl` axis; `--exchange` defaults to `hyperliquid`; `--api-base`
defaults to `$VIKE_API_BASE`, else `https://data.vike.io/v1`. `--panel` switches to the hourly asset
panel (`/v1/{exchange}/assets/hourly`) and writes `kind=perp_metrics` rows — `(ts, premium,
open_interest)` per hour — under `perp_panel:{venue}:{asset}:{start}-{end}`; the usage text names it
the only producer that fills `open_interest`, and
`crates/vike-backfill/src/vikedata/panel.rs` states why: the venue's own surface serves OI as a
current snapshot and nothing else.

<Callout type="warn" title="A trailing window on a timer doubles the hours two firings share">
  `crates/vike-backfill/src/vikedata/schedule.rs`: idempotency is batch-level on the commit key, so
  re-running the same command writes 0 rows, but two overlapping windows are two keys and every hour
  they share lands twice. Fire `--days 30` at 04:00 and again at 05:00 and you have 719 hours of
  doubled notional in a series whose whole purpose is a ratio. `--schedule` is the shape that cannot
  express it: whole complete UTC days off a fixed grid, only for days that have ended, so two firings
  inside one day emit identical windows and two days emit adjacent ones. `--catch-up N` re-attempts
  the preceding days (default 1, max 31 — every extra day is a metered request on every firing).
</Callout>

The guards are the value, and `vikedata/mod.rs` lists them as ported rules: `label_basis` must
agree across every page and an absent one is a hard failure on the `pnl` axis (the endpoint's
default resolves a wallet's cohort at query time, which is lookahead, and it shipped once); the
grading echo must match what was asked; a `(ts, cohort)` seen twice across a page overlap is
first-wins; the cursor walk has three stops, including a window break, because the endpoint keeps
serving up to its own now regardless of the `start` sent; both notionals are snapped before
anything is derived from them (measured: 430 of 8,190 rows differing at \~1.4 ULP between two GETs of
a byte-identical URL); and the hour label is multiplied from seconds to milliseconds, because an
unmultiplied row lands in the 1970 partition for good.

The header also says what is measured and what is not. Against the live endpoint on 2026-08-25, the
`pnl` `label_basis` echo is real and the auth header is case-insensitive; a `--axis size --days 1`
run stored 300 rows. Still unmeasured: the `pnl` and `tier` axes end to end, and any cursor walk past
one page.

`VIKE_API_KEY` comes from the credential store and is sent as an `X-API-KEY` header
(`crates/vike-backfill/src/vikedata/client.rs`). Absent is a refusal, not a fallback: an
unauthenticated fetch 403s part-way through a window and would store a partial batch under a key
claiming the whole one, indistinguishable from a thin tape afterwards (bin header).

## Route two: `vike_archive_backfill` and the Parquet archive [#route-two-vike_archive_backfill-and-the-parquet-archive]

`crates/vike-backfill/src/vike_archive.rs` describes the archive: Polymarket full L2
(`book_events`), taker tape (`trades`) and derived top-of-book (`l1_quotes`), one UTC day per
Hive-style partition at `{base}/venue=polymarket/date=YYYY-MM-DD/{stream}.parquet`, plus an open
`manifest.json` needing no key. Auth is an `X-API-Key` header; the bin reads
`VIKE_ARCHIVE_API_KEY` from `<project>/settings/secrets.env` and passes it in as a parameter. The
sizes are the vendor's own: a `book_events` day runs \~7.4 GB, 465M rows, 453 row groups.

```
vike_archive_backfill --from YYYY-MM-DD --to YYYY-MM-DD [--kind book|trade|quote|all]
    [--tokens T1,T2,...] [--tokens-file PATH] [--store DIR] [--dry-run]
    [--asset NAME --tenor NAME] [--bulk ...] [--file PATH [--jobs N]]
```

The module's differentiator is that it does not need the whole file: `HttpRangeReader` implements
the `parquet` crate's `ChunkReader` over ranged GETs, so the reader pulls the footer (\~1.17 MB in
two range reads) and then only the column chunks of row groups whose `token_id` min/max statistics
bracket a requested token (`select_row_groups`). A filtered single-token scan costs one row group —
tens of MB — rather than the day. Ingest streams one row group at a time and commits under
`vikearchive:{kind}:{date}:rg{idx}`, a per-row-group key that makes a partial run resumable.

The bin header (`crates/vike-backfill/src/bin/vike_archive_backfill.rs`) then records where the time
actually goes. A `book_events&#x60; day costs \~419 row groups × one HTTP round trip each through the
CDN — hundreds of seconds of network latency, not compute. &#x2A;*`--file PATH`** is the measured fix:
download the day file once, then ingest it locally through the identical decode/map/commit pipeline
(`LocalFileReader` in place of `HttpRangeReader`), committing byte-identical rows under the same
keys. `--file` needs an unambiguous target — `--from` equal to `--to`, and an explicit `--kind` —
and it is mutually exclusive with `--asset`/`--tenor`, the pair that switches to the family layout
(`venue=polymarket/asset=<asset>/tenor=<tenor>/date=.../{stream}.parquet`, resolved through the
`/v1/archive/datasets` and `/v1/archive/url` discovery calls). `--jobs N` fans the local ingest
across worker threads (default `min(4, available_parallelism)`), and `--bulk` switches to
`vike_data::BulkIngestSession`'s staged commit profile (defaults 20 row groups / 2M rows / 256 MB
per window). The two compose.

<Callout type="warn" title="A resumed --bulk run must repeat the same --jobs">
  Bulk idempotency is by commit key, and the keys embed a chunk index that is a function of the
  selected row groups and the job count. Re-running a crashed `--jobs 4` import as `--jobs 8`
  re-chunks, mints different keys, and rewrites rows already committed — duplicates, not a no-op,
  because the store never dedups by row value
  (`crates/vike-backfill/src/bin/vike_archive_backfill.rs`'s header states the rule, and
  `resolve_jobs` beside it carries the fan-out's own measurements).
</Callout>

Two siblings share this lane. `events_api_backfill` reads the live `/v1/events` endpoint under the
same feature and key and is on [EOD, events and exec trades](/docs/trader/data-providers/eod-and-events).
And `crates/vike-data/src/archive_store.rs`'s `ArchiveParquetHistStore` skips the import
entirely, answering `HistStore` reads straight off downloaded day files — the route
[the Polymarket page](/docs/trader/data-providers/polymarket) recommends for research.

## When two writers cover one window [#when-two-writers-cover-one-window]

`crates/vike-data/src/datafusion_hist/sources.rs` is where the store keeps the rule this vendor
makes necessary. Commit-key idempotency stops the same writer re-ingesting a window; it does nothing
about two different writers — the recorder's `live-…` key and a backfill's — covering one window,
and the store never dedups by row value, so a scan returns both copies. `StoreSourcePolicy` — the
ranked prefix list plus its `strict` flag, which builds the call-time `SourceRankPolicy` — is
persisted next to the data as `_sources.json` so `DataFusionHist::run_maintenance` can resolve
duplicates on its own, and the header lists what makes a row-dropping pass safe on a timer: an
absent policy file is byte-identical to today; an empty prefix list supersedes nothing; a series
whose commit key matches no listed prefix is skipped, with the key named, unless `strict: false` is
set; and every drop is reported through `rows_superseded`. It is not a claim about which source is
better — only which one this operator decided wins.


# Adding a venue (/docs/trader/developer/adding-a-venue)



Adding a venue touches a per-venue table in a couple of dozen files. Nobody knows how many, and that
is deliberate: **no count is written down anywhere**, because every hand copy of a roster in this
tree has rotted, and the brief that first asked for a scaffold listed nine such sites from memory and
was already far short. `just new-venue-sites` prints the derived set. `just new-venue NAME` fills it
in.

## The roster is one const, and it fails everything until you classify [#the-roster-is-one-const-and-it-fails-everything-until-you-classify]

`crates/vike-model/src/venues.rs`'s `VENUES` is the single canonical roster — the authority on
"every venue Vike Trader has a bridge crate for". Four per-venue capability tables had each grown
their own private copy of the venue list inside their rows and completeness tests, and those copies
had already drifted: one venue was absent from three of the four.

The contract now is that &#x2A;*every per-venue table's completeness test iterates `VENUES`**, so adding
an entry fails every table's tests until its rows land. Fallback arms stay for genuinely unknown
strings, but no roster venue may silently ride one: a roster venue's row is always *named*, even when
its value equals the fallback, because the named row is the declaration that the venue was
classified rather than forgotten.

## The scaffold, and why its work-list is derived [#the-scaffold-and-why-its-work-list-is-derived]

Each per-venue table declares its **own** insertion point, next to its own rows, with a marker
comment carrying its own template:

```text
// vike:new-venue:row  "{venue}" => VenueCaps::…,  // TODO(new-venue: {venue}): …
// vike:new-venue:note <free text — a step a generator cannot safely take>
```

The scaffold walks the tree, renders every template, and inserts it above its marker —
`crates/vike-bridge-core/src/tif.rs` and `crates/vike-bridge-core/src/pump_spec.rs` each carry one,
next to the rows it belongs to. The generator knows nothing about which tables exist, so a **new**
capability table joins the form by adding one marker line — no generator change.
`crates/vike-ops/tests/new_venue_gate.rs` supplies the missing half: an independent derivation of
which files *need* a marker, so a table cannot join the tree without joining the form. The scaffold
fills in the shape; the gate makes you fill in the content, because every generated row is tagged
and `no_scaffold_placeholder_survives_into_main` refuses the tag.

**How a row site is derived.** `row_sites` calls a `.rs` file a row site when it names all but at
most `ROW_SITE_MISS_TOLERANCE` of the ids in `VENUES` as quoted string literals — the actual
signature of a per-venue table, and nothing else in the tree names the whole roster. The tolerance
matters: requiring *every* id erased precisely the tables that were already missing a row, and
erased them *because* a venue had been added, which is the exact moment the form matters.

The tempting alternative — "a `#[test]` whose body iterates `VENUES`" — is measurably worse in both
directions. It over-matches on a test that iterates the roster only to mirror another table; and it
under-matches on a file whose roster loop asserts nothing per venue, so a new venue's missing row
there is invisible to a test-shape derivation and to the suite alike. Literals find it; failures do
not.

<Callout type="warn" title="The derivation is a generous proxy, and three of its sites gate nothing">
  It answers "does this file carry a per-venue table", not "does this file go red". Three of the sites
  it finds gate nothing at all for a new venue — a missing row there is a silent wrong answer, which is
  strictly worse than a red test. A derivation keyed on redness would have skipped exactly those.
</Callout>

Structural files — the workspace `members` list chief among them — are not `.rs` and name no venue
literal, so they sit outside the derivation and are pinned by hand in `STRUCTURAL_SITES` with the
reason each is still checkable elsewhere. The local CI crate roster used to be one of them and no
longer is: it is derived, so a new venue joins the local gate the same way it joins the merge gate —
by being a workspace member. That is a step *deleted* from the form rather than automated.

A rendered row's *compilation* is deliberately not gated — that is the compiler's job, and the round
trip (`just new-venue foo` → `cargo check` → `just new-venue-remove foo`) is how a template change is
proven. One formatting trap *is* gated, because it defeats the scaffold rather than merely looking
bad: a generated row ending in a trailing `//` comment directly above a marker is rustfmt-unstable —
the formatter re-indents the marker onto the comment's column, the format check goes red on the
tool's own output, and the moved marker then breaks removal. Measured against the real formatter, a
following *statement* is not a reprieve; only a following comma-separated **element** is.

## The shared homes are consumed, never modified in passing [#the-shared-homes-are-consumed-never-modified-in-passing]

A venue conversion consumes three shared homes: the venue **family drivers**, the `vike-bridge-core`
pumps, and the per-venue capability tables. A missing knob in any of them is a **stop-and-report**,
not a local patch — the extension lands as one coordinated pull request informed by every consumer's
report.

The playbook for a behaviour divergence found across adapters is two steps, never one. **Step 1
declares today's reality**: a static capability map, one row per venue citing the adapter code it was
read from, a verbatim matrix pin, and a completeness test iterating `VENUES` — merged
byte-identical, with contradictions *pinned* rather than fixed. **Step 2 flips behaviour**, one venue
row at a time, behind demo smokes.

## What the new bridge must satisfy [#what-the-new-bridge-must-satisfy]

Two shared conformance harnesses in `crates/vike-bridge-core/tests/` machine-check the venue-adapter
contract, each carrying its own roster-exhaustiveness test over `VENUES` — so every roster venue is
either a covered implementation or a deferred-with-reason row, and a new venue reddens both until it
is classified. `bridge_conformance.rs` runs one scenario table against each covered venue's real
event mapper folded through the real order FSM, checking the emitter split, no-silent-vanish, and
exactly-one-terminal; `market_data_conformance.rs` is the market-data twin over each venue's real
frame router.

The contract those harnesses enforce is described on
[The ExecutionClient seam](/docs/trader/concepts/execution-client-seam) and
[Order lifecycle](/docs/trader/concepts/order-lifecycle); the per-venue pages live under
[Venues](/docs/trader/venues).


# Building (/docs/trader/developer/building)



Vike Trader is a Cargo workspace of small crates. A plain `cargo build --workspace` is a real build
of most of it — but not of all of it, and the gap is the first thing worth understanding before you
change anything.

## The roster is derived, never written down [#the-roster-is-derived-never-written-down]

CI does not read a hand-maintained list of crates. It computes one:
`sorted(names - EXCLUDE_FROM_CI)` over the workspace members `cargo metadata` reports. That is
`xtask/src/ci/mod.rs`'s `ci_crates`, and the consequence is the point — &#x2A;*a crate joins the merge
gate the moment it joins `[workspace].members`**, with nothing to edit to let it in.

`xtask/src/ci/tables.rs`'s `EXCLUDE_FROM_CI` is the whole of the exception, and each row carries its
reason: the vendored IBKR wire-protocol copy (exercised through its own feature lane); `vike-desktop`,
the egui/wgpu desktop binary, whose eframe + wgpu closure matches no other lane's cache and which
is instead checked, linted and unit-tested by its own dedicated job; and `vike-backfill`, which only
builds and tests under features. `xtask` itself is deliberately absent from that list — excluding
the tool that derives the merge gate would leave it as the one crate the merge gate never compiles.

## A default build is not the whole tree [#a-default-build-is-not-the-whole-tree]

Large parts of the workspace are behind off-by-default Cargo features, and the reason is usually
that a default build should not compile them: an order signer, a proprietary SDK shim, a remote
control channel, a DataFusion dependency. Each of those configurations gets a **feature lane**.

Two files own the lanes between them, and they own different halves.
`xtask/src/ci/tables.rs`'s `FEATURE_SUITES` decides which suite keys the plan may emit and which
crates trigger each one; the shell script CI runs decides, in its `case` arms, what each key
actually runs. `xtask/src/lib.rs`'s header states that split, and records that moving the lane
commands into the crate would be a separate change with its own gate to rewrite. The `features` job
wires the first straight into the second, so the two key sets are one roster written twice — which
is why they are gated against each other. Nearly every row there carries a written argument for the
coverage hole it closes, and `tables.rs` states the rule for editing it: a row there is not a
preference, it is a claim about what CI would otherwise fail to test.

<Callout type="warn" title="A lane is defined in one place, and this page is not it">
  What a lane compiles is decided by the `case` arms of the feature-suite shell script CI executes;
  `xtask/src/lib.rs`'s header records exactly that split. That script ships with the private build
  tooling rather than the published tree, so no summary of it — this page included — can be checked
  against it. What you can open is the other half: `xtask/src/ci/tables.rs`'s `FEATURE_SUITES` names
  every suite key and the crates that trigger it.

  Treat a lane's crate list here as history, not as a spelling. Two lanes have already been widened,
  and each widening is argued on its own trigger row in that table. The FXCM one twice: first when
  the live mount arm landed behind vike-mount's own `fxcm` feature, then when the release grew an
  FXCM-linked daemon asset. The IBKR one twice: first when the live-mount chain above the bridge
  crate turned out to be compiled by nothing, then again when the daemon itself grew an `ibkr`
  feature and the chain reached one crate further. Re-spelling a lane from a prose copy is how a
  chain silently drops out of it.
</Callout>

## The one committed cargo config [#the-one-committed-cargo-config]

Two files configure the compiler for everyone who clones the repository: `.cargo/config.toml` and
the root `Cargo.toml`'s profile tables. Neither is anybody's code, both are read on every build, and
a change to either arrives without a call site to review it — which is why
`crates/vike-ops/tests/build_config_gate.rs` exists.

It reads **every** file cargo would honour, not the one at the root. Cargo merges `.cargo/config.toml`
— and the pre-1.39 extensionless `.cargo/config` — out of every ancestor directory of wherever it was
invoked, closest-wins, so a config placed under `crates/` outranks the repository root for the normal
inner loop. `only_the_repository_root_carries_a_cargo_config` refuses that shape outright: a setting
that applies depending on which directory you happen to be standing in cannot be reviewed by reading
a diff.

Two content rules follow. `every_cargo_config_table_is_windows_scoped` requires every table to be
scoped to `x86_64-pc-windows-msvc`, as an allowlist rather than a banned-table list, because a banned
list is a hand copy of cargo's vocabulary and would rot the day cargo adds a table. And
`no_committed_cargo_setting_decides_which_program_runs` refuses `rustc-wrapper`, `rustc`, `rustdoc`
and `runner` in every table, the Windows one included. `linker` is deliberately *not* in that set:
a linker receives object files and rustc's own link arguments, while `rustc-wrapper` and `rustc`
receive every source file in the tree, `rustdoc` runs the doctests, and `runner` receives the
compiled test binary — which would turn `cargo test`, the command every gate runs under, into
"execute a program of this file's choosing" before any assertion in any of them is reached.

The guarantee, exactly: a committed cargo setting in this repository may name the linker the Windows
dev box runs, and no other program, on no other host.

## Why `just xtask`, and not `cargo xtask` [#why-just-xtask-and-not-cargo-xtask]

The usual convention for a repository's build tool is a `cargo xtask` alias. &#x2A;*There is deliberately
no such alias here.** An alias lives in `.cargo/config.toml`; `build_config_gate.rs` requires every
leaf path in that file to sit under `target.x86_64-pc-windows-msvc`; and cargo does not allow
`[alias]` to be target-scoped. No spelling of the convention passes the gate that protects the Linux
boxes holding the credential store, so `xtask/src/main.rs` says so in its own header and a `just`
recipe is the entry point instead: `just xtask <cmd>`, which is `cargo run -p xtask -- <cmd>`.

That tool has four commands and one consumer each — and no fifth, because a command nobody
consumes is a surface that rots unobserved, which is the defect the crate was written to remove:

| command         | consumer                                  | output                          |
| --------------- | ----------------------------------------- | ------------------------------- |
| `crates`        | the local recipes' `ci_crates :=`         | one line, `-p a -p b …`         |
| `affected`      | both workflows' `plan` step               | seven `key=value` lines         |
| `feature-lanes` | a human, and the gates                    | `key<TAB>trigger,trigger`       |
| `docs-bins`     | the release's `bins.json` docs-data asset | JSON: every workspace `[[bin]]` |

[CI derivation](/docs/trader/developer/ci-derivation) explains how `affected` selects and how the local
recipes are held to the same spelling; [Testing](/docs/trader/developer/testing) covers the tiers that run
over what you built.


# CI derivation (/docs/trader/developer/ci-derivation)



"What does CI run for this change" has exactly one implementation: `xtask/src/ci/`. Everything that
needs the answer calls it — both workflows' `plan` step (`affected`), the local recipes' crate roster
(`crates`), and a developer at a prompt. `xtask/src/lib.rs`'s header states the rule those three
consumers exist to serve: there is no second copy to keep in step, so a new exclusion, feature lane
or trigger crate is one edit.

## The output contract [#the-output-contract]

`xtask/src/ci/mod.rs`'s `Plan::render` emits seven `key=value` lines in a fixed order — `any`,
`crates`, `suites`, `hist`, `core`, `app`, `lightgbm` — which the workflow turns into job outputs.
That shape is a contract with the workflow files, not an internal detail, and `suites` is a JSON
array whose order becomes matrix-leg order.

## Selection [#selection]

The rule is the same for a pull request and for a push to `main` (a push just diffs against the
pre-push SHA instead of the merge base): the crates a changed file **owns**, plus every crate that
transitively depends on them through a normal dependency, intersected with the CI roster — except
that a `.rs` file under the owning crate's own `tests/`, `benches/` or `examples/` seeds no
reverse-dep walk, since nothing outside that crate can link a test-target source. A crate whose
changed files are all of that shape is therefore selected alone; a `src/` change, or a non-`.rs`
file under `tests/` (a fixture a `src/` file may `include_str!`), restores the full walk for that
crate. Dev-dependents are added exactly **one hop**.

That one-hop rule is the whole design of `xtask/src/ci/graph.rs`. A dev-dependency is a test edge,
not a layering edge, and this workspace dev-depends upward on purpose; feeding those edges back into
one graph makes it cyclic, and a transitive walk then escapes the layering entirely. Measured: the
chain `oanda -> bridge-core =dev=> binance -> core =dev=> script -> indicators` is how one
indicator-registry edit reached an unrelated venue crate, the DataFusion lane and every Polymarket
suite — 31 crates where 9 were affected.

Narrowing must never silently under-test, so three things escalate to the full roster: a
workspace-global path (`GLOBAL_PREFIXES`, except a purely additive `Cargo.lock`-only change), an
unresolvable diff base, and `CI_FULL=1`.

### The diff base [#the-diff-base]

`xtask/src/ci/git.rs` resolves whose changes a run is testing, and every rung of its ladder was
forced by a measurement. `actions/checkout` on a `pull_request` event checks out the **merge ref**,
not the head; that commit's first parent is the base-branch tip and its second is the PR head. The
payload's `base.sha` field lags that parent, and a three-dot diff cannot repair the gap because
`base.sha` is already an ancestor through the first parent. Measured on one pull request that
changed 2 files: `base.sha` was two commits behind, the diff arrived with 40 paths including a
global one, and the plan escalated to the full matrix on the strength of files belonging to two
other pull requests. `HEAD^1..HEAD` on the same merge ref returns exactly its own 2 paths.

<Callout type="warn" title="Every ambiguity resolves toward the larger set">
  The failure mode of getting the base wrong is *under*-testing. An unclassifiable parent pair, a base
  branch that is not an ancestor, an orphaned `before` SHA, unrelated histories, a failed diff — each
  falls through to the next, more conservative rung, and the last rung is `None`, which the caller
  reads as the full matrix.
</Callout>

## The five gates [#the-five-gates]

**`ci_plan_gate.rs`** holds the derivation itself: the diff-base ladder over real git repositories
with actual merge commits — the only test in the tree that builds them — plus the pure selection
rules over synthetic graphs. It cannot be skipped for a change that could break the derivation,
because `GLOBAL_PREFIXES` names `xtask/`, so any planner change escalates to the full roster. That
escalation is not a convenience: the planner computes the plan for its own pull request, so without
it a bug that selected too little would select too little for itself, go green, and conceal itself.

**`local_gate_mirrors_ci.rs`** holds the local recipes to what CI derives. The measured cost of not
having it: the local crate roster one crate behind the derivation, the release workflow's third copy
six behind, and one feature lane naming four features where the suite named six. Its first direction
no longer compares a copy to a truth, because there is no copy — `ci_crates :=` *calls* the
derivation, and what is asserted is the property that made the comparison unnecessary: the assignment
invokes it and names no crate. The second compares the `clippy` and `features` recipes against the
suite script on subcommand, packages, features, target and flags. `UNMIRRORED_SUITE_STEPS` enumerates
the suite's structural steps that cannot be mirrored at all — the recipes run through PowerShell on
the Windows dev box, where `grep` does not exist — so that hole is measured rather than invisible.
Its third, `every_suite_key_is_both_implemented_and_plannable`, holds the suite keys in the script
and in `FEATURE_SUITES` to one set — the direction a comparison of commands is blind to.

**`feature_suite_roster_gate.rs`** is where that key pairing is argued, and the two disagreements
are not symmetric. An arm with no key can never be planned: the commands exist, the mirror gate
dutifully requires the recipes to match them, and the lane reads in review as covered code while CI
compiles not one line of it — silent, permanently. A key with no arm is loud. The check itself was
written here too and deleted rather than shipped twice, so what this file keeps is the half nothing
else can see — the workflow's own prose, where a comment may name one suite key or all of them,
never a partial list, because that comment had already rotted to eleven of fourteen.

**`feature_lane_coverage.rs`** asks the missing direction — that every declared Cargo feature is
compiled by *some* lane. A feature no lane turns on is never type-checked, never linted and never
run, and looks exactly like covered code in a diff. Coverage is computed to a fixpoint over three
activation rules: named by a lane, reached through a crate's own feature closure, or turned on by a
dependency declaration that resolver-2 unifies across everything built together. `default` gets no
special case and an empty feature array gets no exemption — emptiness describes the array, not the
code behind the `#[cfg]`.

**`lockfile_gate_mirror.rs`** covers the one invocation in the merge gate that passes `--locked`.
The incident: a commit added a dev-dependency to a manifest and touched no `Cargo.lock`; every local
check was green because a bare `cargo check`, `test` or `clippy` silently *updates* the lockfile and
carries on. The whole missing delta was one string in one array. The gate pins that CI still runs the
shared script, that it runs in the one job with no condition on it, that the pre-push recipe runs it
*before* pushing and before any lane `cargo check` rewrites a stale lock, and that the local recipe
delegates rather than reimplementing — because a hand-rolled copy would go green and red at the same
moments while losing the diagnostic, which is the entire reason a local runner is worth having.


# Decision records (/docs/trader/developer/decision-records)



Vike Trader keeps one page per **architectural verdict** — decisions that were investigated,
concluded, and are expensive to re-litigate. The directory's own README states the failure it exists
to prevent, and it is concrete: an investigation that was already run, concluded, and written down
*somewhere unreachable* gets run a second and a third time, "because nothing in a fresh checkout says
it was ever settled."

A record is not a design document. Designs and execution plans live elsewhere; this directory holds
**answers to questions** — most of them "no", or "not this way", or "not yet" — "plus the one field
that keeps a 'no' from ossifying into dogma: **what would reopen it**."

## The shape of a record [#the-shape-of-a-record]

Files are named `NNNN-short-title.md`, numbered in the order records are *written* rather than the
order decisions were made — the date field carries that. Each is kept to roughly one screen.

| field                      | holds                                                                 |
| -------------------------- | --------------------------------------------------------------------- |
| **Status**                 | the vocabulary and the rule, in one cell — see below                  |
| **Date**                   | when the decision was made, not when the record was written           |
| **Context**                | the question that was asked                                           |
| **Verdict**                | what was decided, in one or two sentences                             |
| **Why**                    | the reasoning, with citations                                         |
| **What would reopen this** | "the load-bearing field. A verdict with no reopen condition is dogma" |
| **Sources**                | where the above was read from                                         |

## How to read a Status line [#how-to-read-a-status-line]

The vocabulary is `accepted`, `superseded by NNNN`, `deferred`, and `proposed`. One of the four
carries an explicit prohibition.

<Callout type="warn" title="proposed is not settled">
  `proposed` means written up, awaiting the author's ratification, and — in the README's own words —
  **never to be cited as settled** while it says so. Not every record in the directory is `accepted`,
  so the status is the first thing to read, not the last.
</Callout>

The record's own `**Status:**` line is the authority; the index table carries the second copy, and
those two are the only places the word may appear. "An ungated hand copy of a word that changes on
ratification" is the rot this directory is built against, so it is not restated a third time — not in
a record's prose, not in the index's narrative, not in the root project instructions.

The two copies are compared as the **leading word only**, and that is deliberate: a record may
qualify its status in prose — naming what it supersedes, or recording that a finding inside it was
retracted — and the index may decorate its cell with a warning mark, without either counting as a
disagreement. So read the whole line. The first word is what the gate checks; the rest is where the
qualification lives, and some `accepted` records use it to mark themselves as the weakest in the
table and say exactly how far they may be cited.

## The gate, and the incident behind it [#the-gate-and-the-incident-behind-it]

`crates/vike-ops/tests/decision_index_gate.rs` machine-checks the index against the records on disk,
in both directions. It exists because of a specific failure: the index carried a standing warning
paragraph about one record, while that record had **retracted the finding in its own text**, in the
first sentence of its own `**Status:**` line. "The index was still telling a reader the opposite.
Nobody noticed, because nothing compared the index to the records it indexes."

`every_record_has_an_index_row` catches the direction that bites a new record — the common miss,
since "adding the file is the interesting work and editing the table is the afterthought."
`every_index_row_names_a_real_record` catches the direction that bites a rename.
`every_index_status_matches_the_record` is the leading-word comparison above, and
`every_record_declares_a_known_status` derives its vocabulary *from the README's own format table*
rather than copying it into a constant, "so there is one authority for it and this file cannot drift
from the page it polices." Underneath sit three floor tests: both stores are keyed on the four-digit
id and both used to overwrite on a collision, so a duplicate made one claimant **invisible** to
every rule above, and which one depended on directory order.

Three things are deliberately **not** checked. The title cell, because it is a one-line gloss rather
than a copy of the record's heading. Numbering being gapless, because parallel branches can
legitimately race for the next id and "a gap is a merge artifact to fix by hand, not a CI failure."
And the prose *outside* the table — the very paragraph that motivated the gate — because "no text
rule can tell whether a narrative note about a record is still true; only a reader can." The gate
catches the structural half and says so, rather than implying coverage that does not exist.

## Writing one [#writing-one]

Add a record when a decision is **durable, non-obvious, and would otherwise have to be
rediscovered**: a proposal was declined, an approach was measured and rejected, a built thing was
deliberately removed, or a rule was adopted that constrains future work. Do not add one for a
routine implementation choice — that belongs in the code's own module doc, which is where this
codebase documents by default.

* **Cite by symbol, never by line number.** Line numbers rot silently, and
  `crates/vike-ops/tests/citation_gate.rs` bans them. The README's own bullet records that it used
  to claim these Markdown files were *not* machine-checked, and that the claim was false — the gate
  scans every tracked `.md` outside its exclusion list, verified by planting a bad citation into a
  record and watching `no_citation_pins_a_line_number` redden.
* **Never invent a rationale.** "A record whose 'Why' was reconstructed from a plausible guess is
  worse than no record, because it will be trusted." Where the reasoning could not be recovered, the
  field says so and names what is missing. Several records carry that marker; they are honest gaps,
  not oversights.
* **Superseding beats editing.** When a verdict is reversed, write a new record and set the old
  one's status to `superseded by NNNN`. The directory's worked example is a record whose reversal
  "is more instructive than either decision alone."

The practice generalises the principle the rest of the gate family runs on: prose that can rot
becomes a test. Decision `0007` is that rule's own record.

Related: [Docs gates](/docs/trader/developer/docs-gates) ·
[Architecture](/docs/trader/concepts/architecture) ·
[Drift gates](/docs/trader/developer/drift-gates)


# Docs gates (/docs/trader/developer/docs-gates)



Six gates in `crates/vike-ops/tests/` walk markdown and doc comments rather than code. Every one of
them exists because a specific written claim was measured wrong, and all of them are text-only — no
cargo invocation, no symbol resolution, no new dependency. One is the exception: it runs a process.

Because markdown belongs to no workspace member, the CI derivation cannot reach these gates by
reverse-dependency closure. `xtask/src/ci/tables.rs`'s `DOC_GATE_CRATE` force-adds the one crate that
owns them whenever a `.md` file changes. Before that existed, a documentation-only pull request
planned zero crates and not one prose gate ran.

## `citation_gate.rs` — a citation must resolve, and must not pin a line [#citation_gaters--a-citation-must-resolve-and-must-not-pin-a-line]

Four rules. A backticked path anchored at a repository top-level directory must exist on disk; in
`` `path`'s `SYMBOL` `` the file must contain `SYMBOL` as a whole token; a `path:NNN` that resolves to
exactly one in-repo file is **rejected outright**; and in `` `page.md`'s "Title" `` the cited markdown
must still carry a section with that title.

The ban on line numbers is the interesting part. 26 of the 33 in-repo `path:line` citations were
stale, and the only ones that had *not* rotted pointed into frozen vendored code — so a line number
into living code is structurally doomed, and the repair is the symbol form the tree had already
invented on its own. Rule 4 exists because a *move* rots a pointer the other three cannot see: a
documentation reorganisation left two section pointers behind, both green, one of them sending an
operator triaging a red CI gate to a runbook at an address that no longer held it.

The gate checks the unambiguous subset and declines the rest on purpose — a bare shorthand path is
relative to an unstated base and cannot be resolved without guessing, and a false positive teaches
people to write exceptions. Coverage is therefore partial, a floor test pins it so it cannot decay to
checking nothing, and every blind spot is written down. One exclusion is conditional: a frozen design
note is not scanned **unless** it declares a `**Status:**` line, because that line answers "where does
this stand" and a reader takes it as being about now — one such spec declared a gap that had already
been closed, and an orchestrator briefed an agent to implement code that already existed.

## `docs_constants_gate.rs` — a documented default must equal its constant [#docs_constants_gaters--a-documented-default-must-equal-its-constant]

One operator page said a `SIGTERM` loses up to 5,000 rows per series. Both numbers on it were right
and the sentence was wrong: the recorder has two in-memory stages and the page named one. The real
bound for a single-series recorder is 70,536 rows — a 14× understatement that survived months.

Each row proves four independent things: that one line of the markdown carries both the row's context
anchor and its number verbatim as the page spells it; that the matcher finds the symbol in the cited
Rust file and the literal beside it equals the claimed value; that the two are the **same quantity**
(`5,000` == `5_000`, `30 s` == `30`, `10µs` == `10_000` nanoseconds); and that a row converting between
units names both of them. Without the third rule a row could pin a page number and a constant that have
nothing to do with each other and stay green forever; without the fourth, a row free to assert a 1000×
difference could hide a real disagreement behind a made-up factor.

## `one_authority_gate.rs` — one fact, one authority [#one_authority_gaters--one-fact-one-authority]

That same 5,000 was stated in two documents, and the failure mode is what makes duplication expensive
rather than untidy: fixing one file leaves the number alive in the other, where it reads as
independent confirmation and grows back.

The rule is deliberately narrow. **A bare number is never flagged** — years, record ids, ports and
percentages all repeat legitimately, and a gate on bare numbers would report hundreds of coincidences
and earn an exception table until it meant nothing. What is flagged is a number in the same semantic
company twice: the pair `(identifier, number)`, either by proximity to the nearest qualifying
backticked identifier on the line or as an explicit `key = number`. Measured filters kill the
coincidence classes — single digits are excluded, date-shaped numbers are incident prose, line pins
belong to the citation gate, and digits inside an identifier's own name are part of the name.

## `unrun_command_gate.rs` — a documented command's output, checked by running it [#unrun_command_gaters--a-documented-commands-output-checked-by-running-it]

The other five compare prose to a file; this one compares prose to a **process**. Three consecutive
review rounds on one pull request found nothing but this defect — including an emergency-halt recipe,
on the page whose first heading is "STOP EVERYTHING, RIGHT NOW", whose `sed` anchor never matched, so
the variable came back empty and the next line failed.

<Callout type="warn" title="A harvested command is never executed">
  Harvesting reads markdown to decide *which claims exist*; it never feeds a harvested string to a
  process. Every argument vector this gate spawns comes from a `const` array in its own source, so the
  set of executable commands is fixed at compile time and changing it is a reviewed diff — not
  something a markdown edit can reach. Do not "finish the job" by running the harvested pairs: that
  would hand anyone who can edit a `.md` file the ability to run a command in CI. An unrunnable claim is
  **declared** instead, and a test asserts that every harvested claim is either checked or declared, so
  the unverifiable population cannot grow unnoticed.
</Callout>

The harvester narrows by adjacency: 3,325 program-shaped candidates, 631 with an argument shape, 78
with a claim phrase somewhere in the block, and 14 with that phrase *adjacent* to the command. A
module doc is one comment hundreds of lines long, so a block-wide search paired unrelated sentences —
64 of the 78 were that.

## The two index gates [#the-two-index-gates]

`decision_index_gate.rs` holds the decision-records index to the records it indexes. The incident: the
index carried a standing warning that one record had already **retracted in its own text**, and
nothing compared the two. An index that omits a record is worse than a missing record — the reader
who checks the table concludes the question was never settled and re-litigates it. It gates four
directions plus a floor of three tests, because the gate had three ways to be silently disarmed, and
the status vocabulary is *derived* from the index's own format table rather than copied into a
constant.

`superpowers_index_gate.rs` is the same shape over the design-document index, which opened by
claiming to be a 1:1 list and carried six hand-written numbers that nothing checked. Both gates leave
the semantic half alone: no text rule can tell whether a narrative note about a record is still true,
and stating that limit beats implying coverage that does not exist.

How to read a settled verdict is on [Decision records](/docs/trader/developer/decision-records).


# Drift gates (/docs/trader/developer/drift-gates)



A few build outputs in Vike Trader are **committed** rather than produced at build time, each to
keep a whole toolchain — or a whole upstream — out of a clean checkout. That trade buys a fast,
dependency-light build and costs one thing: a committed artifact can drift from the source it came
from, silently, and no compiler will notice.

The family rule is three clauses, and every member obeys all three: **re-derive from source in CI,
compare exactly, and pin the generator beside the artifact** — not in a central document, which is
the copy that rots.

## The two members [#the-two-members]

**The cTrader protobuf bindings.** `crates/bridges/ctrader/src/generated/openapi.rs` is
pre-generated and committed, so a normal build never runs prost-build or protoc — they stay out of
the build graph *and* the supply chain. A path-filtered workflow regenerates from the vendored
schema with the pinned toolchain and fails unless the committed file is byte-identical, a plain
`cmp` whose reason `crates/bridges/ctrader/src/proto.rs`'s `generated` module states beside the
`include!`: the committed file is prost-build's verbatim output for the vendored schema, renamed on
commit.

**The vendored IBKR wire-protocol client.** `crates/bridges/vike-ibkr/vendor/ibapi` is a
workspace-excluded copy of an upstream crate, re-derived by a path-filtered workflow that runs a
standalone drift script. The check lives in a script rather than inline in the workflow because it
is not one command: it reconstructs, in stages, a vendoring procedure a person performs by hand.
`crates/bridges/vike-ibkr/vendor/ibapi/VENDORED.md`'s *Refresh procedure* is that procedure —
re-clone upstream at the desired tag, re-copy `src/`, `Cargo.toml` and `LICENSE`, re-apply the
three manifest trims and the three test-module drops, update the record's own fields — and it ends
by telling the refresher to "run the gate before pushing", naming the same script the workflow
runs. A check the next refresher must run locally cannot live inside a workflow file.

Both are separate, path-filtered workflows rather than jobs in the main CI run, and both carry
SHA-pinned actions, a read-only token and a job timeout — the runner also runs live trading.

## Why the comparison styles differ [#why-the-comparison-styles-differ]

<Callout title="The looser-looking gate is the correct one">
  The bindings are compared byte-for-byte. The vendored client is compared three different ways in one
  run, and its `src/` under rustfmt normalization rather than as raw bytes. That is not a weaker gate
  written by a tired author — it is the only comparison that could have been green the day it was
  written.
</Callout>

The drift script compares the three things that were copied — `src/`, `Cargo.toml` and `LICENSE`,
the set `crates/bridges/vike-ibkr/vendor/ibapi/VENDORED.md&#x60;'s "What was copied" names — and each on
its own terms, argued beside the code that performs it.
&#x2A;*`LICENSE`** gets a raw `cmp&#x60;: nothing processes it on either side.
&#x2A;*`Cargo.toml`** gets a raw `cmp` after applying the record's documented trims and two declared
normalizations — measured 2026-08-22 against the pinned upstream commit, the trims are
byte-reproducible, "the whole difference being the vike provenance banner at the top of the
committed file and one trailing blank line."

**`src/`** is compared as rustfmt-normalized text, because the raw bytes are not reproducible and
never were. Upstream ships a `rustfmt.toml` with `max_width = 150`; that file was not among the
copied ones, and the copy was reformatted under this repository's own config —
`crates/bridges/vike-ibkr/vendor/ibapi/VENDORED.md` records both, in its "What was copied" section.
Measured 2026-08-22 at the pinned commit, **276 of the 280 committed `.rs` files differ from
upstream, every difference line-wrapping and none of it code** — and running this repository's
rustfmt over upstream's `src/` collapses that to zero. A byte gate there would have been red on the
day it was written.

The normalization is honest about both sides of the trade. Both trees go through the same rustfmt,
which re-prints parsed source while preserving comments verbatim — so a changed identifier, a
changed literal, an added or removed statement, an edited comment, a reordered item and an added or
removed file all survive it and redden the gate. What it cannot see is whitespace and wrapping
inside the committed files: "rustfmt erases nothing but layout, so the residual is layout alone."

## Where each pin lives [#where-each-pin-lives]

The third clause keeps the other two meaningful. The bindings' regen recipe is a committed,
standalone project that `=`-pins its codegen crates and commits its own lockfile — freezing the
pretty-printer whose output must match byte-for-byte — and CI regenerates with `--locked`. Those
pins may be bumped only together with a re-commit of the generated file.

For a vendored copy the only build input is an upstream commit, so the pin lives in the vendored
tree's own `VENDORED.md` and the gate **parses it there** rather than carrying a second copy a
refresh would have to remember to update. It insists on a full 40-hex commit, because "a tag or a
branch can be moved under us, and an abbreviated sha can collide", fetches that commit rather than a
ref, and cross-checks the recorded version against the committed manifest's — "a half-finished
refresh is exactly the state where they disagree."

The vendoring is not a pure copy. One set of local edits — three test-only modules dropped from
`src/` — was *undocumented* until the gate measured it, and they are reconstructed rather than
ignored, because "a gate that merely IGNORED files missing from the copy would let the next refresh
drop a load-bearing source file in silence."

## The member that left, and the rule it left behind [#the-member-that-left-and-the-rule-it-left-behind]

The JForex sidecar jar was the third member: it was committed, and a dedicated workflow rebuilt it
from the committed Java sources to prove the two still agreed. It is a *runtime* artifact rather
than a compile input, so the release workflow now builds it from those sources on every tag and
attaches it to the Release, checksummed in that release's `SHA256SUMS`, and a release-tools fetch
script installs it into the runtime-tool directory `crates/vike-model/src/state_path.rs`'s
`PROJECT_BIN_DIR` names — "so there is no second copy to drift from and nothing a `git diff` could
fail to notice."

Deleting the workflow with the question would have been wrong, because two properties it rested on
are still true and now more load-bearing: "the release ships bytes nobody reviews, and a
`SHA256SUMS` line is only worth anything if somebody can re-derive the bytes it describes." So it
became a **reproducibility** gate — it builds and tests the jar, runs a protocol smoke, then builds
it twice from a clean directory and compares the two byte for byte. The build script had claimed
"same sources plus same JDK gives a bit-identical jar" all along, a claim nothing ever checked,
because the old gate compared a build against a human-committed artifact and "could not tell
reproducibility from luck."

**The rule this leaves: an artifact a deployed binary must find is a release asset, never a
committed one — commit the pin, ship the build.**

The pin outlived the membership. `crates/bridges/dukascopy/tests/jdk_pin_gate.rs` holds the JDK
version equal across four files — the gate, the release that builds the shipped jar, and both
provisioning scripts — because `javac` output differs across JDK releases. Its header names the
failure with no other detector: if the gate's pin and the release's pin drift, "the gate reproduces
a jar nobody has, the release publishes a jar nothing checked, and both workflows stay green."

Related: [Supply chain](/docs/trader/developer/supply-chain) ·
[Release gates](/docs/trader/developer/release-gates) ·
[Docs gates](/docs/trader/developer/docs-gates)


# Developer guide (/docs/trader/developer)



This tree is for somebody changing Vike Trader rather than running it. It is organised around one
idea that shapes almost every rule in the repository: &#x2A;*a claim that can rot is either derived or
gated, never restated in prose.** That is decision record 0007, whose own `Status:` line is the
authority for whether it still stands — this page does not carry a third copy of that word.

## Why the doctrine exists [#why-the-doctrine-exists]

It was not a preference. Three independent measurements from the tree that motivated the gates:

* **Citations.** 26 of the 33 in-repo `path:line` citations were stale, and seven fully-qualified
  paths pointed at files that no longer existed. Git archaeology showed every one was exactly right
  on the day it was written. `crates/vike-model/src/venue_margin_support.rs` alone carried four that
  landed on a blank line, a `};`, and a doc-comment fragment.
* **Hand copies of a derived list.** The local recipes' CI crate roster had drifted one crate behind
  the derivation, the repository's own guidance file four behind, and the release workflow's third
  copy six behind — while one feature lane named four features where the suite named six. Every one
  of them green, because nothing checked. `xtask/src/lib.rs`'s header records what replaced them,
  and what still lives elsewhere.
* **Counts in prose.** The library-layer settings work-list was written down as 63, then 59, and
  measured 77. It grew across five pull requests that each had no reason to notice, while every
  prose statement of it went stale.

The decisive datum is the citation one. The only `path:line` citations that had *not* rotted pointed
into frozen vendored third-party code. A line number into living code is structurally doomed — so
`crates/vike-ops/tests/citation_gate.rs` does not police line numbers, it **bans** them, and the
repair is the rot-proof form the tree had already invented on its own before any gate existed:

```text
`crates/bridges/bybit/src/exec.rs`'s `DEFAULT_LEVERAGE`
```

A symbol citation survives every edit a line number does not, and it breaks only when the cited
thing is genuinely renamed or deleted — which is exactly when the documentation is wrong.

## What a gate looks like here [#what-a-gate-looks-like-here]

Almost all of them are **text-only**: they walk the real tree, strip comments and string literals,
and compare two things that must not disagree. No cargo invocation, no symbol resolution, no new
dependency. `crates/vike-ops/tests/settings_registry.rs` is the shape the rest are modelled on, and
`crates/vike-ops/tests/layer_gate.rs` and `crates/vike-ops/tests/local_gate_mirrors_ci.rs` say so in
their own headers. They fail a pull request; they are not review comments.

Five properties recur, and they are worth recognising when you read a failure:

<Callout title="The five recurring properties">
  **Gate the class, not the instance.** A defect that was an advertised-but-unreachable settings
  *layer* did not get a test for that layer — it got `crates/vike-config/tests/layers_are_reachable.rs`,
  which drives every layer named in `PRECEDENCE` and panics on one with no scenario rather than
  skipping it.

  **A ratchet where a flat ban is unavailable.** `settings_registry.rs`'s `LIBRARY_PIN` pins the set
  of offending rows as a fixed-size array, so its declared length *is* the count and no prose is
  allowed to be the authority. It may shrink, never grow.

  **Measure the blind spot; do not assume it.** `MAP_LOOKUP_PROVEN` in the same file fails equally on
  an addition, because a blind spot that is only ever an upper bound is not measured, just assumed
  smaller.

  **A gate that walks nothing passes everything.** Every walking gate carries a file-count floor. That
  earned its keep immediately: `layers_are_reachable.rs`'s first version rooted one directory too
  high, the self-crate filter emptied the walk, and it failed on the floor rather than passing
  vacuously.

  **False positives are worse than no gate**, because they teach people to write exceptions. So
  `citation_gate.rs` checks only the unambiguous subset and declines bare shorthand paths — roughly
  297 such tokens — on purpose, and every exception table carries a per-row written reason.
</Callout>

And one rule about writing a gate: mutation-prove it, then verify the mutation actually applied. One
attempt appended its test mutation to the end of a file and landed in the `#[cfg(test)]` half the
gate correctly discards — it silently did nothing, and the gate stayed green.

## The families [#the-families]

<Cards>
  <Card title="Building" href="/docs/trader/developer/building" description="The workspace, the feature lanes, the one committed cargo config, and why there is no cargo xtask alias." />

  <Card title="CI derivation" href="/docs/trader/developer/ci-derivation" description="One implementation of what CI runs, and the five gates that hold the local recipes and CI to one spelling." />

  <Card title="Structure gates" href="/docs/trader/developer/structure-gates" description="Dependency direction, compile-time paths, and re-spelled primitives — how to read each failure." />

  <Card title="Adding a venue" href="/docs/trader/developer/adding-a-venue" description="The scaffold whose work-list is derived from the tree, and the shared homes a venue consumes." />

  <Card title="Settings gates" href="/docs/trader/developer/settings-gates" description="The environment registry, the credential-store ratchet, and the two consumption gates." />

  <Card title="Docs gates" href="/docs/trader/developer/docs-gates" description="Six gates over prose — citations, documented defaults, documented commands, and the two indexes." />

  <Card title="Safety gates" href="/docs/trader/developer/safety-gates" description="The gates over the kill switches, the graceful stop, the live-account lock, and every paper mount." />

  <Card title="Supply chain" href="/docs/trader/developer/supply-chain" description="What a workflow may fetch onto a trading box, the unsafe ratchet, and the cargo deny bans table." />

  <Card title="Release gates" href="/docs/trader/developer/release-gates" description="The container image, the deploy layout, the release artifacts, and the public mirror." />

  <Card title="Drift gates" href="/docs/trader/developer/drift-gates" description="The committed generated artifacts, and why the looser-looking comparison is the correct one." />

  <Card title="Testing" href="/docs/trader/developer/testing" description="The tiers: unit, property, conformance, gate, smoke, latency." />
</Cards>

The architectural rule the structure gates enforce is explained on
[Architecture](/docs/trader/concepts/architecture); how to read a settled verdict is on
[Decision records](/docs/trader/developer/decision-records).


# Release gates (/docs/trader/developer/release-gates)



A release leaves the repository as bytes nobody re-reads: an image, a set of unit files, a handful
of binaries, a published source tree. Five gates in `crates/vike-ops/tests/` hold the properties of
those artifacts that no compiler can see — each chosen because its violation stays invisible until
the artifact is *run* in production.

## The container image [#the-container-image]

`crates/vike-ops/tests/container_image_gate.rs` opens with the fact that shapes it: &#x2A;*no runner has
a container runtime.** Measured 2026-08-24 on the box the release workflow is pinned to, none of the
four common runtimes is installed and the docker socket does not exist, while a control probe finds
the ordinary shell tools — "so that is a fact about the runner and not about a broken check."

Coverage is split by what is provable without one. The entrypoint is executable shell, so it is
*run*: `the_entrypoints_own_selftest_passes` drives the real script through the stamp, the
verification, the wholesale swap and every refusal. The Dockerfile is text, so the rest are text
rules. `the_entrypoint_execs_the_daemon` is called "the single most dangerous line". Without `exec` the
shell stays PID 1, and a shell does not forward SIGTERM to its children: `docker stop` waits out its
timeout then SIGKILLs, so `cancel_orders_on_shutdown` never runs and "the resting book is ABANDONED
at the venue" — the defect `crates/vike-ops/tests/graceful_stop_pin.rs` exists to keep fixed,
reached through the container instead of the unit file. Alongside it: the base image is pinned by
digest, no packages are installed, both released binaries are present, the stop timeout outlasts the
daemon's own shutdown deadline, and `no_baked_environment_variable_is_a_removed_setting` —
`vike_config::REMOVED_ENV` names variables whose presence is a hard startup refusal, and one baked
as an `ENV` line would make every container of that image refuse to start.

<Callout type="warn" title="What the image gate cannot prove">
  That the image builds, that the base's glibc satisfies the binaries, or that the entrypoint works
  under a real PID 1. `crates/vike-ops/tests/container_image_gate.rs` says so itself, in its *What it
  deliberately does NOT prove* section: none of it is reachable without a container runtime, so the
  release script that stages and builds the image carries the runtime check instead — "the only place
  the glibc-too-old failure can be observed at all."

  That check runs `--version` on *every* version-capable link — six of them, all symlinks into one
  dispatcher — inside the freshly built image before anything is published.
  `crates/vike/src/lib.rs`'s `Route::Version` records the same rule from the dispatcher's side: "the
  image smoke runs `--version` through every link, the dispatcher's included." One link is not
  enough — a released image once answered `vike-tradehub --version` with that tool's usage error, a
  break a single-link smoke catches only for the link it runs.
</Callout>

## The shipped units [#the-shipped-units]

`crates/vike-ops/tests/deploy_layout_gate.rs` holds one rule — every shipped daemon unit describes
one project folder, and the same one throughout — and names two defects that shipped before it
existed. The first was a layout that no longer existed anywhere, so a fresh deploy rebuilt an
abandoned three-location shape. The second was worse: `EnvironmentFile=` pointed at the **credential
store**. Nothing was exposed, but the route shipped, and it inverts a guarantee four gates rest on —
the live, control, reconcile and Telegram flags are read off the real process environment precisely
*because* the store never reaches there.

The write grant is the instructive rule, because its first version caused what it looked like it
prevented. It demanded exactly one `ReadWritePaths=` naming exactly one path, on the argument that a
second path is a second location. It is not: every path was already required to be under the unit's
own root, so a second path inside one folder is a *narrower* grant. The rule forced the one daemon
that legitimately writes in two places to grant the only single path covering both — the root —
which on a shared folder covered a live daemon's binaries, its notional ceiling, its credential
store and its armed kill switch. Containment is checked instead: no granted path may reach
`ExecStart=`'s binary or any `ExecStartPre=` binary — not the executable and not a directory holding
it, since write permission there is enough to unlink and replace the file — nor the settings
directory the unit names. The gate states its own limit: intent is all a text gate can read.

## The fxcm-linked artifact [#the-fxcm-linked-artifact]

`crates/vike-ops/tests/release_fxcm_artifact_gate.rs` governs a second daemon binary built from the
same tagged commit with `--features fxcm`. Its rule is one line: &#x2A;*a release may grow an
fxcm-linked artifact; it may not change the one everybody deploys.** A feature build writes to the
same output path the default build just produced, so getting it wrong silently replaces the binary
the deploy installs — with one that dies at exec, before `main`. The extra asset rides in the
checksum manifest but is never installed, checked over a *derived* subject rather than a hand list,
because "an absence check never opens the file nobody remembered to add, and reports a pass for it."
Third, an asset named `-fxcm` must actually be linked: with no SDK the identical command produces a
stub that builds green, so the script reads the ELF's dynamic section rather than trusting an exit
code, and the gate runs it against a fake `cargo` — the only way to prove the guard is *wired into*
the build.

<Callout type="warn" title="A return from a test body is a pass">
  This gate's behavioural half once opened with an early `return` on a missing toolchain, so a runner
  without a C compiler reported it green over a release script none of it had executed. Since
  2026-08-28 the cases differ: off an ELF platform they are `#[ignore]`d with the reason attached, and
  a missing tool *on* Linux fails, because a box that can build the workspace already has all three.
</Callout>

## The public mirror and the dispatcher [#the-public-mirror-and-the-dispatcher]

`crates/vike-ops/tests/publish_mirror_gate.rs` guards the script deciding what leaves the private
repository, on two properties. **ALLOW is an allowlist** — a catch-all turns the script into
"publish everything except…", which fails in the wrong direction, silently, and once. And **the
forbidden-token scan refuses** rather than warns: "redaction alone is a habit; redaction plus a
refusal is a gate." Neither is checkable by reading the script, so the gate *runs* it over the real
tree and inspects the result.

`crates/vike-ops/tests/multicall_gate.rs` requires the multicall dispatcher to do nothing before
handing over, and one tool to run per process. It performs the process's single environment sweep,
then hands control to a tool that boots for itself — if the dispatcher also booted, one process
would walk for settings twice, and the second walk is blind to the settings-directory override. That
is the defect that once put a live daemon on no policy, no config and no credentials, every venue
silently on paper, no error anywhere. The boot-ownership gate cannot catch it: it keys on crate
directories containing a boot call, so "the dispatcher boots and the tool it calls boots" reads as
two crates each booting once. The one-tool rule follows from process-global state — a second tool
would inherit the first's logging and handlers in a process that may be signing orders — so the
dispatcher panics, and the gate proves the panic is real.

Related: [Supply chain](/docs/trader/developer/supply-chain) ·
[Drift gates](/docs/trader/developer/drift-gates) ·
[Safety gates](/docs/trader/developer/safety-gates)


# Safety gates (/docs/trader/developer/safety-gates)



These gates cover the code you reach for when something is wrong. Each one is a text gate over the
source rather than a runtime test, and each one says out loud what a text gate cannot prove — because
in this family, false confidence is the failure.

## `kill_switch_gate.rs` — the page is read at 3am [#kill_switch_gaters--the-page-is-read-at-3am]

The kill-switch runbook is read by someone who is not going to verify it, which makes it exactly the
kind of prose this tree has learned not to trust. A kill-switch page that has rotted is worse than
none, because the operator stops looking for the real switch.

Seven rules. Each documented mechanism's file must exist and contain its symbol as a whole token; the
page must still carry that row's operator trigger string and its citation; **every** citation anywhere
on the page must resolve, wider than the row table, so a claim added in prose is gated the same as a
table row; no line numbers; a floor on the row and citation counts, so the gate cannot decay into
checking nothing; a mutation self-test, without which the first three rules could be vacuously green
forever; and for the subset whose trigger is a line the binary *prints*, that the binary still prints it.

<Callout type="warn" title="Reachability of a symbol is not reachability of a mechanism">
  This gate cannot tell that a switch's configuration type exists but is constructed by no binary. That
  finding is written on the page under "Switches that do not work" and is checked by nothing here.
  Proving "no shipping binary arms this" needs a call graph, and a text gate pretending to do it would be
  the exact false confidence the file exists to prevent. The same holds for behaviour: one behaviour test
  was later spelled to assert the **opposite** of what it once did, and every row and citation here
  stayed green through the reversal, because a text gate cannot read a test name for its meaning.
</Callout>

## `graceful_stop_pin.rs` — one stop flag, many triggers [#graceful_stop_pinrs--one-stop-flag-many-triggers]

Neither headless daemon installed a signal handler, so a service stop ran none of the teardown each of
them already owned. The fix was one package: the handler sets the **existing** stop flag, and the
ordinary teardown runs below a single wait on it. A second teardown route is how the two drift, and
drift here reads as "the interactive stop closes the book and the service stop does not".

So what is pinned is the shape rather than the intention. Both daemons reach the same shared stop
primitive, both install handlers, and neither declares or names a signal crate of its own — a ban
*derived* from the module that owns the surface, so it tracks the platform split rather than pinning one
literal. The trading daemon's teardown must wait on the flag, not sit below an uninterruptible park. The
handler must be installed **before** anything can place an order — the first cut of the fix failed that,
with the install below the core mount, so the maker could already be resting orders while the signal
still killed the process outright. The loser of a teardown claim must wait, never return, because a
return from `main` truncates the winner's teardown. Every shipped unit must bound the stop explicitly
rather than inherit the 90-second default, and none may carry an `ExecStop=`: one added without a
matching daemon-side poll was measured at 0.02 s with zero daemon code run.

## `feed_stop_windows_gate.rs` — exhaustive over the source, not over memory [#feed_stop_windows_gaters--exhaustive-over-the-source-not-over-memory]

The recorder's feed-stop budget is derived from the largest blocking window a feed thread can occupy
when the stop flag goes up, and its doc comment tabulated those windows. The table shipped saying
"every one of them" and "each is followed by a stop check". Both were false the day they were written: a
REST book seed ran on the shared 30-second pager agent — three times the newly-bounded dial — with no
stop poll in front of it. The same change that bounded the dial left a larger window immediately behind
it and then asserted exhaustiveness over the result.

The rule keys on **shape**, not on a list of blessed names: in a file that mounts a feed driver, an
unbounded WebSocket connect fails; every agent-shaped call is classified and must be a row of the
gate's own table of agent rungs; and a bounded call's ceiling **argument** must itself be a row of
the derivation table — the direction that catches "somebody bounded a new window and did not tell
the budget about it". What the gate cannot see is executable rather than promised: a test runs the
rules against each missed shape and asserts the miss, beside positive controls asserting the catch.
An earlier round wrote that residual as prose, and it was already wrong in the same direction as the
table it replaced.

## `held_divergence_is_visible_gate.rs` — a held divergence must reach the log [#held_divergence_is_visible_gaters--a-held-divergence-must-reach-the-log]

A held reconciliation divergence was written to an in-memory ring reachable only through a control
channel that is off by default. Measured on the live box: a folded-pass line reporting two alerts every
60 seconds for hours, zero lines at `warn` or above, and no way for anyone reading logs to learn which
two divergences were being held. The count reached the operator; the content did not.

Emitting the line unconditionally fixed the silence and bought a flood — under a quarantine policy a
divergence nothing heals is re-diffed and re-held every interval, and one day logged 396 identical
warnings with a genuinely new divergence indistinguishable among them. So the emission moved behind an
announcer that logs the **transitions** of the held set plus a slow backlog summary, and both properties
are gated: the raise path still logs, and no warning on that path is unguarded.

## `live_lock_claim_order_gate.rs` — claim before you build [#live_lock_claim_order_gaters--claim-before-you-build]

The live lock is the one-live-process-per-venue-account tripwire, and neither composition root was
holding one over what is actually live. The daemon locked the **wrong set** — one sentinel per
run-profile mount, while the builder armed an exec client for every wired venue the credential store
answered for. Measured on one startup, two log lines apart: nine live authenticated sessions, one lock.
The desktop app locked the right set at the wrong **time** — its claims came from a value that does not
exist until every exec client has been constructed, and three venue clients post a leverage call at
startup, so a lock refused there had already changed account state at three venues.

A mutation campaign then showed what pinning a *name* is worth here: three one-line edits, each
relocating the sentinel directory, left every test green. The gate pins each root's declared **chain**
instead — from the boot's state directory to the claim — with each hop checked by what it is built
from, and it refuses shapes it cannot classify rather than passing them.

## `paper_mount_arming_gate.rs` — every construction site is classified [#paper_mount_arming_gaters--every-construction-site-is-classified]

A mount arms the operator halt sentinel; a simulation must not. The accessor's own doc said two named
seams each assert on this, "so adding a third mount seam that forgets fails a test in its own crate" —
and a third seam already existed, unarmed, when the sentence was written. An assertion inside seam A
and an assertion inside seam B are evidence about A and about B; nothing was looking at the **set**.

So every file under a crate's `src/` that calls a paper-client constructor needs a row, and the
constructor set is *derived* from the type's own `impl` block and matched under whatever name the
calling file's imports give it. Mount rows must arm; simulation rows must not — and that opposite half
is not symmetry for its own sake, because the backtest-equals-paper equivalence gate drives the same
client, so a sentinel read on a simulation path would make backtest fills depend on a file lying around
in the project state directory. Test code is out of scope: it constructs unarmed books by the dozen, and
that *is* the simulation shape. The gate is file-level rather than call-site-level, with per-seam tests
bounding the residual — those answer "is this book armed", and this gate answers the one none of them
can: "is there a seam nobody is asking about".

What each of these mechanisms does is on [Halt](/docs/trader/concepts/halt),
[The dead-man's switches](/docs/trader/concepts/dead-mans-switch) and
[Reconciliation](/docs/trader/concepts/reconciliation).


# Settings gates (/docs/trader/developer/settings-gates)



Two separate questions get gated here, and they fail for opposite reasons. The registry asks
&#x2A;*"is every environment read declared, and does a library do it?"*&#x2A; The consumption gates ask
&#x2A;*"does anything actually read the key this file accepts?"** A settings key that nothing reads is
worse than an unimplemented feature, because the CLI reports it as the *origin* of an effective
value and hands the operator positive confirmation of something false.

## The registry [#the-registry]

`vike_ops::settings::SETTINGS` is the verbatim registry of every environment variable this workspace
reads. It is **data, not behaviour** — nothing in the runtime consults it. It exists so
`crates/vike-ops/tests/settings_registry.rs` can walk the real source tree and assert that the table
and the tree agree in both directions: an undeclared `env::var` fails CI, and a stale row fails CI
too. Rows are keyed on the pair `(name, krate)`, not on name alone, so one variable read from several
crates gets one row per crate, each carrying its own default and evidence.

Genuinely dynamic call sites — a name the program assembles at runtime — must be named in
`DYNAMIC_ALLOWLIST` with a written reason. A blind spot has to be **declared** to exist, and that
principle recurs: `MAP_LOOKUP_PROVEN` pins exactly which map-lookup rows rest on a resolved call site
rather than on the loose literal sweep, and it fails on a removal *and* on an addition, so the
remaining blind spot is measured rather than assumed smaller.

### The rule the registry exists to enforce [#the-rule-the-registry-exists-to-enforce]

**Libraries take configuration as parameters; only binaries read the process environment or the
credential store.** A `Layer` records which shape each row has — `Library` is the work-list (a
library reading global state its caller can neither see nor override), `Injected` is the target
state (a pure parser over a caller-supplied map), and `Binary` is the third correct shape.

<Callout type="warn" title="The Library work-list is a ratchet: it may shrink, never grow">
  `LIBRARY_PIN` pins the set of offending `(krate, name)` pairs as a fixed-size array, so its declared
  length is the only machine-true count and no prose is allowed to be the authority for it. A ratchet
  was needed because a flat ban is unavailable — dozens of legitimate rows exist and four families are
  deliberately exempt — and because the count grew silently across five pull requests that each had no
  reason to notice, while every prose statement of it went stale. `library_rows_do_not_grow` names the
  offending pair and the two legitimate responses; `library_pin_has_no_stale_rows` fails on a removal
  with "delete the line", a one-line cleanup rather than a blocker.
</Callout>

### The credential store is a second ratchet, on a class the first cannot see [#the-credential-store-is-a-second-ratchet-on-a-class-the-first-cannot-see]

Everything above keys on an `env::var` **call**, and the credential store is not read that way: it is
a filesystem read of a path a runtime walk produces, with no `env::var` anywhere near it. A library
loading it was therefore *structurally invisible* to `LIBRARY_PIN`, not merely unpinned.
`CREDENTIAL_STORE_PIN` closes that — same walk, same comment stripper, same `Layer` rule, keyed on
the **name** of the function that performs the read. It is a separate pin because there is no
variable name to key on and because the fix is a different instruction: "take the map as a
parameter", not "move the read to a binary".

Keying on a name left its own hole, and a real defect walked into it: a hand-rolled filesystem read
of a working-directory-relative `.env` — a second credential store outside the project settings
directory — had no name to key on and was invisible to both gates. So the ratchet takes a second kind
of evidence, keyed on the **shape**: a filesystem opener whose path argument names the store. The
residual is declared and executable — a path bound to a local first, produced by a helper, or reached
through a loop variable still escapes, and a test asserts each miss so the blind spot cannot be
quietly widened or quietly closed.

### The key that appears as no literal at all [#the-key-that-appears-as-no-literal-at-all]

Credential keys have neither a variable name nor a reader name: the loader composed each one from a
`{VENUE}_{TIER}` prefix and handed it to a map lookup, so the key existed only at runtime. One
venue's live API secret was read on every credential probe with neither a row nor a sighting, while
its demo twin had one only because a test fixture happened to spell it.

The fix was not a fourth scanner: it was making the key set **data**. `vike_model::credential_keys`
folds its suffix and tier tables over `VENUES` into the whole enumerable grid, the loader composes
its names from those same tables, and `every_generated_key_is_declared` demands a registry row for
each. Adding a venue, a tier or a suffix now reddens CI until the rows exist — exactly what the
roster contract promises for every other per-venue table.

## The two consumption gates [#the-two-consumption-gates]

`crates/vike-config/tests/policy_is_consumed.rs` exists because a risk ceiling shipped as a field,
was validated on load, was accepted by the strict unknown-key check, and was **read by nothing** —
while a module doc stated in as many words that it was consumed at the order surfaces. The field was
removed. Its rows now name a file and a needle, and `every_claimed_consumer_really_reads_it` opens
that file and looks, so claiming a ceiling is enforced when it is not turns the gate red, and so does
deleting the consumer later.

`crates/vike-config/tests/settings_are_consumed.rs` is the twin for the three types that had the
identical defect and no gate at all. A clean-install validation found five keys displayed as
effective while nothing read any of them: no control server, nothing listening, and the trace log in
the wrong directory at `trace` level — a configuration that once wrote 341 GB onto the disk hosting a
live trading node.

Both gates run four directions: every field or key has a row; every claimed consumer really reads it;
a claimed consumer must live **outside** the settings crate, since that crate parses, validates,
clamps and serializes every field and would otherwise let every row claim consumption while asserting
nothing; and a row admitting no consumer must be honest in the other direction.

`settings_are_consumed.rs` checks `pub` data rather than a fixture, because a test alone would have
left `vike-cli config show` still lying — the command reads the same rows and names the unread keys.
What each file governs is on [Settings](/docs/trader/concepts/settings) and under
[Settings reference](/docs/trader/reference/settings).


# Structure gates (/docs/trader/developer/structure-gates)



Three gates fail on the *shape* of a change rather than on its behaviour. The rule the first one
enforces is explained on [Architecture](/docs/trader/concepts/architecture); this page is about reading
the failure when one of them goes red, because in all three cases the obvious repair is the wrong
one.

## `layer_gate.rs` — dependency direction [#layer_gaters--dependency-direction]

Every workspace member declares its rank in its own manifest, and
`crates/vike-ops/tests/layer_gate.rs`'s `every_normal_vike_dependency_goes_strictly_down` asserts
that for every **normal** (non-dev) `vike-*` edge `c -> d`, `layer(d) < layer(c)`. Text-only over the
manifests, no cargo invocation.

**Reading the failure.** The edge is the defect; the number rarely is. The ranks in `TIERS` were
established by reading the real graph — all 275 normal `vike-*` edges in the tree the gate was
written against — and every one of them satisfied the rule as merged, so the tree had no layering
violation to fix when the gate landed. Raising the rank of the crate that failed will make the gate
pass and will also pull whatever that dependency drags in.

That is not abstract. One normal edge from the headless trading daemon to the GUI's shared crate
dragged the entire egui widget stack — ten crates — into the daemon, for three pure modules. The
cost was never CI minutes: it was daemon build time, binary size, and the `cargo deny --all-features`
supply-chain audit surface on the box that signs real orders. It was found by somebody noticing build
times.

<Callout type="warn" title="A rank is a total order; the architecture is a partial one">
  Where two families are genuinely incomparable the numbers still put one above the other, and the gate
  then permits the wrong-direction edge in whichever direction was chosen. Two of those choices are
  deliberate, made toward the mistake that has actually happened: the whole UI stack ranks **above**
  everything headless, which is what makes the motivating edge fail; and venue bridges rank **below**
  the simulator, so a bridge reaching for the backtester is red while the reverse edge — the far less
  dangerous one — is not.
</Callout>

Dev-dependencies are exempt, and that is not a loophole: a dev-dep is a test edge, and this workspace
dev-depends upward on purpose. `dev_dependencies_genuinely_point_upward` asserts the exemption is
still *needed*, so nobody can fold dev edges into the rule and have it pass for the wrong reason.
`[build-dependencies]` are not exempt, and optional versus non-optional is not distinguished — an
optional normal dep is still an edge somebody can turn on.

## `compile_time_path_gate.rs` — a running binary may not use its build tree [#compile_time_path_gaters--a-running-binary-may-not-use-its-build-tree]

`env!` over the manifest directory expands at **compile** time to the directory of the crate being
built, so the value names the tree the binary was built in, never the project it is later run from.
On the box that built it those two coincide, which is exactly why the defect is invisible everywhere
except in production.

The tree convicted itself before the gate existed: a venue bridge built its sidecar-jar and JVM
fallbacks that way, so a binary built elsewhere and deployed into a project folder found neither and
degraded to paper with nothing in the log but "bridge jar not found". Both reads were already pinned
by the settings registry — and the *deployment* consequence was gated by nothing at all. Both sites
were retired in the batch that added this gate; it exists to stop the class growing back.

**Reading the failure.** Every use in non-test `src/` of a workspace member is keyed on
`(file, enclosing fn)` and carries a `Disposition` — a closed three-variant classification, not a
free-text reason column, because these are not exemptions: several are debt somebody should still
retire, and a reason column is an invitation to write a plausible sentence and join the list. The
class that *claims* mitigation is machine-checked: `every_ladder_rung_row_is_corroborated_by_its_file`
requires such a file to actually reach the runtime store-root resolver, and requires every other
row's file not to. So the repair is either to route the path through the runtime resolver or to
classify the site honestly — never to add a row that says something plausible.

Three exclusions fall out of deriving the roster from `[workspace] members` rather than maintaining a
list: vendored third-party code, the excluded protobuf regeneration recipe (whose own compile-time
path is correct — the build tree *is* its subject), and `tests/`/`benches/`, where resolving a
committed fixture from the manifest directory is right and a gate arguing with roughly 50 such sites
would teach people to write exceptions.

## `duplicate_shape_gate.rs` — a hoisted primitive may not be re-spelled [#duplicate_shape_gaters--a-hoisted-primitive-may-not-be-re-spelled]

The motivating commit added four fresh copies of the closing-side ternary to the backtest engine
**six days after** that helper was hoisted into the shared scalar module. CI was green.

The gate walks the real `crates/` tree, masks comments and string literals, and looks for the banned
expression shapes textually. Each shape names the one helper it should call: the closing-side
ternary, and a hand-rolled quantity·price·multiplier product — which resolves to one of *three*
notional helpers that are not interchangeable, because picking the wrong one silently changes risk
arithmetic.

**Reading the failure.** `ALLOWLIST` carries an exact **count** per `(file, shape)`, and it fails in
both directions: too many sites is a new re-spelling, too few is a stale exemption. So converting an
allowlisted site forces its entry to be revisited rather than quietly outliving its reason. The gate
is textual on purpose and must not become an AST pass — an approximate matcher plus an explicit,
reasoned allowlist beats a precise matcher nobody maintains. Its limits are declared: four-or-more
factor products are margin formulas with their own helpers and are out of scope, and factors are
classified by identifier *word*, so a price bound as a bare `p` carries no price word and escapes.


# Supply chain (/docs/trader/developer/supply-chain)



Vike Trader's whole workspace compiles into one order-signing binary, and every workflow in the
product repository runs on self-hosted runners — the machines that hold the credential store and run
the live trading daemons. Three gates carry the consequences.

## What CI may fetch [#what-ci-may-fetch]

`crates/vike-ops/tests/supply_chain_gate.rs` opens with the fact that shapes it: the runners use
`clean: false` and a persistent per-runner `CARGO_HOME`, so a tool fetched by a CI step "lands on
the trading box and stays there" — and both tools it governs then execute everything.
`cargo-nextest` runs every test binary in the workspace; `sccache` is installed as `RUSTC_WRAPPER`
and wraps every `rustc` invocation on that runner thereafter. The policy predated the gate and was
already false in two places when the gate was written, which is the whole argument for gating it.

* **`every_action_reference_is_sha_pinned`** — every third-party `uses:` names a full 40-character
  commit SHA. Two references had floating tags while \~25 others were SHAs. A major-version tag is
  retagged on every point release, and even a patch-specific tag "is only a POINTER: a tag can be
  force-moved onto any commit, so it names an intent, not an artifact."
* **`every_downloaded_archive_is_checksum_verified`** — a downloaded tool archive needs a
  `sha256sum -c` in the same file. cargo-nextest was fetched from a mutable URL piped straight into
  `tar`; sccache was version-pinned but unverified. A `curl | tar` "cannot be verified even in
  principle: the bytes are extracted before anything can look at them." The failure message adds the
  part people get wrong — take the sum from the vendor's published `.sha256` asset, because hashing
  the file you just downloaded verifies nothing.
* **`no_tool_download_resolves_a_mutable_pointer`** — no `/latest/`. Kept separate because a
  `/latest/` URL with a hard-coded sum is the worst combination: it breaks CI the moment upstream
  publishes, "which reads as flakiness and invites deleting the sum."

Detection is on shape, not spelling. `is_tool_fetch` records that its first draft keyed on a
`.tar.gz` suffix and so would not have caught the very line the change removed — that URL has no
extension at all. It now matches bytes piped into an extractor or interpreter, a URL that is plainly
an archive, or an output flag naming one.

<Callout type="warn" title="What the gate does not prove">
  It proves a download is version-pinned and sum-checked. It cannot prove the sum is the *right* one,
  and it says nothing about staleness: Dependabot maintains `uses:` SHA pins but cannot see a URL
  inside a `run:` block, so those pins are manual maintenance forever.
</Callout>

## How much unsafe code exists [#how-much-unsafe-code-exists]

`crates/vike-ops/tests/unsafe_and_toolchain_gate.rs` turns "how much unsafe is in this binary" into
a number. The root manifest declares `unsafe_code = "forbid"`, but cargo applies a workspace lint
table to a member only if that member opts in — so a crate that never wrote those two lines sits
silently outside the policy. One crate did exactly that; it had no unsafe in it, "which is precisely
why no human was ever going to find it."

So the gate walks the derived member roster, asks each manifest whether it inherits, and ratchets.
`UNSAFE_EXEMPT` may shrink, never grow, and holds two argued rows: the FXCM bridge, whose `sys.rs`
is a C++ FFI shim, and `vike-core`, which uses `deny` rather than the workspace forbid so a per-site
`#[allow(unsafe_code)]` can carve out audited OS-mmap entry points while every other unsafe stays
denied. `UNSAFE_SITES` is the literal answer — **15 sites, 4 files, 2 crates** — counted per file
rather than flagged, because the interesting regression is an already-blessed file growing a
fifteenth site, which a boolean cannot see. `UNSAFE_ALLOW_SITES` is the separate carve-out ledger,
and the two agreeing is itself the check.

The same file pins the toolchain: the channel is written in six places, and
`the_toolchain_version_has_exactly_one_value` makes them agree by test. Measured 2026-08-06, the
boxes did **not** agree on their default toolchain, so the pin is the only reason those environments
compile the same code with the same compiler.

## One transport stack [#one-transport-stack]

`deny.toml` is the single scanner over every locked package, run with `all-features = true` so it
sees the full attack surface rather than the default build. `[advisories]` runs stricter than
cargo-deny's defaults — `yanked = "deny"`, `unmaintained = "all"` — with `ignore` entries as the
only escape hatch, each carrying a reason and a recheck trigger; `[sources]` denies unknown
registries and git dependencies outright.

`[bans]` denies wildcard versions and carries the machine-enforced "ONE transport stack" list: no
second HTTP client (`reqwest`, `isahc`, `curl` → `ureq`), no second WebSocket (`tokio-tungstenite`,
`async-tungstenite` → `tungstenite`), no alternative TLS (`native-tls`, `openssl` → `rustls`;
`aws-lc-rs` → `ring`), no second curve implementation (`secp256k1` → `k256`). Every entry is green
today and was *proven to bite* by temporarily adding a second client and reverting. Shared HTTP type
and parse libraries are deliberately not banned — banning them would redden the gate rather than
catch a real second stack.

`[licenses]` sets `private = { ignore = true }`, and that exemption is what keeps the gate green:
the licence is source-available rather than OSI-approved, so it has no SPDX identifier and could
never appear in the allow list. Free. Source-available under FSL-1.1; every release becomes
Apache-2.0 two years on.

`just deny` audits the source lockfile at merge. Its release-time twin `just audit-bin` builds a
shipped binary with an embedded SBOM via `cargo-auditable` and scans the *artifact* against RustSec
— what the distributable actually links.

Related: [Release gates](/docs/trader/developer/release-gates) ·
[Drift gates](/docs/trader/developer/drift-gates) ·
[Architecture](/docs/trader/concepts/architecture)


# Where it runs (/docs/trader/getting-started/deployment-targets)



One core, several front ends. Which one you install decides what you can do without touching
anything else, so the choice is worth a table before a download.

## The surfaces [#the-surfaces]

| Surface                                          | Backtests               | Paper            | Live        | Studio                             | Observe                       | Managed by                | Needs                            |
| ------------------------------------------------ | ----------------------- | ---------------- | ----------- | ---------------------------------- | ----------------------------- | ------------------------- | -------------------------------- |
| Desktop app (`vike-desktop`, `vike-desktop.exe`) | only via a data service | no               | no          | remote store only                  | its only mode                 | you, on your desk         | a GPU, a display, a running node |
| `vike-tradehub`                                  | no                      | yes, the default | yes, opt-in | no                                 | it is the node being observed | systemd, or the container | no GPU; a project folder         |
| `vike-datahub`                                   | yes — it serves them    | no               | no          | it is what remote runs dispatch to | no                            | systemd, or the container | no GPU; a history store          |
| `backtest`                                       | yes, one process        | no               | no          | no                                 | no                            | a shell                   | no GPU; a history store          |
| `vikeio/vike-tradehub` image                     | yes                     | yes              | yes, gated  | no                                 | serves the node               | Docker                    | a mounted project folder         |
| `vikeio/vike-thin` image                         | only via a data service | no               | no          | remote store only                  | its only mode, in a browser   | Docker                    | CPU for software rendering       |

**The desktop app** ships as **one** build. `vike-desktop` declares no cargo features at all: it
holds no trading core, mounts no venue, links no DataFusion and takes `vike-data` with default
features — the `HistStore` trait and nothing behind it. What it draws comes from a node and a data
service over the wire, which is why it needs one running.

It drives the Studio remote-only, against the resolved datahub address — the explicit
`config.datahub_addr`, else a connected backend's own advertisement — and shows a
"Studio: no data store" label naming both fixes when neither answers.
[Observe mode](/docs/trader/gui/observe-mode) covers the modes; the sizes are on
[Requirements](/docs/trader/getting-started/requirements).

<Callout title="This was two builds, and the second one is gone">
  Until the 2026-09-09 rename the crate was `vike-app` and was compiled twice — a `fat` default with
  a local trading core, DataFusion tick recording and the venue bridges, published as `vike-app-fat`,
  and a `thin` observe-only client published as `vike-app-thin`. The `fat` resolution was deleted
  along with the local core, so the surviving build is what `thin` described and the two suffixed
  assets are gone with it. The container image keeps the name `vikeio/vike-thin` deliberately — the
  word now describes the deployment shape, a GUI in a container against a remote node, rather than a
  cargo feature.
</Callout>

**`vike-tradehub`** is the headless daemon: a strategy named in a TOML profile, mounted on the
production live core over the paper exchange by default, with zero real-money, credential or geo
risk and no live feed. The opt-in live variant mounts the same strategy on the real multi-venue
core with per-venue credential-gated execution and the venue's own feed, behind the
`tradehub_live` flag, the credential store, each venue's own second gate, the daemon's venue
allow-list (`LIVE_WIRED_VENUES`) and a venue-plus-symbol check against the core's wired-markets
table. Its observe/control server starts only when an address is configured — `config.tradehub_addr`
or `VIKE_TRADEHUB_ADDR`, unset by default, with the commented `127.0.0.1:7879` in the shipped
examples as the loopback address to use — and is authenticated with scoped HMAC node keys. The Linux
unit is `deploy/vike-tradehub.service`; the container is the same binary under `docker run`. No
daemon asset is published for Windows.

**`vike-datahub`** is the compute-to-data backtest server: a client ships a small profile over
a loopback TCP socket, the server runs the existing backtest engine next to the data and returns
only the report. It listens on `127.0.0.1:7878` by default and refuses a non-loopback bind unless
`VIKE_DATAHUB_ALLOW_PUBLIC_BIND=1` is set *and* a node key is configured; with neither
`VIKE_DATAHUB_OBSERVE_KEY` nor `VIKE_DATAHUB_CONTROL_KEY` in the credential store it
authenticates nothing, which is why it is meant to be reached over an SSH tunnel. The release
binary carries the `serve-datafusion` backend; a default build answers `--help` and reports it has
no backend. It is also what the Studio's [remote runs](/docs/trader/gui/studio/remote-runs) dispatch to.

**`backtest`** is the one-process path: it opens the history store itself, runs a profile, prints
a report, and persists a single run under `<project>/user_data/runs/<run_id>/`. It also owns the
three ways a fresh store gets data — `--seed-demo`, `--fetch` and `--fetch-starter` — because the
tool that consumes history is the honest place for the command that creates some.

## The two images [#the-two-images]

`vikeio/vike-tradehub` carries the whole headless product as one multicall binary, `vike-backend`,
which
answers to every tool name through argv\[0]: `vike-tradehub` (the daemon the container starts by
default), `vike-cli`, `backtest`, `vike-datahub`, `vike-recorder`, `vike-study` and `tearsheet`
(`crates/vike/src/main.rs`'s `TOOLS` — the crate directory kept its old name). Measured on the release runner, the three DataFusion-linked
binaries are 128, 106 and 107 MB apiece; the multicall links that closure once. It runs one tool
per process, deliberately — every tool owns process-global state that assumes it is alone.

That the image is a first-class way to install — not a convenience beside a "real" one — is a
ruling rather than a slogan: it carries every headless tool because an earlier boundary keeping the
image deliberately partial was lifted, which `CHANGELOG.md`'s 0.1.17 entry records. The project
folder is a bind mount that outlives the image.

`vikeio/vike-thin` is the observe-only GUI as a container: the binary runs against a virtual
framebuffer on Mesa's lavapipe software rasteriser and is exported over VNC and noVNC, so it
behaves identically on Linux, Windows and macOS hosts because nothing in it touches host hardware.
The cost was measured on the same idle chart: the native binary drew about 22 fps at 10.9–12.5%
CPU; the container drew about 12 fps at 79–275% CPU. It is for the case a binary cannot serve —
a host with no published asset, a machine you do not control, occasional access — and it is not a
replacement for the native client.

<Callout type="warn" title="What the published backend image does not carry">
  The desktop app (`vike-desktop` needs GPU passthrough), IBKR (the release build enables no `ibkr`
  feature and IB's own gateway would be yours to run), a linked FXCM daemon (`vike-tradehub-fxcm` is
  a separate release asset; the image is built from the `vike-backend` asset alone),
  and a Java runtime for Dukascopy (the image installs no package and stages no runtime tool). None
  of those venues is wired in this image at all — `crates/vike-run/src/node.rs`'s `WIRED_MARKETS`
  carries no IBKR or FXCM row without their cargo features, and Dukascopy has no
  `vike_mount::make_engine` arm in any build — so no engine is mounted for them and nothing is
  announced. A live profile that names one is refused at startup against `LIVE_WIRED_VENUES`, not
  quietly demoted to paper.
</Callout>

## Choosing [#choosing]

* You want a chart and a first backtest on your own machine: the desktop app against a node, or
  the backend image plus `backtest`. [Install on Windows](/docs/trader/getting-started/install-windows),
  [Install on Linux](/docs/trader/getting-started/install-linux),
  [Install with Docker](/docs/trader/getting-started/install-docker).
* You want a strategy running while your laptop is closed: `vike-tradehub` on a Linux box, native
  or in the container, watched from the desktop app over an SSH tunnel.
* You want backtests to run where the history is: `vike-datahub` beside the store, driven by
  `vike-cli backtest`, `sweep` and `walkforward` from anywhere.


# Your first chart (/docs/trader/getting-started/first-chart)



The desktop app opens on a live chart, so "your first chart" is mostly learning what is on it
and how to change it. Five minutes, no credentials — the default feed is Binance's public kline
stream.

## What you need [#what-you-need]

* `vike-desktop` — [Windows](/docs/trader/getting-started/install-windows) or
  [Linux](/docs/trader/getting-started/install-linux) — and the GPU
  [Requirements](/docs/trader/getting-started/requirements) names. It compiles in no local core and no
  venue bridge, so it charts what a daemon streams it: [Observe mode](/docs/trader/gui/observe-mode).
* A running `vike-tradehub` node to point it at. There is no build that trades on its own.
* Internet access to Binance's public endpoints
  (`crates/bridges/binance/src/market_feed.rs`'s `BINANCE_URLS`).

## 1. Launch [#1-launch]

```sh
vike-desktop
```

The window opens maximized and frameless with its own caption, titled `vike_trader_rust — live`.
With no saved workspace, `crates/vike-app-core/src/startup.rs`'s `plan` opens the default
layout: one `BTCUSDT` `1m` chart on Binance with an SMA overlay and RSI and MACD panes, its feed
ensured before the window is published. A saved workspace wins over that default on every later
start, and the last-used named layout wins over the plain file (`restored_workspace`).

## 2. Read what you are looking at [#2-read-what-you-are-looking-at]

The data path is `main.rs`'s header: feed threads → the core's ingest (lossless bar closes,
conflated forming bars and ticks) → the core-owned bar cache → an arc-swapped `CoreSnapshot`
→ the GUI's render model, with the GUI a lossy observer of core state. Per `(symbol, interval)`
the Binance feed runs one thread — a REST kline backfill as the warmup seed, then the public
kline WebSocket — closed bars on the lossless lane, forming updates and last-price ticks on the
conflating one (`market_feed.rs`'s header). So the right-most candle moves between closes; the
ones behind it are final.

The panel (`crates/vike-chart/src/chart/mod.rs`'s header): a right price axis with a price-tag
chip, a time axis with an hourly grid, a dashed last-price line, a crosshair with a time tag,
bottom nav buttons (− + ‹ › ⟳) plus **Auto**, and a style selector. Charts follow the live edge
and auto-fit y out of the box (`vike_chart::interact::FollowLive`): appended bars keep the view
pinned right, panning or zooming away disengages, Reset/Auto — or panning back — re-engages.
`ChartStyle::ALL` holds 20 styles, from candles through Renko, Kagi and Point & Figure to
Footprint.

Everything else sits on one title bar (`crates/vike-desktop/src/chart_window.rs`'s `title_bar`):
the style menu, the symbol and interval buttons, the sync-group chip, **ƒx** (indicators),
**OF** (CVD / Volume Profile / tick size), **Cmp** (compare overlays), the LIVE badge, and the
clone / minimize / maximize / close controls.

## 3. Pick a symbol [#3-pick-a-symbol]

Click the symbol. The popup opens with a focused **Search symbol** box, asset-class tabs — All,
then Stocks, Forex, Crypto, Perps, Options, Futures, Indices, Prediction (`PICKER_TABS`) — and a
venue button cycling All → binance → bybit → okx → hyperliquid → All (`PICKER_VENUES`). Results
come from `vike_catalog::Catalog::search`, up to 60 rows: exact symbol first, then symbol
prefix, base prefix, substring; ties broken by quote (USDT, USDC, USD, BTC, others) and then
catalog order. An empty query returns the filtered head, so the list is useful before you type.
Clicking a row sets symbol *and* venue together and carries the asset class, so a non-spot
symbol routes to its native product feed; a non-Binance chart shows a `VENUE:` prefix on the
symbol button.

The catalog is fetched once, off the UI thread (`main.rs`'s `spawn_catalog_fetcher`): every
wired venue's `CatalogProvider` contributes its universe, a failing provider contributes
nothing, and the credential-gated ones (Alpaca, OANDA, cTrader) yield nothing without keys.
Until it lands the popup shows the quick-picks `BTCUSDT`, `ETHUSDT`, `SOLUSDT` (`SYMS`),
Binance symbols that reset the venue to Binance.

<Callout type="warn" title="The picker searches twelve venues; the app charts six">
  `crates/vike-app-core/src/feed_lifecycle.rs`'s `ensure_feed_on` doc: the app registers live
  clients for binance, bybit, okx, aster, hyperliquid and polymarket, while the picker searches a
  twelve-venue catalog. Pick an alpaca, oanda, dukascopy, fxcm or ctrader instrument and the
  window lands on a venue with no feed — it paints nothing and warns once. Perps, futures and
  options chart only on okx, binance, bybit, aster and hyperliquid; deribit and polymarket rows of
  those classes skip the subscribe (`venue_routing::venue_bar_instrument`).
</Callout>

## 4. Change the interval [#4-change-the-interval]

Click the interval: `1s`, `1m`, `5m`, `15m`, `1h` are venue klines (`IVLS`); below the
separators, `100t` / `500t` / `1000t` are tick-count bars and `1v` / `10v` / `100v` are
volume-threshold bars, both built client-side from the trade tape (`TICK_IVLS`, `VOLUME_IVLS`).

## 5. Add an indicator [#5-add-an-indicator]

**ƒx** opens the indicator picker — search, category tabs, favourites, your own installed
studies, and the "On this chart" list with a per-study settings ⚙ (`tool_views::fx_picker`);
the [catalog](/docs/trader/indicators) lists what it offers. **OF**'s CVD and Volume Profile toggles
make the window lazily subscribe the trade feed (`WinState::orderflow_on`); **Cmp** adds a
percent-normalized overlay of another symbol, and the first overlay flips the price scale to
Percent because overlays draw only there (`WinState::add_compare`).

## More windows, and saving [#more-windows-and-saving]

File ▸ New chart window cascades a fresh chart (`crates/vike-app-core/src/workspace/menu.rs`'s
`menu_bar`; the Window menu holds the arrange verbs). The title bar's clone copies the source
window's symbol and interval.

<Callout type="warn" title="A clone loses its venue">
  `crates/vike-app-core/src/window_spawn.rs`'s header pins it: a clone keeps symbol and interval
  but not `venue`, so cloning an OKX chart yields a window pointed at Binance carrying an OKX
  symbol, subscribed by nobody. Open a new window and pick the symbol again instead.
</Callout>

File ▸ Save Workspace writes the chart layout — symbol, interval, style, geometry, scale,
options, panes, indicators — to `<project>/settings/state/workspace.json` (`$VIKE_WORKSPACE`
overrides), restored at startup; File ▸ Save layout as… keeps named layouts under
`layouts/<name>.json` beside it (`crates/vike-app-core/src/workspace/persist.rs`). Tool windows
are not saved; the launcher recreates them. View ▸ Timezone and File ▸ Export chart image… are
the other two menu verbs worth knowing (`workspace::menu::MenuResult`).

## Verify [#verify]

The last candle changes between bar closes and the dashed last-price line tracks it; the
right-most close arrives on the interval you picked.

## Where to next [#where-to-next]

* [Quickstart: first paper mount](/docs/trader/getting-started/quickstart-paper) — the Trade window
  beside this chart.
* [The chart](/docs/trader/gui/chart) · [Workspaces](/docs/trader/gui/workspace) ·
  [Order flow](/docs/trader/orderflow) · [The desktop app](/docs/trader/gui).

## Troubleshooting [#troubleshooting]

* **The chart is empty after picking a symbol.** The venue has no feed, or the product has no
  bar feed on that venue — the callout in step 3. Pick the same instrument on binance, bybit,
  okx, aster or hyperliquid.
* **The picker shows only three symbols.** The catalog has not loaded or every provider failed
  (no network); the quick-picks are the fallback. Only Deribit's catalog is linked into this
  binary, by design — every other provider answers over the wire.
* **A cloned window never paints.** It dropped its venue — the callout above.
* **The saved layout did not come back.** `restored_workspace` skips the restore under
  `VIKE_SHOT`; otherwise confirm `<project>/settings/state/workspace.json` exists — File ▸ Save
  Workspace is its only writer.

More in [Troubleshooting](/docs/trader/troubleshooting).


# Getting started (/docs/trader/getting-started)



Vike Trader is one execution core with several faces. Before installing anything, the question worth
answering is which face you want, because the install differs and so does what you do first.

Nothing on this path can place a real order. Every venue starts on the paper exchange, and arming one
is a deliberate act you take later, in a file, per venue.

## Which surface [#which-surface]

<Cards>
  <Card title="The desktop app" href="/docs/trader/getting-started/first-chart" description="Charts, the DOM ladder, the trade panel and the Studio IDE. Windows or Linux, one window per thing you are watching. Start here if you want to see markets and click." />

  <Card title="The headless daemon" href="/docs/trader/getting-started/install-linux" description="vike-tradehub: no window, one strategy mounted, controlled over a socket. Start here if you want something that runs on a box and outlives your shell." />

  <Card title="The command line" href="/docs/trader/getting-started/quickstart-backtest" description="vike-cli: scaffold a project, run a backtest, drive a node — and the same binary serves the MCP tools an agent calls. Start here if you want a report without a GUI." />

  <Card title="Where it runs" href="/docs/trader/getting-started/deployment-targets" description="All five deployable shapes side by side, including the data service and the standalone runner — what each can do, who manages it, and what it needs." />
</Cards>

## The order to read this in [#the-order-to-read-this-in]

**Understand it, then size it.** [What is Vike Trader?](/docs/trader/getting-started/what-is-vike-trader)
is the two-minute tour; [Requirements](/docs/trader/getting-started/requirements) carries the measured
numbers for GPU, memory, disk and network per surface — and the fact that there is no macOS build.

**Then install.** [Docker](/docs/trader/getting-started/install-docker) is the shortest path and the one
that needs least from your machine. [Windows](/docs/trader/getting-started/install-windows) and
[Linux](/docs/trader/getting-started/install-linux) install the release binaries directly; each ends with
one project folder holding settings, state, data and logs together.

**Then run something.** Two quickstarts, and they answer different questions.
[First backtest](/docs/trader/getting-started/quickstart-backtest) needs no credentials at all — it
scaffolds the examples, seeds a synthetic tape and prints a report.
[First paper mount](/docs/trader/getting-started/quickstart-paper) brings up a live market feed with every
venue on the paper exchange, so you can watch real prices and place an order that reaches nothing.
[Your first chart](/docs/trader/getting-started/first-chart) does the same in the desktop app.

**Then keep it current.** [Updating](/docs/trader/getting-started/updating) covers what a release is, how
to tell which build is running, and what a version bump does to a write-ahead journal.

## What comes after [#what-comes-after]

Once something runs, the tree splits by what you are trying to do. The
[concepts](/docs/trader/concepts) explain how the thing works — the execution core, the venue seam, the
journal, the gates. The [guides](/docs/trader/guides) are task-shaped: arm a venue, record a feed, replay
a session, triage a stuck order. The [tutorials](/docs/trader/tutorials) are worked runs end to end, with
every number pasted from a real one.

<Callout type="warn" title="Arming is separate, and deliberate">
  Installing arms nothing. A venue trades live only once its per-venue ceiling in `policy.toml` says so
  **and** its credentials are present — the ceiling is read first, so a box with no `[venues]` table
  mounts everything paper whatever else is configured. See
  [risk and arming](/docs/trader/concepts/risk-and-arming) before you go looking for the switch.
</Callout>


# Install with Docker (/docs/trader/getting-started/install-docker)



The backend image carries the whole headless product — the daemon, the CLI, the runner, the data
service, the recorder and the reporting tools — as one container. Your settings, credentials,
state and data live in a project folder on the host, mounted in; the image contains no credential,
and a fresh folder mounts every venue on paper. Expect about ten minutes: a pull, three commands
in a folder, one `docker run`.

## Requirements [#requirements]

Docker or Podman on any host; see [Requirements](/docs/trader/getting-started/requirements) for the
per-OS notes. On Windows use PowerShell or a WSL shell for every command below, never Git Bash —
MSYS path conversion rewrites the container side of `-v`, so the daemon finds no project at all
and every venue silently stays on paper.

## Steps [#steps]

### 1. Pull the image [#1-pull-the-image]

```sh
docker pull ghcr.io/vike-io/vike-tradehub:<version>   # GHCR — named first, on purpose
docker pull vikeio/vike-tradehub:<version>            # Docker Hub, the same bytes
```

The release job that publishes these images tags each one with the release version alone —
`vike-tradehub:<version>`, and no moving `latest` — so a pull always names a version you chose.
GHCR is named first because publishing there stores no secret anywhere: that job pushes with its
own token, scoped to writing packages, while the Docker Hub name is the shopfront, the default
registry, so that pull needs no host prefix. `CHANGELOG.md`'s 0.1.16 entry records both
destinations and why each is reached the way it is.

Inside is one multicall binary, `vike`, answering to `vike-tradehub` (what
the container starts by default), `vike-cli`, `backtest`, `vike-datahub`, `vike-recorder`,
`vike-study` and `tearsheet` (`crates/vike/src/main.rs`'s `TOOLS`). The binaries are the
release's own bytes, copied in and never compiled inside `docker build`, which is why `--version`
can still name the commit.

### 2. Make the project folder [#2-make-the-project-folder]

```sh
R=/srv/vike-trader                       # your folder — substitute it everywhere below
mkdir -p "$R/settings/state" "$R/data"
docker run --rm ghcr.io/vike-io/vike-tradehub:<version> --template > "$R/settings/tradehub.toml"
```

* `settings/state` is the daemon's one writable directory. The `HALT` kill switch lives there and
  nothing creates it lazily; without it the switch is dead until someone reaches for it.
* `settings/tradehub.toml` is the daemon profile — venue, symbol, strategy. `--template` is a verb
  of the entrypoint, not the daemon: it prints the repository's own template to stdout and nothing
  else, so the redirect is safe. Without the file the daemon exits (`bad profile <path>: No such
  file or directory`).
* `data/` is the store, which must outlive a container.

The entrypoint refuses to start without the mount or `settings/`, then reports everything else
wrong inside the folder in one numbered list (`deploy/docker/entrypoint.sh`'s `check_project`),
and probes that `settings/state` keeps flock-serialised appends — the one filesystem shape no code
change rescues.

### 3. Run it [#3-run-it]

```sh
docker run -d --name vike-tradehub \
  --user "$(id -u):$(id -g)" \
  -v /srv/vike-trader:/project \
  --restart on-failure \
  --stop-timeout 10 \
  --memory 2g \
  --cap-drop ALL \
  --security-opt no-new-privileges \
  ghcr.io/vike-io/vike-tradehub:<version>
```

The node server is opt-in and the `docker run` above starts no listener: turn it on with
`-e VIKE_TRADEHUB_ADDR=0.0.0.0:7879`, publish the port to loopback — `-p 127.0.0.1:7879:7879`,
never `-p 7879:7879` — and reach it over an SSH tunnel. The image sets
`VIKE_TRADEHUB_ALLOW_PUBLIC_BIND=1` because a container must bind the wildcard inside its
namespace; on that wildcard address you will see one `ProceedExposed` line at start, and it is
true.

**On Docker Desktop (Windows/macOS)** keep `settings/` a bind mount and put the two writable paths
on named volumes: the mmap-backed journal suite measured 389 s over the host passthrough against
1.23 s on a volume.

```sh
docker volume create vike-state && docker volume create vike-data
docker run -d --name vike-tradehub \
  -v /srv/vike-trader:/project:ro \
  -v vike-state:/project/settings/state \
  -v vike-data:/project/data \
  --read-only --tmpfs /tmp \
  --restart on-failure --stop-timeout 10 --memory 2g \
  --cap-drop ALL --security-opt no-new-privileges \
  ghcr.io/vike-io/vike-tradehub:<version>
```

Drop `--user` with named volumes (a volume is owned by whoever first writes it); keep it with a
Linux bind mount, which carries host ownership.

<Callout title="The template gives you a paper mount, and that is the point">
  Nothing in a daemon profile arms a venue. Going live needs the venue's keys in
  `settings/secrets.env` — absent credentials are the live gate — and the per-venue ceiling in
  `policy.toml` raised from its `paper` default, which can only ever refuse. Start on paper, read
  the snapshot summaries, then read [Arm one venue for demo](/docs/trader/guides/arm-a-venue).
</Callout>

## Verify [#verify]

```sh
docker run --rm -v /srv/vike-trader:/project --user "$(id -u):$(id -g)" \
  --entrypoint /opt/vike/bin/vike-cli ghcr.io/vike-io/vike-tradehub:<version> config check
docker run --rm --entrypoint /opt/vike/bin/vike-tradehub ghcr.io/vike-io/vike-tradehub:<version> --version
```

The first judges the settings tree and the credential store and says *what* is wrong; it does not
judge `tradehub.toml`, which the entrypoint checks itself before this call. The second prints the
commit the binary was built from. The kill switch is a file, so it works from the host or through
`docker exec` whether or not the runtime answers: `touch /srv/vike-trader/settings/state/HALT`
stops new orders and `rm` resumes.

## Next steps [#next-steps]

A fresh store is empty, and every tool over it answers with an empty result that looks exactly
like a broken install. Two commands close it, both through the image's other tools:

```sh
docker run --rm -v "$R:/project" --entrypoint /opt/vike/bin/vike-cli  ghcr.io/vike-io/vike-tradehub:<version> init
docker run --rm -v "$R:/project" --entrypoint /opt/vike/bin/backtest  ghcr.io/vike-io/vike-tradehub:<version> --seed-demo
```

Then [Quickstart: first backtest](/docs/trader/getting-started/quickstart-backtest). To watch the daemon
from a browser — with its node server turned on, as above — the viewer image runs
`vike-desktop --observe` on a virtual display:

```sh
docker run --rm -p 127.0.0.1:6080:6080 \
  -e VIKE_TRADEHUB_ADDR=host.docker.internal:7879 \
  -e VIKE_TRADEHUB_OBSERVE_KEY=<the daemon's observe key> \
  -e VIKE_THIN_VNC_PASSWORD=<a password> \
  ghcr.io/vike-io/vike-thin:<version>
```

Open `http://localhost:6080`; it connects on its own. Publish that port to loopback only — VNC
carries mouse and keyboard, so whoever reaches it drives a GUI authenticated to a trading node —
and prefer the native `vike-desktop` binary whenever you can run one.

## Troubleshooting [#troubleshooting]

* **Every venue on paper, nothing in the log.** The mount or `settings/` was missing, or `docker
  run` came from Git Bash. The entrypoint names the `-v` flag; see
  [Troubleshooting](/docs/trader/troubleshooting).
* **Polymarket dials fail at the SOCKS connect.** The egress proxy defaults to the container's own
  loopback (`crates/bridges/polymarket/src/egress.rs`'s `proxy_url`). Set
  `-e POLY_PROXY_HOST=host.docker.internal`, a full `-e POLY_SOCKS_PROXY=...`, or
  `-e POLY_PROXY_ENABLED=false` if you are not geo-blocked; use `socks5h`, never `socks5`.
* **The log lands in your folder and grows.** Keep the baked `VIKE_LOG_FILE_LEVEL=warn`; the file
  layer defaults to `trace`.
* **`docker stop` cuts the resting-order cancel sweep short.** If you raise `shutdown_deadline_ms`
  in `tradehub.toml`, raise `--stop-timeout` in the same breath.
* **`'<project>/bin' holds files this image did not install`.** The entrypoint refuses to replace
  a `bin/` it did not stamp; move the files aside or set `VIKE_CONTAINER_ADOPT_BIN=1` if you mean
  it.


# Install on Linux (/docs/trader/getting-started/install-linux)



Linux gets the whole product as native binaries. Expect ten minutes for the headless set and a
first backtest; add the desktop app if the box has a display.

## Requirements [#requirements]

x86-64 with glibc 2.39 or newer — the assets are dynamically linked against the release runner's
Ubuntu 24.04, and an older host fails at exec, not at install. The desktop build additionally
wants a Vulkan-capable GPU, an X11 or Wayland session and a font from the candidate set.
[Requirements](/docs/trader/getting-started/requirements) has the measured numbers.

## Steps [#steps]

### 1. Choose a project root [#1-choose-a-project-root]

One directory on a disk with room, owned by the user that will run the binaries, holding `bin/`,
`settings/` (with `state/` and `state/logs/`), `user_data/` and `market_data/`. The root is a
parameter, not a convention.

```sh
R=/srv/vike-trader
mkdir -p "$R/bin" "$R/settings/state/logs" "$R/market_data"
```

<Callout type="warn" title="Not under $HOME if a system unit will run it">
  Every shipped unit sets `ProtectHome=yes`, which replaces `/home` with an empty directory inside
  the unit's namespace, and `ReadWritePaths=` does not rescue it. The daemon then starts with no
  settings and no credentials — `No such file`, not `Permission denied` — every venue silently on
  paper. Measured, twice.
</Callout>

### 2. Download and verify [#2-download-and-verify]

From the release: `vike-cli`, `vike-tradehub`, `backtest`, `vike-datahub`, `vike-recorder`,
`vike-study`, `tearsheet`, the desktop `vike-desktop`, and `SHA256SUMS`. The
manifest is the upload list — an asset cannot be published without a checksum — so verify the
lines for what you took:

```sh
cd "$R/bin"
grep -E ' (vike-cli|vike-tradehub|backtest|vike-datahub)$' SHA256SUMS | sha256sum -c
chmod +x vike-cli vike-tradehub backtest vike-datahub
```

Every Linux binary embeds its dependency SBOM (`cargo auditable`), and `--version` prints the
commit it was built from through `vike_buildinfo::version_line`.

### 3. First commands [#3-first-commands]

```sh
cd "$R"
bin/vike-cli --version
bin/vike-cli config check      # the verdict on settings/ and the credential store: exit 0 = nothing broken
bin/vike-cli init              # scaffold user_data/ with runnable examples, and print the map
bin/backtest --seed-demo       # the synthetic demo tape, under venue `demo`, into market_data/hist
```

`vike-cli init` writes only what is absent and never touches a file you edited. `config check`
judges the four settings files and the store; an absent credential store is fine, because absent
credentials are the live gate. Every binary resolves the project by walking up from the working
directory, so run them from `$R`, or set `VIKE_SETTINGS_DIR=$R/settings` to name it outright.

### 4. The desktop app, if you want it [#4-the-desktop-app-if-you-want-it]

```sh
bin/vike-desktop
```

The binary carries no hard dependency on libX11 or libwayland-client; winit loads them at window
creation, so a missing library surfaces as `XNotSupported(LibraryOpenError)` after the version
line. Install a font it can find — `/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf` is the floor
`vike_app_core::fonts` names — or the window controls render as empty boxes.

### 5. The daemon under systemd, when you want it unattended [#5-the-daemon-under-systemd-when-you-want-it-unattended]

The shipped unit `deploy/vike-tradehub.service` carries the placeholder root `/srv/vike-tradehub`;
substitute yours, check nothing was missed, install it as a *system* unit with a `User=` line, and
create `settings/state` first — under `ProtectSystem=strict` a missing `ReadWritePaths=` target
fails the unit with `status=226`.

```sh
cp settings/tradehub.example.toml "$R/settings/tradehub.toml"   # the source tree's template; the image prints the same bytes with --template
sed "s,/srv/vike-tradehub,$R,g" deploy/vike-tradehub.service > /tmp/vike-tradehub.service
grep -n /srv/vike-tradehub /tmp/vike-tradehub.service            # must print NOTHING
sudo install -Dm644 /tmp/vike-tradehub.service /etc/systemd/system/vike-tradehub.service
sudo systemctl daemon-reload && sudo systemctl enable --now vike-tradehub
```

The unit runs `ExecStartPre=<root>/bin/vike-cli config check`, so `vike-cli` must sit beside the
daemon or the unit fails with `status=203/EXEC`; it sets `VIKE_LOG_FILE_LEVEL=warn` and no
`VIKE_LOG_DIR`, so the log lands inside the one write grant; and it points `EnvironmentFile=` at
`<root>/.env`, never at the credential store. `sudo systemctl stop` is a graceful stop: SIGTERM
raises the same flag the interactive `shutdown` word raises and the ordinary teardown runs, as long
as `TimeoutStopSec=` stays above the profile's `shutdown_deadline_ms`.

## Verify [#verify]

```sh
bin/backtest --list                                  # the compiled strategy names
journalctl -u vike-tradehub | grep '"kind":"ready"'  # the daemon's ready banner, with its mode
```

The daemon logs the identity line first and its `settings dir:` line after it; with recording on,
its store open logs `tick store root resolved … rung=project` — read `rung=`, because `exe-dir`
means no project was found above the working directory.

## Next steps [#next-steps]

* [Quickstart: first backtest](/docs/trader/getting-started/quickstart-backtest) — the demo tape you
  just seeded, through the standalone runner or the data service.
* [Quickstart: first paper mount](/docs/trader/getting-started/quickstart-paper).
* Dukascopy needs the release's `jforex-bridge.jar` at `bin/jforex/jforex-bridge.jar` and a JRE
  under `bin/jre/`; LightGBM needs both `bin/lightgbm/lightgbm` and its `PROVENANCE` file. Both are
  Release assets, published beside the binaries and covered by the same `SHA256SUMS`; a source
  checkout also ships a helper that stages and verifies them into exactly that layout. See [Updating](/docs/trader/getting-started/updating).

## Troubleshooting [#troubleshooting]

* **`version 'GLIBC_2.39' not found` at exec.** The host's glibc is older than the runner's.
* **`status=226` or `203/EXEC` from systemd.** `settings/state` is missing, or `bin/vike-cli` is.
* **Empty boxes instead of window controls.** No font from the candidate set is installed.
* **`rung=exe-dir` in the daemon's store line.** No project above the working directory; run from
  the root or set `VIKE_SETTINGS_DIR`. More under [Troubleshooting](/docs/trader/troubleshooting).


# Install on Windows (/docs/trader/getting-started/install-windows)



Windows gets the desktop app, `vike-desktop.exe`, and `vike-cli.exe`, the command-line surface.
Both are cross-built for `x86_64-pc-windows-gnu` in the release's own `windows` job and need no
runtime shipped beside them. Expect five minutes: a download, a checksum, a folder, a double-click.

<Callout title="One desktop asset now, not two">
  The release used to publish `vike-app.exe` and `vike-app-thin.exe` — two feature resolutions of one
  crate. There is one. The crate declares no features at all, the desktop mounts no venue and runs no
  local trading core, and `vike-desktop.exe` **is** that build. A bookmark or runbook still naming
  either old file names an asset the release no longer produces.
</Callout>

## Requirements [#requirements]

A GPU with a Vulkan driver — the released binary was run on a Windows box and enumerated its real
Intel GPU through Vulkan — and the Segoe UI faces under `C:\Windows\Fonts`, which
`vike_app_core::fonts` looks for first. Details on [Requirements](/docs/trader/getting-started/requirements).

No daemon, runner or data-service `.exe` is published: the release's host lane builds those for
Linux only. To run the backend on a Windows box, use the container —
[Install with Docker](/docs/trader/getting-started/install-docker). `vike-cli.exe` is the exception and
does ship, which is what lets an MCP client on this box launch `vike-cli mcp` as a local subprocess
— see [Client setup](/docs/ai/trader/setup). It still needs something to talk to: its backtest tools want
a `vike-datahub` server and its live tools a running node, neither of which has a Windows binary.

## Steps [#steps]

### 1. Download and verify [#1-download-and-verify]

Take `vike-desktop.exe`, `vike-cli.exe` if you want the command line, and
`SHA256SUMS` from the release. The manifest
covers every asset, and the Windows lines are in it because the `windows` job wrote its own part
and the publish job verified that part before merging it. Check the file:

```powershell
(Get-FileHash .\vike-desktop.exe -Algorithm SHA256).Hash
Select-String vike-desktop.exe .\SHA256SUMS
```

<Callout type="warn" title="The executable is unsigned; expect the unknown-publisher prompt">
  The Windows job builds with `cargo build` and copies the result straight into the release; there
  is no code-signing step, so Windows shows its SmartScreen prompt on first launch. The checksum
  above is the verification, not the prompt.
</Callout>

### 2. Make the project folder [#2-make-the-project-folder]

Every setting, credential and program-written file lives in one folder, and the binary finds it by
walking *up from the working directory* for the nearest `settings\` directory
(`crates/vike-model/src/state_path.rs`'s `PROJECT_SETTINGS_DIR`).

```powershell
$R = 'C:\vike-trader'
New-Item -ItemType Directory -Force "$R\bin", "$R\settings\state\logs", "$R\market_data" | Out-Null
Copy-Item .\vike-desktop.exe "$R\bin\"
```

`bin\` is where the tools a project runs live (`vike_model::state_path::PROJECT_BIN_DIR`), so the
executable sits there and the walk from `bin\` finds `settings\` one level up. If you would rather
launch from anywhere, set `VIKE_SETTINGS_DIR=C:\vike-trader\settings`: it names the directory
outright and beats the walk.

### 3. First launch [#3-first-launch]

Start it from the project root — a shortcut whose *Start in* is `C:\vike-trader`, or a terminal
`cd`'d there:

```powershell
cd C:\vike-trader
.\bin\vike-desktop.exe
```

The window opens maximised, titled `— live`. Before it draws anything the app runs the one startup
sequence (`vike_boot::boot`): refuse a removed environment variable, resolve `settings\` once, load
the credential store, load the four settings files, then log its build identity and what it
resolved. With an empty `settings\` it starts on compiled-in defaults and every venue on paper —
absent credentials are the live gate. To point it at a node instead, name one:

```powershell
.\bin\vike-desktop.exe --observe <host>:7879
```

It takes `VIKE_TRADEHUB_OBSERVE_KEY` from `settings\secrets.env`, and from the environment when
the store has none (`vike_app_core::backend_registry`'s `fill_node_keys_from_env` — a gap-fill,
never an override: a store entry wins). The key must match the daemon's byte for byte. Leaving the
address off is not an error: it falls through to the configured node and then to the local default,
the window opens, and the status bar says whether it connected.

## Verify [#verify]

The rolling log lands at `settings\state\logs\`, prefixed `vike-desktop`
(`crates/vike-desktop/src/main.rs`'s `file_prefix`, not the executable name); its first line is the
identity line — `git <sha> clean, built <time>, <rustc>, <target>` — which names the commit you are
running. If the log appeared beside the executable instead, the walk found no project: check that
`settings\` sits beside `bin\` and that you launched from inside the folder.

## Next steps [#next-steps]

* [Your first chart](/docs/trader/getting-started/first-chart) — pick a symbol, see a live chart.
* [Quickstart: first backtest](/docs/trader/getting-started/quickstart-backtest) — the Studio dispatches the run to a
  data service; the demo tape and `vike-cli init` come from the container's tools on Windows, run
  against the same folder.
* [Observe mode](/docs/trader/gui/observe-mode) — how the app is pointed at a node.

## Troubleshooting [#troubleshooting]

* **SmartScreen blocks the launch.** The binary is unsigned; verify the SHA-256 and choose to run.
* **Every venue on paper and the log is beside the `.exe`.** No `settings\` above the working
  directory — see [Troubleshooting](/docs/trader/troubleshooting).
* **The node answers `bad mac`.** The observe key is absent or differs from
  the daemon's. The app takes it from `settings\secrets.env`, or from the environment when the
  store has none.
* **A blank window or no adapter.** wgpu found no Vulkan device; update the GPU driver.


# Quickstart: first backtest (/docs/trader/getting-started/quickstart-backtest)



A backtest in Vike Trader needs no venue credentials. `vike-cli backtest` ships a small run-profile
TOML to a running `vike-datahub`, which runs the backtest next to the data and returns only a
compact report; the standalone `backtest` binary is the one-process path that opens the store
itself. This page takes you from an empty install to a report using the examples `vike-cli init`
ships and the demo tape `backtest --seed-demo` writes.

## What you need [#what-you-need]

* `vike-cli`, `vike-datahub` and `backtest` — from a release, or all three inside the
  [container image](/docs/trader/getting-started/install-docker).
* No API keys. `vike-cli` opens the credential store for the `trade`, `mcp` and
  `strategy-status` verbs, which authenticate to a node, and for the surfaces that report on the
  store itself — `secrets list`, `config show` and `config check`; `init`, `backtest`, `sweep`,
  `walkforward` and `indicators` never open it. `vike-datahub` reads it only for its own node keys,
  and with none set it authenticates nothing on loopback; the `backtest` runner takes a profile and
  a store and nothing else.

## 1. Scaffold the examples [#1-scaffold-the-examples]

```sh
vike-cli init
```

This creates `<project>/user_data` — strategies, profiles, results, notebooks, logs — with a
runnable example in every folder but `logs/`, where a committed sample would be fiction, and
prints the map before you open a file manager. Re-running is safe: it writes only what is absent.
The pieces this page uses:

```
user_data/
  strategies/rhai/sma_cross/sma_cross.rhai   two moving averages, always in the market
  profiles/backtest.toml                     one run over the demo tape
  profiles/sweep.toml                        a 3 x 3 parameter grid, script inlined
  profiles/walkforward.toml                  four anchored out-of-sample windows, script inlined
```

## 2. Seed the demo tape [#2-seed-the-demo-tape]

```sh
backtest --seed-demo
```

A clean install has an empty history store, and a profile naming a slice the store does not hold
completes and reports no trades — indistinguishable from a strategy that never fired. The demo
tape closes that: `vike_data::demo` writes six months of hourly `BTCUSDT` bars
(2025-01-01 to 2025-07-01) plus the last week at one minute, every bar a closed-form function of
its timestamp, under the venue id `demo`. The shipped `profiles/backtest.toml` names exactly that
slice, and a test holds the two in agreement. Re-seeding writes nothing and says so.

<Callout type="warn" title="The demo tape is a curve, not market data">
  It exists so the tools have something to run. A result computed on it says nothing about any
  market, and it is written under its own venue precisely so it can never be aggregated with rows a
  recorder or a real fetch wrote. For real bars, `backtest --fetch binance:BTCUSDT:1h --days 180`
  pulls public klines with no credentials, and `backtest --fetch-starter` downloads the published
  starter dataset over plain HTTPS for a box that cannot reach a venue at all — Binance geoblocks
  whole countries at the REST layer. Both land under the venue's real id.
</Callout>

## 3. Start the data service [#3-start-the-data-service]

```sh
vike-datahub
```

It listens on `127.0.0.1:7878` (`VIKE_DATAHUB_ADDR`) and opens the store `VIKE_DATAHUB_STORE`
names, falling through `VIKE_HIST_STORE`, a source checkout if the box has one, then this
project's own `market_data/hist` — the same precedence `backtest --seed-demo` used, so from the
same project folder the two agree. Both log `hist store root resolved … store=<path>`; check that
the two lines match. It refuses a non-loopback bind unless you both consent
(`VIKE_DATAHUB_ALLOW_PUBLIC_BIND=1`) and configure a node key, so a remote server is reached over
`ssh -L 7878:localhost:7878 <box>`.

## 4. Run the backtest [#4-run-the-backtest]

```sh
vike-cli backtest \
  --profile user_data/profiles/backtest.toml \
  --script  user_data/strategies/rhai/sma_cross/sma_cross.rhai
```

The profile is shipped as text, and unless you pass `--script` or `--preset` the server is the only
thing that parses it. `--script` injects the file's source into `[strategy.params].src` before it
goes, which is one of two cases where the client re-serialises the TOML rather than sending your
bytes untouched. `--preset <p.toml>` merges a flat table of knobs into `[strategy.params]` the same
way, and it is resolved locally for a reason: only the profile text crosses the wire, so a preset
named *in* the profile would resolve against the server's `user_data/`, not yours.

The report is pretty-printed JSON and deliberately compact — `BacktestReport` carries the profile
name, final equity, total return, trade count, win rate, Sharpe, max drawdown, profit factor,
funding paid and per-symbol PnL, and a ranked zero-trade diagnosis when a run closed no trade and
its equity never moved. It carries no equity curve. `--json` prints the server's bytes verbatim;
`--addr <host:port>` names another server.

Two offline helpers need no server at all:

```sh
vike-cli backtest --list-params --script user_data/strategies/rhai/sma_cross/sma_cross.rhai
vike-cli indicators
```

The first prints the `param(name, default)` knobs a script declares; the second prints every
indicator a script can call, off the same derived list the host binds from.

## The one-process path [#the-one-process-path]

```sh
backtest --profile user_data/profiles/sweep.toml
```

The standalone runner has no `--script`: a profile it runs must carry the script inline in
`[strategy.params].src` — as the shipped sweep and walk-forward profiles do — or name a compiled
strategy from `backtest --list`. The shipped `sweep.toml` covers the demo tape's dates but names
`venue = "binance"`; change it to `demo` to run it here. A single run also persists under
`<project>/user_data/runs/<run_id>/` as `manifest.json` beside `report.json`; a sweep prints its
ranked table and writes nothing. `--store DIR` overrides the store root.

## 5. Search, then validate [#5-search-then-validate]

```sh
vike-cli sweep --profile user_data/profiles/sweep.toml --rank-by sharpe
vike-cli walkforward --profile user_data/profiles/walkforward.toml
```

A `[sweep]` table overrides `strategy.params.<key>` across a value grid and the server returns one
row per point, ranked by `sharpe`, `return`, `max_dd` or `equity` — the ranking is the server's own
`BacktestReport` numbers, never a client re-implementation. A walk-forward is a stability check,
not a second optimiser: `walk_forward_strategy` runs *one fixed parameter set* over each anchored
out-of-sample window, rebases the windows into one stitched equity curve, and `WalkForwardReport`
returns that curve's return and Sharpe beside `wf_consistency`, the fraction of windows that were
profitable. Point both profiles' `[data]` at a slice your store holds first — the shipped
walk-forward spans 2024 to 2026 on `binance`.

## Where to next [#where-to-next]

* [Running a backtest](/docs/trader/backtesting/running) and [Run profiles](/docs/trader/backtesting/run-profiles).
* [Walk-forward](/docs/trader/backtesting/walk-forward) — why it never re-fits.
* [Read a backtest report](/docs/trader/guides/read-a-report).
* [Connect an agent](/docs/trader/guides/connect-an-agent) — the same tools over MCP.


# Quickstart: first paper mount (/docs/trader/getting-started/quickstart-paper)



A paper mount is the desktop app's default state, not a mode you switch on: with no credential
store and no `[venues]` table, `vike_mount::make_engine` gives every venue the paper exchange,
and the first order you place is filled locally against live bars. Ten minutes, no API key.

## What you need [#what-you-need]

* The `vike-desktop` binary — [Windows](/docs/trader/getting-started/install-windows) or
  [Linux](/docs/trader/getting-started/install-linux); the backend Docker image ships no GUI, and the
  thin image's GUI is observe-only — it holds no local core, so it cannot do this walk. The desktop
  build needs the GPU [Requirements](/docs/trader/getting-started/requirements) names.
* Internet access to Binance's public market-data endpoints
  (`crates/bridges/binance/src/market_feed.rs`'s `BINANCE_URLS`).
* No credentials. Leave `<project>/settings/secrets.env` absent for this walk.

## Why nothing real can happen [#why-nothing-real-can-happen]

Two gates sit in front of every venue, and `crates/vike-mount/src/lib.rs`'s header states their
order. The per-venue **arming ceiling** (`policy.venues.<venue>`: `paper` \< `demo` \< `live`) is
consulted first, *above* the credential read — a `paper` venue "returns the paper client having
loaded no credential, fetched no instrument grid and opened no socket". Only then does the older
rule apply: absent credentials mean the venue stays paper.

The ceiling's default is the safe end. `crates/vike-mount/src/policy.rs`'s `MountPolicy::venues`
defaults to `paper` for every venue, and a missing `policy.toml` reads the same way, so a box
with no `[venues]` table mounts everything paper *whatever its credential store holds*. The fold
is `vike_config::VenueMode::cap`, a `min`: `venues.bybit = "live"` does not put bybit live, it
only declines to stop it. `VenueMode::Paper`'s own doc is the whole promise — "Simulated fills
against the local paper exchange. No credential is used, no order leaves the process."

## 1. Launch the app [#1-launch-the-app]

```sh
vike-desktop
```

Settings load before the log subscriber, the window, any feed and any core
(`crates/vike-desktop/src/main.rs`'s `resolve_settings`), and the startup disclosure
(`vike_config::boot_lines`) logs every `policy.*` ceiling plus one aggregated venues line. The
window opens maximized, titled `vike_trader_rust — live`, on the default layout from
`crates/vike-app-core/src/startup.rs`'s `plan`: one `BTCUSDT` `1m` Binance chart, its bar feed
already ensured.

Behind it, `App::new` builds the local core through `vike_run::build_node` — every wired venue's
engine via `make_engine`, `("binance", "BTCUSDT")` the primary
(`crates/vike-run/src/node.rs`'s `BINANCE_MARKET`), `10_000.0` seed per venue
(`NodeConfig::seed_cash`). Each paper engine is `crates/vike-mount/src/paper_fallback.rs`'s
`paper_engine`: a `PaperExecutionClient` with slippage `0.0002`, the venue's static fee schedule
(`vike_model::fee_schedule_for` keyed by `vike_catalog::fee_lane`), `BalanceMode::Delta`, and
the HALT sentinel armed (`paper_client`).

## 2. Open the Trade window [#2-open-the-trade-window]

Click **Trade** in the launcher row (`WinKind::LAUNCHERS`). The window
(`crates/vike-app-core/src/tool_views/trade.rs`'s `trade_tool_content`) is a cross-venue equity
hero, a per-venue Accounts table, a focused trade card and a working-orders table. Accounts rows
carry a `Δ` mode tag — `equity_panel::EquityRow`'s rendering of `BalanceMode::Delta`. The trade
card's header shows the symbol, a `PAPER&#x60; badge and the mark; the ticket has Market / Limit /
Stop tabs, a size field and an optional **+ TP / SL** bracket. **BUY** and **SELL** stay
disabled until the size is positive, a limit has a price or a stop a trigger, and the core
reports no fault (`trade_card`).

## 3. Place a market order [#3-place-a-market-order]

Pick **Market**, enter a small size, click **BUY**. The ticket becomes a `TradeSubmit`, and the
only path to the command lane is `crates/vike-app-core/src/order_dispatch.rs`'s
`Planner::admit`, which always validates against the local preview cap
(`order_entry::OrderLimits::with_max_notional`, fed by `policy.max_notional_per_order`,
permissive when unset), routes to the snapshot's market — binance `BTCUSDT` in the local build
— and `try_send`s into the core's single ingest queue, so the GUI never blocks
(`crates/vike-core/src/runtime/mod.rs`).

`PaperExecutionClient`'s doc says what happens next: `submit` publishes Submitted + Accepted
and rests the order; `on_bar`, "driven by the core on each closed bar of the mounted series",
fills the book with the engine's exact semantics — next-open market fills, limit/stop triggers,
adverse-first intrabar resolution, slippage plus maker/taker fees. So a market order fills at the
open of the *next* closed 1m bar, up to a minute after you click.

<Callout type="warn" title="Keep the 1m chart open on the mounted symbol">
  The paper book fills "against that venue's live 1m bars via the core's `on_bar` seam (so its
  bar feed must be subscribed)" — `paper_fallback.rs`'s `make_engine` doc. The default
  `BTCUSDT@1m` chart is that subscription, and `feed_lifecycle::reap_orphaned_feeds` stops any
  feed no window references. Close or re-interval that chart and resting paper orders wait for
  bars that never arrive.
</Callout>

## 4. Verify [#4-verify]

* The working-orders table lists the order until a terminal status — `is_terminal_status`
  names `FILLED`, `CANCELED`, `REJECTED`, `DENIED`, `EXPIRED`, `LIQUIDATED`; anything else
  keeps its inline ✕ cancel.
* After the fill, the trade card's position line reads LONG or SHORT with size, average price
  and unrealized P\&L; the hero's Realized / Fees / Funding are `hero_totals`' folds over the
  Accounts rows.
* The log lands under `<project>/settings/state/logs` by default (`vike_log::resolve_log_dir`),
  prefix `vike-desktop`. With journaling on (`VIKE_JOURNAL_DIR` or a run profile) the Tearsheet
  window reads the fill back from this session's command journal (`tearsheet_tool_content`).

Now rehearse the kill switch. `touch <project>/settings/state/HALT` — rung 2 of
`vike_bridge_core::halt::halt_path_from_env`; `VIKE_HALT_FILE` names a path outright. A paper
mount arms the sentinel precisely so this rehearsal is real (`paper_client`'s doc): the next
opening submit is refused with a terminal `OrderRejected`, a reducing submit is still admitted
(`vike_exec::halt::halt_admits_submit`), and cancel is never gated. Delete the file to resume.
[Halt](/docs/trader/concepts/halt) has the admit table.

## Where to next [#where-to-next]

* [Your first chart](/docs/trader/getting-started/first-chart) — the window you were staring at.
* [Arm one venue for demo](/docs/trader/guides/arm-a-venue) — the same mount, one venue at a time.
* [The paper exchange](/docs/trader/concepts/paper-exchange) — why backtest == paper by construction.
* [Risk and arming](/docs/trader/concepts/risk-and-arming) ·
  [`policy.toml`](/docs/trader/reference/settings/policy) ·
  [The trade panel](/docs/trader/gui/trade-panel) · [Venues](/docs/trader/venues).

## Troubleshooting [#troubleshooting]

* **"I have credentials and the venue is still paper."** The ceiling refused it. The mount logs
  `ARMING CEILING: <venue> has live credentials, and this deployment's ceiling for it is paper →
  staying PAPER` and names the key to set (`report_capped_to_paper`); with credentials and no
  `[venues]` table, a once-per-process `ARMING CEILING NOW IN FORCE` block lists every affected
  venue (`venue_arming_migration_message`). The Data Manager's **Venues** sub-tab shows Mode,
  Credentials and Effective per venue, each capped row naming its `ArmingBlock`
  (`crates/vike-app-core/src/tool_views/venues.rs`).
* **The order rests and never fills.** The callout above; a limit far from the market rests
  until a closed bar crosses it.
* **BUY/SELL are greyed out.** Size, price/trigger, or a core fault — after a panic the core
  enters safe state, `HALTED`, and denies every new order (`runtime/mod.rs`).
* **`vike-desktop` exits before a window appears.** A removed risk variable is set
  (`vike_config::REMOVED_ENV`, exit code 2), or `secrets.env` carries a `{VENUE}_MAINNET=1`
  line — `vike_config::arming` refuses a credential file that would arm real money; move the
  line to the process environment or delete it.

More in [Troubleshooting](/docs/trader/troubleshooting).


# Requirements (/docs/trader/getting-started/requirements)



## Operating systems [#operating-systems]

**Linux, x86-64.** Every headless binary and both desktop builds are published for it. The
binaries are built on an Ubuntu 24.04 release runner with no `--target`, so they are dynamically
linked against that box's glibc — measured at **2.39** — and a host with an older glibc fails at
exec rather than at install (Debian bookworm's 2.36 is the named counter-example). The container
image pins the same base for the same reason.

**Windows, x86-64.** The desktop app only: `vike-desktop.exe`,
cross-built for `x86_64-pc-windows-gnu`. The resulting binary was run on a Windows box: it
enumerated the real GPU through Vulkan, connected to a containerised daemon and rendered the UI
with the system fonts, with no missing DLLs and no runtime to ship beside it. No daemon, CLI,
runner or data-service `.exe` is published; the backend on Windows is the container.

**macOS: no build is published.** The `vikeio/vike-thin` container image runs on a macOS host because nothing
in it touches host hardware, which makes it the one route to the GUI there, in a browser.

## The desktop app [#the-desktop-app]

`vike-desktop` draws with wgpu, so a native run wants a GPU with a working Vulkan driver. Software
rendering works — the thin image runs the same binary on Mesa's lavapipe — but it is a CPU doing a
GPU's work: on one idle chart the native binary drew \~22 fps at 10.9–12.5% CPU where lavapipe drew
\~12 fps at 79–275%, and the cost is per frame rather than per pixel (4.7× the pixels bought only
\~1.3× the CPU).

On Linux the binary carries no hard dependency on libX11 or libwayland-client — winit loads them
at window creation — so a missing X or Wayland library is a runtime `LibraryOpenError` after the
app has already logged its version, not a start-up failure. The thin image's package list is the
measured set: `libxcursor1 libxrandr2 libxi6 libxinerama1 libxext6 libxrender1 libxfixes3
libxkbcommon-x11-0` and the `libxcb-*` siblings, each found by a crash. A font is required too:
`vike_app_core::fonts` looks for Segoe UI on Windows and for DejaVu, Liberation or Noto files
under `/usr/share/fonts` on Linux — DejaVu is the "always something" floor, the face the lists
count on being installed and the last candidate in `SYMBOLS`, which is the one behind the
title-bar controls; without any of them those controls and the chart buttons render as empty
boxes.

Sizes: the release runner measures the Linux and Windows desktop assets on every run and writes
them into the run log. The figures that used to sit here were of the `fat` and `thin` builds, which
are not produced any more, so they are not restated as if they described the one that is.

## The headless binaries [#the-headless-binaries]

No GPU and no display. Sizes measured on the release runner in the release profile:
`vike-tradehub` 128 MB, `backtest` 106 MB, `vike-datahub` 107 MB — each carrying its own static
copy of the DataFusion/Arrow/Parquet closure — against `vike-cli` at 9.6 MB and `tearsheet` at
1.9 MB. The multicall `vike` binary in the container links that closure once.

Memory: the shipped units cap each process rather than state a floor — `vike-tradehub` at
`MemoryMax=2G`, which the container recipe mirrors with `--memory 2g`; `vike-datahub` at 8G and
`vike-recorder` at 4G. Each is a starvation guard for a box that may also host live trading, and
each unit says to tune it to the box's headroom. Nothing in the tree states a minimum.

## Disk [#disk]

The project folder holds everything: `settings/`, `user_data/`, `market_data/` and `bin/`. The
history store lives at `<project>/market_data/hist` by default, resolved by the same walk that
finds `settings/` — `vike_model::store_path::resolve_store_root` is the precedence, and every
binary that resolves one logs the root and the rung that chose it before opening. A store that
records live feeds is measured in hundreds of gigabytes, which is why it is a sibling of the
directories you copy rather than a child of them. A fresh install is small: the demo tape is six
months of synthetic hourly bars plus one week of minutes, and the published starter dataset is
about 740 KB.

<Callout type="warn" title="The file log, not the store, is what once filled a disk">
  `RUST_LOG`/`VIKE_LOG` filter the console only. The JSON file log defaults to `trace` and captures
  every chatty dependency; one unattended run wrote 341 GB. Every shipped unit that runs a vike
  binary, and the backend image, set `VIKE_LOG_FILE_LEVEL=warn`, and `vike-log` prunes to the
  newest `DEFAULT_MAX_LOG_FILES` daily files at start. Set the level for any long run you launch
  by hand.
</Callout>

## Network [#network]

Venues are reached over TLS with the root certificates compiled into the binary — the container
image installs no `ca-certificates` because nothing in the ELF reads `/etc/ssl/certs`. Two venues
have regional constraints the tree names: Binance geoblocks whole countries at the REST layer,
which is why `backtest --fetch-starter` exists beside `--fetch`; and Polymarket is geo-blocked in
some regions, so its egress proxy defaults *on* at `socks5h://127.0.0.1:1080`
(`crates/bridges/polymarket/src/egress.rs`'s `proxy_url`), a default you turn off or repoint
through the `POLY_PROXY_*` knobs. The daemon's node server and the data service both bind loopback
by default and are meant to be reached over an SSH tunnel; the handshake is plaintext and the
tunnel supplies confidentiality.

## Docker [#docker]

Any host with Docker or Podman. Those two are what the release build itself drives: the image is
built and smoke-run under one of them before it is published, so they are the pair the published
image is known to work with. Another OCI runtime may well run it; nothing here has tried one. On a
Linux host a bind mount is an ordinary `mount --bind`, measured directly. On Docker Desktop
(Windows and macOS) keep `settings/` a bind mount and put `settings/state` and `data` on named
volumes: the mmap-backed journal suite took 389 s over the host passthrough against 1.23 s on a
volume, and concurrent appends are correct there only because every change-journal append takes an
exclusive `flock`. [Install with Docker](/docs/trader/getting-started/install-docker) carries the
recipes.

## Three venues need more than a binary [#three-venues-need-more-than-a-binary]

Dukascopy executes through a Java sidecar: the release ships `jforex-bridge.jar`, and a JRE plus
the jar must sit under `<project>/bin/jre/` and `<project>/bin/jforex/` (or be named outright by
`JAVA_HOME` and `JFOREX_BRIDGE_JAR`) — `crates/bridges/dukascopy/src/config.rs`'s
`resolve_dukascopy_tools` is the ladder, and its last rung is a bare `java` on `PATH`. IBKR trades
against IB's own Client Portal Gateway, which you run. FXCM needs the ForexConnect SDK linked in,
which only the separate `vike-tradehub-fxcm` asset carries, and `vike_fxcm::sdk_linked()` demotes
an unlinked binary to paper at the mount. The generated pages under [Venues](/docs/trader/venues/)
carry each venue's caveats.


# Updating (/docs/trader/getting-started/updating)



A release is a semver tag on a commit that was re-validated over the whole crate roster before
anything was published; `CHANGELOG.md` is the curated summary and the release's own notes are the
PRs merged since the previous tag. Every asset is listed in `SHA256SUMS`, which is the upload
manifest itself — an asset cannot reach the release without a line in it — and a re-run replaces
same-name assets rather than duplicating them.

## Which build is this? [#which-build-is-this]

```sh
vike-cli --version
# vike-cli 0.1.0 (git 62ccdd8e clean, built 2026-08-09T09:41:07Z, rustc 1.96.0, x86_64-unknown-linux-gnu)
```

`vike_buildinfo::version_line` prints the package name and version, then the commit, its
clean/dirty state, the build time, the compiler and the target. Every daemon logs the same line
first at startup, so `journalctl -u vike-tradehub | head` answers it for a running unit. Read
`dirty` and `clean` differently: `dirty` is authoritative, `clean` means no committed change since
the crate was last built, and `dirty?` means the build could not ask git at all. The desktop app
has no `--version` flag; its identity line is the first line of its log.

## The order [#the-order]

1. **Read `config check` on the new binary before you restart anything.** A settings key that
   nothing reads is rejected by name on load, so a key a newer release adds cannot be written
   before the binary that reads it is installed — and a removed environment variable is *refused*
   at startup rather than ignored (`vike_config::REMOVED_ENV`), which is the one update step that
   can turn a daemon that used to start into one that does not. It is telling you something true.
2. **Stop gracefully.** `sudo systemctl stop` sends SIGTERM, which raises the same stop flag the
   interactive `shutdown` word raises, and the ordinary teardown runs — the strategy-state save and
   the terminal journal snapshot, plus the resting-order cancel sweep when
   `flags.cancel_orders_on_shutdown` is on (it is off by default, so quotes stay resting at the
   venue). Keep `TimeoutStopSec=` above the profile's `shutdown_deadline_ms` or SIGKILL wins the
   race.
3. **Replace the binaries** under `<project>/bin/`, verifying each against the new `SHA256SUMS`.
4. **Re-run `vike-cli init`.** Re-running is the ordinary case: a new version ships new examples,
   the default writes only what is absent, and an edited file is never touched. `--reset` restores
   the shipped samples and nothing else; `--dry-run` says what would change.
5. **Start, and read the identity line** to confirm the running commit is the one you installed.

<Callout title="The store does not move on an update, and the log line proves it">
  Every binary that *resolves* the history-store root logs `hist store root resolved …
  store=<path> rung=<rung>` before opening it — `vike` (whose line reads `studio hist store root
  resolved`), `backtest`, `vike-datahub` and the `vike-backfill` collectors. `explicit`/`env` mean
  you named it, `declared-project` means `VIKE_SETTINGS_DIR` did, `dev-checkout` means the source
  checkout that built the binary is still on this box, `project` means the walk found it, `user-dir`
  means no project was found, and `last-resort` means no per-user directory either
  (`crates/vike-model/src/store_path.rs`'s `StoreRootRung`, whose `why` sentence rides the same
  line). A store does not merge: if that line ever changes between versions, the old store is simply
  no longer read and a run reports zero rows rather than failing. The binaries handed a path
  outright print no such line and need none: `vike-recorder` takes it from its profile, `vike-study`
  and `tearsheet` from `--store`; `vike-tradehub` resolves a tick store instead and logs `tick store
  root resolved`.
</Callout>

## Images [#images]

Each image is tagged with the version alone — `vike-tradehub:<version>`, `vike-thin:<version>`,
the same tag on GHCR and Docker Hub — so an update is a pull of the new tag, `docker stop` (SIGTERM,
bounded by `--stop-timeout`), and a `docker run` naming the new tag against the same mounted
folder. Settings, state and data are in the mount, not the image. At start the entrypoint
reconciles `<project>/bin` against the toolset the image stages, comparing a content digest rather
than the release tag; today the staged toolset is empty by policy, so it installs nothing and
touches nothing, and it refuses to replace a `bin/` it did not stamp unless
`VIKE_CONTAINER_ADOPT_BIN=1` says so.

## The runtime tools [#the-runtime-tools]

Two programs a running binary spawns but does not compile ride the release beside the binaries:
the JForex sidecar jar (Dukascopy's only execution path) and the pinned LightGBM CLI with its
`PROVENANCE` file. `vike_model::state_path::PROJECT_BIN_DIR` says where a binary looks —
`<project>/bin/<tool>/` — and a source checkout ships an installer (`just fetch-tools [tag] [tool...]`) that does the same job by hand: it downloads `SHA256SUMS`, refuses any asset the manifest does
not list, verifies before installing, and lands `bin/jforex/jforex-bridge.jar`,
`bin/lightgbm/lightgbm` and `bin/lightgbm/PROVENANCE`. Installing the LightGBM binary without its
`PROVENANCE` produces a tool that is refused at startup, because `vike_ml::cli::LightGbmCli::new`
checks the recorded tag against `vike_ml::pins::PINNED_LIGHTGBM_TAG`. `JFOREX_BRIDGE_JAR` and
`JAVA_HOME` still name a jar or a JVM outright and beat the project rung.

## What a version bump does to the journal [#what-a-version-bump-does-to-the-journal]

If you run with the write-ahead command journal enabled, its on-disk format carries a version.
`crates/vike-core/src/journal/mod.rs` states the contract: this build writes `VERSION` (15 at the
time of writing) and reads or resumes anything in `MIN_READABLE_VERSION..=VERSION` (from 4), so an
older supported journal directory is opened and appended to in place, never rejected — an upgrade
does not cost an operator their live journal. Two things are hard errors: a version below
`MIN_READABLE_VERSION`, a shape this build can no longer parse, and any version *above* `VERSION`,
written by a later build.

The rule that makes the accepted range safe is that a version step may only add a record variant
or a defaulted field. Replay is unaffected: a v4 journal replayed by a v15 binary yields exactly
the record sequence a v4 binary saw. Any step that renames or removes a variant must raise
`MIN_READABLE_VERSION` to `VERSION` in the same commit, which turns a stale journal back into a
loud cold-start error.

<Callout type="warn" title="Downgrading is the direction that refuses">
  A newer build's journal is refused by an older one (`journal format version mismatch`), and the
  refusal is load-bearing: the 14 → 15 step added a defaulted `route_key` field an older build would
  parse without complaint and then misroute, folding a labelled account's balance into the default
  account. Roll a binary back only with the journal it wrote. The journal's home is under
  [The journal](/docs/trader/concepts/journal/).
</Callout>

## Other things a release can move [#other-things-a-release-can-move]

The demo tape carries `DEMO_TAPE_VERSION` in its commit key; a bump makes the next
`backtest --seed-demo` write the new tape alongside the old one rather than silently keeping
stale bars. Program-written state files that changed location migrate on their next write — a read
prefers the state directory and falls back to the legacy path, a write always lands in the state
directory, and the old file is deliberately never deleted (`vike_model::state_path`'s dual read).


# What is Vike Trader? (/docs/trader/getting-started/what-is-vike-trader)



Vike Trader is a trading platform written in Rust. It ships as three surfaces over one core: a
desktop GUI with native charts, a headless daemon for unattended live trading, and a CLI that is
also an MCP server for AI agents. Free. Source-available under FSL-1.1; every release becomes
Apache-2.0 two years on. Every venue connection starts on paper.

## The three surfaces [#the-three-surfaces]

| Surface         | Binary          | What it is for                                                                                                                                                                                                                                                                                                           |
| --------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Desktop GUI     | `vike-desktop`  | egui/wgpu charts over a live feed, order entry, the Studio, venue and credential management. Its default `fat` build carries the local trading core and every venue bridge the mount wires by default — the IBKR, Polymarket and FXCM arms each need their own cargo feature; a `thin` build is the observe-only client. |
| Headless daemon | `vike-tradehub` | Runs a strategy from a TOML profile with no GUI, survives an SSH disconnect, and serves an authenticated observe/control socket that the CLI, the REPL and agents talk to.                                                                                                                                               |
| CLI / MCP       | `vike-cli`      | `backtest` / `sweep` / `walkforward` against a data service, an interactive `trade` REPL over a running node, and `mcp` — a stdio MCP server for any MCP client.                                                                                                                                                         |

Two of them — `vike-desktop` and `vike-tradehub` — are composition roots over the execution core.
`vike-cli` is deliberately not: its manifest links only the light client crates, no concrete
backend, no `vike-backtest`, no engine crate. A `backtest` runs inside `vike-datahub`, the
compute-to-data server that sits next to the history and returns only the report; `trade` and
`mcp` are wire clients to a running `vike-tradehub` node. Where each of these runs, and what it
needs, is on [Where it runs](/docs/trader/getting-started/deployment-targets).

A **Rhai** strategy is the same code in a backtest and on the daemon, by decision rather than
accident: the daemon compiles a script through `vike-script`'s one engine builder and registers no
host function of its own — `crates/vike-tradehub/src/config.rs`'s `resolve_script` states both
halves. What does not carry over is `user_data/indicators/`: `vike-tradehub` never calls
`install_user_indicators`, so a user indicator that resolves under `backtest` is a
function-not-found on the daemon. Compiled strategies are a per-name question instead: the
registry's `LIVE_CAPABLE` ledger records which names would resolve on the daemon and then never
trade, with a written reason for each (a funding reader, for one, because live bars carry no
funding series).

## Fourteen venue bridges [#fourteen-venue-bridges]

Every venue adapter implements one `ExecutionClient` contract: `submit` and `cancel` are required,
everything else has a default, and no order may silently vanish — a dead venue path must
synthesize a terminal rejection. The canonical roster is `vike_model::VENUES`
(`crates/vike-model/src/venues.rs`): binance, bybit, okx, deribit, oanda, ig, fxcm, dukascopy,
polymarket, ibkr, ctrader, alpaca, aster, hyperliquid.

That roster is a contract, not a list. Every per-venue capability table's completeness test
iterates it and asserts a declared row for each entry, so adding a venue fails every table's tests
until its rows land — time-in-force, fees, margin support and the rest are classified or the build
is red. The generated pages under [Venues](/docs/trader/venues/) are rendered from those same tables.

## A backtester you can trust next to live [#a-backtester-you-can-trust-next-to-live]

Backtest fills and paper-exchange fills come from one shared crate, `vike-fills`: one definition
of what a fill costs, when it happens and at what price, extracted verbatim from the backtester so
that a paper executor mounted on a live feed charges exactly what the simulator charges. Costs
(`[engine]`), risk (`[risk]`) and the data slice ride in one run-profile TOML whether you run a
single backtest, a parameter sweep or an anchored walk-forward — the sweep and walk-forward verbs
ship the profile text verbatim so the server honours the whole `[engine]` surface, not a subset.
Start with [Quickstart: first backtest](/docs/trader/getting-started/quickstart-backtest).

## Live reconciliation [#live-reconciliation]

A live session can run the reconciliation engine (`VIKE_RECONCILE=1`): on a schedule, and on
reconnect for the venues wired for it, it fetches the venue's own order, fill and position
reports, diffs them against local state, and resolves divergences under an explicit policy
(`VIKE_RECONCILE_POLICY` — `hybrid`, `synthesize`, `quarantine` or `external-quarantine`). Unset,
it is off and the process is byte-identical to one that never had it. The kinds and the policies
are documented under [Reconciliation](/docs/trader/concepts/reconciliation/).

## A measured latency budget [#a-measured-latency-budget]

The core event hop is covered by a latency gate that runs in CI on a dedicated quiet runner with
reserved cores: `crates/vike-core/tests/runtime_latency.rs`'s baseline harness gates the p99
core-hop tail against `P99_BUDGET_NS`, ten microseconds. It is an assertion on a measured number,
and it is honestly advisory: `main` carries no required status checks, so a red gate reports rather
than blocks, and merging past one is a human decision.

## Paper by default [#paper-by-default]

Two independent gates sit in front of live trading, and both default to closed:

* **Absent credentials are the live gate.** A venue whose keys are not in the credential store
  (`<project>/settings/secrets.env`) mounts as paper. There is no flag that arms a venue without
  keys.
* **A per-venue arming ceiling.** `policy.venues.<venue>` in `<project>/settings/policy.toml`
  (`paper` / `demo` / `live`, default `paper`) is read *before* the credential read and can only
  ever refuse — `vike_config::VenueMode::cap` takes the minimum. A box with no `[venues]` table
  mounts everything paper, whatever the credential store holds.

[Risk and arming](/docs/trader/concepts/risk-and-arming) carries the whole model;
[Arm one venue for demo](/docs/trader/guides/arm-a-venue) is the first time you open either gate.

## Licence [#licence]

Free. Source-available under FSL-1.1; every release becomes Apache-2.0 two years on. The
conversion is per version and rolling — each release starts its own two-year clock, and the
Apache-2.0 grant is irrevocable. Paid support and consulting on Vike Trader are explicitly
permitted; what the licence blocks is selling Vike Trader itself as a competing product or hosted
service. `LICENSE.md` is the whole grant, including the future-licence clause.


# The chart (/docs/trader/gui/chart)



The chart is its own crate. `crates/vike-chart/src/lib.rs` describes what it owns: the GUI-local
render model (an integer bar-index `model::Bar` / `model::ChartState`, fed per core snapshot by the
app), the egui\_plot renderer `chart::draw` with its twenty styles, volume and oscillator sub-panes,
follow-live edge and visible-range y-autofit, the synthetic style transforms, the per-bar order-flow
rendering, and the indicator paint adapter `indicators::Active` over the parity-gated
`vike-indicators` compute core. Its dependency contract is the reason it is testable at all: no
windowing, no GPU layer, no execution core — data arrives as plain `ChartState`s, so the crate rides
the ordinary CI roster while the GUI shell around it is only compile-checked.

## Styles [#styles]

`crates/vike-chart/src/chart/mod.rs`'s `ChartStyle::ALL` lists all twenty in menu order, and
`STYLE_SECTIONS` groups them: **Bars** (Candles, Hollow candles, Heikin Ashi, Volume candles, Bars,
HLC bars, High-low), **Lines** (Line, Line with markers, Step line, Area, Baseline, HLC area,
Columns), **Special** (Renko, Range, Line break, Kagi, Point & Figure) and **Orderflow**
(Footprint). The order is load-bearing — a workspace file persists a style as its index into
`ALL`, so new styles are appended and never inserted.

The five Special styles are close-based, deterministic transforms (`crates/vike-chart/src/transforms.rs`)
that live on an ordinal axis: `t` becomes the unit index while each unit keeps its source bar's
timestamp for approximate labels. `auto_box` derives the default box or reversal size from an ATR
fold and falls back to 0.5% of the last price floored at one price unit, so an instrument priced
under 200 gets a fallback of 1.0. Footprint is different in kind — an alternate per-bar
substrate of buy/sell price cells on the same bar axis, which falls back to plain candles when no
footprint input is present (default off). Where each order-flow study renders is on
[In the GUI](/docs/trader/orderflow/in-the-gui).

## The pane stack [#the-pane-stack]

Below the price pane sit Volume, an optional CVD pane, and one pane per oscillator study.
`crates/vike-chart/src/panes.rs`'s `PaneFractions` gives every pane a persisted, identity-keyed
fraction of the available height: the key is the pane's kind plus the oscillator's stable
`Active::uid`, never its position, so hiding, re-showing or reordering studies never scrambles which
stored share belongs to which pane. `PaneFractions::drag` is the separator: it transfers height
between exactly the two adjacent panes, clamped so neither crosses the minimum. Studies can be
merged into an existing pane or moved to a new one above or below an anchor
(`crates/vike-app-core/src/workspace/state.rs`'s `WinState::move_study`), and the ƒx picker's
"Add to" selector chooses the target at add time.

## Indicators [#indicators]

`crates/vike-chart/src/indicators.rs` re-exports the registry, the picker `Category` axis and the
render-placement axis from `vike-indicators`; only egui colours, visibility and the bar conversion
live in the chart. Each `Active` keeps a persistent streaming instance folded over the closed prefix
only, and `Active::update` does the cheapest correct thing per frame: nothing when the closed series
is unchanged, one `on_bar` when exactly one bar closed, a full refold only on a structural change.
The forming bar is previewed on a throwaway clone. The header carries a measurement worth knowing:
that clone once deep-copied the retained history every frame — at `vwma`'s registry maximum
`period = 400`, 4.6 MB and 1006 µs per frame for one overlay — and is now bounded to a
finite-window kernel that took the same clone to about 7.8 µs. A user-written Rhai indicator is
still the interpreter itself, so its per-frame clone plus one script evaluation is the price of
plotting it.

User indicators from `user_data/indicators/*.rhai` sit in a second registry rather than in the
built-in catalog; `WinState::add_indicator` resolves through `get_any`, so a workspace restores one
by name exactly like a built-in and silently skips a file that has since gone. The picker itself
(`crates/vike-app-core/src/tool_views/fx_picker.rs`) offers search, category tabs, a ★ Favourites
section that is global across windows, a "✎ My indicators" section, and an "On this chart" list with
per-study settings and a foreign source-symbol menu. The catalog is on
[Indicators](/docs/trader/indicators/).

## Scales, follow-live and autofit [#scales-follow-live-and-autofit]

`crates/vike-chart/src/scale.rs`'s `ScaleMode` is the seam between raw price space and what
egui\_plot draws: Linear, Log (strictly positive prices only), Percent, and Indexed to 100; Invert is
an orthogonal flag. `crates/vike-chart/src/chart/controls.rs`'s `y_gutter` documents the right-click
menu on the price axis (Auto / Regular / Logarithmic / Percent / Indexed to 100 / Invert), and
`WinState::scale` notes Alt+L as the toggle hotkey. Every transcendental in `scale.rs` is spelled
through the `libm` crate so a tick step never depends on which platform libm rounded the last bit.

`crates/vike-chart/src/interact.rs`'s `FollowLive` pins the view to the right edge while engaged;
panning or zooming away disengages, and Reset, Auto or panning back re-engages. Its `auto_y` flag is
the visible-range y-autofit: y bounds refit every frame and interactions are x-only while engaged;
a right-gutter drag disengages it, and the price-gutter double-click, the Auto button, a Reset, or a
history reload re-engage it. `crates/vike-chart/src/lod.rs`'s `lod_decimate` collapses a far-zoomed
view to about one min-max OHLC bar per screen column, and returns the visible slice untouched at
normal zoom so the LOD path is byte-identical to the pre-LOD render.

## Settings, compare, studies, sync [#settings-compare-studies-sync]

The chart-settings dialog (`crates/vike-chart/src/chart/dialogs.rs`) is tabbed Symbol / Canvas /
Scales and edits a working copy of `crates/vike-chart/src/options.rs`'s `ChartOptions` — candle,
wick and border colours, the canvas background including a vertical gradient, grid toggles, autofit
margins, the last-price line, a price-precision override and the volume pane — with live preview
until OK commits.

`WinState::compare` overlays other symbols on the price pane as %-normalized lines; a compare
symbol can be moved to its own pane and pinned to its own absolute right axis
(`ScaleAssign::Right`). `crates/vike-chart/src/studies.rs` is the tick-driven twin of `Active`:
VPIN, book imbalance and order-to-trade ratio fold over the live tape and are sampled once per bar
close, carrying the last value through quiet bars; the two book-dependent studies stay empty until a
book snapshot has actually arrived, so no line is fabricated.

`crates/vike-chart/src/sync.rs` keys cross-window sync on timestamps, because bar indices do not
align across symbols or intervals; `WinState::sync_group` (1–4) broadcasts a ghost crosshair and a
sticky-leader visible range across grouped windows. Display timezone is one global setting
(`crates/vike-chart/src/tz.rs`'s `DisplayTz::CURATED`, thirteen zones, default Local).

<Callout type="warn" title="One cache key is trusted by every cache">
  `crates/vike-chart/src/model.rs`'s `cache_key` field doc records the trap: the closed length, first
  and last open-times and timezone identity form one key that y-extent, grid marks, the volume cache,
  the transform cache and the incremental sync all trust. A revised historical bar, or two venues
  aliased onto one `symbol@interval` chart key, changes the interior without changing that key and
  goes stale in every cache at once.
</Callout>


# The cockpit (/docs/trader/gui/cockpit)



The cockpit is the `Polymarket` window kind, and its widgets live in `crates/vike-cockpit/src/lib.rs`:
reusable egui panels for the rolling up/down markets a scalper trades. Like the DOM it is
Rust-native, chart-engine-free and execution-core-free — each widget is a stateless `draw` over
caller-owned view state and borrowed per-frame inputs, returning neutral actions the app maps to its
own commands. Four modules make up the Phase-1 set: `chain`, `header`, `ticket` and `ladder`, each
with a pure, unit-tested core beneath the paint. The wiring around them is
`crates/vike-app-core/src/tool_views/cockpit.rs`.

## The chain rail [#the-chain-rail]

`crates/vike-cockpit/src/chain.rs` states the law the rail is built on: Polymarket's short-horizon
up/down markets are a deterministic chain of fixed-length buckets — each window opens on a
boundary, `open = now - now % window`, and closes `window` seconds later, when the next one takes
over. A scalper trades the current window while watching the next few line up, so the rail shows the
current window plus the next N, each with a live MM:SS countdown, its Up/Down odds and its volume;
the current window's countdown is rendered large and turns red inside the final `URGENT_MS` — ten
seconds. The arithmetic is pure and tested: `window_open_ms` floors with `rem_euclid` so negative
timestamps floor toward −∞, `window_close_ms` is the next open, `chain_windows` returns the current
window plus `n` more, and `fmt_countdown` renders `M:SS` and clamps an already-closed value to
`0:00`. Clicking a card emits `ChainRailAction::SelectWindow`.

The glue fixes the constants: `POLY_WINDOW_SECS` is 300 — the five-minute market — and
`POLY_CHAIN_LOOKAHEAD` shows four future windows. Colour follows Polymarket's language: YES/Up green,
NO/Down red.

## The Price-to-Beat header [#the-price-to-beat-header]

`crates/vike-cockpit/src/header.rs` renders the four numbers a scalper lives off: the reference price
the window opened at (the "price to beat", loudest), the live spot, the signed distance between them
(`ptb_delta` is spot minus reference — positive means Up is winning, green; negative Down, red) and
the time left, plus the current Up/Down odds. It is a readout: `draw` takes only borrowed
`PtbInputs` and paints, and its countdown reuses `chain::fmt_countdown` so every cockpit clock
formats identically.

## The one-click ticket [#the-one-click-ticket]

`crates/vike-cockpit/src/ticket.rs` trades a form for two large BUY UP / BUY DOWN buttons with the
live price on their face, quick-size chips (`SIZE_CHIPS`: +$1, +$5, +$25, +$100, each adding to the
stake) and a fee-inclusive payout preview. `payout_preview` is the pure core: `size / price` shares
each redeem at $1, the net profit is that minus the stake and the fee on winnings, and a degenerate
price or stake yields nothing to win. `FEE_BPS` is 0 today — Polymarket charges none — but the preview
is fee-aware so a future schedule flows through that one site. `TicketState` starts disarmed with a
$1 stake.

<Callout type="warn" title="The arm switch is the button colour">
  The header of `ticket.rs` describes the safety-versus-speed switch: disarmed, the buy buttons are
  muted and inert; armed, they light up and fire. `draw` emits `TicketAction::BuyUp` or `BuyDown`
  only while armed, so the trading mode is unmistakable before a click sends anything.
</Callout>

## The probability ladder [#the-probability-ladder]

`crates/vike-cockpit/src/ladder.rs` is the DOM's sibling adapted to a prediction market. Instead of
an unbounded price grid the rungs are the integer-cent probabilities 1¢ through 99¢ — 0 and 100 are
resolved states, never a live rung. Each rung carries its resting YES-token depth: a bid column
(buying YES, Up, green) on the left and an ask column (selling YES, which is buying NO, Down, red) on
the right. Each side paints a depth bar whose width is proportional to resting size and whose alpha
rises with it — a liquidity heatmap normalised against the peak single-side size over the visible
rungs, so a wall of depth is the widest, brightest rung. Clicking a rung's column rests a limit
there (`ProbLadderAction::PlaceLimit`, the cent as a 0–1 probability); the inline ✕ on your own
marker cancels (`CancelOrder`). The visible window centres on the inside market, or on 50¢ when
neither side is known.

The glue buckets the book onto that ladder: `bucket_prob_levels` sums every level that rounds to the
same cent, drops the resolved ends, and hands the ladder the top 64 levels per side. The YES/NO
quote it derives from the single YES-token book is stated in its own comment: buying YES pays the
best ask, and buying NO is approximately one minus the best bid.

## What the cockpit does not yet source [#what-the-cockpit-does-not-yet-source]

`cockpit_tool_content`'s doc is explicit about neutral inputs. Only the current window's rail card
carries live odds; future windows' odds and every per-window volume stay `None`, because those
markets are not yet resolved and full per-window Gamma resolution is a follow-up, deliberately not a
fetch loop in the render path. The header's reference and spot are fed `0.0`, because no BTC/ETH
spot feed is threaded to the cockpit yet. Selecting a window on the rail emits no core action. The
rail and ladder label is the resolved market name when the background Gamma resolver has cached one
for the token, else the elided token id (`poly_labels::poly_short_label`) — the raw 78-digit id is
unreadable. A book counts as stale after `POLY_STALE_MS`, fifteen seconds, about 7.5× the DOM's two
seconds, because a Polymarket book ticks far less often and a valid quiet market would otherwise
flash STALE.

## Where an order goes [#where-an-order-goes]

Ticket and ladder actions become `CockpitCmd::Submit` — a market taker when `price` is `None`, a
resting limit otherwise, on venue `"polymarket"` — or `CockpitCmd::Cancel`, and drain through the
same `order_dispatch` chokepoint as every other UI order as `SubmitSource::Cockpit`.

<Callout type="warn" title="Polymarket has no testnet">
  `crates/vike-desktop/Cargo.toml`'s `polymarket` feature only makes the live arm compile; what mounts at
  runtime is decided by two environment gates, both off by default — `POLY_EXEC=1` for live execution
  and `POLY_RECONCILE=1` for reconciliation — and its comment says plainly that enabling `POLY_EXEC=1`
  trades real money on a venue that is US-geo-blocked. Without the feature the venue falls through to
  the paper arm. [Polymarket operations](/docs/trader/venues/polymarket-operations) carries the whole
  argument.
</Callout>


# Connections (/docs/trader/gui/connections)



The Connections window is `crates/vike-connections/src/lib.rs`: the venues × Sim/Demo/Live
credential-status grid — which venues have API keys configured in the project's credential store —
plus in-app editing of those keys and a live per-venue connection-status column. `status` is the
pure enumerator, `env_write` the write, and `view` the egui render that `vike-desktop` mounts as the
tool window. The body that wires it is
`crates/vike-app-core/src/tool_views/connections.rs`, which also hosts the remote-backend picker,
editor and settings sections described below.

## The grid [#the-grid]

The row roster is `crates/vike-connections/src/status.rs`'s `VENUES`, which is
`vike_catalog::BRIDGE_VENUES` — one list, so a new bridge appears here without a second edit. For
every venue that follows the generic `{VENUE}_{ENV}_API_KEY` / `_API_SECRET` naming the enumerator
reads through `vike_bridge_core::credentials::load_credentials_from`, the single naming authority;
venues whose bridge reads a bespoke shape get a per-venue override that reads the exact names that
bridge's own loader reads. The header is blunt about why: falling through to the generic grid is a
claim, and when it is false the grid disagrees with the mount in both directions — a green dot
beside a venue `vike_mount::make_engine` will leave on paper, and no dot beside one it will arm.
Alpaca, cTrader, IBKR and Polymarket each sat in that fallback once while reading none of those
names.

The store is re-read fresh by the binary every frame the tool is visible; the body's doc calls a
per-frame parse of a small file cheap, and it is what keeps the grid live after a save or an
external edit.

The **Status** column is the runtime counterpart. `crates/vike-model/src/feed_status.rs`'s
`parse_feed_status` classifies each bridge feed's own status string into `ConnectionState` —
`Unknown`, `Disconnected`, `Connecting`, `Connected` or `Error` — in a fixed order: disconnected
first, then the error family, then the connected family, then the connecting family. The map the
app passes covers every streaming feed (binance, bybit, okx, aster, hyperliquid, polymarket); a
venue with no live producer yet — deribit, the FX and broker venues — is absent and always renders
`Unknown`, never guessed. It is the same classifier the status strip's dot and the headless daemon's
health gate read.

## The editor, and the one write it makes [#the-editor-and-the-one-write-it-makes]

`crates/vike-connections/src/view.rs` lists the non-negotiables. An existing secret's plaintext is
never read back into the UI — edit fields are `egui::TextEdit::password` and start empty, and the
dot is the only feedback that something is configured. Only non-empty fields are written; an empty
field means leave unchanged. No secret value is ever passed to a log — only the venue and tier.

Save goes through `crates/vike-connections/src/env_write.rs`'s `save_credentials_journalled`: the
store write is `vike_secrets::save_credentials`, whose `upsert_env` transform
(`crates/vike-secrets/src/env_write.rs`) replaces matching `KEY=value` lines in place, appends
keys that were absent, preserves every comment, blank line and their order verbatim, and lands the
result atomically by temp file and rename. That module's header names the rule it enforces: nothing
may regenerate, reorder or clobber the store, because it is the user's only copy of live venue keys.
The journalled wrapper then appends a `credential_write` record to the change journal — key names
only, and it cannot record a value because `Change::credential_write` has no parameter for one. The
store write happens first and its error is returned; a journal failure is logged at `error` and
never fails a write that landed.

<Callout type="warn" title="One walk decides where Save lands">
  `CredentialHome::resolve` derives both the store path and the journal from the boot's own
  `settings_dir` and `state_dir`. Its doc records why: the Save arm used to find the store by a
  `$VIKE_SETTINGS_DIR`-blind walk while the grid rendered from a read that honoured the override, so on
  a deployment naming its settings directory the editor showed one project's keys and Save wrote
  another project's file, silently. See [Settings](/docs/trader/concepts/settings).
</Callout>

## Accounts [#accounts]

A venue may hold more than one account, and `account_strip` in `view.rs` puts that dimension in a
selector above the grid rather than as more rows or more columns, so the table's shape is constant
in the number of accounts and a box with one account renders exactly the panel that shipped. The
default account is always offered first. **Add account** takes a label and writes nothing — an
account comes into existence when its first credential is saved, which is the rule the read side
already obeys. There is deliberately no Remove: it could only be implemented by deleting lines from
the store, so the panel renders an instruction naming the file instead. Every key name is composed
through `vike_model::account_keys::account_key`, which appends `__{LABEL}` after the whole of
today's key and returns the default account's names unchanged; [Accounts](/docs/trader/concepts/accounts)
carries the grammar.

Arming a venue is not done here. The Data Manager's Venues tab shows each venue's mode, credentials
and effective arming and carries the switch — see [Data Manager](/docs/trader/gui/data-manager) and
[Risk and arming](/docs/trader/concepts/risk-and-arming).

## Backends [#backends]

Below the grid sits the remote-backend picker. `crates/vike-app-core/src/backend_registry.rs` keeps
`backends.json` beside the workspace file: one `BackendRecord` per daemon with a display name, a
dial address, and the credential-store **key names** of its observe and control keys — never key
material, because a GUI-written JSON file would be a second, ungated copy of a live key, and a name
is auditable by eye against `vike-cli secrets list` where a value is auditable by nothing. The
address is the daemon's dial address, not `config.tradehub_addr`, which is its bind address. Each
record's `control` flag is a per-backend arming gate: with it false, or no control key named,
`resolve_keys` never yields a control key. Rows render with an Active marker and one
Connect/Disconnect button; clicking the active row disconnects, any other row connects, and
`switching_available` makes the buttons inert while a local trading core runs.

`crates/vike-app-core/src/backend_editor.rs` adds Add, Edit and an are-you-sure Delete. Validation
runs before the save so a hostile name is refused visibly rather than silently renamed; deleting the
active backend disconnects first; editing it takes effect on the next connect. `key_presence` is a
read-only membership check of the typed name against the credentials map — present or absent, never
a value.

The **Backend settings** section (`crates/vike-app-core/src/tool_views/backend_settings.rs`) fetches
the active daemon's effective settings rows over the wire and lets an operator edit them; a
`policy.toml` row's Save stays disabled until the exact dotted key has been typed into a confirm box
that is never pre-filled, the daemon enforces the same rule server-side, and an accepted write
answers restart-required — the running backend keeps its boot-time values until restarted. Against a
daemon that predates the verb, the section says so. How the observer connects at all is on
[Observe mode](/docs/trader/gui/observe-mode).


# The DOM ladder (/docs/trader/gui/dom-ladder)



The DOM lives in `crates/vike-panels/src/dom.rs`, whose header calls it the "Pro" click-trade
ladder plus the "Elite" order-flow surface — a time×price liquidity heatmap strip — switchable in the
window header. It is Rust-native (the Python app it descends from had no DOM), and it is pure egui
painting over `vike_model::L2Book` with no dependency on the execution core: `draw` is a stateless
render over caller-owned `DomState` and borrowed `DomInputs`, and every trader intent leaves as a
neutral `DomAction` the app maps to a `vike_exec::Command`. The same data-in, actions-out seam the
chart uses.

## The interaction grammar [#the-interaction-grammar]

The header states it: click-to-trade is **side-bound**. The column decides the side — Buy/Bid on the
left, Sell/Ask on the right — and the row decides the price. Limit versus stop resolves by side of
market: a buy above the ask or a sell below the bid would cross, so it becomes a stop, and holding
`Shift` forces a stop regardless (`resolve_is_stop`). Clicking your own resting order cancels it;
dragging it reprices it and emits `DomAction::Modify`. The footer carries Close and Reverse plus
cancel-side buttons. `DomAction` is the complete vocabulary: `Place`, `Modify`, `Cancel`,
`CancelSide`, `CancelAll`, `ClosePosition` and `Reverse`.

The toolbar exposes quantity presets (`QTY_PRESETS`: 0.001, 0.005, 0.01, 0.05, 0.1 — BTC-scale
defaults), a price-grouping selector in ticks (`GROUP_STEPS`: 1, 2, 5, 10, 25, 50), recenter, and a
reduce-only arm. `DomState::default` starts in Pro mode on Binance at qty 0.01, grouping 1.

## What the ladder is showing [#what-the-ladder-is-showing]

`DomVenue` cycles Binance → Bybit → OKX → Aster → Hyperliquid in the header. The glue in
`crates/vike-app-core/src/tool_views/dom.rs` renders the live L2 book for the selected venue,
folded in `data_sink::BookStore`, and paints a synthetic stand-in
(`crates/vike-app-core/src/dom_math.rs`'s `synth_book`, seeded by `default_price` and `tick_for`)
only until the first real snapshot lands. Working orders and the position are projected per venue
from the published snapshot — orders filtered to the window's venue and instrument, the position
from that venue's block — and `signed_position_size` resolves direction the venue-correct way:
hedge-mode perps carry it in the `LONG`/`SHORT` string, one-way and paper positions in the sign of
the size. Reading the string alone once made every short render as a long with inverted P/L and
made Close/Reverse pick the wrong side.

The ladder centres on the live book's mid rather than on the last trade, so real depth stays in view
even when the last-trade mark lags a few ticks; scrolling latches a manual centre. Depth bars scale
against the peak grouped quantity over the visible rows, the last-trade row is amber, and the
position's average price gets a marker.

<Callout type="warn" title="The header badge is where a click's order actually goes">
  `header` paints `PAPER` in amber or `● LIVE` in red — in the source's own words, "where a click's
  order actually goes." The glue sets `paper` to the inverse of the window's `live` flag, which is true
  only when the selected venue has a credential-gated live execution client. A `● STALE` badge appears
  and the ladder dims when no book update has arrived inside the freshness window, so a frozen book
  never reads as live.
</Callout>

## Capabilities, not post-hoc rejects [#capabilities-not-post-hoc-rejects]

`DomInputs::caps` carries the selected venue's declared adapter capabilities, filled by the app from
`vike_model::caps_for`. The widget consults `caps.allows_modify()` at drag-start, at the drop and at
the marker affordance, so a venue with no native modify never offers drag-to-reprice instead of
letting it become a reject after the fact; an unknown venue resolves to `VenueCaps::UNSUPPORTED`,
which offers nothing. The per-venue table this reads is described on [Venues](/docs/trader/venues/).

## Elite: the liquidity heatmap [#elite-the-liquidity-heatmap]

In Elite mode the region splits — the heatmap strip takes the left 42% and the ladder the rest,
sharing row geometry. `DomHeatmap` is a fixed-capacity ring buffer of per-row intensity columns
(180 columns by default), pushed on a throttled cadence — every sixth repaint — and normalised
against a running peak. The header describes it as the modest, egui-painter form of the surface: O(rows)
per push, rendered as rectangles, with a GPU or texture upgrade left as a later, feature-gated
change that would read the same ring buffer.

## Cost to fill [#cost-to-fill]

`DomState::cost_to_fill` is an opt-in footer readout, off by default so the render path is unchanged:
for a hypothetical market order of `cost_qty` (which follows the toolbar quantity unless set) it
walks both sides of the displayed book and shows the projected average fill and slippage versus mid.
`cost_to_fill` is `L2Book::simulate_fill` verbatim — the same walk `vike_exec::impact_veto` performs
— so the basis points a trader reads here are the ones a `max_slippage_bps` gate compares to its
budget. `cost_label` states the two known divergences: an incomplete walk renders `∞` where the
slippage would go (the displayed book cannot cover the size, and the gate rejects exactly that case
as not fillable), and the gate rounds size to the venue lot grid while the readout walks the size as
typed. A one-sided book shows no slippage number rather than a fabricated zero.

## What happens after the click [#what-happens-after-the-click]

Every `DomAction` drains through `crates/vike-app-core/src/order_dispatch.rs`, the one place a UI
intent becomes a command. A `Place` is `SubmitSource::Dom` and a Close or Reverse is
`SubmitSource::DomExit`; both go through `Planner::admit`, the one chokepoint where the local
preview runs before anything reaches the command lane. What that preview can measure differs by
shape: a priced `Place` is capped on notional, computed with the instrument's contract multiplier
so the UI measures the same quantity `RiskGate` does; a Close or Reverse is a market leg carrying
no price, so no notional is measured for it at all and only the qty bounds apply.
`OrderIntent::Modify` — the drag-to-reprice — is a declared residual: it carries only the order id
and the new price, so it is not capped, and the exemption is named in an exhaustive classification
test rather than left implicit. The venue-side `RiskGate` remains the authority either way; see
[Risk and arming](/docs/trader/concepts/risk-and-arming) and [The trade panel](/docs/trader/gui/trade-panel)
for the rest of that chokepoint.


# The desktop app (/docs/trader/gui)



`vike-desktop` is the desktop face of Vike Trader: a native egui multi-window shell in which every
window carries its own title toolbar — a chart-style menu, symbol and interval dropdowns, a LIVE
badge, and clone / minimize / maximize controls. This page is written from
`crates/vike-desktop/src/main.rs`'s module header, `crates/vike-desktop/Cargo.toml`'s `[features]` table
and `crates/vike-app-core/src/lib.rs`, which together say what the app is made of and why it is
split the way it is.

## One snapshot, many windows [#one-snapshot-many-windows]

The GUI never touches trading state directly. `crates/vike-desktop/src/main.rs`'s header states the
data path: market data flows from feed threads into the core's ingest, the core owns the bar cache,
and it publishes an arc-swapped `CoreSnapshot` that the GUI converts into its render model
whenever the snapshot changes. In the header's own words, the GUI "is a lossy observer; it never
touches the core's state directly." Every panel below — the chart, the DOM ladder, the trade
panel, the Polymarket cockpit — reads that snapshot and hands its intents back as neutral actions
that the frame loop turns into commands. The single-writer core behind it is described in
[The execution core](/docs/trader/concepts/execution-core).

## The window kinds [#the-window-kinds]

`crates/vike-app-core/src/workspace/state.rs`'s `WinKind` is the roster: `Chart`, `Trade`,
`Dom`, `Options`, `Greeks`, `News`, `Calendar`, `Data` (labelled "Data Manager"), `Studio`,
`Connections`, `Tearsheet` and `Polymarket`. `WinKind::ALL` holds all twelve; `WinKind::LAUNCHERS`
is the nine-entry launcher row (Chart, Trade, DOM, Options, Greeks, News, Calendar, Data,
Tearsheet). Each kind carries an icon, a per-tool accent colour, and a stable lowercase slug that
is the `VIKE_TOOL` QA vocabulary — `from_slug` resolves over `ALL`, so the two directions cannot
disagree.

<Cards>
  <Card title="The chart" href="/docs/trader/gui/chart" description="Twenty styles, panes, indicators, scale modes and cross-window sync." />

  <Card title="The DOM ladder" href="/docs/trader/gui/dom-ladder" description="Side-bound click-to-trade depth and the Elite liquidity heatmap." />

  <Card title="The cockpit" href="/docs/trader/gui/cockpit" description="The rolling-window rail and probability ladder for Polymarket up/down markets." />

  <Card title="The trade panel" href="/docs/trader/gui/trade-panel" description="Order entry, sizing and the one dispatch chokepoint every UI order crosses." />

  <Card title="Connections" href="/docs/trader/gui/connections" description="Credential status per venue, the masked editor, and remote backends." />

  <Card title="Observe mode" href="/docs/trader/gui/observe-mode" description="--observe against a headless daemon, and the thin build that can only observe." />

  <Card title="Workspaces" href="/docs/trader/gui/workspace" description="Arrange, persist and restore the window layout; named layouts." />

  <Card title="The options chain" href="/docs/trader/gui/options-chain" description="The chain grid, greeks and the options books." />
</Cards>

The Studio IDE and the Data Manager are large enough to have their own sections:
[Studio](/docs/trader/gui/studio) and [Data Manager](/docs/trader/gui/data-manager).

## What the tool windows fetch [#what-the-tool-windows-fetch]

`crates/vike-app-core/src/tools.rs`'s header names the sources: News reads Cointelegraph RSS,
Calendar reads ForexFactory's weekly JSON, and Options reads vike-deribit's chain provider (BTC,
ETH and SOL book summaries). Two calendar fetches need a third-party key — `ToolApiKeys` carries
`FINNHUB_API_KEY` for the weekly earnings calendar and `FMP_API_KEY` for dividends — and the
module reads neither the environment nor the credential store itself: the app root resolves both
once at startup and hands them in, so a key added afterwards needs a restart.

The bottom status strip carries two dots. `crates/vike-app-core/src/status_dot.rs` decides their
colours: the feed dot is classified by `vike_model::feed_status::parse_feed_status`, the same
parser the Connections tool and the headless daemon's health gate read, and the control dot takes a
plain `bool` from the control handle rather than recovering one from a rendered string.

## Two builds [#two-builds]

`crates/vike-desktop/Cargo.toml` declares **no `[features]` table**. It used to carry a `fat`
default — the local trading core reached through `vike_run::build_node` and the fourteen venue
bridges, DataFusion-backed tick recording, the Studio's local store arm and bulk backfill — and a
`thin` alias for its absence. `fat` was deleted with the local core, so `vike-mount`,
`vike-run` and `vike-backfill` stand in the manifest as tombstone comments and there is
nothing extra to turn on. Which of the three arms a launch composes is decided by
`crates/vike-app-core/src/split_plane.rs`'s `app_mode`, and [Observe mode](/docs/trader/gui/observe-mode)
covers all three.

<Callout title="The window opens maximized and frameless">
  `main.rs` builds the native window with `with_maximized(true)` and `with_decorations(false)` — the
  app paints its own caption. A fixed size with no position once let the OS drop the frameless window
  partly off-screen on smaller displays. The OS title reads `Vike Trader — OBSERVING <addr>` on every
  run, not just under `--observe`: `startup_backend` has no "not connected" rung, so the address
  always resolves and `window_title`'s `— live` arm is unreachable.
</Callout>

## Why two crates [#why-two-crates]

`crates/vike-app-core/src/lib.rs` is the eframe-free, wgpu-free logic extracted from `vike-desktop` so
it runs in CI. `crates/vike-ops/tests/ci_excluded_gui_shell_ratchet.rs`'s header states the split
precisely: `vike-desktop` is compiled once and clippy-gated, but the only tests that
execute inside it are the pure-logic byte-layout pins in `crates/vike-desktop/src/chart_gpu.rs`;
everything else in `main.rs` is type-checked and then never run, because the crate sits outside the
derived CI roster. Several of its modules arrived after a bug that shipped for exactly that reason:
`core_sync` carries four silent-data-loss fixes that existed only as code comments because nothing
compiled the file they lived in, `order_dispatch` closed a real hole where only three of five submit
paths validated and the Trade window had no local notional cap at all, `fonts` had every candidate
font path naming Windows, and `window_spawn` found six hand copies of the cascade arithmetic with
two already drifted apart. Others — the workspace shell, the tool bodies in `tool_views`, the
startup layout, the observe bridge — moved down so that code no gate compiled would finally be
compiled, clippied and tested; the rest is simply newer work authored here rather than in the shell.
The size of the unexecuted half is ratcheted by that same file, which fails a PR that grows it.

Two tool bodies still live in `main.rs`: `crates/vike-app-core/src/tool_views/mod.rs`'s header
says Options keeps its modal and poll-thread wake channel there, and Studio needs the
feature.


# Observe mode (/docs/trader/gui/observe-mode)



`vike-desktop --observe <ADDR>` names the node to watch: the app connects to a headless
`vike-tradehub` daemon's observe server instead of spawning a local trading core. The scan is in
`crates/vike-desktop/src/main.rs` — the argument after `--observe` is the address — and everything it
feeds is in `crates/vike-app-core`, where it is tested. This page is written from
`crates/vike-app-core/src/split_plane.rs`, `backend_conn.rs`, `observe_bridge.rs`,
`tradehub_control.rs`, and `crates/vike-desktop/Cargo.toml`.

## One mode, and two the library still declares [#one-mode-and-two-the-library-still-declares]

`split_plane.rs`'s `app_mode` maps the pair (fat build?, `--observe` given?) to what `App::new`
composes, and it still declares three arms:

| build | `--observe` | mode                                                           |
| ----- | ----------- | -------------------------------------------------------------- |
| fat   | no          | `LocalCore` — local trading core plus local venue feeds        |
| fat   | yes         | `ObserveWithFeeds` — a remote account plane beside local feeds |
| thin  | yes         | `ObserveOnly` — the feed-less observer                         |
| thin  | no          | refused before `App::new`                                      |

⚠ &#x2A;*The shipped binary reaches exactly one of them.** `crates/vike-desktop/src/main.rs` calls
`app_mode(false, …)` — the first argument is a literal `false`, because the crate declares no
features and the `fat` resolution that set it was deleted with the local core. So every launch
composes `ObserveOnly`, and the two upper rows are library surface nothing in the release can
select. They are listed because the enum is still there and a reader of the source will meet them.

The module doc divides the client's data into two planes with different owners. The **account
plane** — orders, positions, equity, kline history — belongs to the backend and arrives as wire
snapshots over the observe bridge. The **market-data plane** — DOM books, the trade tape, tick,
volume and order-flow series — belongs to the venue and is subscribed directly and keylessly. The
`ObserveWithFeeds` would run both in one process — a remote daemon's account plane beside local
venue feeds, with no local core — and `LOCAL_FEED_VENUES` is the one written copy of that feed set
(binance, bybit, okx, aster, hyperliquid, polymarket). The arm the release composes, `ObserveOnly`,
mounts no feeds at all: the venue bridges are not in this binary's dependency graph.

## What the one build links [#what-the-one-build-links]

`crates/vike-desktop/Cargo.toml` declares **no `[features]` table**. `vike-mount` and `vike-run`
stand in it as a tombstone comment rather than as dependencies, so there is no venue→engine
composition root to reach; `vike-data` is taken with default features, which is the `HistStore`
trait and nothing behind it, so no DataFusion enters the tree. The manifest's own verification line
is `cargo tree -p vike-desktop -i datafusion`, which must report the crate unreachable. The one
venue crate that does link is `vike-deribit`, an unconditional edge through the options-chain
provider.

It links the Studio and drives it remote-only: with a datahub address resolved —
`config.datahub_addr`, else the connected backend's own advertisement — it opens a
`RemoteHistStore`; with neither it shows a "Studio: no data store" label naming both fixes.
CI's `app-check` job compiles the crate once, because there is one configuration to compile.

## Which daemon a launch dials [#which-daemon-a-launch-dials]

`backend_conn.rs`'s `startup_backend` is the ladder, and it has no "not connected" rung. A
non-blank `--observe` flag is an override and becomes the synthetic `cli_observe_record`, whose
observe key is the credential-store name `VIKE_TRADEHUB_OBSERVE_KEY`, whose control key is
`VIKE_TRADEHUB_CONTROL_KEY`, and which is armed — so on the CLI path the process-level master gate is
the only gate, exactly as before the registry existed. Otherwise the registry's active record is
used as itself, because that record is the only place its key names live. Otherwise the local
default `DEFAULT_OBSERVE_ADDR`. The doc records why the app no longer exits without a flag: a
viewer that opens and says "not connected" in its status bar is strictly better than one that closed
on a typo, since nothing in it can place an order. `config.tradehub_addr` is deliberately not a
rung — that is the daemon's bind address, which a client cannot dial. Backends are added and picked
in [Connections](/docs/trader/gui/connections).

## The bridge [#the-bridge]

`observe_bridge.rs` is the reverse bridge: each pushed `WireSnapshot` is republished into the
GUI's arc-swap cell as a `CoreSnapshot`, so every DOM, Trade and portfolio panel renders the remote
daemon's live state unchanged. Charts render too — the daemon ships a bounded bar tail, about 300
closed bars plus the forming candle per mounted series, which `wire_to_core` rebuilds into the bar
cache. `spawn_bridge` connects inside its own thread so window startup never blocks, and re-dials on
a dropped link with a two-second backoff sliced into 50 ms checks so a stop lands promptly. The
status line tracks each phase and ends `OBSERVING <addr> (connected)`, led by the daemon's identity
once a frame carries one — `name [LIVE]` in uppercase for a live daemon, `name [paper]` otherwise —
and the OS window title reads `Vike Trader — OBSERVING <addr>`.

<Callout title="An unknown order status renders as Rejected">
  `map_order_status` decodes the wire's rendered status string and falls back, with a warning, to the
  terminal `Rejected` for anything it does not recognise — so an unknown status can never render as
  live or actionable. `crates/vike-app-core/src/observe_bridge.rs`'s module doc records that before
  the exhaustive round-trip test existed, a newly added status variant did exactly that, silently.
</Callout>

`build_portfolio` maps the wire's cross-venue totals but sets `capital_base` to `0.0`, meaning
unknown, because the wire carries no seed and inventing one would let the drawdown curve read as a
real capital base on the observe path.

## The control channel [#the-control-channel]

Observing is read-only by default. `observe_bridge.rs`'s `connect_control` builds a second,
dedicated connection under `Scope::Control` only when two things hold: `VIKE_TRADEHUB_CONTROL=1` —
the exact string `"1"`, read off the real process environment by
`tradehub_control::control_enabled` — and a non-blank control key. When it connects, the GUI's
order buttons drive the remote core, and the function's doc says it outright: this can place and
cancel real orders on the daemon. A missing key logs a warning and the observer stays read-only. For
a registry record the per-backend `control` gate is an additional AND, so a record file flipping
`control = true` is never sufficient on its own.

<Callout type="warn" title="The status strip paints the armed segment amber">
  `main.rs`'s status bar renders the control summary in a loud amber to flag that this observer can
  drive real orders, with a red dot when the control link is down, and a latched server error is
  click-to-dismiss. The trade panel routes to the snapshot's own market — under observe, the remote
  daemon's venue and symbol — and refuses with `NoRoutableMarket` before the first frame arrives
  rather than misrouting.
</Callout>

`tradehub_control::wire_from_command` lowers a live-core command into the wire vocabulary and is
deliberately partial: submit, cancel, modify, mass-cancel, flatten, market-exit, trading-state and
the strategy live-params re-tune have a wire form; brackets, batches, conditionals, combos, margin
changes, reconcile plumbing and shutdown yield `None` and are logged and dropped. The handshake
underneath — an HMAC-SHA256 nonce challenge bound to the scope, so an observe key can never forge a
control handshake — is on [The node protocol](/docs/trader/concepts/node-protocol); the daemon side is
[vike-tradehub](/docs/trader/reference/binaries/vike-tradehub).

## Switching at runtime [#switching-at-runtime]

`backend_conn.rs`'s `switch_backend` replaces the whole connection and performs the backend-session
clear its doc calls safety-critical: the old bridge is stopped and joined, session-owned render state
is reset and an empty snapshot published, so backend A's data never paints under backend B's
connection, while the local feed plane survives the switch. `switching_available` answers false
while a local core runs, so that path is byte-identical to before switching existed.


# The options chain (/docs/trader/gui/options-chain)



Two tool windows carry options in Vike Trader: **Options**, the chain grid, and **Greeks**, the
position ledger priced off it (`WinKind::Options` and `WinKind::Greeks` in
`crates/vike-app-core/src/workspace/state.rs`). `vike-options` is the venue-free pure core, with
its own [concept page](/docs/trader/concepts/options); `crates/bridges/deribit/src/chain.rs` fetches the
venue's book; `crates/vike-chart/src/options_chain.rs` owns only the paint; and two pure modules in
`vike-app-core`, `options_books.rs` and `options_greeks.rs`, fold the trader's own state onto the
chain — pure so CI's tests execute them, which nothing in the GUI shell's `main.rs` is.

## The grid [#the-grid]

`crates/vike-chart/src/options_chain.rs` paints the mirrored **CALLS | Strike · IV | PUTS** ladder:
nine fields a side, the ATM row marked by an accent rule, an expiry strip above. The field set is
`vike_options::columns::CHAIN_FIELDS`, ordered centre-to-outer on the puts side and reversed for
calls so the table mirrors around the spine: Volume, Distance, Rel dist, Bid, Ask, Spread, Theor,
Bid %, Ask %. Every value comes from `columns::cell_value` and every string from `columns::fmt`.
**Theor** is a Black–Scholes price from the quote's own implied vol at a risk-free rate of zero. A
missing input renders as a dash — the column model treats a zero spot or a zero mark as
not-available, never as zero.

Three pills drive the view. The **underlying** selector offers whichever of BTC, ETH and SOL
fetched, in that order; switching clears an expiry selection the new bundle lacks
(`crates/vike-app-core/src/tools.rs`'s `resolve_options_selection` — the file every fetch-side
symbol below lives in), so a switch never shows an empty grid. The **expiry strip** labels
each contract `02 Jul`, or `0DTE` for the one settling today (`vike_options::make_expiry&#x60; counts
calendar days). The **±N strikes** pill cycles `STRIKE_WINDOW_PRESETS` — 6, 12, 20, 30 — and
`strike_window_range` keeps the window balanced: the same count each side of ATM, capped to the
shorter side, so a near expiry short of far-OTM strikes never renders lopsided.

## Where the numbers come from [#where-the-numbers-come-from]

The chain is Deribit's public REST `get_book_summary_by_currency` — no API key, one call per
currency's whole book, behind a 5 s cache (`crates/bridges/deribit/src/chain.rs`'s
`CACHE_TTL_MS`). BTC and ETH have coin-settled books
whose premiums are scaled to USD by the underlying price; SOL lives on the shared USDC book, already
in dollars, and passes through unscaled (`is_usd_quoted`). Each refresh takes the nearest
**8 expiries*&#x2A; per underlying and fetches every chain **±30 strikes** wide, the widest preset, so the
±N pill trims what is already held and never re-fetches (`fetch_underlying`). The poll repeats every
**12 s** (`OPT_POLL_SECS`: 12 s × 3 underlyings, 5 s-cached, ≈ 15 REST calls a minute); the
**Refresh** pill wakes it at once, and a burst of clicks coalesces into one refetch. An underlying
that fails a pass keeps its last-good bundle; the status reads `options error: …` only when nothing
fetched. `VIKE_RECORD_CHAINS=1`, off by default, records every polled chain as a `kind=chain`
snapshot (`options_provider`).

Between polls, two keyless WebSocket feeds from `crates/bridges/deribit/src/options_feed.rs` keep
the grid live. `markprice.options.{btc_usd,eth_usd,sol_usdc}` pushes mark and IV for every listed
option, and `apply_markprice_to_chains` re-derives the greeks from each fresh IV.
`ticker.{instrument}.100ms` streams top-of-book for a fixed focus set — the front expiry's ATM ±10
strikes of BTC and ETH, subscribed once on the first successful poll
(`front_expiry_focus_instruments`). The REST poll backstops chain structure, open interest, volume,
and the bid/ask of every strike outside that focus set.

## Trading from the chain [#trading-from-the-chain]

A **Bid** or **Ask** cell is clickable only when its quote carries both a venue `instrument_name`
and that price (`quote_order`): an ask click buys, a bid click sells, and the click opens a
**confirm ticket** while submitting nothing (`OptionChainActions::order`). The ticket is prefilled
with instrument, side and price, defaults the quantity to 0.1, and lets both be edited before
**Confirm Buy** / **Confirm Sell** or **Cancel** (`OptOrderTicket`). Only a confirmed ticket
reaches `plan_options` in `crates/vike-app-core/src/order_dispatch.rs`, which builds a `deribit`
limit order and admits it through `admit(SubmitSource::Options, …)` — the gate every window's order
passes, so the local cap and the [venue-side checks](/docs/trader/concepts/risk-and-arming) apply as they
do to the [trade panel](/docs/trader/gui/trade-panel).

The trader's own state is painted back onto the ladder. `build_books` in
`crates/vike-app-core/src/options_books.rs` folds every live (non-terminal) Deribit order and every
Deribit position in the core snapshot into an `InstrumentBook` keyed by instrument name; other
venues are ignored, and a strike with neither gets no entry. The position badge is the net signed
size across the instrument's legs (`dom_math::signed_position_size`) — a green `+2` or a red `-1`.
Working orders show as a `○N` marker whose click cancels the **first** resting order, repeated to
peel them off one at a time, routed to `OrderIntent::Cancel` as the
[DOM ladder](/docs/trader/gui/dom-ladder) routes its own.

<Callout type="warn" title="The chain you look at and the book you trade on are different hosts">
  Every public read in the Deribit bridge — the chain and both feeds — is hardcoded to mainnet
  `www.deribit.com`; every authed socket, the order transport included, is hardcoded to testnet. A
  ticket confirmed off the real book lands on a different book on a different host, and
  `crates/bridges/deribit/src/exec.rs`'s header is explicit that demo credentials route the TESTNET
  order and user-data endpoints, and it names no mainnet execution path at all.
</Callout>

<Callout type="warn" title="Cancel is a silent success for an order this process did not submit">
  `crates/bridges/deribit/src/client.rs`'s `cancel_order` resolves the venue id through an in-memory
  map owned by one client, and a miss returns `Ok(())`. A `○N` marker for an order placed before a restart or discovered by reconcile
  reports a cancel that did nothing.
</Callout>

## The Greeks window [#the-greeks-window]

**Greeks** is read-only (`crates/vike-app-core/src/tool_views/greeks.rs`). It takes the snapshot's
Deribit positions and prices them off the chains the Options window already fetched, through
`position_greeks` in `crates/vike-app-core/src/options_greeks.rs`, at r = 0 to match the chain's
own enrichment: the underlying's spot and the option's IV are looked up in the loaded chain,
`vike_options::black_scholes_greeks` prices one contract, and the result is scaled by the signed
quantity — a long put carries −Δ, a short flips every sign. The table is Instrument, Qty, Avg Px,
Delta, Gamma, Vega, Theta, with a NET row over the priced positions; Δ is per 1.0 of underlying,
Γ per 1.0², Θ per calendar day, ν per one vol-point.

That NET row is a naive per-unit sum, meaningful within one underlying only — a 1-delta BTC option
and a 1-delta ETH option are wildly different dollar exposures. The line beneath it, **NET Δ ·
USD**, is the dimensionally correct aggregate (`PortfolioNetGreeks`): each option leg's delta
scaled by its underlying spot, per underlying and as a total. Perp and future legs join it as delta
only, folded as the venue-reported `coin_delta × spot` — a Deribit perp's `qty` is USD notional,
not coin, so the fold never re-derives exposure from it — and contribute nothing to Γ, ν or Θ.

<Callout title="An unpriced position is listed, never dropped">
  A position whose expiry is not among the eight fetched, whose strike falls outside the ±30 fetched
  window, or whose chain has no spot or IV yet shows `—` in every greek, stays in the table, and is
  named beneath the totals in `net_usd.unpriced` — as is a perp or future with no venue coin delta or
  no loaded spot. The net is flagged incomplete; nothing is folded as a guess.
</Callout>


# The trade panel (/docs/trader/gui/trade-panel)



The Trade window is `crates/vike-app-core/src/tool_views/trade.rs`: the cross-venue equity hero,
the per-venue Accounts table, the focused trade card — order ticket plus sizing, leverage and TP/SL
— and the working-orders table. Its header notes why it moved out of the GUI shell: the four decision
helpers the render code used to inline are now named, pure functions with unit tests, which is the
point of the move for a crate that has no executed tests of its own. The layout is responsive —
two columns when at least 620 px wide, accounts and orders left and the trade card right, stacked
with the card first when narrower — and the composed width is capped at 960 px so a maximized window
does not stretch the tables across the screen.

## What it shows [#what-it-shows]

The hero renders the big cross-venue `equity_total`, a P\&L chip, an unpriced-positions badge, and a
Realized / Fees / Funding strip, plus Margin used when it is non-zero. The numbers come from
`crates/vike-app-core/src/equity_panel.rs`'s `EquityPanelModel::from_snapshot` — one `EquityRow` per
venue block in snapshot order, with a short mode tag: `Δ` for a delta-tracked balance, `auth` for an
authoritative one. `hero_totals` sums the rows as plain naive folds in row order, matching every
other display sum in the panel.

The Accounts table lists Venue · mode · Equity · uPnL · Fees · Funding with right-aligned tabular
numbers; a venue with positions that carry no mark source gets a warning badge whose hover text
(`unpriced_tooltip`) names those symbols. A per-asset balances line follows when the snapshot carries
one. The Orders table shows Side · Qty · Type · Status and an inline ✕ on every order that is still
working; `is_terminal_status` fixes the set that gets no cancel button — FILLED, CANCELED, REJECTED,
DENIED, EXPIRED, LIQUIDATED.

## The trade card [#the-trade-card]

The card header carries the snapshot's symbol, the mark on the right, and the core's fault line if
one is latched. The position line reads LONG or SHORT with size, average price and unrealized P\&L,
and adds the leverage and estimated liquidation price when both are known; otherwise it reads Flat.

The ticket has a margin-mode pill (Isolated / Cross) and a leverage pill that opens a 1–125 slider.
Changing leverage does more than relabel: it emits `Command::SetMargin` with an initial-margin
requirement of `1 / leverage` for the snapshot's venue and symbol, so the gate and the liquidation
estimate update truthfully. Order-type tabs are Market, Limit (with a Price field) and Stop (with a
Trigger field). BUY and SELL are enabled only when the resolved quantity is positive, the type's price
or trigger is present, and the core reports no fault. A **Flatten position** button appears whenever
a position is open and submits a reduce-only market order for the full size on the closing side.

### Sizing [#sizing]

`crates/vike-app-core/src/trade_sizing.rs` is the pure sizing math, and `SizeMode` is the segmented
control above the size field: **Qty** is base units; **Amount** is the position's quote value, so
`qty = input / mark`; **Cost** is the margin the trader commits, so `qty = input × leverage / mark`.
All three modes are always offered, spot or perp. A derived line under the field shows the conversion
— the notional for Qty, the base quantity and margin for the other two — and the presets 25%, 50%,
75% and Max write `pct_to_qty` of free buying power into the field and switch it to Qty mode. Free
buying power is the primary venue block's `free_bp`, which the margin engine computes; the Cost /
Max readout under the buttons prints `margin_cost` and `max_qty` for the current inputs.

## From a click to a command [#from-a-click-to-a-command]

A click fills `crates/vike-app-core/src/tools.rs`'s `TradeSubmit`: side, quantity, reduce-only,
the order kind, an optional limit price or stop trigger, and optional take-profit and stop-loss
prices. Its doc states the bracket rule: when both `tp` and `sl` are set on an entry, the app
dispatches an `OrderIntent::Bracket` — an OTO entry with OCO exits — instead of a plain order.

Every UI order then passes `crates/vike-app-core/src/order_dispatch.rs`'s `plan_dispatch`, which is
pure: the frame's drained intents, the order limits and the snapshot in; commands and rejects out.
Inside it, `Planner::admit` is the chokepoint for a single order and `admit_bracket` for a bracket,
and both always validate. The bracket path validates the three legs the runtime will actually build
(`vike_model::build_bracket`: OTO entry, OCO stop-loss, OCO take-profit, all at the entry quantity)
and refuses atomically if any leg fails — which is also how a market-entry bracket gets a notional
cap through its priced take-profit leg. The module's header records the hole this closed: of five
submit paths only three validated, and the Trade window — the panel a human types into — had no
local notional cap at all, nor did its bracket sub-path.

<Callout type="warn" title="The preview cap is a preview, not the risk authority">
  `crates/vike-app-core/src/order_entry.rs`'s `validate_with_multiplier` runs local checks only: finite
  quantity and prices, a strictly positive quantity within the caps, a price on every limit, and
  `|qty| × |price| × |multiplier| ≤ max_notional`. The multiplier comes from
  `CoreSnapshot::multiplier_of`, so options and inverse perps are measured the way the venue-side
  `RiskGate` measures them — the plain `validate` assumes 1.0 and under-measures them. Market orders
  carry no price, so their notional is not checked here at all; the venue-side gate owns that. See
  [Risk and arming](/docs/trader/concepts/risk-and-arming).
</Callout>

The ceiling itself arrives as a value: `OrderLimits::with_max_notional` takes
`max_notional_per_order` from `policy.toml`, resolved once by the binary, and ignores a non-finite or
non-positive number rather than turning it into a silent halt. Its doc records that the value used
to come from `VIKE_MAX_ORDER_NOTIONAL` — a ceiling any exported variable could raise — and that a
process which still finds that variable set refuses to start; the key is on
[policy.toml](/docs/trader/reference/settings/policy).

The trade path routes to the snapshot's own `(venue, symbol)`, never a literal. That is identical
in a local build, whose primary engine is what the snapshot publishes, and it is exactly what an
[observe-mode](/docs/trader/gui/observe-mode) client with control enabled needs — the header describes
the panel showing one market while the BUY button submitted another before this changed. A snapshot
with empty strings, the placeholder before an observer's first frame, is an explicit
`NoRoutableMarket` reject. A plain ticket the preview refuses still consumes its client-order id,
as the original sites did — a bracket and an unroutable ticket consume none. The id spelling is
`ui-<n>-<shot>` for this window, though the working-orders table never displays it — the table
reads the id only to address a cancel click. What happens to the order after the command lane is
[Order lifecycle](/docs/trader/concepts/order-lifecycle).


# Workspaces (/docs/trader/gui/workspace)



The desktop workspace is `crates/vike-app-core/src/workspace/mod.rs`: multi-window management,
arrangement and layout persistence, split by concern into `state` (per-window state and the window
chrome loop), `arrange` (cascade, tile, grid, maximize and restore), `persist` (the chart layout as
JSON), `menu` (the menu bar, command emission only) and `rail` (the left rail of minimized windows).
It is egui-only and free of app content — tool-window view state lives elsewhere — which is what let
it move out of the GUI shell into a crate CI tests.

## Windows [#windows]

`crates/vike-app-core/src/workspace/state.rs` says how a window behaves: each is a floating
`egui::Window`, egui owns the live geometry so the user can drag and resize, and the app reads the
rectangle back each frame. An arrange or maximize action forces geometry for a single frame through
`pending` and then releases it. A freshly opened or restored window is pinned to its intended size
for `OPEN_PIN_FRAMES` — eight frames — because an unpinned window would otherwise auto-shrink to
its content over the first few frames. `WinKind` names the twelve kinds and `WinKind::LAUNCHERS`
the nine in the launcher row; [The desktop app](/docs/trader/gui/) lists them.

`WinState` carries window chrome plus chart content: symbol, interval, the data venue the live bar
feed subscribes to (`DEFAULT_VENUE` is `"binance"`, the value that keeps every pre-feature path
byte-identical), the picked instrument's asset class for feed routing, style, indicators, scale,
invert, chart options, pane fractions, the sync group, the order-flow toggles and the compare
series. The chart key it builds, `series_key`, spells a non-Binance series as `venue:SYMBOL@interval`
and a Binance one bare. Build that key by hand and drop the venue, and every non-Binance series
lands in the Binance-shaped slot — which is why `series_key` exists as one function rather than a
format string repeated at each call site.

Tool-window view state is deliberately not in `WinState`. `crates/vike-app-core/src/tools.rs`'s
`ToolView` is the per-window state for the tool windows (selection, filters, page, expiry, the
order-ticket out-slots), owned by the app keyed by window id and taken out of the map around each
draw; `ToolData` is the fetch-thread-owned data behind News, Calendar and Options.

## Arrange, menu, rail [#arrange-menu-rail]

`crates/vike-app-core/src/workspace/arrange.rs`'s `Arrange` offers Cascade, TileH, TileV, Grid,
MinimizeAll and RestoreAll, plus per-window maximize and restore. Its naming is explicit: Tile
Horizontal is full-width rows stacked vertically; Tile Vertical is full-height columns side by side.
Arranging never draws — it writes one-frame `pending` rectangles that the window loop consumes next
frame.

`crates/vike-app-core/src/workspace/menu.rs` is pure command emission: `menu_bar` returns a
`MenuResult` of the actions chosen this frame and the app applies them. File holds New chart window,
Open and Save Workspace, Save layout as…, the Load layout and Delete layout submenus, Export chart
image… and Exit; View holds Timezone; Window holds the six arrange actions and Toggle left panel.
`crates/vike-app-core/src/workspace/rail.rs` draws the left rail as vertical tabs, one per minimized
window, sized to their rotated text; clicking a tab restores its window. New windows land in a
cascade slot decided by `crates/vike-app-core/src/window_spawn.rs`, which also builds the window's
state and names the live subscriptions it needs before it can paint.

## What is persisted [#what-is-persisted]

`crates/vike-app-core/src/workspace/persist.rs` captures chart windows only. Its header lists the
scope: symbol, interval, style, geometry, minimized and maximized state, follow-live flags, the
price-scale mode, the flattened `ChartOptions`, the per-pane heights, and per-indicator parameters
and per-line colour and width. `WinSnap` also carries the venue, the asset class, the invert flag,
pane membership and order, the sync group, the CVD, profile and tick-size order-flow settings, and
the compare series with their panes and axis pins. Tool windows are launcher-recreatable and carry
runtime state, so they are skipped. `Workspace` adds the globals: the display timezone, the
order-flow backfill hours (default 2.0), the GPU candle-layer toggle (default off) and the indicator
favourites.

The file is `$VIKE_WORKSPACE`, else `<state_dir>/workspace.json`, where the state directory is
`VIKE_STATE_ROOT` or the project's `settings/state`. It is loaded automatically at startup when
present — skipped under `VIKE_SHOT` so QA captures stay deterministic — and written only by an
explicit File → Save Workspace. `save_path` returns an error, never a different location, when no
state directory resolves, and the caller surfaces it: a save that silently landed elsewhere would be
found by nothing.

<Callout title="A corrupt or old file never bricks startup">
  `load_from` treats an unparseable file as "no saved workspace" with a warning and falls back to the
  default layout. `VERSION` is 2 and a v1 file still loads: `ChartOptions` is flattened with a
  struct-level default, so every colour and flag absent from an old file takes its custom default
  rather than a type-zero, and every later field is `#[serde(default)]`. Pane keys written under the
  old `Osc` spelling are accepted through a serde alias, because a parse error on one entry would
  reset the whole saved workspace.
</Callout>

## Named layouts [#named-layouts]

The single `workspace.json` stays the default, auto-loaded layout. Any number of named layouts can be
saved as `layouts/<name>.json` beside it — same schema, same forward-compatibility — driven by
`save_layout`, `load_layout`, `delete_layout` and `list_layouts`. `sanitize_layout_name` maps a
user-entered name to a safe filename stem (alphanumerics, dash, underscore and space survive;
everything else becomes an underscore), and the stem is the displayed name. `last_layout.txt`
remembers the layout last loaded or saved-as so a restart can reopen it; a stale pointer to a
deleted layout is ignored. `base_dir` is one base for the layouts directory, the pointer file and
the backend registry's `backends.json`, so the family can never half-move when `$VIKE_WORKSPACE`
relocates it.

Which windows a fresh launch opens is `crates/vike-app-core/src/startup.rs`'s `plan`: a restored
workspace (a named layout is preferred over `workspace.json` when one was last active), one of the
QA capture tool windows, or the default BTCUSDT chart — and, for each, which feeds must be ensured
before it can paint.


# Arm one venue for demo (/docs/trader/guides/arm-a-venue)



By default nothing on the box trades anything real. Getting one venue onto its own demo account is
two edits in two files, in a fixed order: a **ceiling** in `policy.toml` naming which venues this
deployment means to trade, and **credentials** in the store deciding whether the venue can reach that
tier. The ceiling is read first, which is the usual reason a store full of keys still mounts paper.

## 1. Write the ceiling [#1-write-the-ceiling]

`crates/vike-mount/src/lib.rs`'s `make_engine` is the composition root, and its header states the
order: the deployment's per-venue arming ceiling — `policy.venues.<venue>` — is consulted first, and
"a `paper` venue returns the paper client having loaded no credential, fetched no instrument grid and
opened no socket". Only then does the older rule apply, absent-credentials-is-the-live-gate.

```toml
# <project>/settings/policy.toml
[venues]
binance = "demo"
```

The three tiers are `paper < demo < live` (`crates/vike-config/src/venue_mode.rs`'s `VenueMode`),
declared in ascending risk order so the `Ord` derive follows the declaration rather than a comment.
`demo` is "the venue's own demo/testnet/sandbox account — real wire, real rejections, no real funds".

<Callout type="warn" title="A ceiling only ever refuses">
  The fold is `VenueMode::cap`, and its module doc is emphatic: `min(mode, whatever the existing
  mechanisms decide)` — &#x2A;*never `max`**. A `venues.bybit = "live"` line does not put bybit live; it
  "declines to stop bybit going live if its credentials, its `{VENUE}_MAINNET` flag and its mount arm
  all already say so". Arming still takes the credentials. The ceiling can only take them away.
</Callout>

The default is a filled map, one `paper` row per roster venue, not an empty one: the safest answer
for a machine with no `policy.toml`. `Policy` is also the one settings type with no environment layer
at all — it implements neither `EnvOverride` nor `CliOverride`, both sealed, so
`policy.apply_env(&env)` does not fail a review, it fails to compile
(`crates/vike-config/src/policy.rs`). See [Settings](/docs/trader/concepts/settings).

If your box already had credentials and has never written a `[venues]` table, the first mount prints
a paste-ready block naming every venue that has credentials and is now paper
(`crates/vike-mount/src/paper_fallback.rs`'s `venue_arming_migration_message`, latched to fire once
per process). Writing the table at all silences it, whatever the values — including all `paper`,
"which is a decision like any other".

## 2. Put the demo keys in the one store [#2-put-the-demo-keys-in-the-one-store]

There is one file and no precedence:

```text
<project>/settings/secrets.env
```

`crates/vike-secrets/src/lib.rs` is the authority — "point at the file, edit the file". `<project>`
is resolved at runtime by walking up for a project marker, and `VIKE_SETTINGS_DIR` names the
`settings` directory outright — the level holding `secrets.env`, not `<project>` above it. Ask the
binary rather than guessing:

```sh
vike-cli secrets path       # where it resolved for THIS invocation, and its exposure
vike-cli secrets template   # the key grid, empty values, to stdout
vike-cli secrets list       # key NAMES only, never a value
```

`vike-cli secrets` is read-only by construction, and `template` has deliberately no `--out` flag:
"the moment this command owns a path it can truncate a live store"
(`crates/vike-cli/src/cmd/secrets.rs`). Creating the file is your editor's job; redirect the template
into it yourself.

The names are `{VENUE}_{SIM|DEMO|LIVE}_API_KEY` / `_API_SECRET` / `_API_PASSPHRASE`, composed from
`vike_model::credential_keys`' suffix and tier tables rather than spelled at each call site. FX
venues have bespoke shapes, and more than one account per venue appends `__{LABEL}` after the whole
of today's key — see [Accounts](/docs/trader/concepts/accounts).

<Callout type="warn" title="Required is per-venue, and OKX is the reason">
  key + secret is the required set for binance, bybit and deribit; OKX additionally requires
  `_API_PASSPHRASE`, because its signer sends one on every request. A store with two of the three
  resolves `None` and the venue stays paper exactly like an unconfigured one — the correct outcome and
  an invisible one, which is why `crates/vike-bridge-core/src/credentials.rs`'s
  `missing_required_passphrase` names the missing variable out loud at the mount.
</Callout>

Absent credentials **are** the live gate: no store means an empty map, every venue loader returns
`None`, every venue stays paper. A store that exists and cannot be read is the opposite case and
errors, because "not configured" and "cannot open" must never look the same to an operator.

## 3. Check before you start [#3-check-before-you-start]

```sh
vike-cli config check
```

`crates/vike-cli/src/cmd/config_check.rs` resolves the same directory through the same loader as
`config show` and hands back an exit code, so it can sit in a unit's `ExecStartPre=`. Its levels are
arguments, not tuned severities: an **absent** store is `ok` (that is the live gate), a
`VIKE_SETTINGS_DIR` naming a non-directory is a failure (set-but-unhonoured), and an unreadable store
is a warning that becomes a failure only on a box armed for live.

## Why it is still paper [#why-it-is-still-paper]

`crates/vike-config/src/venue_arming.rs`'s `ArmingBlock&#x60; exists to answer exactly the complaint &#x2A;"I
set live and it is still paper"*, one observable cause per variant with a distinct response:
`Disarmed` (the ceiling), `NoCredentials` (the store), `FeatureAbsent` (this binary has no arm — the
`ibkr`, `polymarket` and `fxcm` features), `MainnetSwitchUnset` (`{VENUE}_MAINNET` is a conjunct of a
`live` ceiling, never a replacement for it), `LiveOnlyArm` (Polymarket runs no testnet) and
`SdkAbsent` (FXCM without its linked SDK).

<Callout type="warn" title="Do not arm mainnet from the credential file">
  `crates/vike-config/src/arming.rs` refuses startup when a `{VENUE}_MAINNET` line in `secrets.env`
  carries the arming value — the exact string `1`, after a trailing `#` comment is stripped and
  whitespace trimmed; `0`, empty and `true` arm nothing at any reader and are ignored rather than
  refused. The file is `KEY=value`, last wins, and an append needs no read permission — so a line
  nobody re-reads could flip a venue from demo to mainnet. Refusing rather than ignoring is
  deliberate: an operator who wrote the line believes they are on mainnet, and a build that quietly
  traded demo would have them reading demo fills as real ones.
</Callout>

With the ceiling written and demo keys in place, the mount takes the venue to its demo tier. What the
venue can then do is its own generated page under [venues](/docs/trader/venues); what a first live order
is checked against before it leaves is [startup preflight](/docs/trader/concepts/startup-preflight) and
[risk and arming](/docs/trader/concepts/risk-and-arming).


# Connect an agent (/docs/trader/guides/connect-an-agent)



`vike-cli mcp` is a local stdio MCP server that exposes Vike's agent surface as tools: an agent
can author and validate a Rhai strategy, run backtests, sweeps and walk-forwards against a data
service, read a running trading node's live state, and — gated behind a mandatory preview —
place and manage orders on it. The client-side preview is UX; the node's own limits and the
core risk gate are what actually enforce.

This page is the Trader-side summary. [Build with AI](/docs/ai) is the same server documented as an MCP
surface — [Client setup](/docs/ai/trader/setup) per client (Vike's remote data server is a separate
entry the same client can hold at the same time; it is set up on
[Data client setup](/docs/ai/data/setup)), and [Trader tools](/docs/ai/trader) tool by tool.

## Add the server [#add-the-server]

`vike-cli mcp` speaks MCP's stdio transport (newline-delimited JSON-RPC 2.0), so any MCP client
can launch it directly. Two optional flags scope what the tools can reach:

* `--addr <host:port>` — the `vike-datahub` server the backtest tools use (default
  `127.0.0.1:7878`),
* `--node <host:port>` — the running `vike-tradehub` node the trade tools observe and control
  (no default; without it the create+backtest tools still work, `node_snapshot` returns a clean
  error, and a write tool still previews — what errors is a call that passes the gate, carrying
  both `confirm: true` and a valid `preview_token`, and finds no node to send to).

Two more decide which tools the session has at all, and they belong in the same entry:

* `--profile full|read-only|offline` — the default is `full`, all seventeen. `read-only` serves the
  ten read tools and withholds the seven order-write ones; `offline` serves only the four that open
  no socket. A withheld tool is absent from `tools/list` as well as refused if called, because the
  advertised roster and the routing gate are two complements of one pass over the registry
  (`ToolAccess::new`, `crates/vike-cli/src/cmd/mcp.rs`) rather than two lists that can disagree.
* `--deny-tool <name>` — withhold one more by name, repeatable.

An unknown value for either is a usage error naming the valid set and never widens to `full`. Only
whoever edits the launch command can change the scope; the agent cannot, and the refusal it gets
says so instead of sending it hunting for a switch.

**Claude Code:**

```sh
claude mcp add vike -- vike-cli mcp --node 127.0.0.1:7879
```

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "vike": {
      "command": "vike-cli",
      "args": ["mcp", "--node", "127.0.0.1:7879"]
    }
  }
}
```

### Node keys [#node-keys]

The node tools authenticate with two HMAC keys, resolved from the process environment first and
then from the same credential store the daemon reads (`<project>/settings/secrets.env`):

* `VIKE_TRADEHUB_OBSERVE_KEY` — reads (`node_snapshot`),
* `VIKE_TRADEHUB_CONTROL_KEY` — writes (the seven tools below, `set_trading_state` included).

If a key is in neither place, the affected tools return an error naming both locations
(`vike-cli secrets path` prints where the store resolves; `vike-cli secrets list` shows key
names, never values).

## Verify it works [#verify-it-works]

Ask Claude:

> show me the node snapshot

That calls the read-only `node_snapshot&#x60; tool and returns the node's live state — orders,
positions, per-venue equity, recent events. With no node configured you can still verify the
offline half: &#x2A;"list the vike strategy templates"* calls `list_templates` with no server at
all.

## The 17 tools [#the-17-tools]

**Read-only** (safe, `readOnlyHint`):

| Tool                | What it does                                                        | Needs                  |
| ------------------- | ------------------------------------------------------------------- | ---------------------- |
| `validate_strategy` | Compile a Rhai strategy — compile *is* validation                   | nothing (offline)      |
| `discover_params`   | List a script's tunable `param(name, default)` knobs                | nothing (offline)      |
| `list_templates`    | Starter Rhai strategies as `{name, code}`                           | nothing (offline)      |
| `list_indicators`   | The host-bound *built-in* roster; never your `user_data/indicators` | nothing (offline)      |
| `run_backtest`      | Run a profile TOML on the datahub, return the report                | `--addr` reachable     |
| `run_sweep`         | Parameter-grid sweep, server-ranked                                 | `--addr` reachable     |
| `run_walk_forward`  | Anchored out-of-sample walk-forward                                 | `--addr` reachable     |
| `list_strategies`   | The compiled native strategies the server offers                    | `--addr` reachable     |
| `list_series`       | Every stored data series, with coverage                             | `--addr` reachable     |
| `node_snapshot`     | Live node state: orders, positions, equity, events                  | `--node` + observe key |

**Order-write** (`destructiveHint`, all preview-gated, all need `--node` + the control key):
`submit_order`, `cancel_order`, `modify`, `flatten`, `market_exit`, `mass_cancel`,
`set_trading_state`. This is the full write-verb roster of the human `trade` REPL — both
surfaces build commands through the same construction site (`crate::cmd::verbs`), so the two
can never drift.

## A worked flow [#a-worked-flow]

A typical create-and-test session, tool by tool:

1. **`list_templates`** — start from a shipped starter (SMA cross, RSI reversion, Donchian
   breakout), each parameterized via `param()`. Read the body before trusting the name: the
   Donchian starter is a *shape*, not the indicator — it stands in with `sma`, because a bare
   `donchian(...)` is not bound: its first output line is `upper` rather than the namesake, so only
   the per-line accessors (`donchian_upper()` and its siblings) are callable.
2. **`validate_strategy`** — compile the edited script. A bad script is an `ok: false` answer
   with the compiler error, not a tool failure — the agent reads it and fixes the script.
3. **`run_backtest`** — ship a profile TOML (the agent can inline the script via the `script`
   argument) and read the returned report JSON.
4. **`run_sweep`** — the same profile with a `[sweep]` table; the server returns the ranked
   grid, best first. Follow with `run_walk_forward` before believing a search.

## The safety model [#the-safety-model]

Stated from the source, because an agent with order-writing tools deserves an exact contract:

* **Paper by default, twice over.** A venue with no credentials in
  `<project>/settings/secrets.env` mounts as paper — absent credentials *are* the live gate —
  and the per-venue ceiling `policy.venues.<venue>` in `policy.toml` defaults to `paper` and can
  only ever refuse: the fold that applies it is a minimum, never a maximum
  (`crates/vike-config/src/venue_mode.rs`'s `VenueMode::cap`), so a `live` line arms nothing by
  itself. Nothing an MCP tool does can arm a venue.
* **Mandatory preview on every write, and the confirm needs a token.** A write executes only on a
  call carrying **both** `confirm: true` **and** the `preview_token` an earlier preview of that
  same command returned. Anything less previews: it returns the fully resolved wire command, a
  client-side guardrail check, the rationale that would be recorded, and a fresh token. This is not
  convention — it is the code path: in `crates/vike-cli/src/cmd/mcp.rs`, `Server::call_tool` reads
  `confirm` as exactly the JSON boolean `true` (the *string* `"true"` previews too) and looks the
  token up in `PendingPreviews`, which fires it once, expires it after 60 seconds and binds it to
  the command it previewed. ⚠ A confirming call with **no** token is the dangerous shape, because
  it is not an error: it returns another preview, `will_execute: false`, `isError: false`. Read
  `will_execute`, never the absence of an error. A preview is also not necessarily offline — with
  `--node` set and a control key present it dials the node for a dry-run verdict
  (`Server::node_preview`); what it never does is send the command. And the gate is not the only
  answer available: `--profile read-only` in the launch command above hands the agent a server whose
  `tools/list` does not contain a write tool at all, which is the right shape when the session's job
  is to read and report.
* **The node is the enforcing gate, not the client.** The preview's guardrail (the local
  `policy.toml` notional ceiling) is advisory UX. What enforces is server-side on the
  `vike-tradehub` node — `crates/vike-tradehub/src/server.rs`'s `ControlLimits::vet`, a
  per-connection rate token bucket plus the notional cap built from `ControlLimitsConfig`, whose
  ceiling comes from the *node's* `policy.toml` (`max_notional_per_order`) — and, beneath it, the
  execution core's `RiskGate`. An agent cannot loosen either from the client side. The two have
  different reach: the rate token is spent on *every* command, while the notional cap only judges
  order-increasing verbs that carry a price (`submit_order`, `modify`) — a `flatten` or
  `mass_cancel` is rate-limited but never size-checked, which is the right way round for commands
  that only reduce exposure.
* **Every order carries a client order id.** The node refuses a remote submit with an empty
  `client_order_id`, so the local MCP server mints one before the preview renders
  (`crates/vike-cli/src/cmd/verbs.rs`'s `fill_client_order_id` — the same generator and wire form
  the live core uses). The agent does not have to carry that id back: a confirming call executes
  the **stored** command rather than the one it rebuilt, so the id that reaches the venue is the id
  the preview displayed — which is also why `same_intent` ignores exactly this field when it binds
  a token to its command. `client_order_id` in the accepted response is always the authoritative
  id. The node's registry is coid-keyed but does not dedupe: a repeated id re-sends the order and
  replaces its registry row.
* **Honest outcomes, per command.** Each write tool reports the fate of *its own* command:
  `accepted`, a named refusal, or — on a timeout or dropped connection — an explicit *unknown*
  telling the agent to check `node_snapshot` **before** retrying, because the command may have
  executed. There is no shared error latch that could misattribute an old refusal to a new
  command.
* **A recorded "why".** Every write tool takes an optional `reason` string — the agent's
  rationale. It is echoed in the preview, sanitized server-side, and lands in the node's audit
  trail; it never reaches the order, the core, or a venue. The sanitizer is `sanitize_reason` in
  `crates/vike-tradehub/src/audit.rs`: every Unicode control character is stripped, the text is
  capped at 512 characters (`MAX_REASON_CHARS`), and a result that comes back empty is recorded as
  no rationale at all.
* **A record of what was *attempted*, if you ask for it.** The node's trail holds accepted commands
  only, so a refusal reaches it never — it was refused before a byte left the MCP process. Launch
  the server with `--trace` and it appends one JSONL entry per tool call under
  `<project>/settings/state/agent/`: the tool, the profile, the arguments and a verdict of `ok`,
  `preview`, `refused` or `error` (`crates/vike-cli/src/cmd/mcp_trace.rs`). It is off unless the
  flag is given, and it records no secret — credential-shaped argument keys, and credential-shaped
  SHOUTING\_CASE identifiers inside string values, are both redacted — and, for a gated write, the preview token's
  identity rather than its bytes.

<Callout type="warn" title="market_exit is the panic button">
  `market_exit` cancels every live order and then flattens every *net* position (optionally scoped
  to one venue; a hedge-mode long/short leg has no net bucket and is skipped). It is preview-gated
  like every other write, but treat it as the incident tool it is.
</Callout>


# Guides (/docs/trader/guides)



Nine pages, each named for a task rather than a subject. Where the [concepts](/docs/trader/concepts)
explain how something works and the [tutorials](/docs/trader/tutorials) walk a worked example end to end,
these answer "I need to do this now" — the steps, the gates in the way, and what it looks like when
it went right.

## Before anything reaches a real account [#before-anything-reaches-a-real-account]

<Cards>
  <Card title="Arm one venue for demo" href="/docs/trader/guides/arm-a-venue" description="Two gates stand between a credential and a live socket, and the ceiling is the one consulted first." />

  <Card title="Stop, liquidate, restart" href="/docs/trader/guides/stop-liquidate-restart" description="What a stop leaves at the venue, what the kill switch does and in which order, and what a restarted node does and does not recover." />

  <Card title="Triage a stuck order" href="/docs/trader/guides/triage-a-stuck-order" description="The confirm-grace ladder, what a venue confirm can return, and which reconciliation divergence you are actually looking at." />
</Cards>

## Running it [#running-it]

<Cards>
  <Card title="Record a live feed" href="/docs/trader/guides/record-a-feed" description="One TOML profile, one daemon, and a tape of the markets you actually watched — plus the two watchdogs that notice when it goes quiet." />

  <Card title="Replay a recorded session" href="/docs/trader/guides/replay-a-session" description="Two different replays: a market tape through the backtest engine, and a command journal through the real core." />

  <Card title="Run a sweep on the data service" href="/docs/trader/guides/sweep-on-the-service" description="Ship a profile to the box that holds the history, run the grid next to the data, and get back only the ranked result." />

  <Card title="Read a backtest report" href="/docs/trader/guides/read-a-report" description="Every row of the summary table, what the annualization factor actually is, and why a flat run prints what it prints." />
</Cards>

## Driving it from somewhere else [#driving-it-from-somewhere-else]

<Cards>
  <Card title="Connect an agent" href="/docs/trader/guides/connect-an-agent" description="Point an assistant at the MCP server: tools to author strategies, run backtests, watch a live node — and, behind a preview gate, place orders." />

  <Card title="Control the daemon from Telegram" href="/docs/trader/guides/telegram-control" description="A second remote write surface, off at compile time, behind four gates and a mandatory confirmation." />
</Cards>

<Callout type="warn" title="Two of these can move real money">
  Arming a venue and connecting a write-capable control surface are the two places where a mistake
  reaches an account rather than a log. Both pages lead with what stops that, and both are worth
  reading through once before following.
</Callout>


# Read a backtest report (/docs/trader/guides/read-a-report)



A finished backtest prints one flat summary. `crates/vike-analytics/src/report.rs`'s
`BacktestReport` is that struct, and its first property is what makes the numbers trustworthy: **it
does no metric maths of its own**. Every field is a direct pass-through from the run result or a
single call into `metrics::`, so a divergence here is a wiring bug rather than a maths bug — and a
test asserts the whole struct field-for-field against calling `metrics::` directly on the same
inputs.

## The table, row by row [#the-table-row-by-row]

The shape, with the precision each row is actually formatted at (values here are illustrative):

```text
name:          my-run
final_equity:  10412.77
total_return:  4.1277%
n_trades:      37
win_rate:      54.0541%
sharpe:        1.2043
max_drawdown:  6.8100%
per_symbol_pnl: (none)
```

* **`total_return`** — the fractional return from the first to the last equity-curve point.
* **`win_rate`** — the fraction of trades with positive PnL.
* **`sharpe`** — the annualized Sharpe of per-bar or per-tick returns. The annualization factor is
  the subject of the next section, and it is the row most often misread.
* **`max_drawdown`** — the largest peak-to-trough drop, as a positive fraction of the peak.
* **`per_symbol_pnl`** — populated on multi-symbol event runs, empty for single-symbol and vector
  runs.

Two fields are in the struct and conditional in the table. &#x2A;*`funding_paid`*&#x2A; is the net perp funding
cashflow over the run, received-positive and paid-negative, and prints only when it is nonzero, so a
spot report is byte-identical to one from before the field existed. &#x2A;*`profit_factor`** — gross
profit over gross loss — is deliberately *not* printed at all: the human table's row set predates it,
and the field exists for ranking objectives and JSON consumers. It carries a house sentinel:
`INFINITY` when there are no losing trades but some profit, `0.0` when there is neither, serialized
as JSON `null` when non-finite so a `--json` consumer sees an explicit "no meaningful ratio" rather
than a number.

The struct is deliberately compact — it is the `backtest` binary's human table, its `--json` schema,
and the sweep's ranking source, not an everything-drawer. A caller wanting the long-form catalogue
composes this for the shared fields and adds its own from `metrics::`.

## The Sharpe scale is derived, not matched [#the-sharpe-scale-is-derived-not-matched]

`crates/vike-backtest/src/harness/report.rs`'s `periods_per_year` is the single source of truth for
the annualization factor, so the single-run binary and a sweep rank the same profile on the same
scale. It is **derived from the interval**: daily bars anchor at 252, and every other interval scales
off that by how many fit in a day, `252 · (86_400_000 / interval_ms)`. So `1h` gives 6,048 and `1m`
gives 362,880.

<Callout type="warn" title="This used to return 252 for everything">
  A one-minute run was annualized as though its bars were daily — 1,440 bars per day counted as one —
  which understated every intraday Sharpe by a factor of about **37.9** (`sqrt(1440)`), silently,
  because the number still looked like a Sharpe. It also made `--rank-by sharpe` incoherent across a
  sweep whose points differ in interval. The daily anchor is preserved exactly, so no existing daily
  report moved by a single bit.
</Callout>

Two limits are stated rather than hidden. The 252 anchor is the equity convention of 252 trading
days, and these markets trade 24/7, so a defensible crypto anchor is 365 — changing it would move
every existing daily report, which is a separate decision from fixing the intraday scale. And a tick
profile keeps the default factor, because a tick stream has no fixed period and there is no honest
observation count to derive.

## When the run did nothing [#when-the-run-did-nothing]

A run that closed zero trades **and** whose equity never moved off the starting cash prints a ranked
diagnosis in place of the bare all-zero table — "total return 0%, Sharpe NaN, max drawdown 0%" says
nothing about why. `crates/vike-analytics/src/zero_trade.rs`'s `ZeroTradeReport::analyze` composes it
purely from diagnostic counters the engine already accumulated: the gate-drop channel (the risk gate,
the cash gate, a volume cap, a latency reject), stale-price wait deferrals, session-gate skips, the
strategy's warm-up requirement, and the raw step count. Each cause carries a stable kebab-case code —
`no-data`, `warmup-shortfall`, `orders-denied`, `stale-price`, `session-closed`, `no-orders` — a
headline and an actionable detail, ordered most-probable first, and the list is never empty because a
catch-all `no-orders` is emitted when nothing more specific applies.

It is inert by construction: `analyze` returns nothing for any run that closed a trade **or** moved
equity, which is also why an open-and-hold position — zero closed trades, but a real marked position —
is deliberately not flagged. Its equity curve moved. See
[sizing and zero-trade diagnosis](/docs/trader/analytics/sizing-and-zero-trade).

## The live tearsheet is a different tool [#the-live-tearsheet-is-a-different-tool]

`tearsheet` looks like the same report and is not: it renders **a live session's command journal**,
not a backtest. It reads the journal segment directory (`--journal DIR`, or `VIKE_JOURNAL_DIR`),
reconstructs closed round-trips through the shared cost-basis primitive, and computes the standard
performance tearsheet — bit-for-bit identical to a backtest over the same fills, which is exactly the
property the shared report struct buys: it lives outside the backtest crate's feature gate so
`LiveTearsheet` composes it for the fields they share, and the two cannot drift apart.

<Callout type="warn" title="Two flags decide whether its returns mean anything">
  `--seed CASH` (default 10000) sets the base of the realized-only equity curve, so it scales total
  return, CAGR and Sharpe — pass the session's real starting equity or those numbers are arithmetic
  about the wrong denominator. And that curve is realized-per-trade rather than a fixed calendar
  cadence, so `--periods-per-year` (default 252) makes every annualized ratio approximate.
</Callout>

`--html PATH` additionally writes a self-contained HTML tearsheet — metrics table, inline-SVG equity
and underwater-drawdown charts, and a monthly-returns table when the timestamps allow — leaving the
terminal output unchanged. With `--store DIR` on a build carrying the `hist` feature, two enrichments
replace the bare realized-only view: the equity curve is read from the store's `kind=equity` series
(the cross-venue account rollup lives under `venue="portfolio"`, `symbol="TOTAL"`), giving a true
mark-to-market curve with a stderr note and a fallback when no such series exists, and each trade's
MAE/MFE is back-filled from OHLC bars over the trade window.

Where a run's files land is [runs on disk](/docs/trader/backtesting/runs-on-disk); every statistic's
definition is [metrics](/docs/trader/analytics/metrics); ranking a grid of these is
[run a sweep on the data service](/docs/trader/guides/sweep-on-the-service).


# Record a live feed (/docs/trader/guides/record-a-feed)



`vike-recorder` accumulates a live tape into your own history store, so you can backtest on markets
you have actually watched without buying an archive. It is a separate binary on purpose
(`crates/vike-recorder/src/lib.rs`): recording drags the signer, WebSocket and TLS stack into
whatever links it, so keeping it out of `vike-datahub` means a panic in feed parsing cannot take
serving down. Not the desktop app either — a tape that exists only while a window is open has a hole
wherever you closed it — and not `vike-tradehub`, because a trading restart must not punch a hole in
the tape.

## The profile [#the-profile]

One TOML file names the store and what to record. Every tick re-resolves each subscription's current
symbols, publishes their family membership, and drives the venue feed to exactly that set; rows land
in your DataFusion+Parquet store through `RecorderSink`, **one commit per family** rather than one per
symbol (`crates/vike-datahub/src/recorder.rs`).

```toml
store = "market_data/hist"

[[subscribe]]
venue = "polymarket"
family = "btc-updown-5m"
backfill = "off"
```

A rolling **family** is recorded as one grouped series, which is why a 5-minute rotation costs one
commit per flush instead of one per token. A subscription may name a family **or** symbols, never
both. A misspelled key is refused **by name**, with the line number and the keys that would have been
accepted — `webhook` for `webhooks` once left an operator believing a pager was armed.

<Callout type="warn" title="The store path is two traps in one line">
  A **relative** `store` resolves against the process working directory — right for the daemon, whose
  unit sets `WorkingDirectory=<project>`, and wrong for every command you run by hand: a hand-run
  `--once` from a source checkout was measured writing its tape *into the checkout* while the project's
  own `market_data/` stayed empty. And the directory name `hist` is not a free choice — it is the name
  every binary's own default resolves to (`crates/vike-model/src/state_path.rs`'s `HIST_SUBDIR`, under
  `PROJECT_DATA_DIR`), so a store called anything else is one the code cannot name: a reader run
  without `--store` opens `<project>/market_data/hist`, finds nothing, and reports zero rows rather
  than failing.
</Callout>

## Which venues this build can record [#which-venues-this-build-can-record]

`crates/vike-recorder/src/venues/mod.rs` is the only venue-aware code in the crate, one module per
recordable venue, each behind its own Cargo feature — enabling `polymarket` pulls an EIP-712 signer
into the binary, and a build recording only static-symbol venues should not link one. A
feature-absent build answers with a **startup error naming the missing feature**, never a silent
no-record.

Families are general, not a Polymarket shape: Polymarket asks what is live right now because its
token ids rotate every five minutes, while Binance resolves the same key as a glob (`*USDT`, `BTC*`,
`*USDT.P`) over an instrument list that does not change from tick to tick. What a Binance recording
contains is worth stating plainly — its declared capabilities are bars, trades and depth, with
`quotes: false` and `book: false`, so the tape is the **trade tape plus a conflated depth series**,
and the trade lane is the only path to that data at all
(`crates/vike-recorder/src/venues/binance.rs`).

## Prove the profile before you daemonize [#prove-the-profile-before-you-daemonize]

`--once` runs a single tick and exits: it proves the profile parses, the store opens, and each family
resolves to live symbols, without leaving a daemon running.

<Callout type="warn" title="Read the exit code, not the log">
  `--once` exits `0` only if every feed ended that tick with a live subscription, and `4`
  (`EXIT_DRY_RUN`) otherwise, naming each feed that would record nothing. It exited `0` on a total
  resolve failure until 2026-08-08.
</Callout>

## Two watchdogs, because one is blind to the other [#two-watchdogs-because-one-is-blind-to-the-other]

A feed that is subscribed and **connected but receiving nothing** is invisible from every other
vantage point: `subscribe_*` returned `Ok`, the socket is established, no error is raised, and the
loss counters stay at zero because there are no rows to lose. A production recorder ran **95 minutes**
in exactly that state, writing nothing for binance while logging a clean startup and zero warnings;
it was noticed by accident, days later, by reading row counts by hand
(`crates/vike-recorder/src/liveness.rs`).

* **`SilenceWatch`** watches *series* — rows arriving on something already subscribed. `--silent-secs`
  defaults to 300 s, chosen against the slowest thing a healthy recorder does: a Polymarket up/down
  family rotates every five minutes, so a shorter threshold cries wolf every cycle. On by default,
  deliberately — the failure is silent by nature, so an operator who has to know to switch it on is
  exactly the operator who will not.
* **`ResolveWatch`** watches *feeds* — a venue that has never produced a symbol to subscribe at all.
  It exists because the first is structurally blind to it: a venue that resolved nothing subscribed
  nothing, so the series watch iterates an empty set and reports nothing at two seconds or at two
  days. A misconfigured Polymarket proxy recorded nothing for a whole run while every watchdog stayed
  green.

A silent series is always logged and always alerted. The third reaction, `--exit-on-silence`
(`EXIT_SILENT` = 3, distinct from a startup failure so a supervisor can tell them apart), is opt-in:
a venue can be legitimately quiet, and a quiet market must not kill a daemon recording five healthy
ones.

The `[alerting]` table is optional and **its absence means defaults, not off** — with no `webhooks`
the alert still fires and still reaches the log; naming a target escalates it to a pager.
`series_prefix` scopes it by a prefix on the `{kind}/{venue}/{symbol}` key, because a Polymarket
token id does not exist yet when the file is written. **No credential goes in this file**:
`webhooks` names targets, and the token behind a name comes from the credential store or the process
environment.

## Maintenance, and the one memory knob [#maintenance-and-the-one-memory-knob]

`[maintenance]` is likewise optional-with-defaults rather than optional-and-off. The recorder commits
once per buffer flush, so a busy series writes a part every few seconds: **23 parts in 150 s** for one
family's book, about 57 KB each, roughly 13,000 files a day if nothing merges them. Compaction runs
in its own thread and takes the same per-series lock the appends do, so a racing flush serializes and
loses nothing.

`max_merge_rows` is the memory knob, and it is rows rather than bytes for a measured reason: a merge
is materialized whole (its output is timestamp-sorted, and a sort cannot stream), and on a live
Polymarket book series the parts were only 2.5× compressed, so a 64 MB budget peaked at **8.95 GB**.
Size it against your `MemoryMax`. `retention_days` omitted means keep forever — a recorder exists to
accumulate tape, so deleting any of it is always an explicit choice — and `0` is rejected, because it
would prune the tape as it is being written.

## Stopping without losing the tape [#stopping-without-losing-the-tape]

One stop flag, many triggers: a control word on stdin (`quit`/`shutdown`/`stop`), and SIGTERM/SIGINT
through `vike_ops::stop`'s `install_handlers`, so `systemctl stop`, a bare `kill` and Ctrl-C all reach
the same teardown. EOF stops only on a TTY — under systemd stdin is `/dev/null`, which reads EOF
immediately. On Windows there is no signal, but `install_handlers` bridges the console control events
onto the same flag — Ctrl-C, Ctrl-Break, window close. A *detached* recorder has neither a console
nor a TTY stdin, and unlike `vike-tradehub` it watches for no `SHUTDOWN` file, so nothing short of
`taskkill` reaches it — and that loses the buffered tape.

Teardown order is load-bearing: &#x2A;*unsubscribe every feed first, then shut the sink down.** The other
order leaves feed threads pushing rows into a channel whose writer is gone, and those rows are counted
as dropped with no reporter left to announce them. The sequence is budgeted end to end —
`FEED_STOP_BUDGET_SECS` plus `SHUTDOWN_DEADLINE_SECS`, summing to `TOTAL_STOP_BUDGET_SECS`, which is
what the shipped unit's `TimeoutStopSec=` is checked against — and ordered flush first with the
maintenance join last, so what a hard cap abandons is a restartable compaction pass and never the
rows. Until that handler existed SIGTERM reached none of it, and the flush is where the tape was lost.

Once there is tape, [replay it](/docs/trader/guides/replay-a-session); the store's layout and its
per-`kind` contracts are in [the history store](/docs/trader/concepts/hist-store) and
[concepts/data](/docs/trader/concepts/data). A long run also wants
[`VIKE_LOG_FILE_LEVEL`](/docs/trader/data-providers/log-volume).


# Replay a recorded session (/docs/trader/guides/replay-a-session)



"Replay" means two things here, and they answer different questions. **Tick replay** feeds a
recorded market tape back through the backtest engine, so a strategy sees the quotes, trades and book
events you actually recorded. **Journal replay** re-folds a live session's command journal through
the real single-writer core and proves the result bit-identical. The first tests a strategy; the
second tests the run.

## Replaying a recorded tape [#replaying-a-recorded-tape]

Set `kind = "tick"` on the run profile's `[data]` table and the harness loads from the history store
instead of the bar lane (`crates/vike-backtest/src/harness/profile.rs`'s `DataKind`).

```toml
[data]
kind = "tick"
venue = "polymarket"
symbols = ["71321045679252212594626385532706912750332728571942532289631379312455583992563"]
from = "2026-08-01T00"
to   = "2026-08-02T00"
```

`crates/vike-backtest/src/hist_replay.rs`'s `replay_ticks` scans each symbol's `scan_quotes`,
`scan_trades` and `scan_book_updates` over the range and merges them into one timestamp-ordered
stream. **The tie-break at equal timestamps is Book, then Quote, then Trade** — book first because
live derived quotes follow the book application that produced them, and quote-before-trade preserves
the original documented policy. A symbol with zero rows of all three kinds in range is
sparse-tolerant: a warning and a skip, not an error, so an all-sparse window degrades to an
empty-but-valid result rather than failing the run.

A cross-venue slice uses the `[[data.series]]` form instead, one entry per series with its own venue,
symbol and lane kind. Order is preserved **and is meaningful**: the engine's k-way merge breaks an
equal-timestamp tie by stream order, so listing a reference series first delivers a same-millisecond
reference sample *before* the print it should inform.

<Callout type="warn" title="The default replay is faster than any real consumer">
  Recorded ticks carry two clocks — the venue's `ts` and the machine's `local_ts`. The default orders
  each stream by the venue clock alone, so a replayed strategy sees every event the instant the venue
  stamped it, earlier than a live consumer ever could. On a proxied feed that systematically flatters
  the backtest. `engine.feed_latency = true` orders each symbol's stream by the **arrival** clock
  instead. It retags nothing: every tick keeps its venue `ts`, and matching stays on venue time —
  the venue matched when it matched. Only delivery order moves.
</Callout>

Two edge cases in that mode are documented and pinned by tests. A `local_ts` of zero or less (a
fixture, a backfilled row, a pre-`local_ts` part) falls back to the venue `ts`, so a partly-stamped
tape degrades gracefully instead of collapsing every unstamped tick to the front. A `local_ts`
*earlier* than the venue `ts` is clock skew — a machine cannot receive a tick before the venue
stamped it — and is **clamped up** to the venue `ts`, the only conservative direction, so modelled
feed latency is never negative. The re-order is a stable sort, so an unstamped tape replays
byte-identically in either mode. In v1 the re-order is per symbol: a single-symbol replay is fully
arrival-ordered, while cross-symbol interleaving stays venue-ordered.

`feed_latency` is tick-mode only and a bar-mode profile setting it is rejected at load, as is the
queue-position fill model, which the tick loop alone consults. See
[tick replay](/docs/trader/backtesting/tick-replay), [queue models](/docs/trader/backtesting/queue-models) and
[run profiles](/docs/trader/backtesting/run-profiles); getting the tape in the first place is
[record a live feed](/docs/trader/guides/record-a-feed).

## Replaying a command journal [#replaying-a-command-journal]

The [command journal](/docs/trader/concepts/journal) is off by default, so the first step is to have
recorded one. `crates/vike-core/src/run_profile.rs`'s `journal_config_from_env` resolves it from
exactly two places, and the precedence is deliberate: a loaded `VIKE_RUN_PROFILE` is
**authoritative** — its `[sinks.journal]` decides, even when that means no journal — and the
`VIKE_JOURNAL_DIR` quick knob is not consulted when a profile is present, so a profile can never be
silently overridden. A set-but-malformed profile disables journaling and logs a warning rather than
falling through.

Then hand the directory to the `replay_journal` binary, which takes one argument — the journal
directory — and prints a fixed set of lines: the total source record count (commands *and*
snapshots, labelled honestly rather than as the re-folded tail length), the number of snapshots
verified, the final state hash, and one line per engine giving its open-order count, its position
count and its balance. A failed replay prints `REPLAY FAILED` and exits non-zero
(`crates/vike-core/src/bin/replay_journal.rs`).

`crates/vike-core/src/replay.rs`'s `replay_offline` restores the engine from the journal's **first**
`Snap`, re-folds the whole tail through a real core, and fences the reproduced final hash against the
source journal's **last** `Snap` hash. Restoring from the latest checkpoint instead would leave
nothing to replay on a clean run — its exit snapshot already reflects everything — which is a
worthless fence. The replay core's sequence numbers differ from the source's, so per-record
comparison is impossible; final-hash equality is the guarantee.

Three details make the fold faithful. The replay core uses a pure no-op `ReplayClient`, because the
original venue events are already journaled and get re-pumped — a client that also emitted events
would double the state. A `QueueClock` replays the tail's recorded `now_ms`, so timestamp-derived
state such as an order's creation time matches. And the replay core mounts no strategy at all: a
mounted strategy reacts to non-journaled market data, but its order flow does not, because
`apply_strategy_intent` journals each already-resolved intent write-ahead of applying it. The same
shape covers an emulated conditional's fire and its disarm — the *decision* is journaled write-ahead
and re-applied through the identical site, never re-evaluated, so a fire can neither double nor
vanish.

<Callout type="warn" title="Two tails a replay refuses rather than approximates">
  v1 is single-engine: a multi-engine base returns `ReplayError::Unsupported`, because per-engine
  `seed_cash` is not part of the engine snapshot. A watchdog-tick tail is `Unsupported` too — the
  stuck-order and dead-man wall-clock sweeps it carries are not deterministic functions of the journal.
  A refusal is the honest answer; a fence that quietly skipped them would prove nothing.
</Callout>

Reading an older journal is safe and does not affect determinism. A build writes `VERSION` and reads
anything from `MIN_READABLE_VERSION` upward, appending to an older directory in place rather than
rejecting it, so upgrading a binary never costs an operator their live journal. The rule that makes
the range safe is that a version step may only *add* a record variant or a `serde(default)`-guarded
field; anything that renames or removes one must raise `MIN_READABLE_VERSION` in the same commit. A
version above `VERSION` — written by a later build — is a hard error.

`replay_offline` has a sibling that shares the same engine: `restore_from_journal` restores from the
**latest** `Snap`, re-folds the usually-empty crash tail, and returns the reproduced engines and coid
session with **no fence** — it is a restore, not a proof. What a restarted node actually picks up is
covered by [stop, liquidate, restart](/docs/trader/guides/stop-liquidate-restart); the format itself is
[journal replay](/docs/trader/concepts/journal/replay).


# Stop, liquidate, restart (/docs/trader/guides/stop-liquidate-restart)



Three verbs, three outcomes. A **stop** ends the process and, by default, leaves both your resting
orders and your positions at the venue. A **liquidation** is the kill switch: cancel everything,
flatten everything, halt. A **restart** recovers less than most operators assume, and the venue's
books come back through reconciliation, not replay. None of the three is a side effect of another.

## Stop: the process, or one mount [#stop-the-process-or-one-mount]

Both headless daemons share one stop primitive (`crates/vike-ops/src/stop.rs`): a single
`AtomicBool` raised by any of several triggers — the `shutdown`/`quit` word on a TTY stdin,
SIGTERM/SIGINT (so `systemctl stop`), and on Windows the console control events plus a `SHUTDOWN`
file under the state directory (`vike_ops::stop::STOP_FILE_NAME`), because a detached Windows
process has no console to be Ctrl-C'd in. The handler stores a bool and nothing else; the teardown
runs on the daemon's own path. Before the handler existed, `systemctl stop` ran not one line of
Rust: the resting book was abandoned at the venue on every restart of every box, while
`systemctl status` reported a clean stop.

The teardown, in order (`CoreThread::run` in `crates/vike-core/src/runtime/mod.rs`): drain what is
queued; if `flags.cancel_orders_on_shutdown` is on, run `cancel_resting_on_shutdown`
(`crates/vike-core/src/runtime/watchdog.rs`) — a `MassCancel` through the one order-write path,
marked risk-off so no venue budget sheds it, ungated by trading state so it works from a `Halted`
core; detach the venue clients; write the exit `Snap` if journaling is on; save each mount's
strategy-state sidecar. The whole sequence sits inside `[daemon] shutdown_deadline_ms` (default
`5_000`, `crates/vike-tradehub/src/config.rs`'s `DaemonSettings`) via
`vike_ops::shutdown::run_with_deadline`: a wedged venue delays the stop, it cannot prevent it, and
whatever is still in flight at the deadline is abandoned. The Telegram grammar has no stop verb at
all.

<Callout type="warn" title="A stop never closes a position">
  `cancel_orders_on_shutdown` cancels; it does not flatten. The sweep's own log line says it:
  "POSITIONS ARE NOT CLOSED — this leaves no ORDERS, not a flat book." And the flag is OFF by default
  (`crates/vike-core/src/runtime/mod.rs`'s `CoreConfig::cancel_orders_on_shutdown`, the standing
  statement of the stop policy): teardown detaches and exits, and your quotes stay resting at the
  venue with nothing left running to manage them — which is
  what an operator restarting for a deploy usually wants, and why the safer-sounding value is not the
  default. Set it in `<project>/settings/flags.toml` ([flags](/docs/trader/reference/settings/flags)).
</Callout>

A hard kill — `kill -9`, `taskkill` — runs none of this: no cancel sweep, no state save, no terminal
journal snapshot.

Stopping one strategy without stopping the process is the runtime unmount
(`Command::UnmountStrategy`; `crates/vike-core/src/runtime/mod.rs`'s `unmount_strategy_runtime`).
It cancels exactly the mount's attributed orders before removal — an order left resting after
nothing routes fills to its strategy is an unmanaged book — and, like the shutdown sweep, it does
not flatten: the position stays open, visible in the residual attribution row, and closing it is a
`Flatten` you issue.

## Liquidate: the kill switch [#liquidate-the-kill-switch]

`market-exit` (`vike-cli trade`'s `Verb::MarketExit`; `/marketexit` on
[Telegram](/docs/trader/guides/telegram-control)) is `OrderIntent::MarketExit`
(`crates/vike-exec/src/lanes.rs`): a compound verb the runtime expands at apply time into one
`MassCancel` first, then one `Flatten` per non-flat *net* position derived from the post-cancel
account (a hedge-mode long/short leg has no net bucket for `Flatten` to size against, so it is
skipped) — each a reduce-only MARKET order for `|position|`, lowered through the same `apply_intent`
site as any order, so mint → RiskGate → client stays structural. It is usable from a `Halted` core
with no precondition: the gate admits a position-covered reduce (`vike_model::is_covered_reduce` —
the order must oppose the position and be covered by it), which is exactly the shape `Flatten`
mints. The gate re-takes that verdict on the *lot-rounded* size, so the one leg a halt can still
deny is a position sitting off the lot grid, whose flatten rounds up into a flip. So `market-exit`
and `state halted` work in either order.

It is best-effort, not atomic. Against a real venue the mass-cancel is fire-and-forget over the
adapter's actor thread; its ACKs land asynchronously, possibly after the flatten market orders are
already on the wire, so a resting order can still fill after a flatten leg. Check `positions`
afterwards and re-issue the exit if the board is not flat.

Then close the door. `state halted` sets `TradingState::Halted` on the engine and the `RiskGate`
denies everything except a covered reduce — the in-process gate. The cross-process gate is a file:

```sh
touch <project>/settings/state/HALT   # the very next submit is refused
rm    <project>/settings/state/HALT   # resume
```

`crates/vike-bridge-core/src/halt.rs` resolves the path once per process — `VIKE_HALT_FILE` if
set, else `<project>/settings/state/HALT`, else `<exe_dir>/HALT` as a reported last resort — probes
that it can be created, and logs `HALT sentinel path resolved` (or `HALT KILL SWITCH IS NOT
ARMABLE`, as an error) at the first mount. With the file present, every venue on the shared
`ExecActor` refuses an opening submit with a terminal `OrderRejected` carrying
`HALT_REJECT_REASON`, admits a `reduce_only` submit, passes cancels through and blocks modifies. It
needs no IPC and no responsive runtime, which is what it is for. Nothing writes it for you except a
tripped dead-man's switch; `state halted` does not. [Halt](/docs/trader/concepts/halt) carries the full
admit table.

<Callout type="warn" title="The file boundary trusts the reduce_only flag">
  `ExecActor` holds no position book, so at that boundary the caller-asserted flag is the only
  evidence in existence (`crates/vike-exec/src/halt.rs`'s `halt_admits_submit`). A strategy bug that
  tags entries `reduce_only` can open risk through a HALT file on a flat book; every such admission is
  logged. The `RiskGate` in front of it is the verifying gate, and `policy.toml`'s
  `halt_admit = "verify"` tightens the file boundary only where the adapter holds a book — cTrader
  alone today; everywhere else it degrades to `admit` and says so at mount.
</Callout>

The [dead-man's switches](/docs/trader/concepts/dead-mans-switch) are the automatic twin, and there are
two of them with opposite defaults. The **connection** one
(`crates/vike-core/src/runtime/link_deadman.rs`) trips on a link a venue's own bridge has reported
`Disconnected` for longer than `policy.toml`'s `link_deadman_grace_ms` — a key that is **armed when
absent**, at two minutes — and cancels that venue's resting orders. The **silence** one
(`crates/vike-core/src/runtime/deadman.rs`) trips on ingest gone quiet past `deadman_timeout_ms`
and cancels everything; that key is **off unless written**, because a market that closes is silence
too and an armed default halted every FX and equities mount at every session close. Under the shared
default action `DeadManAction::CancelAllAndHalt` either one also sets `Halted` on every engine and
writes this same sentinel; plain `cancel_all` leaves the trading state as-is. Either way the latch
re-arms on recovery — `Halted` and the file do not. `vike-tradehub`'s live mount is the only thing
that constructs either switch; `vike-desktop` sets neither, so a desktop session has no automatic stop
of any kind.

<Callout type="warn" title="Armed by default is not armed everywhere">
  The connection switch arms for a venue only when that venue's bridge discloses a disconnect **and**
  this daemon subscribes the lane that carries it. On a default live mount both hold for **binance,
  bybit, okx and aster** — the quote/trade/book tick pump this daemon subscribes now discloses its own
  transport state onto the core tick lane — and for polymarket behind its Cargo feature. Every FX and
  equities venue is off because its market has sessions and a close is not an outage, and seven roster
  venues are off because their bridges disclose no disconnect at all. So an FX-only or equities-only
  mount still has no automatic stop for "the link died and we still have orders out", and no line in
  `policy.toml` changes that. The daemon logs one line per mounted venue at startup saying
  armed-or-why-not — read those for the box in front of you, and see
  [the dead-man's switches](/docs/trader/concepts/dead-mans-switch) for what would move a venue.
</Callout>

## Restart: what comes back [#restart-what-comes-back]

Up to two interlocks fire first. A configured journal directory takes an exclusive advisory lock
(`crates/vike-core/src/journal_lock.rs`, acquired on the `CommandJournal::open` path and so only
when journaling is on), which makes restarting before the old process has died a loud `AddrInUse`
naming the directory, never a second writer; a crashed process's lock is released by
the OS, so a leftover `LOCK` file is never stale. Each armed live venue claims
`<state_dir>/LIVE-<venue>.lock` (`crates/vike-ops/src/live_lock.rs`): one live process per venue
account, because two of them see each other's activity as `PositionDrift`. A paper mount claims
nothing.

What a restarted `vike-tradehub` recovers:

* **Profile mounts** — re-created from the profile at every boot.
* **Runtime mounts** — the topology sidecar (`crates/vike-core/src/mount_topology.rs`), replayed
  by `resurrect_runtime_mounts` after the core spawns and before feeds arm. A clean stop
  deliberately keeps its records: "the operator said stop the daemon" is not "the operator said
  unmount". Only an explicit unmount forgets one.
* **Strategy state** — `<state root>/strategy-state/<mount_id>.json`
  (`crates/vike-core/src/strategy_state.rs`; the id is `binance__BTC_USDT__1m`-shaped, or the
  sanitized controller id), loaded through `Strategy::load_state` at mount and saved on a clean
  shutdown or the periodic save. Fail-open: an absent or corrupt sidecar means no saved state,
  never a refused boot. See [Mounting](/docs/trader/concepts/mounting).
* **The HALT file** — it is a file. A halted node restarts halted until you `rm` it.

What it does not recover:

* **The order and position book.** `crates/vike-core/src/replay.rs`'s `restore_from_journal` can
  rebuild the engines, the coid session, the armed conditional and contingency books and the
  per-mount ledgers from the latest `Snap` — and no shipped binary calls it
  (`crates/vike-exec/src/account.rs`'s `seed_seen_fill_ids` says so in as many words). The journal
  itself is opt-in (`VIKE_JOURNAL_DIR`, or a run profile's `[sinks.journal]`); what it buys today is
  [offline replay](/docs/trader/concepts/journal/replay). Engines start empty, the fill-dedup ledger
  starts empty, and the venue resync lane is floored at spawn
  (`crates/vike-bridge-core/src/exec_actor.rs`'s `is_pre_spawn`), so history from before the process
  started is never re-folded through it. Adopting that state is
  [reconciliation](/docs/trader/concepts/reconciliation)'s job: `PositionDrift` re-converges position
  size, and the daemon defaults its [policy](/docs/trader/concepts/reconciliation/policies) to
  `quarantine`, so a restarted node holds the drift for your confirm instead of rewriting the book at
  the venue's average price unattended.
* **Orders you did not cancel.** They rest at the venue under a process that no longer exists; the
  new one meets them as `UnknownOrder` divergences — quarantined, with nothing to adopt unless
  `generate_missing_orders` is on, and adoption is narrowed to terminal orders. Cancel them by hand,
  or turn `cancel_orders_on_shutdown` on.
* **Attribution.** Post-restart fills on pre-restart orders are unattributed and land in the
  residual row (`CoreConfig::coid_mounts`).
* **The in-process halt.** `Halted` lives on the engine, and the engine is new.

## Never trade the account by hand while a mount runs [#never-trade-the-account-by-hand-while-a-mount-runs]

The mount cannot tell your order from a stranger's. Anything at the venue that nothing local
explains — an order row, a position row, a net-qty residual, a cash move — is tagged
`DivergenceOrigin::External` (`crates/vike-exec/src/recon/types.rs`), and you and a running mount
are exactly the two processes `live_lock` exists to keep apart. Under `hybrid`, `PositionDrift`
auto-applies: local position size is rewritten onto the venue's number and realized PnL is booked at
the venue's average price with no operator in front of it; a foreign fill inside the lookback
arrives as a coid-less `MissingFill`. `external-quarantine` holds both for a claim. If you must act
at the venue, `state halted` first, and expect reconciliation to raise what you did under whichever
policy the node runs. Stuck orders have their own path:
[Triage a stuck order](/docs/trader/guides/triage-a-stuck-order).


# Run a sweep on the data service (/docs/trader/guides/sweep-on-the-service)



`vike-datahub` is a headless **compute-to-data** backtest server. A client sends a small profile
config over a localhost TCP socket; the server runs the existing `vike-backtest` engine right next to
the data and returns just the report. The heavy history never crosses the wire — only the profile in
and the metrics summary out (`crates/vike-datahub/src/lib.rs`). That is what makes a sweep on a box
holding a large recorded tape practical from a laptop.

## Start the service [#start-the-service]

The server takes no options: the listen address and the store root come from the environment.

* `VIKE_DATAHUB_ADDR` — the listen address, default `127.0.0.1:7878`.
* `VIKE_DATAHUB_STORE` — the history-store root. Unset, it falls through the shared store-root
  precedence; the old CWD-relative last resort is gone, and it was the whole bug — launching from
  anywhere but the repo root created an empty store beside the shell.

Only a build with the `serve-datafusion` feature can actually serve, because that is what makes the
concrete DataFusion backend nameable; a default build still produces a runnable binary that answers
`--help` and `--version` identically. That is not a detail: this binary once parsed no argv at all,
so under the feature `vike-datahub --help` **started a server**.

<Callout type="warn" title="A non-loopback bind is refused, and one opt-in is not enough">
  Binding a non-loopback address is refused at startup unless `VIKE_DATAHUB_ALLOW_PUBLIC_BIND` is set
  to the exact string `"1"` **and** at least one node key is configured. The opt-in alone used to be
  enough, behind a warning, and `crates/vike-datahub/src/datahub_cli.rs`'s header records why that
  was not sufficient: the opt-in consents to being REACHABLE, and that is not consent to serve a
  store write and a script compiler unauthenticated. The guard did not soften when authentication landed: the
  handshake is plaintext and authenticates the **connection**, not each frame, so a tunnel is still what
  supplies confidentiality and integrity. Reach a remote service with
  `ssh -L 7878:localhost:7878 <box>`.
</Callout>

Authentication is opt-in and **the credential is the switch** — this workspace's absent-credentials
idiom pointed at a server. With neither `VIKE_DATAHUB_OBSERVE_KEY` nor `VIKE_DATAHUB_CONTROL_KEY` in
the credential store, the server authenticates nothing and behaves exactly as it did before
authentication existed: `Hello` is optional and informs rather than gates. With either set, `Hello`
becomes mandatory and must be the first frame, the `Welcome` answering it carries a fresh 32-byte
per-connection nonce, an `Auth` frame carrying the HMAC over that nonce must follow, and any verb
before `AuthOk` is refused and closes the connection. `Observe` reads history and the catalog;
`Control` additionally admits the backfill write and every `Run*` verb — **those compile
client-supplied Rhai server-side, so they are not reads whatever they return**.
`crates/vike-datahub/src/server.rs`'s `required_scope` is the one authority for the split and its
match is exhaustive, with no `_` arm, so a new verb cannot be added unclassified.

## Write the `[sweep]` table [#write-the-sweep-table]

A sweep is an ordinary backtest profile with one extra table. Each key overrides
`strategy.params.<key>` across a value grid, and `crates/vike-backtest/src/harness/sweep.rs`'s
`expand_sweep` takes the cartesian product, clearing each expanded point's own `sweep` field so every
point is itself a plain, runnable single-backtest profile.

```toml
[sweep]
rsi_period = [7, 14, 21]
threshold  = [1.5, 2.0, 2.5]
```

A profile with no `[sweep]` table, or an empty one, expands to exactly one point with no overrides.
Shipped to the service as a *sweep*, it comes back as a clean server-side error instead.

## Ship it [#ship-it]

```text
vike-cli sweep --profile <run.toml> [--addr 127.0.0.1:7878]
               [--rank-by sharpe|return|max_dd|equity] [--json]
```

The profile's **text** is read locally and shipped verbatim; the server parses and validates it with
`BacktestProfile::from_toml_str`, expands the grid, and runs it. `--rank-by` defaults to `sharpe`;
the name is validated locally against a four-entry roster so a typo costs no round trip, and the
metric itself is computed and applied server-side by the canonical comparator, so rows arrive already
ordered best-first. That local list is a spelling check, not a second implementation.

<Callout title="Why the whole TOML crosses the wire">
  This command used to re-parse the profile into wire DTOs — a second profile parser and a second date
  parser in the workspace — and that mapping could not carry `[engine].fee`, `[engine.impact]`,
  `[engine.resolution]`, `[risk]`, `snap_to_properties`, a tick slice or a cross-venue
  `[[data.series]]` slice. A sweep therefore ran quietly under **different costs** than the same
  profile's `vike-cli backtest`. Shipping the text leaves one profile parser in the workspace and makes
  the sweep honour the whole profile; it also removed a local reimplementation of Sharpe, max drawdown
  and total return, so every printed statistic is now the server's own report number
  (`crates/vike-backtest/src/harness/sweep.rs`).
</Callout>

## What the service does with the grid [#what-the-service-does-with-the-grid]

Every expanded point is fully independent over one shared store handle, so points run on a rayon
pool. Determinism does not rest on scheduling: `par_iter().map().collect()` is order-preserving, so
rows come back in expansion order regardless of which point finished first, and the ranking sort that
follows is stable over that same input — the identical bytes the one-at-a-time loop produced, pinned
by `parallel_and_sequential_sweeps_are_byte_identical`.

<Callout type="warn" title="Parallelism multiplies the data slice">
  The shared store handle shares the *handle*, not the loaded data: every point independently re-scans
  and fully materializes its own slice, so peak RSS and store I/O are `N_threads × slice`, not
  `1 × slice`. On a large recorded tick slice an uncapped one-worker-per-core sweep is an OOM shape,
  and these sweeps run on boxes that also host live trading. So the points get a bounded pool of their
  own rather than rayon's global one: it defaults to `min(4, available_parallelism())`, overridable
  with `VIKE_SWEEP_THREADS` (if the OS refuses those threads the sweep warns and falls back to the
  ambient pool — the same rows, without the bound). Raising that raises the multiplier — size it
  against the slice, not the core count. `VIKE_SWEEP_SEQUENTIAL=1` pins the whole process back to one
  at a time.
</Callout>

The server is deliberately hard to wedge: each connection runs on its own thread, so a panic inside a
handler drops that one socket rather than the accept loop; framing and decoding are split, so a
well-framed body from a newer client that this build cannot decode is answered with an error and the
loop continues; an idle or half-open peer hits a read timeout that always closes rather than resuming
a desynced stream; and every request produces a response, so a client always learns the outcome.

Reading what comes back is [read a backtest report](/docs/trader/guides/read-a-report). The expansion
itself is [sweeps](/docs/trader/backtesting/sweeps); when a full grid is too expensive, the same profile
feeds [search](/docs/trader/backtesting/search) and the pluggable
[objectives](/docs/trader/backtesting/objectives) seam.


# Control the daemon from Telegram (/docs/trader/guides/telegram-control)



`vike-tradehub` can be driven from a phone. The channel is a `getUpdates` long-poll against
Telegram's Bot API — an outbound HTTPS GET, no inbound listener — and every write instruction is
answered with a preview and a single-use token before anything reaches the core.

<Callout type="warn" title="The accepted risk, stated once">
  `crates/vike-tradehub/src/telegram/mod.rs` states it plainly: with this channel enabled,
  &#x2A;*possession of the bot token plus membership in an allowlisted chat is sufficient to place real
  orders.** Telegram is a third party sitting in an order-origination path. `ControlLimits` and the
  core `RiskGate` still bound the blast radius; the residual does not go away.
</Callout>

## 1. Build with the feature [#1-build-with-the-feature]

The default is a **compile-time** one, not a runtime one. Without the `telegram` feature
`src/telegram/` is not part of the crate at all, `main.rs` has no mount and no call site, and the
direct `ureq` edge is dropped. A runtime gate can be misconfigured or inherited from a stale systemd
unit; code that was never compiled in cannot be reached by any misconfiguration. The crate is built
with `--features telegram`, and that feature has its own CI lane.

## 2. Open all four gates [#2-open-all-four-gates]

They are required **simultaneously**, and they live in two different places on purpose:

| gate                             | where            | semantics                                    |
| -------------------------------- | ---------------- | -------------------------------------------- |
| `VIKE_TRADEHUB_CONTROL=1`        | process env      | the exact string `"1"`                       |
| `VIKE_TELEGRAM_CONTROL=1`        | process env      | the exact string `"1"`                       |
| `VIKE_TELEGRAM_BOT_TOKEN`        | credential store | absent or blank means nothing is constructed |
| `VIKE_TELEGRAM_ALLOWED_CHAT_IDS` | credential store | comma-separated; empty means disabled        |

Absent any one of the four there is no poller thread, no token in memory and no network call.
`maybe_spawn` enforces that ordering literally: the two process-env flags are checked by the pure
`control_gates_open` first and the credential loader is passed as a *function*, so on the closed path
the store is never even opened and the bot token never enters the process's address space. An
optional fifth, `VIKE_TELEGRAM_ALLOWED_USER_IDS`, can only ever **narrow**.

<Callout type="warn" title="Authorization is per-chat; attribution is per-user">
  The gate asks one question — is this chat allowlisted? — and a chat is not a person. An allowlisted
  `-100…` supergroup authorizes every member, including everyone anyone later adds, with no config
  change and nothing to review. `parse_updates` therefore reads `message.from.id` and the `@handle`,
  and `confirm_reason`/`confirmed_by` put both the instructing and the confirming actor into the audit
  rationale. The confirm token stays chat-bound rather than user-bound deliberately: binding it would
  stop an operator confirming a colleague's preview.
</Callout>

An unlisted `chat_id` is **ignored and logged, never answered** — no reply, not even an error. A bot
that answers unknown chats is an oracle confirming a trading node exists behind it.

## 3. The grammar [#3-the-grammar]

`crates/vike-tradehub/src/telegram/parse.rs`'s `parse_instruction` is the whole grammar and the only
place a chat string becomes a `WireCommand`. Anything without a leading `/` is silently ignored, so
ordinary group chatter produces no bot noise; `/verb@botname` is accepted, because Telegram appends
the bot's username in a group.

Read verbs answer immediately: `/status`, `/positions`, `/orders`, `/equity`, plus `/help`
(`/start`). Write verbs are previewed only:

```text
/submit <venue> <symbol> <buy|sell> <qty> [price] [reduce]
/cancel <client_order_id>
/modify <client_order_id> [qty=<q>] [price=<p>]
/masscancel
/flatten <venue> <symbol>
/marketexit
/state <active|reducing|halted>
/confirm <token>
```

There is no stop verb. Stopping the daemon is
[its own procedure](/docs/trader/guides/stop-liquidate-restart).

## 4. Preview, then confirm [#4-preview-then-confirm]

1. A write instruction is answered with a preview: the resolved `WireCommand`, the
   server-authoritative guardrail verdict, and a single-use token. &#x2A;*Nothing is sent.**
2. Only `/confirm <token>`, within `CONFIRM_WINDOW_MS` (60 s), executes.
3. The token is single-use — `PendingConfirms::take` removes it *before* the command is handed to
   the core — and bound to the exact command it previewed **and** to the chat that asked. A token
   that has fired, expired, or belongs to another chat is refused, and a wrong-chat attempt does not
   burn it.

`crates/vike-tradehub/src/telegram/confirm.rs` lists those properties as a table with the test that
gates each one, so removing a guarantee fails CI rather than evaporating quietly. The store is
**memory-only**: a day-old `/confirm` replayed out of Telegram's queue after a restart finds no
pending entry and executes nothing, while a replayed `/submit` produces only another preview.

Every confirmed instruction then goes through `crate::server::accept_command` — the exact function
the TCP `Request::Command` arm calls — so the rate token, the notional cap, the rationale sanitizer,
the lowering, the single-writer lane and the audit record are identical by construction rather than
by review. See [the control boundary](/docs/trader/concepts/control-boundary).

## 5. At-most-once across a restart [#5-at-most-once-across-a-restart]

Telegram's `update_id` is monotonic. `crates/vike-tradehub/src/telegram/ledger.rs`'s `UpdateLedger`
persists the high-water mark (append-only lines, max on load) to
`<project>/settings/state/telegram_updates.ledger`, and every `getUpdates` passes
`offset = last + 1`, which is also how Telegram is ACKed. An update is marked **before** it is acted
on: a daemon that dies mid-command must lose that command, never place it twice.

A ledger write that cannot land is an error, never a shrug. At arming, `maybe_spawn` opens the ledger
to prove it appendable and returns `None` with one `tracing::error!` if it is not — the daemon keeps
trading headless and the remote write surface simply does not exist. At runtime an unmarkable update
is dropped undispatched.

## When the channel goes quiet [#when-the-channel-goes-quiet]

`crates/vike-tradehub/src/telegram/failure.rs` separates "retrying could help" from "retrying can
never help". A **401, 403 or 404** is permanent: one `error!` and the poller stops. Everything else —
5xx, 429, 409, transport, unreadable body, bad JSON — is transient, with exponential backoff to a
ceiling and announcements throttled to consecutive failures 1, 2, 4, 8. `409 Conflict` is
deliberately transient: it means two daemons on one token, or an active webhook, and neither is a
rejected credential.

That policy exists because of a measurement. A wrong bot token fails *instantly* — there is no long
poll to wait through — so the old answer-every-failure-the-same loop settled at roughly two requests
per second forever: **19 warnings in 10 s** on a clean install with a mistyped token, about 164,000
outbound third-party requests and 164,000 WARN lines (\~37 MB) per day, at the exact level operators
are told to set `VIKE_LOG_FILE_LEVEL` to. The token is read once at mount, so the error line names
the restart.

The bot token is embedded in the API base URL, which is why `ProdTelegramDeps` has no `Debug` and
never interpolates the URL or a transport error into a message, and `TelegramConfig`'s `Debug`
redacts the token.


# Triage a stuck order (/docs/trader/guides/triage-a-stuck-order)



"Stuck" is two different failures wearing one word, and they are triaged in opposite directions. An
order **pre-ack** — `Initialized` or `Submitted`, with no terminal from the venue — may or may not
exist at the venue at all. An order the venue **never mentions** in a reconcile pass is the reverse:
your book says it is live and the venue's report is silent. Start by asking which one you have.

## The core already has a ladder [#the-core-already-has-a-ladder]

`crates/vike-core/src/runtime/watchdog.rs`'s `sweep_stuck_orders` is the last-resort backstop for the
first case: an adapter that accepted `submit` and whose thread wedged before emitting any terminal.
Its whole design constraint is stated up front — **it must never race a slow-but-real venue ack into
a phantom reject**, because a synthesized `OrderRejected` would strand a real position, and the later
genuine `OrderAccepted` or `OrderFilled` is then an illegal transition out of `Rejected` and is
dropped (counted as `stranded_terminal_drops` in the exec fold, with the position still stranded).

So it is a ladder, not a timeout:

* **Stage 1**, at `created + submit_ack_timeout`: the order is flagged un-acked and the venue is
  actively **prodded** — the core issues a `confirm` once and records when. Nothing is terminalized.
* **Stage 2**, at `created + submit_ack_timeout + grace`: the hard reject — *unless* the in-flight
  confirm guard defers it. A reject candidate that had a stage-1 confirm and is still pre-ack (a real
  ack or fill would have moved it out) has its confirm presumed in flight, so the deadline extends to
  `created + submit_ack_timeout + 2·grace`. Only past that, still pre-ack, is the backstop
  `OrderRejected` synthesized.

An order that somehow reaches the reject deadline without a prior confirm — a busy core skipped
ticks, or a clock jumped — is not rejected on the spot either: it is confirmed now and deferred, so
the invariant *no backstop reject without at least one active confirm and its grace window* holds.
The fold thread issues no network call itself: `confirm_order` is fire-and-forget onto the adapter's
own thread, and the sweep only waits for the terminal to arrive on the event lane. Reconcile-seeded
orders carry no creation timestamp and are never swept.

<Callout type="warn" title="The watchdog is off unless something armed it">
  `CoreConfig::submit_ack_timeout` is `None` by default, which disables the ladder entirely. A run
  profile's `[guards]` table arms it: `submit_ack_timeout_ms` is stage 1 and
  `submit_ack_confirm_grace_ms` is stage 2's window. Leaving the grace key out leaves the caller's
  value exactly as the binary built it — that struct carries no default of its own, and it used to,
  which is the incident: its stale 5 s was written over the hardened 15 s default whenever the timeout
  key was named, silently halving the confirm window on a live mount.
</Callout>

## What a confirm actually does [#what-a-confirm-actually-does]

`vike_exec::ExecutionClient`'s `confirm` re-queries one order's status by client-order-id. Like every
method on that seam it is fire-and-forget: the venue's authoritative terminal returns over the ingest
lane, and the call returns nothing. Its **default is a no-op** — a client with no order-status
re-query does nothing, and the backstop reject still covers it — so what a confirm buys you depends
on the venue adapter overriding it.

Where one is implemented, the mapping is shared and venue-neutral
(`crates/vike-bridge-core/src/rest.rs`'s `resolve_ambiguous_submit`), with three outcomes and one
rule:

* the venue **has** the order, live or already filled → a managed `OrderAccepted` carrying the venue
  order id, with the fill following on the normal user-data lane;
* the venue confirms it **never landed** → the true terminal `OrderRejected`;
* the re-query itself was **inconclusive** (transport error, double timeout) → an *optimistic*
  `OrderAccepted` with no venue id, **never** a false terminal, because a phantom reject here would
  strand a position the venue actually opened.

That last arm is why the grace matters. If you tune it, the documented lower bound is that the grace
should exceed `submit_ack_timeout/2` plus the adapter's re-query round trips — the halved timeout is
watchdog tick jitter, and the re-query term is the number of sequential REST calls a venue's confirm
makes (two for Bybit's realtime-then-history hop, one for OKX). A grace of zero collapses the ladder
back to immediate-reject-at-timeout, making both the window **and** the guard no-ops, and reinstating
exactly the phantom-reject risk they exist to remove.

## When the order is not pre-ack [#when-the-order-is-not-pre-ack]

If the order is past `Submitted` and simply not moving, the watchdog will never touch it — it only
sweeps `Initialized` and `Submitted`. This is where [reconciliation](/docs/trader/concepts/reconciliation)
takes over, and the divergence kind names your situation
(`crates/vike-exec/src/recon/types.rs`'s `DivergenceKind`):

* **`MissingTerminal`** — the venue's order is terminal and yours is not. Local origin, and it
  auto-applies under `hybrid`, but it **resolves to no events**: auto-apply is not the same as doing
  something.
* **`OrphanLocalOrder`** — a live local open order this pass's venue report never mentions. It folds
  nothing under any policy, deliberately: a synthesized cancel would terminalize an order that may
  still be resting at the venue. Its classification decides only whether a held policy *surfaces* it,
  which before the reclassification it did not — `hybrid` folded an empty event list and raised
  nothing at all.
* **`UnknownOrder`** — the venue reports an order with no local match, the mirror image. It
  quarantines with nothing to adopt unless `generate_missing_orders` is on, and even then adoption is
  narrowed to a *terminal* unknown order whose fills fell outside the lookback, so a live one can
  never book the same activity twice.

<Callout type="warn" title="Two of these three fold nothing, whatever the policy">
  Which is the useful part of the diagnosis: under a policy that HOLDS the kind — `quarantine` for
  all three, `hybrid` for `OrphanLocalOrder` and `UnknownOrder` — reconciliation will **tell** you
  about a stuck order and will not clear it for you. A `hybrid` `MissingTerminal` auto-applies, so it
  neither folds nor alerts, and `synthesize` surfaces none of the three. Cancelling it is your action,
  from the `trade` REPL or an agent tool, and if the venue has genuinely lost it the cancel is what
  proves so.
</Callout>

## Confirming a held divergence [#confirming-a-held-divergence]

A held divergence appears in the published snapshot's reconciliation block as a `ReconAlertView` —
its kind, a detail string, and how many events are held pending confirm. It deliberately **never**
carries the raw proposed events; those stay fold-thread state until you confirm. You confirm by the
`id` that block carries, which the reconcile pass assigns monotonically **within this process run**
and is not stable across a journal replay.

Under `quarantine` every divergence waits for that confirm; under `external-quarantine` the
foreign-origin ones do, including a coid-less `MissingFill` — a venue fill echoing no client order id,
which names no local order at all. See [policies](/docs/trader/concepts/reconciliation/policies).

## Do not help by hand [#do-not-help-by-hand]

Cancelling a stuck order in the venue's own web UI while a mount runs does not settle it quietly — it
moves the disagreement to the next reconcile pass: `MissingTerminal` while the venue report still
carries the now-terminal order, `OrphanLocalOrder` once it has aged out of that report. Neither reads
as foreign activity — `crates/vike-exec/src/recon/types.rs`'s `DivergenceKind::origin` classifies
them `ReconciliationMaterialized` and `Absence`, never `External` — so `external-quarantine` treats
both exactly as `hybrid` does (it differs only where the origin is `External`), and neither folds an
event under any policy. If you must, halt first — the procedure is
[stop, liquidate, restart](/docs/trader/guides/stop-liquidate-restart), and the states an order can
legally reach are [the order lifecycle](/docs/trader/concepts/order-lifecycle).


# Indicators (/docs/trader/indicators)



Vike Trader ships **171** built-in single-series indicators and **8** two-series *pair* indicators.
Neither number is a hand count: `crates/vike-indicators/tests/parity.rs`'s
`registry_is_complete_and_consistent` asserts the registry holds exactly 171 uniquely-named rows and
that `make` round-trips every one, and `crates/vike-indicators/tests/pairs_parity.rs`'s
`pair_registry_is_complete_and_consistent` does the same for the 8.

## The one guarantee [#the-one-guarantee]

Every indicator is two implementations of one series. `Indicator::on_bar` is the streaming path — feed
the next bar, advance, get this bar's output line or lines, with no lookahead; the event engine and the
live path use it. `Indicator::vectorize` is the batch path — the whole series at once, one `Vec<f64>`
per output line; the vector engine and the chart use it.

They are **one source of truth**: `on_bar` folded over a series equals `vectorize` on that series
*bit-for-bit*. `parity.rs`'s `on_bar_equals_vectorize_for_every_indicator` is that gate, and it compares
through `f64::to_bits` with both-NaN counted equal — never through a tolerance. `vectorize` is the
reference kernel, warm-up positions emit `f64::NAN`, and fold order (naive left folds) is load-bearing
rather than incidental.

<Callout type="warn" title="Three indicators read the future, and they say so">
  `ichimoku` (its `chikou` line), `zigzag` and `williams_fractal` are flagged
  `IndicatorMeta::batch_only`: their batch form reads bars ahead of the one being computed, so no causal
  streaming path can equal it. `vectorize` is the authority, `on_bar` is a best-effort that is NaN at the
  unknowable tip, and the parity gate skips exactly these three. Every other row sets the flag `false` —
  the exceptions are declared in the registry, not discovered by a reader.
</Callout>

## The nine categories [#the-nine-categories]

A category is a `vike_indicators::Category` variant — a picker grouping, not a source file. Each gets a
page listing every indicator in it with parameters, defaults and sweep ranges; `Category::label` is
where the display name comes from, which is why `Overlap` shows as *Trend*.

| Category                                    | Built-in rows | Picker label |
| ------------------------------------------- | ------------- | ------------ |
| [overlap](/docs/trader/indicators/overlap)       | 21            | Trend        |
| [momentum](/docs/trader/indicators/momentum)     | 36            | Momentum     |
| [volatility](/docs/trader/indicators/volatility) | 16            | Volatility   |
| [volume](/docs/trader/indicators/volume)         | 14            | Volume       |
| [statistics](/docs/trader/indicators/statistics) | 13            | Statistics   |
| [pattern](/docs/trader/indicators/pattern)       | 63            | Patterns     |
| [price](/docs/trader/indicators/price)           | 4             | Price        |
| [structure](/docs/trader/indicators/structure)   | 4             | Structure    |
| [user](/docs/trader/indicators/user)             | 0             | User         |

Those pages are generated: `crates/vike-ops/src/docs_data.rs` renders `indicators.json` from
`vike_indicators::registry` and `pair_registry` — every `Category` variant, empty ones included, because
a category that vanished for having no rows is the silent omission that exporter's gate refuses.

## Warm-up and seed history [#warm-up-and-seed-history]

`Indicator::lookback` is the index of the first bar at which `vectorize` yields a non-NaN value on *any*
line. It is not a seed size for a multi-line indicator: `adx`'s namesake line trails its `+DI`/`-DI`,
`macd`'s signal and histogram trail the macd line. `Indicator::lookback_full` — the first index at which
*every* line is valid — is the number to size seed history with, and is always at least `lookback`; both
are reachable by name and parameters through `registry::lookback` and `lookback_full`. `lookback` is a
conservative lower bound: rows with a real parameter-derived override report
`IndicatorMeta::lookback_exact` and are gated `==`, the rest `>=`, and `tests/lookback.rs`'s
`EXACT_FLOOR` ratchet holds the exact-override count at 105 or more.

<Callout type="warn" title="A lookback of zero does not always mean warm">
  `Indicator::warmup_path_dependent` flags the indicators whose value depends on all history since the
  mount rather than on a bounded window. Their `lookback()` of `0` is truthful — they emit a number from
  bar one — but it is not the number a chart holding full history shows: `psar` fabricates its initial
  trend, `vwap` accumulates only from the current UTC day *as seen*, and the cumulative series start at
  whatever bar the mount began at. Seed these with as much history as you have — for `vwap`, at least
  back to the UTC-day boundary.
</Callout>

## Parameters, and where an indicator draws [#parameters-and-where-an-indicator-draws]

Each parameter is a `ParamSpec` — a display name, the `default` that `new()` sets, and the `min`, `max`
and `step` behind the dialog's sliders and the sweep grid. `registry::coerce` is the one value-coercion
site: a missing entry or a `NaN` becomes the default, the result is clamped to `[min, max]`, and extra
values are ignored. Every parameterised constructor runs its slice through it, so `make_with` at the
declared defaults reproduces `make` bit-for-bit.

Two axes sit orthogonal to the category. `RenderKind` says whether the indicator belongs on the price
panel (`Overlay`) or in its own oscillator pane (`Oscillator`). `OutputStyle` says how each line renders
— `Line`, `Band`, `Histogram`, `Dots` or `Marker`. `Marker` is pattern-exclusive and means a per-bar
signal (`+100` bullish, `-100` bearish, `0` none) rather than a price, so the chart anchors a glyph to
the flagged bar's own extreme and keeps the series out of the price pane's autofit. See
[the chart](/docs/trader/gui/chart) and [the indicators pane](/docs/trader/gui/studio/indicators-pane).

## Indicators you write, and pairs [#indicators-you-write-and-pairs]

The `User` category ships empty and always will: `IndicatorMeta::user` rows never sit in `registry()`.
The variant exists because it is the one honest answer for a file the crate has never seen — filing a
user indicator under `Statistics` would claim a classification nobody made.
[Writing an indicator](/docs/trader/scripting/writing-an-indicator) and
[loading indicators](/docs/trader/scripting/loading-indicators) cover that path; the
[custom-indicator tutorial](/docs/trader/tutorials/custom-indicator) proves your own kernel
streaming-equals-batch with the shipped harness.

[Pair indicators](/docs/trader/indicators/pairs) read a second instrument, which a single bar cannot supply,
so they live behind their own `PairIndicator` trait and `pair_registry`, isolated from the single-series
seam. Two of the eight — `half_life` and `kalman_beta` — port nothing: they are statistics that return a
plottable number and decide nothing, which is why they sit on a shared seam rather than inside one
strategy.

<Callout title="The same bits on every box">
  IEEE 754 does not require `ln`, `log10`, `exp` or `atan` to be correctly rounded, so two C runtimes may
  disagree in the last bit. Measured, not assumed: `fisher`, `hvol`, `chop`, `linearreg_angle`, `alma` and
  the pair kernels `spread` and `correl_log` hashed differently on Windows and Linux. The crate calls
  `libm` rather than the platform's, and two gates hold it — `libm_cross_platform_pin` pins the values to
  one committed set for all platforms, and `production_code_calls_libm_not_the_platform` reads every
  production line under `src/` and refuses the platform spellings outright.
</Callout>

The `indicators` CLI verb prints this catalog from a terminal, narrowed to what a Rhai strategy can
actually call: `crates/vike-cli/src/cmd/indicators.rs`'s `bound_metas` keeps only the registry rows
`vike_script::RHAI_INDICATORS` binds under a bare name or `vike_script::line_accessors` reaches by
line, so its roster is smaller than 171 — and the three `batch_only` rows above, reachable by no
spelling at all, appear in none of it. See
[reference/cli/research/indicators](/docs/trader/reference/cli/research/indicators).


# Momentum indicators (/docs/trader/indicators/momentum)




Momentum indicators measure the speed and persistence of a move — oscillators, rate-of-change families and their signal lines. Vike Trader ships **36** of them in this category, out of
171 built-in single-series indicators and 8
[pair indicators](/docs/trader/indicators/pairs); the [indicators overview](/docs/trader/indicators) carries
the catalog's shape and the categories side by side.

Every built-in indicator carries one guarantee: its streaming `on_bar` path equals its batch
`vectorize` kernel bit-for-bit, proven by the parity gate in the product tree
(`crates/vike-indicators/tests/parity.rs`). The exceptions are declared, not discovered: an
indicator marked **batch-only** reads future bars in its batch form, so its streaming value is a
causal best-effort that is NaN at the unknowable tip, and the gate skips it by name. No indicator in this category is batch-only.

## Indicators [#indicators]

Each parameter is shown with its built-in default and the range and step the Studio's sweep grid
offers for it (`ParamSpec` in `vike_indicators::registry`).

| Id                  | Name                     | Parameters (default; range, step)                                                                                                                                                                                                                                    | Batch-only |
| ------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `rsi`               | RSI                      | `length` = 14 (1–1000, step 1)                                                                                                                                                                                                                                       | no         |
| `macd`              | MACD                     | `fast_length` = 12 (1–1000, step 1); `slow_length` = 26 (1–1000, step 1); `signal_length` = 9 (1–1000, step 1)                                                                                                                                                       | no         |
| `stochastic`        | Stochastic               | `length` = 14 (1–1000, step 1); `smooth_k` = 3 (1–1000, step 1); `smooth_d` = 3 (1–1000, step 1)                                                                                                                                                                     | no         |
| `cci`               | CCI                      | `length` = 20 (1–1000, step 1)                                                                                                                                                                                                                                       | no         |
| `roc`               | Rate of Change           | `length` = 10 (1–1000, step 1)                                                                                                                                                                                                                                       | no         |
| `williams`          | Williams %R              | `length` = 14 (1–1000, step 1)                                                                                                                                                                                                                                       | no         |
| `awesome`           | Awesome Oscillator       | `fast_length` = 5 (1–1000, step 1); `slow_length` = 34 (1–1000, step 1)                                                                                                                                                                                              | no         |
| `mom`               | Momentum                 | `period` = 10 (1–400, step 1)                                                                                                                                                                                                                                        | no         |
| `rocp`              | ROC Percentage           | `period` = 10 (1–400, step 1)                                                                                                                                                                                                                                        | no         |
| `rocr`              | ROC Ratio                | `period` = 10 (1–400, step 1)                                                                                                                                                                                                                                        | no         |
| `rocr100`           | ROC Ratio ×100           | `period` = 10 (1–400, step 1)                                                                                                                                                                                                                                        | no         |
| `apo`               | Absolute Price Osc       | `fast` = 12 (2–200, step 1); `slow` = 26 (2–400, step 1)                                                                                                                                                                                                             | no         |
| `ppo`               | Percentage Price Osc     | `fast` = 12 (2–200, step 1); `slow` = 26 (2–400, step 1)                                                                                                                                                                                                             | no         |
| `cmo`               | Chande Momentum Osc      | `period` = 14 (2–200, step 1)                                                                                                                                                                                                                                        | no         |
| `bop`               | Balance of Power         | none                                                                                                                                                                                                                                                                 | no         |
| `dpo`               | Detrended Price Osc      | `period` = 20 (2–400, step 1)                                                                                                                                                                                                                                        | no         |
| `trix`              | TRIX                     | `period` = 18 (2–200, step 1)                                                                                                                                                                                                                                        | no         |
| `tsi`               | True Strength Index      | `long` = 25 (2–400, step 1); `short` = 13 (2–200, step 1)                                                                                                                                                                                                            | no         |
| `smi_ergodic`       | SMI Ergodic              | `long` = 20 (2–400, step 1); `short` = 5 (2–200, step 1); `signal` = 5 (2–200, step 1)                                                                                                                                                                               | no         |
| `coppock`           | Coppock Curve            | `wma_p` = 10 (2–100, step 1); `roc_long` = 14 (2–200, step 1); `roc_short` = 11 (2–200, step 1)                                                                                                                                                                      | no         |
| `kst`               | Know Sure Thing          | `roc1` = 10 (1–200, step 1); `sma1` = 10 (2–200, step 1); `roc2` = 15 (1–200, step 1); `sma2` = 10 (2–200, step 1); `roc3` = 20 (1–200, step 1); `sma3` = 10 (2–200, step 1); `roc4` = 30 (1–200, step 1); `sma4` = 15 (2–200, step 1); `signal` = 9 (2–200, step 1) | no         |
| `aroon`             | Aroon                    | `period` = 14 (2–400, step 1)                                                                                                                                                                                                                                        | no         |
| `aroonosc`          | Aroon Oscillator         | `period` = 14 (2–400, step 1)                                                                                                                                                                                                                                        | no         |
| `adx`               | ADX                      | `period` = 14 (2–100, step 1)                                                                                                                                                                                                                                        | no         |
| `adxr`              | ADXR                     | `period` = 14 (2–100, step 1)                                                                                                                                                                                                                                        | no         |
| `elder_ray`         | Elder Ray                | `period` = 13 (2–200, step 1)                                                                                                                                                                                                                                        | no         |
| `stochf`            | Fast Stochastic          | `k` = 14 (2–100, step 1); `d` = 3 (1–50, step 1)                                                                                                                                                                                                                     | no         |
| `stochrsi`          | Stochastic RSI           | `rsi_p` = 14 (2–100, step 1); `k` = 14 (2–100, step 1); `d` = 3 (1–50, step 1)                                                                                                                                                                                       | no         |
| `ultosc`            | Ultimate Oscillator      | `p1` = 7 (2–100, step 1); `p2` = 14 (2–200, step 1); `p3` = 28 (2–400, step 1)                                                                                                                                                                                       | no         |
| `vortex`            | Vortex                   | `period` = 14 (2–200, step 1)                                                                                                                                                                                                                                        | no         |
| `chande_kroll_stop` | Chande Kroll Stop        | `p` = 10 (2–200, step 1); `x` = 1 (1–10, step 1); `q` = 9 (2–200, step 1)                                                                                                                                                                                            | no         |
| `asi`               | Accumulative Swing Index | `limit` = 1 (0.1–10, step 0.1)                                                                                                                                                                                                                                       | no         |
| `fisher`            | Fisher Transform         | `period` = 9 (2–100, step 1)                                                                                                                                                                                                                                         | no         |
| `connors_rsi`       | Connors RSI              | `rsi_p` = 3 (2–100, step 1); `streak_p` = 2 (2–100, step 1); `rank_p` = 100 (10–500, step 1)                                                                                                                                                                         | no         |
| `relative_vigor`    | Relative Vigor Index     | `period` = 10 (2–200, step 1)                                                                                                                                                                                                                                        | no         |
| `ac`                | Accelerator Oscillator   | none                                                                                                                                                                                                                                                                 | no         |

## Using them [#using-them]

In a [Rhai strategy](/docs/trader/scripting/writing-a-strategy) an indicator is a call by id with its
parameters in registry order — `rsi(…)` — and the Studio's
[indicators pane](/docs/trader/gui/studio/indicators-pane) offers the same catalog with each parameter's
sweep range pre-filled from the defaults below. From Rust, `vike_indicators::make(id)` builds the
default instance and `make_with(id, &params)` the parameterised one; both consult the same
registry row this table was rendered from.


# Overlap indicators (/docs/trader/indicators/overlap)




Overlap studies are drawn on the price pane itself — moving averages, bands, channels and envelopes that share the price axis. Vike Trader ships **21** of them in this category, out of
171 built-in single-series indicators and 8
[pair indicators](/docs/trader/indicators/pairs); the [indicators overview](/docs/trader/indicators) carries
the catalog's shape and the categories side by side.

Every built-in indicator carries one guarantee: its streaming `on_bar` path equals its batch
`vectorize` kernel bit-for-bit, proven by the parity gate in the product tree
(`crates/vike-indicators/tests/parity.rs`). The exceptions are declared, not discovered: an
indicator marked **batch-only** reads future bars in its batch form, so its streaming value is a
causal best-effort that is NaN at the unknowable tip, and the gate skips it by name. In this category that is `ichimoku`.

## Indicators [#indicators]

Each parameter is shown with its built-in default and the range and step the Studio's sweep grid
offers for it (`ParamSpec` in `vike_indicators::registry`).

| Id           | Name               | Parameters (default; range, step)                                                             | Batch-only |
| ------------ | ------------------ | --------------------------------------------------------------------------------------------- | ---------- |
| `sma`        | Simple MA          | `length` = 20 (1–1000, step 1)                                                                | no         |
| `ema`        | Exponential MA     | `length` = 20 (1–1000, step 1)                                                                | no         |
| `wma`        | Weighted MA        | `length` = 20 (1–1000, step 1)                                                                | no         |
| `psar`       | Parabolic SAR      | `step` = 0.02 (0.001–0.5, step 0.001); `max_af` = 0.2 (0.05–1, step 0.01)                     | no         |
| `dema`       | Double EMA         | `period` = 20 (2–400, step 1)                                                                 | no         |
| `tema`       | Triple EMA         | `period` = 20 (2–400, step 1)                                                                 | no         |
| `trima`      | Triangular MA      | `period` = 20 (2–400, step 1)                                                                 | no         |
| `smma`       | Smoothed MA        | `period` = 14 (2–400, step 1)                                                                 | no         |
| `zlema`      | Zero-Lag EMA       | `period` = 20 (2–400, step 1)                                                                 | no         |
| `hma`        | Hull MA            | `period` = 20 (2–400, step 1)                                                                 | no         |
| `vwma`       | Volume-Weighted MA | `period` = 20 (2–400, step 1)                                                                 | no         |
| `t3`         | Tillson T3         | `period` = 20 (2–400, step 1); `v` = 0.7 (0–1, step 0.05)                                     | no         |
| `alma`       | Arnaud Legoux MA   | `period` = 20 (2–400, step 1); `offset` = 0.85 (0–1, step 0.05); `sigma` = 6 (1–20, step 0.5) | no         |
| `midpoint`   | Midpoint           | `period` = 14 (2–400, step 1)                                                                 | no         |
| `midprice`   | Midprice           | `period` = 14 (2–400, step 1)                                                                 | no         |
| `supertrend` | Supertrend         | `period` = 10 (1–100, step 1); `mult` = 3 (0.5–10, step 0.5)                                  | no         |
| `ichimoku`   | Ichimoku Cloud     | `tenkan` = 9 (2–100, step 1); `kijun` = 26 (2–100, step 1); `senkou` = 52 (2–200, step 1)     | **yes**    |
| `mcginley`   | McGinley Dynamic   | `period` = 14 (2–200, step 1)                                                                 | no         |
| `gmma`       | Guppy MMA          | none                                                                                          | no         |
| `envelopes`  | Envelopes          | `period` = 20 (2–200, step 1); `pct` = 2.5 (0.1–20, step 0.1)                                 | no         |
| `alligator`  | Alligator          | none                                                                                          | no         |

## Using them [#using-them]

In a [Rhai strategy](/docs/trader/scripting/writing-a-strategy) an indicator is a call by id with its
parameters in registry order — `sma(…)` — and the Studio's
[indicators pane](/docs/trader/gui/studio/indicators-pane) offers the same catalog with each parameter's
sweep range pre-filled from the defaults below. From Rust, `vike_indicators::make(id)` builds the
default instance and `make_with(id, &params)` the parameterised one; both consult the same
registry row this table was rendered from.


# Pair indicators (/docs/trader/indicators/pairs)




A pair indicator reads TWO series — an instrument and its benchmark, or the two legs of a spread —
where every indicator in the [main catalog](/docs/trader/indicators) reads one. They live behind their
own seam (`vike_indicators::pairs::PairIndicator`, with `pair_registry` as their roster) because
the second input changes the whole streaming contract: a pair value is defined only where both
series have a bar, and the lookback a kernel needs is a function of both. Vike Trader ships
**8** of them beside its 171 single-series indicators.

They carry the same guarantee as the single-series catalog — streaming equals batch, bit-for-bit,
under their own parity gate (`crates/vike-indicators/tests/pairs_parity.rs`) — and the same
parameter surface: a name, a default, and the range and step the Studio's sweep grid offers.

## Pair indicators [#pair-indicators]

| Id              | Name                   | Parameters (default; range, step)                                                   |
| --------------- | ---------------------- | ----------------------------------------------------------------------------------- |
| `ratio`         | Price Ratio            | none                                                                                |
| `spread`        | Spread                 | `log` = 0 (0–1, step 1)                                                             |
| `spread_zscore` | Spread Z-Score         | `period` = 20 (2–200, step 1); `beta` = 1 (-5–5, step 0.1)                          |
| `beta`          | Beta                   | `period` = 5 (2–200, step 1)                                                        |
| `correl`        | Correlation            | `period` = 30 (2–200, step 1)                                                       |
| `correl_log`    | Log-Return Correlation | `period` = 30 (2–200, step 1)                                                       |
| `half_life`     | Spread Half-Life       | `period` = 20 (2–200, step 1); `beta` = 1 (-5–5, step 0.1)                          |
| `kalman_beta`   | Kalman Hedge Ratio     | `delta` = 0.0001 (0.000001–0.1, step 0.0001); `ve` = 0.001 (0.000001–1, step 0.001) |

## Using them [#using-them]

A pair indicator needs its benchmark named: in a [Rhai strategy](/docs/trader/scripting/writing-a-strategy)
the second series is declared beside the first, and the [pairs z-score](/docs/trader/strategies/templates/pairs-zscore)
template is the reference consumer — it trades the rolling z-score of a spread using exactly this
seam. From Rust, `vike_indicators::pair_make(id)` and `pair_make_with(id, &params)` build an
instance; `pair_lookback(id, &params)` answers how much history both legs must carry before the
first value is defined.


# Pattern indicators (/docs/trader/indicators/pattern)




Pattern indicators recognise candlestick and bar formations, emitting a signal on the bar where the pattern completes. Vike Trader ships **63** of them in this category, out of
171 built-in single-series indicators and 8
[pair indicators](/docs/trader/indicators/pairs); the [indicators overview](/docs/trader/indicators) carries
the catalog's shape and the categories side by side.

Every built-in indicator carries one guarantee: its streaming `on_bar` path equals its batch
`vectorize` kernel bit-for-bit, proven by the parity gate in the product tree
(`crates/vike-indicators/tests/parity.rs`). The exceptions are declared, not discovered: an
indicator marked **batch-only** reads future bars in its batch form, so its streaming value is a
causal best-effort that is NaN at the unknowable tip, and the gate skips it by name. No indicator in this category is batch-only.

## Indicators [#indicators]

Each parameter is shown with its built-in default and the range and step the Studio's sweep grid
offers for it (`ParamSpec` in `vike_indicators::registry`).

| Id                        | Name                           | Parameters (default; range, step) | Batch-only |
| ------------------------- | ------------------------------ | --------------------------------- | ---------- |
| `doji`                    | Doji                           | none                              | no         |
| `engulfing`               | Engulfing                      | none                              | no         |
| `hammer`                  | Hammer                         | none                              | no         |
| `inverted_hammer`         | Inverted Hammer                | none                              | no         |
| `hanging_man`             | Hanging Man                    | none                              | no         |
| `shooting_star`           | Shooting Star                  | none                              | no         |
| `dragonfly_doji`          | Dragonfly Doji                 | none                              | no         |
| `gravestone_doji`         | Gravestone Doji                | none                              | no         |
| `longlegged_doji`         | Long-Legged Doji               | none                              | no         |
| `rickshaw_man`            | Rickshaw Man                   | none                              | no         |
| `takuri`                  | Takuri                         | none                              | no         |
| `marubozu`                | Marubozu                       | none                              | no         |
| `closing_marubozu`        | Closing Marubozu               | none                              | no         |
| `spinning_top`            | Spinning Top                   | none                              | no         |
| `high_wave`               | High Wave                      | none                              | no         |
| `long_line`               | Long Line                      | none                              | no         |
| `short_line`              | Short Line                     | none                              | no         |
| `belt_hold`               | Belt Hold                      | none                              | no         |
| `opening_marubozu`        | Opening Marubozu               | none                              | no         |
| `doji_star`               | Doji Star                      | none                              | no         |
| `harami`                  | Harami                         | none                              | no         |
| `harami_cross`            | Harami Cross                   | none                              | no         |
| `piercing`                | Piercing                       | none                              | no         |
| `dark_cloud_cover`        | Dark Cloud Cover               | none                              | no         |
| `counterattack`           | Counterattack                  | none                              | no         |
| `meeting_lines`           | Meeting Lines                  | none                              | no         |
| `separating_lines`        | Separating Lines               | none                              | no         |
| `matching_low`            | Matching Low                   | none                              | no         |
| `on_neck`                 | On Neck                        | none                              | no         |
| `in_neck`                 | In Neck                        | none                              | no         |
| `thrusting`               | Thrusting                      | none                              | no         |
| `kicking`                 | Kicking                        | none                              | no         |
| `kicking_by_length`       | Kicking by Length              | none                              | no         |
| `homing_pigeon`           | Homing Pigeon                  | none                              | no         |
| `gap_side_side_white`     | Gapping Side-by-Side White     | none                              | no         |
| `tasuki_gap`              | Tasuki Gap                     | none                              | no         |
| `morning_star`            | Morning Star                   | none                              | no         |
| `evening_star`            | Evening Star                   | none                              | no         |
| `morning_doji_star`       | Morning Doji Star              | none                              | no         |
| `evening_doji_star`       | Evening Doji Star              | none                              | no         |
| `three_white_soldiers`    | Three White Soldiers           | none                              | no         |
| `three_black_crows`       | Three Black Crows              | none                              | no         |
| `identical_three_crows`   | Identical Three Crows          | none                              | no         |
| `three_inside`            | Three Inside                   | none                              | no         |
| `three_outside`           | Three Outside                  | none                              | no         |
| `three_line_strike`       | Three-Line Strike              | none                              | no         |
| `three_stars_in_south`    | Three Stars in the South       | none                              | no         |
| `abandoned_baby`          | Abandoned Baby                 | none                              | no         |
| `advance_block`           | Advance Block                  | none                              | no         |
| `stalled_pattern`         | Stalled Pattern                | none                              | no         |
| `two_crows`               | Two Crows                      | none                              | no         |
| `upside_gap_two_crows`    | Upside Gap Two Crows           | none                              | no         |
| `tristar`                 | Tristar                        | none                              | no         |
| `unique_three_river`      | Unique Three River             | none                              | no         |
| `stick_sandwich`          | Stick Sandwich                 | none                              | no         |
| `ladder_bottom`           | Ladder Bottom                  | none                              | no         |
| `concealing_baby_swallow` | Concealing Baby Swallow        | none                              | no         |
| `rise_fall_three_methods` | Rising/Falling Three Methods   | none                              | no         |
| `mat_hold`                | Mat Hold                       | none                              | no         |
| `hikkake`                 | Hikkake                        | none                              | no         |
| `hikkake_mod`             | Modified Hikkake               | none                              | no         |
| `xside_gap_three_methods` | Up/Down-side Gap Three Methods | none                              | no         |
| `breakaway`               | Breakaway                      | none                              | no         |

## Using them [#using-them]

In a [Rhai strategy](/docs/trader/scripting/writing-a-strategy) an indicator is a call by id with its
parameters in registry order — `doji(…)` — and the Studio's
[indicators pane](/docs/trader/gui/studio/indicators-pane) offers the same catalog with each parameter's
sweep range pre-filled from the defaults below. From Rust, `vike_indicators::make(id)` builds the
default instance and `make_with(id, &params)` the parameterised one; both consult the same
registry row this table was rendered from.


# Price indicators (/docs/trader/indicators/price)




Price transforms are the typical, median, weighted and average price series other indicators build on. Vike Trader ships **4** of them in this category, out of
171 built-in single-series indicators and 8
[pair indicators](/docs/trader/indicators/pairs); the [indicators overview](/docs/trader/indicators) carries
the catalog's shape and the categories side by side.

Every built-in indicator carries one guarantee: its streaming `on_bar` path equals its batch
`vectorize` kernel bit-for-bit, proven by the parity gate in the product tree
(`crates/vike-indicators/tests/parity.rs`). The exceptions are declared, not discovered: an
indicator marked **batch-only** reads future bars in its batch form, so its streaming value is a
causal best-effort that is NaN at the unknowable tip, and the gate skips it by name. No indicator in this category is batch-only.

## Indicators [#indicators]

Each parameter is shown with its built-in default and the range and step the Studio's sweep grid
offers for it (`ParamSpec` in `vike_indicators::registry`).

| Id         | Name           | Parameters (default; range, step) | Batch-only |
| ---------- | -------------- | --------------------------------- | ---------- |
| `avgprice` | Average Price  | none                              | no         |
| `medprice` | Median Price   | none                              | no         |
| `typprice` | Typical Price  | none                              | no         |
| `wclprice` | Weighted Close | none                              | no         |

## Using them [#using-them]

In a [Rhai strategy](/docs/trader/scripting/writing-a-strategy) an indicator is a call by id with its
parameters in registry order — `avgprice(…)` — and the Studio's
[indicators pane](/docs/trader/gui/studio/indicators-pane) offers the same catalog with each parameter's
sweep range pre-filled from the defaults below. From Rust, `vike_indicators::make(id)` builds the
default instance and `make_with(id, &params)` the parameterised one; both consult the same
registry row this table was rendered from.


# Statistics indicators (/docs/trader/indicators/statistics)




Statistical indicators are the regression, correlation and distribution kernels — the raw material of a research feature set. Vike Trader ships **13** of them in this category, out of
171 built-in single-series indicators and 8
[pair indicators](/docs/trader/indicators/pairs); the [indicators overview](/docs/trader/indicators) carries
the catalog's shape and the categories side by side.

Every built-in indicator carries one guarantee: its streaming `on_bar` path equals its batch
`vectorize` kernel bit-for-bit, proven by the parity gate in the product tree
(`crates/vike-indicators/tests/parity.rs`). The exceptions are declared, not discovered: an
indicator marked **batch-only** reads future bars in its batch form, so its streaming value is a
causal best-effort that is NaN at the unknowable tip, and the gate skips it by name. No indicator in this category is batch-only.

## Indicators [#indicators]

Each parameter is shown with its built-in default and the range and step the Studio's sweep grid
offers for it (`ParamSpec` in `vike_indicators::registry`).

| Id                    | Name                 | Parameters (default; range, step)                            | Batch-only |
| --------------------- | -------------------- | ------------------------------------------------------------ | ---------- |
| `linearreg`           | Linear Regression    | `period` = 14 (2–200, step 1)                                | no         |
| `linearreg_slope`     | Linear Reg Slope     | `period` = 14 (2–200, step 1)                                | no         |
| `linearreg_angle`     | Linear Reg Angle     | `period` = 14 (2–200, step 1)                                | no         |
| `linearreg_intercept` | Linear Reg Intercept | `period` = 14 (2–200, step 1)                                | no         |
| `tsf`                 | Time Series Forecast | `period` = 14 (2–200, step 1)                                | no         |
| `var`                 | Variance             | `period` = 20 (2–200, step 1)                                | no         |
| `zscore`              | Z-Score              | `period` = 20 (2–200, step 1)                                | no         |
| `skew`                | Skewness             | `period` = 20 (2–200, step 1)                                | no         |
| `kurtosis`            | Kurtosis             | `period` = 20 (2–200, step 1)                                | no         |
| `mad`                 | Mean Abs Deviation   | `period` = 20 (2–200, step 1)                                | no         |
| `std_error`           | Standard Error       | `period` = 20 (2–200, step 1)                                | no         |
| `std_error_bands`     | Std Error Bands      | `period` = 20 (2–200, step 1); `mult` = 2 (0.1–10, step 0.1) | no         |
| `rank_correlation`    | Rank Correlation     | `period` = 14 (2–200, step 1)                                | no         |

## Using them [#using-them]

In a [Rhai strategy](/docs/trader/scripting/writing-a-strategy) an indicator is a call by id with its
parameters in registry order — `linearreg(…)` — and the Studio's
[indicators pane](/docs/trader/gui/studio/indicators-pane) offers the same catalog with each parameter's
sweep range pre-filled from the defaults below. From Rust, `vike_indicators::make(id)` builds the
default instance and `make_with(id, &params)` the parameterised one; both consult the same
registry row this table was rendered from.


# Structure indicators (/docs/trader/indicators/structure)




Structure indicators mark swings, fractals and zig-zags — the market-structure primitives, some of which can only be known in hindsight. Vike Trader ships **4** of them in this category, out of
171 built-in single-series indicators and 8
[pair indicators](/docs/trader/indicators/pairs); the [indicators overview](/docs/trader/indicators) carries
the catalog's shape and the categories side by side.

Every built-in indicator carries one guarantee: its streaming `on_bar` path equals its batch
`vectorize` kernel bit-for-bit, proven by the parity gate in the product tree
(`crates/vike-indicators/tests/parity.rs`). The exceptions are declared, not discovered: an
indicator marked **batch-only** reads future bars in its batch form, so its streaming value is a
causal best-effort that is NaN at the unknowable tip, and the gate skips it by name. In this category that is `zigzag`, `williams_fractal`.

## Indicators [#indicators]

Each parameter is shown with its built-in default and the range and step the Studio's sweep grid
offers for it (`ParamSpec` in `vike_indicators::registry`).

| Id                   | Name               | Parameters (default; range, step)                          | Batch-only |
| -------------------- | ------------------ | ---------------------------------------------------------- | ---------- |
| `pivot_points`       | Pivot Points       | none                                                       | no         |
| `volume_profile_poc` | Volume Profile POC | `window` = 50 (5–500, step 1); `bins` = 24 (4–200, step 1) | no         |
| `zigzag`             | ZigZag             | `deviation` = 5 (0.1–50, step 0.5)                         | **yes**    |
| `williams_fractal`   | Williams Fractal   | `n` = 2 (1–10, step 1)                                     | **yes**    |

## Using them [#using-them]

In a [Rhai strategy](/docs/trader/scripting/writing-a-strategy) an indicator is a call by id with its
parameters in registry order — `pivot_points(…)` — and the Studio's
[indicators pane](/docs/trader/gui/studio/indicators-pane) offers the same catalog with each parameter's
sweep range pre-filled from the defaults below. From Rust, `vike_indicators::make(id)` builds the
default instance and `make_with(id, &params)` the parameterised one; both consult the same
registry row this table was rendered from.


# User indicators (/docs/trader/indicators/user)




The user category is where indicators you load yourself land: it ships EMPTY, by design. Of the 171 built-in indicators, none sits here, and the table below
is empty on purpose: the exporter renders every `vike_indicators::Category` variant, empty ones
included, so a category that vanished for having no rows can never pass for one that was never
declared.

An indicator you write — in Rhai, through the Studio, or as a Rust type registered with
`IndicatorMeta::user` — is classified `User` and appears in the catalog beside the built-ins
with the same parameter surface: name, default and sweep range. Two pages walk the two paths:
[writing an indicator](/docs/trader/scripting/writing-an-indicator) covers the Rhai form and its
`param()` declarations; [loading indicators](/docs/trader/scripting/loading-indicators) covers where
a user indicator lives on disk and how the Studio and the CLI pick it up.

Every built-in indicator carries one guarantee: its streaming `on_bar` path equals its batch
`vectorize` kernel bit-for-bit, proven by the parity gate in the product tree
(`crates/vike-indicators/tests/parity.rs`). The exceptions are declared, not discovered: an
indicator marked **batch-only** reads future bars in its batch form, so its streaming value is a
causal best-effort that is NaN at the unknowable tip, and the gate skips it by name.

A user indicator is outside that gate: the parity harness runs over the built-in registry, so the
streaming-equals-batch property is yours to test for your own kernels — the
[research](/docs/trader/research) tree shows the harness a study can reuse for exactly that.

## Indicators [#indicators]

| Id | Name | Parameters (default; range, step) | Batch-only |
| -- | ---- | --------------------------------- | ---------- |

## Using them [#using-them]

In a [Rhai strategy](/docs/trader/scripting/writing-a-strategy) an indicator is a call by id with its
parameters in registry order — `sma(…)` — and the Studio's
[indicators pane](/docs/trader/gui/studio/indicators-pane) offers the same catalog with each parameter's
sweep range pre-filled from the defaults below. From Rust, `vike_indicators::make(id)` builds the
default instance and `make_with(id, &params)` the parameterised one; both consult the same
registry row this table was rendered from.


# Volatility indicators (/docs/trader/indicators/volatility)




Volatility indicators size how much price moves rather than where — ranges, deviations and the bands built on them. Vike Trader ships **16** of them in this category, out of
171 built-in single-series indicators and 8
[pair indicators](/docs/trader/indicators/pairs); the [indicators overview](/docs/trader/indicators) carries
the catalog's shape and the categories side by side.

Every built-in indicator carries one guarantee: its streaming `on_bar` path equals its batch
`vectorize` kernel bit-for-bit, proven by the parity gate in the product tree
(`crates/vike-indicators/tests/parity.rs`). The exceptions are declared, not discovered: an
indicator marked **batch-only** reads future bars in its batch form, so its streaming value is a
causal best-effort that is NaN at the unknowable tip, and the gate skips it by name. No indicator in this category is batch-only.

## Indicators [#indicators]

Each parameter is shown with its built-in default and the range and step the Studio's sweep grid
offers for it (`ParamSpec` in `vike_indicators::registry`).

| Id                    | Name                      | Parameters (default; range, step)                                                                     | Batch-only |
| --------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------- | ---------- |
| `bollinger`           | Bollinger Bands           | `length` = 20 (1–1000, step 1); `mult` = 2 (0.1–10, step 0.1)                                         | no         |
| `donchian`            | Donchian Channel          | `length` = 20 (1–1000, step 1)                                                                        | no         |
| `keltner`             | Keltner Channel           | `ema_length` = 20 (1–1000, step 1); `atr_length` = 10 (1–1000, step 1); `mult` = 2 (0.1–10, step 0.1) | no         |
| `atr`                 | ATR                       | `length` = 14 (1–1000, step 1)                                                                        | no         |
| `true_range`          | True Range                | none                                                                                                  | no         |
| `natr`                | Normalized ATR            | `period` = 14 (2–100, step 1)                                                                         | no         |
| `stddev`              | Std Deviation             | `period` = 20 (2–200, step 1)                                                                         | no         |
| `hvol`                | Historical Volatility     | `period` = 20 (2–200, step 1); `ann` = 365 (1–365, step 1)                                            | no         |
| `bbands_pctb`         | Bollinger %B              | `period` = 20 (2–200, step 1); `k` = 2 (0.5–5, step 0.1)                                              | no         |
| `bbands_width`        | Bollinger Width           | `period` = 20 (2–200, step 1); `k` = 2 (0.5–5, step 0.1)                                              | no         |
| `donchian_width`      | Donchian Width            | `period` = 20 (2–200, step 1)                                                                         | no         |
| `ulcer`               | Ulcer Index               | `period` = 14 (2–200, step 1)                                                                         | no         |
| `chop`                | Choppiness Index          | `period` = 14 (2–200, step 1)                                                                         | no         |
| `relative_volatility` | Relative Volatility Index | `period` = 14 (2–200, step 1)                                                                         | no         |
| `high_low_52w`        | 52-Week High/Low          | `period` = 252 (2–1000, step 1)                                                                       | no         |
| `mass`                | Mass Index                | `period` = 25 (2–200, step 1); `ema_period` = 9 (2–50, step 1)                                        | no         |

## Using them [#using-them]

In a [Rhai strategy](/docs/trader/scripting/writing-a-strategy) an indicator is a call by id with its
parameters in registry order — `bollinger(…)` — and the Studio's
[indicators pane](/docs/trader/gui/studio/indicators-pane) offers the same catalog with each parameter's
sweep range pre-filled from the defaults below. From Rust, `vike_indicators::make(id)` builds the
default instance and `make_with(id, &params)` the parameterised one; both consult the same
registry row this table was rendered from.


# Volume indicators (/docs/trader/indicators/volume)




Volume indicators fold traded quantity into the picture — accumulation, flow and volume-weighted prices. Vike Trader ships **14** of them in this category, out of
171 built-in single-series indicators and 8
[pair indicators](/docs/trader/indicators/pairs); the [indicators overview](/docs/trader/indicators) carries
the catalog's shape and the categories side by side.

Every built-in indicator carries one guarantee: its streaming `on_bar` path equals its batch
`vectorize` kernel bit-for-bit, proven by the parity gate in the product tree
(`crates/vike-indicators/tests/parity.rs`). The exceptions are declared, not discovered: an
indicator marked **batch-only** reads future bars in its batch form, so its streaming value is a
causal best-effort that is NaN at the unknowable tip, and the gate skips it by name. No indicator in this category is batch-only.

## Indicators [#indicators]

Each parameter is shown with its built-in default and the range and step the Studio's sweep grid
offers for it (`ParamSpec` in `vike_indicators::registry`).

| Id           | Name                      | Parameters (default; range, step)                                                       | Batch-only |
| ------------ | ------------------------- | --------------------------------------------------------------------------------------- | ---------- |
| `vwap`       | VWAP (session)            | none                                                                                    | no         |
| `obv`        | On-Balance Volume         | none                                                                                    | no         |
| `ad`         | Accumulation/Distribution | none                                                                                    | no         |
| `adosc`      | Chaikin A/D Oscillator    | `fast` = 3 (2–50, step 1); `slow` = 10 (2–200, step 1)                                  | no         |
| `cmf`        | Chaikin Money Flow        | `period` = 20 (2–200, step 1)                                                           | no         |
| `efi`        | Elder Force Index         | `period` = 13 (2–200, step 1)                                                           | no         |
| `eom`        | Ease of Movement          | `period` = 14 (2–200, step 1)                                                           | no         |
| `kvo`        | Klinger Volume Oscillator | `fast` = 34 (2–200, step 1); `slow` = 55 (2–500, step 1); `signal` = 13 (2–100, step 1) | no         |
| `mfi`        | Money Flow Index          | `period` = 14 (2–100, step 1)                                                           | no         |
| `net_volume` | Net Volume                | none                                                                                    | no         |
| `nvi`        | Negative Volume Index     | none                                                                                    | no         |
| `pvi`        | Positive Volume Index     | none                                                                                    | no         |
| `pvt`        | Price Volume Trend        | none                                                                                    | no         |
| `volume_osc` | Volume Oscillator         | `short` = 5 (2–50, step 1); `long` = 10 (2–200, step 1)                                 | no         |

## Using them [#using-them]

In a [Rhai strategy](/docs/trader/scripting/writing-a-strategy) an indicator is a call by id with its
parameters in registry order — `vwap(…)` — and the Studio's
[indicators pane](/docs/trader/gui/studio/indicators-pane) offers the same catalog with each parameter's
sweep range pre-filled from the defaults below. From Rust, `vike_indicators::make(id)` builds the
default instance and `make_with(id, &params)` the parameterised one; both consult the same
registry row this table was rendered from.


# Avellaneda–Stoikov (/docs/trader/market-making/avellaneda-stoikov)



`crates/vike-mm/src/avellaneda.rs` is the optional pricing layer `SpreadMaker::with_avellaneda_stoikov`
turns on. It is "net-new Rust with NO Python twin (like `SpreadMaker` itself), so 'parity' means
self-consistent reference-value pinning + neutral-reduction, not oracle bits." Its output is a
`(bid, ask)` pair that "still flows UNCHANGED into the size-skew → breaker → filtration →
modify-in-place tail" of [quote emission](/docs/trader/market-making/quote-emission), "so A-S inherits
the adverse-selection guard it classically lacks."

## The closed forms [#the-closed-forms]

The module header states them, "adapted to Polymarket's 0–1 bounded prices":

```text
reservation price   r      = s − q_norm · γ · V
optimal half-spread δ_half = ½·γ·V + (1/γ)·ln(1 + γ/κ)
effective variance  V      = min(σ̂²·H, p·(1−p))
```

`s` is the fair mid, `q_norm` the size-normalised signed inventory, `γ` risk aversion, `κ` the
fill-intensity decay, `H` the effective horizon (`min(τ_hold, T−t)` where a resolution time is
known, `τ_hold` alone otherwise), and `p = s` the current probability. "The Bernoulli cap `p(1−p)`
makes skew and spread vanish at the 0/1 walls (V→0) and peak at p=0.5 — the defensible adaptation
that keeps A-S from over-penalising inventory near a wall." The half-spread is decomposed into
`as_vol_halfspread` (`½·γ·V`) and `as_intensity_halfspread` (`(1/γ)·ln(1+γ/κ)`), "so the floor is
a clean bit-anchor when `V == 0`".

Each input has one owner. `AsState::fair_value` takes the raw mid, or with `use_micro_price` the
micro-price "weighted toward the side with LESS resting size"; a one-sided book returns `None`.
`q_norm = position / q_scale`, with `q_scale = 0` treated as `1`. `update_sigma2` is one EWMA step
of the per-ms mid variance, `inst = Δ²/Δt`, with `α = 1 − 0.5^(1/half_life)`. `horizon_ms` returns
`τ_hold` under `HorizonMode::ConstantTau`, and `min(τ_hold, T−t)` under `TimeToResolution` once a
`resolution_ts` is known — without one it returns `τ_hold` there too.
`bounded_variance` implements the three `VarianceMode`s — `LocalCapped` (the default),
`PureBernoulli`, `RawLocal` — clamped at `0`. κ comes from `effective_kappa`, the subject of
[intensity fits](/docs/trader/market-making/intensity-fits).

`AsParams::default` is "the recommended Polymarket starting configuration": `gamma` 0.1,
`tau_hold_ms` 3 600 000, `resolution_blackout_ms` 60 000, a `kappa_default` of 50 — "used directly
in `KappaMode::Fixed`", the default mode, and unclamped there — with `kappa_min` `1` and
`kappa_max` `1000`, which clamp a *fitted* κ in `crates/vike-mm/src/fits.rs`'s `fit_kappa`,
`sigma_half_life` 32, `trade_window_ms` 60 000, `n_min` 20, `q_scale` 100 and a one-tick
`min_standoff_ticks`. `horizon_mode` defaults to `TimeToResolution` with `resolution_ts` unset, so
on the recommended configuration that hour is the whole horizon until a profile names a resolution
time.

## The price domain [#the-price-domain]

The 0–1 geometry "is now ONE case of a `PriceDomain` knob". `domain_bounds` resolves the posted
walls: `UnitInterval` gives `(tick, 1 − tick)` "with the SAME arithmetic the layer hard-coded before
the generalization"; `Unbounded` gives `(−∞, +∞)`, for which the clamp "is an exact no-op";
`Band { lo, hi }` gives explicit walls. Two pairings "are load-bearing for a `$`-scale mount":
`VarianceMode::RawLocal`, because "the Bernoulli cap goes negative for `p > 1`", and a
`min_half_spread_ticks` floor, because "the adverse-selection half-spread is sub-tick at `$`-scale,
so without it bid/ask snap to one tick."

## The width ladder [#the-width-ladder]

`bounded_half_spread` is "THE WIDTH LADDER — the single authority on how a raw model half-spread
becomes the posted one". Three stages, and "the ORDER is the whole design": the
`min_half_spread_ticks` floor (the sub-tick guard); the `max_half_spread_ticks` cap, re-floored so
"a `max < min` misconfig can never sacrifice the two-sided quote"; and the break-even `fee_floor`
from `break_even_half_spread`, which is `½ · round_trip_fee_rate · s` — "one leg's rate times the
price, even though the bar being cleared is the whole round trip."

The third stage does not join the `max(floor, cap)` idiom. When `fee_floor_exceeds_cap&#x60;, "the
answer is **`None`: post nothing**", because the cap answers "how wide may I go and still hope to
fill?" and the fee floor "how wide must I be to not lose money?", and when they disagree "that is a
fact about the INSTRUMENT … not about the tuning". The measurement behind the rule: "on prod2's
bybit BTCUSDT mount: a 60-tick ceiling ⇒ ≤ 1.903 bp of capture against a 4.000 bp round-trip fee,
i.e. −3.94 bp per round trip, forever."

<Callout type="warn" title="The fee floor makes an impossible mount refuse; it does not make it profitable">
  "The cure for `fee_floor_exceeds_cap` is a different instrument or a different fee tier, never a
  wider cap." `AsState::note_fee_floor` warns on the EDGE into and out of the refusal — twice per
  episode, never per tick, because the requote is the vike-core hot fold — and `round_trip_fee_rate`
  is `None` on a hand-built `AsParams`: `None` means "nobody could name this venue's maker fee as a
  fraction of price", which is not the same statement as a measured `Some(0.0)`.
</Callout>

## Assembly [#assembly]

`assemble_quote` is "the affine two-sided posting geometry shared by A-S/GLFT and the Group-B
model overrides": bid `(r − d).min(s − standoff)`, ask `(r + d).max(s + standoff)` so "inventory
skew can't push a quote across `s`", the wall clamp, a grid snap through `snap_to_tick` (which uses
`vike_model::round_to_step`, round-half-to-even), and acceptance only of "a genuine, correctly-ordered
two-sided quote that still straddles the fair mid" — `lo ≤ bid < s < ask ≤ hi`. Otherwise `None`,
the same hold contract as a one-sided book.

Three resolution-aware terms live in this file too. Inside the blackout — `in_blackout`, only under
`TimeToResolution` with a known `resolution_ts` and a positive window — `price` returns
`widest_quote`, "stay two-sided but push fills out to the extreme walls"; `effective_blackout_ms`
widens that window near the money by `1 + atm_blackout_scale·exp(−z²/2)`. `terminal_var` adds
`γ_term · w(τ) · p(1−p)` into `V` over the last `terminal_ramp_ms`, because the settlement variance
"does NOT vanish as `τ → 0` — unlike the diffusion term". `blended_anchor` pulls the priced mid
toward `p_up(underlying)` by `underlying_weight`; "only the pricing sees this — the σ̂²/κ estimators
keep the raw book mid." The rest of the resolution machinery is on
[settlement](/docs/trader/market-making/settlement).

## GLFT through the same assembly [#glft-through-the-same-assembly]

`gueant_skew_coeff` is the Guéant–Lehalle–Fernandez-Tapia stationary coefficient
`S = √(σ̂²·γ / (2·κ·A) · (1 + γ/κ)^(1 + κ/γ))`, `A` the base fill intensity at the touch "per ms,
matching the per-ms `σ̂²` — the units MUST agree". `effective_variance` feeds it to the shared
assembly as `V_eff = S/γ`, "which makes the posted depths `c1 + (½ ± q)·S` — the SAME affine form
A-S emits with `γ·V`"; the horizon, the settlement term and the Bernoulli cap "are all IGNORED here
(GLFT is horizon-free)". The `glft_equals_avellaneda_stoikov_at_matching_variance` test pins the
identity as bit-exact.

## Two paths through `price` [#two-paths-through-price]

With `ReservationModel::AsLinear`, `SpreadSource::AsOptimal`, both alpha weights,
`running_penalty_phi` and force-flatten all off, `AsState::price` returns `as_quotes` — "the
verbatim pre-Group-B call, so the fast path is byte-identical BY CONSTRUCTION". Anything else takes
the override path: swap the reservation (the LMSR walk on
[binary outcomes](/docs/trader/market-making/binary-outcomes)), add the Cartea–Jaimungal shift
([short-term alpha](/docs/trader/market-making/short-term-alpha)) and the force-flatten skew, swap the
half-spread source, then run "the SAME width ladder `as_quotes` runs" and the same `assemble_quote`.


# Binary outcomes (/docs/trader/market-making/binary-outcomes)



The Avellaneda–Stoikov layer was first written for Polymarket's 0–1 outcome tokens, and its
Bernoulli cap, unit-interval walls and resolution blackout are the bounded-price adaptations on
[Avellaneda–Stoikov](/docs/trader/market-making/avellaneda-stoikov). Two further modules give the
reservation and the half-spread models native to a binary venue. Both are "Group-B pluggables" —
`ReservationModel` and `SpreadSource` on `crates/vike-model/src/strategy/maker_params.rs` — and
both default to the A-S path, byte-identical.

## The LMSR reservation [#the-lmsr-reservation]

`crates/vike-mm/src/fairvalue.rs` is the "LMSR logistic fair-value / inventory-skew reservation
for a bounded \[0,1] outcome token". It ports Hanson's Logarithmic Market Scoring Rule "to a
live-anchored form: the binary LMSR price is the logistic `1/(1+exp(-Δ/b))` of net inventory `Δ`
over liquidity depth `b`." The reason for log-odds: "a linear cash-skew would walk a near-0/near-1
quote straight off the edge", while log-odds "keeps the reservation on the bounded \[0,1] simplex
and reproduces the LMSR 'wall' near the boundaries, where a unit of inventory moves price by
`mid·(1−mid)/b`, vanishingly small at the edges and largest at the coin-flip mid."

`lmsr_reservation(mid, net_inventory, b)` converts the live mid to log-odds, walks it, and maps
back:

```text
logit_mid = ln(mid / (1 − mid))
r         = 1 / (1 + exp( −(logit_mid − net_inventory / b) ))
```

Long YES (`net_inventory > 0`) lands "strictly BELOW `mid` (skew DOWN to sell the position off)";
short lands strictly above. Two guards keep a bad input from moving a quote: "a degenerate depth
(`b <= 0`) or a mid outside the OPEN interval `(0, 1)` … returns `mid` unchanged". Zero inventory
short-circuits to `mid` exactly rather than round-tripping through `ln` and the logistic, because
"two independently-rounded transcendentals need not compose back to `mid` bit-for-bit".

At the call site in `AsState::price`, LMSR "walks the live mid in log-odds by SIGNED net inventory
(`position`, not `q_norm`) over depth `b`; inert (returns `anchor`) off the unit interval, so a
$-scale book is unchanged." Select it with `reservation_model = "lmsr"` (or `"logistic"`); depth is
`lmsr_b`, default `100.0`, "larger ⇒ flatter walk, more subsidy at risk".

## Two half-spread sources [#two-half-spread-sources]

`crates/vike-mm/src/spread_source.rs` supplies "two \[0,1]-native half-spread SOURCES for the
maker's `half_spread` slot". Both are alternatives to the A-S `½·[γ·V + (2/γ)·ln(1 + γ/κ)]`: "they
price the spread from prediction-market microstructure instead of an inventory/vol/liquidity trio,
which is the natural fit for a \[0,1] binary-outcome venue (Polymarket up/down)."

**LS-LMSR** (Othman and Sandholm, *A Practical Liquidity-Sensitive Automated Market Maker*, EC'10).
The liquidity parameter scales with volume, `b(q) = α·Σ_i q_i`, "so the market maker's built-in
overround (Σ\_i p\_i − 1) IS a volume-scaled spread. We read that overround off as a half-spread."
`ls_lmsr_prices` implements the two instantaneous prices `∂C/∂q_i` of the binary cost function,
with the derivation in its doc — the ordinary softmax price plus a liquidity-sensitivity
correction — and `ls_lmsr_half_spread` returns `(p_yes + p_no − 1)/2`. At a symmetric book the
result is exactly `α·ln(2)`, "the pinned identity"; "more balanced books carry a WIDER spread than
lopsided ones (a near-resolved book, `p→(1,0)`, has overround → 0)". `α ≤ 0` or `Q ≤ 0` gives `0.0`.
The maker feeds it the probability split `(anchor, 1 − anchor)`, so it is "widest at p≈0.5, tight
toward the walls."

**Glosten–Milgrom** (JFE 14:71–100, 1985). "The spread is pure adverse selection: an informed
fraction `μ` trades on a known binary value `V∈{0,1}`, noise traders flip a coin, and the
competitive dealer's zero-profit bid/ask are the conditional expectations `E[V|sell]`/`E[V|buy]`.
The half-spread is the price of being picked off." `glosten_milgrom_quotes`:

```text
ask = E[V|buy]  = π·(1+μ) / ( π·(1+μ) + (1−π)·(1−μ) )
bid = E[V|sell] = π·(1−μ) / ( π·(1−μ) + (1−π)·(1+μ) )
```

`μ=0 ⇒ ask==bid==π` exactly; `μ=1 ⇒ (0, 1)`. `PI_GUARD` (`1e-12`) clamps the belief strictly
inside `(0, 1)` so the degenerate priors "never form `0/0`". `glosten_milgrom_half_spread` is
`(ask − bid)/2`, with "the `π·(1−π)` shape: maximised near `π=0.5` and → 0 as `π → 0` or `π → 1`".

Select with `spread_source = "ls_lmsr"` or `"glosten_milgrom"` (`"gm"`); the constants are
`ls_lmsr_alpha` and `gm_mu`, both `0.0` by default. On `gm_mu`, "a live `μ̂` estimate (VPIN / OFI
toxicity) is the follow-up feed" — the [VPIN](/docs/trader/orderflow/vpin) study is the named
candidate; today `gm_mu` is a hand-set constant.

<Callout type="warn" title="A zero read must not collapse the quote — floor it">
  Both sources "are floored/capped by the existing `min/max_half_spread_ticks` so a zero read never
  silently collapses the quote (use a `min_half_spread_ticks` floor with GM/LS-LMSR)." At their
  defaults both read `0.0`, and `AsState::price` runs the result through the same
  `bounded_half_spread` ladder the A-S path uses — "the stage-1 floor still guards a zero LS-LMSR/GM
  read from collapsing the two-sided quote; stage 3 refuses when no width clears the round-trip fee
  under the cap."
</Callout>

## Orthogonal by design [#orthogonal-by-design]

The two knobs are independent: `ReservationModel` "only swaps how `r` responds to inventory" and
`SpreadSource` is "orthogonal to `ReservationModel`" — "all three feed the same `half_spread` slot,
then the shared `min/max_half_spread_ticks` floor/cap and grid snap." Either non-default selection
moves `price` off its verbatim fast path onto the override path, where the Cartea–Jaimungal shift
of [short-term alpha](/docs/trader/market-making/short-term-alpha) and the force-flatten of
[settlement](/docs/trader/market-making/settlement) are added to whichever reservation was chosen, and
the posting geometry is the same `assemble_quote`. The `round_trip_fee_rate` field notes that
`vike_run::MakerMountConfig::polymarket` cannot arm the break-even floor, because "the
`Free`/`ProbabilityScaled` shapes are refused" — the operational side is on
[Polymarket operations](/docs/trader/venues/polymarket-operations).


# Market making (/docs/trader/market-making)



`crates/vike-mm/src/lib.rs` is "the HFT market-maker crate: the `SpreadMaker` reference strategy
and its pure pricing/risk helpers, extracted from vike-core … into a dedicated, CI-gated crate that
depends on `vike-model` alone. It does NOT own the runtime — vike-core's live core still MOUNTS the
maker (via a `Box<dyn Strategy<LiveBroker>>`), because `LiveBroker: HftBroker`; only the maker code
moved here, engine-agnostic over the trait."

## The seam [#the-seam]

`crates/vike-model/src/strategy/mod.rs`'s `HftBroker` is "the HFT extension of `Broker`: the
tagged-resting-order verbs a market-making strategy needs that are NOT on the portable `Broker`
common denominator" — a signed `position` read plus `submit_limit_tagged`, `modify_tagged` and
`cancel_tagged`. A `tag` is "a strategy-chosen stable id naming one resting order, so a later
modify/cancel resolves it WITHOUT the strategy ever seeing a client-order-id". The maker is written
`impl<B: HftBroker> Strategy<B>`, and because `HftBroker: Broker` "a plain `Broker`-only backtest
engine still cannot mount them, so the type system keeps documenting the HFT requirement". The
resting bid and ask carry the tags `"bid"` and `"ask"`; the maker re-prices them in place through
`modify`, "which preserves venue queue priority", rather than cancel/replace. The portable
[strategy seam](/docs/trader/strategies/index) is the parent contract.

## What composes [#what-composes]

The crate header tells the maker's history as a stack of additions, each with the same contract:
off by default, and byte-identical to the maker beneath it when off. In the `SpreadMaker` doc's
words, "the breaker decides WHICH sides quote, the skew decides their SIZES, the style + filter
decide their PRICES."

| layer                                       | builder                                                                | off state                                      | page                                                           |
| ------------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------- |
| fixed `mid ± half_spread`                   | `SpreadMaker::new(qty, half_spread)`                                   | the base                                       | [quote styles](/docs/trader/market-making/quote-styles)             |
| inventory-skew sizes                        | `with_skew`                                                            | `skew = 0.0` ⇒ both multipliers exactly `1.0`  | [inventory skew](/docs/trader/market-making/inventory-skew)         |
| per-side fill-rate breaker                  | `with_fill_breaker`                                                    | any of window/threshold/cooldown non-positive  | [inventory skew](/docs/trader/market-making/inventory-skew)         |
| quote-style registry + own-order filtration | `with_quote_style`, `with_own_order_filtration`, `with_own_order_book` | `Mid`, `filter_own = false`                    | [quote styles](/docs/trader/market-making/quote-styles)             |
| Avellaneda–Stoikov pricing                  | `with_avellaneda_stoikov`                                              | `as_state = None`                              | [Avellaneda–Stoikov](/docs/trader/market-making/avellaneda-stoikov) |
| refresh tolerance                           | `with_refresh_tolerance`                                               | `None`, or an all-zero bag                     | [refresh tolerance](/docs/trader/market-making/refresh-tolerance)   |
| ladder                                      | `with_ladder`                                                          | `levels <= 1`                                  | [ladder quoting](/docs/trader/market-making/ladder-quoting)         |
| liquidity rewards                           | `with_liquidity_rewards`                                               | `weight = 0.0`                                 | [liquidity rewards](/docs/trader/market-making/liquidity-rewards)   |
| flow toxicity                               | `with_flow_toxicity`                                                   | both knobs `0.0`, or no reading ever delivered | [short-term alpha](/docs/trader/market-making/short-term-alpha)     |

The breaker is the adverse-selection guard the plain maker lacked: it "NETS the two sides against
each other (round-trip netting): a bid fill later offset by an ask fill is a completed,
inventory-neutral round-trip … and must NOT trip the guard — only NET one-directional accumulation
on one side does." A tripped side is pulled until its cooldown expires "while the other side keeps
quoting (and re-skewing) normally."

Every layer feeds one shared tick step, `requote` — [quote emission](/docs/trader/market-making/quote-emission)
walks its stages in order.

## Config and state are split [#config-and-state-are-split]

`SpreadMaker::cfg` holds "the maker's whole CONFIG bag — every live-tunable knob, held as the SAME
`SpreadMakerParams` shape the live-parameter plane transports", and it is "deliberately
CONFIG-ONLY". The runtime state — the per-side resting snapshot, ladder rungs, breaker deadlines,
the fill window, the own-order ladder, the learned book tick — lives in sibling fields that
`apply_params` never touches, "so a live re-tune keeps resting orders, queue position, and learned
state." `Strategy::on_params_updated` hot-swaps the bag without unmounting and bumps
`params_epoch`, which "starts at `0`; observable so a caller/test can confirm a re-tune actually
landed."

One exception is written into the field doc: `cfg.avellaneda_stoikov` is "PINNED `None` — the live
A-S params' single authority is `as_state.params`", re-attached by `SpreadMaker::params` on the way
out and stripped on the way in, so no second copy can drift.

Across a restart, `crates/vike-mm/src/strategy_impl.rs`'s `SpreadMakerStateV1` persists "ONLY the
per-side fill-rate breaker's suppression deadlines and (if A-S is enabled) the online estimator's
accumulators" — not the fill window, not the resting-order cache (rediscovered by the reconcile
pass), and not the A-S params, so "a restart with a DIFFERENT tuning should price with the new
tuning, not a stale saved one."

## The lanes [#the-lanes]

`crates/vike-mm/src/strategy_impl.rs` owns the `Strategy` impl. `on_quote_tick` and
`on_order_book` both run `requote`; the book lane also learns the venue's real grid, adopted on the
L1 lane "so one `*_half_spread_ticks` can't resolve to two different spreads." `on_trade_tick`
feeds the κ tape, `on_mark` the A-S underlying anchor, `on_flow` the toxicity reading — none of
the three touches the broker; the reaction lands "at the NEXT quote in `requote`".

## From a profile [#from-a-profile]

`SpreadMaker::from_params` is the registry reader: "a bare `{}` yields the recommended A-S maker
(`AsParams::default`) and each present key overrides one knob." It "mirrors how
`vike_run::build_maker` composes the live maker (fixed seed → `with_quote_style` → A-S), minus the
reward mount-only sub-bag." The template registry carries both names —
[`spread_maker`](/docs/trader/strategies/templates/spread-maker) and
[`gueant_maker`](/docs/trader/strategies/templates/gueant-maker) — and `with_spread_model` is how "the
`gueant_maker` registry alias forces `SpreadModel::Gueant` so the same `spread_maker` knobs price
with the GLFT closed form."

<Callout type="warn" title="A typo in an enum key fails the profile — it does not fall back">
  `ParamError` exists "because `Option` could not say which of two things happened": each enum reader
  once returned `None` for an absent key and for an unrecognized one alike, so
  `spread_model = "gueant_lehale"` "silently ran Avellaneda–Stoikov while the profile named GLFT". A
  present-but-unrecognized `variance_mode`, `horizon_mode`, `price_domain`, `spread_model`,
  `reservation_model`, `spread_source`, `kappa_mode` or `style` now refuses to resolve. The one
  residual is named on `read_pricing_chains_as`: `pricing` maps to a `bool`, so `pricing = "styel"`
  still reads as `"as"`.
</Callout>

The `from_params` table also names the crypto profile: an unbounded `$`-scale asset "wants
`price_domain = "unbounded"`, `variance_mode = "raw_local"`, `horizon_mode = "constant_tau"`,
`min_half_spread_ticks = 2`, `max_half_spread_ticks = 60` — the exact knobs
`vike_run::MakerMountConfig::crypto` sets."

## Three crate rules [#three-crate-rules]

Every fold in the crate is a naive left-to-right `f64` fold with no `mul_add`, and
`crates/vike-mm/src/fits.rs`'s header carries the reason: "the expression shapes are bit-anchored
by the tests below and must not be 'simplified'." Each module restates it as house style — "naïve
folds, no `mul_add`, per the crate rule."

The other two are `crates/vike-mm/src/own_book.rs`'s header. Own-book removals go through
`shift_remove`, "never `swap_remove`, so queue order survives a cancel in the middle of a level",
because "insertion order IS venue queue order". And every own-book timestamp is "ONE caller-chosen
EVENT clock (never wall-clock)": the `_ns` suffixes "follow the HFT nanosecond convention", but
"the code never converts or divides a timestamp", and the maker feeds it an event ts that is
"epoch-MILLIS on the live quote/book/fill lanes".

The crate's second reference strategy, `XemmMaker` (`crates/vike-mm/src/xemm/mod.rs`), is complete
and tested and is reached by **no binary**: `crates/vike-run/src/xemm.rs`'s `build_live_xemm_core`
has no caller, and `crates/vike-strategy/src/registry.rs`'s `strategy_by_name` has no `xemm` arm —
so no profile, flag or feature can resolve it.
[Cross-exchange market making](/docs/trader/market-making/xemm/index) carries that record.


# Intensity fits (/docs/trader/market-making/intensity-fits)



`crates/vike-mm/src/fits.rs` holds "the A-S fill-intensity ESTIMATORS — the `κ` fits and the
base-intensity `A` profile". They are "four pure functions over a tape, no state and no venue types,
each the maximiser of one likelihood the A-S/GLFT closed forms consume." Why κ matters: per
`crates/vike-model/src/strategy/maker_params.rs`'s `KappaMode`, "`κ` sets the spread's
adverse-selection floor `(1/γ)·ln(1+γ/κ)`; only `κ` (not the base rate `A`) enters the spread."

## Three modes [#three-modes]

`KappaMode` selects which estimate `AsState::effective_kappa` prices with.

* **`Fixed`** (the default): `kappa_default`. "The online MLE is still maintained from the trade
  tape but is NOT used to price — 'available but gated'."
* **`LiveFit`**: the public-print MLE below, "gated by the `n_min` sample floor (below it, or on a
  degenerate window, it falls back to `κ_default`)."
* **`OwnFillFit`**: the censored fit over the maker's own outcomes, shrunk toward the public fit
  below `n_min` own fills. "Where `LiveFit` reads the whole tape's prints, this reads the fill
  intensity THIS maker actually realises at its own quoted distances, so `κ` reflects the adverse
  selection it truly faces."

From a profile the key is `kappa_mode` (`fixed | live_fit | own_fill_fit`), with `kappa_default`,
`kappa_min`, `kappa_max`, `n_min` and `trade_window_ms` beside it; `SpreadMaker::from_params` calls
this "the audit-F3 selector that makes the whole #790 κ-fit family reachable from a registry/harness
table."

## The public tape [#the-public-tape]

`fit_kappa` is the "size-weighted exponential MLE for the fill-intensity decay `κ`:
`κ̂ = Σw / Σ(w·δ)`, with the `n_min` sample floor and the degenerate-window guard (`Σ(w·δ) <= 0`)
both falling back to `κ_default`, and a trusted fit clamped to `[κ_min, κ_max]`." The clamps have
reasons on `AsParams`: "`κ → 0` blows `ln(1+γ/κ)` → the spread explodes" and "`κ → ∞` collapses
the spread."

The tape is fed by `Strategy::on_trade_tick` in `crates/vike-mm/src/strategy_impl.rs` — a no-op
when A-S is off — through `AsState::record_trade`, which folds "each executed trade's size-weighted
distance-from-mid into the online intensity estimator's running sums over an event-time window
(O(1) amortised)". `δ` is the trade's distance from `last_quote_mid`, the mid `requote` last priced
off; trades arriving before the first priced tick are ignored. Entries older than
`trade_window_ms` are evicted from the front and subtracted from both sums.

## The own-fill tape [#the-own-fill-tape]

`fit_kappa_censored` models "each order's fill intensity as `λ(δ) = A·exp(−κ·δ)` (δ =
distance-to-mid at placement) and treats the order as an exponential survival with that
distance-dependent rate: a FILLED order contributes its fill, a PULLED/unfilled order is a
RIGHT-CENSORED exposure." Profiling `A` out leaves κ as the root of `S1(κ)/S0(κ) = mean-fill-δ`,
where the two sums run over all orders "(fills AND censored — the censored exposures carry the
survival information)" and the right-hand side is the mean δ over filled orders only. The ratio is
monotone decreasing in κ, "so the root is found by BISECTION on `[κ_min, κ_max]` (deterministic, no
RNG)" — 80 halvings, with a target outside the bracket clamped to the near bound. No fills means
`None`: "the likelihood carries nothing to locate `κ`".

`shrink_kappa` keeps a thin own tape honest: "a LINEAR blend `w·own + (1−w)·public` with
`w = min(n_fill / n_min, 1)`", all public at zero fills and all own at or beyond `n_min`, "so a
maker prices with the robust public estimate until it has accumulated enough of its OWN fills to
trust their intensity."

The tape is built by `SpreadMaker::feed_own_outcome` in `crates/vike-mm/src/lib.rs`, "a GUARDED
no-op unless the A-S layer is on AND its `kappa_mode` is `OwnFillFit`". δ is the resting quote's
distance to the fair mid it was last priced against; exposure is the event time since that side's
last place or re-price (`quoted_ts`). The breaker's suppression pull in
[quote emission](/docs/trader/market-making/quote-emission) records "a CENSORED own outcome … BEFORE
the resting snapshot / placement clock is cleared." `AsState::record_own_outcome` drops non-finite
inputs, floors δ and exposure at 0, evicts by the same `trade_window_ms` window, and re-fits "HERE —
on the RARE own-outcome event, never on the per-tick requote path — and caches its result."

<Callout title="What survives a restart">
  `crates/vike-mm/src/strategy_impl.rs`'s `AsStateV1` persists the public tape (`trades`, `sum_w`,
  `sum_w_delta`) alongside σ̂². The own-outcome tape does not travel: `own_obs` is "NOT persisted — it
  re-warms after a restart, like the fill-rate breaker's fill window."
</Callout>

## The base intensity [#the-base-intensity]

`fit_base_intensity` profiles `A` "from the SAME censored own-order tape `fit_kappa_censored` fits
`κ` on, given a known/fitted `kappa`": once κ is fixed the log-likelihood "has a CLOSED-FORM
maximizer in `A`: `∂/∂A = D/A − S0(κ) = 0 ⇒ Â = D / S0(κ)`", `D` the count of filled orders. Units:
exposure in ms gives `Â` in "orders/MILLISECOND, matching the per-ms `σ̂²` the GLFT `S` consumes".

Only the Guéant model reads it. `AsState::effective_a` returns the cached `Â` "once the own-fill
tape carries fills (i.e. under `KappaMode::OwnFillFit`), else the fixed `AsParams::base_intensity_a`.
Only consulted under `SpreadModel::Gueant` (A-S ignores `A`), so an A-S maker is byte-identical
either way." The fixed default is `1.0`, described on the field as "a placeholder that MUST be
calibrated to the venue's touch flow before a live GLFT mount".

## What the tests pin [#what-the-tests-pin]

The estimators are bit-anchored — the header says the expression shapes "must not be
'simplified'" — and the own-fill suite in `fits.rs` pins recovery: on a synthetic tape with fill
counts proportional to `0.5ʲ` at distances `(j+1)·Δ`, `censored_mle_recovers_known_kappa`
requires κ̂ within `1e-3` of `ln 2 / Δ`, and that κ̂ solves the score equation to `1e-6`. The
censored orders that equalise each level "are ESSENTIAL: drop them and the weighting (hence the
recovered κ) changes." `effective_kappa_owns_fit_and_off_modes_ignore_the_tape` pins that `Fixed`
never reads the own tape even when populated. The formulas themselves sit inside
[Avellaneda–Stoikov](/docs/trader/market-making/avellaneda-stoikov).


# Inventory skew (/docs/trader/market-making/inventory-skew)



`crates/vike-mm/src/skew.rs` holds the two pure risk helpers of the
[spread maker](/docs/trader/strategies/templates/spread-maker): `skew_multipliers`, which shapes the
two quote **sizes** from inventory, and `net_signed_fills`, the round-trip netting the fill-rate
circuit breaker trips on. Both were moved out of the crate root verbatim and are isolated so they
unit-test without a runtime. Neither touches a price: prices come from the style or the
[Avellaneda–Stoikov layer](/docs/trader/market-making/avellaneda-stoikov), the skew decides sizes, and
the breaker decides which sides quote at all.

## Size shaping [#size-shaping]

`skew_multipliers(position, target, max_inventory, skew)` returns a `(bid_mult, ask_mult)` pair
applied to the base quote size. With `imbalance = clamp((position − target) / max_inventory, −1, 1)`:

```text
bid_mult = max(1 − skew · imbalance, 0)
ask_mult = max(1 + skew · imbalance, 0)
```

Its doc lists the five properties the `skew_sizing` tests cover. **Neutral**: `skew <= 0`, or a
degenerate `max_inventory <= 0`, yields exactly `(1.0, 1.0)` for any position, reproducing the
fixed-size path bit-for-bit — and guarding the division. **Directional**: long (`position > target`)
shrinks the bid and grows the ask, leaning to sell the position down; short mirrors.
**Symmetric** about the target. **Monotonic**: the bid is non-increasing and the ask
non-decreasing as position rises. **Clamped**: beyond `±max_inventory` the multipliers saturate at
`1 ∓ skew`, floored at zero so an over-unit `skew` can never request a negative size. The crate
header adds where the position comes from: the maker reads its own signed position off the broker
through `HftBroker::position`, and the default target of `0` means stay flat.

`SpreadMaker::with_skew(target_inventory, max_inventory, skew)` is the builder; the TOML keys of
the same names default to `0.0` / `1.0` / `0.0`, which `SpreadMaker::from_params` notes are
exactly the constructor's neutral values, so a keyless table is byte-identical with skew off. The
shaped size is the base every [ladder](/docs/trader/market-making/ladder-quoting) rung multiplies, and
the [reward](/docs/trader/market-making/liquidity-rewards) `min_size` floor is applied after it.

## Round-trip netting [#round-trip-netting]

`net_signed_fills(fills, now, window_ms)` sums the **signed** fill size within `[now − window_ms,
now]`: `+size` per bid (buy) fill, `−size` per ask (sell) fill. The sign *is* the round-trip
cancellation — a bid fill later offset by an equal ask fill sums back toward zero, which is a
completed, inventory-neutral round trip, the desired market-making outcome, and must not trip the
guard. Only net one-directional accumulation survives the sum: a result at or above `+threshold`
means bids are being repeatedly hit without offsetting asks — adverse selection on the bid, a
falling market lifting it — and suppresses the **bid**; at or below `−threshold`, the mirror
suppresses the **ask**. Every timestamp in the window is a fill or quote event stamp
(`FillRec::ts`); wall-clock is never read, matching the runtime's event-clock determinism.

## The breaker [#the-breaker]

`SpreadMaker::with_fill_breaker(window_ms, net_fill_threshold, cooldown_ms)` arms it, and
`SpreadMaker::breaker_enabled` is the single gate every breaker path checks: all three knobs must
be positive, and any non-positive value leaves it off, so the strategy reduces exactly to the
skew-only maker with no fill tracking and no suppression. `Strategy::on_fill` in
`crates/vike-mm/src/strategy_impl.rs` records each fill at its event timestamp, evicts everything
older than the window — the window rides the latest fill — nets, and arms the over-hit side's
cooldown from the fill's timestamp. The threshold it compares against is
`net_fill_threshold / pull_accel_mult(fill.ts)`, the [settlement](/docs/trader/market-making/settlement)
acceleration, which is exactly `1.0` unless a resolution is known, so the default comparison is
bit-for-bit the unchanged threshold; the pure netting is untouched.

The arm is acted on by `requote`, from either lane: a side is suppressed while the triggering
event's timestamp is still before its `suppressed_until` deadline, its resting quote is **pulled**
through `HftBroker::cancel_tagged`, and it is not re-quoted until the cooldown expires, while the
other side keeps quoting and re-skewing normally. The crate header calls this the adverse-selection
guard the plain maker lacked.

<Callout type="warn" title="A pull is never tolerance-gated">
  The [refresh tolerance](/docs/trader/market-making/refresh-tolerance) is consulted only on the re-price
  path, so it can never suppress the breaker's suppression cancel — a quote that must come off the
  book always comes off. A laddered side pulls every rung.
</Callout>

## In the cross-exchange maker [#in-the-cross-exchange-maker]

The [xEMM](/docs/trader/market-making/xemm) reuses both helpers with two deliberate differences.
`XemmMaker::with_skew` shapes the maker leg's sizes off the **owned** hedge ledger's `maker_pos`,
never a broker read, for the reasons the [hedge ledger](/docs/trader/market-making/xemm/hedge) page
carries. And `XemmMaker::record_maker_fill` folds **maker-leg fills only** into the breaker window:
hedge-leg fills are the strategy's own mechanical offset, not market flow, and netting them would
cancel every real one-sided signal to exactly zero. Its module doc ranks the breaker as the third
of four independent safety layers — the one that fires on the **symptom** regardless of whether
any pricing model is right, so a wrong assumption costs bounded one-sided flow.

The end-to-end suite is `crates/vike-mm/src/tests/breaker.rs`: round-trip netting, per-side
suppression and cooldown expiry, the accelerated pull near a binary resolution, the OFI-to-toxicity
synthesis that feeds the same guard, and the breaker-off reduction.


# Ladder quoting (/docs/trader/market-making/ladder-quoting)



`crates/vike-mm/src/ladder.rs`'s `desired_side` is the pricing half of ladder quoting: given one
side's level-0 context — the price and size today's single quote would use — it maps a
`LadderParams` onto that side and returns the rungs as absolute `(price, size)` pairs, rung 0 first
and deepest last. The data half lives one layer down, in `vike-model`:
`crates/vike-model/src/strategy/maker_params.rs`'s `LadderParams` and `LadderLevel`, plus the
size-profile expansion `LadderParams::rungs`. The header names why the split runs that way: the
params ride the typed live-parameter payload, so they have to be a `Copy` scalar bag in the bottom
layer, exactly the split [quote styles](/docs/trader/market-making/quote-styles) already keep between
`QuoteStyle` (data in `vike-model`) and `book::priced` (arithmetic here). Like `skew`, `book` and
`refresh`, the geometry is isolated so it unit-tests without a runtime or a broker.

## The geometry [#the-geometry]

Rung 0 is **always** `(level0_px, base_qty)` — a laddered maker's innermost order is bit-for-bit
the quote the single-order maker would have rested. Rung `k` steps `k · offset_step` further
**out**, away from the reservation price: a bid rung sits that far below the level-0 bid, an ask
rung that far above the level-0 ask. The step's absolute size is the ladder's `LadderOffsetUnit`
scale times `offset_step`, and the unit is the one grid-agnostic choice in the design:

* `HalfSpread` (the default) measures the step in multiples of the level-0 half-spread, the gap
  between the reservation price and level 0's quote. It needs no tick grid at all, so a `1.0` step
  reads identically on a 0..1 prediction market and a five-figure crypto book.
* `Ticks` steps by the venue grid the maker already quotes on. It needs the book's positive
  `tick_size`; on an unknown grid the ladder collapses to level 0 only.

Sizes are a multiplier of the base size, so the [inventory skew](/docs/trader/market-making/inventory-skew)
that shapes level 0 flows through every rung. `LadderSizeProfile::Linear` (the default) is
arithmetic growth, `size_k = base · (1 + k·(ratio − 1))` — a ratio of `2` gives multipliers
`1, 2, 3, 4…`; `Geometric` is `size_k = base · ratio^k` — the same ratio gives `1, 2, 4, 8…`. Both
put level 0 at exactly `1.0 ×` the base, and a `size_ratio` of `1.0` makes every rung the base size
under either profile. A ratio below `1` shrinks deeper rungs; the geometric profile decays without
ever reaching zero, the linear one can.

`LadderParams::levels` counts rungs per side **including** level 0. `levels <= 1` is off:
`LadderParams::is_active` is false, the maker rests exactly today's one order per side under the
`"bid"`/`"ask"` tags, and the pre-feature verbs are reproduced byte-identically. The module is
reached only when the ladder is active (`levels >= 2`); nothing in it logs or allocates on the
default path.

## Two guards — never place a nonsensical rung [#two-guards--never-place-a-nonsensical-rung]

The header lists exactly two ways a rung is refused. With **no usable price scale** —
`unit_scale <= 0`, a `Ticks` unit on an unknown grid or a zero or crossed half-spread — deeper
rungs would collapse onto level 0's price, so the ladder is cut to level 0 only. With **a non-positive
rung size** — a decaying `Linear` profile past zero, or a skew-floored base — the rung is not
placeable; because both profiles are monotone in `k`, the walk stops at the first such rung and the
returned set is the contiguous placeable prefix `0..m`. The in-file tests pin both: a five-level
linear ladder at ratio `0.5` on a base of `2.0` returns two rungs, and a four-level ladder with a
zero half-spread returns one.

## How the maker drives it [#how-the-maker-drives-it]

`crates/vike-mm/src/quote.rs`'s `requote` takes the ladder branch at its stage (5), after pricing,
the reward fold, the skew and the per-side suppression verdict have already produced this tick's
`(bid_px, ask_px)` and sizes. The rung geometry is taken from **this tick**: `half` is
`(ask_px − bid_px)/2`, `tick` is the book view's `tick_size`, and each side's `base_qty` is its
already-skewed level-0 size. Rungs carry tags `"bid0".."bidN"` / `"ask0".."askN"`, and
`SpreadMaker::requote_ladder_side` diffs the desired set against what is resting:

* **suppressed** by the [fill-rate breaker](/docs/trader/market-making/inventory-skew): pull every
  resting rung of that side and place nothing — the whole-side analogue of the single path's
  suppression cancel, so a rung is never stranded;
* otherwise, for each desired rung `k`: submit it if no rung `k` is resting, else modify it in
  place unless the per-rung [refresh tolerance](/docs/trader/market-making/refresh-tolerance) says the
  drift is churn; then cancel any resting rung beyond the desired count — the ladder shrank, through
  a re-tune with fewer levels or one of the guards above.

A fill on a side sets that side's `refresh_stale` flag, which forces every rung through the modify
arm once so a partial fill's size top-up is never read as "no change". The tolerance is never
consulted on a pull.

<Callout type="warn" title="A rung that dies at the venue is not freed">
  "What is resting" is the maker's own `SideState::rungs` vec, written only by the diff above — and
  nothing clears a rung the venue terminated. `crates/vike-mm/src/strategy_impl.rs`'s
  `on_order_event`, the order-death hook that frees a single quote's slot after a fill, a cancel or a
  reject, matches the tags `"bid"`/`"ask"` exactly and returns on any rung tag. Its doc says so: "⚠
  &#x2A;*The LADDER path is NOT covered.** … A laddered maker therefore still wedges per-rung; the ladder
  is off by default (`levels >= 2`), and the single-quote path — the one the live mount runs — is
  closed." A rung's tag carries its index into `rungs`, so freeing one would renumber every deeper
  rung's tag away from the order actually resting under it; closing this needs a per-rung liveness
  slot rather than a dense vec, which is a reshape of the diff. Until then a filled, canceled or
  rejected rung stays in the vec and every later tick re-prices a terminal order through
  `modify_tagged`.
</Callout>

Two retirements handle mode switches: `SpreadMaker::retire_single_order` cancels the leftover
`"bid"`/`"ask"` on the way **into** ladder mode, and `SpreadMaker::retire_ladder_orders` cancels
resting rungs on the way **out** — a guarded no-op while the rung vector is empty, which is always
the case on the never-laddered path, so the single-order tail stays byte-identical.

<Callout title="It composes rather than replaces">
  `SpreadMaker::with_ladder`'s doc spells the composition: the style or
  [Avellaneda–Stoikov layer](/docs/trader/market-making/avellaneda-stoikov) sets rung 0's price, the skew
  shapes the base size every rung multiplies, and own-order filtration subtracts the rungs — the doc
  recommends `SpreadMaker::with_own_order_book`, which tracks N orders, over the single-snapshot
  filtration. The ladder rides the live-parameter plane, so `on_params_updated` can turn it on or
  off or re-shape it without a remount.
</Callout>

The behaviour suite is `crates/vike-mm/src/tests/ladder_quoting.rs`, whose header names what it
covers: N rungs per side diffed to the minimal verb set, the single-quote reduction at
`levels <= 1`, per-rung tolerance, whole-side pulls, and live toggling. Where the ladder sits in the
one shared tick step is on [quote emission](/docs/trader/market-making/quote-emission).


# Liquidity rewards (/docs/trader/market-making/liquidity-rewards)



`crates/vike-mm/src/reward.rs` is two things in one file: the **pure reward model** — how a
sampling-reward program scores a resting order — and the
[spread maker](/docs/trader/strategies/templates/spread-maker)'s fold that uses that shape to place its
quote. It is net-new Rust with no Python twin — the header says parity here means self-consistent
reference-value pinning and neutral reduction, not oracle bits — and every fold is a naive `f64`
fold with no `mul_add`, per the crate rule.

## The model [#the-model]

The header describes the shape it models — Polymarket's sampling reward. A rewardable market pays
a proportional share of a per-market daily pool for resting liquidity near the midpoint, sampled
per minute. Per order the closeness score is

```text
S(v, s) = ((v − s) / v)²
```

where `v` is the market's `max_spread` from the midpoint in cents and `s` the order's spread from
the size-cutoff-adjusted midpoint in cents. The score is quadratic — closer to the mid earns
**superlinearly** more — and an order counts only when it is within the band (`s ≤ v`) and at least
`min_size` shares. The per-side sum `Σ S·size` is combined two-sidedly: with the midpoint inside
`[0.10, 0.90]` the market scores `max(min(Q_one, Q_two), max(Q_one, Q_two) / c)` with `c = 3`, so
quoting one side alone earns a third of it; strictly outside that range it scores
`min(Q_one, Q_two)` — **both sides required**, a missing side scores nothing. The absolute payout is
irrelevant to the maker; only this shape drives its quote.

The three constants are public — `REWARD_MIDPOINT_LO` (`0.10`), `REWARD_MIDPOINT_HI` (`0.90`) and
`REWARD_SINGLE_SIDED_DIVISOR` (`3.0`) — and so are the three scoring functions `spread_score`,
`side_score` and `q_min`. The crate root explains why the module is `pub`: a Polymarket mount or an
analysis can compute expected reward with them, while the maker's own fold helpers stay
crate-private. `spread_score` returns `1.0` at the mid, `0.0` at the band edge and zero outside it,
for a negative spread or for a non-positive band; the tests pin that the same one-cent tightening
is worth more near the mid than near the edge.

## The fold [#the-fold]

`clamp_into_band(mid, bid_px, ask_px, params)` pulls a candidate two-sided quote **into** the band.
With `band = max_spread_cents / 100` in 0..1 price units, each side's spread from the mid is capped
at `s_target = band · (1 − weight)`. The doc states the two properties that matter: the maker never
quotes wider than the Avellaneda–Stoikov candidate wanted — a tighter A-S side is honoured — but a
too-wide side is pulled in to at most `s_target`, which is at most the band, so the side always
qualifies. Because it never widens a side, it can only ever raise the reward score. A larger
`weight` means a tighter cap, closer to the mid, more reward and more adverse selection: `weight`
**is** the reward-versus-A-S dial. The pulled price is deliberately left un-snapped — the A-S
grid-snap and wall-clamp already ran upstream and the venue mount re-snaps. Off (`weight <= 0`, or
a non-positive band) returns the input unchanged bit-for-bit, the byte-identical default.

`moas_holds` is the min-order-age gate. It answers `true` — skip the re-price, let the quote keep
ageing toward the reward floor — only while reward chasing is active with a positive
`min_order_age_ms`, the side has rested less than that, **and** the resting quote is still safely
in-band around the mid (spread in `[0, band]`). Out-of-band or crossed returns `false`, so a safety
re-price always fires. It is never consulted on a place, pull or fill path; `quote.rs`'s
`reward_moas_holds` also answers `false` on a fill-stale side, and it composes with the
[refresh tolerance](/docs/trader/market-making/refresh-tolerance) — either may skip — rather than
replacing it.

## Where it sits in the tick [#where-it-sits-in-the-tick]

`crates/vike-mm/src/quote.rs`'s `requote` runs the fold at its stage (2b), immediately after
pricing. Two details there are load-bearing. The band is scored off the **book midpoint**, computed
from the touch, not off the A-S reservation the candidate is centred on. And the fold is skipped
entirely inside the A-S near-resolution **blackout**: inside it the maker quotes at the walls, and
reward-clamping it back into the band would farm rewards straight into the resolution vol spike.
Stage (3b) then floors each reward-active side's size **up** to `min_size` — never down — after the
[inventory skew](/docs/trader/market-making/inventory-skew) has shaped it, and that floored base flows
into rung 0 of a [ladder](/docs/trader/market-making/ladder-quoting).

<Callout type="warn" title="Two safety authorities outrank the fold">
  The header names them: the A-S blackout and the fill-rate breaker. The caller skips the fold inside
  a blackout, and a suppressed side is pulled regardless of any reward hold. A rewards-shaped quote
  never quotes through a blackout to farm rewards. The behaviour suite,
  `crates/vike-mm/src/tests/liquidity_rewards.rs`, tests exactly that pair alongside the band clamp
  and the age hold.
</Callout>

## The knobs [#the-knobs]

`crates/vike-model/src/strategy/maker_params.rs`'s `RewardParams` is nested as
`Option<RewardParams>` in the maker's params; `None`, and any `weight <= 0`, is off. `weight` is
the intensity in `[0, 1]`, clamped outside it. `max_spread_cents` is the band half-width in cents —
`3.0` is ±3¢, ±0.03 on a 0..1 market — and a non-positive value is off. `min_size` is the
eligibility floor in shares; `0.0` imposes none. `min_order_age_ms` is the program's minimum order
age, Polymarket's being about `30_000`; a non-positive value disables the age gate.
`RewardParams::default` is a Polymarket-shaped starting point that is still **off** — `weight
0.0`, `3.0` cents, no size floor, `30_000` ms — so a `Some(RewardParams::default())` is inert until
`weight` is raised. `SpreadMaker::with_liquidity_rewards` is the builder.

The type's doc draws the layering line: this is the **strategy half**. A
[Polymarket](/docs/trader/venues/polymarket) mount parses its live market config — `max_spread`,
`min_size`, `min_order_age`/`moas` — and feeds it here as plain parameters, so `vike-mm` needs no
venue dependency. The rest of quoting a bounded \[0,1] token — the LMSR fair value and the spread
sources — is on [binary outcomes](/docs/trader/market-making/binary-outcomes), and the resolution-side
mechanics on [settlement](/docs/trader/market-making/settlement).


# Multi-asset (/docs/trader/market-making/multi-asset)



`crates/vike-mm/src/multi_asset.rs` is the "multi-asset (correlation-aware) Guéant market-making
pure core — the covariance-matrix generalization of the single-asset A-S/GLFT inventory penalty".
It ports the Bergault–Guéant result (Guéant, *Optimal market making*; Bergault and Guéant, *Size
matters for OTC market makers*, arXiv 1606.01862 and 1810.04383): "for a maker holding an inventory
VECTOR `q` across N correlated assets with a returns covariance matrix `Σ` (per-ms σ², symmetric
PSD) and risk aversion `γ`, the reservation-price skew for asset `i` is the i-th component of the
matrix-vector product".

```text
skew = γ · (Σ · q)          →     skewᵢ = γ · Σⱼ Σ[i][j]·q[j]
rᵢ   = mᵢ − skewᵢ
```

<Callout type="warn" title="Built, tested, and called by nothing on a live path">
  `crates/vike-mm/src/lib.rs` declares the module under `#[allow(dead_code)]`: it was "written ahead
  of the live multi-symbol maker mount (a DEFERRED follow-up), so nothing on a live path calls it
  yet; `#[allow(dead_code)]` keeps the merge-gate clippy green until the mount wires it in." Every
  statement below is about a pure function with in-file tests, not about a maker you can mount.
</Callout>

## Why a matrix [#why-a-matrix]

The header's argument: "This is the exact generalization of the single-asset reservation term
`r = s − q·γ·V`: the SCALAR variance penalty `q·γ·V` becomes the VECTOR penalty `γ·(Σ·q)`. On a
DIAGONAL `Σ` (uncorrelated assets) it collapses back to N independent single-asset makers —
`skewᵢ = γ·Σ[i][i]·q[i]` — so the value of the matrix form is entirely in the OFF-DIAGONAL terms: a
position in a CORRELATED asset `j` leans asset `i`'s reservation too. Holding a long BTC-perp
inventory therefore already skews the ETH-perp quote down, hedging the correlated exposure a fleet
of independent makers would each ignore — that cross-asset lean is the whole reason to run one
correlated maker over N separate ones."

The single-asset term it generalizes is `crates/vike-mm/src/avellaneda.rs`'s
`as_reservation_price`, on the [Avellaneda–Stoikov](/docs/trader/market-making/avellaneda-stoikov)
page.

## The two functions [#the-two-functions]

`multi_asset_skew(inventory, cov, gamma)` returns the vector `γ · (Σ · q)`; element `i` is
"`gamma · Σⱼ cov[i][j]·inventory[j]` (naive left-to-right fold, no `mul_add`)". Its guard is
deliberate: "a DIM MISMATCH — `cov` not square-of-side `inventory.len()` … returns a ZERO vector of
length `inventory.len()` (the inert, no-skew answer), rather than panicking or silently reading a
ragged matrix." An empty inventory returns an empty vector.

`multi_asset_reservation(mids, inventory, cov, gamma)` returns `mids[i] − skew[i]`, "the multi-asset
twin of `as_reservation_price`'s `s − q_norm·γ·V`. The shared quote assembly would post each side
around `mids[i] − skewᵢ`." On a `mids`/`inventory` length disagreement it falls back to the raw
mids — the same inert answer, one level up.

The dense matrix math is hand-rolled: "no linear-algebra crate — the matrices are tiny (N assets a
maker quotes, single digits), so a plain nested naive fold is both simplest and keeps the workspace
dependency/`cargo deny` surface flat." Two things are the caller's job, not this module's: "`Σ`
symmetry/PSD is the CALLER's contract (a covariance estimator's job), NOT enforced here."

## What the tests pin [#what-the-tests-pin]

* `diagonal_cov_reduces_to_independent_single_asset`: on a diagonal Σ each `skewᵢ` equals
  `γ·cov[i][i]·q[i]`, and the reservation matches `as_reservation_price` per asset "bit-for-parity".
* `positive_off_diagonal_leans_correlated_asset`: a long position in A with B flat and a positive
  `cov[1][0]` gives B a positive skew, so "B's reservation `mid_B − skew_B` is pulled DOWN even with
  zero B inventory: the cross lean."
* `negative_off_diagonal_flips_the_lean`: a negative off-diagonal leans a flat B up.
* `hand_computed_2x2_correlated_example`: with `γ = 0.5`, `q = [2, −3]` and
  `Σ = [[2, 1], [1, 2]]`, the skew is `[0.5, −2.0]` and mids `[100, 50]` become `[99.5, 52.0]`.
* `dim_mismatch_returns_zeros`: wrong row count, a ragged row, and a mids/inventory mismatch all
  take the inert path.

## The read a mount will need [#the-read-a-mount-will-need]

The single-symbol seam cannot supply an inventory vector. `crates/vike-model/src/strategy/mod.rs`'s
`MultiHftBroker` is "the MULTI-SYMBOL extension of `HftBroker`: the ONE extra read a
correlation-aware market maker needs that the single-symbol `HftBroker` cannot express — the signed
net inventory of a NAMED symbol", `position_of(symbol)`, "so a maker quoting N correlated
instruments can read the WHOLE inventory vector `q` its covariance-matrix skew (`γ·Σ·q`, see
`vike_mm::multi_asset`) folds over." Because `MultiHftBroker: HftBroker`, a broker that answers
`position_of` can still mount any single-symbol maker, "and a plain single-symbol engine simply
cannot mount a maker that needs the multi read (the type system documents it)."

That trait exists; the maker that consumes it, and the covariance estimator that would own Σ, are
the deferred follow-up the module was written ahead of. The [index](/docs/trader/market-making/index)
lists what is mounted today.


# Quote emission (/docs/trader/market-making/quote-emission)



`crates/vike-mm/src/quote.rs` is "the maker's QUOTE-EMISSION unit — the one shared tick step both
`Strategy` lanes drive". `SpreadMaker::requote` "is the pipeline: own-filter the public book →
price (A-S layer or the pure `QuoteStyle` placement) → reward-band clamp → inventory-skew the sizes
→ flow-toxicity widen/cut → per-side breaker suppression → LADDER or SINGLE placement. The STAGE
ORDER is semantic (each stage consumes the previous stage's `(price, size)`), and every stage's
'off ⇒ byte-identical' contract is stated inline at the stage that owns it." It "stays ONE
straight-line function rather than a guard-stage pipeline: this crate runs on the p99 core thread,
and inline is what makes the neutral-reduction argument checkable by reading."

## The two lanes [#the-two-lanes]

Both are in `crates/vike-mm/src/strategy_impl.rs`. `on_quote_tick` builds a one-level-per-side
`BookView` from the touch, on the grid "LEARNED from the L2 book lane (`learned_book_tick`) when one
has been seen, else the configured `tick_size` param". `on_order_book` builds a view from the top
`depth_levels + 2` levels of the `L2Book` — "enough to index the `Depth` level AND still expose a
genuine best after filtration removes our own top-of-book level" — and stamps the tick with the
mount's `now`. `ts` everywhere is "the triggering event's EVENT ts (quote/book), never wall-clock."

## The stages [#the-stages]

**(1) Own-filter.** Only when `filter_own` is set. "Two filtration backends behind the ONE
`filter_own` gate: the opt-in `OwnOrderBook` ladder … when it is mounted, else the original
single-snapshot pair". On the default path the raw book is borrowed with no clone. Both backends
are on [quote styles](/docs/trader/market-making/quote-styles).

**(2) Price.** The signed inventory is read once from `HftBroker::position`. If A-S state is
present, `AsState::price` produces the pair (and advances σ̂²); otherwise `BookView::priced` applies
the selected `QuoteStyle`. A `None` means "no valid two-sided quote (book lacks a side / A-S pinned
at a wall) — hold the current resting orders untouched this tick".

**(2b) Reward clamp.** With a positive reward `weight`, `clamp_into_band` pulls the pair into the
venue's reward band, scored off the book midpoint, "not the A-S reservation the candidate is centred
on". It is skipped inside the A-S blackout: "the maker quotes at the walls (A-S widest) and must
NOT be reward-clamped back into the band — that would farm rewards straight into the resolution vol
spike." See [liquidity rewards](/docs/trader/market-making/liquidity-rewards).

**(3) Sizes.** `skew_multipliers` shapes `qty` per side from inventory versus target — "neutral
params yield (1.0, 1.0)". (3b) bumps each side up to the reward `min_size`, never down. See
[inventory skew](/docs/trader/market-making/inventory-skew).

**(3c) Toxicity.** With a non-zero `ToxicityParams` bag and a reading in hand, the toxic side is
pushed further from mid by `flow · widen · half` — `half` being this tick's `(ask_px − bid_px)/2`,
"captured BEFORE any widen so both sides scale off the SAME base spread" — and its size cut by
`(1 − flow · size_cut).max(0)`. (3c-i) synthesizes the reading from OFI when no external one has
ever arrived; [short-term alpha](/docs/trader/market-making/short-term-alpha) has the conditions.

**(4) Suppression.** A side is suppressed while `ts < suppressed_until` with the breaker enabled,
or when the toxicity cut drove its size to `0` while the guard is active. That second clause is
deliberately guard-scoped: on the default path "a side can reach `0` only via an extreme inventory
skew whose long-standing place-at-zero behavior is preserved".

**(5) Placement.** An active ladder (`levels >= 2`) rests N rungs per side from this tick's pair;
otherwise the single-order tail runs, bid first then ask. Switching modes retires the other mode's
orders first (`retire_single_order`, `retire_ladder_orders`), each "a guarded no-op" when there is
nothing to retire. Rungs are on [ladder quoting](/docs/trader/market-making/ladder-quoting).

## One side, three arms [#one-side-three-arms]

`requote_single_side` is the collapsed per-side tail, keyed by the tag `"bid"` or `"ask"`:

* **Suppressed:** pull the resting quote with `cancel_tagged`, "recording a CENSORED own outcome
  for the OwnFillFit κ MLE BEFORE the resting snapshot / placement clock is cleared."
* **Not resting:** `submit_limit_tagged`.
* **Resting:** `modify_tagged` in place, "additionally gated by the order-refresh TOLERANCE
  (`refresh_skips`) and the reward min-order-age hold (`reward_moas_holds`): a target that barely
  moved leaves the resting order — and its queue position — untouched, sending nothing."

The header is explicit that the two gates "are reachable ONLY from the re-price arm: a place or a
pull is never gated." `refresh_skips` answers `false` at once when no tolerance is configured, when
nothing is resting, or when the side is `stale` — a fill has invalidated a snapshot that "is the
maker's INTENDED quote but the venue-side remainder is smaller, so the comparison would wrongly read
'no change' and the partial-fill size top-up would be lost." `reward_moas_holds` short-circuits the
same way, "so a safety re-price (a mid that ran the quote out of the band) always fires." The
arithmetic behind the first gate is on [refresh tolerance](/docs/trader/market-making/refresh-tolerance).
Every arm updates that side's `SideState` and mirrors its verb into the own-order ladder when one
is mounted.

## The hold that speaks [#the-hold-that-speaks]

<Callout type="warn" title="An unpriced tick is announced on the edge, not swallowed">
  `requote`'s early return on `None` "was the maker's one wholly silent hold". `SpreadMaker::note_no_quote`
  now warns once when a hold episode opens — "maker HOLDING: the book priced no two-sided quote …
  Zero levels on a side means the FEED is not delivering that side — check the venue subscription
  before touching the maker's tuning" — and `note_quote_resumed` warns once when it closes. The
  `no_quote_holding` field doc carries the incident: a maker "can hold forever with `orders:0`,
  `fault:null` and an empty journal, which is exactly the state prod2 sat in on 2026-08-17 across
  \~112k summary `seq` while its bybit market-data socket carried keepalives and no `orderbook.50`
  data." The fee-floor warn could not speak, "because `AsState::price` returns at
  `fair_value(view)?` BEFORE reaching it".
</Callout>

When the break-even refusal is the cause, `note_no_quote` says nothing and does not latch:
`AsState::note_fee_floor` "has already announced the hold with the two numbers that make it
actionable, and it announces its own recovery." Both warns are edge-triggered because the requote
is the vike-core hot fold, whose rule is "instrument per-order boundaries and fault transitions
only."


# Quote styles (/docs/trader/market-making/quote-styles)



Where the two quote prices land on the book, when the Avellaneda–Stoikov layer is not pricing, is
a `QuoteStyle`. `crates/vike-model/src/strategy/maker_params.rs` holds the enum — "a small registry
of PURE styles" that lives in the bottom layer "so it can ride the typed live-params payload" — and
`crates/vike-mm/src/book.rs` holds the arithmetic, because "it needs this crate's private book
view."

## The book view [#the-book-view]

`BookView` is "a normalized, best-first view of one book that the `QuoteStyle` registry + own-order
filtration are PURE functions of. `bids` are highest-price first, `asks` lowest-price first; each
level is `(price, size)`." `tick_size` is the venue grid: an L2 book carries its own
(`BookView::from_l2`, the `n` best levels), and the L1 lane supplies "the venue tick LEARNED from
the L2 book lane (`learned_book_tick`) when one has been seen, else the configured `tick_size`
param (pure-L1 fallback)" (`BookView::from_quote`, exactly one level per side) — so one
`*_half_spread_ticks` can't resolve to two different spreads across the lanes. A `0.0` grid means
"`Top` can't step and filtration is inert."

## The four styles [#the-four-styles]

`BookView::priced(style, half_spread, depth_levels)` returns `None` when the book lacks a side.
Otherwise:

| style           | bid                 | ask                 | note                                                                                                       |
| --------------- | ------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------- |
| `Mid` (default) | `mid − half_spread` | `mid + half_spread` | `mid = 0.5·(best_bid + best_ask)` — "the ORIGINAL SpreadMaker pricing, reproduced bit-for-bit"             |
| `Join`          | `best_bid`          | `best_ask`          | "quote at the touch"                                                                                       |
| `Top`           | `best_bid + tick`   | `best_ask − tick`   | "one tick in front; … a `0.0` grid collapses `Top` to the touch"                                           |
| `Depth`         | `bids[n].price`     | `asks[n].price`     | `n = depth_levels`, "clamped to the deepest available level (so a 1-level L1 view collapses to the touch)" |

`half_spread` is read by `Mid` only and `depth_levels` by `Depth` only. The builder is
`SpreadMaker::with_quote_style(style, depth_levels, tick_size)`; from a profile the keys are `style`
(`top | join | mid | depth`) and `depth_levels`, which `from_params` exposes so "a backtest profile
can sweep the fill-rate-driving placement, not just the pricing model."

<Callout type="warn" title="The style prices only when A-S does not">
  `read_pricing_chains_as` on `SpreadMaker::from_params`: `pricing = "as"` — and absent — chains the
  A-S layer, "which makes the `style` key INERT (`requote` bypasses the `QuoteStyle` placement
  whenever A-S state is `Some`)". `pricing = "style"` skips A-S "so the selected placement
  (`style`/`depth_levels`) actually prices — the registry path where the `style` key finally does
  something (audit F8)." A `style` line under the default `pricing` changes nothing.
</Callout>

## Single-snapshot filtration [#single-snapshot-filtration]

`filter_own` in `book.rs` subtracts "our OWN resting orders from the public book so the maker never
joins or leans on its own quote — the correctness fix for quoting on the same feed it consumes."
For each own `(price, size)` it finds the level at the same tick on that side and subtracts the
size; "a level whose remaining size is `<= 0` is REMOVED, so the derived best shifts to the next
genuine market level (exactly what stops a `Top`/`Join` maker from stepping in front of — or resting
on — itself)." Matching is by tick index through `subtract_own`, which "mirrors `L2Book`'s own
quantization"; with no grid it is a no-op.

It is enabled by `with_own_order_filtration` and is OFF by default, which `crates/vike-mm/src/lib.rs`
lists among the opt-in refinements that COMPOSE with the rest. Turning it on changes pricing
bit-for-bit. The subtracted pair is the
per-side `SideState::own` snapshot — "the maker's INTENDED quote, not the venue-side remainder".

## The own-order ladder [#the-own-order-ladder]

`crates/vike-mm/src/own_book.rs` exists because the single snapshot "is wrong in two ways the moment
either assumption breaks": "Multiple own orders per level" — a ladder or an in-flight replace has N
orders at a price, and "the single snapshot can only subtract the last one it remembered" — and
"The accepted→public race": a venue acks "microseconds before the public market-data feed shows it.
Subtracting it in that window removes depth the feed never added — inventing a phantom-empty level
and pushing a `Top`/`Join` maker to quote THROUGH real resting depth."

`OwnOrderBook` is, per side, "a `BTreeMap<price_ticks, level>` (price-ordered …), where a level is
an insertion-ordered `IndexMap<coid, OwnOrder>` — insertion order IS venue queue order, and it also
makes the per-level f64 qty fold deterministic." Removals use `shift_remove`.

An `OwnOrder` has "deliberately only three states": `Submitted` ("NOT in the public book, so it
must never be subtracted — enforced structurally: a `Submitted` order has no `ts_accepted`"),
`Accepted`, and `PendingCancel` ("still resting at the venue … until the cancel lands, so by default
it still counts"); terminal outcomes remove the order. `OwnOrder::is_visible` is the race gate: true
"only when the venue has accepted it AND `ts_accepted + accepted_buffer_ns <= now_ns`", and "a `0`
buffer means 'trust the accept immediately' — the behavior of the pre-existing single-snapshot
filtration." `StatusMask::RESTING` (accepted + pending-cancel) is the default; `ACCEPTED_ONLY` is
"for a maker that wants to lean on the depth it is about to reclaim."

`on_modify` is chosen "so the book never OVER-subtracts": a price move re-enters the new level "at
the BACK (a venue re-price forfeits queue priority)" as `Submitted` with the stamp cleared; a size
increase re-arms the stamp; a reduction keeps it, "since subtracting the smaller new size can only
under-subtract, which is the safe direction." `subtract_levels` is "byte-identical to
`book::subtract_own`'s arithmetic for the single-own-order case".

### Who drives it [#who-drives-it]

`SpreadMaker::with_own_order_book(tick_size, accepted_buffer)` is "the whole opt-in" — it implies
`filter_own`. The maker drives the ladder through `OwnBookFiltration::place` "with an **optimistic
ack**": a `Strategy` never sees client-order-ids or venue accepts, "so the maker keys the book by
its own tag (`"bid"`/`"ask"`) and stamps `ts_accepted` itself at the placing event ts", the buffer
"measured from send instead of ack." A runtime that knows the tag↔coid mapping drives the real
lifecycle verbs through `SpreadMaker::own_book_mut`, "after which the buffer covers market-data
propagation alone."

<Callout title="Units, and what is not saved">
  "The `_ns` suffixes follow the HFT nanosecond convention; **the code never converts or divides a
  timestamp**, so any single consistent unit is valid." The live lanes feed epoch-millis, "so a
  maker-side `accepted_buffer_ns` is configured in MILLIS." The ladder is mount-structural — not in
  `SpreadMakerParams`, untouched by a re-tune — and "nothing here is persisted": the cache is
  "rediscovered from the venue by the runtime's reconcile pass." It keeps its own fixed grid rather
  than adopting the L2 book's, "so on the L2 lane pass that venue's grid here explicitly."
</Callout>

The place in the tick where either filtration runs is stage (1) of
[quote emission](/docs/trader/market-making/quote-emission).


# Refresh tolerance (/docs/trader/market-making/refresh-tolerance)



`crates/vike-mm/src/refresh.rs`'s `within_tolerance` is the anti-churn gate of the
[spread maker](/docs/trader/strategies/templates/spread-maker). Given what one side already has
**resting** — a `(price, size)` pair — and the target the current tick just computed, it answers
"close enough to leave alone". A `true` means the caller skips the modify and leaves the resting
order, and its venue queue position, untouched.

## Why it exists [#why-it-exists]

The crate header (`crates/vike-mm/src/lib.rs`) states the cost it removes: without the gate the
maker emits two venue modifies per book delta forever, which on a rate-limited CLOB reached over a
long-haul link is its biggest wire cost. `SpreadMaker::from_params` adds the second reason in its
reader comment — a quote that re-prices every tick forfeits its FIFO slot, so the tolerance is
load-bearing for a [queue-position fill backtest](/docs/trader/backtesting/queue-models): a quote that
never holds its place can never be hit by a taker trade.

## The contract [#the-contract]

Both axes are **relative**, measured in basis points of the **resting** value, held in
`crates/vike-model/src/strategy/maker_params.rs`'s `RefreshTolerance` (`price_bps`, `size_bps`).
The header's reason for that unit is that it reads sanely on both a 0..1-priced prediction market
and a five-figure crypto book without the strategy knowing either venue's tick grid. A skip needs
**both** axes inside tolerance:

* price: `|target_px − resting_px| ≤ price_bps · 1e-4 · |resting_px|`
* size: `|target_sz − resting_sz| ≤ size_bps · 1e-4 · |resting_sz|`

The per-axis helper `drift_within` carries the edge rules. An exactly unchanged value always
passes, whatever the threshold — there is nothing to send. A non-positive `tol_bps` therefore means
"no tolerance on this axis": only exact equality passes it. A zero or non-finite resting reference
has no relative scale to measure against, so it never passes, and NaN anywhere never skips — the
conservative direction is to re-price rather than silently strand a stale quote. The comparison is
multiplied through (`delta · 10_000 ≤ tol_bps · scale`) rather than divided: no reciprocal
rounding, and NaN falls out as `false`. The in-file tests pin the boundary as inclusive — 25 bp of
`100` is `0.25`, and a target of `100.25` is inside.

**Off is the default.** A `None` tolerance never reaches the module at all, and an all-zero bag —
including `RefreshTolerance::default` — returns `false` from every call, so an unconfigured maker
re-prices on every tick exactly as it did before the feature, byte-identical.

## Where it may and may not be consulted [#where-it-may-and-may-not-be-consulted]

<Callout type="warn" title="Only the re-price path is gated">
  `crates/vike-mm/src/quote.rs`'s `refresh_skips` is reachable only from the modify arm of
  `requote_single_side`. Placing a new quote and **pulling** a resting one — the fill-rate breaker's
  suppression cancel — are never tolerance-gated: a quote that must come off the book always comes
  off, whatever the tolerance is set to — `crates/vike-mm/src/refresh.rs`'s header states it in
  those words, paired with the other invariant the module keeps: a fully-inert bag must stay byte-identical to the
  ungated maker.
</Callout>

There is a second refusal before the arithmetic runs. `refresh_skips` answers `false` immediately
when the side's snapshot is **stale** — `SideState::refresh_stale`, set by `Strategy::on_fill`
whenever a fill lands on that side. The reason is that `SideState::own` is the maker's *intended*
quote, not the venue-side remainder: after a partial fill the venue holds less than the intended
size, so an intended-versus-target comparison would read "no change" and the size top-up would be
silently lost. The flag forces the next tick through the modify arm exactly once, which re-issues
the full configured size. `on_fill` sets it before the breaker's early return, deliberately,
because it is independent of the breaker; and it is inert while the gate is off, since it is "read
ONLY by `refresh_skips`/`reward_moas_holds` (and the ladder's per-rung twin), which short-circuit
to 're-quote'". The [ladder](/docs/trader/market-making/ladder-quoting) is that twin: `requote_ladder_side`
reads the flag directly rather than through either helper, and applies the same predicate per rung,
with the same stale short-circuit and the same rule that a pull is never gated.

## Tuning it against the edge [#tuning-it-against-the-edge]

`RefreshTolerance`'s doc carries the ceiling. The tolerance is a fraction of the resting price,
while the edge the maker is paid for is `half_spread` away from mid; if `price_bps · 1e-4 · price`
approaches or exceeds `half_spread`, a market move that stays inside the tolerance — and therefore
sends nothing — can leave the resting quote at or through the new mid, quoting at zero or negative
edge and inviting exactly the adverse fill the spread exists to price. The doc's useful ceiling is
a small fraction, say a tenth, of `half_spread / price · 1e4` basis points; past that the gate is no
longer only suppressing churn, it is silently widening the maker's fill risk.

`SpreadMaker::with_refresh_tolerance` adds the size axis's interaction with the
[inventory skew](/docs/trader/market-making/inventory-skew). A `size_bps` of `0.0` demands bit-exact
size equality, so it only ever fires on a fixed-size maker; with skew active the sizes are
recomputed from a continuously varying position every tick, the size axis would essentially never
compare equal, and the gate would never fire — a non-zero `size_bps` is effectively required there,
sized to swallow the inventory jitter and still re-quote on a real re-size.

On a reward-bearing venue the tolerance also protects reward **eligibility**. The same doc quotes
the measurement: Polymarket's rewards program enforces a minimum order age of 30 s (`moas: 30` on
`GET /clob-markets/{condition_id}`), so an order re-quoted more often than that scores zero. The
[liquidity-rewards](/docs/trader/market-making/liquidity-rewards) fold adds its own min-order-age hold,
`reward_moas_holds`, which composes with this gate — either may skip — rather than replacing it.

The TOML keys are `refresh_price_bps` and `refresh_size_bps`, both defaulting to `0.0` (off) in
`SpreadMaker::from_params`. The [cross-exchange maker](/docs/trader/market-making/xemm) exposes the same
bag through `XemmMaker::with_refresh_tolerance`, with the same rule: consulted only on the re-price
path. The behaviour suite is `crates/vike-mm/src/tests/refresh_tolerance.rs` — sub-tolerance drift
skips the modify, supra-tolerance re-prices in place, a fill always forces the size top-up, and a
pull is never tolerance-gated.


# Settlement (/docs/trader/market-making/settlement)



`crates/vike-mm/src/settlement.rs` holds the pure τ-driven risk heuristics of the
[spread maker](/docs/trader/strategies/templates/spread-maker) on a binary \[0,1] prediction market. The
header states the hazard: holding inventory to resolution on the **wrong** side is a total loss, so
as `τ = T − t` runs to zero the maker must (1) actively unwind toward flat and (2) tighten its
circuit breaker on the toxic side faster than symmetric time decay would. Everything here keys off
one anchor, `AsParams::resolution_ts` — the resolution timestamp `T` in epoch milliseconds, which
for Polymarket is `GammaMarket.end_date` parsed at mount. `SpreadMaker::from_params`'s reader says
every settlement feature reads it: the force-flatten τ, the blackout, the terminal penalty, the
underlying anchor and the pull acceleration.

## What the pricing layer already does [#what-the-pricing-layer-already-does]

The header separates this module from its neighbour. The
[Avellaneda–Stoikov layer](/docs/trader/market-making/avellaneda-stoikov) already skews harder and
widens through a settlement-variance term — `AsParams::terminal_penalty_gamma`, folded in over the
last `terminal_ramp_ms`, so the reservation skew strengthens and the half-spread widens at
`p ≈ 0.5` as `t → T` — and blacks out near resolution: within `resolution_blackout_ms` of `T` it
quotes maximally wide, pushing fills out to the `[tick, 1 − tick]` walls, to dodge the
resolution-news vol spike the Bernoulli cap does not catch. That doc also draws a line the operator
should know: the blackout is the pricing layer's stance, while an active mass-cancel **pull** is the
mount's `on_feed_status` job. What this module adds is the thing the pricing layer lacks — an active
force-flatten schedule that ramps the target inventory toward zero.

<Callout title="These are practitioner heuristics">
  The header says so in as many words. There is no canonical closed-form `f(τ)` for a force-flatten
  schedule: the literature — Avellaneda–Stoikov and its settlement variants — prices the reservation
  and the spread but does not prescribe an active-liquidation ramp. The shapes here are deliberately
  the simplest defensible ones, **linear** in τ; a caller wanting a convex late-panic curve composes
  these, and the linear primitives are the pinned, testable baseline.
</Callout>

## The force-flatten schedule [#the-force-flatten-schedule]

`flatten_weight(tau_ms, flatten_by_ms)` answers how much of the current position should already be
unwound, in `[0, 1]`. `flatten_by_ms` is the τ at which the maker wants to be fully flat, measured
as time-to-resolution — `30_000` means "flat by 30 s before resolution". A non-positive window is
disabled and returns `0.0`; a τ at or beyond the window is `0.0`, nothing to unwind yet; inside the
window the weight ramps linearly, `1 − tau_ms / flatten_by_ms`; and a τ at or below zero is `1.0`,
the whole position wanted gone. It is monotone non-increasing in τ and always clamped.

`force_flatten_skew(q_norm, flatten_w, strength)` turns that weight into an additive reservation
shift: `−strength · flatten_w · q_norm`. A long book yields a negative shift — a lower reservation
price, so the maker leans to sell and flatten — and a short book mirrors. The lean grows with the
weight, so the pressure to be flat rises as τ runs out, and it is exactly `0.0` when the weight is
zero or `strength` is zero, the opt-out. The call site is the A-S reservation in
`crates/vike-mm/src/avellaneda.rs`'s `AsState`: τ is `resolution_ts − ts`, or `i64::MAX` without a
known resolution — outside any window, weight zero, inert — and the shift is added to the
reservation after the Cartea–Jaimungal short-alpha term. The keys are `flatten_by_ms` and
`flatten_strength`, both defaulting to off; `AsParams::flatten_strength`'s doc notes that `0.0` is
byte-identical even with a window set.

## The accelerated pull [#the-accelerated-pull]

`accelerated_pull(tau_ms, ramp_ms, max_accel)` is the factor the per-side
[fill-rate breaker](/docs/trader/market-making/inventory-skew) **divides** its effective net-fill
threshold by, so it trips sooner as τ runs out. A non-positive ramp, or a τ outside it, returns
`1.0`; inside, the multiplier ramps linearly from `1.0` to `1 + max_accel`; at or after resolution
it is `1 + max_accel`. It is always at least `1.0` — floored, so a negative `max_accel` can never
weaken the breaker — and monotone non-decreasing toward resolution. Because it is `1.0` bit-for-bit
when off, dividing the threshold by it is byte-identical on the default path: `x / 1.0 == x`.

The wiring is in two places. `SpreadMaker::pull_accel_mult` reads `1.0` unless the A-S layer is on
with a known `resolution_ts` **and** `pull_accel_ramp_ms > 0` — the two knobs live on `AsParams`,
so a breaker-only maker with no A-S layer reads `1.0` and is byte-identical. `Strategy::on_fill` in
`crates/vike-mm/src/strategy_impl.rs` then compares the netted fills against
`net_fill_threshold / pull_accel_mult(fill.ts)`; the pure `net_signed_fills` is untouched, and the
multiplier is applied only at that comparison. The keys are `pull_accel_ramp_ms` and
`pull_accel_max`, defaulting to off.

## The inert-when-off invariant [#the-inert-when-off-invariant]

Every function here returns its neutral value — a `0.0` shift, a `1.0` multiplier — when its window
parameter is zero or non-positive, so a maker that has not opted in is byte-identical to the
pre-settlement path. The in-file tests pin the disabled, far, at-resolution and mid-ramp values for
all three functions, including `accelerated_pull`'s `1.0` being bit-exact so the divided threshold
is unchanged.

Two things this page does not cover. The **active** unwind that crosses the book is a different leg
— [taker flatten](/docs/trader/market-making/taker-flatten) — and both the schedule here and the skew are
passive. And the venue side of resolution — what the Polymarket bridge does when a market resolves,
auto-redeem included — is on [Polymarket operations](/docs/trader/venues/polymarket-operations); the
reward-band fold's own blackout rule is on [liquidity rewards](/docs/trader/market-making/liquidity-rewards).


# Short-term alpha (/docs/trader/market-making/short-term-alpha)



`crates/vike-mm/src/alpha.rs` is "the Cartea–Jaimungal short-term-alpha slot the A–S reservation
currently lacks — the additive drift term `a·h − φ·q·h` and its two microstructure signal inputs,
isolated so they unit-test without a runtime." It is pure `f64` with naive folds and no `mul_add`,
"the reservation stack pins fold order".

The header names both sources: Cartea, Jaimungal and Penalva's *Algorithmic and High-Frequency
Trading* (2015) for "the inventory-penalized short-alpha market-making formulation: the optimal
quotes ride a reservation price shifted by an additive signal term `a·(T−t)` and a running inventory
penalty `−φ·q·(T−t)`", and Cont, Kukanov and Stoikov's *The Price Impact of Order Book Events*
(Journal of Financial Econometrics 12(1):47–88) for "the signed order-flow-imbalance (OFI) variable
`e_n` built from best-quote queue changes".

## The two signals [#the-two-signals]

**Book imbalance.** `book_imbalance` is the "normalized queue lean at the touch":
`(bid_sz − ask_sz) / (bid_sz + ask_sz)`, "`+1` all bid, `−1` all ask, `0` balanced". A
non-positive denominator returns `0.0`, "which also guards the division". It is read from the top
level of the same book view the maker prices from, so an own-filtered view feeds an own-filtered
imbalance.

**Order-flow imbalance.** `OfiTracker` is "an EWMA-decayed rolling sum of the signed best-quote
queue change `e_n` per book update". With the previous best `(b', bs', a', as')`:

```text
e_bid = (bid >= b' ? bid_sz : 0) − (bid <= b' ? bs' : 0)
e_ask = (ask <= a' ? ask_sz : 0) − (ask >= a' ? as' : 0)
e_n   = e_bid − e_ask
```

"A bid stepping up or growing adds size (buy pressure, `e_n > 0`); a bid stepping down or an ask
stepping down/growing subtracts (sell pressure, `e_n < 0`)." The first update has no previous best
and only seeds state. Then `ofi = ofi·decay + e_n`, the decay "in `[0, 1)`: `0` = memoryless, only
the latest `e_n`; near `1` = a long-memory sum." The default `ofi_decay` on `AsParams` is `0.9`, and
"a live re-tune preserves the warm tracker (like σ̂²), so this is inert on a re-tune."

`combine_alpha` joins them linearly, `beta·imbalance + lambda·ofi`, "so the caller tunes each
channel independently (either weight `0` drops that channel)."

## The shift [#the-shift]

`cj_reservation_shift` returns `alpha_signal · horizon − phi · q_norm · horizon`. "Positive alpha
RAISES the reservation (lean into predicted up-drift); long inventory (`q_norm > 0`) with `phi > 0`
LOWERS it (lean to unwind). `horizon = 0` (terminal) ⇒ both terms vanish."

Where it is applied is `AsState::price` in `crates/vike-mm/src/avellaneda.rs`, on the Group-B
override path described on [Avellaneda–Stoikov](/docs/trader/market-making/avellaneda-stoikov). Two
details of that call site matter for tuning. The OFI tracker is advanced "ONLY when λ is active, so
an imbalance-only (or penalty-only) maker never pays for it." And the horizon passed is `1.0`: "for
a continuously-requoting live maker the CJ time horizon is folded into the gains (β/λ/φ), so the
normalized unit horizon h = 1.0 is used rather than a wall-clock (T−t)." The three weights are
therefore per-tick gains in price units, not rates.

The knobs on `AsParams`: `alpha_beta_imbalance` (`0.0` default — "positive `β` leans the
reservation into the heavier book side"), `alpha_lambda_ofi` (`0.0` default — "the OFI channel is
off AND the OFI tracker is never advanced ⇒ byte-identical + free"), `ofi_decay`, and
`running_penalty_phi` (`0.0` default — "an ADDITIONAL, horizon-scaled pull" on top of the A-S `γ·V`
skew, which is unchanged). All at their defaults, `price` takes the verbatim fast path and never
constructs the shift at all.

## The toxicity fallback [#the-toxicity-fallback]

`ofi_toxicity` synthesizes "a flow-toxicity INTENSITY in `[0, 1]` from an order-flow-imbalance
magnitude — the internal fallback the `SpreadMaker` feeds its flow-toxicity guard when no external
`Strategy::on_flow` reading exists": `tox = 1 − exp(−|ofi| / scale)`, "reaching \~0.63 (`1 − e⁻¹`) at
`|ofi| = scale`", `scale <= 0` disabling it. It "depends on `|ofi|` only, so it is symmetric in the
sign of the OFI (the CALLER derives the toxic SIDE from that sign)."

The caller is stage (3c-i) of `SpreadMaker::requote` in `crates/vike-mm/src/quote.rs`. Its side
mapping: "positive OFI = buy pressure ⇒ aggressive BUY takers lift our ASK ⇒ the ASK is the
toxic/adverse side"; negative OFI marks the bid. The guard then widens the toxic side by
`tox · widen · half` and cuts its size by `(1 − tox · size_cut).max(0)`, "the size-to-zero case
routing through the maker's existing per-side suppression PULL path."

<Callout title="Three conditions, and an external reading wins for good">
  The synthesis runs only when a `ToxicityParams` guard is configured, `ofi_toxicity_scale != 0`, and
  "NO external `on_flow` reading has ever arrived". The `flow_external` latch on `SpreadMaker` is
  "set once `Strategy::on_flow` ever fires and never cleared, so an external toxicity feed takes
  PRECEDENCE permanently … and never clobbers the real reading." And because the tracker only advances
  while `alpha_lambda_ofi != 0`, the `AsParams::ofi_toxicity_scale` doc notes that "a live
  synthesized signal also requires that channel on."
</Callout>

From a registry table the guard is built when either `toxicity_widen` or `toxicity_size_cut` is
present, and `ofi_toxicity_scale` "pairs with" them "so the internally-synthesized OFI reading can
actually fire from a registry table — no external `on_flow` feed exists in a backtest."

The standalone [depth-imbalance](/docs/trader/orderflow/depth-imbalance) study in the order-flow tree
is a separate implementation — "pure functions over `&L2Book` + `ImbalanceTracker`, a small
streaming wrapper that recomputes on every book update"; the signal here is computed inside the
maker from the view it is about to price.


# Taker flatten (/docs/trader/market-making/taker-flatten)



`crates/vike-mm/src/taker_flatten.rs`'s `taker_flatten` is the market-order side of Guilbaud and
Pham, *Optimal High-Frequency Trading with Limit and Market Orders* (Quantitative Finance
13(1):79–94, 2013; arXiv:1106.5040), reduced to one pure function. The header states the idea it
cherry-picks: a passive maker earns the spread by resting limit orders, but pure limit quoting
cannot bound inventory — an adverse run fills one side repeatedly and the position drifts
unboundedly. Guilbaud–Pham add an impulse-control leg on top of the continuous quoting: at discrete
moments the agent may cross the book with a **market** order to instantaneously cut inventory it
cannot skew its way out of.

Vike Trader's maker already has two passive answers to the same problem — the
[inventory skew](/docs/trader/market-making/inventory-skew) leans quote sizes toward flat, and near a
binary resolution the [settlement](/docs/trader/market-making/settlement) schedule force-flattens through
a reservation shift. What lives here is the missing **active** leg.

## The decision [#the-decision]

`taker_flatten(inventory, band)` returns `Some((side_sign, qty))` naming the market order that cuts
the band-excess inventory, or `None` when nothing should be taken. `inventory` is the current signed
position, `band` the tolerated inventory half-width the passive skew manages. It fires only when
`inventory.abs() > band`, **strictly** over — sitting exactly at the band is not over, so it holds.
When it fires, `side_sign = −inventory.signum()` (long sells to reduce, short buys) and
`qty = inventory.abs() − band`, so `qty` is strictly positive whenever the result is `Some`. A
negative band is clamped to zero rather than allowed to widen the trigger, and zero inventory is
`None` under any band.

<Callout title="Flatten the excess, not the position">
  The header argues the design choice at length. When the band is breached the leg cuts only the
  amount **over** the band, leaving the position resting exactly at it — the band *is* the tolerated
  inventory the passive skew is meant to manage. A full flatten to zero would pay the taker spread
  and impact on inventory the maker deliberately tolerates, and would fight the skew, which is already
  leaning that inventory down for free. Cutting to the band is the minimal taker action that restores
  the passive regime's invariant, `|inventory| <= band`. A caller wanting a hard flatten-to-zero
  passes `band = 0`, and then `qty` is the full `|inventory|`.
</Callout>

The header is explicit that this is a **practitioner heuristic**. The Guilbaud–Pham optimal impulse
region is the solution of a quasi-variational HJB inequality with no closed form; the fixed band is
the standard practitioner reduction of that region to one tunable — the simplest defensible shape
and the pinned, testable baseline. A convex or asymmetric band is a caller composition on top.

The inert-when-off invariant follows from the strict inequality: a maker whose inventory stays
within its band never takes, the impulse leg is dormant, and the maker is byte-identical to the
passive skew-only path. The in-file tests pin each edge — within the band, at the band, long and
short over it, a zero band, a negative band.

## Who calls it [#who-calls-it]

The crate root once parked this module under `#[allow(dead_code)]` as a deferred pure core; the
allow is gone because the [cross-exchange maker](/docs/trader/market-making/xemm) calls it as its
hard-naked-band impulse. `XemmMaker::drive_flatten` in `crates/vike-mm/src/xemm/mod.rs` is that
site, and its doc sets the terms:

* it fires at most **once per halt** — the `flatten_fired` latch is cleared on resume, so a halted
  maker being ticked does not send a flatten market every tick;
* it fires only while the hedge ledger owes nothing — an in-flight hedge is already closing the
  exposure, and a second market on top of it would over-hedge;
* it runs only once `guards::over_hard_band` holds on the ledger's naked exposure, and it cuts back
  to the **soft** band: the call is `taker_flatten(naked, naked_band)`, sent through
  `Broker::submit_market` on the hedge symbol.

The same doc states when the leg can be reached at all. In the fully-hedged configuration
(`hedge_ratio == 1.0`) the ledger's residual and the naked exposure are the same quantity, so this
leg is unreachable by construction; it exists for the deliberately partial case
(`hedge_ratio < 1.0`) and for an exposure that arrived some way the ledger's own retry cannot
close. The two bands
are `XemmParams::naked_band` (soft — while `|unhedged|` exceeds it, the side that would grow the
exposure is suppressed) and `XemmParams::naked_hard_band` (halt, pull both sides, fire the
impulse for the excess over the soft band); `XemmMaker::new` defaults them to `qty` and `3·qty`,
and `XemmMaker::with_naked_bands` tunes both. The whole guard vocabulary is on
[guards](/docs/trader/market-making/xemm/guards).

<Callout type="warn" title="Nothing an operator can run reaches this leg today">
  `taker_flatten` is `pub(crate)` in `crates/vike-mm/src/taker_flatten.rs`, and the xEMM's impulse is
  its only caller outside that crate's own tests — the single-venue spread maker does not call it. The
  xEMM itself is reached by no binary, profile, flag or feature:
  `crates/vike-strategy/src/registry.rs`'s `strategy_by_name` carries no `xemm` arm, so no run profile
  can resolve one. It is complete, tested and dormant. Keep-or-kill was investigated and answered in a
  decision record that prices the deletion — losing this leg is one of the listed costs — and the
  reachability question is settled there, not here.
</Callout>


# Flow bars (/docs/trader/orderflow/bars)



`crates/vike-orderflow/src/bars.rs` is "tick-, volume- and dollar-interval bar aggregation with a
buy/sell/delta split, plus the opt-in López-de-Prado information-driven bars". All five builders
reuse the one [classification](/docs/trader/orderflow/classification) semantic and emit the same bar.

## The bar [#the-bar]

```rust
pub struct OrderflowBar {
    pub o: f64, pub h: f64, pub l: f64, pub c: f64,
    pub buy_vol: f64, pub sell_vol: f64, pub delta: f64,
    pub trade_count: u32,
    pub first_ts: i64, pub last_ts: i64,
}
```

Behind every builder sits one private accumulator, `BarAcc`, which "accumulates the running fields
of one open bar": OHLC, the buy and sell sums, a trade count, and a running notional Σ price·size
that "is only consulted by `DollarBarBuilder`; the tick/volume builders carry it inertly". At close
`delta` is `buy − sell`, and `first_ts`/`last_ts` are the first and last contributing trade's
`ts`.

## The five builders [#the-five-builders]

| builder                                     | closes when                                | the boundary trade                                         | `push` returns         |
| ------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------- | ---------------------- |
| `TickBarBuilder::new(n)`                    | the count reaches `n`                      | whole — a trade is one tick                                | `Option<OrderflowBar>` |
| `VolumeBarBuilder::new(threshold)`          | `buy + sell` reaches `threshold`           | **split** by volume; the filling slice closes the bar      | `Vec<OrderflowBar>`    |
| `DollarBarBuilder::new(threshold)`          | Σ price·size reaches `threshold`           | **split** by the size that fills the remaining dollar room | `Vec<OrderflowBar>`    |
| `ImbalanceBarBuilder::new(unit, threshold)` | \|Σ ±unit\| reaches `threshold`            | included whole — no split                                  | `Option<OrderflowBar>` |
| `RunsBarBuilder::new(unit, threshold)`      | max(buy-run, sell-run) reaches `threshold` | included whole — no split                                  | `Option<OrderflowBar>` |

Every constructor asserts its parameter (`n >= 1`, `threshold > 0`). Each builder has a `forming()`
read — "Snapshot of the OPEN (unclosed) bar — the chart's forming bar. Pure read." — and a batch
`from_trades` over a slice, which returns closed bars only; the tick and imbalance forms say so in
place ("trailing partial bar dropped"). Zero- and negative-size trades never open or advance a bar
on any path.

### Why volume and dollar bars return a `Vec` [#why-volume-and-dollar-bars-return-a-vec]

`vol_fold` closes bars "whenever `acc.buy+acc.sell` reaches `threshold`" and "splits the trade
across boundaries by volume": the trade is cut into a synthetic sub-trade of the size that fills
the open bar's room, at the trade's own price, side and timestamp, and the remainder starts the
next bar. One large print can therefore close several bars in a single `push`, which is why the
return type is a list.

`dollar_fold` is "the dollar twin of `vol_fold`": it splits by `room / price`, the size that fills
the remaining dollar room. It carries a guard the volume form does not need. If the computed take
is non-positive, or too small to advance the remainder at all (sub-ulp), "the whole remainder is
absorbed into the open bar instead of looping". That is also where a degenerate `price <= 0` trade
lands: it contributes volume but no notional, "so it can never close a bar on its own".

<Callout title="The two boundary conventions are deliberate and different">
  Volume and dollar bars split the crossing trade so a bar's volume is exactly its threshold. The
  imbalance and runs bars include the crossing trade whole, because — in the module's words — "LdP
  samples AT the crossing tick". Do not expect an imbalance bar's total volume to be a round
  number.
</Callout>

## Information-driven bars [#information-driven-bars]

The two remaining builders are the López de Prado imbalance and runs bars (AFML §2.3.2), in their
"fixed-threshold deterministic form". Both are opt-in: "a caller that never constructs this leaves
every existing bar path byte-identical", and the header restates that a default path which builds
none leaves the tick/volume/dollar behavior unchanged.

`FlowUnit` is the per-trade quantity they weight each signed trade by — `Tick` weights every trade
as 1, `Volume` as its `size`, `Dollar` as `price·size`. It is fixed at construction and affects
only *when* a bar closes; "the ordinary buy/sell/delta volume split on the emitted bar is
unaffected by the chosen unit".

**Imbalance bars** advance a running signed sum θ by +weight for a buy aggressor and −weight for a
sell, and close when |θ| reaches the threshold.

**Runs bars** grow two cumulative per-side sums and close when the larger reaches the threshold.
The doc comment is emphatic about what this is: "LdP's cumulative-side statistic, NOT the longest
CONSECUTIVE same-signed streak."

The EWMA-adaptive thresholds from the same chapter — `E[T]·|2P(buy)−1|` for imbalance,
`E[T]·max{P, 1−P}` for runs — are named as the documented future extension; what ships is the
fixed-threshold variant.

## On the chart [#on-the-chart]

`crates/vike-app-core/src/tickvol.rs` is where these bars become chart intervals. Its `BarKind`
classifies an interval string: the fixed kline set passes through unchanged, while `"<n>t"` and
`"<x>v"` select the tick and volume aggregators. `TickVolAgg` wraps one builder — the header names
`TickBarBuilder` or `VolumeBarBuilder` — and converts each closed `OrderflowBar` to a
`vike_model::Bar`, with `funding`, `bid`, `ask` and `symbol` left `None` the way the kline path
leaves its own not-sourced fields. Dollar, imbalance and runs bars are not named on that interval
path.


# Buy/sell classification (/docs/trader/orderflow/classification)



`crates/vike-orderflow/src/classify.rs` opens by calling itself "the one load-bearing semantic of
the whole crate", and the rest of the crate agrees: every study that splits volume into buy and
sell reaches this module rather than deciding for itself. It is three items long.

```rust
pub enum Side { Buy, Sell }

pub fn classify(t: &TradeTick) -> Side          // is_buyer_maker → Sell, else Buy
pub fn signed(t: &TradeTick) -> (f64, f64)      // (buy_add, sell_add) for the full size
```

## The convention [#the-convention]

`TradeTick::is_buyer_maker` is the Binance-aggTrades convention, and the header spells out what
it means: the buyer was the resting maker — a bid — so the aggressor was the **seller**. `classify`
therefore maps `is_buyer_maker = true` to `Side::Sell` and `false` to `Side::Buy`. The module's own
tests put it in market terms: an ask lifted is a buy aggressor; a bid hit is a sell aggressor.

`signed` is the form the builders actually consume. Its doc comment: "(buy\_add, sell\_add) for the
full `size` of `t`, routed to the aggressor side" — a buy contributes `(size, 0.0)`, a sell
`(0.0, size)`. A trade is never split between sides; it goes whole to the side that crossed the
spread.

The module ports no Python twin — it is new native code — so there is no frozen fixture behind it,
only the hand-computed tests beside it (the [index](/docs/trader/orderflow) explains why that is the
crate's oracle).

## Everything downstream inherits it [#everything-downstream-inherits-it]

The crate header (`crates/vike-orderflow/src/lib.rs`) states the consequence: `delta = buy_vol −
sell_vol` everywhere below. Concretely:

| study                                              | how it uses the semantic                                                                                                                                                                                                             |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [flow bars](/docs/trader/orderflow/bars)                | the header of `bars.rs`: all builders "reuse the one `crate::classify::signed` buy/sell semantic"; `OrderflowBar::delta` is `buy − sell` at close. The information-driven bars call `classify` directly to sign each trade's weight. |
| [CVD](/docs/trader/orderflow/cvd)                       | `CvdAccumulator::push` adds `b − s` from `signed`                                                                                                                                                                                    |
| [footprint](/docs/trader/orderflow/footprint)           | `FootprintBuilder::push` adds `signed`'s pair to the trade's price bucket                                                                                                                                                            |
| [volume profile](/docs/trader/orderflow/volume-profile) | `VolumeProfileBuilder::push` does the same into its own grid                                                                                                                                                                         |

Because there is exactly one classification site, a feed whose maker flag is inverted would
invert every delta, footprint cell and profile bin at once — there is no second reading anywhere
to disagree with.

<Callout type="warn" title="A missing flag reads as a buy">
  On `crates/vike-marketdata/src/bar.rs`'s `TradeTick` the field is `#[serde(default)]`, and the struct's
  own description says the aggressor flag is present "where available". A trade record that carries
  no flag deserializes with `is_buyer_maker = false`, which `classify` reads as a buy aggressor. On
  a tape that never supplies the flag, every study on this page's list would report all volume as
  buy volume and a delta equal to total volume — a number that looks like a signal and is not.
</Callout>

## The aggressor-free alternatives [#the-aggressor-free-alternatives]

Not every venue publishes an aggressor flag, and `crates/vike-orderflow/src/vpin.rs` answers that
in two places. `Vpin` itself has a flagless mode: "feeds without a real aggressor flag construct
with `has_aggressor = false` and pass the prevailing mid to `push`: `price >= mid` → Buy, else
Sell (the quote-midpoint test)", and a missing mid falls back to the flag so no trade is dropped;
the chart's study registry exposes the same switch as its `aggressor flag` parameter set to 0. The
crate header names the other: `BvcVpin`, "the aggressor-free" VPIN of Easley, López de Prado and
O'Hara (2012), which classifies volume in bulk by the price change of each bucket, `Φ(ΔP/σ)`, with
a tick-rule option. It does not go through `classify` at all — that is the point of it. Both are
described on the [VPIN](/docs/trader/orderflow/vpin) page.


# CVD (/docs/trader/orderflow/cvd)



`crates/vike-orderflow/src/cvd.rs` is, after `classify`, the shortest module in the crate, and its
header is its whole contract: "cumulative volume delta — running Σ(buy − sell) over the trade
stream". Buy and sell are the [classification](/docs/trader/orderflow/classification) module's reading
of the aggressor flag, so a rising CVD means aggressive buying has exceeded aggressive selling
since the accumulator started, whatever price has done meanwhile.

## The accumulator [#the-accumulator]

```rust
pub struct CvdAccumulator { cvd: f64 }

impl CvdAccumulator {
    pub fn new() -> Self;
    pub fn push(&mut self, t: &TradeTick);          // cvd += buy − sell; size <= 0 skipped
    pub fn value(&self) -> f64;
    pub fn from_trades(trades: &[TradeTick]) -> f64; // the batch twin
}
```

`push` takes `signed`'s `(buy, sell)` pair for the trade and adds `buy − sell`; a trade of zero or
negative size returns before touching the sum. `value` is a plain read. The sum is a naive
running `+=` fold — there is no compensated summation, and the order of the trades is the order
of the sum.

`from_trades` is the batch form over a slice, and the module's parity test drives the same trades
through both and compares `value().to_bits()` to the batch result: streaming and batch are
bit-identical, not merely close. The zero-skip is pinned by the same file — `+3 buy, −2 sell, skip
0, +1 buy → +2`.

## The per-bar form the chart draws [#the-per-bar-form-the-chart-draws]

The accumulator is the trade-stream primitive. The chart does not run it. `crates/vike-chart/src/orderflow.rs` derives CVD from the per-bar
[footprint](/docs/trader/orderflow/footprint) substrate instead: its `cvd_from_footprints` is
"cumulative volume delta per bar: running Σ over bars of (Σ cell.buy − Σ cell.sell)", index-aligned
to the footprints and so to the chart's bars, and again a "naive fold (no compensation)". The
header's reason is architectural — CVD and the visible volume profile are both derived from
`&[FootprintBar]`, "the single orderflow input — so the app feeds one structure and the renderer
computes the three views".

<Callout title="Two computations, one semantic">
  The trade-stream accumulator and the chart's per-bar derivation are separate code, but both read
  buy and sell through the same `signed` split, and the footprint cells are themselves sums of that
  split. Where the two would differ is what they start from and how the sum is grouped: the
  accumulator from its construction, folding trade by trade in tape order; the chart from the first
  bar it holds, folding each bar's cell totals and then accumulating those. Both folds are naive, and
  no test compares them.
</Callout>

Where the CVD pane sits and what it is drawn against is the [in the GUI](/docs/trader/orderflow/in-the-gui)
page.


# Depth imbalance (/docs/trader/orderflow/depth-imbalance)



`crates/vike-orderflow/src/imbalance.rs` holds the depth-imbalance studies over
`vike_model::L2Book` — a book-pressure mechanism from the standard literature, implemented
independently. Unlike the trade-fed builders it reads no `TradeTick`; its input is the reducer
described on the [data model](/docs/trader/concepts/data-model) page.

## Two pure functions [#two-pure-functions]

**`depth_imbalance(book, n)`** is `(Σ bidQ − Σ askQ) / (Σ bidQ + Σ askQ)` over the top `n` levels of
each side, in `[−1, 1]`. The header positions it precisely: "the depth-N generalization of
`L2Book::imbalance` (which is the n=1 top-of-book special case, kept where it is)". The sign is
bid pressure — `+1` all bid, `−1` all ask. It returns `None` if either side is empty or all sizes
are zero. An `n` deeper than the book uses what exists.

**`weighted_depth_imbalance(book, n)`** is the same ratio "with every level's size damped by
inverse distance to mid": each level contributes `w·q` with

```
w = 1 / (1 + d)²,   d = |price − mid| / mid
```

"so touch depth counts (almost) fully and far depth fades quadratically". It returns `None` if
either side is empty, if the mid is unavailable or non-positive — "Polymarket-style books can sit
at 0" — or if all weighted sizes are zero.

The book side of both comes from `crates/vike-marketdata/src/orderbook.rs`'s `L2Book::top_n`, "the N
best (price, qty) on each side (bids high→low, asks low→high)", and `L2Book::mid`, which is `None`
unless both a best bid and a best ask exist. The module fixes the arithmetic order: "`top_n`
yields bids high→low and asks low→high, and both sums are naive `+=` folds in that order" — so
the number is a deterministic function of the book, not of iteration luck.

The tests carry the reference values. Bids `(99, 10)`, `(98, 5)`; asks `(101, 10)`, `(102, 15)`:
`n = 2` gives `(15 − 25) / 40 = −0.25`, `n = 1` gives `0` and equals `L2Book::imbalance`. A
mirrored book flips the sign exactly, asserted on the bit pattern. And a book whose bid mass sits
at the touch while an equal ask mass sits far away reads `0` unweighted and tips positive
weighted — the weighting seeing what the plain count cannot.

## The tracker [#the-tracker]

```rust
pub struct ImbalanceTracker 

impl ImbalanceTracker {
    pub fn new(n: usize, weighted: bool) -> Self;      // asserts n >= 1
    pub fn update(&mut self, book: &L2Book) -> Option<f64>;
    pub fn last(&self) -> Option<f64>;
}
```

`ImbalanceTracker` is "a small streaming wrapper that recomputes on every book update and caches
the last GOOD value across momentarily unreadable books (one side empty mid-resync)". `update`
recomputes the chosen variant; a `Some` result replaces the cache and is returned. A `None` — the
resync flicker where one side is briefly empty — is returned as `None` but "does NOT wipe
`last()`".

<Callout type="warn" title="update and last answer different questions">
  `update` tells you whether this book was readable; `last` tells you the most recent reading that
  was. A consumer that displays `last()` during a resync is showing a value from before the
  flicker, by design — the alternative was a gauge that blanks every time a venue re-snapshots.
</Callout>

## How it is gated [#how-it-is-gated]

The crate header (`crates/vike-orderflow/src/lib.rs`) notes that the book-fed studies have no
trade-slice batch twin, so instead of the streaming ↔ batch parity the trade builders carry,
`imbalance` is "pure functions/scripted-snapshot gated" — hand-built books with hand-computed
answers, including the bounds, the exact sign flip under mirroring, and the cache surviving a
one-sided update. The [order-to-trade ratio](/docs/trader/orderflow/otr) is the other study on the
same footing.


# Footprint (/docs/trader/orderflow/footprint)



`crates/vike-orderflow/src/footprint.rs` builds the footprint: a "per-bar, per-price-bucket
buy/sell volume grid". Its header is explicit that it owns very little of its own arithmetic —
the cells "reuse `profile::{PriceBin, bucket, grid_to_cells}` — the bucketing and grid→bins
transform are owned by `profile`, not re-derived here". A footprint bar is, structurally, one
bar's worth of [volume profile](/docs/trader/orderflow/volume-profile) before the POC and value area
are reduced from it.

## The shape [#the-shape]

```rust
pub struct FootprintBar {
    pub bar_index: u64,
    pub cells: Vec<PriceBin>,   // PriceBin { price, buy_vol, sell_vol }, ascending by price
}
```

`FootprintBuilder::new(tick_size)` asserts a positive tick size and holds one open grid, a
`BTreeMap` from bucket index to a `(buy, sell)` pair. `push` skips a zero-size trade, takes the
[classification](/docs/trader/orderflow/classification) module's `signed` split, and adds it to the
bucket `profile::bucket(price, tick_size)` — "the one rounding site for all price bucketing in this
crate", `(price / tick_size).round()`. `close_bar` converts the grid to ascending cells through
`profile::grid_to_cells`, clears it, and stamps the bar with a counter that starts at 0 and
advances by one per close.

Two consequences of that design are worth holding:

* **A cell's `price` is a grid price, not a traded price.** `grid_to_cells` sets it to
  `bucket × tick_size`. Every trade that rounds into the same bucket lands in the same cell.
* **The bar boundary is the caller's.** The builder has no clock and no threshold; `push` takes
  a trade and `close_bar` takes nothing. Whoever calls `close_bar` decides what a bar is — a
  time interval, a [flow bar](/docs/trader/orderflow/bars), or anything else.

`from_bars` is the batch twin: it takes trades already grouped per bar (`&[Vec<TradeTick>]`) and
returns one `FootprintBar` per group, indexed by position. The module's tests drive the same
grouped trades through `push`/`close_bar` and assert the two results equal, and pin the invariant
that the sum of a bar's cells equals its buy and sell volume with zero-size trades excluded.

## From footprint to profile [#from-footprint-to-profile]

`VolumeProfile::from_footprints(footprints, tick_size, lo, hi)` in `crates/vike-orderflow/src/profile.rs`
merges "the cells of `footprints[lo..=hi]` (clamped to range) into one volume-at-price profile with
POC + 70% value area". Its doc comment carries one requirement: "`tick_size` must match the
footprints' bucketing". The tests confirm that merging every bar's footprint reproduces the
profile a `VolumeProfileBuilder` computes over the same trades directly — bins, POC and value area
alike.

## How the app keeps one per chart bar [#how-the-app-keeps-one-per-chart-bar]

`crates/vike-app-core/src/orderflow.rs`'s `OrderflowAgg` is the "app-side per-bar orderflow
aggregation": it buckets the drained trade tape into the chart's bars by open time and retains the
per-bar footprint cells, "the substrate SP2 renders from". Its header is mostly about what happens
to a tick that arrives before the chart has a bar to put it in, and the rule is that
"pre-bar-0 ticks are never silently lost":

* **No bar grid at all** — the tick is "unplaceable for now", and the cause is transient by
  construction (a Data Manager delete removes the chart and its aggregator together, so a re-add
  presents an aggregator whose chart has not synced yet). Those ticks are held in `pending` and
  folded in, each at its own bar by timestamp, on the first later ingest that carries a grid. The
  hold is bounded by `PENDING_MAX_TICKS`; at the bound the oldest held ticks are evicted, counted
  in `evicted_ticks`, and warned about.
* **A grid exists but the tick predates bar 0** — "unplaceable by construction", because the cell
  list is index-aligned to a bar list that only grows forward. Discarding is correct; discarding
  silently was the defect. The count is `dropped_before_grid`, warned on a doubling schedule.

<Callout title="A held tick that is still too old when the grid appears is discarded, not aged out">
  The header's own reasoning: staleness "resolves itself into a counted discard at flush time", so
  the hold needs no separate age bound.
</Callout>

## Drawing a cell [#drawing-a-cell]

`crates/vike-chart/src/orderflow.rs`'s `cell_text_legible` decides whether a cell shows its
numbers: "footprint cell numbers are drawn only when the cell is tall enough to be legible", with
the threshold at 11 pixels of cell height. Below it nothing replaces them. `draw_footprint`
(`crates/vike-chart/src/render.rs`) is explicit: "the tinted rect alone carries the imbalance read
(no delta-bar fallback: the tint already IS the delta signal)" — the helper's own comment still
mentions a delta-colored bar from the original two-tier sketch, and the renderer does not draw
one. The [in the GUI](/docs/trader/orderflow/in-the-gui) page covers the pane itself.


# In the GUI (/docs/trader/orderflow/in-the-gui)



The [order-flow crate](/docs/trader/orderflow) computes; `vike-chart` draws. Its header claims "the
per-bar orderflow substrate rendering (`chart::ChartStyle::Footprint` + the CVD/volume-profile
overlays, SP2)", and `crates/vike-chart/Cargo.toml` lists `vike-orderflow` among the five `vike-*`
crates it depends on, annotated "per-bar footprint substrate → CVD/profile/footprint render (SP2)".
Everything below follows from one decision stated in `crates/vike-chart/src/orderflow.rs`'s
header: CVD and the visible volume profile are derived from `&[FootprintBar]` — "the single
orderflow input — so the app feeds one structure and the renderer computes the three views."

## One input: the footprint substrate [#one-input-the-footprint-substrate]

`ChartInputs::footprint` (`crates/vike-chart/src/chart/mod.rs`) is "the per-bar footprint
substrate (SP2), index-aligned to `state.bars` — the single orderflow input CVD/profile/footprint
are all derived from chart-side", and it is `None` "when the app hasn't aggregated trades for
this chart (default-off: no orderflow rendering happens without this)".

The app builds it in `crates/vike-app-core/src/orderflow.rs`'s `OrderflowAgg`, which buckets "the
drained trade tape into the chart's bars (by open-time)" and retains per-bar footprint cells; the
per-frame drain that feeds it is `crates/vike-app-core/src/core_sync.rs`, which runs every frame
outside the snapshot gate so a workspace with no kline feed no longer stalls. The bucket width
defaults to `nice_orderflow_tick`: "a 'nice' 1/2/5×10^k bucket tick \~ price × 0.0002 (≈2 bps)" —
about $10 on BTC, $0.5 on ETH, $0.0001 on a $0.5 coin — computed through the `libm` crate so a
price on a decade boundary cannot bucket ten times finer on one machine than another.

### Turning it on [#turning-it-on]

`WinState::orderflow_on` (`crates/vike-app-core/src/workspace/state.rs`) is true "when either
toggle is on, OR the chart style is `Footprint` on a Kline interval"; the window loop uses it "to
lazily subscribe the trade feed and register an `orderflow::OrderflowAgg` — never on a fresh,
all-default window". The toggles sit behind the chart toolbar's **OF** button
(`crates/vike-desktop/src/chart_window.rs`): a popup with CVD and Volume Profile checkboxes and a
tick-size override, Auto or a pinned value; the label tints while either toggle is on. All three
persist per window (`crates/vike-app-core/src/workspace/persist.rs`'s `cvd_on`, `profile_on`,
`of_tick_size`), and a workspace file written before they existed loads them off.

The subscription is the window's own venue tape — "any venue with a `subscribe_trades` feed
(OKX/Bybit/…) drives CVD/footprint, not just Binance" — and `footprint` stays `None` "until this
chart's aggregator exists AND has ingested at least one trade batch (a one-two-frame startup lag
after the toggle flips)". The tick size the chart receives is the aggregator's actual bucketing
width, so what is drawn matches the granularity the data was bucketed at.

## The three views [#the-three-views]

**Footprint** is a chart *style*. `ChartStyle::Footprint` is the "per-bar buy/sell price-cell
grid — the orderflow footprint chart", rendered from the substrate and falling back to plain
candles when it is `None`. It has its own "Orderflow" section in the style menu because it is not
a reindexing transform like Renko or Kagi but "an alternate per-bar substrate (buy/sell price
cells) for the SAME bar axis". `draw_footprint` (`crates/vike-chart/src/render.rs`) paints, per
bar, a column of per-price cells with a faint imbalance tint; the bar's point-of-control cell —
max buy + sell volume within that bar — gets an amber outline; buy/sell numbers appear only when
`cell_text_legible` passes, a cell at least 11 px tall — "below that the tinted rect alone
carries the imbalance read". It draws the visible bar range only, clamped against both lists: a
substrate shorter than the bar list ("the aggregator hasn't caught up to a just-opened forming bar
yet") draws the bars that have cells and stops at the shorter of the two, and a stale or
out-of-range bound degrades to drawing nothing rather than a panic. The cells themselves are on
the [footprint](/docs/trader/orderflow/footprint) page.

**Volume profile** is an overlay on the price pane. `paint_volume_profile`
(`crates/vike-chart/src/chart/price_render.rs`) draws "a visible-range volume-at-price histogram

* POC + value-area band painted on the price pane, pinned to the RIGHT edge of the visible
  x-range". It is windowed to the same visible bar bounds as the footprint, and the bucket width
  comes from one derivation, `orderflow_tick_size`, "so the two always agree for the same visible
  range". `ChartState::visible_profile_shared` caches the profile by visible bounds, substrate
  length and tick size, so an unchanged frame is an O(1) clone rather than a
  `VolumeProfile::from_footprints` recompute. Its POC line is the palette's amber,
  `PROFILE_POC_COLOR` — "same hex as `dom.rs`'s private `LAST`, the DOM ladder's last-trade row".
  POC and value area are on the [volume profile](/docs/trader/orderflow/volume-profile) page.

**CVD** is a sub-pane. `PaneKey::Cvd` is "a singleton pane like `Volume`, not per-uid like
`Study`, since there is at most one CVD pane per chart", and `draw_cvd_pane` plots
`cvd_from_footprints` over the whole substrate — "the CVD pane plots the full running series, so
it can't be windowed the same way" as the profile. `ChartState::cvd_shared` caches it on
`footprint_gen`, a monotonic generation the aggregator bumps on every rebuild. The pane's gate is
`cvd_on` **and** footprint data present; the layout tests pin that "`cvd_on` alone must not
produce a pane without footprint data". Volume, CVD and study panes are peers in the order the
user arranged, sized by the identity-keyed `PaneFractions`. The fold is on the
[CVD](/docs/trader/orderflow/cvd) page.

## The study panes [#the-study-panes]

`crates/vike-chart/src/studies.rs` is "the tick-driven twin of `crate::indicators::Active`":
`vike-orderflow` owns the compute, and this adapter "turns those TICK-driven folds into
BAR-INDEXED oscillator-pane series", reusing the indicator paint state and `ParamSpec` surface so
"a study pane is indistinguishable from an indicator pane to the renderer and to the settings
dialogs". `study_registry()` holds three:

| name             | label                      | needs a book | bands           |
| ---------------- | -------------------------- | ------------ | --------------- |
| `vpin`           | VPIN (order-flow toxicity) | no           | 0.2 · 0.5 · 0.8 |
| `book_imbalance` | Book imbalance (depth-N)   | yes          | −0.5 · 0 · 0.5  |
| `otr`            | Order-to-trade ratio       | yes          | 0               |

The header's load-bearing decision is the tick-to-bar mapping: each `ActiveStudy` keeps one
incremental instance folded over the live tick stream and samples its committed value when a bar
closes; a quiet bar carries the last value ("a flat segment is the truthful reading"); bars
before the first committed value sample NaN; the forming bar gets a speculative tail from the
study's interim read, dropped at the next sync. A book-dependent study renders nothing until a
book snapshot has been fed — "no fabricated values" — while VPIN needs trades only.
`render_study` draws through the same oscillator body indicators use, and a study pane shares the
indicator uid space, so "a study and an indicator can even share one pane". Each fold is on its
own page: [VPIN](/docs/trader/orderflow/vpin), [depth imbalance](/docs/trader/orderflow/depth-imbalance),
[OTR](/docs/trader/orderflow/otr).

<Callout type="warn" title="The desktop app does not build a study yet">
  `crates/vike-desktop/src/app_ui.rs`, the one place the app assembles `ChartInputs`, passes
  `studies: &[]` — "empty until the app grows its own study menu + tick fan-in — an empty slice
  renders byte-identically to the pre-studies chart". The three studies above are a chart-engine
  capability with tests, not a menu item: no picker in the shipped app adds a VPIN, book-imbalance
  or OTR pane. The Footprint style, the volume-profile overlay and the CVD pane are the order-flow
  views you can turn on today.
</Callout>

## What is not an order-flow study [#what-is-not-an-order-flow-study]

Two neighbours look like this crate's work and are not. The [DOM ladder](/docs/trader/gui/dom-ladder)
and its order-flow heatmap live in `vike-panels`, whose manifest calls it "chart-engine-free" and
depends on `vike-model`, `vike-ui-theme` and egui only — `L2Book` is what it paints over, and it
never reads `vike-orderflow`. And tick and volume bars (`"<n>t"`, `"<x>v"` intervals) are a bar
*source* for the chart's ordinary sync path, built by `crates/vike-app-core/src/tickvol.rs` from
the [flow bars](/docs/trader/orderflow/bars) builders — not a pane; `orderflow_on` notes they are
"otherwise out of scope for the Footprint STYLE", which applies on kline intervals. The engine as
a whole is on [the chart](/docs/trader/gui/chart) page, and per-window persistence on
[workspaces](/docs/trader/gui/workspace).


# Order flow (/docs/trader/orderflow)



`vike-orderflow` is the crate every order-flow study in Vike Trader is computed by. Its own header,
`crates/vike-orderflow/src/lib.rs`, states the contract in one line: a pure trade-aggregation core
that folds `vike_model::TradeTick` streams into orderflow primitives — no I/O, no rendering, no
threading. The manifest (`crates/vike-orderflow/Cargo.toml`) declares it at layer 20, tier
`domain`, "one hop over the vocabulary: a single-purpose pure core", and its only workspace
dependency is `vike-model`. The one crate beyond that is `libm`, pulled in for the standard-normal
CDF that [VPIN](/docs/trader/orderflow/vpin)'s bulk volume classification needs — a pure-Rust FDLIBM
`erf`, deterministic across platforms, and already a workspace-pinned dependency rather than a
new supply-chain entry.

## The input [#the-input]

Six of the nine modules read one type: `crates/vike-marketdata/src/bar.rs`'s `TradeTick`, "one
executed trade: price + size, with the aggressor flag where available". Its fields are `ts` (epoch
milliseconds, UTC), `local_ts` (the machine receive time — `0` means not stamped, which is what
fixtures and backfill carry), `price`, `size`, `is_buyer_maker` and `symbol`. Two more, `imbalance`
and `otr`, read a `vike_model::L2Book` instead — the same reducer the
[data model](/docs/trader/concepts/data-model) page describes. The ninth, `p2`, reads neither: its
`push` takes a bare `f64`, which is why the
[streaming quantiles](/docs/trader/orderflow/streaming-quantiles) page calls it the one module that
folds nothing from the tape.

## One semantic, nine modules [#one-semantic-nine-modules]

| module      | symbols                                                                                                                       | what it is                                                                                                                 | page                                                         |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `classify`  | `Side`, `classify`, `signed`                                                                                                  | the load-bearing semantic: `is_buyer_maker=false` → Buy, `true` → Sell; `delta = buy_vol − sell_vol` everywhere below      | [classification](/docs/trader/orderflow/classification)           |
| `bars`      | `OrderflowBar`, `TickBarBuilder`, `VolumeBarBuilder`, `DollarBarBuilder`, `ImbalanceBarBuilder`, `RunsBarBuilder`, `FlowUnit` | tick, volume and dollar bars with a buy/sell/delta split; the opt-in information-driven bars                               | [flow bars](/docs/trader/orderflow/bars)                          |
| `cvd`       | `CvdAccumulator`                                                                                                              | running Σ(buy − sell)                                                                                                      | [CVD](/docs/trader/orderflow/cvd)                                 |
| `footprint` | `FootprintBuilder`, `FootprintBar`                                                                                            | a per-bar `PriceBin` grid                                                                                                  | [footprint](/docs/trader/orderflow/footprint)                     |
| `profile`   | `VolumeProfileBuilder`, `VolumeProfile`, `PriceBin`                                                                           | price-bucketed bins, POC, 70% value area                                                                                   | [volume profile](/docs/trader/orderflow/volume-profile)           |
| `imbalance` | `depth_imbalance`, `weighted_depth_imbalance`, `ImbalanceTracker`                                                             | depth-N and inverse-distance-weighted book pressure                                                                        | [depth imbalance](/docs/trader/orderflow/depth-imbalance)         |
| `otr`       | `OtrTracker`, `OtrConfig`, `OtrSample`                                                                                        | order-to-trade ratio from consecutive top-N snapshot diffs per event-time window                                           | [order-to-trade ratio](/docs/trader/orderflow/otr)                |
| `vpin`      | `Vpin`, `BvcVpin`, `VolumeClassifier`                                                                                         | fixed-volume-bucket order-flow toxicity; the aggressor-free variant with bulk volume classification and a tick-rule option | [VPIN](/docs/trader/orderflow/vpin)                               |
| `p2`        | `P2Quantile`                                                                                                                  | the Jain–Chlamtac P² single-quantile estimator in O(1) space, for future adaptive thresholds                               | [streaming quantiles](/docs/trader/orderflow/streaming-quantiles) |

The header splits them into two families. The first five are "builders, one file each"; the last
four are microstructure studies — mechanisms from the standard literature, implemented
independently.

## Two conventions every builder shares [#two-conventions-every-builder-shares]

**Forming versus committed.** Every bar builder carries a `forming()` read, documented identically
on each: "Snapshot of the OPEN (unclosed) bar — the chart's forming bar. Pure read." The closed
bar is what `push` returns; the open one is what the chart draws while it is still filling.
`OtrTracker`'s `forming()` and `last()` "mirror the crate's forming/committed convention", so a
book-fed study reads the same way.

**Zero-size trades are skipped.** `TickBarBuilder::push` returns `None` for `size <= 0`,
`CvdAccumulator::push`, `FootprintBuilder::push` and `VolumeProfileBuilder::push` return without
touching state, and every batch `from_trades` filters on `size > 0` before folding.
`ImbalanceBarBuilder::push` says it outright: "Zero/negative-size trades are skipped entirely
(never open or advance a bar)."

## The gate discipline [#the-gate-discipline]

The header states what every builder is tested against, and it is not the parity-fixture
machinery the rest of the platform uses:

* hand-computed expected-value tests — "the real oracle — no CPython twin here";
* invariant and zero-skip tests;
* streaming ↔ batch bit-parity on `f64::to_bits`, where "batch is a genuinely separate slice
  computation, not `push` in disguise".

The book-fed studies, `imbalance` and `otr`, have no trade-slice batch twin, so they are gated as
pure functions over scripted snapshots instead. `p2` is gated against an exact full-sort quantile
oracle plus the published paper example.

<Callout title="No Python twin, so no frozen fixture">
  `crates/vike-orderflow/src/classify.rs` says it "ports no Python twin (new native)". The
  [parity gate](/docs/trader/concepts/parity-gate)'s frozen fixtures therefore do not reach this crate;
  its oracle is hand computation checked into the tests beside each builder, and its parity claim is
  the streaming-equals-batch one above.
</Callout>

## Where it is consumed [#where-it-is-consumed]

The header closes with "SP2 renders this, SP3 backfills it — both out of scope here." The
consumers name themselves in their own headers:

* `crates/vike-app-core/src/tickvol.rs` — interval strings of the form `"<n>t"` and `"<x>v"`
  select the tick and volume aggregators; `TickVolAgg` wraps one builder and converts each closed
  `OrderflowBar` to a `vike_model::Bar` for the chart's normal sync path, while the fixed kline
  set passes through unchanged.
* `crates/vike-app-core/src/orderflow.rs`'s `OrderflowAgg` buckets the drained trade tape into
  the chart's bars by open time and retains per-bar footprint cells — "the substrate SP2 renders
  from".
* `crates/vike-chart/src/orderflow.rs` derives CVD from `&[FootprintBar]`, "the single orderflow
  input — so the app feeds one structure and the renderer computes the three views"; the visible
  volume profile is this crate's own `VolumeProfile::from_footprints`, which the chart reaches
  through `ChartState::visible_profile_shared`.

Which pane draws which study is the [in the GUI](/docs/trader/orderflow/in-the-gui) page; the chart
engine itself is under [the chart](/docs/trader/gui/chart).


# Order-to-trade ratio (/docs/trader/orderflow/otr)



`crates/vike-orderflow/src/otr.rs` is the order-to-trade ratio, "a quoting-intensity study
inferred from consecutive book snapshots". Its header is candid about what it can and cannot see,
and that candour is the contract: without an order-by-order feed, messaging activity is
**approximated** by diffing the visible top-N level lists of consecutive snapshots.

## The proxy [#the-proxy]

For each side, two consecutive snapshots of the top `depth` levels are compared price by price:

| a price that is…                          | counts as     |
| ----------------------------------------- | ------------- |
| present only in the new list              | an **add**    |
| present in both with a different quantity | an **update** |
| present only in the old list              | a **cancel**  |

Prices are matched on exact bits, which is safe because "both lists come off the SAME integer-tick
grid (`L2Book::top_n` prices are `tick · tick_size`), so equal price ⇒ equal bits". The first push
has nothing to diff against and contributes no messages; it is the baseline.

<Callout type="warn" title="A level scrolling out of the window is a cancel — by construction">
  A level pushed off the top-N by a better price "counts as a cancel by construction — this is a
  visible-window proxy, not exchange message truth; document-level contract, not a bug". The tests
  pin it: a new best bid arriving on a depth-2 window reads as one add and one cancel. Read the
  ratio as activity at the visible edge of the book, not as a message count.
</Callout>

## The formula [#the-formula]

Per fixed **event-time** window — default 100 ms, configurable:

```
OTR = (adds + 2·updates + cancels) / max(trades, 1) − 1
```

An update is one cancel-plus-replace, hence two messages. The `−1` sets the baseline at parity:
"0 means one message per trade above baseline parity". The `max(trades, 1)` floor keeps a window
with no prints finite — the tests show five messages over zero trades reporting `4.0`.

## The tracker [#the-tracker]

```rust
pub struct OtrConfig { pub depth: usize, pub window_ms: i64 }   // Default: depth 10, 100 ms

pub struct OtrSample {
    pub window_start: i64, pub window_end: i64,   // end = start + window_ms
    pub adds: u64, pub updates: u64, pub cancels: u64, pub trades: u64,
    pub otr: f64,
}

impl OtrTracker {
    pub fn new(cfg: OtrConfig) -> Self;                    // asserts depth >= 1, window_ms >= 1
    pub fn push(&mut self, ts: i64, book: &L2Book, trade_count: u32) -> Option<OtrSample>;
    pub fn forming(&self) -> Option<OtrSample>;
    pub fn last(&self) -> Option<OtrSample>;
}
```

`push` folds "one observation: `ts` (event time, ms), the book to snapshot, and how many trades
printed since the previous push". It returns the committed sample only when this push crossed the
window boundary, and then "the push's own diff lands in the NEXT window". `forming()` is the open
window's counts with an interim ratio, `None` before any push; `last()` is the last committed
window. The header says the pair "mirror the crate's forming/committed convention" — the same
reading the [flow bars](/docs/trader/orderflow/bars) offer.

### Windows are event-anchored [#windows-are-event-anchored]

Two rules from the header decide where windows begin and end:

* "The first push after a close starts the next window at its own ts (idle gaps don't emit empty
  windows)." A push at 730 ms into a 100 ms window closes exactly one window, `[0, 100)`, and
  opens the next at 730 — however long the gap.
* "A push whose ts reaches `start + window_ms` FIRST closes the window (its own diff opens the
  next one)." The boundary is half-open: a push at 99 ms is still in the first window; a push at
  100 ms closes it.

The module's scripted window, from its tests: baseline at t=0; at t=50 one bid add and one ask
update with three trades; the push at t=100 closes the window with `adds 1, updates 1, cancels 0,
trades 3` and `OTR = (1 + 2·1 + 0) / 3 − 1 = 0`. The t=100 diff — a bid pulled — opens window two
with one cancel.

## How it is gated [#how-it-is-gated]

Like [depth imbalance](/docs/trader/orderflow/depth-imbalance), this study has no trade-slice batch
twin, so the crate header lists it among the studies that are "pure functions/scripted-snapshot
gated": the diff counts (identical lists, from-empty, to-empty), the window arithmetic, the
half-open boundary, the event anchoring and the trade floor are each pinned against hand-computed
values. The book it reads is `crates/vike-marketdata/src/orderbook.rs`'s `L2Book`, on the
[data model](/docs/trader/concepts/data-model) page.


# Streaming quantiles (/docs/trader/orderflow/streaming-quantiles)



`crates/vike-orderflow/src/p2.rs` is the one module in the crate that folds nothing from the
tape. Its header states what it is: "P² (Jain & Chlamtac 1985) — streaming single-quantile
estimator in O(1) space and O(1) per-observation update; the textbook five-marker algorithm with
the parabolic (piecewise-parabolic, "P²") marker-height adjustment and the linear fallback when
the parabola would break marker monotonicity." It is a "generic utility for future adaptive
thresholds (e.g. a VPIN alarm level tracking its own p95)", and the crate "keeps it pure and
venue-free like everything else here".

## Why a streaming estimator [#why-a-streaming-estimator]

An exact quantile needs the whole sample sorted. A threshold that tracks its own history — the
95th percentile of every [VPIN](/docs/trader/orderflow/vpin) reading so far — would otherwise hold a
growing buffer. P² keeps five numbers and updates them once per observation.

## The mechanism [#the-mechanism]

From the header: "five markers track (min, \~p/2, \~p, \~(1+p)/2, max) of the stream. Each
observation bumps the positions of the markers above its cell, drifts the DESIRED positions by
fixed increments, and nudges any interior marker whose actual position strayed ≥ 1 from desired —
parabolic height interpolation when the move preserves `q[i−1] < q' < q[i+1]`, linear otherwise.
The p-quantile estimate is the middle marker's height."

The struct's fields say the same in data: `q`, the five marker heights (`q0` the running min,
`q4` the running max once initialized); `n`, the actual marker positions — "1-based counts;
integer-valued, kept as f64 — every mutation is ±1.0, exact"; `np`, the desired positions;
`dnp`, the per-observation increments; and `init`, "the first ≤ 5 observations (init buffer, then
frozen)". On the fifth observation the buffer is sorted into the markers, and the desired
positions and their increments are seeded as `[1, 1+2p, 1+4p, 3+2p, 5]` and
`[0, p/2, p, (1+p)/2, 1]`.

## The surface [#the-surface]

```rust
pub struct P2Quantile 

impl P2Quantile {
    pub fn new(p: f64) -> Self;        // asserts 0 < p < 1, finite
    pub fn push(&mut self, x: f64);    // NaN is ignored
    pub fn value(&self) -> Option<f64>;
    pub fn count(&self) -> u64;
}
```

`push` folds one observation; "NaN is ignored (a poisoned marker never recovers)". `value` is
"the middle marker once ≥ 5 observations exist; the exact interpolated sample quantile of the
buffer below that; None when empty". The header's reason for the small-sample rule is that "the
algorithm is undefined below 5".

The exact form used under five samples is `interp_sorted`, the linear-interpolated quantile of
an ascending-sorted slice: "rank r = p·(m−1), value = v\[⌊r⌋] + frac·(v\[⌊r⌋+1] − v\[⌊r⌋])". The
tests walk it for the median: after 4 and 2 the value is 3; after 4, 2 and 6 it is 4; after 0,
2, 4 and 6 it is 3.

<Callout title="An estimate, not a rank">
  From the fifth observation on the value is the middle marker's height. It starts as the middle of
  the sorted first five — still an element of the sample — and each adjustment after that moves it
  by interpolation, so once the marker has moved it is generally no longer a value the stream
  contained. The parabolic step moves a marker to where the local density suggests the quantile
  sits; the linear fallback is taken only when that move would cross a neighbouring marker.
</Callout>

## How it is gated [#how-it-is-gated]

The crate header says `p2` "is gated against an exact full-sort quantile oracle + the published
paper example", and the module's tests spell out both:

* **The paper's worked example.** Table I of Jain & Chlamtac (1985): 20 observations at
  p = 0.5, whose final middle-marker height the paper gives as 4.44063. The estimator reproduces
  it within 1e-4, with `count()` reading 20.
* **Against the oracle.** Over 1000 deterministic uniforms (an LCG in the test — no random
  dependency) the estimate lands within 0.02 of the exact sorted quantile for p in {0.1, 0.5,
    0.9, 0.95}; over 2000 skewed samples (the cube of a uniform) within 0.03 for p in {0.5, 0.9} —
  "a distribution-shape robustness check, looser gate".
* **Invariants.** Under a mixed stream the markers stay sorted and the estimate stays within the
  \[min, max] of everything seen; a stream with NaNs interleaved counts only the finite
  observations and still yields a finite value.

## Where it stands [#where-it-stands]

The chart's study registry (`crates/vike-chart/src/studies.rs`) imports `Vpin`,
`ImbalanceTracker` and `OtrTracker` from this crate and not `P2Quantile`; the module header files
it under "future adaptive thresholds", and the crate header lists it beside the microstructure
studies for that reason. It is the missing piece between a toxicity level and an alarm — the
part that decides what "high" means for this instrument, from this instrument's own history.


# Volume profile (/docs/trader/orderflow/volume-profile)



`crates/vike-orderflow/src/profile.rs` is the "volume-at-price profile with POC + 70% value
area". It also owns the price bucketing the whole crate uses — the
[footprint](/docs/trader/orderflow/footprint) module borrows it rather than re-deriving it — so this
page is where a price becomes a bin.

## The shape [#the-shape]

```rust
pub struct PriceBin { pub price: f64, pub buy_vol: f64, pub sell_vol: f64 }

pub struct VolumeProfile {
    pub tick_size: f64,
    pub bins: Vec<PriceBin>,      // ascending by price
    pub poc: f64,                 // the bin price with the largest buy + sell
    pub value_area: (f64, f64),   // (low bin price, high bin price)
}
```

## Bucketing [#bucketing]

`bucket(price, tick_size)` is "the one rounding site for all price bucketing in this crate":
`(price / tick_size).round()`, an integer bucket index. `grid_to_cells` turns the sorted grid back
into ascending `PriceBin`s whose `price` is `bucket × tick_size` — a grid price, not the price of
any particular trade. Buy and sell volume per bin come from the
[classification](/docs/trader/orderflow/classification) module's `signed` split, so a bin's `buy_vol`
is aggressive buying at that grid price.

`VolumeProfileBuilder::new(tick_size)` asserts a positive tick size. `push` skips a zero-size trade
and adds the split to the trade's bucket; `finish` reduces a copy of the grid, so it can be read
repeatedly while trades keep arriving — the crate's forming convention in this module's shape.
`from_trades` is the batch twin, described in place as "separate path: collect then reduce", and
the module's parity test asserts `finish()` on a streamed builder equals it.

## The reduction [#the-reduction]

`build` is the shared reducer, used by the builder and by `VolumeProfile::from_footprints`.
Given ascending bins:

1. **Total** is Σ(buy + sell) over the bins.
2. **POC** is the bin with the largest `buy + sell`. Ties go to the **lower** price — the bins
   are ascending and the first maximum is kept.
3. **Value area** is a greedy one-bucket expansion from the POC. The target is `0.70 × total`.
   While the accumulated volume is below the target, the reducer looks at the next bin above and
   the next bin below the current range and adds whichever holds more volume; a tie goes
   **down**, to the lower price. When only one direction remains, it takes that direction; when
   neither remains, it stops. The result is `(bins[lo].price, bins[hi].price)`, and the POC is
   always inside it.
4. **Empty** input — no bins, or a `from_footprints` range that is empty or out of range —
   produces `poc = 0.0`, `value_area = (0.0, 0.0)` and no bins.

The module's own worked example, from its tests: four trades at tick 1.0 — 5 bought at 100, 10
sold at 101, 3 bought at 102, 1 bought at 99. Total 19, so the target is 13.3. The POC is 101
(volume 10); adding 100 (volume 5) reaches 15 ≥ 13.3, so the value area is `(100, 101)`.

<Callout title="The tie rules are part of the contract">
  Both ties — POC and value-area expansion — resolve toward the lower price. That is what makes the
  profile a deterministic function of the trades; two paths that reduce the same grid produce the
  same POC and the same value area bit for bit, which the streaming ↔ batch and
  footprint-merge tests rely on.
</Callout>

## From footprints [#from-footprints]

`VolumeProfile::from_footprints(footprints, tick_size, lo, hi)` merges "the cells of
`footprints[lo..=hi]` (clamped to range) into one volume-at-price profile with POC + 70% value
area". It re-buckets each cell's price through the same `bucket`, so "`tick_size` must match the
footprints' bucketing". The tests pin that merging all of a chart's footprints equals the direct
builder over all of its trades, and that a sub-range excludes exactly the bars outside it.

That is the form the chart uses: `crates/vike-chart/src/chart/price_render.rs`'s
`paint_volume_profile` reaches it through `ChartState::visible_profile_shared`, so the profile a
pane shows is the profile of the bars in view, computed from the same cells the footprint pane
draws. Where it renders is the [in the GUI](/docs/trader/orderflow/in-the-gui) page.


# VPIN (/docs/trader/orderflow/vpin)



`crates/vike-orderflow/src/vpin.rs` carries two estimators of the same quantity. `Vpin` is the
aggressor-classified form: it reads each trade's side through the
[classification](/docs/trader/orderflow/classification) module, "the crate's one load-bearing
semantic". `BvcVpin` is the canonical Easley, López de Prado and O'Hara form, which needs no
aggressor flag at all — price and volume only. Both are streaming, pure, and gated
streaming-against-batch like every builder in the [crate](/docs/trader/orderflow).

## The mechanism [#the-mechanism]

The trade stream is chopped into fixed-**volume** buckets of `bucket_volume`. A trade that
overflows the open bucket spills its remainder into the next — the same splitting convention as
`bars::VolumeBarBuilder` on the [flow bars](/docs/trader/orderflow/bars) page. Each completed bucket
scores an order-flow toxicity imbalance:

```
|Vbuy − Vsell| / Vbucket ∈ [0, 1]
```

VPIN is the rolling mean of the last `window` completed buckets — `DEFAULT_VPIN_WINDOW` is 50 —
"maintained as an O(1) rolling sum (add-newest/subtract-evicted — never a window re-scan on the
hot path)".

The module's hand-computed case, pinned in its tests: with a bucket volume of 4, two buys of 2
fill the first bucket at an imbalance of 1.0; a sell of 1, a buy of 1 and a sell of 2 fill the
second at |1 − 3| / 4 = 0.5; VPIN reads (1.0 + 0.5) / 2 = 0.75.

## `Vpin` — the aggressor-classified form [#vpin--the-aggressor-classified-form]

```rust
impl Vpin {
    pub fn new(bucket_volume: f64) -> Self;            // aggressor-classified, window 50
    pub fn with_params(bucket_volume: f64, window: usize, has_aggressor: bool) -> Self;
    pub fn push(&mut self, t: &TradeTick, mid: Option<f64>) -> Vec<f64>;
    pub fn committed(&self) -> Option<f64>;
    pub fn forming_bucket(&self) -> Option<VpinBucket>;
    pub fn interim(&self) -> Option<f64>;
    pub fn completed_buckets(&self) -> usize;
    pub fn bucket_imbalances(trades: &[TradeTick], bucket_volume: f64) -> Vec<f64>;
    pub fn from_trades(trades: &[TradeTick], bucket_volume: f64, window: usize) -> Option<f64>;
}
```

Construction asserts a finite, positive `bucket_volume` and a `window` of at least 1. `push`
folds one trade and "returns the imbalances of every bucket this trade COMPLETED (usually empty;
≥ 2 when one big trade spans several buckets)"; a trade of non-positive size is skipped.

**Classification.** With `has_aggressor` — the default — each trade routes by `classify`. A feed
without a real aggressor flag constructs with `has_aggressor = false` and passes the prevailing
mid to `push`: `price >= mid` is a buy, else a sell — the quote-midpoint test. "A missing mid
falls back to the aggressor flag so no trade is ever dropped."

**Forming versus committed.** The convention mirrors `bars`: `committed()` reads completed
buckets only and is `None` until the first bucket completes. `forming_bucket()` and `interim()`
are pure reads that fold the open bucket's partial imbalance, |b − s| / filled, in "as the NEWEST
window sample (evicting the oldest when the window is full), without mutating state".
`interim()` falls back to `committed()` when nothing is forming, and is `None` only before any
volume has arrived.

**Batch twins.** `bucket_imbalances` is the full completed-bucket series with the trailing
partial bucket dropped; `from_trades` is the last ≤ `window` entries of that series under "a
naive-fold mean — a fresh sum, NOT the streaming rolling sum". The parity tests state what the
two forms owe each other: on exact-dyadic sizes streaming and batch are bit-identical even past
eviction; on non-dyadic sizes the per-bucket imbalances stay bit-identical (same fold order) and
the rolling-sum mean may differ from the fresh fold only at rounding noise.

## `BvcVpin` — the aggressor-free form [#bvcvpin--the-aggressor-free-form]

The header cites the paper: Easley, López de Prado & O'Hara (2012), "Flow Toxicity and Liquidity
in a High-Frequency World", *Review of Financial Studies* 25(5):1457–1493 — "the paper that
defines VPIN and &#x2A;*Bulk Volume Classification (BVC)**".

* **Buckets.** Equal-volume buckets of `bucket_volume` (VBS), with the same spill convention.
  Each bucket's close price is the price of the trade that filled it.
* **BVC.** A bucket's directional split comes from its price change, not from trade-level tags:
  `buy_frac = Φ((P_i − P_{i−1}) / σ_ΔP)`, where Φ is the standard-normal CDF (`norm_cdf`, a
  `libm` `erf` mirroring `vike-options`) and σ\_ΔP is the population standard deviation of bucket
  price changes over the last `window` buckets. Then `V_buy = VBS·buy_frac`,
  `V_sell = VBS·(1 − buy_frac)`, and the bucket imbalance is `|2·buy_frac − 1|`.
* **The value.** `value()` is the rolling mean of the last `window` imbalances — and `None` until
  `window` of them exist. The first bucket close only sets the `P_{i−1}` reference: "a price
  CHANGE needs two closes, so N imbalances need N+1 closes". The tests pin the boundary — a window
  of 2 is ready on the third close.
* **The tick-rule option.** `VolumeClassifier::TickRule` classifies each bucket wholly by the sign
  of ΔP: up → all buy, down → all sell, flat → balanced. It is "the degenerate limit BVC itself
  falls back to when σ\_ΔP is undefined".
* **Degenerate guards.** A non-positive or non-finite `bucket_volume` and a `window` below 1 panic
  at construction; a non-positive-size trade is skipped; σ\_ΔP ≤ 0, or fewer than two ΔP samples
  (the warm-up), falls back per bucket to the tick rule — "so a flat tape yields `0.0` (no NaN
  from `Φ(0/0)`) and a one-way tape yields `1.0`".

The worked series from the tests: closes 100, 101, 100. The first is the reference; the second
gives ΔP = +1 with one sample in the σ window, so the tick rule fires and the imbalance is 1.0;
the third gives ΔP = −1 against σ = 1, `buy_frac = Φ(−1)`, and an imbalance of
`|2·Φ(−1) − 1| = erf(1/√2) = 0.6826894921370859`.

### A side as well as a magnitude [#a-side-as-well-as-a-magnitude]

`value()` is deliberately side-less. `directional_bias()` is the signed rolling mean of
`(2·buy_frac − 1) ∈ [−1, 1]`: "`> 0` buy-toxic → ask side, `< 0` sell-toxic → bid side — so a
caller can route the magnitude onto a per-side gate". It shares `value()`'s readiness gate.

### Feeding it [#feeding-it]

`on_trade(price, size)` buckets internally and returns the imbalance of every bucket the trade
completed (empty for the very first bucket); `on_trade_tick` is the `TradeTick` convenience, with
the aggressor flag "deliberately unused — BVC needs none". A caller that has already formed
equal-volume buckets feeds their close prices to `on_bucket(close)` instead — the two must not be
interleaved on one instance. The batch twins are `imbalances_from_closes` ("a genuinely separate
slice computation (NOT `on_bucket` in disguise)") and `from_bucket_closes`; the σ fold order is
shared verbatim between the streaming and batch paths, so the per-bucket imbalance series is
bit-identical across them.

## In the chart [#in-the-chart]

The chart engine's study registry (`crates/vike-chart/src/studies.rs`) builds its `vpin` entry —
"VPIN (order-flow toxicity)" — on the aggressor-classified `Vpin`: bucket volume 1000 by default,
window 50 (2 to 1000), an aggressor-flag switch whose `0` selects quote-midpoint classification,
and reference bands at 0.2, 0.5 and 0.8. It is the one study that needs trades only and is never
book-gated. What that registry can reach in the shipped app is on the
[in the GUI](/docs/trader/orderflow/in-the-gui) page; a walkthrough over a recorded tape is the
[VPIN tutorial](/docs/trader/tutorials/orderflow-vpin-study).

<Callout title="A level, not an alarm">
  Neither estimator emits a signal. A threshold that adapts to its own history is what the crate's
  [streaming quantile](/docs/trader/orderflow/streaming-quantiles) exists for — its header names "a VPIN
  alarm level tracking its own p95" as the intended use.
</Callout>


# Environment variables (/docs/trader/reference/environment)



Three rules govern the environment, each because its opposite produced a real defect.

## The ceilings are not env-settable, at all [#the-ceilings-are-not-env-settable-at-all]

`vike_config::Policy` — leverage, per-order notional, the slippage band, the halt-file admit mode,
the per-venue arming ceiling — implements neither `EnvOverride` nor `CliOverride`, and
`crates/vike-config/src/layers.rs` seals both traits, so an override is a compile error rather than
a review comment. Everything else resolves default, then file, then environment, then CLI.
[Settings](/docs/trader/concepts/settings) carries the split; the files are on the
[settings reference](/docs/trader/reference/settings).

## Removed variables refuse to start [#removed-variables-refuse-to-start]

Deleting a read is only half the job. An operator who set `VIKE_MAX_ORDER_NOTIONAL=250` believes a
ceiling is active; a build that quietly stopped reading it would trade **uncapped** while they
believed otherwise. `crates/vike-config/src/removed.rs`'s `REMOVED_ENV` is the table, and
`refuse_removed_env` is the first step of startup for every root that loads settings —
`vike-desktop`, `vike-tradehub` and `vike-cli`:

| variable                           | replaced by                              | why it went                                                                           |
| ---------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------- |
| `VIKE_MAX_ORDER_NOTIONAL`          | `policy.toml` — `max_notional_per_order` | an order-size ceiling any exported variable can raise is not a ceiling                |
| `VIKE_TRADEHUB_MAX_ORDER_NOTIONAL` | `policy.toml` — `max_notional_per_order` | an order-size ceiling any exported variable can raise is not a ceiling                |
| `VIKE_SECRETS_PASSPHRASE`          | `secrets.env`                            | nothing consumes it — credentials are read from the project's own store, in plaintext |

"Set" means present with a **non-empty value after trimming**: an empty `VAR=` configured nothing
under the old readers either, so refusing over a leftover blank line would turn a harmless artefact
into an outage. Every offender is reported in one pass, and the message renders the operator's own
value as a paste-ready TOML line — unless the value would itself be a secret, where `echo_value` is
`false` and only the name is printed, since echoing one turns a startup error into a credential in
any log capturing stderr.

Two daemons deliberately do **not** refuse, each stating its reason in its own boot spec rather
than as a bare flag — `crates/vike-boot/src/lib.rs`'s `RemovedEnv::Ignore`. The recorder and the
data service read none of the ceilings whose variables were removed, and a recorder must not
acquire a new reason to fail to start; on those boxes `vike-cli config check`, which the shipped
units put in their `ExecStartPre=`, is the surface that refuses a stale environment.

<Callout type="warn" title="A removed FILE refuses the same way — and says which of two things it found">
  A `<project>/vike.toml` override layer once sat above `<project>/settings/`, reintroducing the
  &#x2A;which file won?* question that directory exists to answer. It is refused by name from inside the
  loader, and **only `NotFound` counts as absent** — anything else means absence was not established,
  so it refuses too, with a different message. Under
  a service sandbox a stat below the home tree returns `EACCES`, not `ENOENT`, and the fail-closed
  verdict once named a file that did not exist. Nothing here rewrites the file: it is the operator's.
</Callout>

## Every read is declared [#every-read-is-declared]

`vike_ops::settings::SETTINGS&#x60; is a verbatim registry of every environment variable the workspace
reads: one row per &#x2A;*(name, crate)** pair, carrying scope, the layer the read happens at, how the
name reaches the code, and the documented default. The table is data — the runtime never consults
it. It exists so `crates/vike-ops/tests/settings_registry.rs` can gate the source tree and the table
against each other **both** ways: an undeclared `env::var` fails CI, and so does a stale row.

`Layer` encodes the rule the registry exists for — &#x2A;libraries take configuration as parameters; only
binaries read the process environment.* `Binary` and `Injected` (a pure parser over a caller-supplied
map) are the correct shapes; `Library`, a direct `env::var` under `src/` outside a binary, is the
work list. That list is a **ratchet**: `LIBRARY_PIN` holds it as a fixed-size array, so it may shrink
but never grow. It had to be — the count went from 60 on 2026-07-29 to 77 a week later, across five
changes that each had no reason to notice.

## Finding out what a box is actually reading [#finding-out-what-a-box-is-actually-reading]

`vike-cli config show --section env` prints the registry resolved against this machine, with
`--filter` (a substring of the name or the reading crate), `--changed-only` and `--json`. The store
precedence is **process env, then the credential store, then the documented default**, and
*presence* wins rather than non-emptiness: an exported `NAME=` beats the store with an empty string,
reported as such.

<Callout type="warn" title="That order is what the stores support, not a promise any reader honours">
  Most consumers read exactly one store, so a `source` word alone would assert a provenance the tool
  cannot verify. Every row therefore also prints what its reader *does*: `env` for a direct
  `env::var`, `caller-map` for a map the caller supplies, `unknown` for a computed name. A value found
  only in the credential store while its reader calls `env::var` is warned about under the table.
</Callout>

Redaction happens on construction, inside the resolver rather than in either printer, so `--json`
cannot leak what the table hides. One disclosure is stated rather than hidden: the registry declares
the whole per-venue, per-tier API-key grid, so the table **names** those keys and marks each set or
unset — pasted output shows which venues a box holds keys for, never a value.

## Three worth knowing before you need them [#three-worth-knowing-before-you-need-them]

`VIKE_SETTINGS_DIR` names the settings directory outright, honoured before any filesystem probe and
skipping the project walk entirely. A blank value is *ignored* rather than honoured: an empty
`Environment=VIKE_SETTINGS_DIR=` line would otherwise resolve settings to the working directory.

`RUST_LOG` (aliased `VIKE_LOG`) filters **the console only**. The file layer defaults to `trace` and
captures the `log`-to-`tracing` bridge, so a batch tool driving a chatty dependency writes a JSON
file no console setting can turn down: one hour of a backfill measured **6.4 GB**, and a long range
once wrote 341 GB and nearly filled the disk hosting a live trading node. `VIKE_LOG_FILE_LEVEL=warn`
(or `off`) is the switch — see [log volume](/docs/trader/data-providers/log-volume). `VIKE_LOG_DIR` tops
the log-directory precedence, above a config file's `log_dir` and the project's own
`settings/state/logs`. The gates behind all of this are on
[settings gates](/docs/trader/developer/settings-gates).


# Reference (/docs/trader/reference)



Vike Trader is not one program with a window bolted on. It is **one core** and several front ends
that observe it, so the question of which binary to run is the question of which front end you
want.

## The core [#the-core]

`crates/vike-core/src/lib.rs` is the single-writer live core: **one thread owns all mutable trading
state**, ingest arrives through the `vike-exec` lanes, and readers take a lossy `arc-swap`
`CoreSnapshot` and never back-pressure the writer. Producer lanes live in `vike_exec::lanes`, so
venue bridges never depend on the core crate at all. Nothing that renders, serves or reports gets
to touch that state directly — every front end below is a reader of published snapshots and a
sender of commands.

## The front ends [#the-front-ends]

**The desktop app** (`crates/vike-desktop/src/main.rs`) is a native egui multi-window shell. Market data
flows feed threads to core ingest, the core-owned bar cache to the `arc-swap&#x60; snapshot, and the GUI
converts each changed snapshot into its render model: &#x2A;"the GUI is a lossy observer; it never
touches the core's state directly."* The shipped build compiles out the whole
local-core, DataFusion and venue-bridge subsystem, leaving an observer client. See
[the GUI section](/docs/trader/gui) and [`vike-desktop`](/docs/trader/reference/binaries/vike-desktop).

**The daemon** (`crates/vike-tradehub/src/lib.rs`) is the same core, headless. Its testable
internals live in a library so integration tests can drive them; the slim bin composes them into a
process lifecycle — log init, node build, stdio control, bounded teardown. Two modules are the
shape worth knowing: `publish` projects `CoreSnapshot` into `WireSnapshot` and runs the **one**
publisher thread that fans coalesced frames to subscribers over bounded, drop-oldest mailboxes,
never touching the hot fold; `server` is the authenticated node server, where a `Scope::Control`
peer's request is lowered into the core's real `Command`/`OrderIntent` — and only when the daemon
threads a command sink in. See [the node protocol](/docs/trader/concepts/node-protocol) and
[`vike-tradehub`](/docs/trader/reference/binaries/vike-tradehub).

**The CLI** (`crates/vike-cli/src/lib.rs`) is a subcommand dispatcher in the git/cargo style. It
routes and never grows command logic. `run` resolves settings first, so a removed environment
variable is refused before any verb executes, and the credential-store read is **lazy**: no verb
opens the file that holds every venue key on the box until it needs it — the node-facing arms
(`trade`, `mcp`, `strategy-status`) for their node keys, and `config show`, `config check` and
`secrets list` for their own disclosure reads. A backtest or provenance command never opens it at
all. `config check` makes the exit code the product, which is what the shipped service units put in
their `ExecStartPre=`. See [the CLI reference](/docs/trader/reference/cli).

**The data service** (`crates/vike-datahub/src/lib.rs`) inverts the direction: a client sends a
small backtest *profile* over a localhost socket, the server runs the existing `vike-backtest`
engine next to the data, and returns only the report. The heavy history never crosses the wire.
It owns no engine — it is assembly of crates that already exist — and its transport is blocking
`std::net`, thread-per-connection, with length-prefixed JSON frames: no async runtime, no second
HTTP stack. See [`vike-datahub`](/docs/trader/reference/binaries/vike-datahub).

## Library plus thin bin — and one executable that carries them all [#library-plus-thin-bin--and-one-executable-that-carries-them-all]

Each tool's body lives in its crate's library and its `main.rs` is a shim, so a second dispatcher
can reach the same code without a static copy of it. That dispatcher is `crates/vike/src/lib.rs`,
and the reason is measured: &#x2A;*2026-09-01, release profile — `vike-tradehub` 128 MB, `backtest`
106 MB, `vike-datahub` 107 MB, while `vike-cli` is 9.6 MB and `tearsheet` 1.9 MB.** The gap is one
static copy of DataFusion/arrow/parquet per binary, and an image that ships all of them pays it
every time. Folding the tools into one executable links that closure once.

<Callout type="warn" title="One tool per process">
  Every tool owns process-global state that assumes it is alone — logging init where only the first
  configuration wins, signal handlers, a scripting one-shot, a dozen `OnceLock`s. A run that executed
  two tools in one process would silently give the second the first one's logging and signal
  handlers, so the dispatcher **refuses a second call** rather than documenting the hazard, and
  `crates/vike-ops/tests/multicall_gate.rs` holds the refusal by reading the source.
</Callout>

The dispatcher itself does nothing: no boot, no logging, no signal handler, no project resolution.
That restraint is load-bearing. Every tool calls the shared startup sequence for itself, and a
dispatcher that also resolved the project would make one process walk for its settings **twice** —
where the second walk is blind to `VIKE_SETTINGS_DIR` and answers from whatever directory the
process happens to sit above. What it does pass down is a context carrying the one environment
sweep and the one working directory for the whole process.

## Every front end starts the same way [#every-front-end-starts-the-same-way]

`crates/vike-boot/src/lib.rs` owns the startup sequence once, because five composition roots used
to hand-assemble the same ordered steps: refuse a removed environment variable, resolve
`<project>/settings`, load the credentials, load the settings, derive the project-relative paths,
build the log subscriber, then disclose what was resolved. **One walk decides**, and the log
subscriber comes last deliberately — the log directory and both log levels are themselves settings,
so a subscriber built first could only ever honour the environment. That crate therefore logs
nothing at all and returns everything as data, which is also what lets a binary whose stdout is a
protocol choose its stream.

## In this section [#in-this-section]

* [CLI](/docs/trader/reference/cli) — the dispatcher and one page per verb.
* [Binaries](/docs/trader/reference/binaries) — every bin target in the workspace, derived at build time.
* [Settings files](/docs/trader/reference/settings) — the four TOML files and `alerts.json`, key by key, with each key's consumer.
* [Environment variables](/docs/trader/reference/environment) — the registry, and the variables refused at startup.


# Feature importance (/docs/trader/research/feature-importance)



`crates/vike-ml/src/importance.rs` answers a question about the fit rather than about a
prediction: which feature columns did the trees actually split on, and how much gain did each one
contribute. Its header explains why the parser lives in `vike-ml` — everything it knows is a fact
about this crate. It parses the text `train` tells LightGBM to write and `parse` reads back, it
was verified against the binary `pins` pins, its column convention is `TrainData::write_csv`'s,
and what it reconstructs is precisely `split_gain`, one of the fields
`crates/vike-ml/src/model.rs` states it parses past and drops because inference has no use for
it. A consumer that owned this parser would be documenting the crate's format from the outside and
would need re-verifying every time either side moved; it was written that way once, in a research
crate since dissolved, and this is that file having come home.

The header is emphatic that [inference](/docs/trader/research/inference) reads none of this.
`importance_from_model_text` is a separate fold over the same text, and nothing about it changes
what the walker keeps.

## The format, verified rather than remembered [#the-format-verified-rather-than-remembered]

The header records the verification: trained with the pinned v4.7.0 binary on a CSV in the exact
shape `write_csv` produces — label first, no header — the model text carries:

* a header line `max_feature_idx=<N-1>`, where the label column is *not* counted, and
  `feature_names=Column_0 Column_1 …` — auto-generated, because the training CSV this crate writes
  has no header. The model file therefore cannot name a caller's columns; index-to-name mapping
  belongs to whoever packed the matrix, and a length equality against `max_feature_idx + 1` is the
  only honest check available;
* per `Tree=<k>` section, `split_feature=` (one feature index per internal node,
  `num_leaves - 1` of them) and `split_gain=` (the same count, pairwise: entry `j` of both
  describes the same split);
* for a constant tree — `num_leaves=1`, LightGBM's `AsConstantTree` when a fit could not split —
  both keys with an empty value, not an absent line. Hand-written minimal models omit the lines
  entirely; both spellings mean zero splits and both are accepted;
* `end of trees`, after which per-tree lines never appear. Anything after it — the parameter echo
  LightGBM writes there — is ignored.

## The result [#the-result]

`FitImportance` is plain data: `n_features`, the feature count the *model* declares
(`max_feature_idx + 1`), and two vectors indexed by feature column position — `gain`, the total
split gain per feature with `0.0` for one no tree ever split on, and `splits`, how many splits
used each feature with `0` for one never used. The three lengths agree by contract. The field doc
on `n_features` says what the caller does with it: compare it against the matrix it packed and
refuse on mismatch, because a misaligned index-to-name mapping silently attributes importance to
the wrong feature. The explicit zeros are the "which columns were never used" half of the report.

## Why it refuses instead of shrugging [#why-it-refuses-instead-of-shrugging]

The header's argument: a misaligned importance table is worse than none, because it attributes
the model's behaviour to the wrong named feature and poisons every downstream pruning decision. So
each of the following is an `Err` naming the tree, never a row silently skipped:

* a `split_feature=` / `split_gain=` pair whose counts disagree;
* a `split_feature` index at or past the declared width — the test for it is called *the*
  misattribution guard, since growing the vector would let a model trained on a wider matrix than
  the caller packed produce a plausible table whose every row is shifted;
* an unparsable entry in either array;
* a `split_feature=` or `split_gain=` line without its partner, which the message calls a
  doctored or truncated tree section;
* either key appearing twice in one tree;
* a `Tree=` section arriving before `max_feature_idx=`, or a text with no `max_feature_idx=` at
  all.

The error is a `String` rather than `MlError`, and the header says why: every message names a
tree, and neither candidate variant frames that — `Parse` wants a line number this fold
deliberately does not track, and `Shape` renders a pairing fault as a row/feature count. The whole
value of these refusals is the sentence.

<Callout title="Structural completeness is the other parser's job">
  A text that never said `end of trees` still folds its last tree here. `parse_model_text`, which
  runs first on every real fit, is the authority on whether a model file is complete; this parser's
  own job ends at correct pairing.
</Callout>

## How a study asks for it [#how-a-study-asks-for-it]

`crates/vike-ml/src/learner.rs`'s `fit_captured` doc records how the request reaches a fit. The
importance table and the model text are both artifacts of one fit, and `Learner::fit_captured`
(`crates/vike-ml/src/learner.rs`'s `Capture` and `CapturedFit`) carries the request as a parameter
rather than as a second method, so a caller asking for both never pays for the fit twice. The two
artifacts are independent by construction — a text-only request runs no importance parse and
cannot be failed by one — and what each absence costs is the caller's decision, not the crate's.
The shared test double, `ScriptedLearner`, reports a scripted `FitImportance` only when a
`Capture` actually asks for it, the way a real learner answers.
[Train a model](/docs/trader/tutorials/train-a-model) is the tutorial that reads the table out of a
study.

## The one scorer: `binary_logloss` [#the-one-scorer-binary_logloss]

`crates/vike-analytics/src/metrics.rs` holds the crate's scores over predictions — pure functions, no
model and no training involved. It ships one: `binary_logloss(labels, probs)`, the mean binary
cross-entropy `-mean(y ln p + (1 - y) ln(1 - p))`, lower is better. Its doc pins three edges. Each
probability is clamped to `[LOGLOSS_EPS, 1 - LOGLOSS_EPS]` with `LOGLOSS_EPS = 1e-15`, the value
LightGBM's own metric uses, because without it a confidently wrong prediction scores `+inf` and a
search would rank two catastrophic candidates as equal. An empty input returns `NaN` rather than
`0.0`, because zero is the best possible score and an empty validation fold would otherwise win a
grid search outright. A length mismatch scores over the shorter overlap: the signature is
infallible, and truncating to the aligned prefix never fabricates a label or a probability.

Two arithmetic choices are deliberate and opposite to the walker's. The sum is
`vike_model::py_sum`, the workspace's Neumaier-compensated fold, and this is the only place in the
crate that uses it — hundreds of small logs in arrival order are exactly what compensation exists
for — while the tree walk does a plain fold because it must reproduce LightGBM's accumulation bit
for bit. And both logarithms are `libm::log`, not `f64::ln`: the doc records that the platform
libms disagree in the last bit across most of this function's domain, and a log-loss is a number
two grid points are ranked by, so a last-bit difference is a different winner at a tie.

<Callout type="warn" title="Nothing in the workspace calls it yet">
  The doc says so plainly: `binary_logloss` is latent public-API surface. No caller's fixtures move
  when the arithmetic underneath it changes, and the first caller will be measuring the `libm`
  answer from its first run.
</Callout>


# The fit cache (/docs/trader/research/fit-cache)



`crates/vike-ml/src/fit_cache.rs` is the cross-run fit cache: a validation score that a previous
run already computed for these training bytes, this hyperparameter point, this seed, this
validation half and this objective is not refitted. It sits over the learner seam described in
[Models](/docs/trader/research/models), and `crates/vike-ml/src/lib.rs`'s header explains why it lives
in the library rather than in a study — a cache over a learner is library work, and a second
consumer of the seam would otherwise have to rewrite it.

## Why it exists, measured [#why-it-exists-measured]

The module header carries the numbers. Fitting is the whole cost of a hyperparameter search: one
20-trial run of the study that first needed this cache was about 1,591 LightGBM fits at a p50 of
6.9 s each, spawn and I/O were 2.3% of a fit, so wall clock is fits divided by parallelism and the
only lever is fewer fits. Cross-run duplication is real for any search: a seed-deterministic TPE
startup deck means a 20-trial and a 50-trial run at the same search seed share every startup point
per fold, seed sweeps overlap on grid points, and a re-run of an identical config duplicates
everything. Those are searches over model fits — the header places them in the cohort study that
first needed the cache — not the strategy-parameter sweeps over backtests that
[Search](/docs/trader/backtesting/search) describes.

## The constraint that outranks everything [#the-constraint-that-outranks-everything]

The header states it in one line: &#x2A;*a wrong cache hit silently corrupts results and is worse than
no cache.** So the key content-addresses the actual bytes the fit consumes, never descriptions of
them — not a path, not a fold id, not a config name. `score_key` is a SHA-256 over three parts, in
an order the doc says is frozen because it is the address of every entry in every existing
on-disk cache:

1. **The fit identity**, produced by the learner through `Learner::fit_identity`
   (`crates/vike-ml/src/learner.rs`), because only the learner knows what its trainer eats. For
   the real learner, `crates/vike-ml/src/gbdt_learner.rs`'s `GbdtLearner`, the header lists what
   it covers: the training CSV bytes exactly as `TrainData::write_csv` streams them to the
   binning, the rendered train config and the rendered save-binary config with their path lines
   normalised (every searched axis, the fit seed, the categorical declaration and every
   non-searched parameter among them), the model text-format version, and the trainer binary's
   `PROVENANCE` file bytes. The trait doc adds the contract: two calls may share an identity only
   when their fits are bit-identical by construction, and a shape `fit` would refuse gets no
   identity, so a refusal is never served from a cache.
2. **The validation half's own bytes** — `n_rows`, `n_cols`, every feature's bit pattern and every
   label: the exact in-process input to `predict_proba` and to whatever scores its output.
3. **The objective identity** — an opaque digest the caller supplies, for the same reason the
   learner supplies the first part.

Two hashing tools make that possible. `Transcript` is a domain-separated transcript in which every
part enters as its own fixed-width digest, so two part sequences with equal concatenations can
never collide — the framing a plain running hash lacks. `DigestWriter` is an `io::Write` that
hashes instead of storing, which is what lets an \~8 MB training CSV enter the key as its exact
bytes without ever materialising; its `f64_bits` hashes the bit pattern, not the value, because
`-0.0` and `0.0` are different bytes on every wire a trainer reads and `NaN` must hash stably.

## What the crate deliberately does not own [#what-the-crate-deliberately-does-not-own]

The objective is a digest this crate cannot compute, and the header says that is structural: the
workspace's scorers live in `vike-analytics`, which declares the same layer as `vike-ml`, and the
layer gate forbids the edge. The caller hashes its own objective and every parameter it scores
with, using `Transcript` and `DigestWriter`, and hands the result in.

A learner that cannot prove its inputs' identity answers `None` from `fit_identity` — the default
— and is simply never cached: a refit, never a wrong answer. `crates/vike-ml/src/test_support.rs`'s
header records that the crate's own test double, `ScriptedLearner`, answers `None` deliberately,
because the only way a scripted double could key on its own behaviour is a caller-supplied salt,
and two doubles scoring differently at one salt would share every key — exactly the wrong hit.
`crates/vike-ml/tests/learner_double.rs` pins both directions: a cache over the double never hits,
and the same cache does hit for a learner that answers an identity.

<Callout type="warn" title="Content-addressing is exactly as reproducible as its inputs">
  The header records that a data source which does not answer one request the same way twice —
  parallel-reduction noise in a server-side aggregate — gives every re-run a fresh key for every
  fit, stores thousands of entries and grows a directory that is never read. That happened for four
  weeks to the first consumer. The cure was to canonicalise at the parse boundary
  (`crates/vike-backfill/src/vikedata/parse.rs`'s `canonical_notional`), and it deliberately does
  not live in the key: snapping inside the key would declare two genuinely different datasets
  equivalent, the wrong hit this design refuses.
</Callout>

## The frozen tag [#the-frozen-tag]

`KEY_SCHEMA` is the key's domain tag, and its value is the string `vike-research fit-cache v1`.
Its doc says the spelling is frozen on purpose: renaming it *is* a bump — it re-keys every entry
in every existing on-disk cache — and a move that changes no keyed byte has no business charging
a user thousands of refits for a tidier constant. The crate it names has been dissolved and
deleted, and that changes nothing; a domain tag is allowed to name something that no longer
exists. `the_key_bytes_are_frozen` pins the whole key over a fixed vector against a digest
computed outside this implementation. The one legitimate reason to bump it is the declared
residual: the in-process inference and the scorer bodies are code, not data, so a change to them
moves scores without moving any keyed byte. `gbdt_learner.rs`'s fit-identity tag,
`vike-research fit-identity v1`, is governed by the identical argument.

## The value, the directory, the failure modes [#the-value-the-directory-the-failure-modes]

The value is the validation score — one `f64` — never the model file: only the score enters an
argmin, and a caller's final refit, whose model is consumed, is deliberately not cached. Entries
are one file per key, named by the key's hex, holding a magic line and the score's 64 bits as 16
hex digits (`entry_bytes`, read back by a strict whole-file `parse_entry`).

`FitCache::dir_beside` owns the one location rule that is a property of the cache: the directory
is a sibling of the caller's scratch root, never a child, so a scratch wipe does not empty it and
every run of every config shares one pool. The directory's *name* is the caller's, because it is
part of an application's on-disk layout and renaming it orphans a user's accumulated entries as
surely as a `KEY_SCHEMA` bump invalidates them.

A corrupt or uninterpretable entry is a miss — deleted on the way to `None` and refitted — never
an error, because a cache must not be able to fail a run. A non-finite score is never persisted: a
caller that folds a deterministically rejected point and a transient spawn failure into the same
`INFINITY` would otherwise make the transient permanent for that key. Two threads racing on one
key both fit and both store; the values are equal by construction, so last-write-wins through
`store`'s atomic rename is benign, with a remove-and-retry fallback for Windows, which refuses a
rename over an existing file. `note_hit` and `note_miss` are public because the code that decides
a hit is a hit lives in whichever crate owns the search loop; `FitCacheStats` is what a run
summary line prints so reuse is visible.

The cost, per `lib.rs`: the crate now owns a hash, and its dependency list grew from `vike-model`
alone to `vike-model` plus `sha2` and `hex` — both already linked into every binary in the
workspace by `vike-bridge-core`'s signer, so nothing new entered the
[supply-chain](/docs/trader/developer/supply-chain) audit surface.


# Research (/docs/trader/research)



Research in Vike Trader is a loop with four stations: a **study** asks a question of recorded
data, a **fit** trains a model where the host can train one, a **score** turns the answer into
numbers, and a **run** is what stays on disk afterwards, listed beside every backtest. All four
live in one headless crate, `vike-studio-core`, whose `crates/vike-studio-core/src/lib.rs` header
describes it as the Studio backend extracted from the GUI so headless consumers can reuse it
without egui — the in-app AI loop is one, and the retired MCP server was another before its tool
surface moved to `vike-cli mcp`. There is no GUI in it, which is why CI can test the whole loop.

## The four stations [#the-four-stations]

**A study** is a function called once with a context and a recipe, returning named numbers and
named text artifacts. It comes in two tiers — interpreted [Rhai](/docs/trader/research/rhai-studies)
and compiled [Rust](/docs/trader/research/rust-studies) — and the `lib.rs` header records why the
interpreted one lives here rather than beside its strategy twin: this is the only layer that can
see both `vike-script` (the Rhai precedent) and `vike-user-research` (the study contract), because
the lower crate may not name the higher. It also records the one property the interpreted tier has
that the compiled one cannot: *in a script, the sanctioned surface is enforcement*.

**A fit** goes through the learner seam in `vike-ml` — [Models](/docs/trader/research/models) — and the
trainer is the upstream LightGBM binary driven as a child process,
[Training](/docs/trader/research/training). The crate's own `ml` module is deliberately the *inference
half only*: it loads a model somebody already trained from its text, scores rows into a probability
series and reports which input mattered, and fits nothing. The platform fact behind that split is that
the trainer binary is a Linux x86-64 executable and is not staged on any other host, while
`crates/vike-ml/src/infer.rs` is pure Rust
over the model text and works everywhere. So a study fits wherever it can fit, and
[Inference](/docs/trader/research/inference) reads what came out.

**A score** is the study's own business. What the runner asserts about it is only the structurally
true negative — `crates/vike-studio-core/src/study_run.rs`'s `STUDY_METRICS_NOTE` says a study's
numbers were *produced by a study, not by the event-driven simulator*, because
`vike-user-research` declares no `vike-backtest` dependency, so no order book, queue position or
fee schedule took part. That is why a study's metrics are never comparable with a backtest run's,
and why the run format keeps them apart (below).

**A run** is minted by `study_run` — the header calls it *what puts a study run there*, and
explains why the study crate cannot do it itself: run persistence lives above it in the layering,
so a study returns a `StudyOutcome` and this crate, sitting above `vike-backtest` and already
owning the listing those runs appear in, is the only one that can be the caller —
`crates/vike-studio-core/src/study_run.rs`'s header works through why the write order has to be
what it is, down to what a half-written run would do to a listing. [Running a study](/docs/trader/research/running-a-study)
is that path end to end.

## Where it all lives on disk [#where-it-all-lives-on-disk]

Everything user-authored sits under `<project>/user_data/`, and
`crates/vike-model/src/state_path.rs` argues each directory. `RESEARCH_SUBDIR` files studies apart
from strategies because *a study is not a strategy*: a strategy is a thing that is mounted, takes
bars and emits orders; a study answers a question about data and produces a number, and nothing
about it belongs in a list of things that can be armed. `STUDIES_SUBDIR` splits into the same two
tiers a strategy has — the constants are `RHAI_SUBDIR` and `RUST_SUBDIR` themselves, not a second
pair — so a user who knows where their `.rhai` strategies go has learned where their `.rhai`
studies go.

`RUNS_SUBDIR` is deliberately at the `user_data/` root, not under `research/`: a research run and a
strategy backtest are *the same shape* — an id, a manifest naming the config, result files, a
report — and the workflow this serves runs research and then a strategy on the same idea, so
splitting them would file the two halves of one investigation in two places. Research owns the
questions; `runs/` owns every answer, of every kind. [Studies](/docs/trader/research/studies) covers
the listing that reads it back.

## The other pipeline in the crate [#the-other-pipeline-in-the-crate]

The same crate carries the Studio's **Run pipeline** — resolve a strategy, load a data slice from
the history store, backtest, score — parameterised by two vocabularies the header names:
`StrategySpec` (Rhai source *or* a native registry strategy plus params) and `DataSlice` (a venue,
a symbol list and a `SliceKind`, either `kind=bar` series or the recorded quote/trade/book tick
series replayed through `vike_backtest::hist_replay`). [The run pipeline](/docs/trader/research/the-run-pipeline)
is that half, and [Studio](/docs/trader/gui/studio) is the window over it. Where the strategies
themselves come from is `user_strategies` — `<project>/user_data/strategies/`, which replaced the
Studio's one-JSON-blob store — described under [User strategies](/docs/trader/scripting/user-strategies).

## What a shipped build compiles [#what-a-shipped-build-compiles]

The crate declares layer 55 (`crates/vike-studio-core/Cargo.toml`), and its default build is
DataFusion-free: `lib.rs` notes that the `vike-study` runner module is gated behind the `study-cli`
feature precisely because a CI lane greps the crate's default normal-dependency tree for a
datafusion crate and fails if it finds one — a structural check a compile-only test would pass. The
concrete store is something a binary builds and hands down; nothing in this tree opens one on its
own. [vike-study](/docs/trader/reference/binaries/vike-study) is the binary that turns the feature on.

## The rest of this section [#the-rest-of-this-section]

* [Studies](/docs/trader/research/studies) — what a study is, where the two tiers live, and how runs
  and studies are listed with every failure named.
* [Running a study](/docs/trader/research/running-a-study) — one entry point for both tiers, the order
  of operations, and what the manifest records.
* [Rhai studies](/docs/trader/research/rhai-studies) and [Rust studies](/docs/trader/research/rust-studies)
  — the two tiers and their contract.
* [The run pipeline](/docs/trader/research/the-run-pipeline) — the Studio's resolve → backtest → score.
* [Models](/docs/trader/research/models), [Training](/docs/trader/research/training),
  [Inference](/docs/trader/research/inference), [The fit cache](/docs/trader/research/fit-cache),
  [Feature importance](/docs/trader/research/feature-importance) and
  [Model pins](/docs/trader/research/model-pins) — the model crate, end to end.
* [Train a model](/docs/trader/tutorials/train-a-model) walks a fitting study from recipe to run.


# Inference (/docs/trader/research/inference)



`vike-ml` splits training from inference on purpose, and `crates/vike-ml/src/lib.rs`'s header
says why. Training drives the upstream LightGBM CLI binary as a child process, once, on the box
that trains ([Training](/docs/trader/research/training)). Inference is compiled into every binary that
runs a strategy — including a live daemon on a box that signs real orders — and shipping a C++
library there, to predict from a model that was already trained, is a cost with no benefit. So
`crates/vike-ml/src/infer.rs` is pure Rust: it parses LightGBM's `save_model` text output and walks
the trees, with no native dependency at all.

That split is only trustworthy if the two agree, and the header is explicit that it is gated
rather than asserted: `crates/vike-ml/tests/train_infer_equality.rs` runs LightGBM's own
`task=predict` over a trained model and compares it to the walker row by row, and
`crates/vike-ml/tests/real_model_golden.rs` freezes one such model and its outputs into the
repository so the comparison re-runs on every CI run, on a machine with no LightGBM binary.
[Model pins](/docs/trader/research/model-pins) covers what those gates prove that the version pins
cannot.

## The parser: strict on purpose [#the-parser-strict-on-purpose]

`crates/vike-ml/src/parse.rs` is the `version=v4` text-model parser and the inference path's only
file read: the trainer driver and the fit cache read files of their own, but nothing that predicts
does. It reads the text format rather than `dump_model`'s JSON because the text
is what `output_model=` writes and `input_model=` reads back — the CLI's own round trip, which the
C++ predictor treats as canonical. The header records the bakeoff proof: a model loaded from disk,
trained one more iteration and reserialised (100 → 101 trees) gave predictions at
`num_iteration_predict=100` byte-identical to the original's. Doubles are written with about 17
significant digits, so the file is a lossless round trip of the in-memory model.

The header's second section is titled "Strictness, on purpose", and every refusal in it exists
because the alternative is a plausible-looking number from the wrong arithmetic:

* an unknown `version=` is `MlError::UnsupportedVersion`, never a best-effort parse;
* a non-`binary` objective, a multiclass model (`num_class` or `num_tree_per_iteration` other than
  1. and a linear tree (`is_linear=1`) are `MlError::Unsupported`;
* `average_output` — the bare line `boosting=rf` writes — is refused by name, because this walker
  sums trees and an averaged model would be wrong by a factor of the iteration count;
* the `end of trees` terminator is required, because a file cut at a tree boundary is a byte-exact
  prefix of a real model in which every line is valid, and accepting it loads a shorter, silently
  under-boosted model;
* the header's `tree_sizes` count is cross-checked against the trees actually present when the
  line exists — the only check that catches a tree removed from the middle;
* `check_children` refuses a child index that leaves the arrays or points backwards, because the
  walk indexes those arrays unchecked per row and would otherwise panic or loop inside a live
  prediction.

`load_model_file` is the inference path's one I/O: it reads a path the caller named, searches
nowhere, reads no environment variable and has no default location — a library that guesses where
its model lives is a library its caller cannot deploy.

## What the model keeps [#what-the-model-keeps]

`crates/vike-ml/src/model.rs` is the parsed shape reduced to what inference reads. `split_gain`,
`leaf_weight`, `leaf_count`, `internal_value`, `internal_weight`, `internal_count` and
`feature_infos` are parsed past and dropped as training bookkeeping (the first of those is what
[Feature importance](/docs/trader/research/feature-importance) reconstructs in a separate pass). A
`Tree` is parallel arrays: `num_leaves - 1` entries per internal node and `num_leaves` leaf
values. A child entry `>= 0` indexes another internal node; a negative one encodes a leaf as its
one's complement, `leaf = !node`. The only `Objective` is `Binary { sigmoid }`, and the sigmoid
comes from the header's `objective=` line — not a per-tree field, and not always 1.0.

`shrinkage` is dropped too, and the module calls that one a trap rather than a tidy-up.

## The routing rules [#the-routing-rules]

`infer.rs`'s header states that every routing rule was read out of LightGBM's
`include/LightGBM/tree.h` rather than inferred, because each one fails silently: the walk
terminates whatever you do, at a different leaf, and the probability that comes out looks like a
probability.

`numerical_decision` is three rules in order. A `NaN` at a node whose `missing_type` is not `Nan`
is remapped to `0.0` and compared normally; a value that *is* the node's missing value goes to the
`default_left` side; otherwise `fval <= threshold` goes left — `<=`, not `<`. `missing_type` is
the two bits above the low two of `decision_type`, and `MissingType::Zero` uses LightGBM's
`kZeroThreshold`, pinned in `model.rs` as `ZERO_THRESHOLD = 1e-35f32 as f64` because upstream's
literal is a float widened to double.

`categorical_decision` is a different function, and its doc calls it the place a hand-written
walker is most likely to diverge in production. It never consults `default_left` or
`missing_type`: a `NaN` or a negative category goes right unconditionally. The category id is
`fval as i32` — truncation toward zero, not rounding — the node's `threshold` is an index into
`cat_boundaries`, not a value, and membership is a bit test in a packed 32-categories-per-word
bitset where a word past the group's end is implicitly zero.

`leaf_value_for` returns `leaf_value[!node]`; a constant tree (empty split arrays) returns its only
leaf without walking.

## The score, and the three things it refuses to do [#the-score-and-the-three-things-it-refuses-to-do]

`GbdtModel::raw_score` is the plain sum of every tree's selected leaf value, and its doc lists what
it deliberately does not do. It does not multiply by `shrinkage`: LightGBM scales `leaf_value` by
the learning rate in place at training time, so applying it again scales every score by the
learning rate squared. It does not add a base score: `boost_from_average`'s init score is folded
into the first tree (`AddBias`), so summing every tree in file order is both necessary and
sufficient. And it does not use a compensated sum — `vike_model::py_sum` is more accurate, which is
exactly why it is wrong here: the equality gate's `the_raw_scores_match_bit_for_bit` compares this
function against LightGBM's own `predict_raw_score=true` output bit for bit.

`predict_proba` is `1 / (1 + exp(-sigmoid * raw))`, and its `exp` is `libm::exp`, not `f64::exp`.
The doc calls that the one place a probability out of this crate could differ between two boxes:
IEEE 754 requires nothing of `exp`, so a method call reaches whichever libm the platform ships,
and the two gates over this function each budget `1e-12` for one `exp` through two libms.

<Callout type="warn" title="The single-row API is unchecked; the batch API is not">
  `raw_score` and `predict_proba` validate nothing in release — they are the per-tick live path — and
  `Tree::feature_value` substitutes `NaN` for an entry the row does not carry, which diverges from
  LightGBM's own `0.0` fill at a `missing_type == Nan` node. A `debug_assert!` on the row width
  catches drift in test and debug builds; `predict_proba_batch` (and its pre-transform twin
  `raw_scores_batch`) is the checked entry point, refusing with `MlError::Shape` a width the model
  cannot use or a buffer that is not a whole number of rows.
</Callout>

Where the probabilities go once a study has them is [Models](/docs/trader/research/models); the
tutorial that fits one end to end is [Train a model](/docs/trader/tutorials/train-a-model).


# Model pins (/docs/trader/research/model-pins)



`crates/vike-ml/src/pins.rs` holds two constants, and its header says they live together in their
own file because the version refusal has to name both and a bump has to change both in one place:

* `MODEL_VERSION = "v4"` — the model text format's own `version=` line, asserted rather than
  sniffed. `parse_model_text` refuses any other value with `MlError::UnsupportedVersion`.
* `PINNED_LIGHTGBM_TAG = "v4.7.0"` — the upstream release the trainer binary is built from,
  asserted at startup by `crates/vike-ml/src/cli.rs`'s `LightGbmCli::new`. The doc records that
  upstream moved from `microsoft/LightGBM` to `lightgbm-org/LightGBM` in 4.7.0, and that `v4.7.0`
  is tag sha `8f7036f0`, released 2026-07-18.

`crates/vike-ml/src/error.rs` makes the refusal actionable on purpose: the `UnsupportedVersion`
message names the version it saw, the version the walker implements, the pinned tag and the bump
procedure, and its doc says a refusal an operator cannot act on is a refusal the next person
widens.

## What each pin proves, and what neither does [#what-each-pin-proves-and-what-neither-does]

The header states the residual first because it is what a reader otherwise assumes away.
`MODEL_VERSION&#x60; is a coarse instrument: &#x2A;*`v4` does not change when fields are added within v4.**
The parser tolerates unknown `key=value` lines silently — it must, since LightGBM already writes
several the walker has no use for — so a new per-node array carrying routing meaning would be read
as noise, dropped, and every prediction would be quietly wrong while the version check stayed
green.

`PINNED_LIGHTGBM_TAG` catches "somebody put a different LightGBM on the box", which the doc calls
a real and common failure — and says nothing about whether the format changed.

So the real bump proof is neither constant. It is `crates/vike-ml/tests/train_infer_equality.rs`,
which trains a real model with the pinned binary, runs LightGBM's own `task=predict` over it,
parses the same text with the pure-Rust [walker](/docs/trader/research/inference) and compares every
row; its header calls the version check only a tripwire in front of it. Its eval rows deliberately
include the cases a hand-written walker gets wrong — a NaN in a numerical column, a NaN in the
categorical column, a negative category, a category the model never saw.
`crates/vike-ml/tests/real_model_golden.rs` freezes one such model and its outputs into the
repository so the walker is checked in the default lane, on every CI run, with no binary
installed; its provenance test compares the fixture's recorded producer against the pin, which it
calls the cheapest possible guard against the most expensive possible mistake.

<Callout type="warn" title="The trainer cannot name itself, so a file names it">
  `cli.rs`'s header records that upstream LightGBM has no version flag — `--version` produces an
  unknown-parameter warning, "No training/prediction data, application quit", and a non-zero exit.
  `LightGbmCli::new` therefore reads the `tag=` line of the `PROVENANCE` file the build recipe
  writes beside the binary (`provenance_version`). A binary with no `PROVENANCE` — the ordinary
  state of one built by hand — is an `MlError::Trainer` naming the binary's path, the missing
  file's path and the recipe, never a panic. The header states the weakness plainly: the check
  catches exactly a missing file or a different recorded tag. It does not catch a different *build*
  of the pinned tag — nothing in the crate hashes the binary, and the recipe's `sha256=` line is
  provenance for an auditor, not a comparison — which is why `crates/vike-ml/src/grid.rs`'s
  `check_grid_params` refuses `num_threads != 1` at the point the fits happen rather than trusting
  this.
</Callout>

`MlError::Trainer` is deliberately distinct from `MlError::Backend`: the first says *the thing I
was told to drive is not the thing I expect*, an operator fault with an operator fix; the second
says LightGBM ran and refused, a data or parameter fault. The `Trainer` message also says the other
half still works — inference needs no binary at all.

## Bumping the pin [#bumping-the-pin]

The procedure is spelled where an operator meets it — `crates/vike-ml/src/error.rs`'s
`UnsupportedVersion` message and `crates/vike-ml/src/cli.rs`'s `refuse_version` both name the
steps. Move `PINNED_LIGHTGBM_TAG` and the build recipe's tag together; rebuild
(`just lightgbm-build`, which refuses a moved tag with no matching commit
recorded); run the equality gate and read its log rather than its exit code — the gate trains at
`verbosity=1` so LightGBM's unknown-parameter warnings are visible, and they arrive on stdout,
which is why `run_config` returns captured stdout; regenerate the golden fixtures with
`capture_the_golden_fixture`; run the default lane on a box with no binary so the fixture's
provenance test fails if fixture and pin disagree. A changed golden number is a finding, not a
chore. The `lightgbm` CI job runs the binary-driven suites through a script that refuses a suite
executing zero tests, because a skipped test passes and `0 passed` is the shape of a green job that
proved nothing.

Telling a benign bump from a format change, cheapest first: the
`version=` line (moved off `MODEL_VERSION` means a parser project, not a bump); the presence and
shape of `cat_boundaries=` / `cat_threshold=` in a model trained with a categorical column; and a
diff of the header key set between old and new fixture — the only cheap signal that something was
added, the case the version check cannot see.

| skew                                                   | detected by                                                                                |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| a new per-node routing array inside `v4`               | the equality gate only                                                                     |
| a renamed or deprecated training parameter             | the gate's `verbosity=1` stdout only                                                       |
| a binary from a different tag, or with no `PROVENANCE` | `LightGbmCli::new`'s `tag=` read — and only those two                                      |
| a truncated or doctored model file                     | `parse_model_text`'s `end of trees` requirement and `tree_sizes` cross-check, at load time |
| a fixture captured from the wrong release              | `real_model_golden.rs`'s provenance test                                                   |
| a `CategoryMap` paired with the wrong model            | the map's header — and only if the caller checks it                                        |

## The third file: the category map [#the-third-file-the-category-map]

`crates/vike-ml/src/categories.rs` is the stable string-to-integer table for a categorical
feature, and its header explains why it must exist: the data file `TrainData::write_csv` hands
LightGBM carries numbers, so a category was already an integer before the trainer saw it, and the
saved model has no record of what that integer meant — a CLI-trained model's `pandas_categorical:`
trailer is `null`. The caller keeps the mapping, in this shape: ids assigned from 0 in declaration
order, one label per line, saved beside the model artifact.

Two properties the walker depends on. Ids are never negative, because a negative category is
LightGBM's "missing" and routes right unconditionally. And an unknown label encodes as `NaN`
(`CategoryMap::encode`), not a fallback id — `NaN` is exactly what a categorical node treats as
missing, the honest answer for a category the model never saw; mapping it onto an existing id
would predict as if it were a different category, and nothing would say so.

<Callout type="warn" title="A wire format with no version">
  The header's own warning: the map and the model are two separate files with nothing linking them,
  and pairing the wrong two is silent and total — every category means a different thing, every
  prediction is wrong, and no error fires anywhere. That is a worse failure than the model file's
  `version=` skew, and it has no marker at all. The minimum defence is `CategoryMap::to_text`'s
  caller-supplied name, written as a `# vike-ml category map for:` header line (`HEADER_PREFIX`) so
  a serving path can refuse a mismatch through `model_name_of`; `from_text` ignores the header, so
  an unlabelled legacy file still loads. Write the two files together, name them together, move
  them together.
</Callout>

`from_labels` refuses what would corrupt the mapping on reload: a duplicate label, a label
containing a newline, one starting with `#` (read back as a comment), and an empty or
whitespace-padded one (`from_text` trims and drops blank lines, so it would vanish and shift every
later id). The order *is* the mapping — a reordered file is a different map. `to_text` and
`from_text` are pure; where the file lives is the caller's decision.


# Models (/docs/trader/research/models)



`crates/vike-ml/src/learner.rs` is the learner seam: fit a model, read one probability per row.
Two traits, and the header says they are the crate's only ones. `Learner` takes a `TrainData`, a
`GridPoint` and a seed and hands back a `ProbaModel`; `ProbaModel` turns one feature row into one
probability. Everything a real implementation needs beyond that — a driven child process, a scratch
directory, a parameter bag, a binned-dataset cache — is behind the trait, and every caller that
only wants "fit, then predict" is written against these two methods.

The seam was written in the one study that first needed a model, as that study's own view of a
learner; that reason expired when the crate pinned its format and its binary, leaving a general
abstraction reachable by nothing else. What it buys is **substitution**: code that fits models can
be tested on a machine with no LightGBM binary — every Windows box and every CI runner — against
`crates/vike-ml/src/test_support.rs`'s `ScriptedLearner`, which answers a scripted probability,
counts its fits and can be told to fail. That double deliberately answers no `fit_identity` and no
model text, because a double that answers `Some` is a double that can be wrong, and a fabricated
identity or text would let every consumer's refusal pass vacuously.

## What the seam promises [#what-the-seam-promises]

`Learner::fit` returns `Result<_, String>` rather than the crate's error enum on purpose: a caller
scoring a grid must treat one rejected point as an ordinary event and keep the other candidates
competing, and the whole value of a rejection is its sentence — `MlError::Backend` already carries
the trainer's stderr tail. Both traits carry `Sync` because a grid search fits and predicts from
several threads at once.

`fit_identity` is the key half of a cross-run fit cache: a content digest of *everything* a fit
would consume, defaulting to `None`. Two calls may share an identity only when their fits are
bit-identical by construction, because a wrong hit silently corrupts results — so `None` means
"cannot prove it", and a cache must then never serve or store for that learner, which is the safe
direction. An implementation digests the actual bytes (rendered configs, the data as the trainer
reads it, the binary's provenance), never a description such as a path or a fold id.
[The fit cache](/docs/trader/research/fit-cache) is the consumer.

`fit_captured` is `fit` plus whatever `Capture` asks be kept: the fitted model's per-feature
importance, its own serialised text, or both. It is one method with a request parameter rather
than a second name because a caller asking for both would otherwise pay the fit twice — identical
trees, twice the wall clock — on the fit nothing caches. The flags are answered independently, so
a text-only request cannot be failed by an importance parse it never wanted. The default answers
`None` to every artifact, and the asymmetry between the absences belongs to the caller: an empty
importance table positively misinforms ("no feature mattered"), so a caller should refuse rather
than write one, while an absent model text costs only the export.

<Callout type="warn" title="Capture::text is the trainer's own bytes">
  The text a learner hands back is its own serialised output, never a re-serialisation of the parsed
  model: this crate parses LightGBM's `save_model` text and deliberately has no writer, since a
  writer would be a second spelling of the format to keep in step with the trainer's.
</Callout>

`ProbaModel` for `GbdtModel` is a one-line delegation to the walker —
`1 / (1 + exp(-sigmoid * raw))` for `objective=binary` — and its tests pin that the impl does not
sanitise: a `NaN` raw score reaches the caller as a `NaN` probability that a ranking caller scores
worst (clamping to `0.5` would let a failed fit rank like a mediocre model and win), while an
infinite raw score saturates to exactly `1` or `0`. [Inference](/docs/trader/research/inference) is the
walker.

## The point a search moves [#the-point-a-search-moves]

`crates/vike-ml/src/search.rs`'s `GridPoint` is the five searched axes as one `Copy`,
const-constructible struct — `num_leaves`, `max_depth`, `min_data_in_leaf`, `learning_rate`,
`feature_fraction` — with the non-searched parameters deliberately absent, because a base copy of a
searched axis is dead state whose only effect would be to give a dropped mapping a plausible value
to fail silently with. `ParamPoint` is the free-form name/value bag, and `GbdtParams::apply`
refuses a name no parameter matches, so a swept knob that was never connected is an error rather
than a winner that means nothing. `DEFAULT_POINT` (`15 / 4 / 20 / 0.05 / 0.7`) is the fallback for
a search with no winner, and its doc says it is not a recommendation.

## The one real learner [#the-one-real-learner]

`crates/vike-ml/src/gbdt_learner.rs` opens with its claim: **the one `Learner` that drives a real
trainer**; everything else implementing the seam is a double. It was a study's own adapter,
promoted under two conditions visible in `GbdtLearner::new(binary, scratch, base)`: the base
parameter bag is a constructor parameter, so no caller's regularisation is compiled into the
library (`GbdtParams::default` is LightGBM's own defaults), and the bin cache's capacity is a fixed
`DEFAULT_BIN_CAPACITY` of 64 with `with_bin_capacity` as the override rather than a function of a
thread pool, so promotion added no dependency. Capacity is a performance knob only — an evicted
entry is re-binned, so no value of it can change a model.

The header answers four questions: the non-searched parameters live in the caller's base bag,
applied by `params_for`, and a base must not restate a searched axis; a categorical column is
declared as a comma-separated string of feature indices, refused before anything spawns if one is
out of range; `fit` and the model are `Sync`, and each fit gets its own scratch directory because
two concurrent fits sharing one config path would train each other's parameters; the error is a
`String`. Two divergences from the original oracle are stated up front: `num_threads = 1`, because
the pinned binary is built without OpenMP and thread count changes the float reduction order, so
fits are parallel across processes rather than inside one; and a full 243-point grid rather than 20
sampled trials, which belongs to the caller's search — this file fits one point.

`fit` checks the shape, finalises the parameters, takes a pre-binned dataset from the fold-keyed
`BinCache` — keyed on the data's content plus the two inputs binning bakes, `min_data_in_leaf` (the
one searched axis consumed at dataset construction) and the categorical declaration, with a
`OnceLock` per key so concurrent first fits bin once — trains into a private directory, parses the
model text, and removes the directory on both outcomes. A fold's 20 search trials therefore write
and parse the \~8 MB training CSV at most three times instead of
twenty, and the models are bit-identical to per-fit CSV construction, proven by a matrix smoke
against the real binary. Its `fit_identity` enumerates every input — the CSV bytes as streamed, the
two rendered configs with path lines normalised, the trainer's `PROVENANCE` digest, the model
text-format version — under a tag frozen at `vike-research fit-identity v1`, a cache key rather
than a citation.

The handover is gated rather than trusted: a crate-private `Trainer` seam lets a recording double
assert the trainer is handed the parameters the fit just built, because substituting the default
bag used to leave every unit test green while every grid point trained identically and the search
still named a winner. What no in-process test can gate — that LightGBM honours what it is handed —
is the equality gate's job, in [Model pins](/docs/trader/research/model-pins).
[Training](/docs/trader/research/training) is the process underneath, and a
[study](/docs/trader/research/studies) is what moves the point — the crate enumerates no grid of its
own, so a caller walks its own five-axis space.


# Rhai studies (/docs/trader/research/rhai-studies)



A Rhai study is the half of the study contract a shipped binary can run.
`crates/vike-studio-core/src/rhai_study/mod.rs` gives the layout and the whole contract:

```text
<project>/user_data/research/studies/rhai/<name>/
├─ <name>.rhai      entry file — stem MUST equal the folder name
└─ *.toml           recipes, loaded by the caller, not by this runner
```

```rust
fn run(ctx, params) {
    let bars = ctx.bars("binance", "BTCUSDT", "1h");
    let out = outcome();
    out.metric("n_bars", bars.len());
    return out;
}
```

That is `StudyFn` with the types erased — the same two arguments, the same return value, the same
three failure kinds as the [Rust tier](/docs/trader/research/rust-studies), so an author porting between
tiers moves a body, not a contract. A script with no `fn run(ctx, params)` is refused at compile
time naming the contract, because a file with the wrong entry is not an empty study but one nothing
will ever call. The extension is compared case-insensitively; the stem exactly.

`RhaiStudy::new` runs the script's top level **once** — `run` is then called with
`eval_ast(false)` on a fresh clone of that scope, so a top-level `const` stays visible while a
run's locals live exactly as long as the call. A `run` that returns anything but an outcome is
refused with the fix in the message. The recipe arrives as a Rhai map (`params.seed` and
`params["seed"]` both work); a TOML datetime becomes its own string, because Rhai has no date type.

## In this tier, the surface is the enforcement [#in-this-tier-the-surface-is-the-enforcement]

The header's one thing worth carrying away: the Rust tier's read-only guarantee is a sanctioned
surface, not enforcement, because a `.rs` file is ordinary Rust. Here the same rule *is*
enforcement. A script can only call what `crates/vike-studio-core/src/rhai_study/bind.rs`
registers — no `use`, no manifest, no FFI — and Rhai's standard packages carry no filesystem or
network surface, so the registration list is the complete set of things a study can reach,
reviewable in one file.

<Callout type="warn" title="The default rhai::Engine is not the safe object">
  `bind.rs`'s `build_engine` installs a `DummyModuleResolver`, and its doc calls that the
  load-bearing line: a default engine's `FileModuleResolver` makes `import "…" as m;` read a file
  from disk — a capability no allow-list would show, reachable without registering anything. Every
  `import` is now a refusal, and `a_study_cannot_import_a_module_because_that_would_be_a_file_verb`
  is the gate. One residual is declared: rhai's `time` package registers `timestamp()`, so a study
  can read a wall clock and be non-reproducible; it reaches no data and no network.
</Callout>

Two names are deliberately not used, because `register_fn` *replaces* an existing registration:
`range` is rhai's own counted-loop constructor, so the time-range constructors are
`ts_range(start, end)` and `ts_range_all()`; and `print`/`debug` are redirected to `tracing`
under the `vike_study` target, never stdout, because a root whose stdout is a protocol
(`vike-cli mcp`) would be corrupted by a script's `print`.

## The three families of host function [#the-three-families-of-host-function]

**`ctx.*` reads.** `ctx.window()`, `ctx.can_fit()`, and one method per store verb — `bars(venue,
symbol, interval)`, `quotes`, `trades`, `book_updates` and `depth` (each `(venue, symbol)`), every
one also accepting a trailing `TsRange`. The short arity uses the run's own window, which is what
stops a study from writing its own window out of `params` and quietly measuring a different range
than the run it is filed under. `ctx.scratch()` is absent on purpose: there is no file verb in
this tier, so a scratch path would be a string no other verb accepts.

**The row types.** `Bar`, `QuoteTick`, `TradeTick` and `BookUpdate` carry property getters
(`b.close`), and `column(rows, "field")` is how a real scan reads: a Rhai loop over a hundred
thousand rows spends interpreter operations per field access, while one host call is a `Vec` walk
in Rust. It projects each type's scalar fields — a book event's `bids`/`asks` are level lists,
reached through the getter as arrays of `#{ price, size }`. An unknown field and a mixed array are
loud refusals, since each would otherwise project a silently wrong column; an absent optional
reads as `NaN`, never `0.0`; a `u64` such as `seq` saturates rather than wrapping into a plausible
small number.

**The outcome.** `outcome()` constructs one; `out.metric(name, value)` takes an integer or a float
(a version that accepted `3.0` and rejected `3` shipped once in the strategy engine);
`out.artifact(name, text)` refuses a non-string body rather than writing a one-character file.
Both raise a runtime error on refusal, so a duplicate metric stops the study instead of being
dropped by a script that never checks a return.

## Fitting from a script [#fitting-from-a-script]

`ctx.fit(x, y, n_cols, params)` takes two flat arrays and a map — `TrainData` is borrowed and
`GridPoint` is a five-field struct, so neither is constructible from a script — and hands back an
opaque `StudyFit`. `FIT_PARAM_KEYS` is the whole accepted map: the five searched axes
`num_leaves`, `max_depth`, `min_data_in_leaf`, `learning_rate`, `feature_fraction` (defaulting to
`DEFAULT_POINT`), `seed`, and the flags `capture_importance` and `capture_text`. An unknown key is
refused by name, because a silently ignored `learning_Rate` is a knob the author believes is armed
and is not. Without a learner the call raises the typed `StudyError::NoLearner`; `ctx.can_fit()`
asks first.

`fit.predict(row)` scores one row; `fit.text()` and `fit.importance()` (an array of
`#{ feature, gain, splits }`) answer the two artifacts, with `has_text()`/`has_importance()` to
ask. Both accessors raise when the learner reported nothing rather than returning an empty value —
an empty importance table would read as "no feature mattered". The artifacts ride along with the
fit because `Learner::fit_captured`'s contract is one fit however many are asked for
([Models](/docs/trader/research/models)). `fit_identity` is absent: a study does not own the cross-run
cache its caller keys, so a digest here would be a surface with no consumer.

## Limits [#limits]

`MAX_OPERATIONS` is `1_000_000_000` per `run` — roughly 500× the strategy engine's ceiling, and
the difference is the unit of work: a strategy hook must finish inside a bar, while a study is
called once for a whole window and a plain loop over a hundred thousand bars is the most ordinary
thing it does. `MAX_CALL_LEVELS` is `64`, as in the strategy tier, since a runaway recursion is a
stack overflow no operation counter catches in time. Size limits are unset: the big arrays a study
holds are the ones the host handed it.

## How a typed error survives the interpreter [#how-a-typed-error-survives-the-interpreter]

`crates/vike-studio-core/src/rhai_study/fault.rs` states the problem exactly. `StudyError`'s
three variants split by who an operator has to talk to, and two carry evidence a caller acts on
mechanically: `Data` carries `vike_data::DataError` itself, and `NoLearner` is the failure a UI
renders as a host ceiling. A Rhai host function can only fail as a `Box<EvalAltResult>`, and the
obvious implementation — raise `e.to_string()`, rebuild a `Study(msg)` on the way out — would
flatten both typed variants into a sentence for every study in this tier. The value cannot ride
inside the Rhai error either: a `Dynamic` requires `Clone + Send + Sync`, and `DataError` derives
`Debug` alone.

So the fix is a side channel, and it is a *log* rather than a slot. Every `raise` appends the typed
error to the run's `FaultLog` and embeds its index in the rendered message as
`[vike-study-fault:N]`; `recover` reads the **last** sentinel and returns that entry. A single
slot was the first shape and is wrong because Rhai has `try`/`catch`: a study that catches a store
fault and then fails for an unrelated reason would report the caught fault as its cause. A message
with no sentinel — a typo, a division by zero, the operation ceiling — comes back as
`Study(rendered)`, and a forged or out-of-range marker degrades to the message. A store failure
raised through the interpreter therefore reaches the [runner](/docs/trader/research/running-a-study)
as `StudyError::Data`, exactly as it would from a Rust study.

With no `user_data/` the tier is inert structurally — nothing is registered until a caller names
a folder — and `RhaiStudy::load` on an absent folder is a named refusal.
[Scripting](/docs/trader/scripting) covers the strategy engine this tier is the twin of.


# Running a study (/docs/trader/research/running-a-study)



A surface — the Studio's Research pane, the `vike-study` binary, any headless caller — holds a
`ListedStudy`: a name, a folder and a tier. `crates/vike-studio-core/src/study_dispatch.rs`
exists because until it did nothing joined that row to a run: `run_study` takes a name and
resolves it through the compiled registry, `RhaiStudy::load` takes a folder, and neither is
reachable from "the row the user clicked" without a `match` on the tier — which, written at every
call site, is a second copy of a rule that should have one. So there is one entry point,
`run_study_plan`, whose whole job is that `match`, and whose two arms converge on the same
persistence: a run produced by an interpreted study and one produced by a compiled study are
indistinguishable on disk.

## The plan [#the-plan]

`StudyRunPlan` has public fields and no constructor, so a field added later stops every caller
until it decides what to put there. It carries the study's `name`, its `dir` (read by the
interpreted tier only; the compiled tier resolves through a registry and never opens it), the
`tier`, the parsed recipe `params` (`empty_params` is "no configuration"), a `RunConfig` naming
which recipe drove the run as the operator spelled it, the `store` the binary built, the `window`,
a `scratch` directory, the `runs_root`, the `produced_by` binary and its `git_sha` if it can name
one, and the `learner`.

The learner is `Option`, and the doc calls that *a change of ceiling rather than of plumbing*. It
used to be hardcoded `None` because the only host was the Studio, whose ML surface is inference
only; a host that can fit now exists, so the field arrived and every caller was made to decide.
`None` remains a working state — a run made with no learner is a different experiment, not a worse
one, and the manifest records which — while a study that must fit answers `StudyError::NoLearner`,
a typed variant a UI can render as a host ceiling. `spawn_study` runs the plan on a worker thread
through the same `spawn_outcome` every Studio run uses; `run_study_plan` keeps the clock as a
parameter so a test can mint against a fixed instant.

## The two arms [#the-two-arms]

**Rust.** `run_study` resolves the name through `vike-user-research`'s generated registry. In a
checkout with no `user_data/` — every CI runner, every fresh clone — that registry is empty by
construction and every name answers `StudyRunError::UnknownStudy` naming the whole (empty) roster;
the message says a compiled study is scanned at build time, so one added since the binary was
compiled is not in it. `study_run.rs` calls that a working state, not a degenerate one.

**Rhai.** `RhaiStudy::load` compiles the folder's entry file at run time — a folder with no entry
file is the study's own refusal — and reaches the same persistence through a bridge the module
reports as a finding: `run_study_with` takes a bare `fn` pointer and an interpreted study is a
value, so the study is parked in a thread-local for one synchronous call and a plain `fn` item reads
it back. It is safe (an `Arc`, never a pointer; the workspace forbids `unsafe`), one call deep, and
disarmed through a `Drop` guard so a panicking study cannot leave the slot armed for the next. The
doc names the real fix — `run_study_with` taking `&dyn Fn` — and why it was not made in the same
change: widening a contract to fit its first caller is how contracts get bent.

## The order of operations [#the-order-of-operations]

`crates/vike-studio-core/src/study_run.rs` lists the sequence and what each ordering buys:

1. read the clock — the run's start second;
2. create the scratch directory, so a study's first write does not fail on a missing parent;
3. build the `StudyContext` and call the study;
4. read the clock again — before anything is written, so the pair measures the study, not the disk;
5. validate the artifact names, before anything is on disk;
6. mint the run directory (`create_run_dir`, whose atomic `create_dir` *is* the id mint);
7. write the artifacts, then the report, then the manifest last.

The study runs **before** the directory is minted, so a study that refuses leaves no empty run
directory for a listing to report as unfinished. The artifacts precede the manifest because
`runs.rs` writes the manifest last precisely so a directory holding one is a run that finished
writing. And a persistence failure never costs the numbers: `StudyRunError::NotPersisted` hands the
`StudyOutcome` back beside the reason, carrying `runs.rs`'s rule — *saving a run is worth doing;
it is not worth losing a run over* — in a type. `StudyPersistError::ReservedArtifact` is the writer
refusing an artifact named after the manifest or the report; the study crate cannot name those
constants, so the check belongs here.

## How a study run is told apart from a backtest run [#how-a-study-run-is-told-apart-from-a-backtest-run]

A study's Sharpe is vectorised — hysteresis, min-hold, slippage, no order book, no queue position,
no fee schedule — and a backtest's is event-driven with real fills. Showing both in one `runs/`
list is what makes the gap visible rather than assumed, so the surface must not let them merge:

* **`STUDY_RUN_KIND`** is the manifest's `kind`, a bare `"study"` rather than `"study-rust"`,
  because the tier is a property of where the source lives and the tiers *differ only in reach*.
* **The metrics nest under `detail.metrics`**, never hoisted beside the common fields. A top-level
  `sharpe` would be renderable in a shared column by a listing that never asked which scorer
  produced it; nested, a reader must branch on `kind` to reach the number at all.
  `STUDY_METRICS_NOTE` rides in the same subtree, because a manifest is also read alone.

<Callout type="warn" title="Non-finite metrics are recorded, and JSON nearly lost them">
  `StudyOutcome::metric` accepts a non-finite value deliberately — a `NaN` Sharpe over a fold that
  never traded is an observation. But `serde_json` writes a non-finite `f64` as `null`, silently, so
  three distinct observations and an absent value would reach disk as one token. Every metric is
  therefore written as an object carrying `value` and `nonfinite`, in `metric_json`; and the metrics
  are an array, because the workspace pins `serde_json` without `preserve_order` and an object would
  sort the study's emission order away.
</Callout>

## The hosts [#the-hosts]

**`vike-study`** (`crates/vike-studio-core/src/study_cli.rs`, behind the `study-cli` feature and
also a tool of the `vike` multicall dispatcher) is the runner that can *fit*: its header records
that until it existed nothing in the workspace could fit a compiled study, because the Studio
supplies no learner. It takes `--study`, `--recipe`, `--from`/`--to`, `--store`, and optionally
`--lightgbm` — omitted, the study runs with no learner and a fitting study refuses by name. The
recipe's optional `[learner]` table carries the study's LightGBM base parameters, because those
are a property of the study rather than of the learner; an absent table means LightGBM's own
defaults, and the run prints which it used. [vike-study](/docs/trader/reference/binaries/vike-study)
has every flag. **The Studio's** [Research pane](/docs/trader/gui/studio/research-pane) is one picker
for both tiers with the tier as a badge, dispatching through `spawn_study` with no learner.

The store is a parameter of both hosts, and `study_run.rs` says why the library constructs none:
a default build of the crate is DataFusion-free, gated by the `studio-standalone` lane, so the
request carries a `StoreHandle` the binary built. [Studies](/docs/trader/research/studies) is where the
runs land; [Train a model](/docs/trader/tutorials/train-a-model) runs one end to end.


# Rust studies (/docs/trader/research/rust-studies)



`vike-user-research` is the compiled user-study host. `crates/vike-user-research/src/lib.rs`
states the mechanism in one sentence: `build.rs` scans
`<workspace>/user_data/research/studies/rust/<name>/<name>.rs` (`VIKE_USER_DATA_DIR` overrides
the root at build time) and generates the registry the crate re-exports — `USER_STUDIES`,
`user_study_entry` and `run_user_study` — copied from the strategy tier's `vike-user-strategies`
rather than reinvented. A study folder holds the entry file, whose stem must equal the folder name,
plus `*.toml` recipes the caller loads. The interpreted twin is
[Rhai studies](/docs/trader/research/rhai-studies).

## The entry contract [#the-entry-contract]

```rust
use vike_user_research::{StudyContext, StudyError, StudyOutcome};

pub fn run(ctx: &StudyContext, params: &toml::Value) -> Result<StudyOutcome, StudyError>
```

`crates/vike-user-research/src/contract.rs`'s `StudyFn` is that signature as a type, and the
generated registry coerces every entry to it (`user_<name>::run as StudyFn`), so a file whose
signature drifts fails the *build* naming the mismatch rather than failing at the call site of a
study somebody is waiting on. It is a function, not a trait — the design refused a `Study` trait as
*wrong tool for one implementation; extract it from two* — and non-generic on purpose, the one
place the contract diverges from the strategy tier's `build<B: HftBroker>`: a Rhai script cannot
carry a type parameter, and a study places no orders, so nothing about it is generic over a broker.

The load-bearing property of a separate crate is compilation: user entry files compile as modules
of *this* crate, a separate unit from `vike-ml` or `vike-analytics`, so they resolve only the
platform's public API. An internals refactor can never break a study, and a study can never grow a
load-bearing dependency on a `pub(crate)` detail. The contract types live here while there is one
study, and `extern crate self as vike_user_research;` lets a user file spell them as
`vike_user_research::…` regardless of where they eventually move.

## What the scan accepts [#what-the-scan-accepts]

`crates/vike-user-research/src/codegen.rs` is the pure scan, `include!`d by `build.rs` so the unit
tests exercise exactly the code the build runs. A folder holding `.rs` files but no `<name>.rs` is
an **error** — the operator's file is right there and nothing will ever compile it — while a folder
with no `.rs` at all is a recipes-only folder, skipped silently. The name must match
`[a-z][a-z0-9_]*`, because it becomes the registry name and the generated module name. A name
present in both tiers is a **warning**, since the interpreted tier is the one a binary install can
run and refusing to build the compiled twin would take away the resolution the operator still has.
There is no `study.toml` and no `live` flag: a study places no orders and its sanctioned surface
reaches no network, so a flag would gate nothing. `build.rs` fails the build outright on any scan
error, because an operator who dropped a malformed folder must hear about it at compile time, not
when a run reports "unknown study"; its scan root is a fixed hop from the crate's manifest
directory, deliberately not the runtime marker walk, because a build script runs in a source
checkout by construction.

## What a study is handed [#what-a-study-is-handed]

`StudyContext` is built by the caller — a binary, the only layer allowed to read the environment —
and never by a study. It carries the store, an optional learner, the run's `window` and a `scratch`
directory the caller owns and may delete afterwards. Its read verbs forward the store's read half
and nothing else: `bars`, `quotes`, `trades`, `book_updates`, `depth` (a store with no depth lane
refuses rather than answering empty), and the research series `cohort` and `perp_metrics`, each
named by stripping the store method's `scan_`/`load_` prefix. The append half is unreachable by
construction: the crate takes `vike-data` feature-free, so the concrete store engine is not
compiled and a study holds no value it could append through.

<Callout type="warn" title="Sanctioned surface, not a guarantee">
  `contract.rs` says it of itself: the read-only property belongs to the sanctioned surface. A user
  file is ordinary Rust compiled into the operator's own binary, and nothing stops it opening a
  socket. What the contract buys is that the cheapest path is the correct one, and that an
  unsanctioned path has to be added to a manifest, in a diff. The Rhai tier is where the same rule is
  actually enforced.
</Callout>

`StudyOutcome` is what comes back: metrics in emission order (a study puts its headline first),
duplicates refused, non-finite values accepted because a `NaN` Sharpe over a fold that never
traded is an observation; and text artifacts whose name becomes a file name in the run directory —
non-empty, at most `MAX_ARTIFACT_NAME` (64) bytes, `[A-Za-z0-9._-]` only, not starting with `.`,
so `../../secrets.env` is refused by the charset rather than defended against by the writer.
`StudyError` has three variants split by who an operator has to talk to: `Study` is the author's,
`Data` carries `vike_data::DataError` itself (a `From` impl lets a body `?` a store read through),
and `NoLearner` is the host's — the documented ceiling of a box with no LightGBM binary.

`StudyLearner` is `vike_ml::Learner` with its model type erased so it can cross a non-generic
boundary, and it erases the whole trait — `fit`, `fit_captured`, `fit_identity` — because a
two-method version would have silently removed two shipped capabilities: exporting the model a run
selected, and keying a cross-run fit cache. [Models](/docs/trader/research/models) is the seam.

## The dependency table is the API [#the-dependency-table-is-the-api]

`Cargo.toml`'s `[dependencies]` is the user-study API surface — a user file resolves
`use vike_ml::…` against that manifest — and the header argues the absences, because nothing else
would record them. Present: `vike-model`; `vike-indicators` (the `ColumnFeature` study↔strategy
seam); `vike-ml` (the learner seam, pure-Rust inference, importance); `vike-analytics` (the signal
backtest, stats, the purged fold splitters); `vike-data` (the trait only); `toml`; and three that
arrived together for one named consumer — `indexmap` and `rand_chacha` as correctness, since an
insertion-ordered map and a portable RNG stream are bit-reproducibility machinery in this
workspace's convention, and `rayon` as speed. Absent on purpose: **no HTTP client**, because a
study reads the history store and the exploratory fetch is an ingest command — a throttled runtime
fetch does not fail a study, it becomes a number that flows into a feature and a Sharpe; &#x2A;*no
`vike-backfill`**, where the vendor clients live; &#x2A;*no `vike-backtest`**, illegal by layer and
wrong by kind, because a research Sharpe and an event-driven one must never quietly become one
number; &#x2A;*no `vike-report`**; &#x2A;*no `serde`**, because a study returns data and the caller
serialises it; &#x2A;*no `sha2`/`hex`**, because the fit cache's key is a method a study calls.

`rayon` sharpens the tier asymmetry: a Rhai study cannot express it, so a study that needs the
grid parallel is a Rust-tier study. That is not new — the interpreted tier can express no `Learner`
implementation, no generic and no `#[cfg(test)]` module either — and the tiers *differ only in
reach, a property of compilation rather than a rule anyone chose*.

## CI and the empty state [#ci-and-the-empty-state]

No `user_data/` — every CI checkout, every fresh clone — means an empty registry and an inert
crate: `user_study_entry` answers `None` for every name. The pipeline is still proven on every run
through the committed fixture tree, which drives a second generated registry end to end, including
a real fit through the shared learner double and a real read through the memory store, so the ML
half is proven on a box with no LightGBM binary. User code compiles only in a source checkout and
into the operator's own binary; `user_data/` is gitignored. `crates/vike-model/src/state_path.rs`'s
`user_rust_studies_dir` carries the operator consequence: the tier is meaningful only in a source
checkout, though it exists and lists on every install.
[Running a study](/docs/trader/research/running-a-study) turns a registry name into a run, and
[Authoring in Rust](/docs/trader/strategies/authoring-rust) is the strategy tier this one mirrors.


# Studies (/docs/trader/research/studies)



A study is a function, not an object. `crates/vike-user-research/src/contract.rs`'s `StudyFn`
states the whole contract: called once with a `StudyContext` and a recipe (`&toml::Value`), it
returns a `StudyOutcome` — named numbers and named text artifacts — or a `StudyError`. The header
honours a design verdict that refused a `Study` trait in as many words — *wrong tool for one
implementation; extract it from two* — and carries the reason: a strategy needs one because it is
*driven* (`on_bar` is called thousands of times and the object between calls is where its state
lives), while a study has no between-calls. The signature is the same on both tiers; a Rhai study
spells it `fn run(ctx, params)` with the types erased. [Rhai studies](/docs/trader/research/rhai-studies) and
[Rust studies](/docs/trader/research/rust-studies) cover each tier's own surface.

## Where a study lives [#where-a-study-lives]

```text
<project>/user_data/research/studies/
├─ rhai/<name>/<name>.rhai      interpreted — runs on a shipped binary
└─ rust/<name>/<name>.rs        compiled — meaningful only in a source checkout
```

The layout is spelled once, in `crates/vike-model/src/state_path.rs`: `RESEARCH_SUBDIR` because
a study is not a strategy, `STUDIES_SUBDIR` because the tiers are the strategy tree's own
`RHAI_SUBDIR`/`RUST_SUBDIR` rather than a second pair, artifact first and language second so a
third language later adds a sibling rather than a new root. `user_rust_studies_dir`'s doc carries
the compiled tier's limit: a `.rs` file is an input to `cargo`, so the tier is meaningful only in
a source checkout — but it still *exists* on a binary install and a listing still shows what is in
it, because an empty directory is an answer while a tier that silently disappears on half the
installs makes "I dropped a file in and nothing happened" unanswerable.

A study is a **folder**, and the entry file's stem must equal the folder name. Beside it sit
`*.toml` **recipes** — named configurations of the same study.
`crates/vike-studio-core/src/study_dispatch.rs`'s `RECIPE_EXT` notes that both tiers document that
layout and neither runner reads a recipe; the caller loads one, and `recipes` lists a folder's
recipes in name order, answering an absent or unreadable folder with an empty list, because a study
with no recipe is the ordinary state — both tiers run with no configuration at all.

<Callout title="A study places no orders, so there is no arming flag">
  `crates/vike-user-research/src/codegen.rs` records that a study folder carries no `study.toml` and
  therefore no `live` flag. The strategy tier has such a default-deny opt-in because mounting a
  strategy on a venue signs real orders; a study places none, and the surface it is handed reaches no
  network — enforced in the Rhai tier, a sanctioned convention in the Rust one. So a flag would be a
  settings key nothing reads — the defect class this workspace names as worse than an unimplemented
  feature.
</Callout>

## Listing: why it was the thing that was missing [#listing-why-it-was-the-thing-that-was-missing]

`crates/vike-studio-core/src/listing.rs` opens with the reason it exists: &#x2A;a result that is not
listed does not exist to the person who produced it.* Research results used to go to a ClickHouse
an end user does not have, and a strategy backtest printed to stdout and was gone with the
scrollback. `crates/vike-model/src/runs.rs` is the half that made a run leave something behind;
this is the half that finds it again.

`list_studies` takes `<project>/user_data/research/studies` — resolved by the binary through
`user_studies_dir`; the library resolves no path — and scans both tiers, `rhai/` then `rust/`, in
name order. It is **enumeration only**: nothing is compiled, nothing is run, no entry-file rule is
applied — a folder is a study. The header argues the boundary rather than apologising for it: a
compiled study resolves through a registry generated at *build* time, so "would this folder run"
is not a question a directory scan can answer; a folder added since the binary was compiled is
real, listable and not in the registry, and listing it is the honest answer. A name claimed in
both tiers lists twice, one row per tier. Each `ListedStudy` carries its name, its folder and its
`StudyTier` — the difference a user acts on.

`list_runs` takes `<project>/user_data/runs` and reads the **common manifest** and nothing else.
Every top-level field of `RunManifest` is identical for every producer, so one row renders a
backtest, a study run and a kind invented next year; the kind-specific `detail` subtree is carried
through untouched. Nothing opens the report: its *name* is common and its *content* is the
producer's business, so the listing reports whether it is there. Runs sort by directory name,
which for a minted id (`<unix-seconds>-<pid>-<seq>`) is chronological, and `ListedRun::run_id` is
deliberately the directory name rather than the manifest's own `run_id`, which is duplicated into
the file and can disagree with it — the path is what a caller opens, so the path decides.

## Nothing is skipped in silence [#nothing-is-skipped-in-silence]

Every failure is a `ListingDiagnostic` carrying its path and its fix, rendered as one line that
names what to do:

* **An absent root is silent; an unreadable one is `RootUnreadable`.** A fresh install has no
  `user_data/` at all, so "nothing there" is ordinary; a root that exists and cannot be listed is a
  permissions bug wearing the "not configured yet" answer, which looks exactly like a correct fresh
  install while every run silently vanishes. The header names the credential store as drawing the
  same line for the same reason.
* **`RunUnfinished`** is a run directory holding no manifest. The manifest is written *last*, so
  this is a run being written right now or one that stopped between its two writes — a
  `Severity::Warning` carrying whether the report is there, which is the whole question an
  operator has about the row.
* **`RunUnreadable`** collapses unreadable, not-JSON and missing-common-field into one variant,
  because to the user they are one event, with the reader's own words attached.
* **`RunIdMismatch`** lists the run under its directory and reports the disagreement.
* **`StrayStudy`** is a script directly in a tier root instead of in a folder — the same first-time
  mistake the strategy loader reports — and the message names where to move it.

`severity` splits these in two: the two warnings leave something listed or recoverable;
everything else means work the user believes is there and is not. Both listings sort before
returning, because a results surface whose rows move between two calls is one nobody can read,
and both import their layout vocabulary from the strategy loader rather than re-spelling it. The
Studio's [Research pane](/docs/trader/gui/studio/research-pane) is one list over both tiers;
[Running a study](/docs/trader/research/running-a-study) is what the row it hands you reaches, and
[Runs on disk](/docs/trader/backtesting/runs-on-disk) is the manifest itself.


# The run pipeline (/docs/trader/research/the-run-pipeline)



`crates/vike-studio-core/src/run.rs` is the Run pipeline: resolve a `StrategySpec` (compile the
Rhai buffer, or build a native registry strategy), load the picked `DataSlice` from the history
store, backtest it, return a result. Its header states the property that shapes everything else —
headless, no egui, so CI tests it directly — and the two axes it widened past the original "one
Rhai script over one bar series": the strategy source and the data slice.

## One strategy vocabulary [#one-strategy-vocabulary]

`crates/vike-studio-core/src/spec.rs` exists so "which kind of strategy is this" is decided in
exactly one place instead of at each of the four runner entry points. `StrategySpec` has two
sources: `Rhai(String)`, the editor buffer compiled through `vike_script::RhaiStrategy` per run
(and per sweep point, with that point's overrides), and `Native { name, params }`, a Rust strategy
from the backtest harness registry resolved by name plus a `toml::Value` params table.
`native_strategies()` is the registry's own roster, so a strategy added to
[the harness registry](/docs/trader/backtesting/harness-registry) appears in the Studio for free.

Params are a bare `toml::Value` rather than a spec type, and the header argues why: there is no
parameter-description mechanism in `vike-backtest`; each registered strategy reads its knobs ad hoc
off a `&toml::Value` (`BuyHold::from_params` is the reader convention, and the reference
strategies with no harness-tunable knobs take `Default::default()` and ignore params entirely), so
a parallel description layer would be a second source of truth no strategy is obliged to honour.
The Studio edits params as free-form `(key, value)` text rows and `params_from_rows` serialises
them: each cell is parsed as a TOML scalar so `3`, `2.5`, `true` and `"BTCUSDT"` reach the strategy
as the type the author meant, and text that is not valid TOML on its own — the common unquoted
symbol — falls back to a plain string. `native_from_toml_str`
is the wire idiom the data service's `RunSlice` verb uses: params ride the wire as TOML text and
are parsed back at the boundary. `build_strategy` is the one place the Rhai/native branch is taken;
`build_strategy_with` applies one sweep point's overrides — Rhai gets them as script `param()`
bindings, native gets them merged into its table.

## The data slice [#the-data-slice]

`DataSlice` carries a venue, a symbol **list**, an interval, a range and a `SliceKind`: `Bars`
replays `kind=bar` series through `StrategyEngine::run`, the original path; `Ticks` routes to
`vike_backtest::hist_replay::replay_ticks` over the store's recorded quote, trade and book series.
`DataSlice::bars` is the single-symbol constructor and is exactly the old struct literal;
`multi_bars` and `ticks` are the widened shapes.

Two enumerators feed the Studio's picker over the trait, so a remote store lists exactly like a
local one: `bar_series`, the one place the "bars only, interval present" filter lives, and
`tick_series`, the distinct `(venue, symbol)` pairs with any replayable tick series
(`REPLAYABLE_TICK_KINDS` is `quote`, `trade`, `book`), deduplicated because the replay merges all
three for a symbol.

<Callout type="warn" title="Depth is recorded, listed by the store, and not replayable">
  `UNREPLAYABLE_TICK_KIND` is `depth`, and its exclusion is reported rather than silent:
  `depth_only_series` names the instruments whose only recorded tick data is depth. Two independent
  reasons: the replay has no depth lane — `replay_ticks` never reads `scan_depth`, so a depth-only
  row would pick a slice that loads nothing — and folding depth into the book lane is the thing the
  store layout exists to prevent, since depth is the conflating L2 lane and a market-making backtest
  over teleporting depth reports fills it could never have got. The fix for such an instrument is to
  record `book`, `trade` or `quote` too.
</Callout>

`load_slice_bars` errors — never panics — on a tick slice, an empty symbol list, a symbol with no
bars in range, or symbols whose series lengths disagree; the last is `StrategyEngine::new`'s own
assert, caught here so a mismatched multi-symbol pick is a red banner rather than a worker-thread
panic. The tick path is the raw venue-ordered replay — no bar seeding, no point-in-time properties
snap, no feed-latency reordering; those knobs belong to a [run profile](/docs/trader/backtesting/run-profiles),
not a two-click picker — and an all-empty slice is a data error rather than a flat curve.
`RunError` keeps `Compile`, `Data` and `Strategy` separate so the UI can say "no such strategy"
instead of "compile error".

## The entry points [#the-entry-points]

Every runner takes a `StoreHandle` — `Arc<dyn HistStore + Send + Sync>`, owned because the tick
path needs an `Arc` it can clone into the engine's `'static` properties closure.

* **`run_slice`** resolves, loads and backtests synchronously; `spawn_run` is its worker-thread
  twin. `spawn_outcome` is the one `channel()` + `thread::spawn` + `tx.send(f())` site behind every
  `spawn_*`, and the UI polls the receiver with `try_recv()` each frame so nothing blocks the egui
  update loop.
* **`run_walkforward_slice`** walks the strategy over `n_splits` anchored out-of-sample windows,
  bar slices only and a single symbol — a tick or multi-symbol slice is a `RunError::Data` rather
  than a silent first-symbol fallback. The `_with_params` form takes a per-call `EngineParams`
  factory, because `EngineParams` is not `Clone` and every window must use the same cost knobs.
  [Walk-forward](/docs/trader/backtesting/walk-forward) covers the method.
* **`run_sweep_slice`** builds the Cartesian product of a `(name, values)` grid, builds the strategy
  per point, backtests each, and ranks best-first by annualised Sharpe through the harness's one
  ranking comparator, so a `NaN` Sharpe — an equity curve poisoned by a blown-up strategy — sorts
  last and can never sit at `best_index` 0. A point that fails to build is skipped; all failing is
  an error. `StudioSweep` carries the deflated Sharpe across the trial set (every input from the
  shared `sharpe_moments` derivation, never the annualised display quantity) and the probability of
  backtest overfitting from CSCV with `N_SPLITS = 16` — `C(16,8) = 12,870` combinations, and that
  second number alone is `NaN` with fewer than two trials or fewer than 16 observations, the
  deflated Sharpe being computed over whatever trials survived.
  [Overfitting](/docs/trader/analytics/overfitting) explains both numbers.
* **`compare_all_slice`** runs every `(name, spec)` strategy over one slice, each with its own
  fresh default `EngineParams`, Rhai and native rows mixing freely — the Saved pane's "Compare all".

The sweep is parallel on the harness's **bounded** pool (`map_bounded`, capped by
`VIKE_SWEEP_THREADS`, never rayon's global pool — a pool that fails to build logs and degrades to
the ambient one): each point materialises its own copy of the slice, and a tick point re-scans the
store outright, so concurrency is an `N_threads × slice` memory multiplier on boxes that also host
live trading. Bar slices load once and every point clones the series. Determinism does not rest on
scheduling — the pool reassembles by index, so entries reach the ranking sort in exact grid order,
and the sort is stable.

[Data and slices](/docs/trader/gui/studio/data-and-slices) is the picker over this pipeline,
[Sweeps](/docs/trader/backtesting/sweeps) and [Tick replay](/docs/trader/backtesting/tick-replay) are the
methods, and [Remote runs](/docs/trader/gui/studio/remote-runs) dispatches the same verbs to a data
service.


# Training (/docs/trader/research/training)



`crates/vike-ml/src/lib.rs` splits training from inference and says why. `train` and `cli` drive
the upstream LightGBM CLI binary as a child process: they render LightGBM's own config text, write
a data file, spawn the binary and read `output_model` back. That binary is built once, from a
pinned upstream tag, on the box that trains. Inference is compiled into every binary that runs a
strategy — including a live daemon signing real orders — and shipping a C++ library there to
predict from a model already trained is a cost with no benefit, so
[Inference](/docs/trader/research/inference) is pure Rust over the model text.

## Why a process and not a binding [#why-a-process-and-not-a-binding]

`crates/vike-ml/src/cli.rs`'s header records the bakeoff: every Rust binding drops
`categorical_feature` at dataset construction, silently, and then records it in the saved model's
parameter block anyway — an artifact that lies to an auditor. Driving the binary is the only route
that gets the feature right, and it costs no crate, no FFI, no `unsafe`, no cmake or bindgen, and
nothing in the `cargo deny --all-features` surface. `crates/vike-ml/src/grid.rs` adds the second
reason: a binding's `Booster::train` consumes its dataset, so it re-bins on every fit — a measured
95 ms/fit floor that cannot be amortised — while a process can bin once.

The binary is a **parameter**. `LightGbmCli::new` takes a path, reads no environment variable and
knows no default location; a binary resolves the path and hands it down — `vike-study --lightgbm`
in the [study runner](/docs/trader/research/running-a-study).

<Callout type="warn" title="The binary cannot name itself, so a file beside it does">
  `LightGbmCli::new` refuses a binary whose `PROVENANCE` file — written by the build recipe beside
  it — records a `tag=` other than `PINNED_LIGHTGBM_TAG`. It reads a file because upstream has no
  version flag: `--version` yields an unknown-parameter warning, "No training/prediction data,
  application quit", and a non-zero exit. The header states the honest weakness: the file is
  self-reported and only its `tag=` line is read, so the check catches a missing file and a different
  recorded tag and nothing else — not a different *build* of the pinned tag, since nothing in the
  crate hashes the binary. The equality gate, not this check, is the real proof —
  [Model pins](/docs/trader/research/model-pins).
</Callout>

`run_config` returns LightGBM's captured **stdout**, and the doc says that is not a convenience:
`Log::Info`, `Log::Warning` and `Log::Debug` all print to stdout and only `Log::Fatal` to stderr,
so the unknown-parameter warnings that are the only detector for a renamed parameter after a
version bump arrive there and nowhere else. A non-zero exit carries the last ten lines of stderr as
`MlError::Backend`; `crates/vike-ml/src/error.rs` keeps that distinct from `Trainer`, which says
*the thing I was told to drive is not what I expect* — an operator fault with an operator fix.

## The config is the seam [#the-config-is-the-seam]

`crates/vike-ml/src/train.rs` is pure functions — text in, text out — so its traps are testable on
a machine with no binary. `TrainConfig::render` emits the text LightGBM reads; LightGBM emits a
model text; `parse_model_text` reads that. Nothing else crosses between the halves.

`TrainData` is a row-major `&[f64]` matrix with `f32` labels, LightGBM's own shape.
`TrainData::new` validates once — a whole number of rows, one label per row — rather than letting
a child process report a shape error forty lines into a file. It declares no categorical column;
`with_categorical` is what declares one, and it re-runs the same `TrainData::validate` to refuse an
index outside a row. That rule is a refusal, not a clamp, because LightGBM ignores an out-of-range
index in silence, bins the column as a number, and the saved model's parameter echo still claims it
was categorical. `write_csv` writes label first, no header, matching LightGBM's defaults; a missing
value is spelled `nan` (`MISSING_TOKEN`), proven by a smoke that asserts the walker and LightGBM
route that row the same way. Values are the shortest decimal that parses back to the same bits, and
the renderer writes `precise_float_parser=true` on every task because LightGBM's default parser
clamps the exponent at 308 and is not correctly rounded — the wire is lossless because it is asked
for.

`render` refuses to leave three things to a default: `output_model` must be named (LightGBM's
default writes `LightGBM_model.txt` into the working directory, which collides the moment two fits
share a scratch root); `num_threads` is always written, always `1`; and `predict_raw_score` is
explicit on a predict task, because a margin and a probability are both plausible numbers. A
predict file carries a dummy label column, since LightGBM reads column 0 as the label and a
label-less file makes an N-feature model see N-1 — and `predict_disable_shape_check=true` is not
the fix; it silences the error while every feature shifts a column.

## Parameters in LightGBM's own names [#parameters-in-lightgbms-own-names]

`crates/vike-ml/src/params.rs`'s `GbdtParams` spells every field as LightGBM does, so a missing
field is looked up in LightGBM's docs rather than ours. Defaults are LightGBM's own — `binary`,
100 iterations, `learning_rate=0.1`, `num_leaves=31`, `min_data_in_leaf=20` — with departures for
determinism: `deterministic=true`, `force_row_wise=true` (with both `force_*` false LightGBM
benchmarks the two histogram strategies at runtime and picks by timing, changing the float
reduction order), `num_threads=1`, a pinned `seed=42`, and `verbosity=-1`. `apply` sets one
parameter by name and refuses an unknown one — a search axis matching no parameter would sweep a
knob that was never connected and report a winner — and refuses an integer that would wrap. One
pairing bites: `bagging_freq=0` disables bagging however small `bagging_fraction` is.

<Callout type="warn" title="A list-valued parameter is a comma-separated string, never brackets">
  LightGBM's config parser strips quotation marks but not brackets: `categorical_feature=0,3` names
  two columns, while `[0,3]` — the shape anyone reaches for who has used the Python API — names
  nothing, the column is binned as numeric, nothing errors, and the model's parameter echo still
  claims otherwise. The defence is a type: `categorical_feature` is an `Option<String>`, and
  `categorical_feature_csv` is how indices become one. Indices are 0-based over feature columns and
  do not count the label.
</Callout>

## Bin once, fit many [#bin-once-fit-many]

`grid.rs` gives the shape this backend was chosen for. A grid varies parameters over a fixed set
of datasets, so each is binned once with `task=save_binary` — about 20 s for 92 of them — and
every later fit reads a \~2.2 MB binary instead of re-parsing an 11.6 MB CSV, measured at \~212 ms
of write plus \~300 ms of parse per fit; over 22,400 fits that is roughly 260 GB of text I/O that
does not happen. The binning config must carry `categorical_feature`, because binning is where
LightGBM decides categorical-versus-numeric and a binary built without it is all-numeric forever.

The second construction-time decision is `min_data_in_leaf`: under the default
`feature_pre_filter`, binning drops every feature that cannot satisfy it, and a dropped feature
leaves the `feature_fraction` sampling universe. `BinPreFilter`'s doc carries the measurement: a
bin built at `min_data_in_leaf=10` and trained at `50` differs from the plain CSV fit at `50`, and
so does a `feature_pre_filter=false` bin, while a bin built at the fit's own value reproduces the
CSV fit byte-for-byte. `MinDataAgnostic` serves a sweep over that axis; `MatchFit` is what the real
learner's per-fold cache uses, keyed on the value ([Models](/docs/trader/research/models)). The
mismatch is silent — LightGBM's `CheckDataset` does not validate `min_data_in_leaf`.

`check_grid_params` refuses any `num_threads` other than `1`, with the measurement in the message:
143,293 ms against 2,105 ms at one thread on this data shape, a 68× cliff in the wrong direction.
The pinned binary is built without OpenMP so it cannot honour more anyway; the refusal means a
binary rebuilt with it does not turn a 30-minute grid into weeks silently.

## Logging, and where the binary comes from [#logging-and-where-the-binary-comes-from]

`grid.rs` logs nothing: a tracing event per fit writes 22,400 records into the trace-level file
layer, which the console filter does not turn down. A caller reports per fold and sets
`VIKE_LOG_FILE_LEVEL=warn` for a grid run — [Log volume](/docs/trader/data-providers/log-volume) has the
incident. `just lightgbm-build` builds the pinned binary into `bin/lightgbm/lightgbm` on the Linux
build box, where a dedicated CI job runs the binary-driven suites — refusing a run in which every
gated test self-skipped, because a skipped test passes and `0 passed` is the shape of a green job
that proved nothing. Off Linux there is no trainer at
all, which is why a study that must fit answers `NoLearner` rather than degrading into a number.
[Train a model](/docs/trader/tutorials/train-a-model) runs the whole path.


# Cheatsheet (/docs/trader/scripting/cheatsheet)



Everything below is registered by `crates/vike-script/src/engine.rs`'s `build_engine` onto a resource-limited engine (the numbers are on [Limits](/docs/trader/scripting/limits)) and driven by `crates/vike-script/src/strategy.rs`'s `RhaiStrategy`. The non-indicator names are pinned in `engine.rs`'s `HOST_FN_NAMES`. The indicator names are derived from the registry at run time and are deliberately not listed here — `vike-cli indicators` prints the callable set ([indicators](/docs/trader/reference/cli/research/indicators)).

## Hooks [#hooks]

| hook            | called                             | notes                                                                                                    |
| --------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `fn on_start()` | before the first bar               | `position()`/`price()` are not refreshed here — there is no symbol yet, so they read their initial `0.0` |
| `fn on_bar()`   | once per bar                       | the only place to read the bar and trade                                                                 |
| `fn on_stop()`  | when the engine stops the strategy |                                                                                                          |

A hook is detected by name as a zero-argument `fn`; one the script never wrote is skipped, never attempted. There is no fill hook — a script observes its resulting position through `position()`. The top level (everything outside a `fn`) runs EXACTLY ONCE at compile: a top-level `const` is visible inside every hook, a top-level `buy(1.0);` is discarded, and a top-level indicator reference is cleared so the first real bar is the first bar any indicator sees. A hook's own `let` locals live for that one call; the script keeps no cross-bar mutable state of its own.

## Context — the current bar [#context--the-current-bar]

| function                                       | returns                                                         |
| ---------------------------------------------- | --------------------------------------------------------------- |
| `close()` `open()` `high()` `low()` `volume()` | `f64`, that field of the current bar                            |
| `index()`                                      | `i64`, the current step index — bars processed so far minus one |
| `now()`                                        | `i64`, engine time in epoch milliseconds                        |

All snapshotted before the hook runs (`register_reads`).

## Account [#account]

| function     | returns                                                                               |
| ------------ | ------------------------------------------------------------------------------------- |
| `position()` | `f64`, signed position size in the mounted symbol; `0.0` when flat                    |
| `price()`    | `f64`, the last mark — the engine's post-fill price in a backtest, the bar close live |
| `equity()`   | `f64`, account equity now                                                             |

The definitions are `vike_model::Broker`'s own (`crates/vike-model/src/strategy/mod.rs`); the script reads a snapshot of them.

## Orders [#orders]

| verb                      | meaning                                    |
| ------------------------- | ------------------------------------------ |
| `buy(qty)`                | market, side `+1`                          |
| `sell(qty)`               | market, side `-1`                          |
| `market(side, qty)`       | market; `side` is `1` to buy, `-1` to sell |
| `limit(side, qty, price)` | limit at `price`                           |

`qty` is `f64` in units; `side` is an integer. A verb records an `Intent` (`crates/vike-script/src/ctx.rs`); after the hook returns cleanly the intents are drained onto the broker in order, on the mounted symbol. A hook that errors drains nothing. The full page is [The order vocabulary](/docs/trader/scripting/order-vocabulary).

## Parameters [#parameters]

```rust
let fast = param("fast", 5.0);   // top level, so the one-time run bakes the value in
```

`param(name, default) -> f64`. The default may be written `5` or `5.0` — it is `Dynamic`, not `f64`, after a version that rejected the integer spelling. First-seen wins in the `(name, default)` list discovery reports; the call itself still returns its own `default` when nothing overrides it. A sweep injects overrides BEFORE the one-time top-level run, so a swept value holds for the strategy's whole life; `discover_params` lists the `(name, default)` pairs in declaration order for the sweep grid.

## Indicators [#indicators]

| form                            | example                                                                | rule                                                                                                                                                 |
| ------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name()`                        | `psar()`                                                               | every parameter at its registry default — the only spelling for a parameterless indicator, and the only way to reach a fractional default            |
| `name(p1)` … `name(p1, p2, p3)` | `sma(20)`, `rsi(14)`                                                   | up to the indicator's own parameter count, at most 3; parameters left off the end take their defaults; one argument too many is a function-not-found |
| `name_line(...)`                | `bollinger_mid(20, 2.0)`, `macd_signal(12, 26, 9)`, `stochastic_k(14)` | one accessor per line of a multi-output indicator, same arguments as the bare name; all lines of one indicator share one streaming instance          |

Arguments are int or float; a non-numeric argument is a runtime error, not NaN. A bare name binds when the indicator is single-output or its line 0 is the namesake line (`macd()`, `adx()`); `bollinger`, `donchian`, `keltner`, `envelopes` and `std_error_bands` are refused bare because their line 0 is `upper` — spell the line, `bollinger_mid()`. Never bound in any spelling: `ichimoku`, `zigzag` and `williams_fractal` (they read future bars), `kst` (nine parameters), and `var` (a Rhai reserved word — use `stddev`).

<Callout type="warn" title="Call every indicator unconditionally, every bar">
  An indicator is fed the current bar the first time it is referenced in that bar; a second reference returns the cached value. One behind an `if` silently skips the bars it is not called on and desyncs from the series (`crates/vike-script/src/lib.rs`). `NaN` means warming up — the shipped templates open with `if s.is_nan() { return; }`.
</Callout>

A user indicator from `user_data/indicators/<name>.rhai` is called the same way: `my_ema()`, `my_ema(20)` for each `param()` it declares, `my_bands_mid()` for a declared line. [Writing an indicator](/docs/trader/scripting/writing-an-indicator) has the file contract; in short, `fn on_bar(bar)` is required, `bar` is a map of `ts`/`open`/`high`/`low`/`close`/`volume`, `this` is the state `fn init()` built, returning `()` means warm-up, and `param()` is the only host function that engine registers — an indicator cannot trade.

## Diagnostics [#diagnostics]

`print(...)` and `debug(...)` go to the `tracing` target `vike_script` at INFO and DEBUG, never to the host's stdout (`redirect_script_output`). `import` is refused. A runtime error costs that bar's orders; ten in a row disable the strategy.

## A whole strategy [#a-whole-strategy]

The shipped `SMA cross` template (`crates/vike-script/src/templates.rs`'s `SMA_CROSS`), which also uses Rhai's own `to_int`, `is_nan` and `abs`:

```rust
let fast = param("fast", 5.0);
let slow = param("slow", 20.0);
fn on_bar() {
    let f = sma(fast.to_int()); let s = sma(slow.to_int());
    if s.is_nan() { return; }
    let target = if f > s { 1.0 } else { -1.0 };
    let delta = target - position();
    if abs(delta) > 1e-12 { market(if delta > 0.0 { 1 } else { -1 }, abs(delta)); }
}
```


# Scripting (/docs/trader/scripting)



A Rhai script in Vike Trader is not a sandboxed toy beside the real strategies; it *is* one.
`crates/vike-script/src/lib.rs` describes the crate as running a Rhai script as a
`vike_model::Strategy<B>` — the same seam the compiled Rust strategies use, at a millisecond
cadence — and every engine that drives strategies, backtest and live alike, drives a script the
same way. This tree covers that crate and one more: the script engine is `vike-script`, while the
user-owned strategy files and their presets live in `vike-studio-core/src/user_strategies/`. They
are documented together because the reader is the person writing a strategy, whichever crate
ends up loading it.

## The contract, in two halves [#the-contract-in-two-halves]

The `lib.rs` header states the script contract as two halves, both about *calling* an indicator.

**What a script may call.** `RHAI_INDICATORS` is the host-bound indicator set, derived from
`vike_indicators::registry()` rather than hand-listed: almost the whole catalog, minus the entries
`unbound_reason` rejects because a scalar binding of them would return a silently *wrong* number.
Each bound indicator has one form per argument count, from zero (every registry default) up to its
own parameter count, and `unbound_reason` says why a missing one is missing. [The engine](/docs/trader/scripting/the-engine)
walks the rules; the [cheatsheet](/docs/trader/scripting/cheatsheet) is the scannable version.

**How it must call it.** An indicator function must be called *unconditionally* on every `on_bar`
invocation to keep its streaming state correct. The header is blunt about the alternative: an
indicator referenced behind an `if` silently skips whichever bars it was not called on, desyncing
it from the bar series. That is a consequence of the fed-once-per-bar cache in `engine.rs`'s
`indicator_value`, and it is the one rule in this tree that fails without an error.

## Defining an indicator, not just calling one [#defining-an-indicator-not-just-calling-one]

The other seam is `RhaiIndicator` in `indicator.rs`. A file under `user_data/indicators/<name>.rhai`
compiles to a real `vike_indicators::Indicator` — fed-once-per-bar state, `vectorize` parity by
construction, and no access to the order verbs — and `RhaiStrategy::compile_with_indicators` binds
it beside the built-ins. The two halves above then apply to it unchanged, including multi-output: a
file declaring `fn outputs() { ["upper", "mid", "lower"] }` gets its lines through the same
`line_fn_name` the built-ins use (`user_line_accessors` is the `line_accessors` twin), under the
same rule for whether the bare name binds at all. A file that declares no `outputs()` is
single-output and unchanged.

Because it is a real `Indicator`, the same compiled prototype also plots: `user_meta` wraps one as
a `&'static vike_indicators::IndicatorMeta` whose factory clones it, which is what the chart's ƒx
picker mounts. Nothing about the script contract changes for that — a file written for a strategy
is already a chart study — except one optional addition, `fn overlay()`, the author's answer to
"price pane, or my own?". [Writing an indicator](/docs/trader/scripting/writing-an-indicator) is the
contract; [Loading indicators](/docs/trader/scripting/loading-indicators) is how the folder reaches a
process.

## Where a script runs [#where-a-script-runs]

A strategy script is compiled in three contexts — the backtest harness, the live daemon and
offline validation — and they reach the same engine.

* **Backtest.** The harness registry's `rhai` arm in `crates/vike-backtest/src/harness/registry.rs`'s
  `strategy_by_name` compiles an inline `src` param into a `RhaiStrategy<SimBroker>`; `vike-cli backtest --script`
  is what puts a file's source there. See [the harness registry](/docs/trader/backtesting/harness-registry).
* **Live.** Rhai scripts are live-mountable on `vike-tradehub`, named explicitly by path in the
  reviewable profile. `crates/vike-tradehub/src/config.rs`'s header spells it —
  `[strategy] rhai = "<path>"`, "mutually exclusive with `name`", "the script named EXPLICITLY by
  path in this reviewable file, its compiled source's sha256 logged at INFO as the audit trail" —
  so nothing is auto-discovered, and `name = "rhai"` is refused with a message pointing at the
  path spelling. Four rails hold that mount, and the fourth is the one this tree leans on:
  `crates/vike-tradehub/Cargo.toml`'s `vike-script` dependency comment records that the daemon
  compiles through "the SAME resource-limited engine the backtest arm builds (`vike-script`'s one
  `build_engine` — this daemon registers no host function of its own)", so the host functions a
  script may call live are the backtest's. The one gap is not the engine's but the process's: the
  user-indicator set `build_engine` binds is process-wide and installed by the BINARY, and this
  daemon installs none (the four that do are on
  [Loading indicators](/docs/trader/scripting/loading-indicators)), so a `user_data/indicators/` file a
  `vike-cli backtest` script can call is a function-not-found here. The same comment calls a
  scripting engine inside the binary that signs real orders a supply-chain decision made
  deliberately, and names the Python/JS refusal beside it — a refusal by class, a product statement
  rather than a deferral.
* **Validation.** `vike-cli mcp`'s `validate_strategy` tool compiles a script through
  `discover_params`, which the tool's own doc calls the same error surface as mounting it.

<Callout type="warn" title="A script cannot import, and cannot print to stdout">
  `build_engine` installs a `DummyModuleResolver`, so `import "…" as m;` is refused: a default Rhai
  engine resolves imports from the process's working directory, which for the daemon is the project
  holding the credential store. `redirect_script_output` points `print`/`debug` at the `tracing`
  facade instead of the host's stdout, because two hosts — `vike-cli mcp` and `vike-tradehub` — use
  stdout as a protocol. Both are argued in [The engine](/docs/trader/scripting/the-engine).
</Callout>

## Where the files live [#where-the-files-live]

A user's strategies are files, not rows in a blob — `crates/vike-studio-core/src/user_strategies/mod.rs`
opens with exactly that sentence, and its layout is one folder per strategy under
`user_data/strategies/rhai/<name>/<name>.rhai`, presets as `.toml` beside the entry, and
`strategies/rust/<builtin>/` holding presets for a strategy whose code is in the binary.
[User strategies](/docs/trader/scripting/user-strategies) is the directory scan and its named
diagnostics; [Presets](/docs/trader/scripting/presets) is how `<strategy>/<preset>.toml` becomes the
params a strategy is constructed with; [Migration](/docs/trader/scripting/migration) is the one-time
move off the Studio's `studio_strategies.json` blob.

## Where a script is written [#where-a-script-is-written]

The Studio's [editor](/docs/trader/gui/studio/editor) is where a strategy script is edited in the app.
The other interpreted tier in the product — a [Rhai study](/docs/trader/research/rhai-studies) — is a
different thing on a different engine: `crates/vike-studio-core/src/rhai_study/bind.rs` registers
a store-reading surface for research, not the order verbs, and its operation ceiling is set for a
whole window rather than a bar. A strategy trades; a study answers a question about data.

## The pages [#the-pages]

| page                                                           | what it is                                                                                  |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| [The engine](/docs/trader/scripting/the-engine)                     | the resource-limited `rhai::Engine`, what is registered on it, and what a script may not do |
| [The order vocabulary](/docs/trader/scripting/order-vocabulary)     | the `Intent` verbs and the `ScriptCtx` they are recorded into                               |
| [Writing a strategy](/docs/trader/scripting/writing-a-strategy)     | the compiled-script strategy: hooks, `param()`, the one-time top level, fail-safe           |
| [Writing an indicator](/docs/trader/scripting/writing-an-indicator) | a Rhai indicator as a real `Indicator`                                                      |
| [Loading indicators](/docs/trader/scripting/loading-indicators)     | `user_data/indicators/*.rhai`, the report, and which binaries install it                    |
| [User strategies](/docs/trader/scripting/user-strategies)           | the strategy tree and its diagnostics                                                       |
| [Presets](/docs/trader/scripting/presets)                           | `<strategy>/<preset>.toml` to constructed params                                            |
| [Migration](/docs/trader/scripting/migration)                       | off the JSON blob, once                                                                     |
| [Limits](/docs/trader/scripting/limits)                             | the ceilings the engine enforces and what hitting one looks like                            |
| [Cheatsheet](/docs/trader/scripting/cheatsheet)                     | every host function and verb on one page                                                    |


# Limits (/docs/trader/scripting/limits)



A plain `rhai::Engine::new()` leaves most of these ceilings OPEN: no operation cap, and no size bound on a string, array or map. Of the five below, call depth is the one rhai already defaults — `MAX_CALL_STACK_DEPTH`, 64 in a release build and 8 in a debug one — so `set_max_call_levels(64)` pins that release default rather than adding a missing ceiling, and in a debug build it raises it from 8 to 64. `crates/vike-script/src/engine.rs`'s `build_engine` opts every strategy script into all five so that a runaway or malicious script cannot hang the strategy loop, and `crates/vike-script/src/indicator.rs`'s `indicator_engine` sets the same five so that one runaway script is bounded the same way whichever seam loaded it.

## The five ceilings [#the-five-ceilings]

| ceiling     | value                  | rhai setter           | what it bounds                                                              |
| ----------- | ---------------------- | --------------------- | --------------------------------------------------------------------------- |
| operations  | 2,000,000              | `set_max_operations`  | operations per hook call, "to avoid consuming too much resources"           |
| call depth  | 64                     | `set_max_call_levels` | levels of function calls, "to avoid infinite recursion and stack overflows" |
| string size | 8 KiB (8 × 1024 bytes) | `set_max_string_size` | the length, in bytes, of a string                                           |
| array size  | 4096                   | `set_max_array_size`  | the length of an array                                                      |
| map size    | 4096                   | `set_max_map_size`    | the size of an object map                                                   |

The last column quotes the setters' own doc comments (rhai 1.25.1, `src/api/limits.rs`). Each value is a literal in `build_engine`; no settings file raises or lowers them.

<Callout title="Per hook call, not per lifetime">
  `build_engine`'s doc: the limits are PER-HOOK-INVOCATION — each `call_fn` gets a fresh operation counter — not cumulative across the strategy's lifetime. A script gets two million operations for every `on_bar`, however many bars it has already seen. `build_engine` itself runs once per mounted strategy, never per bar.
</Callout>

## What a script sees [#what-a-script-sees]

Rhai reports a tripped ceiling as a runtime error, never as a value: `EvalAltResult::ErrorTooManyOperations` (rendered `Too many operations`), `ErrorStackOverflow` (`Stack overflow`) or `ErrorDataTooLarge` (`<type> too large`). Nothing distinguishes one from any other runtime error on the way out, and the strategy's fail-safe treats them all alike.

That fail-safe is `crates/vike-script/src/strategy.rs`'s `RhaiStrategy::run_hook`, and the module header states the contract: a hook that errors emits zero orders that bar — intents recorded before the error are discarded — and the strategy keeps running. The error is logged at `warn` as `rhai hook errored; emitting no orders this bar`, with the hook name and the script error. After 10 CONSECUTIVE errors the strategy self-disables: every later hook call is a no-op, and `rhai strategy disabled after 10 consecutive errors` is logged once at `error`. A successful hook call resets the counter.

The pinned evidence is in `crates/vike-script/tests/binding.rs`. `infinite_loop_trips_op_cap_no_hang` compiles `fn on_bar() { let i = 0; while true { i += 1; } buy(1.0); }`, calls it once, and asserts that the call returned and submitted nothing. `self_disables_after_ten_consecutive_errors_then_stays_inert` errors on the first ten bars and would `buy(1.0)` on the eleventh if the body ever ran again; it does not.

<Callout type="warn" title="Ten errors of any kind, not ten limit trips">
  The counter does not care why a hook failed, and three other faults count the same way, each firing on every bar: a wrong-typed indicator argument (`sma("20")` raises `bad_arg`'s error rather than returning NaN — deliberately, because NaN is the warm-up value and a strategy reading a permanent warm-up does nothing forever without saying why); a call to an indicator name the bridge never bound (a Rhai function-not-found, which `RHAI_INDICATORS`'s doc says self-disables the strategy after the cap); and a user indicator that threw, raised at the call site. A strategy with any of these in `on_bar` is dead after ten bars, and the log is where it says so.
</Callout>

## Compile time is bounded too [#compile-time-is-bounded-too]

The top level of a script — everything outside a `fn` — runs EXACTLY ONCE, inside `RhaiStrategy::compile`, on the same engine with the same limits. A ceiling tripped there is a `ScriptError` and the strategy does not mount; `discover_params` walks the same path when it lists a script's `param()` knobs. A top-level loop that would exhaust the counter therefore fails at compile, where an author sees it, rather than on the first bar.

## A user indicator faults differently [#a-user-indicator-faults-differently]

`indicator_engine` sets the same five numbers, but an indicator's `on_bar` has no error channel — `vike_indicators::Indicator::on_bar` returns a `Vec<f64>`. A script that trips a limit, or throws for any other reason, reads as NaN on every one of its lines for that bar, and the fault is RECORDED rather than dropped: `RhaiIndicator::fault` holds the message, and a later successful bar (or `reset`) clears it. The strategy-side bridge, `engine.rs`'s `register_user_indicators`, reads that fault after feeding the bar and raises it as a Rhai error at the accessor the author called — so a strategy sees an error, not a warm-up NaN, and the ten-error counter applies. A consumer reading through the `Indicator` trait directly — the chart plots the same compiled prototype — gets the NaN and nothing else.

## The study tier is not this [#the-study-tier-is-not-this]

Rhai studies run on a different engine with different ceilings, and the difference is the unit of work rather than a relaxation of standards: `crates/vike-studio-core/src/rhai_study/bind.rs`'s `MAX_OPERATIONS` is 1,000,000,000 because a study is called ONCE for a whole window, and two million would refuse a plain loop over a hundred thousand bars; `MAX_CALL_LEVELS` stays 64, because a runaway recursion is a stack overflow whichever tier it is in; and the size limits are deliberately unset, because the big arrays a study holds are the ones the host handed it out of the store. [Rhai studies](/docs/trader/research/rhai-studies) carries that engine.

## What is not a ceiling [#what-is-not-a-ceiling]

Two closures on the same engine are refusals rather than numbers, and they belong to [The engine](/docs/trader/scripting/the-engine): `import` is refused outright (`DummyModuleResolver`), and `print`/`debug` go to the `tracing` facade under the `vike_script` target instead of the host's stdout. The second has no limit at all — a `print` inside `on_bar` fires once per bar, at INFO, into the file log layer, which defaults to `trace`, so a chatty script over a long backtest writes into `<project>/settings/state/logs`; `VIKE_LOG_FILE_LEVEL` is the knob, and `redirect_script_output`'s doc carries the argument.


# Loading indicators (/docs/trader/scripting/loading-indicators)



`crates/vike-script/src/load.rs` loads `<project>/user_data/indicators/*.rhai` — the user's own
indicators — into compiled `RhaiIndicator`s ready to hand to
`RhaiStrategy::compile_with_indicators`. Its header calls it the sibling of the strategy loader and
deliberately much smaller: an indicator is one file with no presets, so there is no
folder-versus-entry-file rule and no `rust/` tier.

## The layout is flat [#the-layout-is-flat]

`vike_model::state_path::INDICATORS_SUBDIR` is `indicators`, and its doc explains the asymmetry
with `strategies/`: a strategy owns `.toml` presets that must travel with it, while an indicator's
only knob is a top-level `let` inside its own file, so a folder per indicator would be an empty
directory wrapping one file. The file stem is the name a strategy calls it by; the `.rhai`
extension is matched case-insensitively, because a Windows editor that saved `MyThing.RHAI` wrote a
real indicator.

## Every rejection is reported [#every-rejection-is-reported]

`load_user_indicators(root)` returns an `IndicatorLoadReport` rather than a `Vec`, and the header
gives the reason: a user's indicator failing to load is indistinguishable, from inside their
strategy, from a typo in the call — both are function-not-found — so the load side is the only
place that can say which. An absent root is an empty, *clean* report, not a diagnostic; a root
that exists and cannot be read is one. The report holds `root`, the loaded `indicators` sorted by
name, and `diagnostics` in a deterministic order — `load_user_indicators` sorts them on their
`Debug` rendering, which begins with the variant, so they arrive grouped by kind — each
`IndicatorDiagnostic` carrying the file so the user's next action is to open it:

| variant          | when                                                                                     | message                                                                                                                         |
| ---------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `CompileFailed`  | the script did not compile, or has no `fn on_bar(bar)`                                   | `<path>: did not compile — <rhai error>`                                                                                        |
| `NameConflict`   | the stem would shadow a built-in or a host function (`user_indicator_conflict`)          | `<path>: <reason>`                                                                                                              |
| `InSubdirectory` | a `.rhai` inside a subdirectory of `indicators/`                                         | `ignored — indicators/ is FLAT, one <name>.rhai per indicator. Move it up one level.`                                           |
| `DuplicateName`  | two files share a stem (`ema.rhai` + `ema.RHAI`, which coexist on Linux) — neither loads | `` `<name>` is claimed by N files (…) — neither is loaded, because which one won would depend on directory order. Rename one.`` |
| `Unreadable`     | the directory or a file could not be read                                                | `<path>: could not be read — <error>`                                                                                           |

The conflict check runs *before* compiling: a file named `sma.rhai` is refused for its name whether
or not its body is valid, since a compile error for it would send the author to fix the wrong
thing. Order is sorted, not filesystem order — two indicators cannot interact, so order changes no
value, but it changes the diagnostic list, and a report that reshuffles between machines is one
nobody can diff. `is_clean()` is "nothing was rejected", distinct from "loaded nothing".

## Installed once, per process [#installed-once-per-process]

`install_user_indicators` in `engine.rs` installs already-compiled prototypes process-wide, so
every strategy the process compiles can call them — including through the harness's `run_*` entry
points and the Studio runners, none of which take an indicator argument. The set is process-wide
for the same reason `vike_indicators::registry()` is: the built-ins are a static no run path passes
around, and this makes the user's own indicators the same kind of thing. Only a *binary* may call
it, on the `vike_log::init` precedent — the function performs no I/O, so the caller owns the
directory resolution. A second call returns `Err` carrying the already-installed count rather than
silently keeping or replacing the first set, because two callers means two places believe they
own it.

`load_and_install_user_indicators(user_data_dir)` is the pair a composition root wires in one
call: join `INDICATORS_SUBDIR`, load, install, and return every message as data — one
`indicator not loaded — …` line per diagnostic. Data rather than output, because a root whose
stdout is a protocol must print on stderr, and a root logging through `tracing` cannot emit
anything until its subscriber exists. Nothing here is a reason to fail: one half-edited file must
not block a command with nothing to do with it, and an empty return is the normal outcome,
including for a project with no `indicators/` directory at all.

## Which binaries install the set [#which-binaries-install-the-set]

* **`vike-cli`** — `crates/vike-cli/src/lib.rs`'s `install_user_indicators` runs before any
  subcommand dispatches, so a script run by any verb can call them; rejections go to stderr, never
  stdout, because `vike-cli mcp`'s stdout is a protocol.
* **the standalone `backtest` bin** — `crates/vike-backtest/src/backtest_cli.rs` installs before
  the profile load, which is the first step that can compile a script, with diagnostics on stderr
  so `--json`'s machine report stays parseable.
* **`vike-datahub`** — the server installs the set from *its* project's directory. Its doc carries
  the hazard below.
* **`vike-desktop`** — `crates/vike-desktop/src/main.rs`'s `install_user_indicators` deliberately does
  *not* use the pair: it has two consumers of one load and needs the report, so it calls
  `load_user_indicators` once and hands `chart_studies()` to the chart's ƒx picker (unconditionally)
  and `prototypes()` to the strategy bindings (not in the desktop, which has no strategy runner). It runs after `vike_log::init`, so every rejected file is reported, and
  before any window, so the picker is complete the first time it opens. The directory is the
  sibling of the resolved settings directory, not a fresh walk, so a relocated project cannot get
  its credentials from one place and its indicators from another.

In each, `VIKE_USER_DATA_DIR` names the directory outright and beats the project walk, so the
binaries cannot disagree about which library this box has.

<Callout type="warn" title="On a remote datahub, the server's set wins and the client cannot see it">
  `datahub_cli.rs`'s `install_user_indicators` doc calls this a real semantic change. Before it
  existed, a client script calling `my_ind()` failed on the server with an unknown-function error,
  loud and unambiguous. Now it binds to whatever `<server project>/user_data/indicators/my_ind.rhai`
  contains: `vike-cli backtest` ships the script and never the indicator files, and no hash or
  version is exchanged, so the same script on two servers with different indicator directories
  returns different numbers with nothing in the response saying so. Rejections land in the
  operator's log, not the client's error.
</Callout>

## What a script may type [#what-a-script-may-type]

`installed_user_indicators()` returns the installed names, but a name is not necessarily a
callable spelling: a multi-output file whose line 0 is not its namesake has no bare name, exactly
as `bollinger` has none. An advertising surface joins it with `installed_user_bare_call`,
`installed_user_line_accessors` and `installed_user_indicator_params`, which is what
`vike-cli indicators` does — it prints the user set in its own block, one row per callable
spelling with the line it returns, and `--json` carries them under their own key with no
`category`. Two declared limits in that command's header: `--category` never matches a user
indicator, because it has none, and `--name` matches the file's own name rather than a per-line
accessor. See [vike-cli indicators](/docs/trader/reference/cli/research/indicators).

Registration order is what makes the name rules necessary: `build_engine` registers the user set
after the built-ins, and `register_fn` replaces, so a file called `stochastic_k.rhai` would
otherwise take over that accessor for every strategy. `user_indicator_conflict` refuses it, and
`register_user_indicators` skips a refused name rather than binding it. One residual is declared
rather than closed: a collision between two user files — `a.rhai` declaring a line `b`, beside a
file `a_b.rhai` — is invisible to the per-file check, and the later registration wins.

Writing the file itself is [Writing an indicator](/docs/trader/scripting/writing-an-indicator).


# Migration (/docs/trader/scripting/migration)



Before a user's strategies were files, every one the Studio saved lived in a single pretty-JSON array colocated with the data store as `studio_strategies.json` (`crates/vike-studio/src/saved.rs`'s `save_strategies`). `crates/vike-studio-core/src/user_strategies/mod.rs` names the two properties that made that shape lossy: `load_strategies` answers a parse failure with an EMPTY list, so one corrupt byte loses the whole library; and the blob sits at `store.root()`, inside the hist store — re-downloadable market data whose lifecycle is "delete it and re-ingest". The migration in `crates/vike-studio-core/src/user_strategies/migrate.rs` moves those rows into the layout [User strategies](/docs/trader/scripting/user-strategies) describes, once.

## Two populations, two destinations [#two-populations-two-destinations]

The blob holds one row per "saved strategy", but the rows split into two kinds that only look alike (`migrate.rs`'s module header):

| row                                                            | what the user actually authored | becomes                                                                  |
| -------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------ |
| **Rhai** — carries the script                                  | a strategy                      | `strategies/rhai/<name>/<name>.rhai`, the script byte-verbatim           |
| **Native** — carries a registry name plus free-form param rows | a parameter set                 | `strategies/rust/<native>/<entry-name>.toml`, a preset for that built-in |

A native row carries no code and cannot: the strategy is compiled into the binary. Migrating it as a strategy folder would produce an empty folder named after something the user never wrote, so it becomes a preset filed under the registry strategy it belongs to. That folder holds presets and NO entry file, and the loader treats it as a legitimate second shape (`load.rs`'s `StrategyBody::Native`) — `migrate.rs` predicted that rule in its own doc before a rust-side loader existed, and `load.rs`'s header records that copying the `rhai` rule verbatim was a real bug.

The script is copied verbatim, because a migration that reformats or annotates a user's script has rewritten their work.

## Text rows into a TOML preset [#text-rows-into-a-toml-preset]

The JSON's params are `(String, String)` pairs — text, because there is no typed `ParamSpec` seam to check them against. The migration invents none: `preset_toml` runs the rows through `crates/vike-studio-core/src/spec.rs`'s `params_from_rows`, the exact function the Studio uses at run time, and serialises the result through a `toml::Value`. So the migrated file MEANS what the JSON row meant: `2` stays an integer, `true` stays a bool, and a bare `BTCUSDT` — not valid TOML on its own — becomes the quoted string the run-time path would have made of it. A value with a quote in it, or a leading `#`, is escaped by the serialiser rather than pasted into a template.

The table is FLAT (`size = 2`, never a `[params]` wrapper), the one preset format both trees share ([Presets](/docs/trader/scripting/presets)). Above it sit two provenance lines, because six months later "where did this come from" has to be answerable from the file itself:

```toml
# preset 'hold-2' for the built-in strategy 'buy_hold'
# migrated from studio_strategies.json
size = 2
symbol = "BTCUSDT"
```

Both names are folded onto one line first (`one_line` replaces every control character with a space): a name carrying a newline would end the comment and turn a provenance note into a TOML parse error.

## Names become filenames [#names-become-filenames]

The Saved pane never constrained its name box, so a row can be called `BTC / ETH pairs (v2)` — or `../../secrets`. `slug` has one rule: anything that is not a letter, a digit, `-`, `_` or `.` collapses to a single `-`, then leading and trailing `-`/`.` are stripped. That removes every path separator, reserved character and control character without a deny-list, and the strip makes traversal structurally impossible — `..` cannot survive at either end. Letters are Unicode, not ASCII; a strategy named in Cyrillic is a perfectly good filename. From the module's own pins: `BTC / ETH pairs (v2)` becomes `BTC-ETH-pairs-v2`, `../../secrets` becomes `secrets`, and `...` or `///` leaves nothing — reported as `Unnameable`, never silently renamed to something the user would not find again.

## What is reported instead of written [#what-is-reported-instead-of-written]

`plan_migration` is PURE — no filesystem, no clock, no environment — and produces paths relative to `<project>/user_data` in the input's order, so a report reads in the order the Saved pane showed. `apply_migration` joins the root, which is also what confines every write under it. Every failure on either side is a named `MigrationSkip`, never an `Err`: one unwritable file must not abandon the other nineteen.

| skip                    | when                                              | the message says                                      |
| ----------------------- | ------------------------------------------------- | ----------------------------------------------------- |
| `Unnameable`            | the name has no usable filename form              | rename it in the Saved pane and migrate again         |
| `NamelessNative`        | a native row whose registry name is blank         | nothing for the preset to belong to                   |
| `Collision`             | two rows plan the same file                       | which row already claims the path; rename one of them |
| `AlreadyPresent`        | something is already at the target path           | already migrated, left untouched                      |
| `WriteFailed`           | the directory or the file could not be written    | the path and the error                                |
| `PresetNotSerializable` | a native row's params are not expressible as TOML | the serialiser's error; re-create the row by hand     |

Collisions are case-FOLDED: `Fast` and `fast` are two files on Linux and one on Windows, and a migration that silently overwrites on one platform and not the other is worse than one that refuses. Saved names were never unique-constrained and `slug` maps distinct names onto one stem (`my strat` and `my/strat` both become `my-strat`), so this is reachable from ordinary use. The first row wins; every later one is named.

## Idempotent, and the JSON is read-only [#idempotent-and-the-json-is-read-only]

<Callout type="warn" title="A migration that consumes its source cannot be re-run">
  `apply_migration` writes a file only where NOTHING is at that path — probed with `symlink_metadata` rather than `exists()`, so a dangling symlink is not written through. A second run writes nothing, reports every target as `AlreadyPresent`, and leaves a user's later edits to a migrated file intact; `MigrationOutcome::written` is empty on a re-run, which makes the contract observable rather than asserted. The module never reads, writes, moves or deletes `studio_strategies.json` — it does not even take its path. The blob stays the read-only fallback for a build the user rolls back to.
</Callout>

## Where the rows come from, and what loads back [#where-the-rows-come-from-and-what-loads-back]

The migration takes already-parsed `LegacyEntry` rows rather than the Studio's own `SavedStrategy`: that type lives one layer up, in the crate that owns the JSON schema and its back-compat contract. `crates/vike-studio/src/saved.rs`'s `SavedStrategy::legacy_entry` is the one conversion, kept beside the schema so the rule that a row with no `source` key is Rhai has exactly one authority. This page names no menu item or command, because its authority names none; the Studio side is on [Saved strategies and workspace](/docs/trader/gui/studio/saved-and-workspace).

`migrate.rs` pins both round trips end to end: a migrated Rhai row is found by `load_rhai_strategies`, compiles with no diagnostic and reports its source verbatim; a migrated native row loads as a native folder, and `resolve_preset` for `buy_hold` / `hold-2` hands back `size` as the integer `2` and `symbol` as the string `BTCUSDT`, and builds the strategy it presets.


# The order vocabulary (/docs/trader/scripting/order-vocabulary)



A script never touches a broker. `crates/vike-script/src/ctx.rs` describes the arrangement in its
header: `ScriptCtx` is the shared, lock-guarded state the engine's host functions read and
mutate, owned by the strategy through `SharedCtx = Arc<RwLock<ScriptCtx>>` and never a borrowed
`&mut B`. Each Rhai closure registered onto the engine holds a cloned `Arc`, so it can push an
`Intent` without borrowing the strategy itself. The order verbs therefore *record*; the strategy
drains what was recorded into real orders once the hook returns.

## The two intents [#the-two-intents]

`Intent` is the whole order vocabulary, and it is pure data — one enum with two variants:

```rust
pub enum Intent {
    Market { side: i32, qty: f64 },
    Limit { side: i32, qty: f64, price: f64 },
}
```

Its doc calls it one order-verb call recorded by a Rhai script during a bar's evaluation, with no
broker or strategy wiring of its own. Four host functions produce them, registered by `engine.rs`'s
`register_verbs`:

| call                      | records                                        |
| ------------------------- | ---------------------------------------------- |
| `buy(qty)`                | `Market { side: 1, qty }`                      |
| `sell(qty)`               | `Market { side: -1, qty }`                     |
| `market(side, qty)`       | `Market { side, qty }` — `side` is `1` or `-1` |
| `limit(side, qty, price)` | `Limit { side, qty, price }`                   |

`side` arrives from the script as a Rhai integer and is cast to the `i32` the intent carries. There
is no cancel, modify or bracket verb in this vocabulary: the enum has these two variants, and the
seam is the single-symbol MVP that `sym()`'s doc describes.

## What the reads see [#what-the-reads-see]

The context's read fields are snapshotted before each hook evaluation — `cur_bar`, `position`,
`price`, `equity`, `index`, `now` — and `register_reads` exposes each as a zero-argument getter:
`close()`, `open()`, `high()`, `low()` and `volume()` read `cur_bar`; `position()`, `price()` and
`equity()` return `f64`; `index()` and `now()` return `i64`. `run_hook` in `strategy.rs` fills
them from the broker: `equity()`, `index()` and `now()` on every call, `position()` and `price()`
only when there is a symbol to ask about. The doc gives the reason: before the first bar arrives —
inside `on_start` — the symbol is empty, and a real `SimBroker`/`LiveBroker` panics on an unknown
symbol, which the strategy's own fail-safe does not catch. So a pre-trade `on_start` reads
`position()` and `price()` at their prior value, `0.0` on the very first call.

The symbol itself comes from the current bar's tag (`Bar::symbol`), resolved by `sym()`; this is
the single-symbol MVP, and `Strategy::on_bar` sets `cur_bar` fresh every bar.

## The rest of the context [#the-rest-of-the-context]

The remaining fields are the engine's, not the script's, but they explain behaviour a script
author will observe:

* `indicators` — the streaming indicator cache, fed once per bar on reference, keyed on the
  instance's real identity `"<name>:<coerced params>"`, e.g. `"sma:[20.0]"`. `sma(5)` and `sma(30)`
  are two instances; `sma()` and `sma(20)` are one, because the registry default coerces to the same
  slice.
* `user_indicators` — the user-written ones, held concrete rather than boxed beside the built-ins,
  because a per-bar fault has to be readable back out and `Indicator` has no downcast. Keyed on
  `"<name>:<call-site args>"`, the same identity-not-spelling rule, so every output line of one
  indicator shares one entry and one feed.
* `fed_this_bar` — the set of keys already advanced this bar, cleared by `Strategy::on_bar` before
  it runs the `on_bar` hook. `on_start` and `on_stop` run their hooks without touching it.
* `intents` — the output, a `Vec<Intent>` in push order.
* `overrides` and `params_seen` — the sweepable knobs: `overrides` is injected before compile's
  one-time top-level run, and `param()` records each `(name, default)` into `params_seen`, first
  seen wins. Neither is touched by compile's intent/indicator clear, because a swept value must
  persist and discovery reads `params_seen` after compile.

## From intent to order [#from-intent-to-order]

`run_hook` is where the vocabulary meets the broker. It snapshots the reads, clears `intents`,
calls the named zero-argument hook, and then takes the recorded intents and submits them in order:
`Intent::Market { side, qty }` becomes `broker.submit_market(&sym, side, qty)` and
`Intent::Limit { side, qty, price }` becomes `broker.submit_limit(&sym, side, qty, price)`. If the
hook errors, the intents it recorded before the error are discarded and nothing is submitted that
bar — the fail-safe [Writing a strategy](/docs/trader/scripting/writing-a-strategy) describes.

<Callout title="A script holds no cross-bar state of its own">
  `strategy.rs`'s header states the invariant: scripts hold no cross-bar mutable state — all state
  is host-side, the broker's `position()` plus the indicator caches in `ScriptCtx`. A hook body's
  `let`-declared locals live only for that one call. The idiomatic loop is therefore to read the
  position, compute a target, and trade the difference, which is how the shipped `sma_cross`
  example is written. Script-managed persistent state is named there as a follow-up, not a feature.
</Callout>

`on_fill` is a no-op in this tier: the strategy impl's own comment says a script observes its
resulting position via `position()`, not a dedicated fill callback. Fills reach the script the
next time a hook snapshots the broker.

The [cheatsheet](/docs/trader/scripting/cheatsheet) lists every read and verb beside the indicator
forms; [The engine](/docs/trader/scripting/the-engine) is where they are registered.


# Presets (/docs/trader/scripting/presets)



A preset is a named parameter set belonging to exactly one strategy: `<strategy>/<preset>.toml`,
flat beside the entry file or under `presets/`. `crates/vike-studio-core/src/user_strategies/preset.rs`
is the resolver — the header calls it the half that was missing while `Preset` was a type nothing
ran — and its whole job is turning that file into the params a strategy is constructed with without
silently doing nothing.

## A preset is the params table [#a-preset-is-the-params-table]

The shipped `sma_cross/fast.toml` (`crates/vike-cli/src/cmd/init/content.rs`'s `PRESET_SMA_FAST`):

```toml
# Preset: fast — a short-horizon sma_cross, for intraday bars (1m–15m).
fast = 5.0
slow = 15.0
qty = 1.0
```

The keys are flat: they are the keys a profile's `[strategy.params]` receives one for one.
`load.rs`'s `check_preset_shape` enforces that at scan time and refuses two shapes that would
otherwise be accepted and then quietly do nothing. A `[params]` wrapper — `{ params = { fast = 5 } }`
— merged into `[strategy.params]` gives the strategy one key called `params` that no reader looks
at, so every knob silently keeps its default, the worst outcome available because the user did
everything else right; silently unwrapping it instead would make two shapes legal and pick between
them by an invisible rule. And a `src` key is the strategy's *source*, not a knob: allowing it would
let a params file smuggle a whole script past `--script`. Only the exact wrapper shape is refused,
so a legitimately nested knob such as the `[venues]` table `funding_carry` reads is untouched.
Preset names are matched case-insensitively (`fast.toml` and `Fast.toml` are one file on Windows
and macOS), and the flat position wins a clash with `presets/`, the loser reported as
`ShadowedPreset`.

## Two roads to one destination [#two-roads-to-one-destination]

There is exactly one destination: a TOML table, the same one a profile's `[strategy.params]`
carries and the harness registry's `strategy_by_name` hands to each strategy's `from_params`
reader. The header is explicit that the two `StrategyBody` kinds reach it differently, and that
pretending otherwise is how a preset would silently do nothing.

**A built-in strategy takes the table whole.** `StrategySpec::Native { name, params }` *is* the
construction call, so every key survives with its TOML type — `size = 3` an integer,
`symbol = "BTCUSDT"` a string, a nested table a table.

**A Rhai script can only receive numbers.** Its knobs are `param(name, default)` calls, and
`RhaiStrategy::compile_with_params` bakes an `IndexMap<String, f64>` into the script scope — the
same lane a `[sweep]` grid point uses. A string or bool in a preset for a Rhai strategy has
nowhere to go.

<Callout type="warn" title="The Rhai type gap is reported, not swallowed">
  The harness's `rhai_overrides` drops a non-numeric param in silence — the lenient convention for a
  table somebody typed into a profile. The header calls that the wrong answer for a preset, whose
  whole promise is "these values, applied": a user who wrote `symbol = "BTCUSDT"` in a preset for a
  Rhai script must be told it cannot arrive. `PresetRun::dropped` carries those key names, and a
  caller must surface them.
</Callout>

## The resolution [#the-resolution]

`resolve_preset(report, strategy, preset)` resolves against an already-scanned `LoadReport` — the
module reads no filesystem — matching the strategy case-insensitively across both trees, so a
preset for a built-in under `strategies/rust/buy_hold/` is found exactly as a Rhai one is. Both
errors name what *was* found, because the question a person is asking is "then what should I have
typed": `UnknownStrategy` lists every strategy that did load (an absent name is how a user discovers
their folder failed to load; the reason is a diagnostic in the same report), and `UnknownPreset`
lists the presets the strategy does have.

The result is a `PresetRun` — deliberately not a boxed strategy, because a caller usually wants
to show the resolution before or instead of building, and a sweep builds one strategy per grid
point from the same resolution:

* `spec` — the `StrategySpec` to construct: Native carries the preset's table verbatim; Rhai
  carries the script source, with the params riding separately.
* `overrides` — the `(name, f64)` pairs for the Rhai path, in the table's own sorted order so two
  runs of one preset produce identical lists. Always empty for a built-in.
* `dropped` — the keys that could not be carried. Always empty for a built-in.

`PresetRun::build` constructs the strategy through `run.rs`'s `build_strategy_with`, the same call
a Run makes, so "the preset resolved" and "the preset runs" are one claim; `is_lossless()` is the
one-line test a caller gates its warning on.

## The typo a numeric key can hide [#the-typo-a-numeric-key-can-hide]

`split_numeric` accepts a TOML float or integer and names everything else, but it cannot see the
dangerous case: `fastt = 5.0` is perfectly good TOML and perfectly numeric, so it reaches the
engine, matches no `param(...)` call, and the run silently uses the default — a result for a
configuration nobody asked for. `unread_keys` catches it on the Rhai path, and only there: a script
declares its knobs by calling `param()`, and `vike_script::discover_params` runs the top level to
collect them, so any override key the script never declares joins `dropped`. A built-in strategy
has no such declaration — the registry has no param spec — so its keys cannot be checked, and
`UserStrategy::run_with` deliberately does not pretend to. A script that fails to compile yields no
declared set, and one whose top-level run calls `param()` nowhere yields an empty one; either way
the answer is "cannot tell", so nothing is flagged rather than everything. The empty case is
deliberate — `discover_params` runs only the top level, so a script whose knobs are declared inside
a hook body would otherwise have every key false-flagged.

## Presets on the command line [#presets-on-the-command-line]

`vike-cli backtest --preset <p.toml>` reads a preset file locally and merges its keys into the
shipped profile's `[strategy.params]`, last-wins, before `--script` injects the source. The verb's
header explains why the preset is a local path rather than a name in the profile: only the profile
text crosses the wire, and the server is typically another machine, so a `[strategy] preset = "fast"`
field would resolve against the server's `user_data/`, not the author's. `merge_preset_params`
restates the same two refusals — the `[params]` wrapper and the `src` key — in the CLI crate,
because that crate cannot depend on `vike-studio-core` without dragging DataFusion into a laptop
binary. See [vike-cli backtest](/docs/trader/reference/cli/research/backtest).

On the live daemon the same posture applies in the script's vocabulary: under `[strategy] rhai = "<path>"`,
`crates/vike-tradehub/src/config.rs`'s `DaemonProfile::validate` refuses a non-numeric
`[strategy.params]` value at load — `param` takes an `f64`, so a quoted number configures nothing —
and `resolve_script` refuses any key the script's top level never passes to `param(…)`, so a
preset's knobs that survive resolution here are the ones that would mount there — except in the
knob-less case above, where the daemon has no such exemption and refuses outright the keys
`unread_keys` passes over.

What a preset configures is on [Writing a strategy](/docs/trader/scripting/writing-a-strategy) for a
script and under [the strategy templates](/docs/trader/strategies/templates/buy-hold) for a built-in;
where the files live is [User strategies](/docs/trader/scripting/user-strategies); the profile they
merge into is [Run profiles](/docs/trader/backtesting/run-profiles), and the grid that varies the same knobs is
[Sweeps](/docs/trader/backtesting/sweeps).


# The engine (/docs/trader/scripting/the-engine)



Every mounted strategy script gets its own `rhai::Engine`, built once by `build_engine` in
`crates/vike-script/src/engine.rs`. Its doc states the shape: bounded resource limits — opt-in on
a plain `rhai::Engine::new()`, whose `Limits::new()` leaves operations, strings, arrays and maps
unlimited and caps only call and expression depth — so a runaway or malicious script cannot hang
the strategy loop, plus the full read/verb/indicator host-function surface registered against the
strategy's shared context. It is called once per mounted strategy
(`RhaiStrategy::compile_with_params` and `discover_params`), never per bar; `run_hook` reuses the
stored engine, and rhai's function map is an identity-hashed table with a per-call-site cache, so
the size of the registered set changes nothing on the bar path.

## The limits [#the-limits]

`build_engine` sets `set_max_operations(2_000_000)`, `set_max_call_levels(64)`,
`set_max_string_size(8 * 1024)`, `set_max_array_size(4096)` and `set_max_map_size(4096)`. They
are per hook invocation — each `call_fn` gets a fresh operation counter — not cumulative across
the strategy's lifetime. A user indicator's engine (`indicator.rs`'s `indicator_engine`) mirrors
the same five numbers, so one runaway script is bounded the same way whichever seam loaded it.
What a script sees when it hits one is [Limits](/docs/trader/scripting/limits).

## What a script may not do [#what-a-script-may-not-do]

<Callout type="warn" title="import is refused, and that line is load-bearing">
  `build_engine`'s doc calls `set_module_resolver` the load-bearing line in the function. A default
  `rhai::Engine` installs a `FileModuleResolver` rooted at the process's working directory, so
  `import "…" as m;` reads a file from disk — and the daemon's working directory is `<project>`, the
  operator's settings tree with the credential store in it. It is a capability nobody granted: it
  appears in no registration list because it is the interpreter's default, exactly the surface an
  allow-list cannot see. `DummyModuleResolver` makes every `import` a refusal, and
  `crates/vike-script/tests/module_import_refused.rs` gates both engines.
  The same doc records why that matters beyond tidiness: the verdict that lets a script mount live
  would be reopened by network, filesystem, process or credential access from a script, and it rests
  on the live engine surface being exactly the backtest one — so closing `import` keeps a premise that
  verdict already relies on rather than narrowing a decided grant.
</Callout>

`print` and `debug` are redirected, not removed. `redirect_script_output` points them at the
`tracing` facade under the target `vike_script` — `print` at INFO, `debug` at DEBUG — because
`rhai::Engine::new()` wires both to `println!`, and this crate is embedded in binaries whose
stdout is a protocol: `vike-cli mcp` speaks newline-JSON-RPC over stdout and compiles
caller-supplied scripts in-process, and `vike-tradehub` keeps its stdout protocol-only. The doc's
second warning is about volume: a `print` inside `on_bar` fires once per bar either way, but at
INFO it reaches the file layer, which defaults to `trace` and rolls daily, so a chatty script over a
long backtest writes into `<project>/settings/state/logs`. `VIKE_LOG_FILE_LEVEL` is the knob.

## What is registered [#what-is-registered]

Four families, in registration order.

**Reads** (`register_reads`): `close`, `open`, `high`, `low`, `volume`, `position`, `price`,
`equity` return `f64`; `index` and `now` return `i64`. Each is a pure getter over one field of the
[script context](/docs/trader/scripting/order-vocabulary).

**Verbs** (`register_verbs`): `market(side, qty)`, `buy(qty)`, `sell(qty)`, `limit(side, qty, price)`.
Each pushes an `Intent`; the script never sees the context directly.

**Indicators** (`register_indicators`), then the installed user indicators. `register_fn` replaces,
so being registered after the built-ins is what would let a user file take over a built-in name —
the hazard `user_indicator_conflict` and `user_line_conflict` refuse at load. An explicitly passed
indicator wins over the installed set for the same reason one step later: `compile_with_indicators`
registers that set after `build_engine` has returned.

**`param(name, default)`**: records `(name, default)` for discovery, first seen wins, and returns
the injected override if present, else the default. The default is a `Dynamic`, not an `f64`:
registered as `f64` it accepted `param("fast", 5.0)` and rejected `param("fast", 5)` — a knob that
worked or did not depending on whether the author typed a decimal point.

`HOST_FN_NAMES` lists every non-indicator name above, and its doc says it exists for the indicator
bridge rather than for documentation: `register_fn` replaces a same-name registration rather than
erroring, so a registry indicator that happened to be called `close` would silently shadow
`close()` for every script. `exclusion` refuses to bind such a name; nothing collides today.

## Which indicators bind [#which-indicators-bind]

`RHAI_INDICATORS` is the exact set `register_indicators` binds as bare names, derived at run time
from `vike_indicators::registry()` minus every entry `unbound_reason` rejects, so the advertisement
and the binding cannot drift. The count is deliberately not stated; `RHAI_INDICATORS.len()` is the
answer. `exclusion` carries the rules, each a silent-wrong-answer hazard rather than taste:

1. **Not callable from Rhai.** `var` (Variance) is a reserved word, so `var(20)` fails at parse
   time. The check compiles `<name>()` on a throwaway raw engine, so a future rhai release that
   reserves another word cannot leave an advertised-but-uncallable name behind.
2. **Collides with a host function** — `HOST_FN_NAMES`.
3. **`batch_only`.** `ichimoku`, `zigzag` and `williams_fractal` read future bars, so their
   streamed value is revised later by the batch path — a backtest-vs-chart divergence that shows
   up as a wrong number, never an error.
4. **More parameters than the bridge expresses.** Forms go up to `MAX_INDICATOR_ARITY`, which
   is 3; binding a deeper one would pin its tail parameters to their defaults, knobs that look
   present and are not. Today that is `kst`, with 9.
5. **Multi-output under its bare name, when line 0 is not the namesake line.** `bollinger`,
   `donchian`, `keltner`, `envelopes` and `std_error_bands` all declare `upper, mid, lower`, so
   `bollinger(20)` would return the upper band to an author who read it as the middle. The doc
   records that this rule narrowed: it used to refuse every multi-output indicator, which refused
   `macd`, `adx`, `fisher`, `kst`, `kvo` and `supertrend` for a hazard that did not apply (their
   line 0 is their own name) while leaving Bollinger's middle band unreachable by any spelling.

Every line of every multi-output indicator is reachable through a per-line accessor,
`line_fn_name(indicator, line)` = `<indicator>_<line>`: `bollinger_mid`, `macd_signal`,
`adx_plus_di`, `stochastic_k`. `sanitize_line` lowercases and replaces every character a Rhai
identifier cannot carry with `_`, which exists for one family — `stochastic`, `stochf` and
`stochrsi` name their lines `%K` and `%D`. Accessors obey the same `batch_only` and arity rules as
the bare name. `is_callable` — bare name *or* at least one accessor — is the question an
advertising surface should ask, since `bollinger` is absent from `RHAI_INDICATORS` while
`bollinger_mid(20)` is callable; `unbound_reason`'s message for the bare name names the accessor
that works.

## The call shape [#the-call-shape]

Each bound name gets one form per argument count, from zero up to its parameter count, capped
at 3. `name()` takes every registry default — the only spelling for the parameterless indicators
such as the candlestick patterns, `vwap` and `obv`, and the only way to reach a fractional default:
`psar`'s `step` defaults to `0.02` with a `[0.001, 0.5]` range, which no integer argument
expresses. Arguments beyond the parameter count are not registered, so `doji(5)` is a
function-not-found rather than an argument silently discarded, while parameters left off the end
take their defaults.

Arguments are `rhai::Dynamic`, so ints and floats both resolve — `alma(9, 0.85, 6)` is the
natural spelling of an integer period, a float offset and an integer sigma. A non-numeric argument
is a raised error from `bad_arg`, not a NaN, because NaN is exactly what an indicator returns while
warming up: every shipped template opens `if h.is_nan() { return; }`, so `sma("20")` returning NaN
would make a strategy return on every bar forever, looking like a warm-up that never finishes. An
error is loud in the way the strategy already handles — it counts consecutive failures and
self-disables.

`indicator_value` is the bar path: it looks up or lazily builds the streaming instance cached
under `"<name>:<coerced params>"`, feeds it the current bar at most once per bar, and returns the
requested line. Because the key is the coerced parameters, `sma()` and `sma(20)` are one instance
sharing one feed, and every line of one indicator shares one instance too: `bollinger_upper(20)`
and `bollinger_mid(20)` in one bar feed Bollinger once and read two entries of the same output
vector.


# User strategies (/docs/trader/scripting/user-strategies)



`crates/vike-studio-core/src/user_strategies/mod.rs` opens with the rule the whole module exists
for: **a user's strategies are files**, not rows in a blob. It is the loader for
`<project>/user_data/strategies/`, the resolver that turns one of its presets into constructed
params, and the one-time migration off the Studio's `studio_strategies.json`. The directory it
scans is the user-content root `vike_model::state_path::PROJECT_USER_DATA_DIR` defines.

## Why files [#why-files]

The header records what the JSON array denied a person: a script in it could not be opened in an
editor, diffed, committed, copied to another machine or sent to somebody. Two properties made it
lossy rather than inconvenient. One corrupt byte lost the library, because the blob loader
answered a parse failure with an empty list — right for a window layout, wrong for the only copy
of somebody's work — while one file per strategy costs exactly the strategy the bad byte is in.
And it was filed under the wrong owner, at the hist store's root, beside re-downloadable market
data whose lifecycle is "delete it and re-ingest". [Migration](/docs/trader/scripting/migration) is
the move.

## The layout [#the-layout]

```text
user_data/strategies/rhai/<name>/<name>.rhai      the ENTRY file — its stem IS the strategy name
user_data/strategies/rhai/<name>/*.toml           presets, flat beside the entry
user_data/strategies/rhai/<name>/presets/*.toml   …or filed, for the user whose sweep left forty
user_data/strategies/rust/<builtin>/*.toml        presets for a strategy whose code is in the BINARY
```

Four rules the loader depends on. The entry file matches its folder, so a folder holding several
scripts is never ambiguous — the others are helpers, read by nothing here. A `.toml` beside the
entry is a preset for that strategy, so `rm -r <name>/` removes the whole thing and two strategies'
presets can never be confused. A preset *is* the params table, flat. And a folder under `rust/`
needs no entry file when its name is a built-in strategy: the code is in the binary, resolved by
name through the harness registry's `strategy_by_name`, and the folder holds nothing but presets.
`load.rs`'s header admits that treating such a folder as a missing entry file was a real bug the
module used to have, and that `migrate.rs` predicted it.

`state_path.rs`'s `STRATEGIES_SUBDIR` doc gives the reason for the language split: the two have
different lifecycles — a `.rhai` file is read at startup, a `.rs` file must be compiled — and the
tree is artifact first, language second. `user_rust_strategies_dir` is explicit that the `rust/`
tree is meaningful only in a source checkout; on an installed binary it is inert, and that is not
a defect. See [Authoring in Rust](/docs/trader/strategies/authoring-rust).

`vike-cli init` scaffolds the tree with three examples — `sma_cross`, `rsi_meanrev` and `ema_trend`,
each with presets — plus `rust/my_experiment/`. By default it writes only what is absent, so an
edited file is never touched; `--reset` is the one exception, restoring the shipped samples and
overwriting edits to them (a strategy you wrote is not in that table, so nothing here can delete
it) — [vike-cli init](/docs/trader/reference/cli/set-up/init). `VIKE_USER_DATA_DIR` names the root outright and
skips the walk, a separate variable from `VIKE_SETTINGS_DIR` on purpose.

## The scan [#the-scan]

`load_user_strategies(strategies_root)` scans both trees, `rhai/` then `rust/`, into one
`LoadReport`, because a strategy is addressed by name and the two trees share one namespace.
`load_rhai_strategies(root)` is the Rhai tree alone and cannot see the `rust/` presets. Neither
ever fails; every failure is a row. `load.rs`'s header states three decisions that look like
details and are not:

* **An absent root is not an error; an unreadable one is.** A fresh install has no `user_data/`,
  so "nothing there" stays silent; a root that exists and cannot be listed is a permissions bug
  wearing the "not configured yet" answer, and it gets its own `RootUnreadable` row. That is the
  distinction the credential store draws, for the same reason.
* **Every script is compiled during the scan**, through `run.rs`'s `build_strategy` — the same
  call a Run makes — so "it loaded" and "it will run" are one claim rather than a failure moved to
  the moment the user presses Run.
* **A `rust/` folder named after a built-in needs no entry file.** `StrategyBody` is the type that
  says which kind a loaded folder is: `Rhai { entry, source }`, proven to compile, or `Native`,
  whose `UserStrategy::name` is the registry's own spelling however the folder was cased.

Folders are sorted by name before anything loads, dot-entries are skipped as tool droppings, and
names are claimed case-folded across both trees. A folder that loaded nothing claims no name, so a
later folder of the same name is a real strategy rather than a duplicate of a failure.

## The diagnostics [#the-diagnostics]

`LoadDiagnostic` has one variant per mistake a person actually makes, each carrying the path and
the fix, and `Severity` draws the line at "did the user lose a strategy": `BadPreset` and
`ShadowedPreset` are warnings that leave the strategy runnable, everything else is an error.

| variant                 | what happened                                                                                                                                                          |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RootUnreadable`        | the root exists but cannot be listed — fix its permissions                                                                                                             |
| `MissingEntry`          | a `rhai/` folder holds no `<name>.rhai`; the message lists the `.rhai` files it did find, so a misnaming explains itself                                               |
| `NativePresetsMisfiled` | presets for a built-in filed under `rhai/`; the fix is to move the folder to `strategies/rust/`, which is why this is its own row rather than a `MissingEntry` wording |
| `UnregisteredNative`    | a `rust/` folder holding presets whose name is no built-in — they can reach nothing                                                                                    |
| `UnreadableEntry`       | the entry file is there but is not readable as UTF-8 text                                                                                                              |
| `CompileFailed`         | `RhaiStrategy::compile` rejected it, via `build_strategy`; the script author's message verbatim                                                                        |
| `BadPreset`             | a `.toml` could not be read, parsed or used as a params table; the strategy loads without it                                                                           |
| `ShadowedPreset`        | the same preset name flat and under `presets/`; the flat one wins as the documented primary position                                                                   |
| `DuplicateName`         | two folders resolve to one name — `SmaCross/` and `smacross/`, which coexist only on Linux, or `rhai/grid/` beside `rust/grid/`; the `rhai/` claim wins                |
| `StrayScript`           | a script directly in a tree's root; the message names the folder it belongs in                                                                                         |

<Callout title="A rust/ folder with no presets and no registry name is not reported">
  `load_rust_folder` is the one place the loader returns nothing without a diagnostic, deliberately:
  a folder naming no built-in and holding no presets is a source-checkout Rust strategy that has not
  been registered yet — the shipped `my_experiment/` template's exact state — and nothing reads that
  tree at runtime. The moment it holds presets, they are addressed by a name that resolves to
  nothing, and that is a loss the `UnregisteredNative` row reports.
</Callout>

## The compile log [#the-compile-log]

`render_compile_log(report, stamp)` renders one scan as the text a caller appends to
`user_data/logs/compile.log`: one `ok` line per loaded strategy naming its entry file (or
`built-in`) and its presets, one `ERROR`/`WARN` line per diagnostic, and a summary count. Passes are
logged too, because a user debugging "why is my strategy not in the list" needs to see the ones
that are — an absent name is the answer. `stamp` is caller-supplied and the function reads no
clock, one stamp per line so `grep <name>` still answers "when". The module performs no logging and
opens no log file; the composition root decides where the text goes. `user_logs_dir`'s doc adds
that `$VIKE_LOG_DIR` must not redirect this folder, because that variable moves the app log.

A loaded strategy's `spec()` is the bridge to a Run — the Rhai source, or the registry name with
an empty params table — and applying one of its presets is [Presets](/docs/trader/scripting/presets).
The Studio's own restorable state, and the blob this tree replaces, are on
[Saved strategies and workspace](/docs/trader/gui/studio/saved-and-workspace).


# Writing a strategy (/docs/trader/scripting/writing-a-strategy)



`RhaiStrategy<B>` in `crates/vike-script/src/strategy.rs` is the binding that plugs the script
context and the registered host functions into the real strategy seam every engine drives
strategies through. A script is compiled once into a `RhaiStrategy`, holds its own
resource-limited engine, its AST and its context, and from then on is a `Strategy<B>` like any
compiled one.

## A complete script [#a-complete-script]

This is `sma_cross.rhai`, one of the three examples `vike-cli init` scaffolds
(`crates/vike-cli/src/cmd/init/content.rs`'s `SMA_CROSS_RHAI`), trimmed of nothing but comments:

```rust
let fast = param("fast", 10.0);
let slow = param("slow", 30.0);
let qty  = param("qty", 1.0);

fn on_bar() {
    let f = sma(fast.to_int());
    let s = sma(slow.to_int());

    if s.is_nan() { return; }

    let target = if f > s { qty } else { -qty };
    let delta  = target - position();
    if delta >  1e-9 { market( 1,  delta); }
    if delta < -1e-9 { market(-1, -delta); }
}
```

Three things in it are rules rather than style, and each is argued below: the knobs are declared at
the top level, both indicators are read on the first lines of `on_bar` before any branch, and the
script trades the difference between a target and `position()` rather than remembering anything
itself.

## Hooks [#hooks]

`compile_with_indicators` detects which of `on_start`, `on_bar` and `on_stop` the script defines
by walking `AST::iter_functions` for a zero-argument function of that name. An undefined hook is a
no-op, never a call attempt. `on_fill` is not a script hook at all: the `Strategy` impl leaves it
empty, and a script observes its resulting position through `position()`.

## `param()` and the top level [#param-and-the-top-level]

The `strategy.rs` header's design note is the one thing to carry away: a script's top-level
statements — anything outside a `fn` — run *exactly once*, in `compile`, via
`run_ast_with_scope`, and never again per hook call. That matters because rhai's `call_fn` defaults
to re-evaluating the AST's top level into the scope on every call; with a bare `buy(1.0);` at the
top level, that default silently resubmits an order on every hook call. `run_hook` therefore calls
with `eval_ast(false)`, and whatever the one-time run recorded is discarded — intents, because they
belong to no bar, and any indicator touched at top level, so that a script's first real bar is the
first bar any indicator ever sees rather than a phantom zero-bar sample.

That one-time run is also what makes `param(name, default)` work. `compile_with_params` injects the
overrides *before* the run, so a swept value is baked into the persisted scope and visible for the
strategy's whole lifetime; `param()` records each `(name, default)` first-seen, and
`discover_params` compiles a script with no overrides and returns those pairs in declaration order
— the sweep UI's view of the knobs. Declare knobs at the top level; a `param()` call made only
inside a hook body is invisible to that run. A top-level `const` or `let` is visible inside every
`fn` because the one-time run populates a scope that `run_hook` clones fresh for each call — which
is also why a hook's own locals never accumulate across bars.

## Indicators, every bar [#indicators-every-bar]

The `lib.rs` contract's second half: call an indicator unconditionally on every `on_bar`
invocation. An indicator advances only when the script calls it, through the fed-once-per-bar
cache in `engine.rs`'s `indicator_value`, so a call behind an `if` skips the bars where the branch
was not taken and silently stops being an average of the last N. Read every indicator into a local
at the top of `on_bar`, guard the warm-up NaN, then branch. Which names are callable, and in what
forms, is [The engine](/docs/trader/scripting/the-engine).

<Callout type="warn" title="A misspelled indicator compiles, and looks like no signal">
  Rhai resolves a function name when the line runs, not at compile. `RHAI_INDICATORS`'s doc gives
  the consequence: a script calling an unbound name hits a function-not-found error every bar and
  self-disables after the strategy's consecutive-error cap — mounted, and never trading. `vike-cli indicators`
  prints the names that will not do this; a name it does not print is not callable.
</Callout>

## The fail-safe [#the-fail-safe]

`run_hook`'s contract: a script error is logged at `warn` and swallowed — no panic, and no orders
that bar, since the intents recorded before the error are discarded. After 10 consecutive errors
the strategy self-disables for the rest of its life, logging at `error`, rather than risk a wedged
script hammering the engine; a successful hook call resets the counter. A wrong-typed indicator
argument (`sma("20")`) is deliberately one of these errors rather than a NaN, so a typo cannot
look like a warm-up that never finishes. Decision record 0024 counts this as one of its rails:
below the panic level, `run_hook` already fails safe on script errors, and a panicking handler
rides the core's per-dispatch `catch_unwind` like any compiled strategy.

## Running it [#running-it]

**In a backtest.** The harness registry's `rhai` arm (`crates/vike-backtest/src/harness/registry.rs`'s
`strategy_by_name`) compiles an inline `src` param — required; a missing one is a validation error
at load, never a silent no-op — and every other numeric param is a `param()` override, the same
knobs a `[sweep]` varies. `vike-cli backtest --script <s.rhai>` reads the file and injects its
source into the shipped profile's `[strategy.params].src`, so the script travels with the request
and the profile stays about the data; `vike-cli backtest --list-params --script <s.rhai>` prints the
knobs offline through `discover_params`, with no profile and no server. See [Running a backtest](/docs/trader/backtesting/running)
and [Sweeps](/docs/trader/backtesting/sweeps).

**Live.** `[strategy] rhai = "<path>"` in a `vike-tradehub` profile. `crates/vike-tradehub/src/config.rs`'s
`resolve_script` reads the file at resolve time, logs the path and the sha256 of the source actually
compiled at INFO — the journal's answer to "which code traded", robust to the file being edited
between restarts — and compiles it through the same `build_engine` the backtest uses, registering
no host function of its own. Under that key every `[strategy.params]` entry is a `param()`
override, and the daemon's no-silently-ignored-key posture applies in the script's vocabulary: a
non-numeric value is refused, and so is a key the script's top level never passes to `param(…)`.
That scripts mount live at all is a recorded architecture verdict, and its rails are the ones
above; the daemon is
[vike-tradehub](/docs/trader/reference/binaries/vike-tradehub).

**Validated by an agent.** `vike-cli mcp`'s `validate_strategy` tool goes through
`discover_params` — the broker-free public compile path, the same error surface as mounting — and
answers a bad script with `ok: false` and the error, never a tool error.

The [Studio editor](/docs/trader/gui/studio/editor) is where the same script is edited and run in the
app; [User strategies](/docs/trader/scripting/user-strategies) is where the file lives; the
[from-scratch tutorial](/docs/trader/tutorials/rhai-strategy-from-scratch) walks one end to end.


# Writing an indicator (/docs/trader/scripting/writing-an-indicator)



`crates/vike-script/src/indicator.rs` opens by naming the gap it fills: the indicator binding made
every registry indicator *callable* from a script, but a plain Rhai function has nowhere to keep
state between bars and no guarantee about how often it is called — and an indicator is exactly the
thing that needs both. `RhaiIndicator` is a user-written file compiled into a real
`vike_indicators::Indicator`.

## The contract [#the-contract]

A file under `user_data/indicators/<name>.rhai` defines, in the header's own listing:

```rust
fn init() { #{ prev: () } }        // OPTIONAL — the state you keep. Default: an empty map.
fn on_bar(bar) { ... }             // REQUIRED — called EXACTLY once per bar, in order.
fn warmup() { 20 }                 // OPTIONAL — bars before the value means anything.
fn outputs() { ["up", "lo"] }      // OPTIONAL — the output LINES. Default: one, named for it.
fn overlay() { true }              // OPTIONAL — draw on the PRICE pane? Default: false.
```

Inside `on_bar`, `this` *is* the state and mutations to it persist (rhai's `bind_this_ptr`), so an
author writes a recurrence the way they would think of one. `bar` is a map of `ts`, `open`,
`high`, `low`, `close` and `volume` — six fields, always present; `bar_map`'s doc says the `Option`
fields `bid`/`ask`/`funding` and `symbol` are deliberately omitted, because a field that is `()`
on most series is a trap dressed as a feature. Returning `()` means "warming up" and reads as NaN,
like a built-in that is not warm yet; `read_scalar` also coerces integers, so a counting indicator
can return `this.n` without a float cast.

The shipped `donchian_high.rhai` (`crates/vike-cli/src/cmd/init/content.rs`'s
`DONCHIAN_HIGH_RHAI`) uses the whole contract:

```rust
let lookback = param("lookback", 20);

fn overlay() { true }
fn init() { #{ highs: [] } }
fn warmup() { lookback - 1 }

fn on_bar(bar) {
    this.highs.push(bar.high);
    if this.highs.len() > lookback { this.highs.remove(0); }
    if this.highs.len() < lookback { return (); }
    let hi = this.highs[0];
    for h in this.highs { if h > hi { hi = h; } }
    hi
}
```

`compile_indicator` runs the top level exactly once, so a top-level `let` is a real knob, and
fails when `on_bar` is missing or takes the wrong number of arguments — a compile-time answer to
what would otherwise be a per-bar function-not-found. `warmup()` is read as a `Dynamic` rather
than an integer, because `param()` returns a float and `lookback - 1` is the natural spelling; it
becomes the trait's `lookback()`, while `lookback_exact()` stays `false` because a user's estimate
of their own recurrence is not something the crate can verify.

## Three properties the shape buys [#three-properties-the-shape-buys]

The header names them, and none is incidental. **Streaming/batch parity holds by construction**:
`vectorize` is the fold of `on_bar` over a fresh instance, so there is one code path rather than two
that must agree bit-for-bit as the built-ins' must. **Streaming is O(1) per bar**, because the
author holds their own state and cost cannot depend on history length. **An indicator cannot
trade**: `indicator_engine` registers no order verbs, no context reads and no other indicators — it
is a plain engine plus the same limits `build_engine` sets, minus the file-backed module resolver,
with `param` as its only host function. A user indicator is a pure function of the bars it was fed
and its own state, which is both a safety boundary and what makes the fold sound.

## `param()`, exactly as in a strategy [#param-exactly-as-in-a-strategy]

`param(name, default)` is the one host function an indicator engine registers, and the design
comment says why: an author who has written a strategy already knows it. The first-seen list of
`param()` calls is the indicator's parameter surface, the equivalent of a built-in's
`IndicatorMeta::params`. A call site's arguments are positional in that order — `my_mean(50)`
sets the first declared knob and leaves the rest at defaults — and `compile_indicator_with` makes
two passes, because the positions are only knowable by running the top level. More arguments than
declared knobs is an error naming the knobs the file has, never a value quietly dropped. Each
distinct argument tuple is its own instance with its own state, built by `RhaiIndicator::compile_with`
re-running the file's top level, so a knob genuinely changes the recurrence.

## Several lines out: `fn outputs()` [#several-lines-out-fn-outputs]

`fn outputs()` returns the ordered line names, and the file then gets the same per-line accessors
a built-in gets, under the same namesake rule for whether the bare name binds — `my_bands_mid()`,
spelled by `line_fn_name`. The header explains why it is a function rather than syntax: `init` and
`warmup` are read through the identical `AST::iter_functions` probe, so the author learns no new
concept. Names only — no render style, which a built-in declares for the chart and nothing would
read here.

`read_values` enforces the return shape. With a declared list, `on_bar` must return exactly that
many values, in order; padding would invent a number and truncating would hide one, so a mismatch
is an error naming both counts. `()` is warm-up on every line at once, and a single line can warm
up alone: `[upper, (), lower]`. Without `outputs()`, the file is single-output *to the value* — one
number out, and an array return of any length refused, including a one-element one, because a file
that declares nothing must behave exactly as it always did. `read_outputs` refuses an empty list,
a non-string entry, and any line `user_line_conflict` rejects, and refuses two lines that sanitise
to one accessor. One more rule is raised at instantiation by `engine.rs`'s `register_user_form`:
`fn outputs()` must not depend on a `param()` knob, because the accessors were registered from the
prototype's list.

## Faults are held, not silently NaN'd [#faults-are-held-not-silently-nand]

`Indicator::on_bar` returns `Vec<f64>` and has no error channel, so a script that throws on bar N
can only be NaN there — and NaN is the warm-up value. The header calls a permanently warming-up
indicator the exact failure the strategy engine's `bad_arg` was written to avoid, so the fault is
recorded in `RhaiIndicator::fault` rather than dropped, and the strategy-side bridge raises it as
a Rhai error where the consecutive-failure cap can stop the strategy.

## On the chart [#on-the-chart]

`user_meta` wraps a compiled prototype as a `&'static IndicatorMeta` whose factory clones it —
the whole seam between "a user wrote a file" and "the chart can plot it"; it leaks, so a binary
calls it once at startup. `overlay()` defaults to `false` — its own pane — because the crate cannot
know the scale of an unlabelled number, and a z-score on the price axis would wreck the price
pane's autofit and take the candles with it. `param_spec` opens `min`/`max` as wide as `f64` goes
rather than guessing a range, and infers `step` from the default: a whole number steps by 1, a
fraction by 0.001.

<Callout type="warn" title="Names a file may not take">
  `user_indicator_conflict` refuses a file stem that is a Rhai reserved word, a host read or verb, a
  built-in indicator's name — even one the engine leaves unbound, such as `bollinger` — or a
  built-in's per-line accessor such as `stochastic_k`. All four are refusals of silent shadowing: the
  user set is registered last and `register_fn` replaces, so `sma.rhai` would answer every `sma(20)`
  on that one machine. The same rules apply to every line an `outputs()` would generate.
</Callout>

The file's stem is its name, and the strategy calls it by that name; how the folder is scanned,
reported and installed is [Loading indicators](/docs/trader/scripting/loading-indicators). The built-in
catalog it sits beside is under [indicators](/docs/trader/indicators/), where the `user` category is the
one it lands in.


# Authoring in Rust (/docs/trader/strategies/authoring-rust)



A native strategy in Vike Trader is a type that implements
[`Strategy`](/docs/trader/strategies) over a broker bound. Choose the bound first, because it is what
the type system uses to document where the strategy can run.

* `impl<B: Broker> Strategy<B>` — PORTABLE. The same type runs in the backtest sweep harness and on
  a live mount unchanged. `Grid`, `DcaAccumulate`, `FundingCapture`, `PairsZScore` and `BuyHold` all
  take it — but the bound is a compile-time property, not a mount permission: `funding_capture` and
  `pairs_zscore` carry a written `LIVE_CAPABLE` reason the daemon refuses at profile load.
* `impl<B: HftBroker> Strategy<B>` — portable, but only over a broker that can resolve a
  strategy-chosen TAG to a resting order and re-price or cancel it in place. `SpreadMaker` and
  `TrailingScalper` take this bound; a plain `Broker`-only engine simply cannot mount them.
* `impl Strategy<SimBroker>` — a deliberate, load-bearing SECOND form, not a backlog item. It is how
  a strategy says "I drive simulator machinery" — a position sizer, the shared-cash gate, an
  attached protective stop, a symbol universe, a bar-count schedule — and the type is what stops it
  being mounted live. See [simulator-only strategies](/docs/trader/strategies/simulator-only).

## What the reference strategies show [#what-the-reference-strategies-show]

`crates/vike-strategy/src/grid_dca.rs` states the constraint that shapes most portable designs: the
portable `Broker` surface is the common denominator of the two stacks, and it deliberately has NO
`cancel` — only the concrete brokers expose one. `Grid` and `DcaAccumulate` are therefore designed
to need none, and the module is honest about the price: a resting limit placed before a halt or a
take-profit cannot be pulled, so `Grid` re-flattens every bar while halted and `DcaAccumulate` may
re-fill a prior cycle's residual entries. Both are documented, bounded-per-cycle behaviours.

`crates/vike-strategy/src/funding_capture.rs` shows the other way out of the same constraint: it
steers a NET position with market deltas and never rests a limit, so it needs no cancel at all.
`crates/vike-strategy/src/pairs.rs` shows a strategy written as a MEASUREMENT INSTRUMENT rather than
a product — its own header says to expect a negative result and that this is the successful outcome.
None of these are parity-gated: they are net-new Rust surface with no Python twin, so what is tested
is behaviour (does the ladder rest, fill, re-arm and stop as designed?) rather than an f64 oracle.

## The parameter reader convention [#the-parameter-reader-convention]

Nearly every `from_params` in the workspace is a READER, not a schema: it reads a `toml::Value`,
ignores what it does not recognise, and falls back to a compiled default for anything missing.
Follow it — but understand what it costs. A lenient reader cannot fail, so an unrecognised key
silently leaves its knob at the default, and so does a recognised key carrying a value of the wrong
type. That is why [the registry](/docs/trader/strategies/the-registry) publishes `PARAM_KEYS` and
`PARAM_ROUTES` for the built-in names, so a live mount can refuse the table instead of trading it.
The exception worth knowing is `vike_mm::SpreadMaker::from_params` (behind the `spread_maker` and
`gueant_maker` registry names): it returns a `Result`, and its eight enum keys — `variance_mode`,
`horizon_mode`, `price_domain`, `spread_model`, `reservation_model`, `spread_source`, `kappa_mode`
and `style` — refuse the table when PRESENT but naming no variant, or carrying a value that is not
a string at all, rather than quietly running a different model than the profile names. Its numeric
keys, and an absent key of any kind, stay lenient like everything else.

## A strategy as a crate [#a-strategy-as-a-crate]

`vike-user-strategies` is the compiled user-strategy HOST. Its `build.rs` scans

```text
<workspace>/user_data/strategies/rust/<name>/
├─ <name>.rs        entry file — the stem MUST equal the folder name
├─ strategy.toml    optional: `live = true` opts into live mounting
└─ *.toml           presets (loaded by vike-studio-core, not by this scan)
```

and generates the registry the crate re-exports — `USER_STRATEGIES`, `USER_LIVE_CAPABLE` and
`user_strategy_by_name`. The built-in registries consult it AFTER every built-in arm, so a user
folder can never shadow a built-in name, and NO framework crate changes when a strategy is added: a
new native strategy is a new folder, nothing else. `VIKE_USER_DATA_DIR` overrides the scanned root
at build time. A folder name must be a lowercase Rust-identifier-safe token, because the generated
module and match arm are built from it, and a malformed folder is a build ERROR naming the path —
silence is how this tier spent months being mistaken for a working mechanism.

The entry file's contract is one function:

```rust
pub fn build<B: vike_model::HftBroker + 'static>(
    params: &toml::Value,
) -> Box<dyn vike_model::Strategy<B> + Send>
```

The separate crate is the load-bearing part. User entry files compile as modules of THAT crate — a
separate compilation unit from the framework's own strategy layer — so they resolve only the
platform's PUBLIC API, reached through its dependencies: `vike-model`, `vike-strategy`,
`vike-indicators` and `toml`. An internals refactor can never break a user strategy, and a user
strategy can never grow a load-bearing dependency on a crate-private detail.

<Callout type="warn" title="Two things the tier does not do for you">
  The in-tree `PARAM_KEYS` and param-gate tables cover the REFERENCE set only. They do not cover user
  strategies, so a typo'd key in your own `build` silently reads as the compiled default. And
  `strategy.toml`'s `live = true` is an explicit opt-in: an absent file or an absent key means
  sim-only, the default-deny posture.
</Callout>

With no `user_data/` — every fresh clone, every CI checkout — the generated registry is EMPTY and
the host crate is inert, answering `None` for every name. The pipeline is still proven on every CI
run through a committed fixture tree. User code compiles only in a source checkout and into the
operator's OWN binary; `user_data/` is gitignored and never enters the repository.

For strategies written as files rather than as Rust, see [scripting](/docs/trader/scripting); for running
what you have written, see [backtesting](/docs/trader/backtesting/running).


# The controller seam (/docs/trader/strategies/controller-seam)



`crates/vike-strategy/src/controller.rs` is the TOP half of a controller-to-executor split. It
carries two things: the `Controller` decision seam — the WHAT, emit a `PositionIntent` or not — and
the `ControllerHarness` that wraps a controller into a plain `Strategy`, the glue that owns the live
[position executors](/docs/trader/strategies/position-executor) and does the HOW.

## Why it is a Strategy, not a parallel runtime [#why-it-is-a-strategy-not-a-parallel-runtime]

`ControllerHarness<C>` implements `Strategy<B>` for any `B: Broker`. It IS a strategy, so it mounts
through the existing strategy seam and runs unchanged on BOTH engines — the live single-writer
runtime over `LiveBroker` and the backtest engine over `SimBroker`. Direct-submit strategies are
untouched; a strategy adopts managed positions by mounting a harness instead of itself. Every order
an executor emits still crosses the SAME `Broker` handle, then the drain, then the `RiskGate`, then
the client, so the harness adds NO authority and cannot bypass the gate. It is additive: no serde
event or wire change, no new command verb — it is composed entirely from the existing `Strategy`
handlers plus the executor.

## What the harness owns [#what-the-harness-owns]

The controller, asked per `(venue, symbol)` whether to open. The active executors, ONE per
`(venue, symbol)` — a `Vec` keyed by the pair, because there are few of them and a linear scan with
deterministic insertion order replays reproducibly, the same rationale the multi-venue paper client
uses. And a post-exit cooldown stamp per pair: the controller may not re-open a pair until
`last_close_ts + cooldown_ms`, with `0` meaning eligible on the very next observation.

Routing is a `venue_map` of `symbol -> venue` alongside a default venue. That is what makes a
CROSS-VENUE controller tradeable from ONE mount: each series is keyed and evaluated under its own
venue, so a controller whose decision needs two venues' data can observe them all. An empty map —
the default — makes the harness byte-identical to a single-venue mount.

## The per-callback flow [#the-per-callback-flow]

On each `on_bar`, `on_quote_tick` or `on_trade_tick` the harness does three things in order.
**Maybe-open**: if there is no active executor for this pair and the cooldown has elapsed, ask
`Controller::evaluate`; on `Some(intent)` spawn an executor and start it, which submits the entry
through the same broker. **Drive**: advance the active executor — its refresh and retry timer, then
the barrier evaluation. **Reap**: when an executor reaches a terminal state, record its outcome if
it has one, stamp the cooldown from its close timestamp, and drop it.

`on_fill` routes the execution to the active executor for the fill's symbol. `on_order_event`
forwards the reject or deny an executor's retry reacts to, BROADCAST to the active executors rather
than routed, because the portable `Broker` surface exposes no client-order-id to route a single
order by; with one executor per pair, and typically one pair per mount, that is exact, and a
non-reject transition is a no-op inside the executor, so the broadcast is harmless.

## The decision seam [#the-decision-seam]

`Controller::evaluate` reads the same market and account view a strategy gets — but through a SHARED
`&B`, so it can call `price`, `bars`, `position` and `now` and yet **structurally cannot submit
orders**, because every `submit_*` verb needs `&mut B`. A controller decides; the executor executes.
It reasons in POSITIONS — it emits a `PositionIntent` carrying side, quantity, entry kind, triple
barrier and the refresh and retry policies — never in raw orders, and it never sees fills. The
harness invokes it only when it is free to open, so an implementation need not re-check the
cooldown or the active-executor condition.

<Callout title="MomentumController is an example, not a recommendation">
  The shipped reference controller compares the current mark to the mark at its PREVIOUS invitation
  and opens long on a move of at least `threshold`, short on the mirror, otherwise declining. The
  first invitation has no reference, so it records the mark and declines. It is deterministic and
  read-only, works identically on the bar path (`price` is the bar close) and the tick path, and the
  harness mounting it is parity-clean.
</Callout>

## Determinism and live re-tune [#determinism-and-live-re-tune]

Every decision is a pure function of the portable broker reads plus the delivered fills and order
events, and ALL time comes from the injected `Broker::now` and each fill's own epoch-millisecond
timestamp — never a wall clock. Both runtimes deliver those identically, so a harness produces the
same fills and outcomes live and in backtest; `crates/vike-backtest/tests/controller_harness.rs` is
the parity gate.

A mounted harness is re-tuned live without unmounting. `StrategyParams::PositionController` carries
a `ControllerParams` bag spanning the two layers a re-tune touches — the harness cooldown, and the
controller's intent template and decision knob. `ControllerHarness::on_params_updated` applies the
cooldown itself and forwards the whole bag to `Controller::apply_params`, which keeps each
controller the sole authority on which knobs it absorbs, then bumps an observable `params_epoch`. A
foreign variant is a no-op and does not bump it. The policy is that a re-tune affects only FUTURE
opens: an in-flight executor keeps its armed intent and barriers and is never torn down or
retroactively resized.

## Harness knobs from a profile [#harness-knobs-from-a-profile]

Mounted through [the registry](/docs/trader/strategies/the-registry), the harness reads `venue`,
`cooldown_ms` and an optional `[strategy.params.venues]` table. Two hazards are declared rather than
hidden: the `venue` fallback is the literal string `sim`, which on a live mount is a tag no venue
answers to — the registry's own echo reports it for exactly that reason — and a `venues` row whose
value is not a string is dropped silently by the reader's `filter_map`, which is why the echo prints
the surviving map rather than the table that was typed.


# Strategies (/docs/trader/strategies)



Vike Trader has ONE strategy trait. `vike_model::strategy`'s `Strategy` is generic over its broker,
and `Broker` is, in that module's own words, "the strategy's window onto whichever execution stack
is running it": in a backtest the simulator core implements `Broker` with direct mutation (the fast
path), while on the live and paper stacks the per-`on_bar` live context implements it by BUFFERING
submissions, drained through the one live path — mint, then `RiskGate`, then the venue client —
after the handler returns. A strategy never learns which of the two it is talking to.

## The write-once rule [#the-write-once-rule]

A strategy written as `impl<B: Broker> Strategy<B>` runs UNCHANGED on both stacks, and the r7 gate
proves the results are bit-identical. A strategy that needs backtest-only power — schedule
registration, weighted or bracket submits, sizers, multi-timeframe reads — is written against the
concrete simulator broker instead, `impl Strategy<SimBroker>`, and the type system then documents
that it is not live-portable. Portability is pinned by COMPILATION rather than by assertion:
`crates/vike-backtest/src/harness/registry.rs`'s `buy_hold_mounts_on_any_broker` is a generic probe
function whose body is type-checked at its definition, so narrowing an impl back to one concrete
broker stops compiling.

Dispatch is generic — monomorphized, never `dyn` — in the backtest hot loop, because a vtable per
verb would regress the roughly 70 ns/bar engine. The live side may box the strategy
(`Box<dyn Strategy<LiveBroker> + Send>`): one virtual call per closed bar is noise there, and a
boxed strategy is itself a `Strategy`, every hook forwarding through one deref.

## The Broker surface [#the-broker-surface]

The verb surface is deliberately the COMMON DENOMINATOR of the two stacks. Order intake is
`submit_market` and `submit_limit`. Reads are `position`, `price`, `equity`, `bars` (closed bars up
to and including the current step, so no look-ahead), `index` and `now` (engine time in epoch
milliseconds). Engine-specific verbs stay inherent methods on the concrete broker types.

Two pre-trade liquidity reads are defaulted, so an engine with no book answers "I don't know".
`quote_vwap` is the volume-weighted price of consuming the resting book best-level-outward; its
`None` means the answer is unavailable or the displayed depth cannot honour the size, and the trait
is explicit that it "is never a price" — a strategy must treat it as *do not trade this size*, not
as *assume the last price*. `depth_within_price` is the sizing half: total displayed size at a
limit price or better, defaulting to `0.0`, which correctly sizes a book-less engine to no trade.

## HftBroker and MultiHftBroker [#hftbroker-and-multihftbroker]

`HftBroker: Broker` adds the tagged-resting-order verbs a market maker needs: `submit_limit_tagged`,
`modify_tagged` (re-price in place, preserving venue queue priority) and `cancel_tagged`, plus a
symbol-less `position` for the single mounted series. A tag is a strategy-chosen stable id naming
one resting order, so a later modify or cancel resolves it without the strategy ever seeing a
client-order-id — the registry belongs to the runtime. `MultiHftBroker: HftBroker` adds exactly one
more read, `position_of(symbol)`, so a correlation-aware maker can assemble the whole inventory
vector.

## The handlers [#the-handlers]

Every handler defaults to a no-op; implement only what the strategy needs. `on_bar`,
`on_quote_tick` and `on_trade_tick` are skipped until `index >= warmup()` — the R2 gate, enforced
by the engines rather than by the trait, and `on_order_book` sits behind it on the live side only:
the backtest engine dispatches a book event before the gate, and a book event does not advance the
index. Beyond `on_start` / `on_bar` / `on_quote_tick` / `on_trade_tick` / `on_order_book` /
`on_schedule` / `on_fill` / `on_stop`, the seam carries the occasional-lane hooks: `on_feed_status`
(the feed disconnected, went stale, or recovered — the "pull my quotes" trigger), `on_mark` (a
reference mark for a series the strategy watches but is not mounted on), `on_reference_quote` (an
L1 touch from a declared leg on a DIFFERENT venue, deliberately a distinct hook so a maker cannot
mistake the reference venue's touch for its own), `on_flow` (per-side flow toxicity), `on_order_event`
(the non-fill order transitions — see [order lifecycle](/docs/trader/concepts/order-lifecycle)) and
`on_params_updated`. None of those occasional-lane hooks is warmup-gated, and the trait says so hook
by hook: a feed death, a reference mark, a foreign-venue touch, a toxicity reading, an order outcome
and a re-tune are market, account or control facts regardless of bar count, so each fires from the
first one that arrives — as `on_fill` always has. `save_state` / `load_state` let a strategy
survive a process restart.

The fill itself is never delivered through `on_order_event`: quantity, price and the resulting
position and equity stay on the richer `on_fill` path, which fires first.

## Where the line runs [#where-the-line-runs]

The recurring proposal — add the missing accessors to `Broker` and every strategy becomes portable
— is answered in the module doc rather than re-derived: what keeps a backtest-only strategy
backtest-only is not a missing READ but a CONCEPT the live stack does not have. Five of them, each
owned by the simulator alone: the position sizer, the shared-cash gate's `weight` argument, the
protective stop attached to the entry, the symbol universe, and the bar-count schedule.

## Parameters [#parameters]

A strategy family's tuning parameters enter the bottom domain crate on exactly one criterion: the
family supports a LIVE re-tune, so its params ride `StrategyParams`, a serde field of the runtime's
journaled command lane. Two families qualify — the Avellaneda–Stoikov maker
([market making](/docs/trader/market-making)) and the
[position controller](/docs/trader/strategies/controller-seam). Every other family keeps its knobs as
plain fields beside its own implementation and reads them from the harness TOML table.

Next: [the registry](/docs/trader/strategies/the-registry) resolves a name to a strategy,
[authoring in Rust](/docs/trader/strategies/authoring-rust) writes a new one, and
[the templates](/docs/trader/strategies/templates/buy-hold) document the ten portable names.


# The position executor (/docs/trader/strategies/position-executor)



`crates/vike-strategy/src/position_executor.rs` drives ONE position's full lifecycle over a portable
`Broker` handle. It is a plain struct with explicit step methods — `start`, `on_bar`, `on_tick`,
`on_fill`, `on_refresh`, `on_order_event`, `cancel` — that a
[controller harness](/docs/trader/strategies/controller-seam) calls from the matching `Strategy` hooks.
It is deliberately NOT a `Strategy` itself. Every order crosses the same `Broker`, so it still
passes the live `RiskGate`, and all time comes from the injected `Broker::now` and each fill's own
epoch-millisecond timestamp — never a wall clock — so the machine is deterministic and runs
bit-identically live and in backtest.

The PARAM types live one layer down, in `vike_model::barrier`: `TripleBarrier` and
`ControllerParams` are pure serde data and are transitively part of the `StrategyParams` payload the
exec ingest lane carries, so they must sit in the bottom domain crate. The state machine imports
them back down.

## States and transitions [#states-and-transitions]

`ExecutorState` has four live labels — `Pending` (created from an intent, nothing submitted),
`EntryWorking` (the entry is in flight or resting, driving refresh and submit-retry), `Open` (the
position is live and the barriers armed) and `Closing` (a barrier fired, the close is in flight) —
and three terminals: `Closed` (flat, records an outcome), `Failed` (the entry never landed, retries
exhausted) and `Canceled` (stopped before any fill).

`start` submits the entry per the intent's `EntryKind`. A FULL entry fill — `on_fill` accumulates
partials — records the VWAP entry price and the entry timestamp, arms the barriers, and opens the
position. The FIRST barrier hit submits a market close; a full flatten produces the terminal outcome.

<Callout type="warn" title="Closing is sticky">
  Once `Closing`, the executor NEVER re-opens or re-evaluates entry or barriers: `on_bar` and
  `on_tick` are no-ops until the close completes, so a late favourable tick cannot flip a closing
  position back to `Open`. A position, once told to flatten, only completes the flatten — a position
  must never be stranded. A rejected CLOSE resubmits the unflattened remainder and STAYS `Closing`.
</Callout>

## The triple barrier [#the-triple-barrier]

Take-profit, stop-loss and trailing are ABSOLUTE PRICE OFFSETS — a positive distance in price units
— from the ENTRY FILL price; the signed barrier price is derived at check time from the entry price
and the position side by `take_profit_price` and `stop_loss_price`. `TripleBarrier::from_bps` is a
caller-side convenience that converts basis points against a reference price, so the stored shape
stays absolute and unit-free. Every leg is optional and defaults to `None`, an un-armed position.

The third leg is the genuinely new one: `time_limit_ms` is a max HOLDING duration, and
`time_barrier_hit` fires once `now >= entry_ts + time_limit_ms`. Nothing else in the workspace
closes a *position* on elapsed time.

Each price barrier is detected through `vike_model::order_fill_price` — the same gap-open
adverse-fill and trailing-ratchet oracle the conditional-order emulator and the backtest engines use
— so a barrier hit behaves identically on both stacks. The stop is evaluated as a reduce-only stop,
the take-profit as a reduce-only limit, and the trailing stop as a trailing order whose extreme is
seeded from the entry price and ratcheted in place on every non-firing check. The `exit_px` on a
`BarrierHit` is DIAGNOSTIC — the oracle's trigger price, or the current mark for a time exit; the
real close fill is whatever the venue or the sim engine resolves when the market close lands.

## Precedence [#precedence]

`evaluate_barriers` returns the FIRST hit under a fixed, deterministic order: **stop-loss, then
trailing, then take-profit, then time**. Within one ambiguous bar the intrabar path is unknown, so
the ADVERSE barriers are assumed to hit first — the same no-look-ahead-optimism convention the
backtest engines apply to protective stops. A wide bar straddling both a stop and the target
therefore resolves to the stop, and a position past its deadline that also crossed a price barrier
reports the price barrier, because a real cross is more specific — and more pessimistic — than the
timeout. `evaluate_barriers_at_price` is the tick twin: a degenerate one-price bar.

## Refresh and retry [#refresh-and-retry]

`on_refresh` is the harness-driven timer step, a no-op outside `EntryWorking`. It resubmits a
backed-off retry that has come due, and reprices a still-resting, wholly-unfilled LIMIT entry to the
current mark once `RefreshPolicy::every_ms` has elapsed since the last submit.

<Callout type="warn" title="Both refresh modes take the same action here">
  The portable `Broker` surface has NEITHER a modify nor a cancel verb — only `submit_*` — so
  `Reprice` and `CancelReplace` both degrade to one fresh `submit_limit`, and the stale resting order
  is abandoned at this layer. Honouring the distinction needs the richer `HftBroker::modify_tagged`
  and `cancel_tagged` verbs and is a later live-only enhancement; the mode is preserved on the intent
  for it.
</Callout>

`on_order_rejected` treats a venue `Rejected` and a `RiskGate` `Denied` identically — the order
never established, so it is retryable. An entry reject with budget remaining schedules a resubmit
`backoff_ms` in the future and terminalizes `Failed` only once `RetryPolicy::max_attempts` is
exhausted; a reject of a partially-filled entry is ignored, because there is no clean single order
to retry. `cancel` terminalizes as `Canceled` before any inventory exists and FLATTENS instead once
the position is even partly open, so an external stop never strands inventory.

## The outcome [#the-outcome]

`ExecutorOutcome` records the barrier that fired, the entry and exit timestamps and prices, the
realized PnL and the round-trip fees. The PnL is folded through the canonical `vike_model::TradeFold`
— the one cost-basis primitive the account, the sim broker, the vector engine and reconciliation
share — rather than a hand-rolled VWAP difference, so it inherits the contract multiplier
(`PositionExecutor::with_multiplier`) and the GROSS convention for free. Fees are reported
SEPARATELY rather than netted silently into the same field; `ExecutorOutcome::net` is the
fee-adjusted figure.


# Simulator-only strategies (/docs/trader/strategies/simulator-only)




A backtest profile can name more strategies than a live daemon can. The portable roster —
[the registry](/docs/trader/strategies/the-registry), one page per name under
[templates](/docs/trader/strategies/templates/buy-hold) — is the set `vike_strategy::strategy_by_name`
resolves anywhere. The **7** names below resolve only inside the
backtester: each reads something only the simulator has (a schedule, a cash gate, an attached stop
the fill loop resolves), and the registry records the reason in its own words so that promoting one
is a factual claim somebody can check rather than an opinion.

The failure this table prevents is a SILENT one: a strategy whose input never arrives mounts
cleanly, logs nothing unusual and simply never submits. That is the class of live-versus-backtest
divergence Vike Trader keeps a ledger of, and it is precisely the class an operator discovers days
later.

## Simulator-only strategies [#simulator-only-strategies]

| Name                            | Why it is simulator-bound                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rotation_top_k`                | simulator-bound: reads the SimBroker `symbols`/`schedule` fields directly                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `bracket_per_symbol`            | simulator-bound: measures the attached protective `stop` the SimBroker fill loop resolves                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `gated_weights`                 | simulator-bound: drives the SimBroker cash-gate `weight` submit argument                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `caps_sizers_mask`              | simulator-bound: drives `crate::sizing::PositionSizer` via SimBroker's raw=false submit path (a 999.0 sentinel size)                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `tick_pair_mse`                 | simulator-bound: measures `SimBroker::position_of` against the engine's latency shadow                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `cheap_catch_updown_fair_value` | lives in THIS crate now (`crate::cheap_np`) and is still listed here, which is not a contradiction: this table's job is to say why a name the backtest registry owns has no PORTABLE row, and promoting this one needs a `PARAM_KEYS` entry that fails a gate in BOTH spellings — `Declared` requires it to submit under `param_gates`' bar/quote feed and it submits only from `on_trade_tick`, while `NotEnumerated` requires it in `vike_tradehub`'s `AS_MAKER_NAMES`. Its previous reason — reaching crate-internal modules — is what the move removed |
| `sport_copy_follower`           | lives in the simulator crate: reads a SIGNAL series the replay harness synthesizes (portable in principle, not yet moved)                                                                                                                                                                                                                                                                                                                                                                                                                                  |

## The script arm [#the-script-arm]

One more name resolves by name and sits on neither roster: the inline-source script arm. It is
listed here because it fails the same question — "can a daemon mount this by NAME?" — for a
different reason, which the registry states:

| Name   | Where it resolves                                                                                                                                                                                                                                                                                                                                                                              |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rhai` | the SCRIPT path, by NAME: this arm compiles a `vike_script::RhaiStrategy` from an inline `src` param and lives in `vike-backtest` (`vike-script` sits at the SAME layer rank as this crate, so this crate cannot name it; the `src` requirement is why it is on no roster). Scripts DO mount live — the daemon takes them by PATH, `[strategy] rhai = "\<path>"`, never through this registry. |

Scripts DO mount live — the daemon takes them by PATH, `[strategy] rhai = "<path>"`, never through
this registry; the [scripting](/docs/trader/scripting) tree covers that route.

## Where this comes from [#where-this-comes-from]

`vike_strategy::registry::SIMULATOR_ONLY` and `SCRIPT_ONLY`, exported as `templates.json` at
every release; the backtester's own registry test asserts the first table is exactly the set of
arms it still owns.


# The portable registry (/docs/trader/strategies/the-registry)



`vike_strategy::registry` resolves a strategy NAME plus a TOML params table to a boxed strategy —
`strategy_by_name<B: HftBroker>` returns `Box<dyn Strategy<B> + Send>` — and the bound is the whole
point. `HftBroker` is a sub-trait of `Broker`, and BOTH the simulator's `SimBroker` and the live
core's `LiveBroker` implement it, so ONE table serves a backtest and a live mount. The box is
`+ Send` because the live core moves the strategy onto its own thread; it unsize-coerces to the
plain `Box<dyn Strategy<SimBroker>>` the simulator's callers want. It did not always live here: the
registry used to be the backtester's, returning a type only the simulator can name, so a daemon
could not run a strategy it had backtested without linking the whole simulator. The fix was the
BOUND, not a new crate.

`PORTABLE_STRATEGIES` is the roster of ten names, kept in step with the resolver's own `match` by
`registry_lists_every_match_arm`. Two further tables state, as DATA rather than prose, what is NOT
here: `SIMULATOR_ONLY` (seven names, each with its written reason — see
[simulator-only strategies](/docs/trader/strategies/simulator-only)) and `SCRIPT_ONLY` (the inline-source
`rhai` arm; [scripts](/docs/trader/scripting) mount live by PATH instead). `capability(name)` folds all
three into the one answer a caller needs before mounting: `Live`, `NotLive(reason)`,
`SimulatorOnly(reason)`, or `Unknown`.

## Resolving is not trading [#resolving-is-not-trading]

`LIVE_CAPABLE` is the per-name live-mount verdict, one row per name with a written reason for every
"no", machine-checked exhaustive against the roster by `live_capable_table_is_exhaustive`. It
exists because the failure mode is a SILENT NO-OP rather than a compile error or a panic: a strategy
whose input never arrives mounts cleanly, logs nothing unusual, and simply never submits. Each "no"
names the missing input — a funding series no live kline lane carries, a second mount leg no mount
surface declares — so flipping a row is a factual claim somebody can check.

## Four refusals over one params table [#four-refusals-over-one-params-table]

A `from_params` reader almost never fails: every one in the workspace but the Avellaneda–Stoikov
maker's ignores what it does not recognise, so `qtyy = 0.005` is not an error — it is `qty` at the
strategy's compiled default. (The one exception is narrow: `vike_mm::SpreadMaker::from_params`,
which both `spread_maker` and `gueant_maker` resolve through, refuses a PRESENT enum key —
`spread_model`, `kappa_mode`, `style` and five siblings — whose value names no variant or is not a
string at all, and the registry raises `RegistryError::BadParams` so the profile stops at load. An
absent key still keeps its default, and its numeric keys stay as lenient as everyone else's.) In a
backtest a knob at its compiled default is a wrong chart; on a mount it is a live order at a size
nobody typed, behind at most the optional `policy.max_notional_per_order` ceiling.
`crates/vike-tradehub/src/config.rs`'s `DaemonProfile::validate_strategy` is the consumer that
refuses, with the SAME strictness on a paper mount as on a live one — a rehearsal that silently ran
different parameters would conceal exactly what it is for.

| Reader             | The case it catches                                                     |
| ------------------ | ----------------------------------------------------------------------- |
| `unknown_params`   | a key no reader reads                                                   |
| `mistyped_params`  | a declared key whose VALUE no reader can take                           |
| `misrouted_params` | a key that is read, well-typed, and then OVERRIDDEN BY THE MOUNT        |
| `unarmable_params` | a whole table that passes all three and still describes no order at all |

<Callout type="warn" title="A wrong type fails as silently as a wrong key">
  Every accessor but the maker's eight enum readers is an `and_then(Value::as_…)`, which yields `None`
  for a value of the wrong type exactly as it does for an absent one, so `.unwrap_or(default)` lands
  on the compiled default either way. `size = "2"` — quoting a number, the most ordinary TOML slip
  there is — mounts `size = 1` just as surely as `sizee = 2` does. Those eight refuse a wrongly-typed
  value outright, and the maker's numeric knobs default as silently as everyone else's. That is why
  `PARAM_KEYS` declares a `ParamType` per key, not just a name.
</Callout>

`PARAM_KEYS` names, per strategy, exactly the keys its reader looks at and the TOML type that reader
accepts; `crates/vike-strategy/tests/param_keys_gate.rs` scans the readers' own source in BOTH
directions, keys and types alike. A row may decline to enumerate — the Avellaneda–Stoikov maker's
roughly 60-key bag does, with a written reason — and its consumer then owes its own stricter rule.
The daemon's is to refuse a `[strategy.params]` table under those two names outright and build the
maker from the profile's own fields instead, which is strictly stronger than key-checking.

## Route keys [#route-keys]

`PARAM_ROUTES` declares which declared keys name a ROUTE — an instrument, a venue, or a
`SYMBOL = "venue"` routing table — rather than a knob of the strategy's own arithmetic. A route key
is the one kind of declared key that can be well-spelled, well-typed, genuinely read and still
configure nothing: `crates/vike-core/src/runtime/strategy_drive.rs`'s `resolve_intent_symbol` and
`resolve_intent_venue` stamp the MOUNT's own pair onto every intent while no mount declares legs,
which is every mount this workspace builds. MEASURED on prod2 before `misrouted_params` existed: a
`buy_hold` profile whose params named a different symbol than the mount loaded, announced the params
symbol, and filled on the mounted one. Multi-leg names are declined rather than judged — their keys
name legs, not this mount's market — and are refused by NAME one step earlier anyway.

## The honest echo [#the-honest-echo]

`resolved_params` re-runs the same reader the mount used and reports what each declared key LANDED
ON. That is not the same as echoing the profile: a reader may clamp, fall back on an unrecognised
string, drop a row, or supply a default the profile never mentions. Printing the operator's own TOML
back is a claim about the operator, and it is false in exactly the case worth logging.

One class stays deliberately un-refused: a key that passes all four checks and is still read by
nobody, because another key in the same table sent the reader down a different branch. Closing that
class is a test rather than a table — `crates/vike-strategy/tests/param_gates.rs`'s
`an_ungated_key_moves_the_strategy` drives every enumerated strategy over a scripted market and
fails, by name, when a declared key does not change the call trace.


# Alpaca (/docs/trader/venues/alpaca)




Alpaca is one of the 14 venues Vike Trader mounts through the shared bridge contract: the
runtime speaks to every venue through one `ExecutionClient` seam, and everything below is rendered
from the capability tables that seam is built on — [`caps_for`](/docs/trader/concepts/execution-client-seam),
`venue_margin_support`, `fee_schedule_for`, `amend_semantics`, `attribution_for` and `venue_tif`
in the Rust workspace — exported as `venues.json` at every release. This page cannot state a
stale capability: each table has a roster-completeness gate in the product tree, and a wrong row
fails that gate before it could reach here. What a table cannot hold — the operational judgement
— lives in the hand-written [venues overview](/docs/trader/venues).

## How the bridge is wired [#how-the-bridge-is-wired]

**Class: `live-exec-recon`.** A default build mounts a real execution client from this venue's credentials and includes the venue in the default reconcile set: `vike_mount::make_engine` has an ungated arm for it. With no credentials in the store the venue stays paper — absent credentials are the live gate — and `policy.venues.<id>` in `policy.toml` is consulted before the credentials and can only ever refuse (`vike_config::VenueMode::cap` is a minimum, never a maximum).

## Capabilities [#capabilities]

| Capability                   | Value |
| ---------------------------- | ----- |
| Modify (amend) an order      | no    |
| Native batch submit / cancel | no    |
| Reduce-only                  | no    |
| Combo (multi-leg) orders     | no    |
| Post-only                    | no    |
| Batch size cap               | 0     |
| Backfill: bars               | no    |
| Backfill: ticks              | no    |

Live market data the bridge feeds: `bars`, `quotes`, `trades`.

## Order kinds and triggers [#order-kinds-and-triggers]

Order kinds the adapter wires: `market`, `limit`, `stop`, `stop_limit`. Trigger types for the
conditional kinds: `stop-loss`. The vocabulary is the canonical one from
`vike_model::venue_caps::ORDER_KINDS`, not this venue's wire strings; the
[orders concepts](/docs/trader/concepts/orders) pages explain each kind's semantics and the per-venue
matrix.

## Time in force [#time-in-force]

"Supported" is what the adapter wires; "accepted" is what it will take from a strategy without
rejecting — a TIF can be accepted and then coerced or ignored on the wire, and that is what the
last column says (`vike_bridge_core::tif::venue_tif`).

| TIF | Supported | Accepted | On the wire            |
| --- | --------- | -------- | ---------------------- |
| GTC | yes       | yes      | mapped to `gtc`        |
| IOC | yes       | yes      | mapped to `ioc`        |
| FOK | yes       | yes      | mapped to `fok`        |
| GTD | no        | yes      | coerced to GTC (`gtc`) |
| Day | yes       | yes      | mapped to `day`        |

## Margin [#margin]

Margin modes the adapter offers: `cross`, defaulting to `cross`.
What the exchange itself offers (a vendor-documentation transcription, `vike_model::venue_margin_support`):
`cross`, switched `not-applicable`; the isolated-margin
wallet is not adjustable.

## Fees [#fees]

Free in the default schedule (the venue's opt-in probability curve is deliberately not exported). The schedule is `vike_model::fee_schedule_for`'s default row and is what the
[cost model](/docs/trader/backtesting/cost-model) charges in a backtest.

## Amending orders [#amending-orders]

A `modify` on this venue is applied not at all — `modify` is unsupported here, so a change is a cancel and a new order
(`vike_model::amend_semantics`).

## Attribution [#attribution]

No attribution mechanism — orders carry no affiliate or builder tag on this venue. An absent or invalid code degrades to no attribution with a
byte-identical wire (`vike_model::attribution::attribution_for`).


# Aster (/docs/trader/venues/aster)




Aster is one of the 14 venues Vike Trader mounts through the shared bridge contract: the
runtime speaks to every venue through one `ExecutionClient` seam, and everything below is rendered
from the capability tables that seam is built on — [`caps_for`](/docs/trader/concepts/execution-client-seam),
`venue_margin_support`, `fee_schedule_for`, `amend_semantics`, `attribution_for` and `venue_tif`
in the Rust workspace — exported as `venues.json` at every release. This page cannot state a
stale capability: each table has a roster-completeness gate in the product tree, and a wrong row
fails that gate before it could reach here. What a table cannot hold — the operational judgement
— lives in the hand-written [venues overview](/docs/trader/venues).

## How the bridge is wired [#how-the-bridge-is-wired]

**Class: `live-exec-recon`.** A default build mounts a real execution client from this venue's credentials and includes the venue in the default reconcile set: `vike_mount::make_engine` has an ungated arm for it. With no credentials in the store the venue stays paper — absent credentials are the live gate — and `policy.venues.<id>` in `policy.toml` is consulted before the credentials and can only ever refuse (`vike_config::VenueMode::cap` is a minimum, never a maximum).

No testnet credentials are configured, so in practice a reconcile pass issues authenticated MAINNET reads against the real account: withhold the `ASTER_*` keys from any validation run (`crates/bridges/aster/src/exec.rs`, whose `leverage_for` doc records that this venue mounts against MAINNET in practice because only `ASTER_LIVE_*` credentials exist).

## Capabilities [#capabilities]

| Capability                   | Value |
| ---------------------------- | ----- |
| Modify (amend) an order      | yes   |
| Native batch submit / cancel | yes   |
| Reduce-only                  | yes   |
| Combo (multi-leg) orders     | no    |
| Post-only                    | no    |
| Batch size cap               | 5     |
| Backfill: bars               | yes   |
| Backfill: ticks              | no    |

Live market data the bridge feeds: `bars`, `trades`, `depth`.

## Order kinds and triggers [#order-kinds-and-triggers]

Order kinds the adapter wires: `market`, `limit`, `stop`. Trigger types for the
conditional kinds: `stop-loss`. The vocabulary is the canonical one from
`vike_model::venue_caps::ORDER_KINDS`, not this venue's wire strings; the
[orders concepts](/docs/trader/concepts/orders) pages explain each kind's semantics and the per-venue
matrix.

## Time in force [#time-in-force]

"Supported" is what the adapter wires; "accepted" is what it will take from a strategy without
rejecting — a TIF can be accepted and then coerced or ignored on the wire, and that is what the
last column says (`vike_bridge_core::tif::venue_tif`).

| TIF | Supported | Accepted | On the wire             |
| --- | --------- | -------- | ----------------------- |
| GTC | yes       | yes      | ignored — sent as `GTC` |
| IOC | no        | no       | ignored — sent as `GTC` |
| FOK | no        | no       | ignored — sent as `GTC` |
| GTD | no        | no       | ignored — sent as `GTC` |
| Day | no        | no       | ignored — sent as `GTC` |

## Margin [#margin]

Margin modes the adapter offers: `cross`, defaulting to `cross`.
What the exchange itself offers (a vendor-documentation transcription, `vike_model::venue_margin_support`):
`cross`, `isolated`, switched `per-symbol-endpoint`; the isolated-margin
wallet is not adjustable.

## Fees [#fees]

Percentage maker/taker: **0.5 bps** maker, **4 bps** taker (the default schedule; venue tiers and rebates are not modelled). The schedule is `vike_model::fee_schedule_for`'s default row and is what the
[cost model](/docs/trader/backtesting/cost-model) charges in a backtest.

## Amending orders [#amending-orders]

A `modify` on this venue is applied with semantics the registry has not classified — treat a modify as unverified on this venue
(`vike_model::amend_semantics`).

## Attribution [#attribution]

A signed builder address that needs an on-chain approval first; set `ASTER_BROKER_CODE or ASTER_BUILDER_CODE`. An absent or invalid code degrades to no attribution with a
byte-identical wire (`vike_model::attribution::attribution_for`).


# Binance (/docs/trader/venues/binance)




Binance is one of the 14 venues Vike Trader mounts through the shared bridge contract: the
runtime speaks to every venue through one `ExecutionClient` seam, and everything below is rendered
from the capability tables that seam is built on — [`caps_for`](/docs/trader/concepts/execution-client-seam),
`venue_margin_support`, `fee_schedule_for`, `amend_semantics`, `attribution_for` and `venue_tif`
in the Rust workspace — exported as `venues.json` at every release. This page cannot state a
stale capability: each table has a roster-completeness gate in the product tree, and a wrong row
fails that gate before it could reach here. What a table cannot hold — the operational judgement
— lives in the hand-written [venues overview](/docs/trader/venues).

## How the bridge is wired [#how-the-bridge-is-wired]

**Class: `live-exec-recon`.** A default build mounts a real execution client from this venue's credentials and includes the venue in the default reconcile set: `vike_mount::make_engine` has an ungated arm for it. With no credentials in the store the venue stays paper — absent credentials are the live gate — and `policy.venues.<id>` in `policy.toml` is consulted before the credentials and can only ever refuse (`vike_config::VenueMode::cap` is a minimum, never a maximum).

## Capabilities [#capabilities]

| Capability                   | Value |
| ---------------------------- | ----- |
| Modify (amend) an order      | yes   |
| Native batch submit / cancel | yes   |
| Reduce-only                  | yes   |
| Combo (multi-leg) orders     | no    |
| Post-only                    | no    |
| Batch size cap               | 5     |
| Backfill: bars               | yes   |
| Backfill: ticks              | no    |

Live market data the bridge feeds: `bars`, `trades`, `depth`.

## Order kinds and triggers [#order-kinds-and-triggers]

Order kinds the adapter wires: `market`, `limit`, `stop`. Trigger types for the
conditional kinds: `stop-loss`. The vocabulary is the canonical one from
`vike_model::venue_caps::ORDER_KINDS`, not this venue's wire strings; the
[orders concepts](/docs/trader/concepts/orders) pages explain each kind's semantics and the per-venue
matrix.

## Time in force [#time-in-force]

"Supported" is what the adapter wires; "accepted" is what it will take from a strategy without
rejecting — a TIF can be accepted and then coerced or ignored on the wire, and that is what the
last column says (`vike_bridge_core::tif::venue_tif`).

| TIF | Supported | Accepted | On the wire     |
| --- | --------- | -------- | --------------- |
| GTC | yes       | yes      | mapped to `GTC` |
| IOC | yes       | yes      | mapped to `IOC` |
| FOK | yes       | yes      | mapped to `FOK` |
| GTD | no        | yes      | unsupported     |
| Day | no        | no       | unsupported     |

## Margin [#margin]

Margin modes the adapter offers: `cross`, defaulting to `cross`.
What the exchange itself offers (a vendor-documentation transcription, `vike_model::venue_margin_support`):
`cross`, `isolated`, switched `per-symbol-endpoint`; the isolated-margin
wallet is adjustable.

## Fees [#fees]

Percentage maker/taker: **10 bps** maker, **10 bps** taker (the default schedule; venue tiers and rebates are not modelled). The schedule is `vike_model::fee_schedule_for`'s default row and is what the
[cost model](/docs/trader/backtesting/cost-model) charges in a backtest.

## Amending orders [#amending-orders]

A `modify` on this venue is applied in place, and the amended quantity is the order's new TOTAL size (the venue nets it against what has already filled)
(`vike_model::amend_semantics`).

## Attribution [#attribution]

A client-order-id PREFIX (total id length capped at 36); set `BINANCE_BROKER_CODE or BINANCE_BUILDER_CODE` in the credential store. An absent or invalid code degrades to no attribution with a
byte-identical wire (`vike_model::attribution::attribution_for`).


# Bybit (/docs/trader/venues/bybit)




Bybit is one of the 14 venues Vike Trader mounts through the shared bridge contract: the
runtime speaks to every venue through one `ExecutionClient` seam, and everything below is rendered
from the capability tables that seam is built on — [`caps_for`](/docs/trader/concepts/execution-client-seam),
`venue_margin_support`, `fee_schedule_for`, `amend_semantics`, `attribution_for` and `venue_tif`
in the Rust workspace — exported as `venues.json` at every release. This page cannot state a
stale capability: each table has a roster-completeness gate in the product tree, and a wrong row
fails that gate before it could reach here. What a table cannot hold — the operational judgement
— lives in the hand-written [venues overview](/docs/trader/venues).

## How the bridge is wired [#how-the-bridge-is-wired]

**Class: `live-exec-recon`.** A default build mounts a real execution client from this venue's credentials and includes the venue in the default reconcile set: `vike_mount::make_engine` has an ungated arm for it. With no credentials in the store the venue stays paper — absent credentials are the live gate — and `policy.venues.<id>` in `policy.toml` is consulted before the credentials and can only ever refuse (`vike_config::VenueMode::cap` is a minimum, never a maximum).

## Capabilities [#capabilities]

| Capability                   | Value |
| ---------------------------- | ----- |
| Modify (amend) an order      | yes   |
| Native batch submit / cancel | no    |
| Reduce-only                  | yes   |
| Combo (multi-leg) orders     | no    |
| Post-only                    | no    |
| Batch size cap               | 0     |
| Backfill: bars               | yes   |
| Backfill: ticks              | no    |

Live market data the bridge feeds: `bars`, `trades`, `depth`.

## Order kinds and triggers [#order-kinds-and-triggers]

Order kinds the adapter wires: `market`, `limit`, `stop`. Trigger types for the
conditional kinds: `stop-loss`. The vocabulary is the canonical one from
`vike_model::venue_caps::ORDER_KINDS`, not this venue's wire strings; the
[orders concepts](/docs/trader/concepts/orders) pages explain each kind's semantics and the per-venue
matrix.

## Time in force [#time-in-force]

"Supported" is what the adapter wires; "accepted" is what it will take from a strategy without
rejecting — a TIF can be accepted and then coerced or ignored on the wire, and that is what the
last column says (`vike_bridge_core::tif::venue_tif`).

| TIF | Supported | Accepted | On the wire     |
| --- | --------- | -------- | --------------- |
| GTC | yes       | yes      | mapped to `GTC` |
| IOC | yes       | yes      | mapped to `IOC` |
| FOK | yes       | yes      | mapped to `FOK` |
| GTD | no        | no       | unsupported     |
| Day | no        | no       | unsupported     |

## Margin [#margin]

Margin modes the adapter offers: `cross`, defaulting to `cross`.
What the exchange itself offers (a vendor-documentation transcription, `vike_model::venue_margin_support`):
`cross`, `isolated`, switched `account-level`; the isolated-margin
wallet is adjustable.

## Fees [#fees]

Percentage maker/taker: **2 bps** maker, **5.5 bps** taker (the default schedule; venue tiers and rebates are not modelled). The schedule is `vike_model::fee_schedule_for`'s default row and is what the
[cost model](/docs/trader/backtesting/cost-model) charges in a backtest.

## Amending orders [#amending-orders]

A `modify` on this venue is applied in place, and the amended quantity is the order's new TOTAL size (the venue nets it against what has already filled)
(`vike_model::amend_semantics`).

## Attribution [#attribution]

An HTTP header, `X-Referer`; set `BYBIT_BROKER_CODE or BYBIT_BUILDER_CODE`. An absent or invalid code degrades to no attribution with a
byte-identical wire (`vike_model::attribution::attribution_for`).


# cTrader (/docs/trader/venues/ctrader)




cTrader is one of the 14 venues Vike Trader mounts through the shared bridge contract: the
runtime speaks to every venue through one `ExecutionClient` seam, and everything below is rendered
from the capability tables that seam is built on — [`caps_for`](/docs/trader/concepts/execution-client-seam),
`venue_margin_support`, `fee_schedule_for`, `amend_semantics`, `attribution_for` and `venue_tif`
in the Rust workspace — exported as `venues.json` at every release. This page cannot state a
stale capability: each table has a roster-completeness gate in the product tree, and a wrong row
fails that gate before it could reach here. What a table cannot hold — the operational judgement
— lives in the hand-written [venues overview](/docs/trader/venues).

## How the bridge is wired [#how-the-bridge-is-wired]

**Class: `live-exec-recon`.** A default build mounts a real execution client from this venue's credentials and includes the venue in the default reconcile set: `vike_mount::make_engine` has an ungated arm for it. With no credentials in the store the venue stays paper — absent credentials are the live gate — and `policy.venues.<id>` in `policy.toml` is consulted before the credentials and can only ever refuse (`vike_config::VenueMode::cap` is a minimum, never a maximum).

The mount opens a dedicated authenticated protobuf socket synchronously; a connect failure demotes the venue to paper for the session (`vike_mount::make_engine`).

## Capabilities [#capabilities]

| Capability                   | Value |
| ---------------------------- | ----- |
| Modify (amend) an order      | yes   |
| Native batch submit / cancel | no    |
| Reduce-only                  | no    |
| Combo (multi-leg) orders     | no    |
| Post-only                    | no    |
| Batch size cap               | 0     |
| Backfill: bars               | no    |
| Backfill: ticks              | no    |

Live market data the bridge feeds: `bars`, `quotes`.

## Order kinds and triggers [#order-kinds-and-triggers]

Order kinds the adapter wires: `market`, `limit`, `stop`. Trigger types for the
conditional kinds: `stop-loss`. The vocabulary is the canonical one from
`vike_model::venue_caps::ORDER_KINDS`, not this venue's wire strings; the
[orders concepts](/docs/trader/concepts/orders) pages explain each kind's semantics and the per-venue
matrix.

## Time in force [#time-in-force]

"Supported" is what the adapter wires; "accepted" is what it will take from a strategy without
rejecting — a TIF can be accepted and then coerced or ignored on the wire, and that is what the
last column says (`vike_bridge_core::tif::venue_tif`).

| TIF | Supported | Accepted | On the wire             |
| --- | --------- | -------- | ----------------------- |
| GTC | yes       | yes      | not emitted on the wire |
| IOC | no        | no       | not emitted on the wire |
| FOK | no        | no       | not emitted on the wire |
| GTD | no        | no       | not emitted on the wire |
| Day | no        | no       | not emitted on the wire |

## Margin [#margin]

Margin modes the adapter offers: `cross`, defaulting to `cross`.
What the exchange itself offers (a vendor-documentation transcription, `vike_model::venue_margin_support`):
`cross`, switched `not-applicable`; the isolated-margin
wallet is not adjustable.

## Fees [#fees]

Free in the default schedule (the venue's opt-in probability curve is deliberately not exported). The schedule is `vike_model::fee_schedule_for`'s default row and is what the
[cost model](/docs/trader/backtesting/cost-model) charges in a backtest.

## Amending orders [#amending-orders]

A `modify` on this venue is applied with semantics the registry has not classified — treat a modify as unverified on this venue
(`vike_model::amend_semantics`).

## Attribution [#attribution]

No attribution mechanism — orders carry no affiliate or builder tag on this venue. An absent or invalid code degrades to no attribution with a
byte-identical wire (`vike_model::attribution::attribution_for`).


# Deribit (/docs/trader/venues/deribit)




Deribit is one of the 14 venues Vike Trader mounts through the shared bridge contract: the
runtime speaks to every venue through one `ExecutionClient` seam, and everything below is rendered
from the capability tables that seam is built on — [`caps_for`](/docs/trader/concepts/execution-client-seam),
`venue_margin_support`, `fee_schedule_for`, `amend_semantics`, `attribution_for` and `venue_tif`
in the Rust workspace — exported as `venues.json` at every release. This page cannot state a
stale capability: each table has a roster-completeness gate in the product tree, and a wrong row
fails that gate before it could reach here. What a table cannot hold — the operational judgement
— lives in the hand-written [venues overview](/docs/trader/venues).

## How the bridge is wired [#how-the-bridge-is-wired]

**Class: `live-exec-recon`.** A default build mounts a real execution client from this venue's credentials and includes the venue in the default reconcile set: `vike_mount::make_engine` has an ungated arm for it. With no credentials in the store the venue stays paper — absent credentials are the live gate — and `policy.venues.<id>` in `policy.toml` is consulted before the credentials and can only ever refuse (`vike_config::VenueMode::cap` is a minimum, never a maximum).

## Capabilities [#capabilities]

| Capability                   | Value |
| ---------------------------- | ----- |
| Modify (amend) an order      | no    |
| Native batch submit / cancel | no    |
| Reduce-only                  | yes   |
| Combo (multi-leg) orders     | yes   |
| Post-only                    | no    |
| Batch size cap               | 0     |
| Backfill: bars               | yes   |
| Backfill: ticks              | no    |

Live market data the bridge feeds: `bars`, `quotes`, `trades`, `book`.

## Order kinds and triggers [#order-kinds-and-triggers]

Order kinds the adapter wires: `market`, `limit`. Trigger types for the
conditional kinds: none. The vocabulary is the canonical one from
`vike_model::venue_caps::ORDER_KINDS`, not this venue's wire strings; the
[orders concepts](/docs/trader/concepts/orders) pages explain each kind's semantics and the per-venue
matrix.

## Time in force [#time-in-force]

"Supported" is what the adapter wires; "accepted" is what it will take from a strategy without
rejecting — a TIF can be accepted and then coerced or ignored on the wire, and that is what the
last column says (`vike_bridge_core::tif::venue_tif`).

| TIF | Supported | Accepted | On the wire                     |
| --- | --------- | -------- | ------------------------------- |
| GTC | yes       | yes      | not emitted on the wire         |
| IOC | yes       | yes      | mapped to `immediate_or_cancel` |
| FOK | yes       | yes      | mapped to `fill_or_kill`        |
| GTD | no        | no       | unsupported                     |
| Day | yes       | yes      | mapped to `good_til_day`        |

## Margin [#margin]

Margin modes the adapter offers: `cross`, defaulting to `cross`.
What the exchange itself offers (a vendor-documentation transcription, `vike_model::venue_margin_support`):
`cross`, switched `not-applicable`; the isolated-margin
wallet is not adjustable.

## Fees [#fees]

Percentage of the underlying: 3 bps, premium-capped at 0.125%. The schedule is `vike_model::fee_schedule_for`'s default row and is what the
[cost model](/docs/trader/backtesting/cost-model) charges in a backtest.

## Amending orders [#amending-orders]

A `modify` on this venue is applied not at all — `modify` is unsupported here, so a change is a cancel and a new order
(`vike_model::amend_semantics`).

## Attribution [#attribution]

No attribution mechanism — orders carry no affiliate or builder tag on this venue. An absent or invalid code degrades to no attribution with a
byte-identical wire (`vike_model::attribution::attribution_for`).


# Dukascopy (/docs/trader/venues/dukascopy)




Dukascopy is one of the 14 venues Vike Trader mounts through the shared bridge contract: the
runtime speaks to every venue through one `ExecutionClient` seam, and everything below is rendered
from the capability tables that seam is built on — [`caps_for`](/docs/trader/concepts/execution-client-seam),
`venue_margin_support`, `fee_schedule_for`, `amend_semantics`, `attribution_for` and `venue_tif`
in the Rust workspace — exported as `venues.json` at every release. This page cannot state a
stale capability: each table has a roster-completeness gate in the product tree, and a wrong row
fails that gate before it could reach here. What a table cannot hold — the operational judgement
— lives in the hand-written [venues overview](/docs/trader/venues).

## How the bridge is wired [#how-the-bridge-is-wired]

**Class: `sidecar-exec-no-recon`.** Execution runs through an owned child process rather than a socket, and no `make_engine` arm wires a reconcile client for it — a `ReconClient` factory existing is not the same as being in the live reconcile set.

No REST execution API exists, so a Java sidecar drives execution over JSON-lines stdio, and because JForex is position-per-order its fills arrive as per-fill DELTAS rather than the cumulative shape every other venue sends (`crates/bridges/dukascopy/src/netting.rs`, whose header opens with the position-per-order property and the netting plan built on it).

## Capabilities [#capabilities]

| Capability                   | Value |
| ---------------------------- | ----- |
| Modify (amend) an order      | no    |
| Native batch submit / cancel | no    |
| Reduce-only                  | no    |
| Combo (multi-leg) orders     | no    |
| Post-only                    | no    |
| Batch size cap               | 0     |
| Backfill: bars               | yes   |
| Backfill: ticks              | yes   |

Live market data the bridge feeds: none (an execution-only venue — it has no market feed of its own).

## Order kinds and triggers [#order-kinds-and-triggers]

Order kinds the adapter wires: `market`, `limit`. Trigger types for the
conditional kinds: none. The vocabulary is the canonical one from
`vike_model::venue_caps::ORDER_KINDS`, not this venue's wire strings; the
[orders concepts](/docs/trader/concepts/orders) pages explain each kind's semantics and the per-venue
matrix.

## Time in force [#time-in-force]

"Supported" is what the adapter wires; "accepted" is what it will take from a strategy without
rejecting — a TIF can be accepted and then coerced or ignored on the wire, and that is what the
last column says (`vike_bridge_core::tif::venue_tif`).

| TIF | Supported | Accepted | On the wire             |
| --- | --------- | -------- | ----------------------- |
| GTC | yes       | yes      | not emitted on the wire |
| IOC | no        | no       | not emitted on the wire |
| FOK | no        | no       | not emitted on the wire |
| GTD | no        | no       | not emitted on the wire |
| Day | no        | no       | not emitted on the wire |

## Margin [#margin]

Margin modes the adapter offers: `cross`, defaulting to `cross`.
What the exchange itself offers (a vendor-documentation transcription, `vike_model::venue_margin_support`):
`cross`, switched `not-applicable`; the isolated-margin
wallet is not adjustable.

## Fees [#fees]

Free in the default schedule (the venue's opt-in probability curve is deliberately not exported). The schedule is `vike_model::fee_schedule_for`'s default row and is what the
[cost model](/docs/trader/backtesting/cost-model) charges in a backtest.

## Amending orders [#amending-orders]

A `modify` on this venue is applied not at all — `modify` is unsupported here, so a change is a cancel and a new order
(`vike_model::amend_semantics`).

## Attribution [#attribution]

No attribution mechanism — orders carry no affiliate or builder tag on this venue. An absent or invalid code degrades to no attribution with a
byte-identical wire (`vike_model::attribution::attribution_for`).


# FXCM (/docs/trader/venues/fxcm)




FXCM is one of the 14 venues Vike Trader mounts through the shared bridge contract: the
runtime speaks to every venue through one `ExecutionClient` seam, and everything below is rendered
from the capability tables that seam is built on — [`caps_for`](/docs/trader/concepts/execution-client-seam),
`venue_margin_support`, `fee_schedule_for`, `amend_semantics`, `attribution_for` and `venue_tif`
in the Rust workspace — exported as `venues.json` at every release. This page cannot state a
stale capability: each table has a roster-completeness gate in the product tree, and a wrong row
fails that gate before it could reach here. What a table cannot hold — the operational judgement
— lives in the hand-written [venues overview](/docs/trader/venues).

## How the bridge is wired [#how-the-bridge-is-wired]

**Class: `feature-gated`.** The live arm compiles only under a vike-mount cargo feature; a default build has no arm at all and falls through to paper, byte-identical. Reconcile, where wired, sits behind the same feature plus the venue's own inner gates. A release binary built without the feature will never trade here whatever the credential store holds.

Even with the `fxcm` feature on and credentials present, the mount REFUSES to go live unless `vike_fxcm::sdk_linked()` — without the proprietary ForexConnect SDK compiled in, the execution client would accept every order and discard it in silence. No CI runner has ever linked that SDK, so the wire behaviour is proven only by hand on a box with it staged (`crates/bridges/fxcm/src/lib.rs`'s `sdk_linked`).

## Capabilities [#capabilities]

| Capability                   | Value |
| ---------------------------- | ----- |
| Modify (amend) an order      | no    |
| Native batch submit / cancel | no    |
| Reduce-only                  | no    |
| Combo (multi-leg) orders     | no    |
| Post-only                    | no    |
| Batch size cap               | 0     |
| Backfill: bars               | no    |
| Backfill: ticks              | no    |

Live market data the bridge feeds: none (an execution-only venue — it has no market feed of its own).

## Order kinds and triggers [#order-kinds-and-triggers]

Order kinds the adapter wires: `market`, `limit`. Trigger types for the
conditional kinds: none. The vocabulary is the canonical one from
`vike_model::venue_caps::ORDER_KINDS`, not this venue's wire strings; the
[orders concepts](/docs/trader/concepts/orders) pages explain each kind's semantics and the per-venue
matrix.

## Time in force [#time-in-force]

"Supported" is what the adapter wires; "accepted" is what it will take from a strategy without
rejecting — a TIF can be accepted and then coerced or ignored on the wire, and that is what the
last column says (`vike_bridge_core::tif::venue_tif`).

| TIF | Supported | Accepted | On the wire             |
| --- | --------- | -------- | ----------------------- |
| GTC | yes       | yes      | not emitted on the wire |
| IOC | no        | no       | not emitted on the wire |
| FOK | no        | no       | not emitted on the wire |
| GTD | no        | no       | not emitted on the wire |
| Day | no        | no       | not emitted on the wire |

## Margin [#margin]

Margin modes the adapter offers: `cross`, defaulting to `cross`.
What the exchange itself offers (a vendor-documentation transcription, `vike_model::venue_margin_support`):
`cross`, switched `not-applicable`; the isolated-margin
wallet is not adjustable.

## Fees [#fees]

Free in the default schedule (the venue's opt-in probability curve is deliberately not exported). The schedule is `vike_model::fee_schedule_for`'s default row and is what the
[cost model](/docs/trader/backtesting/cost-model) charges in a backtest.

## Amending orders [#amending-orders]

A `modify` on this venue is applied not at all — `modify` is unsupported here, so a change is a cancel and a new order
(`vike_model::amend_semantics`).

## Attribution [#attribution]

No attribution mechanism — orders carry no affiliate or builder tag on this venue. An absent or invalid code degrades to no attribution with a
byte-identical wire (`vike_model::attribution::attribution_for`).


# Hyperliquid (/docs/trader/venues/hyperliquid)




Hyperliquid is one of the 14 venues Vike Trader mounts through the shared bridge contract: the
runtime speaks to every venue through one `ExecutionClient` seam, and everything below is rendered
from the capability tables that seam is built on — [`caps_for`](/docs/trader/concepts/execution-client-seam),
`venue_margin_support`, `fee_schedule_for`, `amend_semantics`, `attribution_for` and `venue_tif`
in the Rust workspace — exported as `venues.json` at every release. This page cannot state a
stale capability: each table has a roster-completeness gate in the product tree, and a wrong row
fails that gate before it could reach here. What a table cannot hold — the operational judgement
— lives in the hand-written [venues overview](/docs/trader/venues).

## How the bridge is wired [#how-the-bridge-is-wired]

**Class: `live-exec-recon`.** A default build mounts a real execution client from this venue's credentials and includes the venue in the default reconcile set: `vike_mount::make_engine` has an ungated arm for it. With no credentials in the store the venue stays paper — absent credentials are the live gate — and `policy.venues.<id>` in `policy.toml` is consulted before the credentials and can only ever refuse (`vike_config::VenueMode::cap` is a minimum, never a maximum).

## Capabilities [#capabilities]

| Capability                   | Value                       |
| ---------------------------- | --------------------------- |
| Modify (amend) an order      | yes                         |
| Native batch submit / cancel | yes                         |
| Reduce-only                  | yes                         |
| Combo (multi-leg) orders     | no                          |
| Post-only                    | no                          |
| Batch size cap               | no cap of the adapter's own |
| Backfill: bars               | yes                         |
| Backfill: ticks              | no                          |

Live market data the bridge feeds: `bars`, `quotes`, `trades`, `depth`.

## Order kinds and triggers [#order-kinds-and-triggers]

Order kinds the adapter wires: `market`, `limit`, `stop`, `stop_limit`, `take_profit`. Trigger types for the
conditional kinds: `stop-loss`, `take-profit`. The vocabulary is the canonical one from
`vike_model::venue_caps::ORDER_KINDS`, not this venue's wire strings; the
[orders concepts](/docs/trader/concepts/orders) pages explain each kind's semantics and the per-venue
matrix.

## Time in force [#time-in-force]

"Supported" is what the adapter wires; "accepted" is what it will take from a strategy without
rejecting — a TIF can be accepted and then coerced or ignored on the wire, and that is what the
last column says (`vike_bridge_core::tif::venue_tif`).

| TIF | Supported | Accepted | On the wire            |
| --- | --------- | -------- | ---------------------- |
| GTC | yes       | yes      | mapped to `Gtc`        |
| IOC | yes       | yes      | mapped to `Ioc`        |
| FOK | no        | yes      | coerced to IOC (`Ioc`) |
| GTD | no        | yes      | coerced to GTC (`Gtc`) |
| Day | no        | yes      | coerced to GTC (`Gtc`) |

## Margin [#margin]

Margin modes the adapter offers: `cross`, defaulting to `cross`.
What the exchange itself offers (a vendor-documentation transcription, `vike_model::venue_margin_support`):
`cross`, `isolated`, switched `at-leverage-set`; the isolated-margin
wallet is not adjustable.

## Fees [#fees]

Percentage maker/taker: **1.5 bps** maker, **4.5 bps** taker (the default schedule; venue tiers and rebates are not modelled). The schedule is `vike_model::fee_schedule_for`'s default row and is what the
[cost model](/docs/trader/backtesting/cost-model) charges in a backtest.

## Amending orders [#amending-orders]

A `modify` on this venue is applied as a cancel followed by a fresh submit — the order loses its queue position and, briefly, its protection
(`vike_model::amend_semantics`).

## Attribution [#attribution]

A signed builder address that needs an on-chain approval first; set `HYPERLIQUID_BROKER_CODE or HYPERLIQUID_BUILDER_CODE`. An absent or invalid code degrades to no attribution with a
byte-identical wire (`vike_model::attribution::attribution_for`).


# Interactive Brokers (/docs/trader/venues/ibkr)




Interactive Brokers is one of the 14 venues Vike Trader mounts through the shared bridge contract: the
runtime speaks to every venue through one `ExecutionClient` seam, and everything below is rendered
from the capability tables that seam is built on — [`caps_for`](/docs/trader/concepts/execution-client-seam),
`venue_margin_support`, `fee_schedule_for`, `amend_semantics`, `attribution_for` and `venue_tif`
in the Rust workspace — exported as `venues.json` at every release. This page cannot state a
stale capability: each table has a roster-completeness gate in the product tree, and a wrong row
fails that gate before it could reach here. What a table cannot hold — the operational judgement
— lives in the hand-written [venues overview](/docs/trader/venues).

## How the bridge is wired [#how-the-bridge-is-wired]

**Class: `feature-gated`.** The live arm compiles only under a vike-mount cargo feature; a default build has no arm at all and falls through to paper, byte-identical. Reconcile, where wired, sits behind the same feature plus the venue's own inner gates. A release binary built without the feature will never trade here whatever the credential store holds.

The mount connects to the Client Portal gateway synchronously; a connect failure demotes the venue to paper for the session and drops its reconcile handle (`vike_mount::make_engine`'s `("ibkr", _)` arm).

## Capabilities [#capabilities]

| Capability                   | Value |
| ---------------------------- | ----- |
| Modify (amend) an order      | no    |
| Native batch submit / cancel | no    |
| Reduce-only                  | no    |
| Combo (multi-leg) orders     | no    |
| Post-only                    | no    |
| Batch size cap               | 0     |
| Backfill: bars               | yes   |
| Backfill: ticks              | no    |

Live market data the bridge feeds: `bars`, `quotes`, `trades`, `book`, `depth`.

## Order kinds and triggers [#order-kinds-and-triggers]

Order kinds the adapter wires: `market`, `limit`, `stop`. Trigger types for the
conditional kinds: `stop-loss`. The vocabulary is the canonical one from
`vike_model::venue_caps::ORDER_KINDS`, not this venue's wire strings; the
[orders concepts](/docs/trader/concepts/orders) pages explain each kind's semantics and the per-venue
matrix.

## Time in force [#time-in-force]

"Supported" is what the adapter wires; "accepted" is what it will take from a strategy without
rejecting — a TIF can be accepted and then coerced or ignored on the wire, and that is what the
last column says (`vike_bridge_core::tif::venue_tif`).

| TIF | Supported | Accepted | On the wire     |
| --- | --------- | -------- | --------------- |
| GTC | yes       | yes      | mapped to `GTC` |
| IOC | yes       | yes      | mapped to `IOC` |
| FOK | yes       | yes      | mapped to `FOK` |
| GTD | yes       | yes      | mapped to `GTD` |
| Day | yes       | yes      | mapped to `DAY` |

## Margin [#margin]

Margin modes the adapter offers: `cross`, defaulting to `cross`.
What the exchange itself offers (a vendor-documentation transcription, `vike_model::venue_margin_support`):
`cross`, switched `not-applicable`; the isolated-margin
wallet is not adjustable.

## Fees [#fees]

Per share with a floor: 0.005 per share, minimum 1, capped at 0.005% of notional. The schedule is `vike_model::fee_schedule_for`'s default row and is what the
[cost model](/docs/trader/backtesting/cost-model) charges in a backtest.

## Amending orders [#amending-orders]

A `modify` on this venue is applied with semantics the registry has not classified — treat a modify as unverified on this venue
(`vike_model::amend_semantics`).

## Attribution [#attribution]

No attribution mechanism — orders carry no affiliate or builder tag on this venue. An absent or invalid code degrades to no attribution with a
byte-identical wire (`vike_model::attribution::attribution_for`).


# IG (/docs/trader/venues/ig)




IG is one of the 14 venues Vike Trader mounts through the shared bridge contract: the
runtime speaks to every venue through one `ExecutionClient` seam, and everything below is rendered
from the capability tables that seam is built on — [`caps_for`](/docs/trader/concepts/execution-client-seam),
`venue_margin_support`, `fee_schedule_for`, `amend_semantics`, `attribution_for` and `venue_tif`
in the Rust workspace — exported as `venues.json` at every release. This page cannot state a
stale capability: each table has a roster-completeness gate in the product tree, and a wrong row
fails that gate before it could reach here. What a table cannot hold — the operational judgement
— lives in the hand-written [venues overview](/docs/trader/venues).

## How the bridge is wired [#how-the-bridge-is-wired]

**Class: `live-exec-recon`.** A default build mounts a real execution client from this venue's credentials and includes the venue in the default reconcile set: `vike_mount::make_engine` has an ungated arm for it. With no credentials in the store the venue stays paper — absent credentials are the live gate — and `policy.venues.<id>` in `policy.toml` is consulted before the credentials and can only ever refuse (`vike_config::VenueMode::cap` is a minimum, never a maximum).

## Capabilities [#capabilities]

| Capability                   | Value |
| ---------------------------- | ----- |
| Modify (amend) an order      | no    |
| Native batch submit / cancel | no    |
| Reduce-only                  | no    |
| Combo (multi-leg) orders     | no    |
| Post-only                    | no    |
| Batch size cap               | 0     |
| Backfill: bars               | no    |
| Backfill: ticks              | no    |

Live market data the bridge feeds: `bars`, `quotes`.

## Order kinds and triggers [#order-kinds-and-triggers]

Order kinds the adapter wires: `market`, `limit`, `stop`. Trigger types for the
conditional kinds: `stop-loss`. The vocabulary is the canonical one from
`vike_model::venue_caps::ORDER_KINDS`, not this venue's wire strings; the
[orders concepts](/docs/trader/concepts/orders) pages explain each kind's semantics and the per-venue
matrix.

## Time in force [#time-in-force]

"Supported" is what the adapter wires; "accepted" is what it will take from a strategy without
rejecting — a TIF can be accepted and then coerced or ignored on the wire, and that is what the
last column says (`vike_bridge_core::tif::venue_tif`).

| TIF | Supported | Accepted | On the wire                             |
| --- | --------- | -------- | --------------------------------------- |
| GTC | yes       | yes      | ignored — sent as `GOOD_TILL_CANCELLED` |
| IOC | no        | no       | ignored — sent as `GOOD_TILL_CANCELLED` |
| FOK | no        | no       | ignored — sent as `GOOD_TILL_CANCELLED` |
| GTD | no        | no       | ignored — sent as `GOOD_TILL_CANCELLED` |
| Day | no        | no       | ignored — sent as `GOOD_TILL_CANCELLED` |

## Margin [#margin]

Margin modes the adapter offers: `cross`, defaulting to `cross`.
What the exchange itself offers (a vendor-documentation transcription, `vike_model::venue_margin_support`):
`cross`, switched `not-applicable`; the isolated-margin
wallet is not adjustable.

## Fees [#fees]

Free in the default schedule (the venue's opt-in probability curve is deliberately not exported). The schedule is `vike_model::fee_schedule_for`'s default row and is what the
[cost model](/docs/trader/backtesting/cost-model) charges in a backtest.

## Amending orders [#amending-orders]

A `modify` on this venue is applied not at all — `modify` is unsupported here, so a change is a cancel and a new order
(`vike_model::amend_semantics`).

## Attribution [#attribution]

No attribution mechanism — orders carry no affiliate or builder tag on this venue. An absent or invalid code degrades to no attribution with a
byte-identical wire (`vike_model::attribution::attribution_for`).


# Venues (/docs/trader/venues)



Vike Trader has a bridge crate for fourteen venues, one directory each under `crates/bridges/`.
`vike_model::VENUES` (`crates/vike-model/src/venues.rs`) is the canonical roster and calls itself
"THE authority on *every venue vike has a bridge crate for*". Every per-venue capability table's
completeness test iterates it, "so adding a venue here fails EVERY table's tests until its rows
land" — and a roster venue's row is always named even where its value equals the registry fallback,
because "the named row is the declaration that the venue was CLASSIFIED, not forgotten". That is why
the per-venue pages here are generated: their rows are the rows the runtime consults.

## What a bridge is [#what-a-bridge-is]

`vike-bridge-core` is "the shared plumbing every venue bridge is built from: blocking REST transport

* signers, the venue-neutral WS user-data pump with reconnect/backoff/keepalive/resync, the
  ExecActor command thread, credentials (the absent-credentials-is-the-live-gate authority), and the
  pinned Decimal wire-format site" (`crates/vike-bridge-core/src/lib.rs`). A venue crate supplies its
  own signer, its wire strings and a pure event mapper; the reliability machinery is shared. A shared
  rule lives in bridge-core rather than in each bridge so the venue arms "cannot drift from each
  other" (`crates/vike-bridge-core/src/lib.rs`'s `leverage` note) — which is why a shared home is
  consumed, not modified in passing: a missing knob is a stop-and-report, and the extension lands as
  one coordinated change informed by every consumer.

At the top of every bridge sits one trait. `vike_exec::ExecutionClient` is "the venue-client seam:
`submit`/`cancel` are the ONLY order-mutating calls that leave the core; every state change comes
back as venue events through the ingest channel"
(`crates/vike-exec/src/execution_engine/client.rs`). Everything else on it has a default — see
[the ExecutionClient seam](/docs/trader/concepts/execution-client-seam).

## The emitter split, machine-checked [#the-emitter-split-machine-checked]

`crates/vike-bridge-core/tests/bridge_conformance.rs` runs one scenario table against every covered
venue's real event mapper, and states the contract it checks:

* **Emitter split** — "Rust emits `OrderSubmitted` synchronously at submit; the venue emits
  `OrderAccepted / Rejected / Canceled / (Partially)Filled`."
* **No silent vanish** — "a dead venue path MUST synthesize a terminal `OrderRejected`."
* **Exactly one terminal** — the `ManagedOrder` FSM "must reach exactly one terminal state
  (`Filled | Canceled | Rejected | Denied | Expired`); illegal/out-of-order events are dropped
  idempotently, never corrupting the single terminal."

The oracle is the real FSM the live core folds through, not a model of it. Ten venues are covered —
binance, bybit, okx, deribit, aster, hyperliquid, oanda, ig, alpaca and fxcm; polymarket, dukascopy,
ibkr and ctrader are deferred with a recorded reason each. Which column a venue sits in is not
optional: `conformance_roster_is_exhaustive` checks both lists exhaustive against `VENUES`, so a new
bridge "fails the gate until it is either wired in or deliberately deferred-with-reason".
`market_data_conformance.rs` is the market-data twin over each covered venue's real `route_frame`
normalizer, with its own roster gate.

## Two gates, and the order between them [#two-gates-and-the-order-between-them]

`vike_mount::make_engine` turns a venue name into a client, and its module doc is blunt about the
sequence: "the LIVE GATE is TWO gates now, and the order between them is the point". The
deployment's per-venue arming ceiling — `policy.venues.<venue>`, `paper` \< `demo` \< `live` — is
consulted **first**, above the credential read, and "a `paper` venue returns the paper client having
loaded no credential, fetched no instrument grid and opened no socket". Only then does the older
rule apply: absent credentials are the live gate, and a venue whose keys are missing stays on
`vike_paper::PaperExecutionClient`.

The ceiling can only ever refuse. `vike_config::VenueMode::cap` is "`min`, never `max`" — its own
doctest asserts that a `live` ceiling over a demo-credentialled venue stays demo, and that a `paper`
ceiling over a live-credentialled venue is refused down to paper. Writing `live` arms nothing by
itself; it declines to stop something else arming it. [Arm one venue for
demo](/docs/trader/guides/arm-a-venue) is the task-shaped version;
[policy.toml](/docs/trader/reference/settings/policy) is the key reference.

<Callout type="warn" title="A box with no [venues] table mounts all paper">
  `vike-mount`'s `venue_arming_migration_message` warns once at startup rather than refusing, naming
  the credentialled venues that are now paper and the settings paths that restore them — because "a
  node that will not start cannot flatten a position either". It self-silences the moment any venue is
  declared, and prints venue slugs only, never a credential key name: "this text is designed to be
  pasted, and a paste-ready block that carries key names invites the reply that carries values."
</Callout>

## How each venue is wired [#how-each-venue-is-wired]

`vike_ops::docs_data`'s `Wiring` is the one docs-facing axis no capability table encodes, "because
it is a property of `make_engine` arms rather than of any adapter". Each generated venue page opens
with its class.

| class                   | what it means                                                                                                      |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `live-exec-recon`       | an ungated arm mounts a real client from credentials; the venue is in the default reconcile set                    |
| `feature-gated`         | the live arm compiles only under a vike-mount cargo feature; a default build has no arm and falls through to paper |
| `sidecar-exec-no-recon` | exec runs through an owned child process, and no arm wires that venue's recon factory                              |
| `paper-only`            | only the paper fallback mounts it; no roster venue is in this class today                                          |

`WIRING` carries one named row per roster venue behind a completeness gate, and an unclassified
venue panics the renderer rather than exporting a guess. A `ReconClient` existing "is not the same
as being in the live reconcile set".

## What the shared plumbing guarantees [#what-the-shared-plumbing-guarantees]

**The halt boundary.** `submit` and `modify` consult the halt file sentinel before touching the
command channel, and the refusal is conditional. A submit that OPENS or ADDS is refused with a
synthesized terminal `OrderRejected` (never a silent vanish); a submit that REDUCES is **allowed** —
`crates/vike-bridge-core/src/halt.rs`'s `halt_admits_submit` "is the whole of that rule", and every
such admission is logged, because that boundary holds no position book and can only trust the
caller's `reduce_only` flag. A modify is blocked so the resting order keeps its terms, and cancel is
never gated. The reducing arm exists because a cancel alone never discharged "a kill switch must
never trap you in a position": "a cancel removes a resting ORDER, while getting OUT of a position
means SENDING one", and until that arm landed `market-exit` under a halt file cancelled everything
and could then close nothing. It works when the runtime is wedged: an operator touches the file over
ssh (`crates/vike-bridge-core/src/exec_actor.rs`). See [halt](/docs/trader/concepts/halt).

**The restart law.** Every venue's resync closure replays a window of venue history bounded by a row
count and nothing else, so the first gap-sentinel after a restart once folded the venue's whole
retained execution history through the non-idempotent fill path — measured on the production box,
"each unexplained equity step equalled the sum of PRIOR sessions' costs, exactly". `run_loop` now
samples its own spawn instant and never forwards a resync event stamped before it;
`run_resync_supervisor` carries the same floor on the user-data lane.

Polymarket carries operational rules no table can hold — they are in
[Polymarket operations](/docs/trader/venues/polymarket-operations). The rest of the arming picture is in
[risk and arming](/docs/trader/concepts/risk-and-arming).


# OANDA (/docs/trader/venues/oanda)




OANDA is one of the 14 venues Vike Trader mounts through the shared bridge contract: the
runtime speaks to every venue through one `ExecutionClient` seam, and everything below is rendered
from the capability tables that seam is built on — [`caps_for`](/docs/trader/concepts/execution-client-seam),
`venue_margin_support`, `fee_schedule_for`, `amend_semantics`, `attribution_for` and `venue_tif`
in the Rust workspace — exported as `venues.json` at every release. This page cannot state a
stale capability: each table has a roster-completeness gate in the product tree, and a wrong row
fails that gate before it could reach here. What a table cannot hold — the operational judgement
— lives in the hand-written [venues overview](/docs/trader/venues).

## How the bridge is wired [#how-the-bridge-is-wired]

**Class: `live-exec-recon`.** A default build mounts a real execution client from this venue's credentials and includes the venue in the default reconcile set: `vike_mount::make_engine` has an ungated arm for it. With no credentials in the store the venue stays paper — absent credentials are the live gate — and `policy.venues.<id>` in `policy.toml` is consulted before the credentials and can only ever refuse (`vike_config::VenueMode::cap` is a minimum, never a maximum).

## Capabilities [#capabilities]

| Capability                   | Value |
| ---------------------------- | ----- |
| Modify (amend) an order      | no    |
| Native batch submit / cancel | no    |
| Reduce-only                  | no    |
| Combo (multi-leg) orders     | no    |
| Post-only                    | no    |
| Batch size cap               | 0     |
| Backfill: bars               | no    |
| Backfill: ticks              | no    |

Live market data the bridge feeds: `bars`, `quotes`.

## Order kinds and triggers [#order-kinds-and-triggers]

Order kinds the adapter wires: `market`, `limit`, `stop`. Trigger types for the
conditional kinds: `stop-loss`. The vocabulary is the canonical one from
`vike_model::venue_caps::ORDER_KINDS`, not this venue's wire strings; the
[orders concepts](/docs/trader/concepts/orders) pages explain each kind's semantics and the per-venue
matrix.

## Time in force [#time-in-force]

"Supported" is what the adapter wires; "accepted" is what it will take from a strategy without
rejecting — a TIF can be accepted and then coerced or ignored on the wire, and that is what the
last column says (`vike_bridge_core::tif::venue_tif`).

| TIF | Supported | Accepted | On the wire     |
| --- | --------- | -------- | --------------- |
| GTC | yes       | yes      | mapped to `GTC` |
| IOC | yes       | yes      | mapped to `IOC` |
| FOK | yes       | yes      | mapped to `FOK` |
| GTD | yes       | yes      | mapped to `GTD` |
| Day | yes       | yes      | mapped to `GFD` |

## Margin [#margin]

Margin modes the adapter offers: `cross`, defaulting to `cross`.
What the exchange itself offers (a vendor-documentation transcription, `vike_model::venue_margin_support`):
`cross`, switched `not-applicable`; the isolated-margin
wallet is not adjustable.

## Fees [#fees]

Free in the default schedule (the venue's opt-in probability curve is deliberately not exported). The schedule is `vike_model::fee_schedule_for`'s default row and is what the
[cost model](/docs/trader/backtesting/cost-model) charges in a backtest.

## Amending orders [#amending-orders]

A `modify` on this venue is applied not at all — `modify` is unsupported here, so a change is a cancel and a new order
(`vike_model::amend_semantics`).

## Attribution [#attribution]

No attribution mechanism — orders carry no affiliate or builder tag on this venue. An absent or invalid code degrades to no attribution with a
byte-identical wire (`vike_model::attribution::attribution_for`).


# OKX (/docs/trader/venues/okx)




OKX is one of the 14 venues Vike Trader mounts through the shared bridge contract: the
runtime speaks to every venue through one `ExecutionClient` seam, and everything below is rendered
from the capability tables that seam is built on — [`caps_for`](/docs/trader/concepts/execution-client-seam),
`venue_margin_support`, `fee_schedule_for`, `amend_semantics`, `attribution_for` and `venue_tif`
in the Rust workspace — exported as `venues.json` at every release. This page cannot state a
stale capability: each table has a roster-completeness gate in the product tree, and a wrong row
fails that gate before it could reach here. What a table cannot hold — the operational judgement
— lives in the hand-written [venues overview](/docs/trader/venues).

## How the bridge is wired [#how-the-bridge-is-wired]

**Class: `live-exec-recon`.** A default build mounts a real execution client from this venue's credentials and includes the venue in the default reconcile set: `vike_mount::make_engine` has an ungated arm for it. With no credentials in the store the venue stays paper — absent credentials are the live gate — and `policy.venues.<id>` in `policy.toml` is consulted before the credentials and can only ever refuse (`vike_config::VenueMode::cap` is a minimum, never a maximum).

## Capabilities [#capabilities]

| Capability                   | Value |
| ---------------------------- | ----- |
| Modify (amend) an order      | yes   |
| Native batch submit / cancel | no    |
| Reduce-only                  | yes   |
| Combo (multi-leg) orders     | no    |
| Post-only                    | no    |
| Batch size cap               | 0     |
| Backfill: bars               | yes   |
| Backfill: ticks              | no    |

Live market data the bridge feeds: `bars`, `trades`, `depth`.

## Order kinds and triggers [#order-kinds-and-triggers]

Order kinds the adapter wires: `market`, `limit`, `stop`. Trigger types for the
conditional kinds: `stop-loss`. The vocabulary is the canonical one from
`vike_model::venue_caps::ORDER_KINDS`, not this venue's wire strings; the
[orders concepts](/docs/trader/concepts/orders) pages explain each kind's semantics and the per-venue
matrix.

## Time in force [#time-in-force]

"Supported" is what the adapter wires; "accepted" is what it will take from a strategy without
rejecting — a TIF can be accepted and then coerced or ignored on the wire, and that is what the
last column says (`vike_bridge_core::tif::venue_tif`).

| TIF | Supported | Accepted | On the wire             |
| --- | --------- | -------- | ----------------------- |
| GTC | yes       | yes      | not emitted on the wire |
| IOC | yes       | yes      | mapped to `ioc`         |
| FOK | yes       | yes      | mapped to `fok`         |
| GTD | no        | no       | unsupported             |
| Day | no        | no       | unsupported             |

## Margin [#margin]

Margin modes the adapter offers: `cross`, `isolated`, defaulting to `cross`.
What the exchange itself offers (a vendor-documentation transcription, `vike_model::venue_margin_support`):
`cash`, `cross`, `isolated`, switched `per-order-field`; the isolated-margin
wallet is adjustable.

## Fees [#fees]

Percentage maker/taker: **2 bps** maker, **5 bps** taker (the default schedule; venue tiers and rebates are not modelled). The schedule is `vike_model::fee_schedule_for`'s default row and is what the
[cost model](/docs/trader/backtesting/cost-model) charges in a backtest.

## Amending orders [#amending-orders]

A `modify` on this venue is applied in place, and the amended quantity is the order's new TOTAL size (the venue nets it against what has already filled)
(`vike_model::amend_semantics`).

## Attribution [#attribution]

An order tag in the `tag` field (max 16 chars); set `OKX_BROKER_CODE or OKX_BUILDER_CODE`. An absent or invalid code degrades to no attribution with a
byte-identical wire (`vike_model::attribution::attribution_for`).


# Polymarket operations (/docs/trader/venues/polymarket-operations)



[The generated Polymarket page](/docs/trader/venues/polymarket) renders the capability tables. This page
carries what a table cannot hold. This is the most trap-laden bridge in the workspace — no testnet,
two opt-in gates, a region pre-flight, chain-verified settlement and a metered cancel lane — and
every rule below exists because of something that happened.

## No testnet, so the venue is opt-in twice [#no-testnet-so-the-venue-is-opt-in-twice]

Every other venue has a demo tier. This one does not. `mount.rs`'s `poly_exec_enabled` puts it
plainly: "Polymarket has **no testnet**: every order this mounts is real money on Polygon mainnet,
so the venue is opt-in twice over (creds AND this flag) rather than the usual once." The second gate
exists so that "an operator who merely has keys in their `.env` — which the reconcile half, the data
feeds and the redeem poller all legitimately want — cannot accidentally arm order placement."

Two independent gates, both the exact string `"1"` rather than a fuzzy truthy parse, read from the
process environment first and the credential store second — where `config.rs`'s `first_token` takes
the first whitespace-separated token, so an annotated `.env` line (`POLY_EXEC=1   # real money`)
still arms:

| flag               | what it mounts                                                                                |
| ------------------ | --------------------------------------------------------------------------------------------- |
| `POLY_EXEC=1`      | the live `ExecutionClient` — real orders, and inseparably the authenticated user-WS fill pump |
| `POLY_RECONCILE=1` | the `ReconClient`, independently                                                              |

"The two compose: exec-only, recon-only, both, or neither." Both unset — the default — builds
nothing and makes **no network call**, and the arm compiles only under vike-mount's `polymarket`
feature, so a default build has no arm at all. Mounting exec starts the fill pump whether you want
it or not, deliberately: "on this venue every post-acceptance terminal arrives only on the user
channel, so exec without the pump would accept orders that can never reach a terminal." Both halves
share one registry and one L2 handshake, because "a fresh registry for the recon half makes every
order report come back with no client order id."

## The region pre-flight [#the-region-pre-flight]

Polymarket restricts **order placement** by region and nothing else: from a restricted egress "the
market feeds stream, `/auth/derive-api-key` succeeds and every authenticated READ … comes back
green, while a submit returns a 403". A wrong-region session looks healthy right up to the first
order, so a live exec mount asks the venue first, through the same proxy the orders will use.
`geoblock_action` is the decision: a `Blocked` verdict **refuses** the mount, naming the country and
region; an `Unknown` verdict — probe unreachable, body unreadable — only **warns**, because "an
unreachable pre-flight is evidence of nothing". Feeds are never gated on it.
`POLY_GEOBLOCK_OVERRIDE=1` skips the check, is read from the credential store only, and "ARMS
nothing on its own".

## The SOCKS egress [#the-socks-egress]

Every `POLY_PROXY_*` knob resolves through `egress.rs`'s `proxy_var`: "the REAL process env first,
the gitignored workspace `.env` map second". That second tier is a bug fix — values written where
every other Polymarket setting lives "were SILENTLY IGNORED", and the failure hid because "the
built-in defaults (`enabled = true`, `127.0.0.1:1080`) happen to match the usual tunnel; move the
tunnel to another port in `.env` and the agent kept dialling 1080." The fallback is a fixed
five-key allow-list (`PROXY_KEYS`), read once and cached.

`check_expected_egress` asserts the tunnel is really carrying traffic. It is opt-in and inert: with
`POLY_EXPECT_EGRESS_COUNTRY` unset it "performs **no network call at all**"; set it and a live smoke
"fails LOUDLY, naming the observed IP/country, instead of limping on". It rides the same
proxy-aware agent every REST call uses.

## Settlement and auto-redeem [#settlement-and-auto-redeem]

A market resolves on-chain, "the local book must flatten at its payout, and winning tokens must be
redeemed for collateral — none of which any CLOB endpoint reports as a fill"
(`settlement/mod.rs`). Nine modules answer that, all opt-in, with no composition-root wiring today:
a default build "never opens a Polygon RPC socket, never posts to the gasless relayer". Three gates,
one per driver — `POLY_CHAIN_WATCH=1` (the read-only chain watcher, "never signs, never sends a
transaction"), `VIKE_PM_RESOLVE=1` (the local settlement fill that flattens a resolved position and
moves no money), and `POLY_AUTO_REDEEM=1` plus credentials, with the `POLY_REDEEM_HALT` kill switch
checked every tick, for the poller that moves real money.

<Callout type="warn" title="redeemable: true is a resolution flag, not a winner flag">
  Measured on this repository's own mainnet wallet on 2026-07-23: **all four** held positions came
  back `redeemable: true`, three of them plain losers (`curPrice: 0`, `cashPnl: -100%`). Settling off
  the flag would have fabricated roughly 29 USDC of profit; redeeming off it submitted four relayer
  calls where one paid. Both drivers now price from the CTF's own `payoutNumerators` and **fail
  closed**: the settlement poller through `settlement/resolve.rs`'s `PayoutSource::Chain`, the default
  — "no chain verdict ⇒ the leg is not due and NOTHING is emitted this pass — a delay, never a guess"
  — and auto-redeem through `RedeemDeps::payout` ⇒ `redeemable_by`, which `ProdDeps` answers from the
  same numerators via a cached `ChainOracle`. An unreachable Polygon RPC means they settle nothing.
</Callout>

Chain payouts close three gaps the flag cannot: "a resolved LOSER with no redeemable row anywhere
settles, an 'ambiguous' condition settles correctly instead of being skipped, and a SPLIT resolution
(`payoutNumerators [1,1] / 2`) settles at its true 0.5." Auto-redeem then separates submitting from
settling: a relayer HTTP 2xx "means it accepted a signed batch … not that the redemption was mined,
and not that it succeeded", so each tick confirms in-flight redemptions against the chain before it
discovers and submits, and writes its ledger record before the relayer is contacted.

<Callout title="Cancels are metered here, and only here">
  This is the one venue in the workspace that sheds a cancel. A `Routine` cancel — a strategy's own
  requote churn — is refused while the cancel bucket sits at or below its reserve and returns a
  **non-terminal** `OrderCancelRejected`, so the order is still resting and the caller must re-offer
  it. Every other intent fires. The account-wide bulk cancel is never to be called directly: "it
  debits one token up front plus one per order the venue actually cancels, which can drive the cancel
  bucket NEGATIVE and lock out every subsequent cancel."
</Callout>

## Which reconcile policy is defensible [#which-reconcile-policy-is-defensible]

It depends on which gates are on, and `PositionDrift` — [one of the two kinds `hybrid` actually
folds](/docs/trader/concepts/reconciliation/policies) — is the mechanism in both hazards.
Reconciling **without** exec diffs live venue state against a paper engine, so on any token the
paper engine also traded it "folds the LIVE account's position into the PAPER engine's books at the
venue's avg price and books realized PnL the paper run never earned". Separately, a resolved market
moves position to cash with no fill, which surfaces as drift too, and is what the chain watcher
closes.

<Callout type="warn" title="POLY_RECONCILE=1 alone means quarantine only">
  Run reconcile-without-exec under `VIKE_RECONCILE_POLICY=quarantine`. `POLY_EXEC=1` plus
  `POLY_RECONCILE=1` — and `POLY_CHAIN_WATCH=1` for settlement truth — is what makes `hybrid`
  defensible: with exec mounted "both sides are the SAME account, so `PositionDrift` converges two
  views of one book instead of importing one into the other."
</Callout>

Market data is a separate matter — the feeds plane is keyless and links no signing crate — and the
historical collectors are covered under [data providers](/docs/trader/data-providers/polymarket).


# Polymarket (/docs/trader/venues/polymarket)




Polymarket is one of the 14 venues Vike Trader mounts through the shared bridge contract: the
runtime speaks to every venue through one `ExecutionClient` seam, and everything below is rendered
from the capability tables that seam is built on — [`caps_for`](/docs/trader/concepts/execution-client-seam),
`venue_margin_support`, `fee_schedule_for`, `amend_semantics`, `attribution_for` and `venue_tif`
in the Rust workspace — exported as `venues.json` at every release. This page cannot state a
stale capability: each table has a roster-completeness gate in the product tree, and a wrong row
fails that gate before it could reach here. What a table cannot hold — the operational judgement
— lives in the hand-written [venues overview](/docs/trader/venues).

## How the bridge is wired [#how-the-bridge-is-wired]

**Class: `feature-gated`.** The live arm compiles only under a vike-mount cargo feature; a default build has no arm at all and falls through to paper, byte-identical. Reconcile, where wired, sits behind the same feature plus the venue's own inner gates. A release binary built without the feature will never trade here whatever the credential store holds.

Two independent inner gates, both unset by default: `POLY_EXEC=1` and `POLY_RECONCILE=1`. Reconciling with `POLY_RECONCILE=1` but without `POLY_EXEC=1` is quarantine-only, because reconciling a live account against a paper engine would let `PositionDrift` — the one kind the `hybrid` policy auto-applies — import the live position into the paper books (`crates/bridges/polymarket/src/mount.rs`'s module header, which names both gates and their defaults). The hand-written companion, [Polymarket operations](/docs/trader/venues/polymarket-operations), carries the rest.

## Capabilities [#capabilities]

| Capability                   | Value |
| ---------------------------- | ----- |
| Modify (amend) an order      | no    |
| Native batch submit / cancel | no    |
| Reduce-only                  | no    |
| Combo (multi-leg) orders     | no    |
| Post-only                    | no    |
| Batch size cap               | 0     |
| Backfill: bars               | no    |
| Backfill: ticks              | no    |

Live market data the bridge feeds: `quotes`, `trades`, `book`.

## Order kinds and triggers [#order-kinds-and-triggers]

Order kinds the adapter wires: `market`, `limit`. Trigger types for the
conditional kinds: none. The vocabulary is the canonical one from
`vike_model::venue_caps::ORDER_KINDS`, not this venue's wire strings; the
[orders concepts](/docs/trader/concepts/orders) pages explain each kind's semantics and the per-venue
matrix.

## Time in force [#time-in-force]

"Supported" is what the adapter wires; "accepted" is what it will take from a strategy without
rejecting — a TIF can be accepted and then coerced or ignored on the wire, and that is what the
last column says (`vike_bridge_core::tif::venue_tif`).

| TIF | Supported | Accepted | On the wire            |
| --- | --------- | -------- | ---------------------- |
| GTC | yes       | yes      | mapped to `GTC`        |
| IOC | no        | yes      | coerced to FOK (`FOK`) |
| FOK | yes       | yes      | mapped to `FOK`        |
| GTD | no        | yes      | mapped to `GTD`        |
| Day | no        | yes      | coerced to GTC (`GTC`) |

## Margin [#margin]

Margin modes the adapter offers: `cash`, defaulting to `cash`.
What the exchange itself offers (a vendor-documentation transcription, `vike_model::venue_margin_support`):
`cash`, switched `not-applicable`; the isolated-margin
wallet is not adjustable.

## Fees [#fees]

Free in the default schedule (the venue's opt-in probability curve is deliberately not exported). The schedule is `vike_model::fee_schedule_for`'s default row and is what the
[cost model](/docs/trader/backtesting/cost-model) charges in a backtest.

## Amending orders [#amending-orders]

A `modify` on this venue is applied not at all — `modify` is unsupported here, so a change is a cancel and a new order
(`vike_model::amend_semantics`).

## Attribution [#attribution]

A signed builder address (no on-chain approval needed); set `POLYMARKET_BROKER_CODE or POLYMARKET_BUILDER_CODE`. An absent or invalid code degrades to no attribution with a
byte-identical wire (`vike_model::attribution::attribution_for`).


# A custom feature, proven (/docs/trader/tutorials/custom-indicator)



A study trains on a MATRIX — a column per feature, a row per bar, computed in one batch pass. A live
strategy computing that same feature per bar has to arrive at the same number for the same
timestamp, or the model receives inputs it never saw. Nothing errors; the edge simply degrades.
`vike_indicators::feature` is the seam that makes that failure unrepresentable, and this tutorial
walks one feature through it.

## Write one kernel, get the other free [#write-one-kernel-get-the-other-free]

```rust
use vike_indicators::feature::ColumnFeature;

/// Percent change over `lag` rows, floored at the row it answers for.
pub struct PctChange {
    pub lag: usize,
}

impl ColumnFeature for PctChange {
    fn vectorize(&self, x: &[f64]) -> Vec<f64> {
        (0..x.len())
            .map(|i| if i < self.lag { f64::NAN } else { x[i] / x[i - self.lag] - 1.0 })
            .collect()
    }

    fn reach(&self) -> usize {
        self.lag + 1
    }
}
```

That is the whole implementation. `vectorize` is the batch form and it is the REFERENCE — it is
what the study trains on. `FeatureStream` is the streaming form and it is PROVIDED: it retains
`reach` values and re-runs the feature's OWN `vectorize` over that tail, taking the final element.
There is deliberately no `on_value` method to override, so an implementor has no second kernel to
write and none to get wrong. Bit-identity is a property of the construction rather than of a test
that has to keep noticing.

The contract is two lines: `vectorize` returns exactly one value per input row, and the value at
row `i` reads only rows `i + 1 - reach() ..= i` — warm-up rows are `NaN`, nothing looks forward.
Before the buffer is full it holds the entire prefix `x[0 ..= i]`, which is exactly what the batch
form can read at that row, so the warm-up rows agree for the same reason the steady state does.

**Why this is not `Indicator`.** `vike_indicators::Indicator` streams a `vike_model::Bar` — OHLCV
plus a timestamp. A model feature is a rolling statistic over an ARBITRARY numeric column: a
funding rate, an open-interest series, a venue spread, a per-cohort aggregate. Pushing one of those
through a `Bar` means inventing five fields.

## Exactly one number is left to get wrong [#exactly-one-number-is-left-to-get-wrong]

`reach` — how many trailing rows, including the current one, a value can read. Over-declaring is
safe and merely wasteful. Under-declaring returns a different number from the streaming path,
silently, past a threshold no short test reaches. That is not a hypothetical shape:
`crates/vike-indicators/tests/parity.rs`'s `every_trimmed_indicator_is_truncation_invariant` exists
because six indicators shipped with exactly that defect, and were green because the gate ran 400
bars while the trim first fired at 512.

Two shipped features show what an exact reach looks like. `WindowFeature::reach` is
`period + lag` — every `window` kernel reads the `period` values ending `lag` rows back, so the
deepest row reached is `period + lag - 1` back and one fewer value is not enough.
`rolling::LaggedDiff::reach` is `lag + 1`, and that feature is deliberately NOT expressed as a
`WindowFeature`: a window kernel blanks its whole window when `min_periods` is unmet, so one NaN
inside `lag + 1` rows makes the answer NaN, while a lagged difference reads exactly two rows and
still answers a number when the rows between them are missing.

## Prove it with the shipped harness [#prove-it-with-the-shipped-harness]

The harness is `vike_indicators::test_support`, public API behind the crate's `test-support`
feature — a shipped build compiles none of it. It is a LIBRARY module rather than a `tests/` file
for a specific reason: a study's own feature definitions belong to whoever wrote the study and live
in the author's own tree, so a test binary inside this repository could never run on them.

```toml
[dev-dependencies]
vike-indicators = { version = "*", features = ["test-support"] }
```

```rust
#[test]
fn pct_change_streams_exactly_as_it_batches() {
    vike_indicators::test_support::assert_feature_parity("pct_change(5)", &PctChange { lag: 5 });
}
```

`assert_feature_parity` is the one call an author makes. It runs `assert_stream_matches_batch` over
every entry of `SHAPES` — `random-walk`, `trend`, `mostly-flat`, `high-vol`, `with-gaps`,
`near-bound`, each generated deterministically and each distinct, three of them gated to actually
contain what they are named for — then `assert_stream_matches_batch_per_group` over a stacked panel
of three unequal groups, so a boundary lands mid-window rather than on a convenient multiple of the
period, then `assert_reach_is_tight`. The series length is DERIVED as six times the reach, floored
at 400 rows, because a constant long enough for a 3-row window is nowhere near enough to truncate a
168-row one.

**The tolerance is zero.** Comparison is `f64::to_bits` equality with both-NaN counting as equal.
That needs no argument about float error budgets: the streaming form re-runs the same `vectorize`,
so there is no second arithmetic that could round differently.

Three refusals make the gate non-vacuous:

* `reach() == 0` is refused — a feature reads at least the row it answers for.
* A series no longer than the reach is refused, because the buffer would never evict a value and
  the assertion would compare a batch pass with itself while staying green with the reach declared
  arbitrarily wrong.
* `assert_reach_is_tight` asserts the OPPOSITE direction — that retaining one value FEWER changes
  the answer — so a reach padded to uselessness (`usize::MAX / 2` passes every parity assertion and
  streams nothing) is reported rather than rewarded. A reach past `MAX_TESTABLE_REACH` (2^20) is
  refused outright, because a stream retaining effectively everything is a batch pass wearing a
  streaming interface. A reach of 1 has no shorter tail to compare against and is reported as a
  no-op rather than as a pass.

<Callout type="warn" title="One stream per instrument">
  `FeatureStream`'s buffer is a rolling window over whatever it is fed, with no notion of an
  instrument. A caller with several instruments needs one stream each, or a `reset()` at the
  boundary — the same discipline `vike_analytics::signal::hysteresis` states for its own carried
  state, and the one `window::per_group` enforces on the batch side.
  `assert_stream_matches_batch_per_group` is what gates it.
</Callout>

## Which preset a feature should take [#which-preset-a-feature-should-take]

`WindowSpec` ships two. `WindowSpec::indicator(period)` is the chart preset: the window ends at the
current row, population variance. `WindowSpec::point_in_time(period)` is the model-feature preset:
the window EXCLUDES the current row (`lag = 1`) and uses sample variance. Pick the second for
anything a model trains on.

## The other custom indicator: a script the engine streams [#the-other-custom-indicator-a-script-the-engine-streams]

`ColumnFeature` is the route for a study's feature matrix. There is a second route, for a rule you
want a live strategy to CALL, and it needs no Rust at all: a file dropped into
`user_data/indicators/`.

The contract is state-first and is stated in `crates/vike-script/src/indicator.rs`'s module doc.
`on_bar(bar)` is required and is called exactly once per bar, in order. `init()`, `warmup()`,
`outputs()` and `overlay()` are optional. Inside `on_bar`, `this` IS the state and mutations to it
persist, so an author writes a recurrence the way they would think of one. Returning `()` means
"warming up" and reads as NaN.

`vike-cli init` writes two of them, deliberately unlike each other. The first keeps a window, which
is exactly the thing a strategy script cannot express on its own:

```rust
// The highest high of the last `lookback` bars.
//
// This is the shape a strategy script cannot write on its own: it has to remember earlier bars.
//
// `param()` makes `lookback` settable from the call site — `donchian_high(50)` — while keeping 20 as
// the default, so `donchian_high()` still works. Anything above a `fn` runs once per setting.

let lookback = param("lookback", 20);

// This one IS a price, so on a chart it belongs over the candles rather than in a pane of its own
// (the default). Delete this to see the difference — nothing else about the indicator changes, and
// a strategy calling it cannot tell either way.
fn overlay() {
    true
}

fn init() {
    #{ highs: [] }
}

// Until the window is full there is no "highest of 20", so say so with () -> NaN.
fn warmup() {
    lookback - 1
}

fn on_bar(bar) {
    this.highs.push(bar.high);
    if this.highs.len() > lookback {
        this.highs.remove(0);
    }
    if this.highs.len() < lookback {
        return ();
    }
    let hi = this.highs[0];
    for h in this.highs {
        if h > hi { hi = h; }
    }
    hi
}
```

The second keeps a recurrence instead — two numbers of state, no buffer, and the same work per bar
however long the series:

```rust
// Consecutive up-closes as a positive count, consecutive down-closes as a negative one.
//
// Contrast donchian_high.rhai: no window, no buffer — two numbers of state and the same work per
// bar however long the series.

fn init() {
    #{ prev: (), run: 0 }
}

// One bar, not zero: "up or down versus the previous close" cannot mean anything on the first bar,
// because there is no previous close yet. warmup() is the index of the first bar your value is real
// on, so leaving it at the default 0 here would be a claim that is one bar wrong.
fn warmup() {
    1
}

fn on_bar(bar) {
    if this.prev == () {
        this.prev = bar.close;
        return ();
    }
    if bar.close > this.prev {
        this.run = if this.run > 0 { this.run + 1 } else { 1 };
    } else if bar.close < this.prev {
        this.run = if this.run < 0 { this.run - 1 } else { -1 };
    } else {
        this.run = 0;
    }
    this.prev = bar.close;
    this.run
}
```

Those two ship from `crates/vike-cli/src/cmd/init/content.rs`'s `DONCHIAN_HIGH_RHAI` and
`STREAK_RHAI`. They are the two shapes worth copying.

## A third one, written for this tutorial [#a-third-one-written-for-this-tutorial]

The smallest useful shape is neither a window nor a recurrence. No state at all, one number per bar:

```rust
// range_pct — this bar's high-low range as a percentage of its close.
//
// The smallest useful shape: no window, no state, one number per bar.

fn init() {
    #{}
}

fn on_bar(bar) {
    if bar.close == 0.0 { return (); }
    (bar.high - bar.low) / bar.close * 100.0
}
```

And a strategy that calls both — the shipped window for a breakout level, the new stateless one to
insist the bar that breaks out is not itself already wide:

```rust
// quiet_breakout — buy a breakout, but only out of a quiet bar.
//
// Uses the shipped donchian_high user indicator for the breakout level and range_pct (written for
// this tutorial) to insist the bar that breaks out is not itself a wide, already-moved bar.
let lookback = param("lookback", 48.0);
let calm = param("calm", 1.0);
let qty = param("qty", 0.05);

fn on_bar() {
    let hi = donchian_high(lookback.to_int());
    let rng = range_pct();
    if hi.is_nan() || rng.is_nan() { return; }

    if close() > hi && rng < calm && position() <= 0.0 { market(1, qty); }
    if close() < hi * 0.97 && position() > 0.0 { market(-1, position()); }
}
```

`param()` declares the knobs. The CLI reads them back out of the file without running a backtest:

```sh
vike-cli backtest --list-params --script quiet_breakout.rhai
```

```text
lookback = 48
calm = 1
qty = 0.05
```

## The run: zero trades, and then zero trades again [#the-run-zero-trades-and-then-zero-trades-again]

```sh
vike-cli backtest --profile tut_breakout.toml
```

```text
{
  "final_equity": 10000.0,
  "funding_paid": 0.0,
  "max_drawdown": 0.0,
  "n_trades": 0,
  "name": "quiet_breakout — BTCUSDT 1h",
  "per_symbol_pnl": [
    [
      "BTCUSDT",
      0.0
    ]
  ],
  "profit_factor": 0.0,
  "sharpe": 0.0,
  "total_return": 0.0,
  "win_rate": 0.0,
  "zero_trade": {
    "causes": [
      {
        "code": "no-orders",
        "detail": "Over 8760 bar(s)/tick(s) nothing was denied, deferred, or gated and no trade closed, so no gate explains the flat result. The strategy most likely never submitted an order - check its entry condition and that it reads the SAME symbol the data is tagged with (bar-mode `snap_to_properties` re-tags bars as `SYMBOL.VENUE`, which a strategy routing on the bare symbol will miss).",
        "headline": "No order-blocking cause was detected."
      }
    ]
  }
}
...(diagnostic continues; the full JSON is in the run's report.json)
```

Zero trades over 8760 hourly bars. The report says so in a field of its own rather than leaving a
flat equity curve to be interpreted, and the `no-orders` cause is the honest one: nothing was
denied, deferred or gated, so no risk gate explains the result. The strategy simply never submitted
an order.

The obvious suspect is the `calm` filter. A 1% high-low range is tight for an hourly BTCUSDT bar, so
widen it to 3.0 and run the same profile again:

```text
{
  "final_equity": 10000.0,
  "funding_paid": 0.0,
  "max_drawdown": 0.0,
  "n_trades": 0,
  "name": "quiet_breakout — BTCUSDT 1h",
  "per_symbol_pnl": [
    [
      "BTCUSDT",
      0.0
    ]
  ],
  "profit_factor": 0.0,
  "sharpe": 0.0,
  "total_return": 0.0,
  "win_rate": 0.0,
  "zero_trade": {
    "causes": [
      {
        "code": "no-orders",
        "detail": "Over 8760 bar(s)/tick(s) nothing was denied, deferred, or gated and no trade closed, so no gate explains the flat result. The strategy most likely never submitted an order - check its entry condition and that it reads the SAME symbol the data is tagged with (bar-mode `snap_to_properties` re-tags bars as `SYMBOL.VENUE`, which a strategy routing on the bare symbol will miss).",
        "headline": "No order-blocking cause was detected."
      }
    ]
  }
}
```

Identical, field for field. A knob that tripled and changed nothing is not the knob that was
blocking, which moves the suspicion off the filter and onto the other term in the entry test.

## The off-by-one, and the run that followed it [#the-off-by-one-and-the-run-that-followed-it]

The shipped `donchian_high` pushes this bar's high into its window BEFORE taking the maximum. So the
value it returns is at least this bar's own high, and a close is never above its own high. The entry
test `close() > hi` is unsatisfiable on every bar of every series — no threshold, no data and no
parameter can make it fire. That is the whole bug, and it is invisible in both runs above.

The correction is one line of ordering: take the maximum of the window as it stands, then push. Call
that file `breakout_level`, point the strategy at it, and leave everything else alone — same
profile, same year of bars, same `calm`:

```text
{
  "final_equity": 8334.568427500006,
  "funding_paid": 0.0,
  "max_drawdown": 0.1839635835571801,
  "n_trades": 48,
  "name": "quiet_breakout — BTCUSDT 1h",
  "per_symbol_pnl": [
    [
      "BTCUSDT",
      -1180.6035000000015
    ]
  ],
  "profit_factor": 0.687335413608655,
  "sharpe": -1.0475904521415624,
  "total_return": -0.16654315724999946,
  "win_rate": 0.3125
}
```

Now the strategy trades, and it loses money. The account ends at 8334.57 from a 10000 start, a
16.65% loss, with a Sharpe of -1.0476 and a peak-to-trough drawdown of 18.4%. It won 31.25% of its
48 trades and its profit factor is 0.687, so the wins do not cover the losses. That is the result;
it is not a step on the way to a better one.

The BTCUSDT line reads -1180.60 rather than -1665. Those are different quantities:
`crates/vike-backtest/src/engine.rs`'s `per_symbol_pnl` is realized PnL plus the open position
marked to the last price, while `final_equity` is the account. Read `final_equity`.

What the run does not say is that the idea is dead. One symbol, one year of hourly bars, one
parameter point, 48 trades — far too few to separate a bad rule from a bad draw, and there is no
out-of-sample split here at all. It also says nothing about whether the `calm` filter helps, because
the two zero-trade runs proved only that the filter was never reached. It has still never been
tested against a version of this strategy that trades.

The result worth keeping is the smaller one, and it is about indicators rather than about breakouts.
An indicator whose arithmetic is one step out of order yields a strategy that silently does nothing,
and the zero-trade diagnostic pointed at the entry condition — which was written correctly, and
which was not where the defect lived.

## Which project's indicators actually answered [#which-projects-indicators-actually-answered]

Both runs above went through `vike-cli backtest`, which ships the SCRIPT to a service and never the
indicator files. The service resolves `donchian_high()` and `range_pct()` against ITS OWN
`user_data/indicators/`, installed once at startup by
`crates/vike-datahub/src/datahub_cli.rs`'s `install_user_indicators`.

<Callout type="warn" title="The server's set wins, and the client cannot see it">
  No hash or version of the indicator set is exchanged with the request. The same script run against
  two services with different indicator directories returns different numbers, and nothing in the
  response says so. `install_user_indicators` therefore logs the directory and the installed names at
  startup even on success, so that two runs which disagree can be told apart by comparing two logs.
  Shipping the set with the request is the real fix and is a protocol change.
</Callout>

Editing an indicator file after the service started changes nothing until it is restarted, for the
same reason: the load happens once.

## Where next [#where-next]

* [Writing an indicator](/docs/trader/scripting/writing-an-indicator) and
  [User indicators](/docs/trader/indicators/user) — the full script contract, including `outputs()` for a
  multi-line indicator.
* [Loading indicators](/docs/trader/scripting/loading-indicators) — which directory is read, when, and
  what a rejected file does.
* [Sweep and walk-forward](/docs/trader/tutorials/sweep-and-walk-forward) — what the losing run above
  would need before its number meant anything.
* [A Rhai strategy from scratch](/docs/trader/tutorials/rhai-strategy-from-scratch).
* [Training](/docs/trader/research/training) and
  [Feature importance](/docs/trader/research/feature-importance).
* [Train a model](/docs/trader/tutorials/train-a-model).
* [Property tests](/docs/trader/developer/testing/property-tests).


# A funding carry across two venues (/docs/trader/tutorials/funding-carry-two-venues)



A funding carry is long the venue that pays and short the venue that charges, sized so the two legs' price exposure cancels. What is left is the funding differential — and a round-trip taker cost that has to come out of it first. This tutorial runs that trade over recorded funding on two venues and shows where the cost comes from.

## The sign law, once [#the-sign-law-once]

`crates/vike-strategy/src/funding_carry.rs`'s header freezes the convention so no page has to re-derive it. On every wired perp venue a **positive `funding_rate` means longs pay shorts**. Per interval, per unit notional, a long position's cashflow is `−funding_rate` and a short's is `+funding_rate`. So a carry that longs venue `L` and shorts venue `S` collects `funding_S − funding_L` — the **gross differential**, non-negative exactly when the long leg sits on the lower rate, which is what `rank_best_carry` orients every pair to.

The controller never books that money. The header is explicit: the runtime already folds `Event::Funding` settlements into account cash through `vike_exec::Account::apply_funding`, so this strategy only decides.

## What the cost is [#what-the-cost-is]

`roundtrip_taker_cost(long_taker, short_taker)` is `2 × (long_taker + short_taker)` — each leg crosses as a taker on entry *and* exit, so four crossings. `net_carry_edge(gross, cost, hold_periods)` amortises that one-time cost over an assumed holding of `hold_periods` funding intervals: `hold_periods × gross − cost`. The default `hold_periods = 1.0` is the conservative single-period breakeven — the pair must clear its **entire** round-trip cost out of one interval's differential.

`rank_best_carry` scores every unordered venue pair rather than just the extremes, and its doc says why: because the round-trip cost is per venue, a fat differential onto a high-fee venue can lose to a thinner one onto cheap venues, so the max-gross pair is not always the max-net pair. ## Where the taker rate comes from

`FundingCarryController::quotes` pulls each venue's taker fee from the static per-venue registry, `vike_model::fee_schedule_for(venue).maker_taker_rates().1`. That table is `crates/vike-model/src/fees.rs`, published tier-0 with no token discount, each row cited: binance spot **10 / 10 bps**, `binance-perp` **2 / 5**, bybit **2 / 5.5**, okx **2 / 5**, hyperliquid **1.5 / 4.5**, aster spot **0.5 / 4** — the last of which is a measurement rather than a claim, swept live across twelve pairs on 2026-08-05, all twelve identical.

<Callout type="warn" title="On a backtest, this static row is the whole answer">
  `vike_mount::resolve_fee_schedule` prefers a venue's real fetched rates, but only consults `ReconClient::fetch_fee_rates` when a reconcile client was built, which is gated on `VIKE_RECONCILE=1` and off by default. The `fees.rs` row therefore decides on essentially every paper and backtest mount. Before the `binance-perp` row existed, a `BTCUSDT.P` mount was charged the spot 10/10 — five times the maker fee.
</Callout>

## The run [#the-run]

`crates/vike-backtest/tests/funding_carry_demo.rs` is the end-to-end fixture, and its profile is the shape to copy. Two `[[data.series]]` entries under their own venues, `engine.attach_funding = true`, and a `[strategy.params.venues]` table mapping each symbol to the venue it routes under:

```toml
[data]
kind = "bar"
interval = "1h"
[[data.series]]
venue = "binance"
symbol = "BTCBIN"
[[data.series]]
venue = "okx"
symbol = "BTCOKX"

[engine]
cash = 100000.0
attach_funding = true

[strategy]
name = "funding_carry"
[strategy.params]
qty = 1.0
entry_threshold = 0.0
time_limit_ms = 14400000
[strategy.params.venues]
BTCBIN = "binance"
BTCOKX = "okx"
```

The fixture seeds binance funding at **+0.02*&#x2A; and okx at **−0.01** every 8 hours: a gross differential of 0.03 against a round-trip cost of `2 × (0.001 + 0.0005) = 0.003`, so the net edge clears an `entry_threshold` of `0.0` comfortably. Those rates are a deliberately fat fixture, not a market observation — the point is that the arithmetic is visible.

Three behaviours are pinned there, and they are the three you should reproduce:

* **Two-leg**, with `symbol` left empty: a leg opens on *both* carry venues from one mount, long the low-funding one and short the high.
* **Single-leg**, with `symbol = "BTCBIN"`: only that symbol's leg opens, while the cross-venue book still informs the decision — the other venue is observed and never traded.
* **Inert**, with no `venues` map: both series route to one default venue, the funding book never reaches two venues, `rank_best_carry` returns `None`, and the run ends with zero trades and zero funding accrued. The venue map is what unlocks the carry.

## Attaching the funding series [#attaching-the-funding-series]

`engine.attach_funding` window-joins the store's `funding` series onto the price bars for the same `(venue, symbol)`, so the bar-loop accrual charges once per interval rather than once per bar. Four properties from its own doc are worth carrying:

* It is **bar mode only** — a profile that sets it with `data.kind = "tick"` is rejected by `BacktestProfile::validate`, not ignored.
* The price interval must be **no coarser than the funding cadence**. If more than one event lands in a price bar's window only the last is kept, and the collision is logged loudly.
* Events predating the first price bar are dropped, with a count on the warning.
* On but with no stored funding data is a **warning and unchanged bars**, never an error — so a silent zero-funding run is a thing to check for, not to assume away.

## The limitation to plan around [#the-limitation-to-plan-around]

The differential-compression and flip exit is built and tested (`should_close_carry`, precedence Flipped → ProfitTarget → Compressed) but **is not wired through today's seam**: `Controller::evaluate` is invited only while a pair is flat, so a held carry exits through its leg's `TripleBarrier` — the `time_limit_ms` in the profile above — not through a funding re-check. That is why the fixture sets a four-hour time limit. Plan the exit as a barrier, and read `hold_periods` as what it is: a constructor knob the live-params bag has no field for, so a re-tune leaves it untouched.

Next: [funding carry](/docs/trader/strategies/templates/funding-carry) for the parameter table, [the controller seam](/docs/trader/strategies/controller-seam) for how a controller becomes a strategy, and [run profiles](/docs/trader/backtesting/run-profiles) for the rest of `[engine]`.


# The grid template on paper (/docs/trader/tutorials/grid-on-paper)



`grid` is a two-sided ladder maker, and it is a good first mount because everything it does is
visible in a few minutes of bars: it rests limits, they fill, it takes profit one step back, and it
re-arms. Mounting it on paper puts it on the PRODUCTION live core — the single-writer runtime, the
ingest lanes, the RiskGate, the one live order path — with `vike_paper::PaperExecutionClient`
standing in for a venue, so there is no real money, no credential and no geo risk anywhere in the
run.

## What the strategy does [#what-the-strategy-does]

`crates/vike-strategy/src/grid_dca.rs`'s `Grid` rests `rungs` buy limits BELOW and `rungs` sell
limits ABOVE an `anchor`, spaced by `step`, `size` units each — the sell side is an opening short
when flat. Each rung is an oscillator: when its ENTRY limit fills, the strategy places a
take-profit limit one `step` back toward the anchor; when THAT fills — a completed round trip — the
entry re-arms. Inventory is therefore bounded by `rungs · size` per side.

A HARD STOP fires when price leaves `[anchor − band, anchor + band]`: the strategy flattens the net
position and HALTS — no re-arms, no new legs.

The knobs, with the defaults `Grid::from_params` falls back to:

| key            | meaning                                                  | default                     |
| -------------- | -------------------------------------------------------- | --------------------------- |
| `anchor`       | `"first"` or `"fixed"`                                   | `"first"`                   |
| `anchor_price` | the fixed anchor, when `anchor = "fixed"`                | `0.0`                       |
| `step`         | price gap between rungs                                  | `1.0`                       |
| `rungs`        | rung count per side                                      | `3`                         |
| `size`         | order size per rung                                      | `1.0`                       |
| `band`         | hard-stop half-width around the anchor                   | `10.0`                      |
| `bounded01`    | a 0..1-bounded market: clamp the band, skip walled rungs | `false`                     |
| `tick`         | the 0..1 market tick, consulted only when `bounded01`    | `0.001`                     |
| `symbol`       | an explicit symbol override                              | the first bar/tick's symbol |

<Callout type="warn" title="The portable Broker surface has no cancel verb">
  `Broker` is the common denominator of the backtest and live stacks — `submit_market` /
  `submit_limit` plus the account and market reads — and `Grid` is designed to need no cancel. The
  price is that a resting limit placed before a halt or a take-profit cannot be pulled, so the
  strategy re-flattens every bar while halted and a stray fill from a residual limit is closed on the
  next event. Inventory stays bounded; the behaviour is documented rather than hidden.
</Callout>

## The profile, and the four refusals it must pass [#the-profile-and-the-four-refusals-it-must-pass]

A `vike-tradehub` profile names the mount and the strategy in the same vocabulary a backtest
profile uses, resolved through the same `vike_strategy::strategy_by_name` registry — so the profile
that was backtested is the profile that trades.

```toml
venue = "binance"
symbol = "BTCUSDT"
interval = "1m"
seed_cash = 10000.0

[strategy]
name = "grid"

[strategy.params]
step = 40.0
rungs = 4
size = 0.001
band = 600.0
```

`[strategy.params]` faces four separate refusals at profile LOAD, and each one is the case the
previous passes:

1. **`unknown_params`** — a key no reader reads. A `from_params` reader ignores what it does not
   recognise, so `sizee = 2` is not an error but `size` at the compiled default.
   `vike_strategy::PARAM_KEYS` declares what each name actually reads.
2. **`mistyped_params`** — a known key carrying an unusable value. `and_then(Value::as_…)` yields
   `None` for a wrong type exactly as it does for an absent key, so quoting a number
   (`size = "2"`) mounts the default just as surely as misspelling it does.
3. **`misrouted_params`** — a key that is read, well-typed, and then OVERWRITTEN by the mount.
   `resolve_intent_symbol` and `resolve_intent_venue` stamp the MOUNT's own venue and symbol onto
   every intent, so a params `symbol` that disagrees with the mount would pass the first two rules
   and send orders somewhere else. `PARAM_ROUTES` declares which keys those are.
4. **`unarmable_params`** — a whole table that passes all three and still describes NO ORDER AT
   ALL. `grid` is one of the two measured instances: `bounded01 = true` with `step` left at its
   compiled `1.0` is one rung spacing across the entire 0..1 domain, and it was measured at zero
   broker calls. `Grid::arms_no_rung` answers that from the same code that rests the rungs. It is
   decidable only because `arm` builds its whole order set from the params plus one anchor, once —
   the wider rule "refuse a mount that would place no orders" is not safe, because a strategy
   waiting on a market condition places none either.

The mount then ECHOES the RESOLVED configuration, including knobs the profile never states — a log
that merely repeats the operator's table is a claim about the operator, and it is false in exactly
the case worth logging.

## Paper, and what it is faithful to [#paper-and-what-it-is-faithful-to]

`vike_paper::PaperExecutionClient` owns a resting book and fills it with the backtest ENGINE'S OWN
public primitives — `BarFillModel::fill_price`, `resolve_intrabar_fills`, `adverse_fill_price` and
`fee` — so "backtest equals paper" is true by construction rather than by review, and gated bit for
bit by `vike-backtest`'s `tests/r7_gate.rs`. The equivalence holds for `Gtc` / `Ioc` / `Fok`; it
does not hold for the expiring time-in-forces, where paper enforces the resting deadline and the
simulator ignores TIF — a divergence no strategy can reach today, since every request the runtime
builds is `Gtc`.

## Getting a live feed behind it [#getting-a-live-feed-behind-it]

The daemon's DEFAULT paper mount proves the lifecycle and the stdio control channel with NO live
feed at all. To watch the grid react to a real market while every order stays on paper, arm the
`tradehub_live` flag, which mounts the same strategy on the real twelve-venue `build_node` core AND
wires that venue's own live feed — and leave the arming ceiling where it is.

`policy.venues.<venue>` in `<project>/settings/policy.toml` is a per-venue ceiling (`paper` \<
`demo` \< `live`) that `vike_mount::make_engine` consults FIRST, above the credential read: a
`paper` venue returns the paper client having loaded no credential, fetched no instrument grid and
opened no socket. Its default is `paper` for every venue, so a box with no `[venues]` table mounts
all paper whatever the credential store holds, and the ceiling can only ever REFUSE — a `live` line
arms nothing by itself. The daemon additionally validates the venue and symbol against the set it
has actually wired for live, and hard-errors rather than falling back silently.

## Where next [#where-next]

* [The grid template](/docs/trader/strategies/templates/grid) and
  [The strategy registry](/docs/trader/strategies/the-registry).
* [The paper exchange](/docs/trader/concepts/paper-exchange) and
  [Risk and arming](/docs/trader/concepts/risk-and-arming).
* [Arm a venue](/docs/trader/guides/arm-a-venue) and [Policies](/docs/trader/reference/settings/policy).
* [The A-S maker on paper](/docs/trader/tutorials/spread-maker-on-paper).


# Tutorials (/docs/trader/tutorials)



Each of these is one run followed from the first command to the number at the end. They are ordered
here by what you need before starting, not by difficulty: the first group needs nothing but the
binaries, the last needs a recorded tape or a fitted model.

The output blocks are captures, not examples. Where a figure is illustrative rather than measured,
its page says so where it prints it.

## Nothing but the binaries [#nothing-but-the-binaries]

<Cards>
  <Card title="RSI mean-reversion backtest" href="/docs/trader/tutorials/rsi-mean-reversion-backtest" description="The shipped example from init to a report on the demo tape, and how to read what the report says." />

  <Card title="A Rhai strategy from scratch" href="/docs/trader/tutorials/rhai-strategy-from-scratch" description="Write, validate and backtest an interpreted strategy against the same seam a compiled one uses." />

  <Card title="A custom feature, proven" href="/docs/trader/tutorials/custom-indicator" description="Implement a feature over one numeric column and prove its streaming form equals its batch form, bit for bit." />

  <Card title="A multi-timeframe strategy" href="/docs/trader/tutorials/multi-timeframe-strategy" description="Synthesise a higher timeframe from one base stream and read it without look-ahead." />
</Cards>

## Searching and validating [#searching-and-validating]

<Cards>
  <Card title="Sweep, then walk forward" href="/docs/trader/tutorials/sweep-and-walk-forward" description="Search a grid with a ranked sweep, then put the winner through an anchored out-of-sample walk-forward." />

  <Card title="Bayesian parameter search" href="/docs/trader/tutorials/tpe-parameter-search" description="Run a TPE search over a sweep profile and compare it against successive halving and the exhaustive grid." />

  <Card title="Monte Carlo and overfitting" href="/docs/trader/tutorials/monte-carlo-and-overfitting" description="Ask a finished backtest how much of its path was luck, and how much of its parameter choice was fitting." />

  <Card title="Pairs stat-arb with a cost gate" href="/docs/trader/tutorials/pairs-stat-arb" description="The pairs template over two real symbols with its round-trip cost floor armed." />
</Cards>

## Against a paper book [#against-a-paper-book]

<Cards>
  <Card title="The grid template on paper" href="/docs/trader/tutorials/grid-on-paper" description="Mount the grid strategy on the production live core with the paper exchange behind it." />

  <Card title="The A-S maker on a paper book" href="/docs/trader/tutorials/spread-maker-on-paper" description="Mount the Avellaneda-Stoikov maker on the live core and watch it quote against a paper book." />

  <Card title="A funding carry across two venues" href="/docs/trader/tutorials/funding-carry-two-venues" description="Open a delta-neutral perp carry from recorded funding rates, and watch the fee table decide the outcome." />
</Cards>

## Needs a recorded tape, a journal or a model [#needs-a-recorded-tape-a-journal-or-a-model]

<Cards>
  <Card title="Record a feed, then replay it" href="/docs/trader/tutorials/record-and-replay" description="Accumulate your own tape with the recorder, stop it without losing the buffer, and replay it." />

  <Card title="Tick replay with a queue model" href="/docs/trader/tutorials/tick-replay-with-queue-model" description="Replay a tape and make a resting maker order wait its turn in the queue." />

  <Card title="A VPIN study over a recorded tape" href="/docs/trader/tutorials/orderflow-vpin-study" description="Fold a trade tape into cumulative volume delta, a footprint grid and two flavours of VPIN." />

  <Card title="Replay a journal and pass the fence" href="/docs/trader/tutorials/journal-replay-determinism" description="Turn on the write-ahead journal, re-fold a recorded session through the real core, and read the verdict." />

  <Card title="Fit a model and read what it learned" href="/docs/trader/tutorials/train-a-model" description="Fit a gradient-boosted classifier through the pinned trainer, then turn the saved model into a signal." />
</Cards>

<Callout title="None of these place a real order">
  Every tutorial runs against the backtester, a recorded tape or the paper exchange. Two of them mount
  on the production live core — with paper behind it, which is the point: the same core, the same
  gates, and nothing reaching a venue.
</Callout>


# Replay a journal and pass the fence (/docs/trader/tutorials/journal-replay-determinism)



The command journal's payoff is not that you can read it. It is that a recorded session can be re-derived through the same single-writer runtime and **proven bit-identical** — which gates the journal format itself, because any nondeterminism in the fold surfaces as a mismatch. `crates/vike-core/src/replay.rs` is that proof, and this tutorial runs it.

## Turn the journal on [#turn-the-journal-on]

Journaling is off by default, so the ordinary desktop and headless paths stay zero-overhead and byte-identical. `journal_config_from_env` describes exactly two ways in, in precedence order:

1. **`VIKE_RUN_PROFILE=<run.toml>`** — load that run profile and use its `[sinks].journal` mapping. The profile is **authoritative**: it decides even when that means "no journal", so a profile can never be silently overridden. A set-but-broken profile disables journaling and logs a warning rather than falling through.
2. **`VIKE_JOURNAL_DIR=<dir>`** — a single-knob quick opt-in at the default cadence, with `VIKE_JOURNAL_SNAPSHOT_EVERY=<n>` optionally overriding the snapshot cadence. Consulted **only** when `VIKE_RUN_PROFILE` is unset.

Neither set means no journal. The same directory is reachable from settings as `config.journal_dir`, with `VIKE_JOURNAL_DIR` as its environment spelling — see [environment variables](/docs/trader/reference/environment).

Run a session — paper is fine, and is the right place to start — then stop it cleanly so the shutdown snapshot is written.

## Replay it [#replay-it]

The `replay_journal` binary (its reference page is [replay-journal](/docs/trader/reference/binaries/replay-journal)) takes the journal directory and nothing else. It prints four things:

```text
journal records  : <total records in the SOURCE journal, commands and snapshots>
snaps verified   : <n>
final state hash : <16 hex digits>
engine <venue>/<symbol>: <n> open orders, <n> positions, balance <x>
```

The first line is labelled honestly in the source: `records` is the **total** source journal record count, not the length of the tail that was re-folded. A failure prints `REPLAY FAILED:` with the error and exits non-zero.

## What it actually does [#what-it-actually-does]

Two entry points share one engine. `replay_offline` — the one the binary calls — restores from the journal's **first** `Snap`, re-folds the whole tail, and fences the reproduced final hash against the source's **last** `Snap` hash. `restore_from_journal` is the crash-restart twin: it restores from the **latest** snapshot, re-folds the usually-empty crash tail, and deliberately has **no fence**, because it is a restore rather than a proof.

Restoring from the first checkpoint is the load-bearing choice. Restoring from the latest would leave nothing to replay on a clean run — its exit snapshot already reflects everything — which is a worthless fence. Cadence snapshots are taken *after* the fold, so every command before the first snapshot is already folded into it and every command after is re-folded forward, re-deriving the whole post-checkpoint history.

The replay core is the real one, with three substitutions:

* a pure no-op `ReplayClient`, because the original venue events are already journaled as `Ingest::Event` records and get re-pumped — a client that *also* emitted events would double the state;
* a `QueueClock` replaying the tail's recorded `now_ms`, so timestamp-derived state such as an order's creation time matches;
* a temporary journal whose snapshot cadence is effectively infinite, so only the exit snapshot fires.

The fence is **final-hash equality**, not per-record comparison: the replay core mints its own sequence numbers, so a per-sequence comparison is impossible, and re-folding from the first checkpoint reproducing the exact final state is the essential guarantee.

## What the fence covers now [#what-the-fence-covers-now]

It used to check exactly one thing — `state_hash(&engines)` — while the restore hands a restart three more values nothing looked at. A fold bug that resurrected a consumed conditional arm, dropped a live one, mis-scoped a mass cancel or rewound a counter reproduced a bit-identical engine hash and passed. `replay_offline` now adds two fences over the same oracle:

* **the resting conditional books**, through `conditionals_hash` against the ones the source's last snapshot recorded — on a v8-or-later journal only, since `Snap.conditionals` was defaulted in at v8 and an older snapshot reads its books back empty;
* **the `coid_seq` / `arm_seq` counters**, as **floors rather than equalities** (`fence_floor`). An overshoot is legal and deliberately produced — a mark-refused tail trailing arm, or a pre-v7 base snapshot — while an undercount is the id-reuse bug worth catching.

Four exclusions remain, each argued rather than overlooked: `now_ms` and the account snapshot's marks, which non-journaled market data mutates on every message; a trailing arm's ratcheted extreme, the books' analogue of those marks; the GTD sweep's fire-once suppression set, which cannot move the hash in either direction; and the publish/cadence bookkeeping — `dirty`, `journaled_since_snap` and the bounded recent-events ring — which decides only when a snapshot or GUI publish fires, never what it contains, and is not restored at all, so a fence would have nothing to compare.

## Reading a failure [#reading-a-failure]

`ReplayError`'s variants are a triage table, and two distinctions matter more than the rest.

<Callout type="warn" title="Truncated is not HashMismatch">
  A journal whose **read** stopped at a torn frame reports `Truncated { cause }`, returned *instead of* `HashMismatch` and only where that would have been returned. The records the fences see are then a prefix of what the session wrote, so the fence target is not the exit snapshot but whichever mid-session checkpoint survived — and re-folding past a mid-session checkpoint necessarily produces a different hash. `HashMismatch` reads as "the engine diverged, this journal cannot be trusted"; for a torn tail that is a misreading of the ordinary consequence of a crash. A truncated journal whose fences all pass still succeeds exactly as before.
</Callout>

`RestoreMismatch { field, expected, got }` is the other split: the engine state matched, but something else the restore hands back did not — a book or a counter. Different cause, completely different triage path. `Unsupported` covers the two shapes this replay does not handle: a multi-engine base snapshot, and a tail carrying watchdog-tick records, which the submit-acknowledgement timeout and both dead-man switches still arm and which are not deterministic functions of the journal. `Empty` means no snapshot at all — a truncated or absent journal, since a clean shutdown always writes one. `Io` is a real disk fault, kept distinct so a determinism tool never folds one into `Unsupported`.

## Upgrading between sessions [#upgrading-between-sessions]

Segments stamp a format version, and this build reads and **resumes** anything in the accepted range rather than rejecting it, so upgrading a binary never costs an operator their live journal. The rule that makes the range safe is that a version step may only **add** a record variant or a defaulted field. Determinism is unaffected by reading an older journal: a v4 journal replayed by a newer binary yields exactly the record sequence a v4 binary saw, because the added variants are ones v4 never wrote, and the additive records that do exist are replay-neutral observations the tail extraction ignores. What an older journal costs is fence COVERAGE rather than determinism: below v8 the conditional-books fence above is skipped, while the hash fence and the counter floors still run.

Next: [the command journal](/docs/trader/concepts/journal) for the format and the sync policy, [replay](/docs/trader/concepts/journal/replay) for the reference page, and [stop, liquidate, restart](/docs/trader/guides/stop-liquidate-restart) for what a restart replays and what it does not.


# Monte Carlo and overfitting over a finished run (/docs/trader/tutorials/monte-carlo-and-overfitting)



A finished run gives you one equity path and one Sharpe ratio. Neither is a result on its own: the path is the order the trades happened to land in, and the Sharpe is the maximum of however many configurations you searched. `vike-analytics` answers both questions, and this tutorial runs them over a run you already have.

## Where the inputs are — and are not [#where-the-inputs-are--and-are-not]

<Callout type="warn" title="report.json does not carry what these statistics need">
  A finished single run persists a common `manifest.json` beside `report.json` under `<project>/user_data/runs/<run_id>/`. But `BacktestReport` is deliberately **compact** — it is the bin's human table, its `--json` schema and the sweep's ranking source, not an everything-drawer — and it carries no trade list and no equity curve. Both families below read `BacktestResult`'s `trades` and `equity_curve`, so they run against the result **in process**, from a caller that ran the backtest, not against the persisted report. And only the single-run path persists at all: a sweep, a euler refinement or a TPE run answers with a `SweepReport`, a different document and a run kind of its own, and writes nothing.
</Callout>

Spell the Monte Carlo module `vike_analytics::montecarlo`. `vike-backtest` re-exports most of that crate's modules at its own root but deliberately not this one — re-adding a name is only correct once a call site needs the shorter spelling, and none ever has.

## How much of the path was ordering [#how-much-of-the-path-was-ordering]

`mc_resample(trade_pnls, start_equity, n_sims, seed, method)` builds `n_sims` synthetic equity paths from the observed trade list. Two methods, each documented by what it preserves:

* **`Shuffle`** reorders the trade list, preserving the exact multiset of P\&Ls per path. Terminal equity is therefore the same on every path; what varies is the *shape* — the sequence, and so the drawdown.
* **`Bootstrap`** samples with replacement, so a path may draw one trade several times and another never. Terminal equity varies too.

You get back `terminal` (each path's final equity), `max_drawdowns` (each path's max-drawdown fraction, through the shared `metrics::max_drawdown`) and `curves_sample` — at most 20 full curves, thinned evenly across the simulations, for plotting. `confidence_bands(curves, qs)` turns equal-length curves into per-step percentile bands.

`mc_summary(trade_pnls, start_equity, n_sims, seed, ruin_pct)` is the one-call version, running the **shuffle** method and returning terminal equity at the 5th, 50th and 95th percentiles, max drawdown at the 50th and 95th, `prob_loss` (the share of paths ending at or below the starting equity) and `risk_of_ruin` (the share ending at or below `ruin_pct × start_equity`).

Two things to decide before you read a number from it.

**Which P\&L you feed.** `Trade.pnl` is *gross price* P\&L and `Trade.fees` is the round-trip cost, carried separately. Feeding `pnl` gives you a pre-cost distribution; feeding `pnl − fees` gives you the one you can spend. Pick deliberately and say which in the write-up.

**What the seed does and does not promise.** The module is seeded for run-to-run reproducibility **within this implementation**, and it says outright that there is no golden fixture for it: porting CPython's exact random number generator was ruled out as not worth it for one file, so no exporter ever froze one. The provenance survives the decision — when the two implementations were run side by side, the same seed produced statistically equivalent, not bit-identical, paths.

## Whether the Sharpe survives the search [#whether-the-sharpe-survives-the-search]

`crates/vike-analytics/src/overfit.rs` has one sanctioned entry: `sharpe_moments(equity_curve)`, which produces the four inputs everything else takes — `sr_per_obs`, `n_obs`, `skew`, `kurt`. It exists because two unit conventions each carry a footgun, and the annualized-Sharpe one has already shipped as a real bug. Never hand `overfit::` an annualized figure; the annualized Sharpe is a display quantity for a different reader.

From one run you can compute the probabilistic Sharpe and nothing more — the deflated Sharpe and the probability of backtest overfitting both need the **set of trials**. That is the whole point, and `audit_selection` is the function that refuses to let you forget it.

<Callout type="warn" title="Feed it the candidates, not the winner">
  `effective_n_trials` derives its count from the trials it is fed, and `pbo_cscv`'s matrix columns must be the full candidate set. Feed either only the *survivors* of a search and you deflate against a trial count that understates by orders of magnitude — the gates will happily pass garbage, because they are only as good as the trial count they are given. The failure is silent and easy to commit: pick the best pair out of fifty, hand its curve alone to `deflated_sharpe_ratio`, read a reassuring number. `audit_selection` takes the full candidate arrays **plus the selected index** precisely so the mistake is visible: a survivors-only call reports `n_candidates == 1` and says so in the verdict. Inconsistent inputs return `None` — an unauditable selection is not a passing one.
</Callout>

The audit reports `selected_trades` beside the Sharpe, and its doc says why: a mean-reversion family dies by **starvation** — too few divergences — before it dies by unprofitability, and a Sharpe-ranked sweep cannot see that. It matters most for pair selection, a maximum over `N(N−1)/2` correlated candidates, a search far larger than any parameter sweep and one that happens *before* the sweep.

## Reading the verdict [#reading-the-verdict]

`overfit_verdict(pbo, deflated_sr, wf_consistency)` folds the three into a level plus its reasons, on a fixed point scale: PBO above 0.5 scores two points and above 0.2 scores one; a deflated Sharpe below 0.5 scores two and below 0.9 scores one; walk-forward consistency below 0.5 scores one. Three points or more is `High`, one or two is `Medium`, zero is `Low`. A `NaN` PBO is **not assessed** — it gets its own reason row rather than a vote toward `Low`.

The Studio has this wired end to end, and it is the fastest way to see the numbers move. Its sweep computes the deflated Sharpe over every trial's per-period Sharpe, and PBO over the full transposed returns matrix at the canonical 16 splits — computed off the UI thread, with the PBO left `NaN` unless there are at least two entries and at least 16 observations. The results pane then shows the single-run half (Sharpe, observations, skew, kurtosis, PSR) and the set half (deflated Sharpe, PBO, overfit risk, walk-forward consistency when a walk-forward ran) with the verdict's reasons as notes.

One habit is worth more than any of these numbers: read `n_candidates` first. It is the first number to check when a result looks too good.

Next: [Monte Carlo](/docs/trader/analytics/monte-carlo) and [overfitting](/docs/trader/analytics/overfitting) for the reference pages, [sweeps](/docs/trader/backtesting/sweeps) and [walk-forward](/docs/trader/backtesting/walk-forward) for producing the trial set honestly, and [results](/docs/trader/gui/studio/results) for the pane that renders it.


# A multi-timeframe strategy (/docs/trader/tutorials/multi-timeframe-strategy)



A multi-timeframe strategy trades one series while consulting a coarser one — enter on the 1-minute bar only when the 4-hour trend agrees. Nothing in Vike Trader asks you to load two series to do that. `crates/vike-backtest/src/timeframe.rs` synthesises the coarse stream from the fine one, and its header states the property the whole tutorial rests on: the module is **look-ahead-safe by construction**, because a coarse bar only becomes visible once its window has fully elapsed, and the engine enforces that visibility.

## The vocabulary [#the-vocabulary]

`parse_timeframe` converts a string to milliseconds by delegating to the single interval vocabulary in `vike_model::time::interval_ms`, so a `"30s"` series that loads from the history store is a valid backtest timeframe alongside `"1m"`, `"4h"` and `"1d"`; anything else comes back as an error naming what was expected. `parse_timeframe_accepts_seconds_and_rejects_garbage` pins both halves, including the rejections (`"1x"`, `"m"`).

`resample(bars, target_ms)` aggregates fine bars into coarse ones **aligned to epoch windows** — one coarse bar per window, chronological, and the final window may be partial. Window membership is a floor-mod of each bar's timestamp, so a `"4h"` series starts at 00:00, 04:00, 08:00 UTC regardless of where your slice begins.

## The two reads, and why they differ [#the-two-reads-and-why-they-differ]

The engine builds the aggregates for you. `EngineParams` carries a `timeframes: Vec<String>` field, and `crates/vike-backtest/src/engine.rs` resamples each registered timeframe **per symbol** at construction. A strategy then asks the broker:

```rust
// One resample per (symbol, timeframe), done once at engine construction.
let params = EngineParams { timeframes: vec!["1h".into(), "4h".into()], ..Default::default() };

// Inside on_bar, per base bar:
let closed: &[Bar] = broker.bars_for(&self.symbol, "4h");      // complete windows only
let forming: Option<Bar> = broker.forming_for(&self.symbol, "4h");
```

`BarSeriesBuffer::bars_for` documents the rule both spellings implement: the coarse list up to — **but not including** — the window that contains `now`, delivered on complete, no look-ahead. `SimBroker::bars_for` is that read per symbol, with the same arithmetic. That exclusion is the no-look-ahead rule: on a base bar stamped 09:15 you can see the 04:00–08:00 coarse bar and never the 08:00 one, because it has not closed. `forming_for` is the explicit opposite: the still-forming coarse bar up to `now`, or `None` when no base bar has started the current window. Asking for a timeframe that was never registered panics with `timeframe … not registered`, so a typo in a string is loud rather than silently empty.

<Callout type="warn" title="bars_for is a SimBroker method, not a Broker method">
  The trait every strategy is generic over exposes `bars(symbol)` — the **base** series — and nothing else. `bars_for` and `forming_for` are inherent methods on `SimBroker`, so a strategy that calls them is written `impl Strategy<SimBroker>` and is bound to the simulator. A strategy meant to stay portable across brokers resamples for itself from `broker.bars(symbol)`, using the same `resample` function the engine uses — same arithmetic, same window alignment, one owner of the law.
</Callout>

## The shared buffer [#the-shared-buffer]

`BarSeriesBuffer` (`crates/vike-backtest/src/bar_buffer.rs`) is that second path packaged. Construct it with the base bars and the timeframes you want; `bars_for(tf, now)` and `forming_for(tf, now)` answer exactly as the engine's per-symbol twins do, and `add_live_bar` appends a base bar and refreshes every registered timeframe's aggregate — the forward mode, for a series that is still growing. Its header records one Rust adaptation worth knowing before you read the code: the buffer **owns** the base-bar `Vec` and the engine reads through it, where the ported original shared a list by reference. One owner, same observable behaviour.

One numeric detail is deliberate rather than incidental. `forming_for` folds the window's volume through `vike_model::py_sum`, the Neumaier-compensated sum, while high and low fold in order — the mirror of the [parity gate](/docs/trader/concepts/parity-gate)'s rule that a ported `sum()` site uses `py_sum` and an explicit accumulation loop stays a naive fold. Reproduce that if you write your own aggregation; a plain `.sum()` there is a bit-level divergence.

## What a profile cannot reach [#what-a-profile-cannot-reach]

There is no `[engine]` key for this. `crates/vike-backtest/src/harness/profile.rs`'s `EngineCfg` declares no `timeframes` field, so a TOML [run profile](/docs/trader/backtesting/run-profiles) cannot register a coarse timeframe and the `backtest` bin cannot run a multi-timeframe strategy that depends on `bars_for`. Multi-timeframe work today is a Rust one: construct `EngineParams` yourself, or resample inside the strategy from `broker.bars(symbol)` — which is also the version that survives being mounted anywhere else.

## Verify it [#verify-it]

Two checks are worth doing before you trust a signal built this way.

1. **Count the coarse bars against the window arithmetic.** Over a slice of `n` one-minute bars, a `"4h"` resample yields one bar per 240-minute epoch window the slice touches, with the last one partial. If your count disagrees, your slice boundaries are not where you think.
2. **Assert the exclusion.** At a base timestamp inside a coarse window, `bars_for` must not return that window's bar and `forming_for` must return it. A strategy that reads a coarse close before the window shut is the classic backtest that cannot be reproduced live, and this is the one line of test that catches it.

Next: [timeframes](/docs/trader/backtesting/timeframes) for the reference page, [the portfolio engine](/docs/trader/backtesting/portfolio-engine) for how per-symbol state is laid out, and [tick replay](/docs/trader/backtesting/tick-replay) when the base stream is ticks rather than bars.


# A VPIN study over a recorded tape (/docs/trader/tutorials/orderflow-vpin-study)



`vike-orderflow` is a pure trade-aggregation core: no I/O, no rendering, no threading. You hand it `vike_model::TradeTick`s and it hands back order-flow primitives. This tutorial takes a recorded tape off the history store and builds three studies from it — CVD, a footprint, and VPIN — in the order the crate itself puts them.

## Get the tape [#get-the-tape]

`HistStore::scan_trades(venue, symbol, range)` returns the executed trades for that series in the range, timestamp-ascending. That is the whole input. Recording one is [record a feed, then replay it](/docs/trader/tutorials/record-and-replay); note there that Binance serves a trade tape and a conflating depth lane but no quotes and no lossless book, which matters for the mid-price variant below.

## The one decision everything inherits [#the-one-decision-everything-inherits]

`crates/vike-orderflow/src/classify.rs` calls itself "the one load-bearing semantic of the whole crate", and it is one line of logic: `is_buyer_maker` is the Binance aggregate-trades convention — the buyer was the resting maker, sitting on a bid, so the **aggressor was the seller**. `is_buyer_maker == false` classifies Buy (an ask was lifted); `true` classifies Sell (a bid was hit). `signed(t)` then routes the trade's **full** size to the aggressor's side, and `delta = buy_vol − sell_vol` everywhere downstream.

If your tape's flag means something else, every number on this page is sign-flipped. Check it once, at the source.

## Cumulative volume delta [#cumulative-volume-delta]

The smallest study, and the one to sanity-check the tape with. `CvdAccumulator::push(&trade)` folds one trade and `value()` reads the running sum; `CvdAccumulator::from_trades(&trades)` is the batch twin over a slice. Non-positive sizes are skipped rather than folded, in this and every other builder.

Fold the whole slice both ways. They must agree bit for bit — that is the crate's own gate discipline, described in its header as streaming-versus-batch parity compared on `f64::to_bits`, where the batch path is a genuinely separate slice computation rather than `push` in disguise. If your own aggregation disagrees with `from_trades`, the bug is yours.

## A footprint [#a-footprint]

`FootprintBuilder::new(tick_size)` asserts a positive tick size, `push` accumulates each trade into its price bucket, and `close_bar()` returns a `FootprintBar` — a bar index plus ascending `PriceBin` cells, each carrying `buy_vol` and `sell_vol` at one price. `FootprintBuilder::from_bars(&bars, tick_size)` is the batch twin over trades already grouped per bar.

To group them, use the bar builders in the same crate: `TickBarBuilder`, `VolumeBarBuilder` and `DollarBarBuilder` each emit an `OrderflowBar` carrying `o/h/l/c`, `buy_vol`, `sell_vol`, `delta`, `trade_count` and first/last timestamps. The volume and dollar builders **split a trade proportionally across a threshold boundary** — by volume and by cumulative price·size respectively — which is the same convention VPIN uses below, so the two agree about where a bucket ends.

The bucketing itself is owned by `profile.rs`, not re-derived: the footprint reuses that module's `PriceBin`, its price-to-bucket rounding and its grid-to-bins transform. The same module builds a `VolumeProfile` with its point of control and a 70% value area, if what you want is volume-at-price rather than per-bar cells.

## VPIN, twice [#vpin-twice]

`crates/vike-orderflow/src/vpin.rs` ships two estimators, and the difference is what they need from the tape.

**`Vpin`** chops the stream into fixed-volume buckets of `bucket_volume`; a trade that overflows the open bucket spills its remainder into the next. Each completed bucket scores an order-flow toxicity imbalance `|Vbuy − Vsell| / Vbucket` in `[0, 1]`, and VPIN is the rolling mean of the last `window` completed buckets — `DEFAULT_VPIN_WINDOW` is 50 — maintained as an O(1) rolling sum, never a window re-scan on the hot path.

```rust
let mut v = Vpin::new(bucket_volume);          // aggressor-classified, window = 50
for t in &trades {
    for imbalance in v.push(t, None) {         // one value per bucket this trade COMPLETED
        // ... a big trade can complete several
    }
}
let toxicity = v.committed();                  // None until the first bucket completes
```

`committed()` reads completed buckets only. `forming_bucket()` and `interim()` are pure reads that fold the open bucket's partial imbalance in as the newest window sample — evicting the oldest when the window is full — without mutating state, which is the convention the bar builders use too.

For a feed with no real aggressor flag, construct with `has_aggressor = false` and pass the prevailing mid to `push`: `price >= mid` classifies Buy, otherwise Sell. A missing mid falls back to the aggressor flag, so **no trade is ever dropped**.

**`BvcVpin`** is the canonical Easley, López de Prado and O'Hara (2012) VPIN, and it needs only price and volume. A bucket's directional split comes from its price change rather than trade-level tags: `buy_frac = Φ((P_i − P_{i−1}) / σ_ΔP)`, with `Φ` the standard-normal CDF over `libm`'s erf and `σ_ΔP` the population standard deviation of bucket price changes over the last `window` buckets. The bucket imbalance is then `|2·buy_frac − 1|`. `directional_bias()` gives the signed version — above zero is buy-toxic, below is sell-toxic — so a caller can route the magnitude onto a per-side gate.

<Callout type="warn" title="BvcVpin needs one more bucket than you expect">
  `value()` is `None` until `window` bucket **imbalances** exist, and that takes `window + 1` bucket closes: the first close only sets the `P_{i−1}` reference, because a price *change* needs two. A study that stops early and reads `None` has not found a degenerate tape — it has not finished warming up.
</Callout>

Its degenerate guards are worth knowing before you tune a bucket size. A non-positive or non-finite `bucket_volume` and a `window` below 1 **panic at construction**. When `σ_ΔP` is undefined — during warm-up, or on a flat tape — the estimator falls back per bucket to the tick rule, which classifies a bucket wholly by the sign of `ΔP`, so a flat tape yields `0.0` rather than a `NaN` from `Φ(0/0)` and a one-way tape yields `1.0`. `VolumeClassifier::TickRule` selects that behaviour outright.

The module documents a default for the window and none for the bucket size, and that is honest rather than an omission: bucket volume is a property of the instrument's own tape, and the guards above tell you what the extremes do.

Next: [VPIN](/docs/trader/orderflow/vpin), [CVD](/docs/trader/orderflow/cvd) and [footprint](/docs/trader/orderflow/footprint) for the reference pages, [buy/sell classification](/docs/trader/orderflow/classification) for the semantic in full, and [in the GUI](/docs/trader/orderflow/in-the-gui) for where each study renders.


# Pairs stat-arb with a cost gate (/docs/trader/tutorials/pairs-stat-arb)



`pairs_zscore` is the shipped statistical-arbitrage template: a rolling z-score of the spread
`A − β·B`, entered when the spread is stretched and exited when it reverts. What makes it worth
running is the gate in front of the entry — it refuses a trade whose expected convergence does not
exceed a full round trip INCLUDING carry.

<Callout type="warn" title="This is a measurement instrument, not a product">
  `crates/vike-strategy/src/pairs.rs`' own module doc says so. Published evidence, measured on ten
  Binance perpetuals at 2 bp per crossing — an order of magnitude cheaper than a retail taker pays —
  decomposes a round trip as gross `+0.15%`, trading cost `−0.12%`, funding `−0.18%`, net `−0.15%`.
  The signal is real and it is about 15 bp. The purpose of the template is to reproduce that verdict
  on your own data, with your own fees and venues, through your own overfitting gates. Expect a
  negative; that is the successful outcome.
</Callout>

## 1. A two-symbol profile [#1-a-two-symbol-profile]

The strategy needs both legs' bars, so the profile's data slice names two symbols:

```toml
name = "pairs_zscore — BTCUSDT / ETHUSDT 1h"

[data]
kind = "bar"
interval = "1h"
venue = "binance"
symbols = ["BTCUSDT", "ETHUSDT"]
from = "2025-01-01T00"
to = "2026-01-01T00"

[engine]
cash = 10000.0
fee_rate = 0.0005

[strategy]
name = "pairs_zscore"

[strategy.params]
symbol_a = "BTCUSDT"
symbol_b = "ETHUSDT"
period = 20
entry_z = 2.0
exit_z = 0.5
notional = 1000.0
```

Every key this table does not set keeps the value in `PairsZScore::default` — `beta` 1.0,
`taker_fee` 0.0005, `half_spread_bps` 1.0, `hold_intervals` 3.0, no funding assumption and no
half-life gate. Sections 5 and 6 are about what those defaults assert.

Both slice forms reach the same code path — `DataCfg::resolved_series` expands the frozen
`venue` + `symbols` pair exactly as it resolves a cross-venue `[[data.series]]` array — so a pair
whose legs live on different venues is the same profile with the longer spelling.

`PARAM_KEYS`' `pairs_zscore` row declares every key the reader takes and its TOML type:
`symbol_a`, `symbol_b`, `period`, `entry_z`, `exit_z`, `beta`, `notional`, `taker_fee`,
`half_spread_bps`, `hold_intervals`, `funding_a`, `funding_b`, `max_half_life`. `period` is a COUNT
read through `as_f64` and then rounded, so it is declared `Number` and `period = 2.6` is legal
input that resolves to `3` — a coercion no type check can see.

## 2. Fetch both legs [#2-fetch-both-legs]

Public klines, no credentials, no venue account:

```sh
backtest --fetch binance:BTCUSDT:1h --from 2025-01-01T00 --to 2026-01-01T00
```

```text
  8760 bars returned, covering 1735689600000..=1767222000000; 8760 rows written
```

The second leg is the same command with the other symbol. A pair needs both spans present before
the profile runs — a leg that is short does not error, it simply never completes a step.

```sh
backtest --fetch binance:ETHUSDT:1h --from 2025-01-01T00 --to 2026-01-01T00
```

```text
  8760 bars returned, covering 1735689600000..=1767222000000; 8760 rows written
```

## 3. The first run traded nothing, and the profile never said so [#3-the-first-run-traded-nothing-and-the-profile-never-said-so]

The first attempt at this tutorial guessed its parameter names instead of reading them off the
registry. That produced a complete run and no orders at all:

```sh
backtest --profile tut_pairs.toml
```

```text
name:          pairs_zscore — BTCUSDT / ETHUSDT 1h
final_equity:  10000.00
n_trades:      0
no trades executed - probable cause(s), most likely first:
  [1] No order-blocking cause was detected.
      Over 8760 bar(s)/tick(s) nothing was denied, deferred, or gated and no trade closed, so no gate explains the flat result. The strategy most likely never submitted an order - check its entry condition and that it reads the SAME symbol the data is tagged with (bar-mode `snap_to_properties` re-tags bars as `SYMBOL.VENUE`, which a strategy routing on the bare symbol will miss).
```

The diagnosis is right, and it is the only signal you get. `PairsZScore::from_params` is a READER:
it ignores a key it does not know and falls back to a default for a key that is absent. Both
symbols default to the EMPTY string, and that constructor's own doc states the consequence —
`symbol_a` and `symbol_b` are required in practice, because with either empty the strategy never
routes an order.

Nothing upstream catches it either. `StrategyCfg` types `params` as an arbitrary `toml::Value`, so
`deny_unknown_fields` never looks inside it, and `vike_strategy::unknown_params` — the check that
would have named the misspelling — runs in `vike-tradehub` at mount time, not in a backtest. A
backtest's whole defence here is `ZeroTradeReport::analyze`, which is why a flat run prints a
ranked diagnosis instead of an all-zero table.

The key names are not a guess anywhere. `crates/vike-ops/src/docs_data.rs`'s `template_record`
exports one record per `PORTABLE_STRATEGIES` name carrying that name's `PARAM_KEYS` row and its
`LIVE_CAPABLE` verdict. The six keys the profile above sets come from there.

## 4. The corrected run [#4-the-corrected-run]

Same tape, same span, the keys spelled as the registry exports them:

```sh
backtest --profile tut_pairs.toml
```

```text
name:          pairs_zscore — BTCUSDT / ETHUSDT 1h
final_equity:  9984.62
total_return:  -0.1538%
n_trades:      90
win_rate:      57.7778%
sharpe:        -0.0851
max_drawdown:  2.0435%
per_symbol_pnl:
  BTCUSDT: 21.90
  ETHUSDT: 9.09
```

**It lost money.** A year of hourly bars on the two largest crypto instruments, a cost-gated
spread, and the account finished 15.38 down on 10,000.

Ninety closed trades is forty-five spread round trips: `flatten` exits both legs together, so a
completed trip books one closed trade on each symbol. Out of a year of hourly z-scores, forty-five
entries is the cost floor rejecting most band breaks rather than a strategy sitting idle.

Now the line worth stopping on. **Both legs are positive** — `+21.90` on BTCUSDT and `+9.09` on
ETHUSDT, about `+31` between them — while the account is down. That is neither a contradiction nor
a reporting bug.

`per_symbol_pnl` is built from each symbol's running `realized`, which accumulates
`FillOutcome::realized_pnl` — documented as GROSS price PnL on the closing quantity. The fee is
carried separately, and `SimBroker::apply_fill` takes it straight out of cash with `cash -= fee`.
Fees never enter the per-symbol column. The roughly 46 dollars between the two numbers is what the
crossings cost.

So the run is a picture of a strategy that was right more often than not, on both legs, and paid
more for the privilege than being right was worth. That is the template's thesis reproduced on one
pair.

**What it does not say.** It is not evidence that pairs trading loses money: one pair, one venue,
one year, one parameter set, one fee rate. A Sharpe of `-0.0851` is a hair below zero, so this run
is statistically indistinguishable from flat, and reading a verdict of either sign into it would be
the overfitting the template exists to expose.

It is also not a market-neutral result. `beta` stayed at its default `1.0`, which sizes the hedge
in equal UNITS rather than equal dollars, so one unit of the BTC leg was hedged with one unit of
ETH — a few percent of the first leg's dollar value. Fit your own beta before reading the sign.

And it does not validate the cost model, because the cost model here is an assumption:
`half_spread_bps` was 1.0 and `hold_intervals` 3.0 because nothing set them otherwise. A wider real
book refuses more entries; a cheaper one lets more through. Section 6 is the knob you owe a number
to.

## 5. The two things this template fixes [#5-the-two-things-this-template-fixes]

**Beta SIZES the hedge leg.** The structure is adapted from a published implementation that fits
`beta` by OLS, uses it only to define the residual, and then splits the legs 50/50 by dollar value
— beta-blind, so the position is not beta-neutral despite beta being computed. Here
`beta_neutral_qtys(notional, price_a, price_b, beta)` returns `(notional/price_a, β·qty_a)`, and
refuses outright (`None`) on a non-finite or non-positive beta rather than inverting a leg behind
your back. With `beta = 1` that is equal UNITS, not equal dollars — section 4 is what that default
looks like in a report.

**The barriers are symmetric and cost-gated.** The prior art's `+1% / −5%` global barriers are
EV-neutral by construction on a driftless process (`5/6·1% − 1/6·5% = 0` exactly) while looking
excellent over a short sample. Here `should_enter` requires the z-score outside `entry_z` AND the
expected convergence `edge` to exceed the total cost, and `should_exit` fires on reversion into
`exit_z` or on a sign flip relative to the z the position was opened at. The edge is deliberately
`(|z| − exit_z)·sd`, not the full `|z|·sd` — you exit at the exit band, not at the mean.

## 6. Where the cost number comes from [#6-where-the-cost-number-comes-from]

`vike_model::spread_quote` prices what a multi-leg spread actually costs to trade rather than how
its mid looks. Its sign rule is the load-bearing part: BUYING a spread means lifting the ask of
every positive-ratio leg and hitting the bid of every negative-ratio leg. A naive `bid_A − bid_B` /
`ask_A − ask_B` construction takes the same side on every leg, which understates crossing cost and
produces a CROSSED quote whenever the short leg is wider than the long one.

When the cost is unknowable — a crossed or missing book — `should_enter` is `false`. An unpriceable
trade is not a free one.

Two knobs decide how honest the gate is:

* **`half_spread_bps`** is the assumed book width, since bars carry no L2. It is not optional in
  spirit: leaving it at zero asserts a frictionless book, which is the assumption this strategy
  exists to test.
* **`hold_intervals`** is how many funding intervals the carry half of the floor is charged for. It
  is always used on an entry check — nothing a bar carries replaces it. `funding_a` / `funding_b`
  are the rates it multiplies, until a bar for that leg carries a funding rate of its own; that rate
  is then remembered and used for every later entry check on that leg, funding-less bars included.

`max_half_life` is an opt-in regime gate on top: refuse entry when the spread's OU half-life exceeds
that many bars, or is NaN — not mean-reverting at all is a stand-down, not a pass. `<= 0.0` disables
it.

## 7. What else the report carries [#7-what-else-the-report-carries]

The z-score kernel is bit-identical to `vike_indicators::pairs::spread_zscore` — not merely the
same formula but the same running-sum recurrence, asserted bitwise by
`inline_zscore_matches_the_indicator_seam` — so a spread you plot on a chart and a spread the
strategy trades are the same number over the same window.

`zero_trade` is present ONLY when the run closed no trades AND its equity never moved, which is why
section 3's output carries a diagnosis and section 4's carries a metrics table. Once trades exist,
the reading is yours to do.

<Callout type="warn" title="pairs_zscore does not trade live today">
  `vike_strategy::LIVE_CAPABLE` refuses the name with its reason: it is TWO-LEG and needs
  `symbol_a` + `symbol_b` as declared mount legs admitted into the venue engine's `extra_symbols`.
  A mount declares no legs today, so the second leg's bars would never arrive and its orders would be
  dropped at `ExecutionEngine::accepts_symbol`. `vike-tradehub` refuses it at profile LOAD rather
  than mounting a strategy that would silently never submit. Everything above is a backtest of a
  strategy you cannot currently mount, and the registry export says so in the same record that names
  its keys.
</Callout>

## Where next [#where-next]

* [The pairs-zscore template](/docs/trader/strategies/templates/pairs-zscore) and
  [pairs indicators](/docs/trader/indicators/pairs).
* [Cost model](/docs/trader/backtesting/cost-model) and [Objectives](/docs/trader/backtesting/objectives).
* [Sizing and zero-trade diagnosis](/docs/trader/analytics/sizing-and-zero-trade) — the ranked causes
  section 3 met, in full.
* [Funding carry across two venues](/docs/trader/tutorials/funding-carry-two-venues) — the other
  cost-dominated template.
* [The strategy registry](/docs/trader/strategies/the-registry) — why a name can resolve and still be
  refused.


# Record a feed, then replay it (/docs/trader/tutorials/record-and-replay)



If you want to backtest a market you have actually watched, you have to record it first. `crates/vike-recorder/src/lib.rs` states the reason plainly: a customer has no production box and no warehouse, the recorders behind the data product share no code with the terminal, so the terminal has to accumulate the tape itself.

It is its own binary on purpose. Recording needs venue feeds, and those drag a signer, a WebSocket stack and TLS into whatever links them — keeping them out of the backtest server means a panic in feed parsing cannot take serving down. Not the desktop app, because a tape that exists only while a window is open has a hole wherever you closed it. Not the trading daemon, because recording must run whether or not you are trading, and a daemon restart must not punch a hole in the tape.

## The profile [#the-profile]

One reviewable TOML names the store and what to record. From the shipped `crates/vike-recorder/recorder.example.toml`:

```toml
store = "market_data/hist"

[[subscribe]]
venue = "polymarket"
family = "btc-updown-5m"
backfill = "off"

[maintenance]
interval_secs = 300
min_parts = 4
```

A `family` is general across venues, not a Polymarket-shaped concept: Polymarket resolves one to live tokens over its Gamma API because its token ids rotate every five minutes, while a static venue resolves the same key as a glob filter over its instrument list. Explicit `symbols` stay per-symbol with no grouping — grouping only pays across a wide subscription. A subscription names one or the other, never both.

<Callout type="warn" title="Two things about that store line">
  The directory name `hist` is not a free choice: it is the name every binary's own default resolves to (`vike_model::state_path`'s `HIST_SUBDIR` under `PROJECT_DATA_DIR`). A store called anything else is one the code cannot name, and a reader run without `--store` opens `<project>/market_data/hist`, finds nothing, and reports zero rows rather than failing. And the **relative** path resolves against the process working directory — right for a daemon whose unit sets `WorkingDirectory`, wrong for every command you run by hand. Measured: a hand-run single-tick run from a source checkout wrote its tape into the checkout while the project's own `market_data/` stayed empty.
</Callout>

Every struct in this file is `deny_unknown_fields`, so a misspelled key is refused **by name**, with the line number and the keys that would have been accepted. That is a refusal rather than a nicety: `webhook` for `webhooks` left an operator believing a pager was armed, a misspelled `retention_days` kept the tape forever after they asked for thirty days, and `backfil` silently fell back to venue-REST backfill — which on Polymarket cannot restore the book at all.

## Building and dry-running it [#building-and-dry-running-it]

Venue support is a Cargo feature, because a bridge is heavy: a build recording only static-symbol venues should not link an EIP-712 signer. A venue this build has no feature for is a **startup error naming the feature to rebuild with**, never a silent no-record. Build `vike-recorder` with `--features polymarket` (or `binance`), then run it with `--profile <file>` and `--once`.

`--once` runs a single tick and exits: it proves the profile parses, the store opens and each family resolves to live symbols, without leaving a daemon running. **Read its exit code, not its log** — `0` only if every feed ended that tick with a live subscription, `4` otherwise, naming each feed that would record nothing. It exited `0` on a total resolve failure until 2026-08-08.

One capability note before you plan a study around it: Binance's declared caps are bars, trades and depth — &#x2A;*`quotes: false`, `book: false`** — so a Binance recording is the trade tape plus the conflating depth lane under its own `kind=depth` series. A lossless Binance L2 book is not obtainable in this workspace by any means, and `depth` is deliberately not a rename of one.

## Stopping it without losing the tape [#stopping-it-without-losing-the-tape]

One stop flag, many triggers: a control word on stdin (`quit` / `shutdown` / `stop` / `exit`), and **SIGTERM and SIGINT** through `vike_ops::stop`'s `install_handlers`, so a service-manager stop, a bare `kill` and Ctrl-C all reach the same teardown.

Until that handler existed SIGTERM reached none of it — and the flush is where the tape was lost, on every restart of every box. On Windows there is no POSIX signal, so the same `install_handlers` call bridges the console control events instead — Ctrl-C, Ctrl-Break and a window close all raise the same flag, and a recorder running in a console stops as gracefully there as a service stop does on Linux. The caveat is that a console event needs a console: a recorder started detached has neither one nor a stdin anybody can type into, and the stop-file trigger `vike-ops` also offers is armed by `vike-tradehub` alone — so on that path `taskkill` is still a kill, not a stop.

Four words, not three: `crates/vike-datahub/src/recorder.rs`'s `control_loop` matches `exit` alongside the other three, while that file's module doc and its reply to an unrecognised word both list only three. Follow the code — `exit` works.

Teardown order is load-bearing: unsubscribe every feed **first**, then shut the sink down. The other order leaves feed threads pushing rows into a channel whose writer is gone, and those rows are counted as dropped with no reporter left to announce them. The whole sequence is budgeted end to end, because a service manager follows SIGTERM with SIGKILL — a feed-stop budget plus a bounded flush tail, summing to what the shipped unit's `TimeoutStopSec` is checked against, ordered flush-first so a hard cap abandons a compaction pass and never the rows.

`[maintenance]` is optional and **its absence means defaults, not off**: the recorder commits once per buffer flush, and a busy series was measured writing 23 parts in 150 seconds for one family's book at about 57 KB each — roughly 13,000 files a day if nothing merges them, and every later scan pays for all of them.

## What lands, and how [#what-lands-and-how]

Rows arrive through `RecorderSink` (`crates/vike-data/src/live_rec.rs`), which never blocks a feed thread — it only ever `try_send`s a row and bumps a dropped counter on a full or disconnected channel — and does every store write on one dedicated writer thread that owns the store handle. Book recording is the **raw** `book_update` lane; the folded-state `book` verb is a documented no-op, because a folded `L2Book` is not serialisable and carries no delta or replay information. Buffers flush on row count, on age, on a UTC-date rollover, or at shutdown, so a buffer never straddles a day and never outlives the process.

The silence watchdog is a pair: one module decides which subscribed series stopped receiving rows, another decides who is told. Both are always on — a silent series is logged and alerted — while **exiting** on silence is opt-in, because a venue can be legitimately quiet.

## Replaying it [#replaying-it]

Point a tick [run profile](/docs/trader/backtesting/run-profiles) at that store root, passing `--store <project>/market_data/hist` to the `backtest` bin. That flag falls back to `$VIKE_HIST_STORE`, then to the `<project>/market_data/hist` of a project `$VIKE_SETTINGS_DIR` declares outright, then to `<repo>/market_data/hist` while the checkout that built the binary still exists, then to the project the working directory sits in, and finally to a per-user data directory — the same precedence the collector bins resolve through, and the root and the rung that chose it are logged.

The replay merges each symbol's quotes, trades and book events into one timestamp-ordered stream with the tie-break **Book, then Quote, then Trade** — book first because a live derived quote follows the book application that produced it — and a symbol with zero rows of all three kinds is skipped with a warning rather than failing the run, so an all-sparse window degrades to an empty but valid result. The streaming loader is pinned bit-identical to the bounded one by `streaming_equals_bounded_bit_eq`, so which of the two you reach for changes memory shape and never numbers.

Next: [record a live feed](/docs/trader/guides/record-a-feed) and [replay a recorded session](/docs/trader/guides/replay-a-session) for the task versions, [tick replay](/docs/trader/backtesting/tick-replay) for the loader, and [tick replay with a queue model](/docs/trader/tutorials/tick-replay-with-queue-model) for what having the book on disk buys you.


# A Rhai strategy from scratch (/docs/trader/tutorials/rhai-strategy-from-scratch)



A Rhai script is not a second-class strategy path. `vike_script::RhaiStrategy<B>` implements
`vike_model::Strategy<B>` — the same seam every compiled Rust strategy is driven through — so the
backtest simulator and the live core mount it with no special case. What differs is the host
surface: a script cannot see a broker, only a handful of registered functions.

## The shape of a script [#the-shape-of-a-script]

Three hooks, each a zero-argument `fn`, all optional. `RhaiStrategy::compile_with_indicators`
detects which of `on_start` / `on_bar` / `on_stop` the AST defines and calls only those.

```rust
// Top level: runs EXACTLY ONCE, at compile.
let len = param("len", 20.0);
let qty = param("qty", 1.0);

fn on_bar() {
    let m = sma(len.to_int());          // read first, every bar
    if m.is_nan() { return; }           // warm-up
    let target = if close() > m { qty } else { 0.0 };
    let delta  = target - position();
    if delta >  1e-9 { market( 1,  delta); }
    if delta < -1e-9 { market(-1, -delta); }
}
```

**The top level runs once and never again.** `compile` executes it through
`Engine::run_ast_with_scope` and `run_hook` then calls with `CallFnOptions::default().eval_ast(false)`,
because rhai's default re-evaluates an AST's top level on every call — which would make a bare
top-level `buy(1.0);` resubmit an order on every hook invocation. Anything that one-time run
recorded is discarded: the intents, and the indicator caches too, so the first real `on_bar` is the
first bar any indicator has ever seen.

**A script holds no cross-bar mutable state.** `run_hook` clones the persisted scope for each call,
so a hook's own `let` locals die with the clone; a top-level `const` survives because it was in the
scope before the clone was taken. State lives host-side — the broker's `position()` and the
indicator caches in `ScriptCtx`.

## What you can call [#what-you-can-call]

`engine::HOST_FN_NAMES` is the whole non-indicator surface: the reads `close` / `open` / `high` /
`low` / `volume` / `position` / `price` / `equity` / `index` / `now`, the order verbs `buy` /
`sell` / `limit` / `market`, and `param`. Each verb pushes an `Intent` into `ScriptCtx::intents`
through a cloned `Arc` — `buy(qty)` and `sell(qty)` are `market(1, qty)` and `market(-1, qty)`;
`limit(side, qty, price)` rests one — and `strategy.rs` drains the recorded intents onto the real
broker at the end of the bar.

`param(name, default)` is the sweepable knob. First-seen wins in the `(name, default)` list
discovery reports — the call itself still returns its own default — the injected override replaces
the default when a profile supplies one, and the default argument is a `rhai::Dynamic` on purpose:
registered as `f64` it accepted `param("fast", 5.0)` and rejected `param("fast", 5)`, so a knob
worked or did not depending on a decimal point.

Indicators are bound from `vike_indicators::registry()`, not hand-listed: `RHAI_INDICATORS` is the
registry minus everything `unbound_reason` rejects, and `register_indicators` filters on the same
predicate, so the advertised set and the bound set cannot drift. Each bound name gets one form per
argument count from zero (all registry defaults) up to its own parameter count.

`MAX_INDICATOR_ARITY` is the ceiling on that ladder, and an indicator with more parameters than it
is not bound at a lower arity — it is not bound at all. See the fourth refusal below.

<Callout type="warn" title="Call every indicator unconditionally, on every bar">
  An indicator advances only when the script calls it. A call behind an `if` silently skips the bars
  the branch did not take, and the number it then returns is no longer an average of the last N — a
  wrong value, never an error. Read every indicator on the first lines of `on_bar`, before any branch
  or early return.
</Callout>

Five kinds of registry entry are deliberately not bound, each because binding them would return a
silently wrong number: a name rhai reserves (`var` is a reserved word, so `var(20)` fails at parse
time), a name that would shadow a host function, the `batch_only` three that read future bars
(`ichimoku` / `zigzag` / `williams_fractal`), an indicator declaring more parameters than
`MAX_INDICATOR_ARITY`, and a multi-output indicator whose line 0 is not its namesake.

The fourth is the one the argument-count ladder above would otherwise hide: the forms stop at the
ceiling, so binding such an indicator would pin every parameter past it to the registry default —
knobs that look present and are not. Today that is `kst`, with nine; it is absent rather than
crippled, and Rust is where you construct it.

The fifth is about which line you get: `bollinger(20)` would hand back the UPPER band to someone
who read it as the middle, so the bare name is refused and `bollinger_mid()` is the spelling —
every line of every multi-output indicator has its own accessor. `unbound_reason` answers why any
particular name is missing. `vike-cli indicators` prints the callable set off the same derived
list the host binds from, including your own `user_data/indicators/*.rhai` files in their own block.

## What the engine will not let you do [#what-the-engine-will-not-let-you-do]

`build_engine` opts into bounded limits (of these, a plain `rhai::Engine::new()` bounds only call
depth, and that already at 64 in a release build), applied per hook invocation rather than
cumulatively: 2,000,000 operations, 64 call levels, 8 KB strings, and 4096 elements for an array
or a map. `set_module_resolver` installs a `DummyModuleResolver`, so every `import` is refused —
a default engine roots a `FileModuleResolver` at the process working directory, which for the
daemon is `<project>`, the operator's settings tree and credential store included. `print` and
`debug` are redirected onto the `tracing` facade, because the embedding binary's stdout is a
protocol.

Runtime errors fail safe: a hook that errors emits zero orders that bar and any intents it recorded
before the error are discarded. After ten CONSECUTIVE errors the strategy self-disables; a
successful call resets the counter.

## Write the indicator the strategy needs [#write-the-indicator-the-strategy-needs]

The rest of this page is one real strategy, written from nothing and run to a number. It wants two
values per bar: a breakout level, which needs a memory of earlier bars, and a measure of how wide
the current bar is, which needs none.

The first ships with `vike-cli init` as `user_data/indicators/donchian_high.rhai`. The second we
write — the smallest shape the indicator seam accepts:

```rust
// range_pct — this bar's high-low range as a percentage of its close.
//
// The smallest useful shape: no window, no state, one number per bar.

fn init() {
    #{}
}

fn on_bar(bar) {
    if bar.close == 0.0 { return (); }
    (bar.high - bar.low) / bar.close * 100.0
}
```

Only `on_bar` is required. `crates/vike-script/src/indicator.rs` declares `INIT`, `WARMUP`,
`OUTPUTS` and `OVERLAY` as optional, and an absent `init` yields exactly the empty map this file
returns — it is written out here because it is the hook you extend the moment the indicator needs
to remember anything.

Returning `()` is the seam's NaN. A bar whose close is zero has no percentage, so the indicator
says so rather than dividing.

## The strategy that calls it [#the-strategy-that-calls-it]

```rust
// quiet_breakout — buy a breakout, but only out of a quiet bar.
//
// Uses the shipped donchian_high user indicator for the breakout level and range_pct (written for
// this tutorial) to insist the bar that breaks out is not itself a wide, already-moved bar.
let lookback = param("lookback", 48.0);
let calm = param("calm", 1.0);
let qty = param("qty", 0.05);

fn on_bar() {
    let hi = donchian_high(lookback.to_int());
    let rng = range_pct();
    if hi.is_nan() || rng.is_nan() { return; }

    if close() > hi && rng < calm && position() <= 0.0 { market(1, qty); }
    if close() < hi * 0.97 && position() > 0.0 { market(-1, position()); }
}
```

Both indicator reads sit on the first two lines of `on_bar`, unconditionally, ahead of every branch
— the rule from the callout above. The NaN check comes after both reads, never instead of one.

`lookback` is declared as `48.0` and converted at the call site, because the indicator's own knob is
a count of bars.

## Validate the knobs before you run [#validate-the-knobs-before-you-run]

```sh
vike-cli backtest --list-params --script quiet_breakout.rhai
```

```text
lookback = 48
calm = 1
qty = 0.05
```

`--list-params` is offline. `crates/vike-cli/src/cmd/backtest.rs`'s `execute` reads the file, runs
`vike_script::discover_params` and stops — no profile, no server. Compiling IS validation here, so a
syntax error, or a TOP-LEVEL call to a function that is not bound, is the answer you get instead of
a list — rhai resolves a name when the line RUNS, so a call inside `on_bar` still passes. An
agent gets the same answer from the read-only `validate_strategy` MCP tool.

The defaults print as rhai renders them, which is why `48.0` reads back as `48` and `1.0` as `1`.
The names and their order are the script's own, in declaration order.

`vike-cli indicators` is the companion check: it prints the callable set, with your own
`user_data/indicators` files in their own block.

## The first run: zero trades [#the-first-run-zero-trades]

Point a run profile at the script exactly as the
[RSI tutorial](/docs/trader/tutorials/rsi-mean-reversion-backtest) does, then run it:

```sh
vike-cli backtest --profile tut_breakout.toml
```

```text
{
  "final_equity": 10000.0,
  "funding_paid": 0.0,
  "max_drawdown": 0.0,
  "n_trades": 0,
  "name": "quiet_breakout — BTCUSDT 1h",
  "per_symbol_pnl": [
    [
      "BTCUSDT",
      0.0
    ]
  ],
  "profit_factor": 0.0,
  "sharpe": 0.0,
  "total_return": 0.0,
  "win_rate": 0.0,
  "zero_trade": {
    "causes": [
      {
        "code": "no-orders",
        "detail": "Over 8760 bar(s)/tick(s) nothing was denied, deferred, or gated and no trade closed, so no gate explains the flat result. The strategy most likely never submitted an order - check its entry condition and that it reads the SAME symbol the data is tagged with (bar-mode `snap_to_properties` re-tags bars as `SYMBOL.VENUE`, which a strategy routing on the bare symbol will miss).",
        "headline": "No order-blocking cause was detected."
      }
    ]
  }
}
...(diagnostic continues; the full JSON is in the run's report.json)
```

Nothing traded over 8760 hourly bars — a year of BTCUSDT.

The `zero_trade` object is not decoration. `crates/vike-analytics/src/report.rs`'s
`BacktestReport::zero_trade` is `Some` only when a run closed no trades AND its equity never moved,
and when it is present the human `Display` table stops after `final_equity` and `n_trades: 0`,
printing the diagnosis in place of the metric rows below it — the JSON above, which is all
`vike-cli backtest` prints, carries both.

`crates/vike-analytics/src/zero_trade.rs`'s `rank_causes` ranks the things that block orders: gate denials, the
stale-price wait, a closed session, a warm-up shortfall, an empty data slice. Here none of them
fired, so it emitted the catch-all `"no-orders"` cause. Read it for what it is — the analyzer
diagnoses gates, not logic, and it is telling you that nothing stopped your orders because there
were none to stop.

One thing this run does not show you. The profile carries the strategy source in
`[strategy.params].src` (the `--script` flag is what injects it —
`crates/vike-cli/src/cmd/backtest.rs`'s `inject_script_src`), but the indicator FILES are never
shipped. The service installs its own `<project>/user_data/indicators/*.rhai` at startup —
`crates/vike-datahub/src/datahub_cli.rs`'s `install_user_indicators` — and that set wins. The same
script against two services with different indicator directories returns different numbers, and
nothing in the response says so.

## The cause, and the corrected run [#the-cause-and-the-corrected-run]

The first suspect was the range filter: `calm = 1.0` demands an hourly bar whose high-low range is
under 1% of its close. Raising it to `3.0` and re-running produced the same zero-trade JSON. That is
the useful half of a failed fix — the filter was not the gate.

The gate was the comparison itself. The shipped `donchian_high`
(`crates/vike-cli/src/cmd/init/content.rs`'s `DONCHIAN_HIGH_RHAI`) pushes the current bar's high
into its window BEFORE taking the maximum:

```rust
fn on_bar(bar) {
    this.highs.push(bar.high);
    if this.highs.len() > lookback {
        this.highs.remove(0);
    }
    if this.highs.len() < lookback {
        return ();
    }
    let hi = this.highs[0];
    for h in this.highs {
        if h > hi { hi = h; }
    }
    hi
}
```

So the value returned on a given bar already includes that bar's own high. A close can never exceed
the high of its own bar, which makes `close() > donchian_high(n)` false on every bar of every tape.
The strategy was right about everything except the one comparison it was built on, and no error was
ever raised — the indicator is a perfectly good rolling maximum, just not the one this entry needs.

The correction is a reordering: take the maximum of the window as it stood BEFORE this bar, then
push. Saved as its own `breakout_level.rhai` and called in place of `donchian_high`, the same
profile gives:

```text
{
  "final_equity": 8334.568427500006,
  "funding_paid": 0.0,
  "max_drawdown": 0.1839635835571801,
  "n_trades": 48,
  "name": "quiet_breakout — BTCUSDT 1h",
  "per_symbol_pnl": [
    [
      "BTCUSDT",
      -1180.6035000000015
    ]
  ],
  "profit_factor": 0.687335413608655,
  "sharpe": -1.0475904521415624,
  "total_return": -0.16654315724999946,
  "win_rate": 0.3125
}
```

## Reading that result [#reading-that-result]

The strategy trades now, and it loses money.

48 trades over the year, of which 31.25% won. Equity ended at 8334.57 of the 10000 it started with:
a total return of -0.1665, which is a 16.65% loss.

Max drawdown was 18.40% and Sharpe was -1.05.

Profit factor is gross profit over gross loss (`crates/vike-analytics/src/metrics.rs`'s
`profit_factor`). At 0.687 it says the winners gave back about 69 cents for every dollar the losers
cost.

What the numbers say: the script compiles, both user indicators resolve, the entry condition now
fires, and the resulting edge is negative on this tape.

What they do not say: anything about the idea in general. This is one symbol, one year, one bar
interval, one parameter point, measured in-sample with no out-of-sample window. A single backtest
number is the weakest evidence the platform can produce, and the honest next step is not to tune
`calm` until the number turns green — a sweep will always find the best-looking point on the tape it
searched.

[Sweep and walk-forward](/docs/trader/tutorials/sweep-and-walk-forward) is where that goes next, and it
is the tutorial that shows what an out-of-sample number does to an in-sample one.

## Mounting it live [#mounting-it-live]

A script can also mount LIVE, by PATH rather than by name: `[strategy] rhai = "<path>"` in a
`vike-tradehub` profile compiles it through the same engine builder and logs the source's sha256,
which is the journal's answer to which code traded.

## Where next [#where-next]

* [Writing a strategy](/docs/trader/scripting/writing-a-strategy) and the
  [cheatsheet](/docs/trader/scripting/cheatsheet).
* [The engine](/docs/trader/scripting/the-engine) and [Limits](/docs/trader/scripting/limits).
* [Writing an indicator](/docs/trader/scripting/writing-an-indicator) — the other seam, a real
  `Indicator` with `vectorize` parity by construction.
* [A custom indicator, end to end](/docs/trader/tutorials/custom-indicator).
* [Sweep and walk-forward](/docs/trader/tutorials/sweep-and-walk-forward).


# RSI mean-reversion backtest (/docs/trader/tutorials/rsi-mean-reversion-backtest)



The quickstart runs `sma_cross`. This tutorial runs the other shipped example — `rsi_meanrev`,
which fades extremes instead of following them — because the two make opposite bets and running
both over one slice is the quickest way to see what a tape has been doing. No credentials are
needed at any step.

## 1. Scaffold the examples [#1-scaffold-the-examples]

```sh
vike-cli init
```

`vike_cli::cmd::init` writes `<project>/user_data` and prints the map. Its `files` table is the
exhaustive list of what it ships and the only thing `--reset` can overwrite; without `--reset` it
writes only what is absent, so a file you edited is never touched, never diffed and never backed
up. Two entries matter here:

```
user_data/strategies/rhai/rsi_meanrev/rsi_meanrev.rhai
user_data/strategies/rhai/rsi_meanrev/default.toml
```

## 2. What the script says, and the two lines that are not style [#2-what-the-script-says-and-the-two-lines-that-are-not-style]

`content.rs`'s `RSI_MEANREV_RHAI` is eleven lines of body. It declares four knobs at the top level
— `len` 14, `lo` 30, `hi` 70, `qty` 1.0 — and then:

```rust
fn on_bar() {
    let r = rsi(len.to_int());
    if r.is_nan() { return; }

    if r < lo && position() <= 0.0 { market(1, qty); }
    if r > hi && position() >= 0.0 { market(-1, qty); }
}
```

**The indicator is read first, on every bar, before any branch.** An indicator only advances when
the script calls it, so a call inside an `if` would skip bars and quietly stop being an average of
the last N. `content.rs`'s module doc states the rule and
`crates/vike-cli/tests/init_cli.rs`'s
`every_shipped_rhai_strategy_reads_its_indicators_before_it_branches` gates it for every shipped
script.

**The `position()` guards are what stop it stacking size** — it enters only from flat or from the
other side, so a long stretch below `lo` opens one position rather than one per bar.

The `is_nan()` return is the warm-up. `crates/vike-indicators/src/indicators/base.rs`'s `Rsi` is
the Wilder RSI — a seeded average of the first `n` gains and losses, then the recurrence — and it
answers `NaN` until the bar at index `n`, so a 14-period RSI decides nothing for the first fourteen
deltas.

<Callout type="warn" title="A name outside the bound set fails on every bar, not at load">
  `crates/vike-script/src/engine.rs`'s `RHAI_INDICATORS` is the host-bound set, derived from
  `vike_indicators::registry()` rather than hand-listed. Rhai resolves a name when the line RUNS, so
  compiling proves nothing: a misspelled indicator errors every bar and, after ten consecutive
  errors, `RhaiStrategy` self-disables — a strategy that looks mounted and never trades, which a
  backtest reports as a flat curve. `vike-cli indicators` prints the set that is actually bound.
</Callout>

## 3. Seed the tape [#3-seed-the-tape]

```sh
backtest --seed-demo
```

`vike_data::demo`'s `DEMO_SLICES` writes two spans under the venue id `demo`: `BTCUSDT` hourly from
2025-01-01T00:00:00Z to 2025-07-01T00:00:00Z, and the last seven days of the same curve at one
minute. Every bar is a closed-form function of its timestamp, so a re-seed is free as well as
safe — each slice appends under a versioned commit key and a store that already holds the tape
takes zero rows.

## 4. Run it [#4-run-it]

The shipped `profiles/backtest.toml` already names that slice. Its `[strategy.params]` carries
`sma_cross`'s `fast`/`slow`, which `rsi_meanrev` does not read — and a params table is a READER,
not a schema, so those two keys are ignored in silence and every `rsi_meanrev` knob keeps the
script's own default. Replace them, or pass the shipped preset:

```sh
vike-datahub &
vike-cli backtest \
  --profile user_data/profiles/backtest.toml \
  --preset  user_data/strategies/rhai/rsi_meanrev/default.toml \
  --script  user_data/strategies/rhai/rsi_meanrev/rsi_meanrev.rhai
```

`merge_preset_params` merges a preset's keys into `[strategy.params]` one for one, last-wins, and
leaves the rest of the profile untouched. A preset is FLAT: a `[params]` wrapper is refused,
because merged as-is it would hand the strategy one parameter called `params` that nothing reads
while every knob kept its default, and a `src` key is refused because that is the strategy's source
rather than a knob. The preset is resolved locally and merged before the request goes out — only
the profile text crosses the wire, so a preset named inside the profile would resolve against the
server's `user_data/`, not yours.

To see the knobs without a server at all:

```sh
vike-cli backtest --list-params --script user_data/strategies/rhai/rsi_meanrev/rsi_meanrev.rhai
```

That runs `vike_script::discover_params`, which compiles the script and executes its top level —
where `param(name, default)` is called — and returns the pairs in declaration order.

## 5. What comes back [#5-what-comes-back]

On the demo tape, with the preset's 14/30/70 and its `qty = 1.0`:

```text
name:          rsi_meanrev — demo BTCUSDT 1h
final_equity:  -133004.57
total_return:  -1430.0457%
n_trades:      51
win_rate:      0.0000%
sharpe:        1.6844
max_drawdown:  1430.7866%
per_symbol_pnl:
  BTCUSDT: -136596.11
```

That is a real run and it is worth sitting with rather than skipping past. The demo tape is not a
one-way line: `crates/vike-data/src/demo.rs`'s `price_at` is a drift plus three superposed cycles —
weekly, daily and a fast wobble — so the curve does snap back, and on the weekly leg it snaps back
hard.

What defeats a short-the-overbought rule here is the drift underneath those cycles. The trend term
adds 9.5 an hour over the hourly span's six months, so the tape opens near 42,000 and its trend
alone ends near 83,000, and each weekly peak sits above the one before it. The strategy shorts each
overbought reading into that rise, and `qty = 1.0` means one whole unit of a five-figure instrument
against ten thousand of cash. A win rate of exactly zero over fifty-one trades is not noise; it is a
strategy selling a drifting tape with size it cannot carry.

Note the Sharpe: **1.6844**, on a run that lost fourteen times the account. A ratio computed on
per-bar returns says nothing about whether the account survived, which is why the [report](/docs/trader/analytics/report)
carries drawdown and equity beside it and why no single number is the answer.

## 6. The same strategy on real bars [#6-the-same-strategy-on-real-bars]

Pull real public hourly bars — no credentials, no venue account:

```sh
backtest --fetch binance:BTCUSDT:1h --from 2025-01-01T00 --to 2026-01-01T00
```

```text
  8760 bars returned, covering 1735689600000..=1767222000000; 8760 rows written
```

Point the profile's `venue` at `binance`, and size it for the account — `qty = 0.05` rather than
`1.0`:

```text
name:          rsi_meanrev — BTCUSDT 1h
final_equity:  12128.52
total_return:  21.2852%
n_trades:      33
win_rate:      69.6970%
sharpe:        1.7800
max_drawdown:  8.3457%
per_symbol_pnl:
  BTCUSDT: 2448.31
```

Same script, same thresholds, same fee rate. What changed is the tape and the size. Two thirds of
the trades win and the worst drawdown is 8.3%. Read that as a demonstration of how much a result
depends on its slice, not as evidence the strategy works: one symbol over one year is one sample,
and [walk-forward](/docs/trader/tutorials/sweep-and-walk-forward) is the next thing to do to it.

## 7. Where the run went [#7-where-the-run-went]

```text
user_data/runs/1788477441-18704-0/
  manifest.json
  report.json
```

The manifest records what produced the numbers — the run id, the profile path and name, the data
slice with its venue-tagged series and the store root, and the start and finish timestamps. The
report is the metrics above as JSON. [Runs on disk](/docs/trader/backtesting/runs-on-disk) covers the
layout.

## 8. Read the report [#8-read-the-report]

`BacktestReport` carries the profile name, final equity, total return, trade count, win rate,
Sharpe, max drawdown, profit factor, net funding and per-symbol PnL. Two fields are conditional and
both tell you something:

* `profit_factor` serializes as `null` when it is not finite — the house sentinel is `INFINITY`
  when there were no losing trades but some profit, and `0.0` when there was neither.
* `zero_trade` is present ONLY when the run closed no trades AND its equity never moved.
  `vike_analytics::zero_trade`'s `ZeroTradeReport::analyze` then ranks the probable causes from
  counters the run already carried — gate drops, stale-price deferrals, session skips, the warm-up
  requirement — and `Display` prints that diagnosis instead of an all-zero metrics table. On a
  mean-reversion strategy the usual cause is thresholds the tape never reached.

## 9. The contrast run [#9-the-contrast-run]

Re-run the same profile against `sma_cross` and `ema_trend`. `content.rs` ships all three for one
reason: they are three SHAPES — always-in reversal, mean reversion, long-only filter — not three
indicators. If the long-only rule beats the always-in one, the short side was costing money.

## Where next [#where-next]

* [Sweep, then walk-forward](/docs/trader/tutorials/sweep-and-walk-forward) — search the RSI thresholds,
  then check the winner out of sample.
* [Write a Rhai strategy from scratch](/docs/trader/tutorials/rhai-strategy-from-scratch).
* [Read a backtest report](/docs/trader/guides/read-a-report) and
  [sizing and zero-trade diagnosis](/docs/trader/analytics/sizing-and-zero-trade).
* [Presets](/docs/trader/scripting/presets) and [Run profiles](/docs/trader/backtesting/run-profiles).


# The A-S maker on a paper book (/docs/trader/tutorials/spread-maker-on-paper)



`vike_mm::SpreadMaker` is the reference market maker: a two-sided quoter priced by
Avellaneda-Stoikov, with inventory-skew size shaping, a per-side fill-rate circuit breaker, a
quote-style registry, own-order-book filtration and an anti-churn refresh gate stacked on top. This
tutorial mounts it with `vike_paper::PaperExecutionClient` as the `ExecutionClient` — the real
runtime, the real risk gate, the real order path, and no venue.

It is written `impl<B: HftBroker> Strategy<B>`, because it needs the tagged-resting-order verbs
(tagged submits, in-place modify, per-tag cancel, a signed-position read) that are not on the
portable `Broker` surface. `vike_core::LiveBroker` implements `HftBroker`, so the live core mounts
it; a plain `Broker`-only backtest engine cannot, which is the type system continuing to document
the requirement.

## What it is quoting [#what-it-is-quoting]

`crates/vike-mm/src/avellaneda.rs` carries the closed forms, adapted for a bounded price domain:

```text
reservation price   r      = s − q_norm · γ · V
optimal half-spread δ_half = ½·γ·V + (1/γ)·ln(1 + γ/κ)
effective variance  V      = min(σ̂²·H, p·(1−p))
```

`s` is the fair mid, `q_norm` the size-normalised signed inventory, `γ` risk aversion, `κ` the
fill-intensity decay, and `H` the effective horizon — `min(τ_hold, T−t)` once a `resolution_ts` is
set, and the bare `τ_hold` otherwise, which is the default. The `p(1−p)` Bernoulli cap is the crux
for a 0..1 market: skew and spread vanish at the walls and peak at 0.5, which keeps A-S
from over-penalising inventory near a wall.

That geometry is one case of a `PriceDomain` knob. `UnitInterval` is the default and clamps quotes
to `[tick, 1−tick]`; `Unbounded` is the dollar-scale case with no wall clamp, where a quote is
bounded only by the standoff and the `bid < s < ask` straddle. Two pairings are load-bearing for a
dollar-scale mount: `VarianceMode::RawLocal`, because the Bernoulli cap goes negative for `p > 1`,
and an `AsParams::min_half_spread_ticks` floor, because the adverse-selection half-spread is
sub-tick at that scale and both sides would otherwise snap to one tick.

Every layer above the pricing is inert at its default, byte-identically: the skew intensity at
`0.0` makes both size multipliers exactly `1.0`; the breaker's window, threshold and cooldown all
at `0` mean it never engages; `QuoteStyle::Mid` reproduces the original midpoint-plus-half-spread
pricing bit for bit; own-order filtration is off, so the maker prices straight off the feed; and
`RefreshTolerance` is `None`, so every tick re-quotes both sides. Turn one on deliberately, and
know that filtration and the styles change pricing bit for bit when you do.

## The mount, and the one non-obvious piece [#the-mount-and-the-one-non-obvious-piece]

`vike_run::build_paper_maker_core` is `spawn_core` plus a `StrategyMount(SpreadMaker)` plus
`PaperExecutionClient`. The wiring that makes it actually fill is the tick-to-bar bridge:

**The maker QUOTES on ticks** (`on_quote_tick` / `on_order_book`), **but the paper client FILLS on
CLOSED BARS** (`on_bar`, next-open discipline — the R7 paper law). A venue serving ticks rather
than candles would therefore produce a maker that quotes forever and never fills, so the mount
synthesises bars: `TickBarSynthesizer` folds the feed mid into an event-time OHLC window and emits
a closed `vike_model::Bar` on each interval boundary, and that bar drives the paper book. A maker
resting inside the spread is filled exactly when the market oscillates through its quote within a
bar — a dip-and-recover fills the resting bid, a spike-and-fall fills the resting ask. It is pure
wiring: neither the `DataClient` nor the `ExecutionClient` seam changes.

<Callout title="Why paper is faithful here">
  `PaperExecutionClient` fills its resting book with the backtest engine's OWN public primitives, so
  backtest equals paper by construction and is gated bit for bit by `vike-backtest`'s
  `tests/r7_gate.rs`. `build_paper_strategy_core_with` also asserts that the mount declares no extra
  legs: a single-symbol paper book stamps its own symbol onto every fill, so a multi-symbol
  rehearsal would book both legs under one symbol and look perfectly correct while the live core
  routed them apart — concealing the very thing the rehearsal exists to catch.
</Callout>

## Running it against a real feed [#running-it-against-a-real-feed]

`crates/vike-run/src/bin/polymarket_maker_paper.rs`, behind the `polymarket` feature, is the mount
above with the real Polymarket `Feeds` as the tick source. It picks a market with `--auto`
(universe selection), `--query` against the Gamma catalog, or a `--token-id` outright, reads the
market's `end_date` into the A-S `resolution_ts`, and runs for `--duration-secs`. It logs position,
working quotes, paper fills and realized PnL every few seconds, then flushes the last synth bar and
shuts the core down cleanly.

No API keys are needed: the market channel is public and unauthenticated, and the mount is paper —
it never signs or sends an order. Polymarket's CLOB is US-geo-blocked, so the binary must run on,
or egress through, a host outside that block; the mount is identical either way, and only the feed
differs from the offline scripted test.

## The daemon route, and the trap in it [#the-daemon-route-and-the-trap-in-it]

`vike-tradehub` mounts the A-S maker as its DEFAULT: absent a `[strategy]` table it builds one from
the profile's own maker fields (`qty`, `half_spread`, `tick_size`, `resolution_ts_ms`, plus
`interval` / `interval_ms` for the synthesiser and `seed_cash` for the paper account) through
`vike_run::build_maker`.

<Callout type="warn" title="Do not name the maker in a daemon profile's [strategy] table">
  `SpreadMaker::from_params` is a reader over `[strategy.params]` and nothing else, so naming
  `spread_maker` there would mount `qty = 1`, `tick_size = 0` and the `[0,1]` Bernoulli wall clamp —
  the exact configuration `vike-tradehub`'s own module doc records as having posted ZERO orders on a
  five-figure hyperliquid asset. `config.rs`'s `AS_MAKER_NAMES` therefore routes both maker spellings
  to the same `build_maker` call the default path makes, and `validate` REFUSES a `[strategy.params]`
  table under either name rather than dropping it. The two spellings cannot differ; an attempt to
  make them differ is a startup error.
</Callout>

That refusal is why the maker's row in `vike_strategy::PARAM_KEYS` is allowed to decline to
enumerate its roughly sixty keys: its consumer carries a stricter rule of its own. On a
`vike-backtest` profile, where `[strategy.params]` is the only configuration that exists, the
reader is live — and it fails loudly on an ENUM key (`spread_model`, `kappa_mode`, `style`, …) that
is present and names no variant, so a value typo is a `vike_mm::ParamError` rather than a silent
default.

## Where next [#where-next]

* [Avellaneda-Stoikov](/docs/trader/market-making/avellaneda-stoikov),
  [Inventory skew](/docs/trader/market-making/inventory-skew) and
  [Quote styles](/docs/trader/market-making/quote-styles).
* [Refresh tolerance](/docs/trader/market-making/refresh-tolerance) and
  [Quote emission](/docs/trader/market-making/quote-emission).
* [The spread-maker template](/docs/trader/strategies/templates/spread-maker).
* [The grid template on paper](/docs/trader/tutorials/grid-on-paper) — the same mount, a simpler
  strategy.


# Sweep, then walk forward (/docs/trader/tutorials/sweep-and-walk-forward)



A sweep answers "which parameters scored best on this slice". A walk-forward answers a different
question — "was that profitable across the whole sample, or in one lucky stretch" — and it answers
it without optimising anything. Running the second after the first is the point of this tutorial;
running only the first is how a curve-fit ships.

Both profiles are shipped by `vike-cli init` (`profiles/sweep.toml`, `profiles/walkforward.toml`),
and both carry their script INLINE in `[strategy.params].src`, because neither the `sweep` nor the
`walkforward` verb takes `--script`. `vike-cli init` writes that inlined copy from the same source
as `strategies/rhai/sma_cross/sma_cross.rhai`, so a fresh scaffold agrees — edit one afterwards and
you must edit the other.

## 1. The sweep [#1-the-sweep]

```toml
[sweep]
fast = [5.0, 10.0, 20.0]
slow = [30.0, 50.0, 100.0]
```

`harness::sweep`'s `expand_sweep` turns a profile carrying that table into the cartesian product of
single-run profiles — each with `strategy.params` overridden for its point and its own `sweep`
field cleared, so every expanded point is itself a plain runnable single-backtest profile. A
profile with no `[sweep]` table expands to exactly one point with no overrides, which is why the
non-sweep path is unchanged.

```sh
vike-cli sweep --profile user_data/profiles/sweep.toml --rank-by sharpe
```

`run_sweep` runs each point through `run_backtest`, keeps a `BacktestReport` or the error string
per point, and ranks the successful rows; failed rows always sort last. `--rank-by` takes
`sharpe` (default), `return`, `max_dd` or `equity`. The name is validated locally and applied
server-side by the canonical `RankMetric` comparator, so the rows arrive already ordered best-first
and the printed statistics are the server's own report numbers.

<Callout title="The whole profile crosses the wire, and that is a correctness fix">
  `vike-cli sweep` used to re-parse the profile into `WireSpec`/`WireSlice`/`WireSweep` DTOs. That
  mapping could not carry `[engine].fee`, `[engine.impact]`, `[engine.resolution]`, `[risk]`,
  `snap_to_properties`, a tick slice or a cross-venue `[[data.series]]` slice — so a sweep quietly
  ran under different costs than the same profile's `backtest`. The text is now shipped verbatim and
  the server's one `BacktestProfile::from_toml_str` parses it.
</Callout>

Three properties worth carrying:

* **Determinism does not rest on scheduling.** Points run on a rayon pool by default, but
  `par_iter().map().collect()` is order-preserving and the ranking sort is a stable
  `slice::sort_by` over that same input order, so the bytes are identical to the one-at-a-time
  loop (`parallel_and_sequential_sweeps_are_byte_identical`).
* **Parallelism multiplies MEMORY, not just speed.** The shared `Arc<dyn HistStore>` shares the
  handle, not the loaded data: every point re-scans and fully materialises its own `Vec<Bar>` /
  `Vec<Tick>`, so peak RSS is `N_threads × slice`. The pool is therefore bounded rather than
  global — `sweep_threads` defaults to `min(4, available_parallelism())` and `VIKE_SWEEP_THREADS`
  raises it. Size that against the slice, not the core count. `VIKE_SWEEP_SEQUENTIAL=1` pins the
  process back to the old loop.
* **Cost multiplies fast.** The shipped grid is 3 × 3 = 9 runs; a fourth axis of five values is 45.
  Write the values as floats — the shipped profile's own warning — because a non-numeric value is
  skipped in silence.

## 2. What the sweep actually reported [#2-what-the-sweep-actually-reported]

The runs below use a smaller grid than the shipped profile, so the whole table fits on the page:
3 × 2 = 6 points over the scaffolded `rsi_meanrev` script's `len` and `lo` axes. The data is real
Binance BTCUSDT 1h bars for the first half of 2025, run at `cash = 10000`, `fee_rate = 0.001` and
`slippage = 0`.

```toml
[sweep]
len = [7.0, 14.0, 21.0]
lo = [20.0, 30.0]
```

Through the standalone `backtest` binary:

```sh
backtest --profile tut_rsi_sweep.toml --rank-by sharpe
```

```text
sweep ranked by sharpe (6 points)
*#1  len=14.0 lo=30.0               ret=0.2129 sharpe=1.7800 max_dd=0.0835 trades=33
#2   len=21.0 lo=30.0               ret=0.1542 sharpe=1.1885 max_dd=0.1341 trades=15
#3   len=14.0 lo=20.0               ret=0.0755 sharpe=0.6565 max_dd=0.1402 trades=12
#4   len=7.0 lo=30.0                ret=0.0246 sharpe=0.2807 max_dd=0.0873 trades=103
#5   len=7.0 lo=20.0                ret=-0.0242 sharpe=-0.1026 max_dd=0.1137 trades=50
#6   len=21.0 lo=20.0               ret=-0.0992 sharpe=-0.6544 max_dd=0.1738 trades=2
```

Two of the six points lost money, and the table keeps them. Ranking is not filtering: rows 5 and 6
print with their negative returns and negative Sharpes, in last place, because a grid point that
failed is evidence about the grid.

The winner returned 21.29% at a Sharpe of 1.7800 over 33 trades. Notice where that ordering comes
from — every `lo = 30.0` point outranks every `lo = 20.0` point. This is a one-axis result. The
grid found an entry threshold that the first half of 2025 rewarded, and `len` only shuffles rows
within it.

Read the trade counts before the returns. Row 4 traded 103 times for +2.46%; row 6 traded twice for
-9.92%. A Sharpe of -0.6544 computed over two trades is a number, not a measurement — and the same
caution applies to the winner's 33.

What the table does not say is anything out-of-sample. All six points were scored on the same bars,
and the top row was then chosen by looking at those scores, so 1.7800 is the maximum of six draws
rather than an estimate of what `len = 14`, `lo = 30` will do next. That is the gap the
walk-forward exists to measure.

### The same grid through the service [#the-same-grid-through-the-service]

`vike-cli sweep` ships the same profile text to a `vike-datahub` server, which parses it with the
one `BacktestProfile::from_toml_str` and ranks the rows itself:

```sh
vike-cli sweep --profile tut_rsi_sweep.toml --rank-by sharpe
```

```text
parameter sweep — 6 point(s), ranked server-side by sharpe
rank  overrides                             final_equity     return    sharpe    max_dd   trades
   1  len=14.0, lo=30.0                         12128.52    +21.29%    1.7800    0.0835       33
   2  len=21.0, lo=30.0                         11542.23    +15.42%    1.1885    0.1341       15
   3  len=14.0, lo=20.0                         10755.26     +7.55%    0.6565    0.1402       12
   4  len=7.0, lo=30.0                          10246.32     +2.46%    0.2807    0.0873      103
   5  len=7.0, lo=20.0                           9758.30     -2.42%   -0.1026    0.1137       50
   6  len=21.0, lo=20.0                          9008.27     -9.92%   -0.6544    0.1738        2
```

Same six points, same order, same numbers. Only the presentation differs: the standalone table
prints `ret` as a fraction where the service table prints a percentage, and the service table
carries `final_equity` as well.

Neither client computes a statistic. `print_sweep` in `crates/vike-backtest/src/harness/sweep.rs` reads each
field straight out of the server's own row, and the standalone table is `SweepReport`'s `Display`
in `crates/vike-backtest/src/harness/sweep.rs`. The star on the standalone table's first row marks
rank 1.

## 3. The walk-forward [#3-the-walk-forward]

Take the winning row's parameters, put them in `[strategy.params]`, and run:

```sh
vike-cli walkforward --profile user_data/profiles/walkforward.toml
```

`harness::walkforward`'s `run_walkforward` is assembly, not new engine code: it resolves the
strategy through the same `strategy_by_name` registry, builds the same bar-lane `EngineParams` and
loads the same bars as a plain `run_backtest` of that profile, then hands the series to
`walkforward::walk_forward_strategy`. So a walk-forward can never disagree with a single run about
what the profile's `[engine]` means — including the fee SCHEDULE and `[risk]`, which the old
DTO-shaped path could not carry.

It is BAR mode over ONE series, deliberately: the splitter divides a single `&[Bar]` by index, so a
tick or multi-symbol profile is a clean validation error rather than a silent first-symbol
fallback.

`[walkforward] n_splits = 4` is the whole configuration. `walk_forward_splits` cuts the series into
`n_splits + 1` chunks; window `s` tests `[s·chunk, (s+1)·chunk)` with the last window running to
the end, and under `Anchored` mode every window's training range starts at index 0. Each window
runs fresh at `[engine] cash` and the OOS curves are rebased onto one running equity, so the
stitched curve compounds.

<Callout type="warn" title="It does not re-fit per window">
  The parameters are fixed and identical in every window. This is an out-of-sample STABILITY check,
  not an optimise-then-test protocol — which is exactly why you run it on the sweep's winner rather
  than instead of the sweep.
</Callout>

`WalkForwardReport` returns the per-window `oos_return`s, the stitched `oos_equity_curve`, its
`oos_return` and `oos_sharpe`, and `wf_consistency` — the fraction of windows that were profitable
out of sample. That last number is the one to look at first: a strong stitched return with a
consistency near 0.25 is one window carrying the strategy.

Point both profiles' `[data]` at a slice your store actually holds before the first run. The
shipped sweep names `binance` over the demo tape's dates, and the shipped walk-forward spans 2024
to 2026; an empty slice is a run with no trades, which reads like a bad strategy rather than an
empty query.

## 4. What the walk-forward actually reported [#4-what-the-walk-forward-actually-reported]

The profile below carries the sweep's winning row — `len = 14.0` and `lo = 30.0` — over the
identical `[data]` and `[engine]` block, plus `[walkforward] n_splits = 4`. The `--addr` flag
defaults to `127.0.0.1:7878`, so a datahub on the same box needs no flag.

```sh
vike-cli walkforward --profile tut_rsi_wf.toml
```

```text
walk-forward: 4 out-of-sample window(s)
window  test_range             oos_return
     1  [869, 1738)               +11.27%
     2  [1738, 2607)               +5.01%
     3  [2607, 3476)               -3.44%
     4  [3476, 4345)               +6.05%

oos_return = +19.64%   oos_sharpe = 1.983   wf_consistency = 75.0%
```

Window 3 lost 3.44%. That is the result, not a run to repeat until it behaves: one of the four
out-of-sample stretches of the first half of 2025 was a losing stretch for these parameters.

`wf_consistency = 75.0%` is that same fact counted — three of four windows finished above the cash
they started with. `walk_forward_strategy` in `crates/vike-backtest/src/walkforward.rs` counts a
window profitable on a strictly positive `oos_return`, so a perfectly flat window would count
against it too.

The index ranges are the anchored splitter showing its work. The series is 4345 bars;
`walk_forward_splits` in `crates/vike-analytics/src/validation.rs` sets
`chunk = n / (n_splits + 1)` = 869, window `s` tests `[s·869, (s+1)·869)`, and the last window runs
to the end.

So the first 869 bars are never tested. They are training-only in every window — that is what
anchored mode buys, and it is also what the stitched number is missing.

Which makes +19.64% not comparable with the +21.29% of the sweep's top row. The sweep scored the
whole slice; the walk-forward scored the last four fifths of it. The same goes for
`oos_sharpe = 1.983`, computed on the stitched curve and so covering the same four windows. The two
returns landing near each other is mildly reassuring and nothing more.

What the run does not say is that the strategy is stable. Four windows is four observations, and
75% and 100% are one window apart. At `n_splits = 4` over six months of hourly bars each window is
about five weeks — short enough for a single trend leg to fill one. Raising `n_splits` buys more
windows, not more data.

Nor is this a forward test. These parameters were chosen by looking at these same bars in the sweep
above, so the selection has already seen every window it is now scored on. The honest reading is
narrow: with `len = 14` and `lo = 30` held fixed, this slice produced three up windows and one down
one.

## Where next [#where-next]

* [Sweeps](/docs/trader/backtesting/sweeps), [Search](/docs/trader/backtesting/search) and
  [Walk-forward](/docs/trader/backtesting/walk-forward).
* [Bayesian parameter search](/docs/trader/tutorials/tpe-parameter-search) — when the grid is too big to
  enumerate.
* [Overfitting](/docs/trader/analytics/overfitting) and
  [Monte Carlo and overfitting](/docs/trader/tutorials/monte-carlo-and-overfitting).
* [Sweep on the service](/docs/trader/guides/sweep-on-the-service).


# Tick replay with a queue model (/docs/trader/tutorials/tick-replay-with-queue-model)



The default backtest fills a resting limit the instant price touches it. `crates/vike-backtest/src/queue_model.rs` says what that means and why it is wrong for a maker: the frozen crossing model behaves *as if the order were always first in the queue*, so it over-fills. On a real venue an order at price P fills only after the resting size **ahead** of it at P has been consumed. This tutorial turns that estimate on.

## The profile [#the-profile]

Everything here is [tick mode](/docs/trader/backtesting/tick-replay). Two knobs and a floor:

```toml
[data]
kind = "tick"
from = "1775000000000"
to   = "1775002000000"

[[data.series]]
venue = "binance"
symbol = "BTCUSDT"

[engine]
cash = 10000.0
slippage = 0.0
fill_model = "l2book"
queue_model = "risk_adverse"
queue_seed_depth = 0.0
queue_min_hold_ms = 2000
```

`queue_model`, `fill_model`, `queue_seed_depth`, `queue_min_hold_ms`, `feed_latency`, `order_latency_ms`, `fill_latency_ms` and `equity_sample_every` are **tick-mode only**. A bar profile that sets `queue_model` is rejected by `BacktestProfile::validate` rather than silently ignored, and an unrecognised value is a fail-fast validation error at load — a typo like `"l2_book"` must not quietly select the optimistic model and undo the realism knob. Absent, the whole lane is off and the run is byte-identical to the frozen crossing fill.

## What the gate actually does [#what-the-gate-actually-does]

`crates/vike-backtest/src/engine/queued.rs` is reached **only** when `EngineParams::queue_model` is `Some`; a default run never enters that module at all. The composition rule is stated in the queue model's own header and is worth reading as a sequence, because the queue gate layers on top of the price law rather than replacing it:

* the existing fill model still decides the **price** condition (limit crossed or touched);
* a **strict cross** — a trade or quote that trades *through* the level — fills in full: everyone at the level, the queue ahead included, was consumed;
* a **touch** at exactly the order's price is queue-gated. A trade at P first consumes the estimated front, and only its **excess** beyond the front fills the order, producing partial fills; a quote touch fills only once the front is already cleared;
* recorded L2 `BookUpdate`s drive `on_depth_change` at each tracked level, so cancellations ahead of the order shorten the wait — the depth-consumption channel the crossing model ignored entirely.

That last point is the reason to record the **book** and not just the trade tape. `queue_seed_depth` is the fallback front used when neither the replayed book nor an L1 quote gives a size at the order's price, and its default is `0.0` — a quote with no observed size-ahead fills on the first at-price trade, which is the optimistic answer again. Feed the book, or set the floor deliberately.

## Choosing a model [#choosing-a-model]

Three values, case-insensitive:

* **`risk_adverse`** — the conservative bound. The front shrinks only on hard evidence: trades at the order's price, or the level itself shrinking below the current front estimate. Cancellations behind the order are never credited, so this is the pessimistic, slowest-fill estimate.
* **`prob_power`*&#x2A; / &#x2A;*`prob_power:N`** — probabilistic, with weight `f(x) = x^N`. A net depth decrease is split between the queue ahead and behind by `prob = f(back) / (f(back) + f(front))`, the probability the cancellation came from behind. `N = 1` splits a decrease pro rata by size; larger `N` biases attribution toward the (usually larger) back.
* **`prob_log`** — the same split with the sub-linear weight `f(x) = ln(1 + x)`, so large backs saturate.

<Callout type="warn" title="Two of the three arms are platform-sensitive">
  `ProbFunc::f` calls `libm::pow` and `libm::log` — never `x.powf(n)` or `.ln()`, which resolve to the platform's own libm and disagree in the last bit between a Windows CRT and glibc. What that bit decides here is a **fill**: the weight moves the estimated queue ahead of a resting maker, which moves whether a trade's excess reaches the order at all, so a backtest can fill on one box and not the other. Decision 0032 carries the measurement. The bare `"prob_power"` spelling escapes it — it parses to `Power(1.0)` and libm's `pow` returns `x` unchanged for `y = ±1` ahead of any arithmetic — so the unconditional exposure is `"prob_log"` plus `"prob_power:N"` for any `N ≠ 1`.
</Callout>

## The minimum hold [#the-minimum-hold]

`queue_min_hold_ms` defers a position-**reducing** fill on the **tagged** maker lane until that long after the position opened, so the backtest cannot fabricate a sub-second maker round trip; the untagged queued-limit lane runs no such check at any setting. It is consulted only when `queue_model` is set, defaults to `0` (off), and its own doc names where to get the number: calibrate from real market-making flip times — the reference measurement is a Polymarket BTC-5m ≈ 2 s at the 10th percentile. A maker result with no floor at all is a result that assumes it could re-quote instantly.

Pair `fill_model = "l2book"` with `slippage = 0.0`: that model fills a resting order only up to the displayed book depth and rests rather than filling size the market never showed, so the book walk *is* the slippage and a flat rate on top double-counts.

## Verify it [#verify-it]

Run the same profile twice, once with `queue_model` absent and once set, and compare `n_trades` and `final_equity`. The difference is the whole point, and it should be large for a passive strategy. Then read the honesty note the shipped `crates/vike-backtest/profiles/wf_grid.toml` writes about its own bar-mode grid, because it names the ceiling this page exists to lift:

> NO QUEUE POSITION, AND NO WAY TO ADD ONE ON THIS LANE… a bar-mode grid fills EVERY rung the bar's high/low merely TOUCHED, at its own limit price, in full size. Real passive fills happen only when someone crosses you, and the ones you get are adversely selected. This is the single largest optimism in the run and it cannot be modelled here — a tick/book profile with `queue_model` + `queue_min_hold_ms` is the only honest version of a maker backtest.

Next: [queue models](/docs/trader/backtesting/queue-models) and [the queue lane](/docs/trader/backtesting/queue-lane) for the reference pages, [latency models](/docs/trader/backtesting/latency-models) for the reaction-time half, and [record and replay](/docs/trader/tutorials/record-and-replay) for getting a book on disk in the first place.


# Bayesian parameter search (/docs/trader/tutorials/tpe-parameter-search)



An exhaustive grid costs exponentially in resolution. Two searches in the harness buy the same
final resolution for far fewer backtests, and they buy it in different ways: `--search euler`
refines locally around the grid's winner, while `--optimizer tpe` models where good scores live and
proposes there. Both read the SAME `[sweep]` table, both score through the same objective seam, and
both return the same ranked `SweepReport` the grid returns.

They live on the standalone runner, which opens the store itself:

```sh
backtest --profile user_data/profiles/sweep.toml --optimizer tpe --trials 120 --seed 7
backtest --profile user_data/profiles/sweep.toml --search euler --euler-depth 4
```

The rest of this page runs all three paths over ONE profile so the numbers are comparable, and
prints what each returned. That profile sweeps two numeric axes of an RSI mean-reversion strategy
on BTCUSDT 1h bars.

## The grid these searches are measured against [#the-grid-these-searches-are-measured-against]

A search is only interesting against the number it is trying to beat, so start with the exhaustive
grid. Three lengths by two oversold thresholds is six backtests:

```sh
backtest --profile tut_rsi_sweep.toml --rank-by sharpe
```

```text
sweep ranked by sharpe (6 points)
*#1  len=14.0 lo=30.0               ret=0.2129 sharpe=1.7800 max_dd=0.0835 trades=33
#2   len=21.0 lo=30.0               ret=0.1542 sharpe=1.1885 max_dd=0.1341 trades=15
#3   len=14.0 lo=20.0               ret=0.0755 sharpe=0.6565 max_dd=0.1402 trades=12
#4   len=7.0 lo=30.0                ret=0.0246 sharpe=0.2807 max_dd=0.0873 trades=103
#5   len=7.0 lo=20.0                ret=-0.0242 sharpe=-0.1026 max_dd=0.1137 trades=50
#6   len=21.0 lo=20.0               ret=-0.0992 sharpe=-0.6544 max_dd=0.1738 trades=2
```

Six evaluations, best sharpe 1.7800 at `len=14 lo=30`. Two of the six points LOSE money — #5 returns
-2.42% and #6 returns -9.92% — and the grid keeps them and ranks them last.

That matters more than it looks. The same two rows reappear at the bottom of the euler run below,
and a reader who only ever sees a winner never learns how much of this space is bad.

The grid rows print no `score=` column. Both search outputs below do, and on every one of their rows
the score equals that row's sharpe, because `--rank-by` picks the objective as well as the ranking.

## The space both searches read [#the-space-both-searches-read]

`numeric_sweep_axes` is the one `[sweep]`-table reader, shared by the grid and both searches. Every
axis must be numeric AND type-homogeneous — an all-integer or an all-float TOML array. A string or
bool axis has no notion of halfway between two values, and a mixed `[1, 2.5]` axis would silently
change the TOML type the strategy receives versus the grid path, so a strategy reading its param
through `as_integer()` would behave differently under a search than under `--search grid`. Both are
a clean validation error telling you to use the grid.

For TPE, `tpe_space_from_profile` then turns each axis into a CONTINUOUS range bounded by that
axis's min and max, with integral axes staying whole. So `fast = [5.0, 10.0, 20.0]` does not mean
"try these three" — it means "search 5 to 20". TPE explores BETWEEN the grid points, the same
philosophy as euler's halving.

The grid above prints `len=14.0` and `lo=30.0`, decimal points and all, so both axes here are float
arrays. TPE therefore receives a continuous `len` over 7 to 21 and a continuous `lo` over 20 to 30.
The six grid points are six particular points inside that box, not the box itself.

## What TPE actually does [#what-tpe-actually-does]

`harness::tpe` is a clean-room implementation of Bergstra, Bardenet, Bengio and Kégl's
Tree-structured Parzen Estimator (NeurIPS 2011, §4), restated for this workspace's maximize
convention:

1. Keep the observation history `{(x, score)}`.
2. Split it at the `gamma` quantile of score — the top fraction is GOOD, the rest BAD.
3. Per parameter, independently, build two Parzen density estimates: `l(x)` from the good
   observations and `g(x)` from the bad ones.
4. Expected improvement is monotone in `l(x)/g(x)`, so propose the `x` that maximises the ratio.
   For a continuous parameter that means drawing `n_candidates` samples from `l` and taking the
   argmax of `l/g`.

A continuous parameter uses an adaptive Parzen estimator — one Gaussian per observation plus a
broad prior Gaussian at the domain midpoint, each kernel's bandwidth the maximum distance to its
sorted neighbours, clipped so it can neither collapse to a spike nor exceed the domain width. The
first `n_startup` asks are seeded-random, to give the model something to fit.

`TpeConfig` publishes the defaults: `DEFAULT_TRIALS` 64, `DEFAULT_GAMMA` 0.25, `DEFAULT_STARTUP`
10, `DEFAULT_CANDIDATES` 24. `--trials` and `--seed` (default 0) are the two the CLI exposes.

## Running the TPE search [#running-the-tpe-search]

Same profile, same objective, twelve trials at seed 7:

```sh
backtest --profile tut_rsi_sweep.toml --optimizer tpe --trials 12 --seed 7
```

```text
tpe: 12 trials (seed 7), best score 1.4950
sweep ranked by sharpe (12 points)
*#1  len=19.024470417556497 lo=26.62415622170128 ret=0.1986 sharpe=1.4950 max_dd=0.1083 trades=16 score=1.4950
#2   len=19.610649528496367 lo=25.829302930280782 ret=0.1582 sharpe=1.2327 max_dd=0.1058 trades=14 score=1.2327
#3   len=19.096107272110384 lo=25.4828741659996 ret=0.1582 sharpe=1.2327 max_dd=0.1058 trades=14 score=1.2327
#4   len=19.852274192045854 lo=28.71331759876744 ret=0.1536 sharpe=1.1804 max_dd=0.1102 trades=16 score=1.1804
#5   len=15.667688416361274 lo=27.573219822649627 ret=0.1213 sharpe=1.0531 max_dd=0.1313 trades=23 score=1.0531
#6   len=13.334186530160558 lo=22.49431522282743 ret=0.1224 sharpe=0.9732 max_dd=0.1434 trades=19 score=0.9732
#7   len=13.551342059120229 lo=23.28076739152503 ret=0.1155 sharpe=0.9328 max_dd=0.1441 trades=21 score=0.9328
#8   len=21.0 lo=27.077044141294163 ret=0.1059 sharpe=0.8671 max_dd=0.1285 trades=12 score=0.8671
#9   len=8.87961618331828 lo=24.131413974177793 ret=0.0763 sharpe=0.6776 max_dd=0.1019 trades=57 score=0.6776
#10  len=8.449839262830166 lo=29.598740765730916 ret=0.0504 sharpe=0.4758 max_dd=0.1085 trades=77 score=0.4758
#11  len=19.31459176678944 lo=23.263613015537427 ret=0.0410 sharpe=0.3962 max_dd=0.1278 trades=7 score=0.3962
#12  len=12.457616477477801 lo=20.167882945281562 ret=0.0307 sharpe=0.3180 max_dd=0.1497 trades=17 score=0.3180
```

The first line is the run summary. It goes to stderr, so a `--json` stdout stays a clean document.

Read the coordinates before you read the scores. Every row is a fresh real number rather than a grid
value, which is the continuous box doing exactly what the section above said it would. The one round
coordinate is `len=21.0` on row #8, and that is the axis's upper bound.

Twelve trials is a small budget deliberately, and it is smaller than it looks. `DEFAULT_STARTUP` is
10, and `TpeOptimizer::ask` draws seeded-random coordinates until the history reaches that many. So
ten of these twelve asks were random and exactly two were model-driven proposals. This run sits much
closer to random search than to a TPE run at its intended budget.

Two coincidences in the table are worth a second look. Rows #2 and #3 sit at different coordinates
and report identical ret, sharpe, max\_dd and trades. So does row #5, against a point the euler run
below reaches from the other direction.

A period has to become a whole number of bars somewhere, and a threshold only bites when an
observation crosses it, so the continuous box contains flat plateaus. Some of the resolution TPE is
paying for is resolution this strategy cannot use.

## Reproducibility, and the bug that was in this contract [#reproducibility-and-the-bug-that-was-in-this-contract]

Every stochastic step draws from a seeded `SplitMix64` owned by the optimiser, so the same seed
over the same space and the same data produces the same proposal sequence. `SplitMix64` rather than
`rand`'s `StdRng` is deliberate: `StdRng`'s algorithm is not guaranteed stable across versions,
while a ten-line generator is fixed forever.

<Callout type="warn" title="That claim once said byte-for-byte and did not hold across platforms">
  The integer stream was never the leak — SplitMix64 is exact `u64` arithmetic. The leak was the two
  float transforms on top of it: Box–Muller's `ln` and `cos`, and `gaussian_pdf`'s `exp`. IEEE 754
  requires nothing of those, so an `f64` method call reaches the platform's libm and MSVC and glibc
  disagree in the last bit. One perturbed draw moves a sampled coordinate, which moves which
  candidate wins the argmax, which moves the proposal, which moves the history every later proposal
  is built from — the sequences FORK rather than drift. All three transcendentals now call the `libm`
  crate, one implementation compiled into the binary. Both `sqrt` calls are deliberately left as
  `f64` methods, because IEEE 754 does require `sqrt` correctly rounded.
</Callout>

## Comparing against successive halving [#comparing-against-successive-halving]

`--search euler` evaluates the coarse grid once, then repeatedly halves the per-axis step and
re-searches only the immediate neighbourhood of the current best point, clamped to each axis's
range and deduped against everything already evaluated. After `D` halvings the effective resolution
is that of a grid with `2^D·(n−1)+1` values per axis; euler pays at most `N + D·(3^d − 1)`. For a
two-axis 5 × 5 grid at depth 3 that is at most 49 evaluations against 1089 for the
equivalent-resolution grid.

The same profile, halved twice:

```sh
backtest --profile tut_rsi_sweep.toml --search euler --euler-depth 2
```

```text
euler: 16 evaluations at depth 2/2 (grid at the depth reached would be 45)
sweep ranked by sharpe (16 points)
*#1  len=14.0 lo=30.0               ret=0.2129 sharpe=1.7800 max_dd=0.0835 trades=33 score=1.7800
#2   len=17.5 lo=25.0               ret=0.1811 sharpe=1.4293 max_dd=0.1336 trades=16 score=1.4293
#3   len=10.5 lo=30.0               ret=0.1600 sharpe=1.3415 max_dd=0.0830 trades=57 score=1.3415
#4   len=12.25 lo=27.5              ret=0.1578 sharpe=1.3370 max_dd=0.0830 trades=36 score=1.3370
#5   len=12.25 lo=30.0              ret=0.1668 sharpe=1.3085 max_dd=0.0833 trades=43 score=1.3085
#6   len=14.0 lo=27.5               ret=0.1406 sharpe=1.2094 max_dd=0.1148 trades=27 score=1.2094
#7   len=21.0 lo=30.0               ret=0.1542 sharpe=1.1885 max_dd=0.1341 trades=15 score=1.1885
#8   len=14.0 lo=25.0               ret=0.1273 sharpe=1.0656 max_dd=0.1365 trades=21 score=1.0656
#9   len=15.75 lo=27.5              ret=0.1213 sharpe=1.0531 max_dd=0.1313 trades=23 score=1.0531
#10  len=17.5 lo=30.0               ret=0.0980 sharpe=0.8521 max_dd=0.1192 trades=21 score=0.8521
#11  len=15.75 lo=30.0              ret=0.0785 sharpe=0.7099 max_dd=0.0934 trades=26 score=0.7099
#12  len=14.0 lo=20.0               ret=0.0755 sharpe=0.6565 max_dd=0.1402 trades=12 score=0.6565
#13  len=10.5 lo=25.0               ret=0.0606 sharpe=0.5592 max_dd=0.0880 trades=38 score=0.5592
#14  len=7.0 lo=30.0                ret=0.0246 sharpe=0.2807 max_dd=0.0873 trades=103 score=0.2807
#15  len=7.0 lo=20.0                ret=-0.0242 sharpe=-0.1026 max_dd=0.1137 trades=50 score=-0.1026
#16  len=21.0 lo=20.0               ret=-0.0992 sharpe=-0.6544 max_dd=0.1738 trades=2 score=-0.6544
```

The budget line is those two formulas made concrete. Three values and two values per axis at depth 2
reach a grid of 9 × 5 = 45 points, the bound `N + D·(3^d − 1)` is 22, and the run spent 16.

`EulerBudget`'s `equivalent_grid` is derived from the depth REACHED rather than the depth asked for,
so that 45 is a comparison the run actually earned.

`--euler-depth` defaults to `EulerConfig::DEFAULT_MAX_DEPTH` (3) and is capped at 16. A halving
that fails to improve the incumbent is NOT a stop condition — only a smaller step can reach the
points between the incumbent and the ones just rejected — so the search runs its full budget and
stops early only when a depth produces no unseen candidate at all. The `EulerBudget` line on stderr
compares against the grid matching the depth ACTUALLY reached, so an early-stopped run cannot
advertise a saving it did not buy.

The price is that euler is a LOCAL refinement: it can only descend into the basin its coarse grid
already found. Keep the coarse grid wide and treat it as a refinement OF a grid, not a replacement
for one. TPE has no such constraint, and correspondingly no guarantee that it visited the coarse
grid at all.

Scoring is shared: `--rank-by` doubles as the objective for both searches, a row whose backtest
succeeded carries a `score` while a failed one keeps `None` and serializes no `score` key at all,
a failed point steers as `NaN` and is unrankable, and a `NaN` candidate never displaces a finite
incumbent — though euler's first evaluated point becomes the incumbent whatever it scored, so an
all-`NaN` search still refines around one. Note that none of the three search paths PERSISTS a
run — only a single run writes `manifest.json` and `report.json` under `user_data/runs/<run_id>/`.

## What the three runs actually say [#what-the-three-runs-actually-say]

| search                 | evaluations | best sharpe | at                   |
| ---------------------- | ----------- | ----------- | -------------------- |
| grid                   | 6           | 1.7800      | len=14.0 lo=30.0     |
| tpe, 12 trials, seed 7 | 12          | 1.4950      | len=19.02… lo=26.62… |
| euler, depth 2         | 16          | 1.7800      | len=14.0 lo=30.0     |

Neither search beat the grid. TPE spent twice the grid's budget and came back roughly a third of a
sharpe point worse. Euler spent nearly three times the budget and returned the grid's own answer —
the same coordinates, the same 1.7800 — so its ten extra half-step evaluations found nothing better
than the point it started from.

That is the result, and it should stay uncomfortable. A page that ran these three searches and
reported an optimiser win would be reporting a run that did not happen.

Why TPE lost is not mysterious. The best point in this space IS a grid point, and TPE searches the
continuous box between grid points, so it can approach `len=14.0 lo=30.0` and never land on it. Its
two nearest rows, #5 and #6, both score under 1.1.

Turn that around and you have the case FOR TPE: had the good point sat between grid points, the grid
could not have reported it at all, and both searches could.

Four things these runs do NOT say:

* **Not that TPE is worse than a grid.** One seed, one two-axis space, one tape, one objective. Every
  proposal moves when the seed moves, which is the whole point of the reproducibility section above,
  so this is a single draw rather than a measurement.
* **Not that TPE was given a fair budget.** `DEFAULT_TRIALS` is 64. This ran 12, of which 10 were the
  random startup, so the model made two proposals.
* **Not that euler wasted ten evaluations.** A refinement that confirms the incumbent has told you
  the incumbent survives a finer sweep. That is information; it is just not a better number.
* **Not that 1.7800 is an edge.** It is the best of six in-sample numbers on one symbol, one interval
  and one window, picked by looking at all six. Taking the maximum of a set is how you buy a number
  that does not survive contact with new data.

The next step is therefore not a bigger search. It is holding that winner out of sample — see
[Sweep, then walk forward](/docs/trader/tutorials/sweep-and-walk-forward).

## Where next [#where-next]

* [Search](/docs/trader/backtesting/search), [Sweeps](/docs/trader/backtesting/sweeps) and
  [Objectives](/docs/trader/backtesting/objectives).
* [Sweep, then walk forward](/docs/trader/tutorials/sweep-and-walk-forward) — validate what a search
  found.
* [Overfitting](/docs/trader/analytics/overfitting).


# Fit a model and read what it learned (/docs/trader/tutorials/train-a-model)



Vike Trader splits machine learning down one line: **fitting drives a child process, inference is pure Rust**. `crates/vike-ml/src/cli.rs` argues the first half — a measured bakeoff disqualified every Rust binding because they drop `categorical_feature` at dataset construction *silently* and then record it in the saved model's parameter block anyway, an artifact that lies to an auditor — and driving the upstream binary costs no crate, no FFI, no `unsafe`, and nothing in the supply-chain audit surface. `crates/vike-ml/src/infer.rs` and `importance.rs` are the second half: pure functions over the model **text**, working identically everywhere.

That split decides where you can stand. The tool provisioning skips the LightGBM binary on every non-Linux host, because it is a Linux x86-64 executable and fetching it onto Windows or macOS "installs a file nothing there can execute" — you can name it explicitly to stage a project folder for a Linux box. So: fit where the binary runs, read the model anywhere.

## Fit it [#fit-it]

`vike-study` is the study runner that can fit. It is feature-gated (`study-cli`) and lives beside the function it calls rather than in the CLI, which is deliberately kept free of the DataFusion dependency this needs.

```text
vike-study --study NAME --recipe FILE --from WHEN --to WHEN --store DIR
           [--lightgbm PATH] [--scratch DIR] [--runs-root DIR]
```

Three of those flags carry a decision:

* **`--lightgbm PATH`** — the pinned trainer. Omitted, the study runs with **no learner**, and a fitting study refuses **by name** rather than silently producing nothing. Before this binary existed nothing in the workspace could fit a compiled study at all: the Studio's ML surface is the inference half only, so it supplies no learner and a study needing a classifier per fold answered `NoLearner` on every invocation.
* **`--scratch DIR`** — per-fit scratch, defaulting under the **project folder, never the system temp directory**.
* **`--recipe FILE`** — the study's own TOML, which may carry a `[learner]` table.

That table exists because a study's non-searched LightGBM parameters are a property **of the study** — the keys its published numbers were measured at — while the learner type knows nothing about any study. In the cohort study those five keys had no home a host could reach: they lived in a test-only module, so any real run would have used LightGBM's defaults and quietly fitted a different model than the one every recorded number came from. An absent table means the trainer's own defaults, which is the right answer for a caller with no opinion and the wrong one to assume in silence — so **the run prints which of the two it used**.

## The pins, and what they do not catch [#the-pins-and-what-they-do-not-catch]

Two constants decide whether a model file and this crate are talking about the same thing: `MODEL_VERSION`, the text's own `version=` line, and `PINNED_LIGHTGBM_TAG`, the upstream release the binary was built from, asserted at startup by `LightGbmCli::new`.

<Callout type="warn" title="The binary cannot name itself">
  `lightgbm --version` does not exist — upstream's `main.cpp` has no version handling, and the flag just produces an unknown-parameter warning and a non-zero exit. So the check reads the `tag=` line out of the `PROVENANCE` file the build recipe writes beside the binary. A binary with no `PROVENANCE` beside it — the ordinary state of one built by hand — is a refusal naming both paths and the recipe to fix it, never a panic. The honest weakness, stated in the module rather than implied: that file is self-reported by our own recipe and only its `tag=` line is ever read.
</Callout>

The deeper residual is worth carrying before you trust a version check: `version=v4` does **not** change when fields are added within v4, and the parser tolerates unknown `key=value` lines silently — it must, since LightGBM already writes several the walker has no use for. A new per-node array with routing meaning would be read as noise, dropped, and every prediction would be quietly wrong while the version check stayed green. The equality gate that trains and predicts through both implementations, not the version check, is the real proof.

## Packing the data [#packing-the-data]

`TrainData::new(x, y, n_cols)` validates the shape **once, here**, rather than letting a child process discover it and report it as a parse error forty lines into a file. `x` is row-major `n_rows × n_cols` `f64`; `y` is one `f32` label per row, because `f32` is LightGBM's own label width. `with_categorical` declares categorical columns and refuses an index outside a row.

<Callout type="warn" title="The list-parameter trap, and the type that closes it">
  `GbdtParams` spells LightGBM's own parameter names, and each field is rendered as one `key=value` line. LightGBM splits list parameters on commas but does **not** strip brackets: `categorical_feature=0,3` names two columns, while `categorical_feature=[0,3]` — the shape anyone reaches for who has used the Python API — names *nothing*. The column would then be binned as numerical, nothing would error, and the saved model's `parameters:` echo would still claim it was categorical. The defence is a type rather than a comment: the field is an `Option<String>`, so a list cannot be written, and `categorical_feature_csv` is how a list of indices becomes one. Indices are 0-based over feature columns; the label column is not counted.
</Callout>

The five searched axes travel separately as a `GridPoint`: `num_leaves`, `max_depth`, `min_data_in_leaf`, `learning_rate`, `feature_fraction`. `DEFAULT_POINT` is `15 / 4 / 20 / 0.05 / 0.7` — conservative on every axis relative to LightGBM's own `31 / -1 / 20 / 0.1 / 1.0` — and its doc is emphatic that it is a **fallback, not a recommendation**: a caller that reaches it has learned nothing about its data.

## Read what came out [#read-what-came-out]

`crates/vike-studio-core/src/ml.rs`'s `ScoringModel` is the whole reading surface. `from_path` or `from_text` parses the walked model **and** its importance table in one load, and refuses as one — a text whose two halves disagree is not half-loaded. Then:

* **`score_rows(flat_x, n_features)`** turns a row-major matrix into the probability series, checking the stride once for the whole matrix and refusing a length that is not a whole number of rows.
* **`score_row(row)`** is the checked single-row door. It refuses a row narrower than the model, because the walker substitutes `NaN` for a column the row does not carry, routes that through the tree, and returns a probability that *looks* like a probability. A wider row is fine; its trailing columns are ignored.
* **`importance_ranked()`** returns `FeatureWeight` rows — index, optional name, `gain`, `splits` — ordered descending by gain with ties broken by ascending index, compared with `total_cmp` so a `NaN` out of a doctored text sorts to one end instead of corrupting the sort.

<Callout title="Every feature, including the ones no tree split on">
  `importance_ranked` deliberately keeps the zero rows. "This input mattered not at all" is an answer, and it is the half of the report that tells you what to stop computing.
</Callout>

Names are the last thing to check. The training CSV this crate writes is headerless, so LightGBM auto-generates `Column_0`, `Column_1`, … and index-to-name mapping belongs to whoever packed the matrix. A model naming **no** column is therefore accepted and every weight's name is `None`; one naming **some** is refused, because that is the shifted-table shape, and a misaligned importance table attributes the model's behaviour to the wrong feature — worse than no table at all.

Next: [models](/docs/trader/research/models) for the learner seam, [training](/docs/trader/research/training) and [inference](/docs/trader/research/inference) for each half, [feature importance](/docs/trader/research/feature-importance) for the parse, and [model pins](/docs/trader/research/model-pins) for the bump procedure.


# Troubleshooting (/docs/trader/troubleshooting)



Every entry is *symptom → cause → fix*, the symptom quoted as it appears in the log or on screen.
Two rules explain most of them. Absent credentials **are** the live gate: a venue with no keys
stays paper, silently, by design. And every misconfiguration splits two ways — **refuse** when a
silent difference would leave you believing a protection is armed when it is not (a ceiling, an
arming flag), **degrade** when "unconfigured" is a state you may have chosen (a venue connection, a
feed, a credential set). `vike-cli config check` states that rule and applies it finding by finding,
one exit code for the lot (`crates/vike-cli/src/cmd/config_check.rs`). Every refusal fires before
any venue is mounted; a degrade may only *reduce* the program's authority, never redirect it.

<Callout title="Read the startup disclosure first">
  `vike-desktop`, `vike-tradehub` and `vike-recorder` print what they resolved once a subscriber exists
  (`crates/vike-config/src/boot.rs`'s `boot_lines`): the settings directory, one line per settings
  file, every `policy.*` ceiling, and whether a credential store was found beside them — by presence,
  never by contents. Most "why is it paper" questions are answered there; `vike-cli config show`
  prints the rest.
</Callout>

## Install [#install]

* **`version 'GLIBC_2.39' not found` at exec (Linux).** The release binaries are glibc-dynamic on
  the release runner, measured at 2.39, and an older host fails at exec rather than at build
  (`deploy/docker/Dockerfile`'s base-image note). Fix: a host at 2.39 or newer, or the
  [container](/docs/trader/getting-started/install-docker).
* **`status=203/EXEC` from systemd.** The unit's `ExecStartPre=` runs `bin/vike-cli config check`,
  so the daemon needs that second binary beside it (`deploy/vike-datahub.service`).
* **`status=226` from systemd.** The system manager refuses a unit whose `ReadWritePaths=` names a
  missing path — `<project>/settings/state`. A `--user` manager does not refuse, so a clean
  `--user` start proves nothing. Fix: create the directory.
* **Container: every venue on paper, no error.** Docker's default working directory is `/` and an
  unmounted `/project` is an empty directory, so the settings walk finds nothing;
  `deploy/docker/entrypoint.sh` refuses this and names the `-v` flag. From Git Bash on Windows,
  MSYS path conversion rewrites the container side of `-v C:\vike-trader:/project` to
  `…:C:/Program Files/Git/project`. Fix: PowerShell or WSL, or `MSYS_NO_PATHCONV=1`.
* **Dukascopy: `bridge jar not found`, venue on paper.** The sidecar jar is a release asset.
  `crates/bridges/dukascopy/src/config.rs`'s `resolve_dukascopy_tools` looks at `JFOREX_BRIDGE_JAR`
  (blank is ignored), then `<project>/bin/jforex/jforex-bridge.jar`; the JVM is `JAVA_HOME/bin/java`
  when that file exists, else `<project>/bin/jre/*/bin/java`, else `java` from `PATH`. Fix:
  `crates/bridges/dukascopy/scripts/provision-jforex.sh` (`provision-jforex.ps1` on Windows), which
  supplies both the runtime and the jar, or point `JFOREX_BRIDGE_JAR` at any copy. An **instant**
  `login failed` afterwards is a corrupted platform cache, not a credential problem — delete
  `%LOCALAPPDATA%\JForex` and retry.

## Credentials and arming [#credentials-and-arming]

<Callout type="warn" title="No project above the working directory is silent">
  "There are no settings here" and "the settings here say nothing" are indistinguishable downstream,
  so a daemon that resolved no project loads no policy, no config and no credentials and trades every
  venue on paper with no error — the incident `vike_boot`'s module header is made of.
</Callout>

* **Every venue on paper; the log sits beside the executable; the store line says
  `rung=user-dir`.** No project marker above the working directory. The walk
  (`crates/vike-model/src/state_path.rs`'s `project_settings_dir`) takes the outermost `Cargo.toml`
  declaring `[workspace]`, else the nearest `Cargo.toml` or `settings/` directory; the probe is
  `is_dir`, so creating `<project>/settings/` is the whole fix. `VIKE_SETTINGS_DIR` names it
  outright and beats the walk.
* **`credential store could not be opened, continuing with NO credentials (every venue stays
  paper)`.** The store exists and is unreadable — an error, where an absent store is the ordinary
  silent state (`crates/vike-secrets/src/store.rs`'s `resolve`). Fix: the file's permissions;
  `vike-cli secrets path` prints the one location consulted.
* **`… holds live venue credentials in PLAINTEXT and is readable beyond its owner (mode 0644)`.**
  A finding, not a refusal; the credentials load anyway. Fix: the `chmod 600` the line prints.
* **`<project>/.env is present but the credential store <project>/settings/secrets.env is NOT`.**
  Nothing reads a project-root `.env` since credentials moved into the settings directory
  (`LegacyStoreWarning`). Fix: copy the venue keys into the store.
* **"I have credentials and the venue is still paper."** The ceiling refused: `ARMING CEILING: <venue> has live credentials, and this deployment's ceiling for it is paper → staying PAPER`
  (`crates/vike-mount/src/paper_fallback.rs`'s `report_capped_to_paper`). Credentials and no
  `[venues]` table gets one `ARMING CEILING NOW IN FORCE` block per process listing every affected
  venue; writing the table at all silences it, and a ceiling can only refuse — `live` does not put a
  venue live. See [Risk and arming](/docs/trader/concepts/risk-and-arming) and
  [`policy.toml`](/docs/trader/reference/settings/policy).
* **The Data Manager's Venues rows name a block.** A row is one venue *account* — a box with no
  `[accounts]` table gets exactly one per roster venue, the default account's — and its
  `ArmingBlock` names its own fix. `Disarmed` (the ceiling), `NoCredentials` (the Connections tab),
  `LiveCredentialsAbsent` (the store holds demo-tier keys only), `MainnetSwitchUnset` (a `live`
  ceiling still resolves demo without `{VENUE}_MAINNET`), `FeatureAbsent` (this binary has no arm
  for ibkr/polymarket/fxcm), `SdkAbsent` (FXCM, below), `ExecFlagUnset` (`POLY_EXEC=1`),
  `NoMountInThisBuild` (the desktop, which mounts no venue), `NoLiveArm` (dukascopy, whose exec factory is mounted in no
  build, so it can only ever be paper), `DemoOnlyArm` / `LiveOnlyArm` (the arm has no such tier — a
  `demo` ceiling over polymarket resolves paper), and, on a labelled second account,
  `AccountNotNamed` (no `policy.accounts.<venue>.<LABEL>` line of its own) or `NoAccountSupport`
  (that venue's arm cannot address a second account at all). `ArmingBlock::ALL`
  (`crates/vike-config/src/venue_arming.rs`) is the whole vocabulary.
* **`vike-desktop` exits with code 2 before a window appears; the daemon prints the same message and
  stops.** Three refusals, in `vike_boot::boot`'s order: a removed variable is set
  (`VIKE_MAX_ORDER_NOTIONAL` or `VIKE_TRADEHUB_MAX_ORDER_NOTIONAL` → `max_notional_per_order` in
  `policy.toml`; `VIKE_SECRETS_PASSPHRASE`, which nothing consumes — `crates/vike-config/src/removed.rs`'s
  `REMOVED_ENV`; an empty value does not count); a `{VENUE}_MAINNET=1` line inside `secrets.env`
  (`crates/vike-config/src/arming.rs` — move it to the process environment); or a settings file that
  exists and is broken. See [Environment variables](/docs/trader/reference/environment).
* **`refusing LIVE mount: no project settings dir resolved`.** A live-armed venue with no project
  has nowhere to keep its live-account sentinel, so `crates/vike-desktop/src/main.rs` refuses rather than
  mounting unguarded. Fix: `VIKE_SETTINGS_DIR`, or run inside the project.
* **`tradehub observe auth denied: bad mac` on a loop.** The client had no key and
  signed with an empty one; `crates/vike-app-core/src/backend_conn.rs` now logs `no observe key:
  VIKE_TRADEHUB_OBSERVE_KEY is absent from the credentials map` first. The key comes from the store;
  an environment value fills it only when the store has none (`backend_registry.rs`'s
  `fill_node_keys_from_env`) and the control key is never filled. It must match the daemon's byte
  for byte. Daemon side, `observe server NOT started` names its cause: no observe key in the store,
  or a non-loopback `tradehub_addr` — keep it on `127.0.0.1` behind an SSH tunnel, or set
  `tradehub_allow_public_bind = true` in `flags.toml` (`crates/vike-tradehub/src/tradehub_cli.rs`).
  See [Observe mode](/docs/trader/gui/observe-mode).

## Feeds [#feeds]

* **The chart stays empty after picking a symbol.** The node carries live clients for six
  venues while the picker searches a twelve-venue catalog, so an alpaca, oanda, dukascopy, fxcm or
  ctrader instrument lands on a venue with no bar feed (`crates/vike-app-core/src/feed_lifecycle.rs`).
  Fix: the same instrument on a venue with a feed.
* **The picker shows only the built-in quick-picks.** The catalog has not loaded or the fetch
  failed; `crates/vike-desktop/src/chart_window.rs` falls back to `SYMS`, Binance symbols, and choosing
  one resets the venue to Binance.
* **`reconcile leg suppressed: venue health probe reports Degraded`.** That venue's feed is mid-gap
  or the network is down; its reconcile leg is deferred and other venues are unaffected
  (`crates/vike-core/src/recon_manager.rs`'s `should_reconcile`). Nothing to fix.
* **Polymarket dials fail at the SOCKS connect.** The proxy is on by default at
  `socks5h://127.0.0.1:1080` (`crates/bridges/polymarket/src/egress.rs`'s `proxy_url`). Fix:
  `POLY_PROXY_ENABLED=false` if you are not geo-blocked, `POLY_PROXY_HOST`/`POLY_PROXY_PORT`, or a
  full `POLY_SOCKS_PROXY`; keep `socks5h`, since plain `socks5` resolves DNS locally and hits the
  block. The venue geo-blocks order *placement* only — a submit is the one call that returns 403 —
  and the live mount probes that first and refuses on a positive answer
  (`crates/bridges/polymarket/src/egress.rs`'s `check_order_placement_geo`, decided by
  `crates/bridges/polymarket/src/mount.rs`'s `geoblock_action`).

## Mounts [#mounts]

* **cTrader or IBKR on paper after a startup outage.** Their handshakes are blocking and fallible
  at mount, and a failure demotes the venue to paper for the whole session with no in-thread
  reconnect (`crates/vike-mount/src/lib.rs`'s `("ctrader", _)` and `("ibkr", _)` arms). Fix:
  restart once the gateway answers. A cold-start `CH_ACCESS_TOKEN_INVALID` with a valid-looking
  pair on disk means a rotated refresh token was never written back to the store.
* **FXCM mounts paper whatever the store says.** `vike_fxcm::sdk_linked()` is `cfg!(fcsdk)`, set
  only when `build.rs` found the ForexConnect SDK; no CI build has ever linked it. `spawn` is
  infallible, so there is no connect result to demote on: a bad password, an unreachable gateway and
  a stub build are indistinguishable from outside. The stub is the only one this arm can catch — it
  refuses out loud and lands on paper. A live-but-failing login mounts "live" and trades nothing,
  and reconcile is what notices.
* **`polymarket: POLY_RECONCILE=1 without a live exec mount → RECONCILE-ONLY (exec is PAPER)`.**

<Callout type="warn" title="Run a recon-only Polymarket mount under quarantine">
  `PositionDrift` is the one divergence kind `hybrid` auto-applies, and against a paper engine it
  imports the live account's position into the paper books at the venue's average price. Set
  `VIKE_RECONCILE_POLICY=quarantine`, or arm `POLY_EXEC=1` so both sides are the same account.
  `crates/bridges/polymarket/src/recon_client.rs`'s `poly_reconcile_enabled` carries the argument,
  kind by kind.
</Callout>

* **New orders come back rejected; cancels and reduce-only exits still work.** The HALT sentinel
  exists: a risk-OPENING submit is refused with a synthesized terminal `OrderRejected` while under
  the default policy a `reduce_only` one is admitted (and logged), a modify is dropped, and cancel
  is never gated (`crates/vike-bridge-core/src/exec_actor.rs`, `crates/vike-exec/src/halt.rs`'s
  `halt_admits_submit`). The path is `VIKE_HALT_FILE`, else `<project>/settings/state/HALT`, else
  `<exe_dir>/HALT` as a reported last resort (`crates/vike-bridge-core/src/halt.rs`). See
  [Halt](/docs/trader/concepts/halt) and
  [Stop, liquidate, restart](/docs/trader/guides/stop-liquidate-restart).
* **BUY/SELL greyed out; the status line reads `CORE FAULT: <fault>`.** A handler panicked. The core
  neither dies nor keeps trading: it enters safe-state — trading state `Halted`, working orders get a
  best-effort cancel, and the engine is never traded on again until the process restarts
  (`crates/vike-core/src/runtime/mod.rs`). The fault is what the GUI reads:
  `crates/vike-app-core/src/core_sync.rs` writes the status line from `snap.fault`, the trade tool's
  header repeats it as `⚠ <fault>`, and the buttons arm on `snap.fault.is_none()`
  (`crates/vike-app-core/src/tool_views/trade.rs`) — not on the trading state. Fix: restart, then
  read the fault.

## The store and the logs [#the-store-and-the-logs]

* **A run reports zero rows; "my tape is empty".** The store resolved on a different rung than you
  assumed. Precedence (`crates/vike-model/src/store_path.rs`): `--store` / a profile's `store =`,
  then `VIKE_HIST_STORE` — which also overrides `config.toml`'s `store_root` — then the project
  `VIKE_SETTINGS_DIR` declares, then the source checkout that built the binary, then the discovered
  project, then the per-user directory. The startup line carries `rung=` and a sentence saying why.
  See [The history store](/docs/trader/concepts/hist-store).
* **The JSON log grows without bound.** The file layer defaults to `trace` and `RUST_LOG` /
  `VIKE_LOG` filter the console only; one hour of a backfill measured 6.4 GB. Fix:
  `VIKE_LOG_FILE_LEVEL=warn` or `off` (`crates/vike-log/src/lib.rs`'s `file_level_directive`).
  Retention keeps `DEFAULT_MAX_LOG_FILES` daily files, three, and cannot help when one day is the
  file — a desktop client measured 5.8 GB in 4h10m before the per-frame `wgpu_core`, `wgpu_hal`,
  `naga` and `eframe::native` targets were pinned to `info`.
* **The log lands beside the executable.** `resolve_log_dir` is `VIKE_LOG_DIR`, then
  `config.log_dir`, then `<project>/settings/state/logs`, then `<exe_dir>/logs` — the last resort
  means no project resolved, the same cause as the paper-everywhere entry above.

## The GUI [#the-gui]

* **Empty boxes where the window controls should be (Linux, the container).** egui's bundled face
  has none of `✕ ─ □ ❐ ●`; the shell loads a symbol face from `crates/vike-app-core/src/fonts.rs`'s
  `SYMBOLS` candidates — Segoe UI Symbol, Noto Sans Symbols 2, DejaVu Sans — and a missing file is
  a silent `false`. Fix: install DejaVu or Noto Sans Symbols 2.
* **The saved layout did not come back.** `crates/vike-app-core/src/startup.rs`'s
  `restored_workspace` returns `None` under `VIKE_SHOT`, which needs the default windows; otherwise
  the last named layout wins, then `workspace.json` under `<project>/settings/state`.
* **`VIKE_SHOT=1` wrote a file named `1`.** The variable takes the output *path*, drops a
  `<path>.dbg` beside it, and captures at frame `VIKE_SHOT_FRAME` (default 180) on a visible frame,
  so the window asks to be always-on-top and focused (`crates/vike-desktop/src/main.rs`).

Each install page's Troubleshooting block — [Windows](/docs/trader/getting-started/install-windows),
[Linux](/docs/trader/getting-started/install-linux), [Docker](/docs/trader/getting-started/install-docker) —
points at the entries above that apply to it. A failure not listed here is worth a report with the
startup disclosure attached.


# Claude Code (/docs/ai/data/setup/claude-code)



One command, and `--transport http` is the load-bearing part of it.

## Add the server [#add-the-server]

```sh
claude mcp add --transport http vike https://vike.io/mcp \
  --header "X-API-KEY: $VIKE_API_KEY"
```

`--transport http` is required: Vike's endpoint is Streamable HTTP, not a stdio subprocess.
Without it Claude Code tries to launch `https://vike.io/mcp` as a command.

Claude Code stores MCP servers per scope — local, project, or user — and `claude mcp add` takes a
`--scope` flag to choose. Check `claude mcp list` after adding to confirm the session you are in
can see it. ⚠ If you scope the server to a project, its configuration lands in a file that may be
committed: read the key from an environment variable, as above, rather than pasting it in.

**Restart any Claude Code session that was already open.** Sessions read the server list at
start; an existing session will not see the new server.

<Callout title="The trader server is a second `claude mcp add`">
  `vike-cli mcp` is a local command rather than a URL, so it is added without `--transport` and
  lands in the same server list — under a different name, since Claude Code keys servers by name.
  See [Trader / Claude Code](/docs/ai/trader/setup/claude-code).
</Callout>

## Verify [#verify]

```sh
claude mcp list
```

`vike` should appear with its URL. Then, in a session:

> Search for PEPE token using Vike

calls `token_search` at 0 credits. If it returns tokens, the transport, the credential and tool
dispatch are all working.

## Removing or replacing it [#removing-or-replacing-it]

```sh
claude mcp remove vike
```

To rotate the key, remove the server and add it again with the new header. Deleting the old key
under **Account → API Keys** is what actually retires it — the entry in Claude Code holds no
authority over it.

## Troubleshooting [#troubleshooting]

**Nothing happens when you ask.** Check `claude mcp list` first. If the server is absent, the add
command wrote to a scope the session is not reading; re-add naming the scope explicitly.

**The server is listed but every call fails.** The key is the likely cause. Test it directly:

```sh
curl -s https://vike.io/mcp \
  -H "X-API-KEY: $VIKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | head -c 400
```

A working key returns a `result` with the tool list. A bad one returns
`{"jsonrpc":"2.0","id":null,"error":{"code":-32000,"message":"Invalid or missing API key"}}` at
**HTTP 401**. The full walkthrough is on [Raw HTTP](/docs/ai/data/setup/raw-http).

**`$VIKE_API_KEY` expanded to nothing.** The add then registers an empty header and every call
fails authentication. Echo the variable before running the command.

**Calls suddenly return `-32000` with "Hourly rate limit exceeded".** That is the shared counter
across MCP, REST and the archive — most often spent by an archive download read over HTTP rather
than by tool calls. See [Rate limits](/docs/data/rate-limits).


# Claude Desktop (/docs/ai/data/setup/claude-desktop)



Claude Desktop is the one client that needs no credential from you. It registers itself with
Vike's authorization server and you approve access in a browser; nothing is copied or pasted.

## Add the connector [#add-the-connector]

1. Open **Settings → Connectors → Add custom connector**
2. Name: `Vike`
3. URL: `https://vike.io/mcp`
4. Leave the **OAuth Client ID** and **Client Secret** fields empty
5. Click **Add**. A browser tab opens — log into Vike and click **Allow**
6. The Vike tools appear under the hammer icon in the chat input

Leaving the client id and secret empty is the point, not a shortcut: Claude Desktop calls
`POST /oauth/register` ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) and gets its
own credentials. Filling those fields in is for a client you registered yourself.

<Callout title="The trader server is a config file, not a connector">
  `vike-cli mcp` is a local process rather than a URL, so it cannot be added as a connector at all
  — it goes in `claude_desktop_config.json`, which the same Settings window opens under
  **Developer → Edit Config**. That setup is on
  [Trader / Claude Desktop](/docs/ai/trader/setup/claude-desktop).
</Callout>

## What Vike's authorization server implements [#what-vikes-authorization-server-implements]

Discovery is standard, so most OAuth-capable clients find everything from the endpoint URL
alone:

| Document                                                                                  | Path                                      |
| ----------------------------------------------------------------------------------------- | ----------------------------------------- |
| Authorization Server Metadata ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)) | `/.well-known/oauth-authorization-server` |
| Protected Resource Metadata ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728))   | `/.well-known/oauth-protected-resource`   |
| Dynamic Client Registration                                                               | `POST /oauth/register`                    |
| Authorization                                                                             | `GET`/`POST /oauth/authorize`             |
| Token                                                                                     | `POST /oauth/token`                       |
| Revocation ([RFC 7009](https://datatracker.ietf.org/doc/html/rfc7009))                    | `POST /oauth/revoke`                      |

What the server advertises and enforces:

* **Scope** — `mcp:tools` is the only scope, and a registration requesting anything else is
  refused with `invalid_scope`.
* **Grants** — `authorization_code` and `refresh_token`. Response type `code`.
* **PKCE** — `S256` is mandatory and is the only method offered. OAuth 2.1 forbids the `plain`
  method and so does this server.
* **Token lifetimes** — authorization code 10 minutes, access token 1 hour, refresh token 30
  days, and a refresh rotates the token.
* **Redirect URIs** — validated against an allowlist (`claude.ai` and loopback addresses), so a
  stranger cannot register a client that redirects your approval somewhere else.

Tokens and client secrets are stored as SHA-256 hashes; a plaintext value is returned exactly
once, at creation.

## Approving, and taking it back [#approving-and-taking-it-back]

The consent screen requires an authenticated Vike session — if you are signed out, Vike parks
the return URL and bounces you through sign-in first, then back to the same consent.

Connected apps are listed under **Account → API Keys → Connected Apps**, one entry per client.
Revoking one revokes every non-revoked token that client holds for your account and leaves your
other connected clients alone. The client registration itself is not deleted — reconnecting is
a fresh approval, not a re-registration.

⚠ Revocation is not instant. A validated token is cached for **45 seconds**, so a revoked token
can keep authenticating for that window.

## Verify [#verify]

> Search for PEPE token using Vike

calls `token_search` — **0 credits** — and returns matching tokens, which proves the transport,
the OAuth token and tool dispatch in one go.

If the hammer icon shows no Vike tools, the connector was added but authorization did not
complete; remove it and add it again, watching for the browser tab. If the tools are listed but
never used, name one in the prompt — "use the vike `token_search` tool" — since Claude decides
per request whether to reach for a tool.

<Callout title="OAuth calls share one hourly budget per user">
  OAuth usage rows carry `api_key_id = 0` and the hourly counter is keyed on `user_id`, so every
  OAuth-connected app on your account draws from one budget — unlike API keys, which get one each.
  See [Rate limits](/docs/data/rate-limits).
</Callout>


# Cursor (/docs/ai/data/setup/cursor)



## Add the server [#add-the-server]

Either **Settings → MCP → Add new server**, or edit the config file directly.

Global, at `~/.cursor/mcp.json` — available in every project:

```json
{
  "mcpServers": {
    "vike": {
      "url": "https://vike.io/mcp",
      "headers": { "X-API-KEY": "YOUR_KEY" }
    }
  }
}
```

Per project, at `.cursor/mcp.json` in the repository root — same shape, scoped to that project.

`url` + `headers` is the **remote** shape, and it is the only one that works here: Vike's data
endpoint is an HTTP service, not a process Cursor launches, so a `command` key in this entry will
not reach it.

<Callout title="The trader server is a sibling entry in this file">
  `vike-cli mcp` is a local subprocess and takes the other shape — `command` + `args` — inside the
  same `mcpServers` object, under a different name. See [Trader / Cursor](/docs/ai/trader/setup/cursor).
  The two share nothing: not a credential, not a budget, not a transport, so one failing says
  nothing about the other.
</Callout>

## Keep the key out of the repository [#keep-the-key-out-of-the-repository]

A per-project `.cursor/mcp.json` sits inside the repository, so a pasted key is one `git add`
away from being committed. Either add the file to `.gitignore`, or keep the server in the global
`~/.cursor/mcp.json` instead.

If a key does get committed, delete it under **Account → API Keys** and create a new one.
Deletion is the fix; rewriting the file is not, because the old key keeps working until it is
deleted — and briefly after, while the auth cache expires.

## After editing [#after-editing]

Reload Cursor, or toggle the server off and on in the MCP pane. The settings pane shows each
server's status and the tools it exposes — a healthy `vike` entry lists **31**.

## Verify [#verify]

> Search for PEPE token using Vike

`token_search` costs 0 credits, so this is free to repeat while you get the configuration right.

## Troubleshooting [#troubleshooting]

**The server shows as failed.** Almost always the JSON: a trailing comma, or a key nested in the
wrong object. `url` and `headers` are siblings *inside* the `vike` object.

**The server is green but tools are never called.** Cursor decides per request whether to use a
tool. Name it — "use the vike `token_search` tool for PEPE" — to confirm the wiring before
trusting the model to reach for it on its own.

**Every call errors.** Test the key outside Cursor with the
[raw HTTP](/docs/ai/data/setup/raw-http) `tools/list` call. ⚠ An authentication failure comes back as
HTTP 200 with a JSON-RPC error in the body, so a client that only checks the status code reports
success on a rejected call.

**A project config and a global config both exist.** Keep the server in one of them. Two entries
named `vike` with different keys will bill two different budgets depending on which one wins,
which makes usage in **Account → API Keys** hard to read.


# Gemini CLI (/docs/ai/data/setup/gemini-cli)



## Add the server [#add-the-server]

```sh
gemini mcp add --transport http \
  --header "X-API-KEY: $VIKE_API_KEY" \
  vike https://vike.io/mcp
```

The argument order is options, then the name (`vike`), then the URL. `--transport http` is
required — the default transport is stdio, which expects a local command rather than a URL.

<Callout title="The trader server is the same subcommand without `--transport`">
  `vike-cli mcp` is a local command, so it is added on the default stdio transport and joins the
  same server list under a different name — a second `vike` would replace this one. See
  [Trader / Gemini CLI](/docs/ai/trader/setup/gemini-cli).
</Callout>

## Verify [#verify]

```sh
gemini mcp list
```

Then, in a session:

> Search for PEPE token using Vike

`token_search` costs 0 credits, so a failed attempt costs nothing.

## Troubleshooting [#troubleshooting]

**The command is rejected as malformed.** Check the argument order: options, then the server
name, then the URL. A header containing spaces must be quoted as one argument, exactly as above.

**The server is added but every call errors.** Test the credential outside the CLI:

```sh
curl -s https://vike.io/mcp \
  -H "X-API-KEY: $VIKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | head -c 400
```

A working key returns a `result` carrying the tool list. ⚠ A bad key returns a JSON-RPC error at
**HTTP 200**, not a 4xx — see [Raw HTTP](/docs/ai/data/setup/raw-http) for the exact shapes.

**`$VIKE_API_KEY` expanded to nothing.** The command then registers an empty header and every
call fails authentication. Echo the variable before running the add, or paste the key literally
into a shell you trust.

**Calls start returning "Hourly rate limit exceeded".** That counter is shared across MCP, the
REST API and the archive. See [Rate limits](/docs/data/rate-limits).


# Client setup (/docs/ai/data/setup)



The data server is a **URL every client points at**: `https://vike.io/mcp`, one Streamable HTTP
endpoint carrying all 31 tools. Nothing is installed and nothing runs locally. What differs per
client is only where the configuration lives and how a credential header is spelled.

Call the server `vike` — the name the rest of these docs uses.

<Callout title="The trader server goes in the same file">
  Vike ships a [second MCP server](/docs/ai) for the trading platform — `vike-cli mcp`, a local process
  rather than a URL — and for most clients its entry sits beside this one in the same config file
  or the same CLI. It is set up on its own pages: [Trader / Client setup](/docs/ai/trader/setup). Give
  it a different name (`vike-trader`) if you add both: a client keys its servers by name, so a
  second `vike` replaces the first.
</Callout>

## Pick your client [#pick-your-client]

| Your client               | How the credential is carried                           | Page                                            |
| ------------------------- | ------------------------------------------------------- | ----------------------------------------------- |
| Claude Desktop            | OAuth 2.1, registered automatically — no key at all     | [Claude Desktop](/docs/ai/data/setup/claude-desktop) |
| Claude Code               | `X-API-KEY` header on `claude mcp add --transport http` | [Claude Code](/docs/ai/data/setup/claude-code)       |
| Cursor                    | `X-API-KEY` in `mcp.json`'s `headers` object            | [Cursor](/docs/ai/data/setup/cursor)                 |
| Gemini CLI                | `--header "X-API-KEY: ..."` on `gemini mcp add`         | [Gemini CLI](/docs/ai/data/setup/gemini-cli)         |
| GitHub Copilot in VS Code | `X-API-KEY` in `.vscode/mcp.json`, `"type": "http"`     | [VS Code](/docs/ai/data/setup/vs-code)               |
| A script, or curl         | `X-API-KEY` header on every `POST`                      | [Raw HTTP](/docs/ai/data/setup/raw-http)             |

## The credential [#the-credential]

Two are accepted, and they are tried in this order:

1. `Authorization: Bearer vk_oat_...` — an OAuth 2.1 access token. Clients that support Dynamic
   Client Registration ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) register
   themselves and you approve access in a browser; no key is ever copied. This is the Claude
   Desktop path.
2. `X-API-KEY: vk_...` — a long-lived key you create under **Account → API Keys**. Every other
   client uses this.

The rule behind the table above: **a client that speaks OAuth Dynamic Client Registration needs
no key at all**; everything else sends a header. Claude Desktop is the one client in this list
that does the former today.

Both credentials resolve to the same account and reach the same 31 tools. The difference that
matters later is how the hourly counter is keyed — per key for `X-API-KEY`, pooled per user for
OAuth. See [Rate limits](/docs/data/rate-limits).

## Where an API key comes from [#where-an-api-key-comes-from]

Create one under [Account → API Keys](https://vike.io/account?tab=api-keys). **Up to five may be
active at once** — the sixth is refused with `Maximum 5 active keys allowed`. The key is shown
once, at creation.

[Getting started](/docs/data/getting-started) walks that, and [Authentication](/docs/data/authentication)
covers both credential types in full.

## Verify the connection [#verify-the-connection]

Whichever client you set up, one prompt proves the whole path — transport, credential and tool
dispatch — rather than just the config file being read:

> Search for PEPE token using Vike

That calls `token_search`, which costs **0 credits**, so a failed verification attempt costs
nothing.

If nothing happens, three checks in order:

1. **Is the server listed at all?** Every client has a way to show its configured MCP servers.
   If Vike is missing, the config file was not read — usually a restart, or the wrong file.
2. **Is the credential reaching the server?** Run the [raw HTTP](/docs/ai/data/setup/raw-http)
   `tools/list` call with the same key: it either returns 31 tools or an explicit error. ⚠ That
   error arrives at **HTTP 200** with the failure in the JSON-RPC body, so a status-code check
   alone is not a test.
3. **Did the tools load but not get used?** Some clients require you to enable a server's tools
   per conversation. Name the tool in your prompt — "use the vike `token_search` tool" — to force
   the issue.

## Revoking access [#revoking-access]

* **API keys** — delete the key under **Account → API Keys**.
* **OAuth clients** — revoke under **Account → API Keys → Connected Apps**. Revocation kills
  every non-revoked token that client holds for your account and leaves your other connected
  clients alone.

Neither takes effect instantly. A validated credential is cached for **45 seconds**, so a revoked
key or token can keep authenticating for that window — a deliberate trade of a few seconds of
staleness for not re-validating the credential from scratch on every request. Rotate by creating
the new credential first, moving traffic to it, then deleting the old one.


# Raw HTTP (/docs/ai/data/setup/raw-http)



An MCP client handles this protocol for you. You need it anyway when you are scripting against
the server, or when a client will not connect and you want to know whether the fault is yours or
its.

Everything is `POST https://vike.io/mcp` with `Content-Type: application/json` and one credential
header — `X-API-KEY: vk_...`, or `Authorization: Bearer vk_oat_...` for an OAuth token.

<Callout title="The trader server is a pipe, not a URL">
  Vike's other MCP server, `vike-cli mcp`, speaks the same JSON-RPC 2.0 over stdio instead of HTTP,
  so there is nothing to curl and its result envelope differs. That protocol walkthrough is on
  [Trader / Raw stdio](/docs/ai/trader/setup/raw-http).
</Callout>

## The handshake [#the-handshake]

Every session opens with `initialize`:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": { "name": "my-client", "version": "1.0.0" }
  }
}
```

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": { "tools": {} },
    "serverInfo": { "name": "vike-mcp", "version": "1.0.0" }
  }
}
```

The server answers with its own protocol version — it does not echo the version you asked
for — and advertises `tools` and nothing else: there are no resources, prompts
or sampling capabilities to negotiate. A client may follow with `notifications/initialized`,
which is accepted and answered with an empty result.

`initialize` is not a gate. Each method is dispatched on its own, so the one-line version of "is
this thing working" is a bare `tools/list`.

## Listing the tools [#listing-the-tools]

```sh
curl -s https://vike.io/mcp \
  -H "X-API-KEY: $VIKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
```

The result is `{"tools": [...]}`, each entry carrying `name`, `description` and `inputSchema`.
There is no paging: `tools/list` takes no cursor and returns the whole catalogue every time, so
the count it returns is the whole surface. Count them to check a connection end to end:

```sh
curl -s https://vike.io/mcp \
  -H "X-API-KEY: $VIKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | jq '.result.tools | length'
```

## Calling a tool [#calling-a-tool]

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "token_search",
    "arguments": { "query": "PEPE", "chain": "ethereum" }
  }
}
```

Every tool answers in the same envelope: one `text` content block holding the tool's JSON
result, serialized as a string.

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{ "type": "text", "text": "[{\"symbol\": \"PEPE\", ...}]" }],
    "isError": false
  }
}
```

So a script does two decodes: parse the JSON-RPC response, then parse
`result.content[0].text` to get the tool's own payload.

A few more calls, with the arguments that matter:

```json
{ "method": "tools/call", "params": {
  "name": "token_screener",
  "arguments": { "chain": "base", "window": "7d", "sort": "smart_inflow", "limit": 20 }}}
```

```json
{ "method": "tools/call", "params": {
  "name": "wallet_summary",
  "arguments": { "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }}}
```

```json
{ "method": "tools/call", "params": {
  "name": "alerts_list",
  "arguments": {}}}
```

That last one is deliberate, and it is the shape that catches scripts: an empty `arguments`
object is a valid call, but it is not "everything" —
[`alerts_list`](/docs/ai/data/alerts) with no arguments returns your *active* rules only, and the
paused and soft-deleted ones need `include_inactive: true`. Read each tool's defaults before
treating an argument-free call as an unfiltered one.

## The error shapes [#the-error-shapes]

**Bad or missing credential** — note the HTTP status:

```
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://vike.io/.well-known/oauth-protected-resource"
```

```json
{
  "jsonrpc": "2.0",
  "id": null,
  "error": { "code": -32000, "message": "Invalid or missing API key" }
}
```

The 401 and its `WWW-Authenticate` header follow the MCP authorization spec: an OAuth-capable
client reads `resource_metadata` and starts discovery from there. The body is still a JSON-RPC
error object, so a client that only parses the body sees the same `-32000` it always did.

**Rate limit** — HTTP 429, so monitoring and generic HTTP clients can see the trip.

```
HTTP/1.1 429 Too Many Requests
Retry-After: 60
```

```json
{
  "jsonrpc": "2.0",
  "id": 6,
  "error": {
    "code": -32000,
    "message": "Hourly rate limit exceeded",
    "data": { "code": "RATE_LIMITED", "retry_after": 60 }
  }
}
```

`Retry-After` is an advisory back-off, not a promise: the window is a rolling hour, so the
honest answer to "when will capacity exist" is per-key and unknowable per request. See
[Rate limits](/docs/data/rate-limits).

**Malformed JSON** is `-32700` with `id: null`; &#x2A;*an unknown method, or an unknown tool name in
`tools/call`**, is `-32601`:

```json
{ "jsonrpc": "2.0", "id": 4, "error": { "code": -32601, "message": "Unknown tool: token_serch" } }
```

**A tool that fails** is not a protocol error. A tool that returns an `error` key is wrapped as an
ordinary successful result and flagged:

```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [{ "type": "text", "text": "{\"error\": \"address is required\"}" }],
    "isError": true
  }
}
```

⚠ So a script that only inspects `error` will read a failed tool call as a success. Check
`result.isError` too.

## In practice, you ask in English [#in-practice-you-ask-in-english]

Once a client is connected you write none of the above. The mapping is what the tool
descriptions are for:

| You ask                                                       | The client calls                            |
| ------------------------------------------------------------- | ------------------------------------------- |
| *"Search for PEPE"*                                           | [`token_search`](/docs/ai/data/tokens)           |
| *"Top wallets by realized PnL this week"*                     | [`wallet_discover`](/docs/ai/data/wallets)       |
| *"Who's been buying LINK in the last 24 hours?"*              | [`token_transfers`](/docs/ai/data/tokens)        |
| *"What has smart money been accumulating on Base this week?"* | [`token_screener`](/docs/ai/data/tokens)         |
| *"Follow the money three hops from this address"*             | [`wallet_trace`](/docs/ai/data/wallets)          |
| *"What's hot on Polymarket?"*                                 | [`polymarket_markets`](/docs/ai/data/polymarket) |
| *"Alert me on big USDC moves"*                                | [`alerts_create`](/docs/ai/data/alerts)          |


# VS Code (/docs/ai/data/setup/vs-code)



## Add the server [#add-the-server]

Create `.vscode/mcp.json` in the workspace and reload the window:

```json
{
  "servers": {
    "vike": {
      "type": "http",
      "url": "https://vike.io/mcp",
      "headers": { "X-API-KEY": "YOUR_KEY" }
    }
  }
}
```

Two differences from the Cursor shape are easy to miss: the top-level key is `servers`, not
`mcpServers`, and each entry carries an explicit `type`. That `type` is what selects the rest of
the entry's shape — `http` takes `url` and `headers`. Vike's data endpoint is a remote HTTP
service; there is no command for VS Code to launch.

<Callout title="The trader server is a stdio entry in this same file">
  `vike-cli mcp` is a local process, so it sits beside this one in the same `servers` object with
  `"type": "stdio"`, `command` and `args`, under a different name. See
  [Trader / VS Code](/docs/ai/trader/setup/vs-code).
</Callout>

## Keep the credential out of the repository [#keep-the-credential-out-of-the-repository]

`.vscode/mcp.json` sits inside the workspace, so a pasted key is one `git add` away from being
committed. Either add the file to `.gitignore`, or use VS Code's input-variable support so the
key is prompted for and stored by the editor rather than written into the file.

If a key does get committed, delete it under **Account → API Keys** and create a new one.
⚠ Deletion is the fix; rotating the file is not, because the old key keeps working until it is
deleted — and for up to 45 seconds after, while the server's auth cache expires.

## Verify [#verify]

Open Copilot Chat in agent mode and ask:

> Search for PEPE token using Vike

`token_search` costs 0 credits. Copilot's tools picker should list the Vike server; if the server
is present but its tools are not offered, they may need enabling for the conversation.

## Troubleshooting [#troubleshooting]

**The file was edited but nothing changed.** Reload the window. MCP configuration is read at
startup.

**The server never appears.** Check the file path (`.vscode/mcp.json`, in the workspace root that
VS Code actually has open) and that the JSON parses — a trailing comma silently disables the
whole file, every entry in it with it.

**Everything is configured and the calls fail.** Test the key with the
[raw HTTP](/docs/ai/data/setup/raw-http) `tools/list` call. ⚠ An authentication failure on `/mcp` comes
back as HTTP 200 with a JSON-RPC error in the body, so a client that only checks the status code
reports success on a rejected call.


# Amazon Q Developer CLI (/docs/ai/trader/setup/amazon-q)



## Add the server [#add-the-server]

Either the CLI:

```sh
q mcp add --name vike-trader --command vike-cli --args '["mcp", "--node", "127.0.0.1:7879"]'
```

or edit the config file directly.

Global, at `~/.aws/amazonq/mcp.json` — available in every workspace:

```json
{
  "mcpServers": {
    "vike-trader": {
      "command": "vike-cli",
      "args": ["mcp", "--node", "127.0.0.1:7879"]
    }
  }
}
```

Per workspace, at `.amazonq/mcp.json` in the project directory — the same shape, scoped to that
project.

<Callout title="Both files are read, and the workspace one wins a name collision">
  Amazon Q takes the **union** of the global and workspace files. A server named in only one of them
  is simply added. A server named in **both** produces a warning and the workspace entry is used —
  so a per-project `.amazonq/mcp.json` that names `vike-trader` silently overrides the global entry's
  `--node`, and the tool you are watching may not be the node you are watching. Keep this server in
  one file, or make the override deliberate.
</Callout>

## Scoping what the tools reach [#scoping-what-the-tools-reach]

Both `vike-cli mcp` flags are optional and both only *widen* what the tools reach.
`--node <host:port>` is the running `vike-tradehub` the live tools observe and control — no
default. `--addr <host:port>` is the `vike-datahub` the backtest tools ship profiles to, defaulting
to `127.0.0.1:7878`. With neither, the four offline authoring tools — `validate_strategy`,
`discover_params`, `list_templates`, `list_indicators` — still work, which makes a flag-less entry
a reasonable first step:

```json
{
  "mcpServers": {
    "vike-trader": { "command": "vike-cli", "args": ["mcp"] }
  }
}
```

The entry also takes an optional `timeout` in milliseconds — how long the client waits for a tool
response, defaulting to 60,000. Every tool here answers in well under that, with one shape worth
knowing: a *confirmed* write waits up to two seconds for the node's acknowledgement
(`ACK_WAIT` in `crates/vike-cli/src/cmd/mcp.rs`) and then answers `outcome: "unknown"` rather than
hanging, so the client timeout is not what protects you from a slow node.

If the binary is reported as not found, give `command` an absolute path.

## The node keys [#the-node-keys]

The entry takes an `env` block, and the two node keys are the only credentials involved — there is
no Vike account and nothing here is metered:

```json
{
  "mcpServers": {
    "vike-trader": {
      "command": "vike-cli",
      "args": ["mcp", "--node", "127.0.0.1:7879"],
      "env": { "VIKE_TRADEHUB_OBSERVE_KEY": "..." }
    }
  }
}
```

Prefer **not** to. Each key resolves from the process environment first and then from
`<project>/settings/secrets.env`, the same store the `vike-tradehub` daemon reads
(`crates/vike-cli/src/cmd/nodekeys.rs`'s `resolve`), so on a configured box the store already
reaches this server and one copy serves both halves. That matters most for
`VIKE_TRADEHUB_CONTROL_KEY`: it places orders, and a per-workspace `.amazonq/mcp.json` sits inside
the repository, one `git add` away from being committed.

`vike-cli secrets path` prints which store a directory resolves to; `vike-cli secrets list` shows
whether a key is in it, by name — never values.

## Verify [#verify]

```sh
q mcp list
q mcp status --name vike-trader
```

Then, in a session:

> list the vike strategy templates

`list_templates&#x60; is offline: no key, no node, no network. If it answers, the subprocess is running
and the protocol is working, and anything still failing is an address or a key rather than the
setup. With a node configured, &#x2A;"show me the node snapshot"* proves the observe key too.

## Troubleshooting [#troubleshooting]

**The server is not listed.** Check which file you edited against `q mcp list`, and remember the
union rule above — a name in both files resolves to the workspace copy.

**It is listed but tools are never called.** Name the tool — "use the `list_templates` tool" — to
confirm the wiring before trusting the model to reach for it on its own.

**The offline tools work and the node tools do not.** That is an address or a key, not the MCP
wiring. The two failures are worded differently on purpose: "no vike-tradehub node configured"
means `--node` never arrived; "set neither in the process environment nor in the credential store"
names a key, and names both places it looked.

**A write tool answered but no order exists.** Not a client problem. A write executes only when a
call carries **both** `confirm: true` **and** the `preview_token` its own preview returned;
anything less returns a fresh preview, `will_execute: false`, and no error at all. [Live
node](/docs/ai/trader/trading#what-the-token-is-and-what-it-is-not) is the contract.

## Where this shape came from [#where-this-shape-came-from]

The two config paths, the union-and-workspace-wins merge rule, the `mcpServers` object with
`command`/`args`/`env`/`timeout`, and the `q mcp add --name … --command … --args` form were read
from AWS's own Amazon Q Developer MCP documentation in September 2026, not from memory. That
documentation is the authority if it has moved since; this page is the copy. Note that the CLI
subcommands are documented under both `q mcp` and `qchat mcp` — the same command set.

## The data server too [#the-data-server-too]

Amazon Q holds both Vike servers in the same `mcpServers` object — the hosted
[data server](/docs/ai/data) is a remote entry carrying `type` and `url` instead of `command`, beside
this one. [Data client setup](/docs/ai/data/setup) has its shape. The names must differ, or the second
replaces the first.


# Claude Code (/docs/ai/trader/setup/claude-code)



## Add the server [#add-the-server]

```sh
claude mcp add vike-trader -- vike-cli mcp --node 127.0.0.1:7879
```

The `--` is what makes this work: everything after it is the command line Claude Code launches, so
`--node` is parsed by `vike-cli` rather than claimed by `claude mcp add`. There is no `--transport`
flag here — the trader server is a local subprocess, which is the default shape.

Two optional flags scope what the tools reach — `--node <host:port>`, the running `vike-tradehub`
the live tools observe and control (no default), and `--addr <host:port>`, the `vike-datahub` the
backtest tools use (default `127.0.0.1:7878`). With neither, the four offline authoring tools still
work:

```sh
claude mcp add vike-trader -- vike-cli mcp
```

## The node keys [#the-node-keys]

Unlike a GUI client, Claude Code is started from your terminal and inherits its environment, so an
exported `VIKE_TRADEHUB_OBSERVE_KEY` / `VIKE_TRADEHUB_CONTROL_KEY` does reach the server. Absent
from the environment, each key falls back to `<project>/settings/secrets.env` — the same store the
daemon reads — resolved by walking up from the working directory, which for a subprocess of Claude
Code is where you started it.

That last clause is the one to hold on to: unless `VIKE_SETTINGS_DIR` names a directory outright,
**which store answers depends on where you launched Claude Code**. `vike-cli secrets path` prints
the store a given directory resolves to, and `vike-cli secrets list` shows whether the key is in
it, by name.

## Scopes [#scopes]

Claude Code stores MCP servers per scope — local, project, or user — and `claude mcp add` takes a
`--scope` flag to choose. Check `claude mcp list` after adding, to confirm the session you are in
can see it.

If you scope the server to a project, its configuration lands in a file that may be committed. That
is fine here, because the entry carries no secret: keep the node keys in the credential store (or
your shell) rather than in `args`, and there is nothing in the entry worth hiding.

**Restart any Claude Code session that was already open.** Sessions read the server list at start.

## Verify [#verify]

```sh
claude mcp list
```

`vike-trader` should appear with its command. Then, in a session:

> list the vike strategy templates

calls `list_templates&#x60;, which needs no key, no node and no network — so it isolates "is the binary
being launched and speaking the protocol" from every credential and address question. With a node
configured, &#x2A;"show me the node snapshot"* then proves the observe key.

## Removing or replacing it [#removing-or-replacing-it]

```sh
claude mcp remove vike-trader
```

To rotate a node key, change it in the credential store (or your shell) and restart the session —
the entry itself carries no secret, so it does not need rewriting.

## Troubleshooting [#troubleshooting]

**Nothing happens when you ask.** Check `claude mcp list` first. If the server is absent, the add
command wrote to a scope the session is not reading; re-add naming the scope explicitly.

**The server fails to start.** Run the command by hand — `vike-cli mcp --node 127.0.0.1:7879` — in
the same directory. It reads JSON-RPC on stdin and answers on stdout, so a binary that is not on
`PATH`, or a flag it rejects (`unknown argument`, exit 1), surfaces immediately rather than as a
silently absent server.

**The trade tools return "set neither in the process environment nor in the credential store".**
That is a node key. The message names both places on purpose, so check the one you expected to
answer: `vike-cli secrets path` for the store, `echo $VIKE_TRADEHUB_CONTROL_KEY` for the shell.
The wording is `Server::missing_key` in `crates/vike-cli/src/cmd/mcp.rs`.

**The node tools return "no vike-tradehub node configured".** That is the `--node` flag, not a key.
The check happens before any socket is opened, so it means the flag never reached `vike-cli` —
most often a missing `--` in the add command. The read and write connections check separately, in
`Server::ensure_observe` and `Server::ensure_control` (`crates/vike-cli/src/cmd/mcp.rs`), so the
tail of the message tells you which one you hit.

## The data server too [#the-data-server-too]

Claude Code can hold both Vike servers. The hosted [data server](/docs/ai/data) is a URL and needs
`--transport http` plus an API-key header — [Data client setup → Claude Code](/docs/ai/data/setup/claude-code)
has that command. Give the two entries different names; Claude Code keys servers by name, so adding
both as `vike` leaves you with one.


# Claude Desktop (/docs/ai/trader/setup/claude-desktop)



`vike-cli mcp` is not a URL and cannot be added as a connector: it is a local process Claude Desktop
launches and speaks stdio to. Declare it in the config file instead.

## The config file [#the-config-file]

**Settings → Developer → Edit Config** opens it, at
`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS and
`%APPDATA%\Claude\claude_desktop_config.json` on Windows.

```json
{
  "mcpServers": {
    "vike-trader": {
      "command": "vike-cli",
      "args": ["mcp", "--node", "127.0.0.1:7879"]
    }
  }
}
```

Then quit Claude Desktop completely and start it again — the config is read at launch, not on save.

Both flags are optional and both only widen what the tools can reach: `--node <host:port>` is the
running `vike-tradehub` the live tools observe and control (no default), and `--addr <host:port>` is
the `vike-datahub` the backtest tools ship profiles to (default `127.0.0.1:7878`). With neither, the
four offline tools — `validate_strategy`, `discover_params`, `list_templates`, `list_indicators` —
still work, so a flag-less entry is a fine first step.

<Callout type="warn" title="Give the binary an absolute path if it is not found">
  Claude Desktop launches the server from the application, which does not inherit the `PATH` your
  shell exports. If the entry fails to start, replace `"vike-cli"` with the binary's full path —
  `/usr/local/bin/vike-cli`, or `C:\\Users\\you\\vike\\bin\\vike-cli.exe`. Note the doubled
  backslashes: this is JSON.
</Callout>

## The node keys [#the-node-keys]

That same launch context is why the keys usually belong in the credential store rather than your
shell profile. `vike-cli` reads `VIKE_TRADEHUB_OBSERVE_KEY` and `VIKE_TRADEHUB_CONTROL_KEY` from the
process environment first and then from `<project>/settings/secrets.env` — the same file the daemon
itself reads — and a GUI-launched child sees none of your terminal's exports. The resolver is
`crates/vike-cli/src/cmd/nodekeys.rs`'s `resolve`.

If you would rather pin them to this one client, the entry takes an `env` block:

```json
{
  "mcpServers": {
    "vike-trader": {
      "command": "vike-cli",
      "args": ["mcp", "--node", "127.0.0.1:7879"],
      "env": { "VIKE_TRADEHUB_OBSERVE_KEY": "..." }
    }
  }
}
```

The process environment wins over the store, **per key**, so an `env` entry here overrides a stored
value of the same name and leaves the other key resolving from the store. Consider what each key
buys before writing it into a file: the observe key reads, the control key **places orders**.

## Verify [#verify]

> list the vike strategy templates

calls `list_templates&#x60;, which needs no key, no node and no network — so it answers exactly one
question: is Claude Desktop launching the binary and speaking the protocol to it. With a node
configured, follow it with &#x2A;"show me the node snapshot"* to prove the observe key as well.

If `vike-trader` never appears under the hammer icon, the config file did not parse or the binary
did not start. Claude Desktop writes each server's stderr to its own log —
`mcp-server-vike-trader.log` under `~/Library/Logs/Claude` (macOS) or `%APPDATA%\Claude\logs`
(Windows) — and `vike-cli` is careful to keep every diagnostic on stderr, because its stdout is a
protocol.

## The data server too [#the-data-server-too]

Claude Desktop can hold both Vike servers at once. The hosted [data server](/docs/ai/data) is a URL, so
it is added in the UI as a connector rather than in this file —
[Data client setup → Claude Desktop](/docs/ai/data/setup/claude-desktop) walks it. If you do add a second
entry to `mcpServers`, give it a different name: a client keys its servers by name and the second
`vike` would replace the first.


# Codex CLI (/docs/ai/trader/setup/codex-cli)



## Add the server [#add-the-server]

```sh
codex mcp add vike-trader -- vike-cli mcp --node 127.0.0.1:7879
```

The form is `codex mcp add <name> [--env KEY=VALUE] -- <command and its arguments>`. Everything
after the `--` is the stdio command Codex will launch, so `--node` lands on `vike-cli` rather than
being claimed by `codex mcp add`.

<Callout type="warn" title="This client's config is TOML, not JSON">
  Codex is the odd one out on this page set. Every other client here keys a `mcpServers` **JSON**
  object; Codex reads `~/.codex/config.toml`, so the `command` + `args` block you would paste into
  Cursor or Claude Desktop is not valid input here. Translate it rather than copying it.
</Callout>

## Or edit the file [#or-edit-the-file]

`~/.codex/config.toml` is the default; a trusted project can carry its own `.codex/config.toml`.
The server is a table named after it:

```toml
[mcp_servers.vike-trader]
command = "vike-cli"
args = ["mcp", "--node", "127.0.0.1:7879"]
```

Both `vike-cli mcp` flags are optional, and both only *widen* what the tools reach. The shortest
working entry is the command alone:

```toml
[mcp_servers.vike-trader]
command = "vike-cli"
args = ["mcp"]
```

which still gives you the four offline authoring tools — `validate_strategy`, `discover_params`,
`list_templates`, `list_indicators`. `--addr <host:port>` is the `vike-datahub` the backtest tools
ship profiles to (default `127.0.0.1:7878`); `--node <host:port>` is the running `vike-tradehub`
the live tools observe and control, and it has no default.

If Codex reports the binary as not found, give `command` an absolute path — the same advice as
every other client here, for the same reason: nothing guarantees your shell's `PATH`.

## The node keys [#the-node-keys]

Codex CLI runs in your terminal, so an exported `VIKE_TRADEHUB_OBSERVE_KEY` /
`VIKE_TRADEHUB_CONTROL_KEY` reaches the server. Each key independently falls back to
`<project>/settings/secrets.env` — the same store the `vike-tradehub` daemon reads — when the
environment does not carry it, so on a configured box you usually need to export nothing at all.
The resolver that applies that order is `crates/vike-cli/src/cmd/nodekeys.rs`'s `resolve`.

To pin one key for this server alone rather than exporting it, the config table takes an `env`
sub-table (and `codex mcp add` takes `--env KEY=VALUE`):

```toml
[mcp_servers.vike-trader]
command = "vike-cli"
args = ["mcp", "--node", "127.0.0.1:7879"]

[mcp_servers.vike-trader.env]
VIKE_TRADEHUB_OBSERVE_KEY = "..."
```

The environment wins over the store *per key*, so setting one there leaves the other resolving from
the store. **A control key is the expensive one to write into a file** — it places orders — so
prefer the credential store, especially for a project-scoped `.codex/config.toml` that sits inside
a repository.

`vike-cli secrets path` prints which store a directory resolves to; `vike-cli secrets list` shows
whether a key is in it, by name — never values.

## Verify [#verify]

```sh
codex mcp list
```

Then, in a session:

> list the vike strategy templates

`list_templates&#x60; is the free check — offline, no key, no node, no network. If it answers, the
subprocess is running and the protocol is working, and anything still failing is an address or a
key rather than the setup. With a node configured, follow it with &#x2A;"show me the node snapshot"* to
prove the observe key too.

## Troubleshooting [#troubleshooting]

**The `--node` flag is rejected.** It is on the wrong side of the `--`. Everything before the
double dash belongs to `codex mcp add`; everything after it belongs to `vike-cli`.

**A JSON block was pasted into `config.toml`.** See the callout above — this is the failure mode
this client has and the others do not, because every MCP setup snippet on the internet is JSON.

**The offline tools work and the node tools do not.** That is an address or a key, not the MCP
wiring, and the two failures are worded differently on purpose: "no vike-tradehub node configured"
means `--node` never arrived, while "set neither in the process environment nor in the credential
store" names a key and names both places it looked.

**A write tool answered but nothing happened.** That is not a Codex problem. A write executes only
when a call carries **both** `confirm: true` **and** the `preview_token` its own preview returned;
anything less comes back as another preview, with `will_execute: false` and no error. [Live
node](/docs/ai/trader/trading#what-the-token-is-and-what-it-is-not) is the contract.

## Where this shape came from [#where-this-shape-came-from]

The config path, the `[mcp_servers.<name>]` table with `command`/`args`/`env`, and the
`codex mcp add <name> --env … -- <command>` form were read from OpenAI's own Codex MCP
documentation (`developers.openai.com/codex/mcp`, which now redirects into the ChatGPT docs) in
September 2026, not from memory. If Codex has changed since, that page is the authority and this
one is the copy.

## The data server too [#the-data-server-too]

Codex holds both Vike servers in the same `config.toml` — the hosted [data server](/docs/ai/data) as a
`url`-carrying table beside this one. [Data client setup](/docs/ai/data/setup) has its shape. Give the
two tables different names.


# Cursor (/docs/ai/trader/setup/cursor)



## Add the server [#add-the-server]

Either **Settings → MCP → Add new server**, or edit the config file directly.

Global, at `~/.cursor/mcp.json` — available in every project:

```json
{
  "mcpServers": {
    "vike-trader": {
      "command": "vike-cli",
      "args": ["mcp", "--node", "127.0.0.1:7879"]
    }
  }
}
```

Per project, at `.cursor/mcp.json` in the repository root — same shape, scoped to that project.

`command` + `args` is the **local** shape, and it is the only one that works here: `vike-cli mcp` is
a subprocess Cursor starts and speaks stdio to, and it has no URL at all. (A `url` + `headers` entry
is the remote shape, which is what the [data server](/docs/ai/data) uses.)

## Scoping what the tools reach [#scoping-what-the-tools-reach]

Both `vike-cli mcp` flags are optional. `--node <host:port>` is the running `vike-tradehub` the live
tools observe and control — no default, so without it `node_snapshot` returns a clean error naming
the flag before any socket is opened. A write tool is quieter: it previews unless a call carries
**both** `confirm: true` **and** the `preview_token` its preview returned, and with no node
configured that preview contacts nothing — so a preview is no evidence the flag arrived; a node
snapshot is. `--addr <host:port>` is the `vike-datahub` the backtest tools ship profiles to,
defaulting to `127.0.0.1:7878`.

With neither, the offline tools — `validate_strategy`, `discover_params`, `list_templates`,
`list_indicators` — still work, which makes a flag-less entry a reasonable first step:

```json
{
  "mcpServers": {
    "vike-trader": { "command": "vike-cli", "args": ["mcp"] }
  }
}
```

If Cursor reports the binary as not found, give `command` an absolute path: an editor launched from
the desktop does not inherit the `PATH` your shell exports.

## The node keys [#the-node-keys]

For the same reason, keep `VIKE_TRADEHUB_OBSERVE_KEY` and `VIKE_TRADEHUB_CONTROL_KEY` in the
credential store — `<project>/settings/secrets.env`, the same file the `vike-tradehub` daemon reads.
`vike-cli` looks in the process environment first and the store second, and a desktop-launched
child process sees none of your terminal's exports, so the store is the source that actually
reaches it. That lookup order is `crates/vike-cli/src/cmd/nodekeys.rs`'s `resolve`.

That is also the safer default for a per-project `.cursor/mcp.json`, which sits inside the
repository: nothing secret ends up in a file that is one `git add` away from being committed. A
committed control key is the expensive kind — it places orders.

`vike-cli secrets path` prints which store a directory resolves to; `vike-cli secrets list` shows
whether the key is in it, by name.

## After editing [#after-editing]

Reload Cursor, or toggle the server off and on in the MCP pane. The settings pane shows each
server's status and the tools it exposes — a healthy `vike-trader` lists **17**.

## Verify [#verify]

> list the vike strategy templates

`list_templates&#x60; is offline: no key, no node, no network. If it answers, the subprocess is running
and the protocol is working, and anything still failing is an address or a key. With a node
configured, &#x2A;"show me the node snapshot"* proves the observe key too.

## Troubleshooting [#troubleshooting]

**The server shows as failed.** Almost always the JSON: a trailing comma, or a key nested in the
wrong object. `command` and `args` are siblings *inside* the server's own object.

**It is green but tools are never called.** Cursor decides per request whether to use a tool. Name
it — "use the `list_templates` tool" — to confirm the wiring before trusting the model to reach for
it on its own.

**A project config and a global config both exist.** Keep the server in one of them. Two entries of
the same name pointing at different `--node` addresses means the tool you are watching may not be
the node you are watching.

**The offline tools work and the node tools do not.** That is an address or a key, not the MCP
wiring — the two failures are worded differently on purpose. "no vike-tradehub node configured"
means `--node` never arrived; "set neither in the process environment nor in the credential store"
names a key, and names both places it looked.

## The data server too [#the-data-server-too]

Cursor holds both Vike servers in the same `mcpServers` object — the hosted [data server](/docs/ai/data)
as a `url` + `headers` entry beside this one. [Data client setup → Cursor](/docs/ai/data/setup/cursor)
has its shape. The names must differ: a second `vike` replaces the first.


# Gemini CLI (/docs/ai/trader/setup/gemini-cli)



## Add the server [#add-the-server]

```sh
gemini mcp add vike-trader vike-cli mcp -- --node 127.0.0.1:7879
```

No `--transport` flag, because stdio is the default and that is what this server speaks. The form is
`gemini mcp add [options] <name> <command> [args...]`: `vike-trader` is the name, `vike-cli` the
command, and `mcp` its first argument. The `--` before `--node` hands the remaining flags to
`vike-cli` instead of letting `gemini mcp add` claim them.

Both `vike-cli mcp` flags are optional — `--node <host:port>` is the running `vike-tradehub` the
live tools observe and control (no default), `--addr <host:port>` the `vike-datahub` the backtest
tools use (default `127.0.0.1:7878`). The shortest working entry is:

```sh
gemini mcp add vike-trader vike-cli mcp
```

which still gives you the four offline authoring tools; `node_snapshot` then returns a clean error
naming the missing flag rather than failing obscurely. A write tool stays quiet about it — it
previews unless a call carries **both** `confirm: true` **and** the `preview_token` its preview
returned, so the missing-node error only ever appears on a fully confirmed call.

## The node keys [#the-node-keys]

Gemini CLI runs in your terminal, so an exported `VIKE_TRADEHUB_OBSERVE_KEY` /
`VIKE_TRADEHUB_CONTROL_KEY` reaches the server. Each key falls back to
`<project>/settings/secrets.env` — the same store the daemon reads — when the environment does not
carry it, so on a configured box you usually need to export nothing at all. The resolver that
applies that order is `crates/vike-cli/src/cmd/nodekeys.rs`'s `resolve`.

`gemini mcp add` also takes `-e KEY=value` to set a variable for one server alone. The environment
wins over the store per key, so that pins one key without disturbing the other.

## Verify [#verify]

```sh
gemini mcp list
```

Then, in a session:

> list the vike strategy templates

`list_templates&#x60; is the free check — offline, no key, no node, no network. If it answers, the
subprocess is running and the protocol is working. With a node configured, follow it with &#x2A;"show me
the node snapshot"* to prove the observe key.

## Troubleshooting [#troubleshooting]

**The command is rejected as malformed.** Check the argument order: options, then the server name,
then the command and its arguments. If a flag meant for `vike-cli` is being rejected by
`gemini mcp add`, it is on the wrong side of the `--`.

**The server is added but never starts.** Run `vike-cli mcp` by hand in the same directory: it reads
newline-delimited JSON-RPC on stdin, so a missing binary or a rejected flag shows up at once —
`vike-cli mcp: unknown argument: <flag>` on stderr, exit 1 — instead of as a silently absent server.
[Raw JSON-RPC](/docs/ai/trader/setup/raw-http) has a one-line handshake you can paste.

**The offline tools answer and the node tools do not.** Two different errors, worded to be told
apart: "no vike-tradehub node configured" means the `--node` flag never reached `vike-cli`, while
"set neither in the process environment nor in the credential store" names a key and both places it
looked. `vike-cli secrets path` prints the store; `vike-cli secrets list` shows key names, never
values.

## The data server too [#the-data-server-too]

Gemini CLI adds both Vike servers with the same subcommand — `--transport http` is the whole
difference, and it is what the hosted [data server](/docs/ai/data) needs.
[Data client setup → Gemini CLI](/docs/ai/data/setup/gemini-cli) has that command. The two names must
differ: a second `vike` replaces the first.


# Client setup (/docs/ai/trader/setup)



The trader server is **a command your client launches**, not a URL it points at. Every client on
this page ends up doing the same thing — start `vike-cli mcp` as a child process and speak
newline-delimited JSON-RPC 2.0 to its stdin and stdout. What differs is where the configuration
lives and how that client spells a local command.

## Pick your client [#pick-your-client]

| Your client               | How the command is spelled                                     | Page                                              |
| ------------------------- | -------------------------------------------------------------- | ------------------------------------------------- |
| Claude Desktop            | `claude_desktop_config.json`, `command` + `args`               | [Claude Desktop](/docs/ai/trader/setup/claude-desktop) |
| Claude Code               | `claude mcp add vike-trader -- vike-cli mcp`                   | [Claude Code](/docs/ai/trader/setup/claude-code)       |
| Cursor                    | `mcp.json`, `command` + `args`                                 | [Cursor](/docs/ai/trader/setup/cursor)                 |
| Gemini CLI                | `gemini mcp add`, the default (stdio) transport                | [Gemini CLI](/docs/ai/trader/setup/gemini-cli)         |
| GitHub Copilot in VS Code | `.vscode/mcp.json`, `"type": "stdio"`                          | [VS Code](/docs/ai/trader/setup/vs-code)               |
| Codex CLI                 | `config.toml`, an `[mcp_servers.*]` table — **TOML, not JSON** | [Codex CLI](/docs/ai/trader/setup/codex-cli)           |
| Amazon Q Developer CLI    | `~/.aws/amazonq/mcp.json`, `command` + `args`                  | [Amazon Q](/docs/ai/trader/setup/amazon-q)             |
| Windsurf                  | `~/.codeium/windsurf/mcp_config.json`, `command` + `args`      | [Windsurf](/docs/ai/trader/setup/windsurf)             |
| A script                  | no client at all — pipe JSON-RPC into its stdin                | [Raw JSON-RPC](/docs/ai/trader/setup/raw-http)         |

These pages name the server `vike-trader`. Any name works; a client keys its servers by name, so
the only rule is that no two entries share one.

<Callout title="The data server goes in the same file">
  Vike's other MCP server — the hosted [data endpoint](/docs/ai/data) — is a URL rather than a command,
  and every client here can hold both at once, side by side in the same config file or the same CLI.
  Its entries are on [Data client setup](/docs/ai/data/setup). That is where the name rule bites: give the
  two entries different names, or the second replaces the first.
</Callout>

## The command, and its flags [#the-command-and-its-flags]

```sh
vike-cli mcp [--addr 127.0.0.1:7878] [--node <host:port>] \
             [--profile full|read-only|offline] [--deny-tool NAME]... \
             [--trace | --trace-dir <dir>]
```

That usage string is `USAGE` in `crates/vike-cli/src/cmd/mcp.rs`. Its `parse_config` accepts those
flags plus `-h`/`--help`, which prints the usage to stdout and exits 0; anything else exits 1
with `unknown argument`. The `--addr` default is that same file's `DEFAULT_ADDR`.

| Flag     | Default          | What it reaches                                                                                 |
| -------- | ---------------- | ----------------------------------------------------------------------------------------------- |
| `--addr` | `127.0.0.1:7878` | the `vike-datahub` server the backtest, sweep, walk-forward and inventory tools run against     |
| `--node` | *none*           | the running `vike-tradehub` node `node_snapshot` reads and the seven order-write tools write to |

Both are optional and both only *widen* what the tools reach. With neither, the four offline
authoring tools — `validate_strategy`, `discover_params`, `list_templates`, `list_indicators` —
still work, which makes a flag-less entry a reasonable first step. `--node` has no default on
purpose: without it, `node_snapshot` returns a clean error naming the flag before any socket is
opened — `Server::ensure_observe` and `Server::ensure_control` in
`crates/vike-cli/src/cmd/mcp.rs` check for the address before they connect. A write tool says
nothing about it until much later: a call that does not carry **both** `confirm: true` **and** a
valid `preview_token` returns a preview whatever the flag says, so the missing-node error appears
only on a fully confirmed call. A preview is never evidence the flag arrived; a node snapshot is.

The other two *narrow* it, and they are the half a client entry is the natural place for:

| Flag                      | Default | What it decides                                                                                                                           |
| ------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `--profile`               | `full`  | which tools this server serves at all — `full` (17), `read-only` (10, no order-write tools) or `offline` (4, nothing that opens a socket) |
| `--deny-tool`             | *none*  | one more tool withheld by name; repeatable                                                                                                |
| `--trace` / `--trace-dir` | off     | append one JSONL record per tool call under `<project>/settings/state/agent`, or in a directory you name                                  |

Under `read-only` the seven order-write tools are &#x2A;*absent from `tools/list`**, not merely refused —
`ToolAccess::new` produces the advertised set and its withheld complement in one pass, so the roster
and the router cannot disagree. That makes a scoped entry the right shape for a client you want
reading a live node and never trading it:

```json
{
  "mcpServers": {
    "vike-trader": {
      "command": "vike-cli",
      "args": ["mcp", "--node", "127.0.0.1:7879", "--profile", "read-only"]
    }
  }
}
```

An unknown profile name or deny name is a usage error naming the valid set; neither ever falls back
to something wider, which matters most in a config file nobody re-reads. And because a scope lives
in the launch command, only whoever edits that file can widen it — the agent cannot, and the
refusal it gets says so rather than sending it hunting for a switch.

A node listens on nothing until `tradehub_addr` in `config.toml` (or `VIKE_TRADEHUB_ADDR`) names an
address — `start_observe_server` in `crates/vike-tradehub/src/tradehub_cli.rs` returns without
binding when it is unset. `127.0.0.1:7879` is the conventional one
(`crates/vike-tradehub/src/server.rs`'s `DEFAULT_ADDR`), and loopback is deliberate — reach a remote
one through an ssh tunnel rather than by binding it publicly; [Remote node](/docs/ai/trader/setup/remote-node)
is that recipe.

<Callout type="warn" title="The node protocol is not encrypted, and the HMAC covers the connection rather than each frame">
  `vike-cli mcp` authenticates to your node with an HMAC-SHA256 nonce challenge, and the scope byte
  is signed into the tag — so a key issued for reads cannot mint a write. That is the whole of what
  it buys. The handshake itself is **plaintext**, and it authenticates the **connection**, not the
  individual frames that follow it. Anyone who can read the traffic can read your orders, your
  positions and your symbols; anyone who can modify it in flight is not stopped by the handshake
  either. The primitive says so about itself, in a section headed *What this does NOT buy* —
  `crates/vike-datahub-client/src/node_auth.rs`, where `sign` and `verify` live, with
  `crates/vike-tradehub-client/src/auth.rs`'s `DOMAIN` binding it to this service.

  On loopback the party who can read that traffic is nobody but the machine's own users, which is
  why the daemon binds `127.0.0.1` and why these pages steer you away from binding it publicly. For a
  node on another host, an ssh tunnel (or a VPN) is not a convenience — it is the layer supplying the
  confidentiality and the in-flight integrity the protocol deliberately does not.
  [Remote node](/docs/ai/trader/setup/remote-node) is the tunnel recipe, including what the daemon does
  when someone binds `0.0.0.0` anyway and what a dropped tunnel looks like from the tools.
</Callout>

## The credentials [#the-credentials]

No Vike account is involved, and nothing here is metered. `vike-cli mcp` talks to services **you**
run, and the two node keys are HMAC secrets shared with your own `vike-tradehub` daemon:

* `VIKE_TRADEHUB_OBSERVE_KEY` — reads (`node_snapshot`),
* `VIKE_TRADEHUB_CONTROL_KEY` — writes (the seven order-write tools).

Each is resolved independently, and in this order: **the process environment first, then the
credential store the daemon itself reads** (`<project>/settings/secrets.env`). The environment wins
because it is the narrower, more deliberate source — that is what makes "point at a different node
for one command" possible at all; `crates/vike-cli/src/cmd/nodekeys.rs` argues the precedence at
length. Values are trimmed on both sides, because the daemon trims too (`from_vars` in
`crates/vike-tradehub-client/src/auth.rs`) and a key with a trailing newline would otherwise fail
the handshake as an opaque `AuthDenied`.

A key present in neither place disables only the tools that need it. The server still starts, the
offline and backtest tools still work, and the affected tool returns an error naming **both**
locations (`Server::missing_key` in `crates/vike-cli/src/cmd/mcp.rs`). The two scopes are separate
at the node as well as here: a control key cannot authenticate a read.

<Callout title="A GUI-launched client inherits none of your shell's exports">
  Claude Desktop, Cursor and VS Code start the server as a child of the *application*, not of your
  terminal, so an `export VIKE_TRADEHUB_CONTROL_KEY=...` in your shell profile is invisible to it.
  Put the keys in the credential store, or set them in the client's own config where it supports an
  `env` block. The store is also where the daemon reads them, so one copy serves both halves.
</Callout>

`vike-cli secrets path` prints which store this project resolves to; `vike-cli secrets list` shows
whether a key is in it, by name — never values.

## Where the binary comes from [#where-the-binary-comes-from]

Every client entry starts with a path to `vike-cli`, so it has to exist and be findable:

* **A release download.** `vike-cli` is published as its own asset, alongside `vike-tradehub`,
  `backtest`, `vike-datahub`, `vike-recorder`, `vike-study`, `tearsheet` and `vike`, and covered by
  the release's `SHA256SUMS`, which is the upload manifest — an asset not named there is not published.
* **The consolidated `vike` executable.** One multicall binary answers to every tool name — by
  `argv[0]` when it is installed under that name, and otherwise as a verb, so `vike vike-cli mcp`
  is the same server. `crates/vike/src/main.rs`'s `TOOLS` is the list of names it answers to, and
  `crates/vike/src/lib.rs`'s `resolve` is the two shapes.
* **A checkout.** `cargo run -p vike-cli -- mcp` works, but a client entry wants a real path.

<Callout type="warn" title="If your install is the container, the client cannot just run vike-cli">
  The image's `ENTRYPOINT` is the daemon's entrypoint script (`deploy/docker/Dockerfile`), so
  reaching the CLI means overriding it and keeping stdin open (`-i`):

  ```sh
  docker run -i --rm -v /srv/vike-trader:/project \
    --entrypoint /opt/vike/bin/vike-cli \
    vikeio/vike-tradehub:<version> mcp
  ```

  `/opt/vike/bin/vike-cli` is a relative symlink to the multicall binary — the links are the image's
  interface, not a convenience. And note that `127.0.0.1` *inside* a container is the container's own
  loopback, so a `--node` pointing at a daemon elsewhere needs an address that container can actually
  reach. [Install with Docker](/docs/trader/getting-started/install-docker) covers the mount.
</Callout>

## Verify the connection [#verify-the-connection]

One prompt, and it proves the whole path — the client launching the binary, the protocol, and tool
dispatch — rather than just the config file being read:

> list the vike strategy templates

That calls `list_templates&#x60;, which is offline: no datahub, no node, no key, no network. If it
answers, the wiring is correct and anything still failing is an address or a key rather than the
setup. With a node configured, follow it with &#x2A;"show me the node snapshot"* to prove the observe
key too.

If nothing happens, three checks in order:

1. **Is the server listed at all?** Every client has a way to show its configured MCP servers. If
   `vike-trader` is missing, the config file was not read — usually a restart, or the wrong file.
2. **Does the command run by hand?** `vike-cli mcp` in a terminal reads JSON-RPC on stdin, so a
   binary that is not on `PATH`, or a flag it rejects, surfaces immediately instead of as a
   silently absent server. [Raw JSON-RPC](/docs/ai/trader/setup/raw-http) has the one-line handshake.
3. **Did the tools load but not get used?** Some clients require you to enable a server's tools per
   conversation. Name the tool — "use the `list_templates` tool" — to force the issue.

## Removing it [#removing-it]

There is nothing to revoke centrally, because there is no account: delete the entry from the
client's config, or rotate the node keys in `<project>/settings/secrets.env` and restart the
daemon. A client holding the old key then fails the handshake.

Once it is connected, [Trader MCP server](/docs/ai/trader) is the tool-by-tool reference — and the
seven order-write tools have their own contract on [Live node](/docs/ai/trader/trading).


# Raw JSON-RPC (/docs/ai/trader/setup/raw-http)



⚠ &#x2A;*The trader server is not HTTP.** It has no URL, no port and no headers: `vike-cli mcp` is MCP's
**stdio** transport — newline-delimited JSON-RPC 2.0 on stdin and stdout, one message per line with
no embedded newlines. Anything a client would send, a shell can send. (The hosted
[data server](/docs/ai/data) *is* HTTP; its curl walkthrough is on
[Data client setup → Raw HTTP](/docs/ai/data/setup/raw-http).)

An MCP client handles all of this for you. You need it anyway when you are scripting against the
server, or when a client will not connect and you want to know whether the fault is yours or its.

## The handshake [#the-handshake]

```sh
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | vike-cli mcp
```

The server echoes the `protocolVersion` you asked for — falling back to `2024-11-05` when a client
declares none (`DEFAULT_PROTOCOL` in `crates/vike-cli/src/cmd/mcp.rs`) — and names itself:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": { "tools": {}, "resources": {}, "prompts": {} },
    "serverInfo": { "name": "vike-cli", "version": "..." },
    "instructions": "This is `vike-cli`'s agent surface: ... \n\n ... Never invent a tool name, and never report an operator-side command as something you ran."
  }
}
```

`serverInfo.version` is the version of the `vike-cli` binary you launched, so it tells you which
build you are talking to. `capabilities` advertises `tools`, `resources` and `prompts`; there is no
sampling to negotiate.

`instructions` is free text a client shows the model as guidance about the server — elided above
because it is a paragraph, not a field you parse. It exists because a tool description can only
describe *its* tool: "there is no tool for this, and the command that does it is `vike-recorder`"
is a fact about the **absence** of a tool, so there is nowhere in a roster to write it. So the text
says this server is one surface of a larger system and names the operator-side commands for the
rest — recording a tape, getting bars into the history store, a local backtest, and which
credential keys this box holds — plus two rules: invent no tool name, and never report a command a
human would have to type as something you ran. It is assembled by `instructions` in
`crates/vike-cli/src/cmd/mcp.rs` from named constants, so the string is the same on every run of a
given build and profile.

⚠ &#x2A;*It is scoped by the same `ToolAccess` the roster is, and it grants nothing.** A `read-only`
session's text drops the preview-gate sentence and an `offline` one drops `list_series` too,
because prose naming a tool `tools/list` withholds is advertising a withheld tool
(`the_instructions_are_scoped_by_the_same_access_the_roster_is`). What the agent may *call* is
unchanged either way — this field is advice, and every gate on this page still applies to the call
that follows it. The operator-side commands are in every profile's text and must be: they are
things a human types, and no scope of this server changes what the operator's terminal can run.

**`initialize` is not a gate.** Each method is dispatched on its own, so the one-line version of
"is this thing working" is a bare `tools/list`:

```sh
printf '%s\n' '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | vike-cli mcp | jq '.result.tools | length'
```

17, under the default `--profile full`. `tools/list` takes no cursor and returns the registry
(`tools_spec()`) filtered by whatever scope the server was launched with, every time — so a count
of 10 or 4 means the operator passed `--profile read-only` or `--profile offline`, and a count one
short of either means a `--deny-tool`.

## The nine methods [#the-nine-methods]

| Method                      | Answer                                                                     |
| --------------------------- | -------------------------------------------------------------------------- |
| `initialize`                | the block above                                                            |
| `notifications/initialized` | nothing at all — it carries no `id`                                        |
| `ping`                      | `{}`                                                                       |
| `tools/list`                | `{"tools": [...]}` — every tool this server's scope admits                 |
| `tools/call`                | a tool result — see below                                                  |
| `resources/list`            | `{"resources": [...]}` — `vike://node/snapshot` and `vike://backtest/last` |
| `resources/read`            | `{"contents": [{uri, mimeType, text}]}`, an array even for one document    |
| `prompts/list`              | `{"prompts": [...]}` — three flows, each with its arguments                |
| `prompts/get`               | the rendered sheet as one `user` message                                   |

Anything else is a `-32601` `method not found: <name>`.

A **resource** is a read the agent does not have to choose a tool for, addressable by URI so a
client can pin it into a conversation: each one routes into the matching tool's own implementation,
so it can never answer differently from the tool beside it, and a URI whose tool the scope withholds
is refused rather than served. `resources/read` on a resource that has nothing to serve — no
backtest has run in this session — is a `-32002`, never an empty document, because `{}` is what an
agent would summarise as "the backtest produced nothing". A **prompt** executes nothing, so the
scope never withholds one; what changes is the text, which names only the write tools this session
actually admits.

Four framing rules follow from how the loop reads stdin *and* how each message is dispatched — `serve` and `Server::handle` in
`crates/vike-cli/src/cmd/mcp.rs` — and a script author will hit all of them:

* **A request carrying an `id` gets exactly one response line; a notification gets none.** A message
  with no `id` is answered with silence even for `initialize`.
* **A line that parses as JSON but carries no `method` is ignored silently.** So echoing a response
  back into the pipe produces nothing, rather than an error you could catch.
* **A line that is not JSON is a `-32700` with `id: null`, and the loop keeps going.** A malformed
  message does not kill the session.
* **Blank lines are skipped, and EOF exits 0.** Closing stdin is the clean shutdown.

Each response is written and **flushed immediately**, so a script that writes a request and then
blocks on a read will not deadlock waiting for a buffer.

<Callout title="The payload is pretty-printed, and the line is still one line">
  The tool's JSON is pretty-printed — but *into a JSON string*, where the newlines become `\n`
  escapes. The transport framing is unaffected: one message, one line. Read by lines, then decode.
</Callout>

## The result envelope [#the-result-envelope]

A successful tool call carries the payload **twice**: pretty-printed inside the usual `text` block,
and again as `structuredContent` for a client that would rather not re-parse a string.

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{ "type": "text", "text": "{\n  \"templates\": [ ... ]\n}" }],
    "structuredContent": { "templates": [] },
    "isError": false
  }
}
```

A failure is a flagged result with **no** `structuredContent`:

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [{ "type": "text", "text": "discover_params requires a `script` string argument" }],
    "isError": true
  }
}
```

<Callout type="warn" title="An unknown tool name is an isError result, not a -32601">
  An unrecognised tool name comes back as `unknown tool: <name>` in an ordinary result carrying
  `isError: true`. A script that only inspects the JSON-RPC `error` member will read a typo'd tool
  name as a successful call and then parse a missing payload. So will a tool that *panics* — a panic
  is deliberately caught and returned as `tool panicked: <name>` with `isError: true`, rather than
  being allowed to take the session down.

  **Test `result.isError` on every call**, not just the presence of `error`.
</Callout>

## Calling a tool [#calling-a-tool]

```json
{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {
  "name": "validate_strategy",
  "arguments": { "script": "let x = param(\"len\", 20);" }}}
```

Note `validate_strategy` and `discover_params&#x60; take &#x2A;*`script`**, not `code`. The two share one
compile path and disagree about a bad script: `validate_strategy` returns it as an `ok: false`
*answer* — the agent reads the compiler message and fixes the script — while `discover_params`
returns it as a tool error, `rhai compile error: …`. A missing `script` argument is a tool error
for both. The four offline tools, and the argument each takes, are on
[Authoring](/docs/ai/trader/authoring); the datahub-backed ones are on
[Backtesting](/docs/ai/trader/backtesting).

## An order-write tool: the two calls, on the wire [#an-order-write-tool-the-two-calls-on-the-wire]

Every write tool is preview-gated, and the gate has **two** conditions rather than one: it executes
only when a call carries `confirm: true` *and* a `preview_token` this server issued for that exact
command. A first call is therefore always a preview, and with no `--node` configured it opens no
connection either — which is what makes the request below safe to paste anywhere.

**Call one — the preview.**

```json
{ "jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": {
  "name": "submit_order",
  "arguments": { "venue": "binance", "symbol": "BTCUSDT", "side": 1, "qty": 0.001 }}}
```

The result's `structuredContent` is the preview. ⚠ **The values below are illustrative** — the
minted id and the token counter differ on every run, and `node_verdict` is whatever *your* node
says — but the field set is exactly what `preview_of` emits:

```json
{
  "will_execute": false,
  "tool": "submit_order",
  "wire_command": {
    "Submit": {
      "client_order_id": "a1b2c3d47",
      "venue": "binance", "symbol": "BTCUSDT",
      "side": 1, "qty": 0.001,
      "order_type": "market",
      "price": null, "trigger_price": null, "reduce_only": false
    }
  },
  "guardrail": { "qty": 0.001, "notional": null, "max_qty": null, "max_notional": null, "within_limits": true },
  "node_verdict": null,
  "verified_by_node": false,
  "preview_token": "pv-1",
  "reason": null,
  "note": "PREVIEW ONLY — nothing was sent. ..."
}
```

`wire_command` is `WireCommand` in `crates/vike-tradehub-client/src/wire.rs`, serialized as-is —
externally tagged, so the variant name is the key and `WireOrderRequest`'s fields are the object.
`notional` is `null` because a market order carries no price to size against, which is the default
order type and the reason the client-side guardrail is not something to lean on.

`node_verdict` is `null` here because this example has no `--node` and no control key, so there was
nobody to ask; with a node configured it carries the node's own dry-run and `verified_by_node`
becomes `true`. The `note` says the same thing in prose, and on this unverified path it says
explicitly that the guardrail is a client-side estimate and not an approval.

**Call two — the execution.** The same arguments, plus both fields:

```json
{ "jsonrpc": "2.0", "id": 6, "method": "tools/call", "params": {
  "name": "submit_order",
  "arguments": { "venue": "binance", "symbol": "BTCUSDT", "side": 1, "qty": 0.001,
                 "confirm": true, "preview_token": "pv-1" }}}
```

Read `preview_token` out of call one's response and put it in call two — that is the whole
protocol. What reaches the venue is the command the *preview* resolved, id included, so there is
nothing to copy back by hand.

<Callout type="warn" title="A script that only checks isError will read a failed confirm as a send">
  Every way of failing this gate returns a **preview**, not an error: no `preview_token`, or a
  `confirm` that is the string `"true"` rather than the JSON boolean (or `1`, or `"yes"`), or both.
  `isError` is `false`, `structuredContent` is a fresh preview carrying a **new** token, and nothing
  went out. Branch on `will_execute`, never on `isError` alone.

  The tokens that *do* raise a tool error are the ones you cannot use anyway: unknown or already used
  (a token fires at most once), expired (the window is 60 seconds), or bound to a different command
  (the binding compares the whole wire command). [Live
  node](/docs/ai/trader/trading#what-the-token-is-and-what-it-is-not) has the four rules and the reason
  the token is deliberately not a secret.
</Callout>

### The four outcomes of a confirmed write [#the-four-outcomes-of-a-confirmed-write]

The server waits for the acknowledgement of the exact command it sent, so the answer always
describes *this* command. It waits up to 2 seconds (`ACK_WAIT`), and there are exactly four shapes:

| What happened                | Shape                                                                                     |
| ---------------------------- | ----------------------------------------------------------------------------------------- |
| The node accepted it         | a normal result: `sent: true`, `outcome: "accepted"`, the authoritative `client_order_id` |
| The node refused it          | `isError: true`, text `node rejected the command: <reason>`                               |
| The connection dropped first | `isError: true`, text saying the outcome is **UNKNOWN** and it may have executed          |
| No answer within 2s          | a **normal** result: `sent: true`, `outcome: "unknown"`                                   |

⚠ &#x2A;*The last two both mean "it may have executed", and only one of them is flagged.** A timeout
comes back as a success-shaped result whose `outcome` is the string `"unknown"`; a dropped
connection comes back as `isError`. A script that branches on `isError` alone will treat a timed-out
submit as a completed one. In both cases the obligation is the same and the note says so: call
`node_snapshot` **before** retrying. The full contract — what the node's `ControlLimits`
(`crates/vike-tradehub/src/server.rs`) and `RiskGate` (`crates/vike-exec/src/risk.rs`) actually
enforce, and why the client-side guardrail is advisory — is on [Live node](/docs/ai/trader/trading).

## Keeping one process alive [#keeping-one-process-alive]

The node connections are opened **lazily and kept** for the life of the process: a control command
is fire-and-forget over a background worker, and the observe connection has to stay subscribed to
keep receiving snapshot pushes (the `Server` struct's own doc says why a per-call connect would be
wrong). So a `printf | vike-cli mcp` one-shot reconnects every time, which is fine for a health
check and wasteful for a session that will issue several node calls.

For a real scripted session, hold the pipe open:

```sh
mkfifo /tmp/vike-mcp-in
vike-cli mcp --node 127.0.0.1:7879 < /tmp/vike-mcp-in &
exec 3> /tmp/vike-mcp-in

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' >&3
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"node_snapshot","arguments":{}}}' >&3

exec 3>&-          # EOF — the server exits 0
```

## Credentials, and their absence [#credentials-and-their-absence]

There is no credential in any of the offline calls above: they need none, and nothing here is
metered. The node tools need `VIKE_TRADEHUB_OBSERVE_KEY` (read) or `VIKE_TRADEHUB_CONTROL_KEY`
(write), read from the process environment and then from `<project>/settings/secrets.env`, and say
so **by name and by location** when neither has one:

```text
VIKE_TRADEHUB_CONTROL_KEY is set neither in the process environment nor in the credential
store — run `vike-cli secrets path` to see which store this project resolves to, and
`vike-cli secrets list` to see whether the key is in it
```

A missing `--node` is a different message, and worth telling apart from the one above:

```text
no vike-tradehub node configured — pass `--node <host:port>` to read node state
```

Both arrive before any socket is opened — `Server::ensure_observe` and `Server::ensure_control`
check the address and the key before they connect — so neither costs a connection attempt.

## When the command itself is the problem [#when-the-command-itself-is-the-problem]

Two exit codes are worth knowing, because `set -e` sees them:

* `vike-cli mcp --help` prints the usage to **stdout** and exits **0**. Help is normal output, not
  a diagnostic — `exit_for_parse_error` in `crates/vike-cli/src/cmd/args.rs` is where that call is
  made, for every non-interactive subcommand. (It exited 1 once, and that broke every wrapper
  checking a status.)
* An unrecognised flag prints `vike-cli mcp: unknown argument: <flag>` plus the usage to **stderr**
  and exits **1**.

Everything `vike-cli` has to say goes to stderr, deliberately: under `mcp`, stdout is a protocol.

## In practice, you ask in English [#in-practice-you-ask-in-english]

Once a client is connected you write none of the above. The mapping is what the tool descriptions
are for:

| You ask                                       | The client calls                                 |
| --------------------------------------------- | ------------------------------------------------ |
| *"Show me the strategy templates"*            | [`list_templates`](/docs/ai/trader/authoring)         |
| *"Does this strategy compile?"*               | [`validate_strategy`](/docs/ai/trader/authoring)      |
| *"What knobs does it have?"*                  | [`discover_params`](/docs/ai/trader/authoring)        |
| *"Which indicators can it call?"*             | [`list_indicators`](/docs/ai/trader/authoring)        |
| *"Backtest this on BTC through last quarter"* | [`run_backtest`](/docs/ai/trader/backtesting)         |
| *"Sweep the fast/slow lengths"*               | [`run_sweep`](/docs/ai/trader/backtesting)            |
| *"Validate it walk-forward"*                  | [`run_walk_forward`](/docs/ai/trader/backtesting)     |
| *"What data do we have stored?"*              | [`list_series`](/docs/ai/trader/backtesting)          |
| *"What is the node holding right now?"*       | [`node_snapshot`](/docs/ai/trader/trading)            |
| *"Flatten the BTC position"*                  | [`flatten`](/docs/ai/trader/trading), previewed first |


# Remote node (/docs/ai/trader/setup/remote-node)



A node on another machine is reached exactly the way a local one is — `--node 127.0.0.1:7879` —
with one thing added in front: an ssh tunnel that makes the daemon's loopback port appear on
yours. Nothing on the daemon changes. This page is that recipe, and the reason it is the recipe
rather than one option among several.

## Why a tunnel, not an open port [#why-a-tunnel-not-an-open-port]

The node protocol authenticates the **connection** and encrypts **nothing**. Its own primitive says
so, in a section headed *What this does NOT buy* — `crates/vike-datahub-client/src/node_auth.rs`,
where `sign` and `verify` live: the handshake is plaintext and authenticates the connection rather
than each frame, and confidentiality and integrity "still come from the tunnel (or a VPN) in front
of it" — scoped authorization behind that barrier, never a replacement for it. The daemon's own
account of the consequence is blunter (`start_observe_server` in
`crates/vike-tradehub/src/tradehub_cli.rs`): on a reachable network the handshake hands out an
offline cracking target for the node key, and once a session is up an on-path attacker can inject
a `Command`.

So the tunnel supplies the two properties the wire deliberately lacks; the keys supply only the
third — *which* of the two scopes this peer may use.

## What the daemon binds, and what not to change [#what-the-daemon-binds-and-what-not-to-change]

`crates/vike-tradehub/src/server.rs`'s `DEFAULT_ADDR` is `127.0.0.1:7879`, and its doc comment
names the tunnel as the intended way in. The address the daemon actually uses is `tradehub_addr`
in `config.toml` (`Config::tradehub_addr`, `crates/vike-config/src/config.rs`), which
`VIKE_TRADEHUB_ADDR` (`TRADEHUB_ADDR_ENV` in the same file) still overrides — and it is **unset by
default**, meaning no node server at all: `start_observe_server` returns without binding when the
address is absent or blank. On the daemon's machine, then:

```toml
# <project>/settings/config.toml
tradehub_addr = "127.0.0.1:7879"
```

Keep it loopback. The tempting edit — `0.0.0.0:7879`, "so I can reach it" — is the thing this page
exists to steer you away from, and the daemon now refuses it: `bind_decision` in `server.rs`
classifies the wildcard binds and any non-loopback interface as public (`bind_exposure`, which
also calls a hostname resolving to both loopback and a LAN address public — the strictest answer
is the true one), and without the separate opt-in `flags.tradehub_allow_public_bind` (or
`VIKE_TRADEHUB_ALLOW_PUBLIC_BIND=1`) the observe server is **not started** and the daemon keeps
trading headless. The refusal is logged as an error whose text tells you to keep `tradehub_addr` on
`127.0.0.1` and run the tunnel below. The flag exists for a trusted LAN or a VPN interface; it is a
distinct flag rather than an inference from the address because typing the address *is* the
mistake.

The daemon reads both node keys from **its own** credential store at bind time
(`vike_tradehub_client::auth::from_vars` over the daemon's `<project>/settings/secrets.env`), and
without `VIKE_TRADEHUB_OBSERVE_KEY` there it likewise starts no server. Control is gated once more
by `flags.tradehub_control`.

## The tunnel [#the-tunnel]

```sh
ssh -L 7879:localhost:7879 <host>
```

Read `-L` left to right: `7879` is the port opened on **your** machine; `localhost:7879` is where
the remote sshd connects on your behalf, evaluated **on the remote host** — so `localhost` there is
the daemon's loopback, which is exactly why a loopback bind is enough. Take the port from
`DEFAULT_ADDR` or from whatever `tradehub_addr` you set, not from memory.

That form ties the tunnel to an interactive shell. For a session that outlives a terminal:

```sh
ssh -N -f \
    -o ServerAliveInterval=30 -o ServerAliveCountMax=3 \
    -o ExitOnForwardFailure=yes \
    -L 7879:localhost:7879 <host>
```

`-N` runs no remote command, `-f` backgrounds after authenticating, the two `ServerAlive*` options
make a silently dead link fail within about 90 seconds instead of hanging, and
`ExitOnForwardFailure` turns "the local port was already taken" into a non-zero exit rather than a
tunnel that forwards nothing. To have something re-establish it, hand the same line to `autossh`:

```sh
autossh -M 0 -N \
    -o ServerAliveInterval=30 -o ServerAliveCountMax=3 -o ExitOnForwardFailure=yes \
    -L 7879:localhost:7879 <host>
```

or give it to a systemd user unit, which restarts it for you:

```ini
# ~/.config/systemd/user/vike-node-tunnel.service
[Unit]
Description=ssh tunnel to the vike-tradehub node

[Service]
ExecStart=/usr/bin/ssh -N -o ServerAliveInterval=30 -o ServerAliveCountMax=3 \
    -o ExitOnForwardFailure=yes -L 7879:localhost:7879 <host>
Restart=always
RestartSec=5

[Install]
WantedBy=default.target
```

(`systemctl --user enable --now vike-node-tunnel`.) If the backtest tools' datahub lives on the same
host, forward its port in the same command — `-L 7878:localhost:7878`, the `DEFAULT_DATAHUB_ADDR`
in `crates/vike-config/src/config.rs` — and `--addr` then needs no change either; that file's
`Config::datahub_advertise_addr` doc describes precisely this two-port tunnel posture.

## Pointing the client at the local end [#pointing-the-client-at-the-local-end]

```sh
vike-cli mcp --node 127.0.0.1:7879
```

The address is your own loopback, so every client entry on the [setup pages](/docs/ai/trader/setup)
works unchanged. The same local end serves the human surfaces: `vike-cli trade --node
127.0.0.1:7879` (`USAGE` in `crates/vike-cli/src/cmd/trade.rs`) and `vike-desktop --observe
127.0.0.1:7879` — the argument after `--observe` is the address (the scan in
`crates/vike-desktop/src/main.rs`'s `main`); [Observe mode](/docs/trader/gui/observe-mode) is that page.

Two questions are being answered here, and they have different answers. **The tunnel authenticates
you to the host** — your ssh key, sshd's business. **The node keys authenticate the connection to
the node** — `VIKE_TRADEHUB_OBSERVE_KEY` for reads and `VIKE_TRADEHUB_CONTROL_KEY` for writes
(`OBSERVE_KEY_ENV` / `CONTROL_KEY_ENV` in `crates/vike-cli/src/cmd/nodekeys.rs`), resolved by
`resolve` in that file per key and independently: the **process environment first, the credential
store second**, a value blank after trimming counting as absent in both, so an empty export cannot
shadow a stored key. They must be the **same** values the daemon loaded on its machine, and on a
remote setup the store your client resolves is *your* `<project>/settings/secrets.env`, not the
daemon's — so either put the two values in it or export them. A key missing from both places
returns a tool error naming both (`Server::missing_key`, `crates/vike-cli/src/cmd/mcp.rs`); the
`trade` REPL prints which source answered on its `connected:` line (`nodekeys.rs`'s `KeyOrigin`).

Withholding the control key is one way to give an agent a read-only view of a remote node, and it
has a limit worth knowing: the write tools are still advertised, and a fully confirmed call reaches
the missing-key error rather than being refused up front. `--profile read-only` is the other way,
and it acts one layer earlier — the seven order-write tools are absent from `tools/list` and refused
by `tools/call`, from one derivation, so nothing on that side of the tunnel offers the agent an
order to place:

```sh
vike-cli mcp --node 127.0.0.1:7879 --profile read-only
```

The two compose, and neither can be widened from the agent's side of the pipe. `--deny-tool NAME`
takes out one more tool by name.

## When the tunnel drops [#when-the-tunnel-drops]

The observe and control connections are opened lazily and kept for the life of the `vike-cli mcp`
process (`Server` in `crates/vike-cli/src/cmd/mcp.rs`) — but a dead one is **not** kept: the next
call that finds it dead reopens it. Four shapes, depending on when the tunnel went and whether the
socket noticed:

* **Before the first use.** `Server::ensure_control` returns `cannot open control connection to
  127.0.0.1:7879: <error>` — usually a refused connection, because nothing is listening on your local
  port; `Server::ensure_observe` says the same with `observe`. Nothing was sent.
* **Mid-command.** The write tool returns an `isError` whose text says the control connection
  dropped before the node answered and the outcome is **unknown** — it may have executed. That is
  `CommandOutcome::Disconnected` in `crates/vike-tradehub-client/src/remote_control.rs`, and the
  [Outcomes](/docs/ai/trader/trading#outcomes) table on the trading page is the contract for it. The
  handle is dropped, so the *next* explicit call reconnects — the unknown command itself is never
  resent by anything.
* **While idle, and the socket reported it** (the tunnel process exited, the daemon restarted).
  The control worker probes the link before writing (`link_is_dead` in `remote_control.rs`), so a
  command that reaches a dead link is classified `CommandOutcome::NeverSent` — not one byte went
  on the wire — and `Server::execute` reconnects and sends *that* command on the same call. The
  agent sees an ordinary outcome, not "unknown". Reads are protected the same way:
  `tool_node_snapshot` checks `RemoteCoreHandle::is_connected` after waiting for a frame, tries one
  fresh connection, and otherwise returns an error naming the last frame's `seq` as **stale** — it
  never returns a stale frame as a result.
* **While idle, and the socket did not report it** (laptop sleep, a Wi-Fi change, a VPN re-key
  under an `ssh -L` with no keepalive). The observe stream carries a heartbeat the node sends every
  `OBSERVE_HEARTBEAT` of silence, and the client reads it under `OBSERVE_READ_TIMEOUT` (three
  beats) — both in `crates/vike-tradehub-client/src/liveness.rs` — so a silently dead link is
  noticed within that window rather than never; a write's reply read carries its own deadline. From
  there it is the reported case above. To shorten the window at the source, run the tunnel with
  `ssh -o ServerAliveInterval=15 -o ServerAliveCountMax=3 -L …`, which turns a silent death into a
  reported one.

The node no longer closes an idle authenticated connection: the 300-second bound in
`crates/vike-tradehub/src/server.rs`'s `handle_connection` applies to the handshake of an
*unauthenticated* peer and is replaced at `AuthOk` by `AUTHED_IDLE_TIMEOUT` (none) — an agent that
thinks for ten minutes between calls is not disconnected for it.

So recovery is: re-establish the tunnel, then carry on — the next call reconnects. No restart of
`vike-cli mcp` is needed. The one discipline that remains is the same as on loopback: after any
outcome that read **unknown**, call `node_snapshot` and read a fresh `seq` before retrying.

## Docker [#docker]

The tunnel's local end is on the **host**, and `127.0.0.1` inside a container is the container's
own loopback — the callout under [Where the binary comes from](/docs/ai/trader/setup#where-the-binary-comes-from)
on the setup page covers what a containerised `vike-cli` needs instead.


# VS Code (/docs/ai/trader/setup/vs-code)



## Add the server [#add-the-server]

Create `.vscode/mcp.json` in the workspace and reload the window:

```json
{
  "servers": {
    "vike-trader": {
      "type": "stdio",
      "command": "vike-cli",
      "args": ["mcp", "--node", "127.0.0.1:7879"]
    }
  }
}
```

Two details are easy to miss if you are copying a Cursor entry: the top-level key is `servers`, not
`mcpServers`, and each entry carries an explicit `type`. That `type` selects the rest of the shape —
`stdio` takes `command` and `args`, `http` takes `url` and `headers`. `vike-cli mcp` is a local
process VS Code launches and speaks stdio to, so `stdio` is the only correct value here.

Both `vike-cli mcp` flags are optional: `--node <host:port>` is the running `vike-tradehub` the live
tools observe and control (no default), `--addr <host:port>` the `vike-datahub` the backtest tools
use (default `127.0.0.1:7878`). Without either, the four offline authoring tools still work. If VS
Code cannot find the binary, give `command` an absolute path — an editor started from the desktop
does not inherit your shell's `PATH`.

## Keep the node keys out of the repository [#keep-the-node-keys-out-of-the-repository]

`.vscode/mcp.json` sits inside the workspace, so anything written into it is one `git add` away from
being committed. The good news is that this server needs nothing secret in the file at all.

`vike-cli` reads `VIKE_TRADEHUB_OBSERVE_KEY` and `VIKE_TRADEHUB_CONTROL_KEY` from the process
environment first and then from `<project>/settings/secrets.env` — the same store the
`vike-tradehub` daemon reads (`crates/vike-cli/src/cmd/nodekeys.rs`'s `resolve`). A desktop-launched
editor passes on none of your terminal's exports, so the store is the source that actually reaches
the server, and it is also the source that keeps the workspace file clean.

⚠ A committed **control** key is worse than a committed API key: it places orders on a live node,
and there is no central console to revoke it from. The fix is to rotate the key in
`<project>/settings/secrets.env` and restart the daemon, which is a real interruption — so do not
put it here in the first place.

## Verify [#verify]

Open Copilot Chat in agent mode and ask:

> list the vike strategy templates

`list_templates` runs offline, with no key, no node and no network, so it separates "is the
subprocess running" from every credential question. Copilot's tools picker should list the
`vike-trader` server; if the server is present but its tools are not offered, they may need enabling
for the conversation.

With a node configured, &#x2A;"show me the node snapshot"* then proves the observe key.

## Troubleshooting [#troubleshooting]

**The file was edited but nothing changed.** Reload the window. MCP configuration is read at
startup.

**The server never appears.** Check the file path (`.vscode/mcp.json`, in the workspace root VS Code
actually has open) and that the JSON parses — a trailing comma silently disables the whole file.

**The server starts but the live tools error while the offline ones work.** That is a node address
or a node key, not the MCP wiring, and the two are worded to be told apart: "no vike-tradehub node
configured" is the `--node` flag; "set neither in the process environment nor in the credential
store" names a key and both places it looked. `vike-cli secrets path` prints the store this project
resolves to; `vike-cli secrets list` shows whether the key is in it, by name.

**The binary is not found.** Run `vike-cli mcp` in a terminal first. It reads JSON-RPC on stdin and
writes every diagnostic to stderr — never stdout, because stdout is a protocol — so a `PATH` problem
or a rejected flag surfaces immediately.

## The data server too [#the-data-server-too]

The same file holds both Vike servers: the hosted [data server](/docs/ai/data) goes in beside this one as
a `"type": "http"` entry with a key header.
[Data client setup → VS Code](/docs/ai/data/setup/vs-code) has its shape, and the warning above about
committing secrets applies with full force to that one — it *does* need a key in the file unless you
use VS Code's input-variable support. The names must differ; a second `vike` replaces the first.


# Windsurf (/docs/ai/trader/setup/windsurf)



## Add the server [#add-the-server]

Open Cascade, click the **MCP** icon in the panel's top-right menu (or go to
**Settings → Cascade → MCP Servers**), and edit the raw configuration. The file is
`~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "vike-trader": {
      "command": "vike-cli",
      "args": ["mcp", "--node", "127.0.0.1:7879"]
    }
  }
}
```

`command` + `args` is the **local** shape, and it is the only one that works here: `vike-cli mcp`
is a subprocess Windsurf starts and speaks newline-delimited JSON-RPC 2.0 to, and it has no URL at
all. The remote shape — a URL rather than a command — is what the [data server](/docs/ai/data) uses.

After editing, refresh the server list from that same MCP panel — Windsurf does not pick the file
up on its own.

## Scoping what the tools reach [#scoping-what-the-tools-reach]

Both `vike-cli mcp` flags are optional and both only *widen* what the tools reach.
`--node <host:port>` is the running `vike-tradehub` the live tools observe and control — no
default. `--addr <host:port>` is the `vike-datahub` the backtest tools ship profiles to, defaulting
to `127.0.0.1:7878`. With neither, the offline tools — `validate_strategy`, `discover_params`,
`list_templates`, `list_indicators` — still work, which makes a flag-less entry a reasonable first
step:

```json
{
  "mcpServers": {
    "vike-trader": { "command": "vike-cli", "args": ["mcp"] }
  }
}
```

If Windsurf reports the binary as not found, give `command` an absolute path: an editor launched
from the desktop does not inherit the `PATH` your shell exports.

## The node keys [#the-node-keys]

<Callout title="A desktop-launched editor inherits none of your shell's exports">
  This is the case the credential store exists for. Windsurf starts `vike-cli mcp` as a child of the
  *application*, not of your terminal, so an `export VIKE_TRADEHUB_CONTROL_KEY=...` in your shell
  profile is invisible to it — the server starts and the offline tools work, but `node_snapshot`
  reports a missing key immediately. A write tool is quieter about it: its preview still returns, with
  `node_verdict: null` and `verified_by_node: false`, because the node dry-run needs the control key
  and silently skips itself without one. The named key error appears only once a call carries both
  `confirm: true` and a valid `preview_token` and the send is actually attempted. Put both keys in `<project>/settings/secrets.env`, the same store the
  `vike-tradehub` daemon reads, and one copy serves both halves.
</Callout>

Each key resolves from the process environment first and then from that store, independently —
`crates/vike-cli/src/cmd/nodekeys.rs`'s `resolve` is the whole rule. The entry does take an `env`
block if you want to pin one:

```json
{
  "mcpServers": {
    "vike-trader": {
      "command": "vike-cli",
      "args": ["mcp", "--node", "127.0.0.1:7879"],
      "env": { "VIKE_TRADEHUB_OBSERVE_KEY": "..." }
    }
  }
}
```

An **observe** key in that file grants reads. A **control** key grants orders, so it is the
expensive one to leave in a config file — prefer the store for it.

`vike-cli secrets path` prints which store a directory resolves to; `vike-cli secrets list` shows
whether a key is in it, by name — never values.

## Verify [#verify]

> list the vike strategy templates

`list_templates&#x60; is offline: no key, no node, no network. If it answers, the subprocess is running
and the protocol is working, and anything still failing is an address or a key rather than the
setup. With a node configured, &#x2A;"show me the node snapshot"* proves the observe key too.

## Troubleshooting [#troubleshooting]

**The server shows as failed.** Almost always the JSON: a trailing comma, or a key nested in the
wrong object. `command`, `args` and `env` are siblings *inside* the server's own object.

**It is green but the tool list is empty.** Refresh from the MCP panel. Windsurf reads the file on
refresh, not on save.

**The offline tools work and the node tools do not.** That is an address or a key, not the MCP
wiring — and almost certainly the inherited-environment trap above. The two failures are worded
differently on purpose: "no vike-tradehub node configured" means `--node` never arrived; "set
neither in the process environment nor in the credential store" names a key, and names both places
it looked.

**A write tool answered and no order exists.** Not a Windsurf problem. A write executes only when a
call carries **both** `confirm: true` **and** the `preview_token` its own preview returned;
anything less comes back as another preview, with `will_execute: false` and no error. [Live
node](/docs/ai/trader/trading#what-the-token-is-and-what-it-is-not) is the contract, and it is worth
reading before an agent in an editor is pointed at a live node.

## Where this shape came from [#where-this-shape-came-from]

The config path and the `mcpServers` object with `command`/`args`/`env`, and the MCP panel route to
it, were read from Windsurf's own Cascade MCP documentation in September 2026, not from memory —
note that `docs.windsurf.com` now redirects into the Devin documentation, which is where that page
lives. That page is the authority if the shape has moved; this one is the copy.

## The data server too [#the-data-server-too]

Windsurf holds both Vike servers in the same `mcpServers` object — the hosted
[data server](/docs/ai/data) as a remote entry beside this one.
[Data client setup](/docs/ai/data/setup) has its shape. The names must differ, or the second replaces
the first.


# cancel_order (/docs/ai/trader/tools/cancel_order)



`cancel_order` withdraws exactly one resting order, named by its client order id. It is a write
tool, so it is annotated `destructiveHint: true` and previews unless a call carries **both**
`confirm: true` **and** the `preview_token` its own preview returned, and it needs
`vike-cli mcp --node <host:port>` plus `VIKE_TRADEHUB_CONTROL_KEY`.

## Arguments [#arguments]

| Parameter         | Type    | Required | Notes                                                                                                            |
| ----------------- | ------- | :------: | ---------------------------------------------------------------------------------------------------------------- |
| `client_order_id` | string  |    yes   | The id to cancel                                                                                                 |
| `reason`          | string  |    no    | Rationale for the node's audit trail                                                                             |
| `confirm`         | boolean |    no    | Must be the JSON boolean `true` **and** be accompanied by `preview_token` — either one missing returns a preview |
| `preview_token`   | string  |    no    | The token this tool's preview returned. Fires once, expires after 60s, bound to the command it previewed         |

Omitting the id is a tool error from `verbs::verb_from_tool_args` before any command is built.

## The preview [#the-preview]

Call it without `confirm` and you get `preview_of(...)`: `will_execute: false`, the resolved
`wire_command`, the advisory `guardrail`, the node's own dry-run when there is a node to ask, the
echoed `reason&#x60;, the confirm note, and a &#x2A;*`preview_token`**. Nothing is sent. With no node
configured nothing is opened either.

To execute, call again with the same arguments plus **both** `confirm: true` **and** that token.
Either one on its own returns another preview — not an error — so read `will_execute` rather than
assuming the second call landed. The token fires once, expires after 60 seconds and is bound to
this exact cancel; [Live node](/docs/ai/trader/trading#what-the-token-is-and-what-it-is-not) has the
four rules and the argument for why it is not a secret.

The guardrail on this verb is always `Guardrail::NoSize` — rendered as `within_limits: true` with a
note saying there was no order size to check. That is not a pass; it is the honest answer that a
cancel has nothing to size.

The rationale round-trip is pinned by
`a_write_preview_echoes_the_reason_without_changing_the_command`, which uses this tool: a `reason`
of `"  stale quote after the feed gap  "` comes back trimmed, a blank one comes back `null`, and
the `wire_command` is byte-identical with and without it. The reason rides *beside* the command on
the wire and can never alter it.

## What the node does with it [#what-the-node-does-with-it]

`lower_command` maps `WireCommand::Cancel` straight to the core's `OrderIntent::Cancel`, and this
is one of the order-scoped verbs, so the acknowledgement echoes the `client_order_id` you named
rather than an empty string.

`ControlLimits::vet` consumes a rate token, as it does for every command, and then stops: its doc
is explicit that the notional cap applies only to order-increasing verbs carrying a price, and that
cancel, flatten, mass-cancel, market-exit and trading-state are risk-reducing and never
size-capped. Cancelling is never refused for being too large.

<Callout type="warn" title="Accepted means the node took the command, not that an order went away">
  A cancel is fire-and-forget, and the code says so plainly:
  `verbs::coid_charset_warning`'s argument closes with "cancel stays fire-and-forget, which is
  honest: the node cannot confirm that an order EXISTS either way." An id that never existed is
  acknowledged exactly like one that did. Call [`node_snapshot`](/docs/ai/trader/tools/node_snapshot) to
  see whether the order actually left the book.
</Callout>

## A malformed id is sent anyway, and that is deliberate [#a-malformed-id-is-sent-anyway-and-that-is-deliberate]

The human `trade` REPL refuses a `submit --coid` outside `^[A-Za-z0-9]{1,32}$` and only **warns**
on a cancel naming one. This MCP surface does not warn at all — `coid_charset_warning` is wired
into the REPL alone.

The asymmetry is argued rather than accidental. A submit is *minting* an id, so insisting on a
charset every venue accepts costs one retype. A cancel names an id that **already exists at the
node**, and this client is not the only thing that puts orders there:
[`submit_order`](/docs/ai/trader/tools/submit_order) passes an agent-supplied `client_order_id` through
unvalidated, and `lower_command` requires only that an id be non-empty. So an order with a coid
outside that charset can exist — and refusing to cancel it would make a live order uncancellable
from the console, to enforce a client-side convention. That trade is unacceptable in a tool whose
reason to exist includes flattening something in a hurry.

## Outcomes [#outcomes]

`Server::execute` awaits this command's own ticket for `ACK_WAIT`, two seconds. `accepted` returns
`sent: true` with the echoed id; a refusal is an error result carrying the node's reason; a timeout
returns `outcome: "unknown"`; a dropped control connection is an error result saying the outcome is
unknown and it may have executed. Both ambiguous cases end the same way — check
[`node_snapshot`](/docs/ai/trader/tools/node_snapshot) before retrying.

To clear a whole book instead of one order, use
[`mass_cancel`](/docs/ai/trader/tools/mass_cancel); to change an order rather than withdraw it, use
[`modify`](/docs/ai/trader/tools/modify). The states an order passes through on its way out are
described in [Order lifecycle](/docs/trader/concepts/order-lifecycle).

> Cancel order a1b2c3d47 — it is stale after the feed gap.


# discover_params (/docs/ai/trader/tools/discover_params)



`discover_params` compiles a Rhai strategy and tells you which knobs it exposes: the exact keys a
profile's `[strategy.params]` or a `[sweep]` grid may override, in declaration order. It is how an
agent finds those names without asking the human who wrote the script.

**Call it on a script you wrote, too.** The description used to read as an inspection tool for
somebody else's code, and an agent that had just authored a strategy answered "which parameters can
I tune" from memory of what it had written instead of calling this. It happened to be right and had
no way to know it was: [`validate_strategy`](/docs/ai/trader/tools/validate_strategy) answers
`{ok: true}` and says nothing about params, and this tool runs the top level only — so the one
mistake worth catching, a `param()` reached from inside a hook, is invisible to the author as well
as to the reader. The tool's own text now says both things (`tools_spec` in
`crates/vike-cli/src/cmd/mcp.rs`).

Offline. `tools_spec` annotates it `readOnlyHint: true`, `idempotentHint: true` and
`openWorldHint: false` — the only one of the three that is unusual is the last: this tool touches
no datahub and no node, so a session with neither configured can still call it.

## Arguments [#arguments]

| Parameter | Type   | Required | Notes                |
| --------- | ------ | :------: | -------------------- |
| `script`  | string |    yes   | Rhai strategy source |

A missing or non-string `script` is a tool error before anything is compiled — the message names
the argument it wanted.

## What comes back [#what-comes-back]

```json
{ "params": [ { "name": "fast", "default": 5.0 }, { "name": "slow", "default": 20.0 } ] }
```

`tool_discover_params` calls `vike_script::discover_params` and maps each `(name, default)` pair
into that object. Defaults are always numbers — `ScriptCtx::params_seen` is an
`IndexMap<String, f64>`, so a knob is an `f64` and nothing else.

Order is **declaration order**, not alphabetical. `discover_params`'s own doc says "in declaration
order", and the `IndexMap` behind `params_seen` is what makes that true rather than incidental.

## How the knobs are found [#how-the-knobs-are-found]

`vike_script::discover_params` builds the engine, compiles the source, and runs its **top level
exactly once** with an empty scope and no overrides. It is broker-agnostic: no `Strategy<B>` is
mounted, so nothing trades and nothing needs a venue.

The recording happens inside the host function itself. `build_engine` registers
`param(name, default)` to record the pair into `params_seen` — **first seen wins** — and return the
injected override if one is present, else the default. Discovery injects no overrides, so what
comes back is the declared default in every case.

<Callout title="param() takes an integer default too">
  The registration comment is explicit that the default argument is a `rhai::Dynamic`, not an `f64`,
  and says why: registered as `f64` it accepted `param("fast", 5.0)` and **rejected**
  `param("fast", 5)` with a Rhai "Function not found" naming an `i64` — a knob that worked or did not
  depending on whether the author typed a decimal point. Every shipped template happens to write
  `5.0`, which is why it went unnoticed.
</Callout>

Because only the top level runs, only the `param()` calls the top level reaches are recorded. That
is the shape the engine documents for the call — `let fast = param("fast", 5.0);` at the top level,
so the one-time run bakes the value in — and a knob buried inside a hook is invisible to discovery.
That is not only a reporting gap: a `[sweep]` grid built from what this tool answers can never name
that knob, so it is driven only by somebody who already knows it is there. The override map itself
is not the limit — `crates/vike-script/src/engine.rs` registers `param` to read `overrides` on
every call, so a name you *do* type into the grid reaches a hook-level `param()` like any other.

## A compile error is a tool error here [#a-compile-error-is-a-tool-error-here]

This is the one place `discover_params` and
[`validate_strategy`](/docs/ai/trader/tools/validate_strategy) differ, and they run the *same* compile
path. `validate_strategy` turns a bad script into an `ok: false` **answer** the agent reads and
fixes; `discover_params` returns a tool error, `rhai compile error: …`. If you are checking whether
a script is sound, call `validate_strategy`; call this one when you want the knobs.

<Callout type="warn" title="Compiling is a much weaker signal than it looks">
  Rhai resolves a registered function when its line **runs**, not at compile time, and this tool runs
  only the top level — so every call inside `on_bar` is unchecked. Three mistakes land in that blind
  spot: an unbound **name** (a typo, or any name outside the host-bound set), a wrong **arity**, and
  a wrong **argument type** on a concretely-typed binding — Rhai's `resolve_fn` hashes each argument's
  `TypeId` and performs no int-to-float coercion for a registered function, so `market(1, 1)` misses
  as hard as a typo, while the indicators and `param` take a `rhai::Dynamic` and accept either. Each
  raises a runtime error on **every bar** — function-not-found for the first two, and
  `crates/vike-script/src/engine.rs`'s `bad_arg` message for a non-numeric indicator argument.
  `RhaiStrategy`'s hook runner swallows it (fail-safe: zero orders that bar) and self-disables after
  10 consecutive errors. The strategy looks mounted and silently never trades. Check the names
  against [`list_indicators`](/docs/ai/trader/tools/list_indicators), which reports the set the host
  actually binds.
</Callout>

## Where it sits in a session [#where-it-sits-in-a-session]

Start from [`list_templates`](/docs/ai/trader/tools/list_templates) or your own source, call this to see
the knobs, then name those knobs in a `[sweep]` table and hand the profile to
[`run_sweep`](/docs/ai/trader/tools/run_sweep) — each key there overrides `strategy.params.<key>` across
a value grid. The language itself is documented under
[Scripting](/docs/trader/scripting/writing-a-strategy), and the engine's registered surface in
[The engine](/docs/trader/scripting/the-engine).

> Here is my Rhai strategy — what knobs does it expose, and what are their defaults?


# flatten (/docs/ai/trader/tools/flatten)



`flatten` closes the net position in one `(venue, symbol)` book. It mints no size of its own: the
quantity is the position, resolved when the intent is applied. Annotated `destructiveHint: true`
like every write tool, it previews unless a call carries **both** `confirm: true` **and** the
`preview_token` its own preview returned, and needs `vike-cli mcp --node <host:port>` plus
`VIKE_TRADEHUB_CONTROL_KEY`.

## Arguments [#arguments]

| Parameter       | Type    | Required | Notes                                                                                                            |
| --------------- | ------- | :------: | ---------------------------------------------------------------------------------------------------------------- |
| `venue`         | string  |    yes   | Venue id                                                                                                         |
| `symbol`        | string  |    yes   | Instrument symbol                                                                                                |
| `reason`        | string  |    no    | Rationale for the node's audit trail                                                                             |
| `confirm`       | boolean |    no    | Must be the JSON boolean `true` **and** be accompanied by `preview_token` — either one missing returns a preview |
| `preview_token` | string  |    no    | The token this tool's preview returned. Fires once, expires after 60s, bound to the command it previewed         |

There is no quantity argument, and that is the design rather than an omission. `OrderIntent::Flatten`
closes the `(venue, symbol)` net position with a **reduce-only market order for `|position|`,
resolved at apply time**, and is a **no-op when flat**. If you want to take off part of a position,
that is a reduce-only [`submit_order`](/docs/ai/trader/tools/submit_order), not this tool.

## The preview [#the-preview]

Called without `confirm`, the write arm builds the command and returns `preview_of(...)` —
`will_execute: false`, the resolved `wire_command`, the advisory `guardrail`, the node's own
dry-run when there is a node to ask, the echoed `reason&#x60;, the confirm note, and a
&#x2A;*`preview_token`**. Nothing is sent, and with no node configured nothing is opened. The guardrail
is `Guardrail::NoSize` (`within_limits: true`, "no order size to check for this verb"): the client
cannot size a flatten either, because the position it will close lives on the node.

Closing the position takes a second call carrying **both** `confirm: true` **and** that token.
Either one on its own returns a fresh preview instead — not an error — so `will_execute` is the
field that tells you whether the flatten was actually issued. The token fires once, expires after
60 seconds and is bound to this `(venue, symbol)`;
[Live node](/docs/ai/trader/trading#what-the-token-is-and-what-it-is-not) has the four rules.

<Callout type="warn" title="The preview shows the intent, never the resulting order">
  Because the quantity is resolved at apply time on the node, the `wire_command` in the preview names
  only the venue and symbol. Nothing on this side can tell you how big the resulting market order
  will be. [`node_snapshot`](/docs/ai/trader/tools/node_snapshot) is what shows you the position before you
  confirm — and the fill afterwards.
</Callout>

## What the node does with it [#what-the-node-does-with-it]

`lower_command` maps `WireCommand::Flatten` to the core's `OrderIntent::Flatten` with an **empty**
coid. That is the account-wide-verb convention: the acknowledgement has no order id to echo,
because the order does not exist yet. The accepted response says so in its own note — an empty
`client_order_id` means an account-wide verb.

`ControlLimits::vet` consumes a rate token and stops there. Its doc lists flatten among the
risk-reducing verbs — cancel, flatten, mass-cancel, market-exit, trading-state — that are never
size-capped. A flatten cannot be refused for being too large, which is the right way round for the
only verb whose whole job is getting smaller.

## It works from a halted core [#it-works-from-a-halted-core]

The reduce-only shape is what gets flatten past the kill switch when nothing else gets through.
`OrderIntent::MarketExit` documents the rule for the compound verb built out of this one: the
`RiskGate` kill switch admits a **position-covered reduce** under `Halted`
(`vike_model::is_covered_reduce`), and that is exactly the shape a flatten mints — side opposite
the position, quantity `|position|`. The same property makes it permitted under
`TradingState::Reducing`. Admission at that arm is all it buys: the rest of
`RiskGate::check_inner` still runs, so an armed `max_notional_per_order` or `max_total_exposure`
denies an oversized flatten in any state, and under `Halted` the verdict is re-taken on the
**lot-rounded** size — a `|position|` of `1.8` on a `1.0` lot rounds up to `2.0`, which would flip
the position, so that leg comes back denied with the reason `halted`.

That correction was made because the reverse had been true for the verb's whole life: the gate
denied every order under `Halted`, `reduce_only` included, so the exits were disarmed in precisely
the situations that reach `Halted` on their own. A kill switch must stop you opening risk, never
trap you in it. [Risk and arming](/docs/trader/concepts/risk-and-arming) sets out the order the gates are
consulted in, and [`set_trading_state`](/docs/ai/trader/tools/set_trading_state) is the tool that moves
the switch.

## Outcomes [#outcomes]

`Server::execute` awaits this command's own ticket for two seconds. `accepted` returns
`sent: true` with an empty `client_order_id`; a refusal is an error result carrying the node's
reason; a timeout returns `outcome: "unknown"`; a dropped control connection is an error result
saying the outcome is unknown and it may have executed. For both ambiguous cases, call
[`node_snapshot`](/docs/ai/trader/tools/node_snapshot) **before** retrying — a repeated flatten against
a book that is already flat is a no-op, but a repeat issued while the first is still in flight is
not obviously one.

To empty one venue or the whole account rather than one book, use
[`mass_cancel`](/docs/ai/trader/tools/mass_cancel) for the resting orders and
[`market_exit`](/docs/ai/trader/tools/market_exit) for both at once.

> Flatten the BTCUSDT position on binance.


# MCP tools (/docs/ai/trader/tools)



`tools/list` returns the whole registry in one response. `tools_spec()` in
`crates/vike-cli/src/cmd/mcp.rs` is that registry — every tool's name, description, input schema
and risk annotations — and `Server::call_tool`'s `match name` is the dispatch half. Each tool has
its own page below: what it does, its schema, a call you can paste into a stdio session, the shape
that comes back, and one prompt that reaches it.

## Three planes, and what each one needs [#three-planes-and-what-each-one-needs]

The tools split by what they touch, not by what they do. Nothing in the first group opens a
socket at all.

| Plane                                   | Tools                                                                                                                                                                                                                                                                                                                                       | Needs                                               |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| Offline — pure `vike-script`, no server | [`validate_strategy`](/docs/ai/trader/tools/validate_strategy) · [`discover_params`](/docs/ai/trader/tools/discover_params) · [`list_templates`](/docs/ai/trader/tools/list_templates) · [`list_indicators`](/docs/ai/trader/tools/list_indicators)                                                                                                             | nothing                                             |
| A `vike-datahub` server                 | [`run_backtest`](/docs/ai/trader/tools/run_backtest) · [`run_sweep`](/docs/ai/trader/tools/run_sweep) · [`run_walk_forward`](/docs/ai/trader/tools/run_walk_forward) · [`list_strategies`](/docs/ai/trader/tools/list_strategies) · [`list_series`](/docs/ai/trader/tools/list_series)                                                                               | `--addr`, default `127.0.0.1:7878` (`DEFAULT_ADDR`) |
| A running `vike-tradehub` node          | [`node_snapshot`](/docs/ai/trader/tools/node_snapshot)                                                                                                                                                                                                                                                                                           | `--node` + the observe key                          |
| The same node, order-write              | [`submit_order`](/docs/ai/trader/tools/submit_order) · [`cancel_order`](/docs/ai/trader/tools/cancel_order) · [`modify`](/docs/ai/trader/tools/modify) · [`flatten`](/docs/ai/trader/tools/flatten) · [`market_exit`](/docs/ai/trader/tools/market_exit) · [`mass_cancel`](/docs/ai/trader/tools/mass_cancel) · [`set_trading_state`](/docs/ai/trader/tools/set_trading_state) | `--node` + the control key                          |

The two halves fail separately and the offline four never notice: `Server::ensure_observe` and
`Server::ensure_control` run before any socket is opened, and a missing key produces an error that
names both places it looked. [The server page](/docs/ai/trader) has the flag and key detail.

## The registry a session sees can be smaller than this [#the-registry-a-session-sees-can-be-smaller-than-this]

`tools/list` returns the whole registry only under the default `--profile full`. An operator who
launches the server as `--profile read-only` serves the first three rows above and **withholds the
fourth**; `--profile offline` serves only the first; `--deny-tool NAME` takes out one more, and is
repeatable. A withheld tool is absent from the advertised registry as well as refused by
`tools/call`, because `ToolAccess::new` produces the advertised set and its withheld complement from
one pass over `tools_spec()` — an advertised-but-refused tool, or a withheld-but-routed one, is the
bug a scoping feature must not ship with. The rings are predicates rather than second rosters:
`read-only` is the negation of `is_write_tool` (so an eighth write verb joins it by construction)
and `offline` is each tool's own `openWorldHint` annotation read back. Which tools each ring leaves
you, and how a refusal reads, is on [`vike-cli mcp`](/docs/trader/reference/cli/mcp).

## Every result has the same shape [#every-result-has-the-same-shape]

A success is `tool_ok`: the payload pretty-printed into one `text` content block, the same value
again as `structuredContent`, `isError: false`. A failure is `tool_err` — the message as text with
`isError: true`. That is an ordinary tool *result*, not a JSON-RPC error, so the agent reads it and
retries rather than seeing the call fail at the protocol layer. Even a panicking tool arrives that
way: `Server::handle` wraps every call in `catch_unwind` and turns a panic into
`tool panicked: <name>`, pinned by `a_panicking_tool_becomes_iserror_not_a_dead_session`.

## Ten read, seven write [#ten-read-seven-write]

The split is machine-pinned rather than conventional. Every read-only tool carries
`readOnlyHint: true` and every write tool carries `destructiveHint: true` in `tools_spec()`, and
`tools_list_has_read_and_write_tools_with_correct_hints` fails the build if a tool falls on the
wrong side — it also asserts each write tool's *description* mentions `confirm`, so at least half
the gate is part of the advertised contract. Only half: the description is what that test reads,
and the **schema** carries the other half. Both properties are defined once and spliced into all
seven tools — `confirm_property` and `preview_token_property` — so the wording cannot drift between
them, which is how the old inline copies ended up in four different spellings. The write roster is
a fixed-size const, `WRITE_TOOLS: [&str; 7]`, because it must stay the full write-verb set of the
human `trade` REPL: both surfaces build their commands through the one construction site in
`crate::cmd::verbs`, so they cannot drift into two vocabularies.

<Callout type="warn" title="A write needs confirm: true AND a preview_token — and one without the other is a preview, not an error">
  `Server::call_tool`'s write arm reads the two together: a `preview_token` is only looked up when
  `confirm` is the JSON boolean `true`, and a confirm with no token binds nothing. Fail *either*
  condition and `preview_of` returns the resolved wire command, the advisory guardrail check, the
  node's own dry-run when there is a node to ask, the rationale that would be recorded — and a fresh
  `preview_token`. Nothing is sent, and nothing is flagged: `will_execute: false` is the only signal.
  `confirm` is read as a JSON boolean and nothing else, so `"true"`, `1` and `"yes"` fall through the
  same way.

  A token that is unknown, already used, expired past `PREVIEW_WINDOW` or bound to a *different*
  command is the loud case — a tool error naming which. The mechanism, and why the token is
  deliberately not a secret, is on [Live node](/docs/ai/trader/trading#what-the-token-is-and-what-it-is-not).
</Callout>

## The arming ceiling applies to every order-placing tool [#the-arming-ceiling-applies-to-every-order-placing-tool]

A write tool mounts nothing. It hands a `WireCommand` to a node that is already running, and what
that node may do to a venue was decided at *its* mount, not here. `vike_mount::make_engine`
consults the deployment's per-venue arming ceiling — `policy.venues.<venue>`, ordered
`paper < demo < live` — **first, above the credential read**: a `paper` venue returns the paper
client having loaded no credential, fetched no instrument grid and opened no socket. The ceiling
can only ever refuse, because `vike_config::VenueMode::cap` is `min` and never `max`, so
`venues.bybit = "live"` does not put bybit live — it declines to stop it. Below that sits the older
rule, that absent credentials *are* the live gate.

Two more gates stand between an accepted command and a fill, and both are server-side on the node:
`ControlLimits::vet` consumes a rate token on every command and applies its notional cap only to
the order-increasing verbs that carry a price (Submit and Modify — cancel, flatten, mass-cancel,
market-exit and set-trading-state are risk-reducing and never size-capped), and beneath it the
execution core's `RiskGate`. The preview's own guardrail is client-side advisory UX; nothing an
agent sends from here can loosen either. [Risk and
arming](/docs/trader/concepts/risk-and-arming) is the concept page,
[`policy.toml`](/docs/trader/reference/settings/policy) the key.

## Where to start [#where-to-start]

[Drive Vike from Claude](/docs/ai/trader/drive-vike-from-claude) runs the whole loop end to end;
[`reference/cli/mcp`](/docs/trader/reference/cli/mcp) is the verb that starts the server.


# list_indicators (/docs/ai/trader/tools/list_indicators)



Lists the indicators a Rhai strategy can call. Offline: no server, no key. The answer is tiered,
because the bound set is most of the catalog and a full dump would spend an agent's context on
indicators it will never use.

## Input [#input]

| Field       | Type   | Default | Answers                                                                                         |
| ----------- | ------ | ------- | ----------------------------------------------------------------------------------------------- |
| *(neither)* | —      | —       | the compact roster: `name` + `category` per indicator, plus a `count` and a `note`              |
| `name`      | string | omit    | one indicator in full — its parameters with defaults, the value it returns, and how to spell it |
| `category`  | string | omit    | one family in full, matched case-insensitively                                                  |

Both are trimmed and a blank string counts as omitted. `tool_list_indicators` checks `name` first
and returns, so a call passing both answers the name.

```json
{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"list_indicators","arguments":{"name":"rsi"}}}
```

## What comes back [#what-comes-back]

The compact roster is `{ "indicators": [ { "name": …, "category": … } … ], "count": N, "note": … }`.
Categories are the `vike_indicators::Category` variants the built-in catalog carries — `Overlap`,
`Momentum`, `Volatility`, `Volume`, `Statistics`, `Pattern`, `Price`, `Structure` — and the rows
come back in registry order, which is curated so related indicators stay together, not
alphabetized. The enum's one other variant, `User`, names a user-written indicator and never
reaches this roster.

A detail row (`name`, or every row under a `category`) adds the fields a roster cannot carry:

| Field       | Meaning                                                        |
| ----------- | -------------------------------------------------------------- |
| `pretty`    | the display label                                              |
| `params`    | one entry per parameter: `name`, `default`, `min`, `max`       |
| `outputs`   | the output lines, in order                                     |
| `accessors` | the per-line spellings, as `line` and the `call` that reads it |
| `bare_call` | whether the bare name resolves at all                          |

Those last two are the pair to read together. `bare_call: false` with a non-empty `accessors` is
the band-indicator shape — reachable, but only line by line. Without the flag there is no way to
tell `bollinger(20)` from `macd(12, 26, 9)` by looking at `outputs`.

The parameters are why detail exists: the host registers one call form per argument count, from
zero up to the parameter count, and the omitted ones take the defaults printed here.

## It is the bound set, never the registry [#it-is-the-bound-set-never-the-registry]

The filter is `vike_script::is_callable` — reachable under its bare name, **or** through at least
one per-line accessor. That is not the same question as membership in the host's bound-name list:
`bollinger` is absent from that list, because its bare name is refused when line 0 is the upper
band, while `bollinger_mid(20)` is perfectly callable. A surface asking the older question reports
a band indicator as unreachable and offers no way in.

The same helpers render the human [`vike-cli indicators`](/docs/trader/reference/cli/research/indicators)
listing, so the two surfaces cannot disagree about what a script may call — which is the only
property that matters here, because the cost of being wrong is silent.

<Callout type="warn" title="A name this tool does not list compiles, then fails on every bar">
  Rhai resolves a registered function when the line **runs**. A script naming an unbound indicator
  compiles, raises `ErrorFunctionNotFound` on every bar, is swallowed fail-safe, and disables itself
  after 10 consecutive errors — mounted, and silently never trading. Check names here rather than
  from memory, and see [`validate_strategy`](/docs/ai/trader/tools/validate_strategy) for why a compile
  cannot catch it.
</Callout>

## A miss is an error, and it explains itself [#a-miss-is-an-error-and-it-explains-itself]

A `name` or `category` nobody can serve is an `isError` result, not an empty list — an empty
answer reads as "that family is empty in this build" and sends the reader hunting through a
config. An unknown category names the ones this build has. An unknown name splits the two ways a
name can miss: not in the registry at all is a typo, while a **real** indicator the host holds
back answers with the host's own reason rather than a paraphrase. Those reasons are the exclusion
rules themselves — a Rhai reserved word or symbol, so the call fails at parse time (`var`, for
Variance; `stddev` is the way in); a collision with a host read or verb, which binding would shadow
for every script; `batch_only`, meaning it reads future bars so the streamed value is retroactively
revised and disagrees with the chart; more parameters than the bridge can express; or a
multi-output whose line 0 is not the namesake, where the message names the accessor that works.

<Callout title="Two things this tool does not answer">
  `name` matches the registry name exactly, so an accessor spelling such as `bollinger_mid` is not a
  name it resolves — ask for `bollinger` and read its `accessors`. And it lists the **built-in**
  catalog only: an indicator you wrote into `user_data/indicators` is callable from the same script
  by the same spelling, but the human `vike-cli indicators` command is what prints it, under its own
  heading.
</Callout>

## The prompt [#the-prompt]

> Which indicators can a Vike Trader Rhai strategy call, and what parameters does `rsi` take?

The `tools/list` description deliberately names none of the roster and is size-capped, because it
ships in every session whether the tool is called or not — so an agent must call the tool to get
the set. [The indicator catalog](/docs/trader/indicators) is the per-category reference and
[writing an indicator](/docs/trader/scripting/writing-an-indicator) the route to your own.


# list_series (/docs/ai/trader/tools/list_series)



`list_series` answers the question every backtest starts with: &#x2A;what data is actually there?* It
returns one row per stored series with the span and row count that series covers, which is what a
profile's `[data]` table can name.

Read-only and remote. `tools_spec` advertises it with `readOnlyHint: true`,
`idempotentHint: true` and `openWorldHint: true` — it changes nothing, the same call twice gives
the same answer, and it reaches off this machine to do it.

## Arguments [#arguments]

None. Its `inputSchema` declares an object with no properties, so the call is the empty object.

```json
{ "name": "list_series", "arguments": {} }
```

## What comes back [#what-comes-back]

`Server::call_tool` routes to `tool_list_series`, which connects to the datahub, calls
`DatahubClient::inventory`, and projects each row into JSON:

```json
{
  "series": [
    {
      "kind": "bar", "venue": "binance", "symbol": "BTCUSDT", "interval": "1m",
      "first_ts": 1704067200000, "last_ts": 1735689600000, "rows": 525600
    }
  ]
}
```

Seven fields, four from `vike_data::series::SeriesId` and three from `SeriesCoverage`. The
`SeriesId` tuple is exactly what the store's leaf directory encodes —
`kind=…/venue=…/symbol=…[/interval=…]` — so `interval` is present for bars, which sub-partition by
bar step, and `null` for tick series. The layouts each `kind` implies have their own pages under
[the data-kind reference](/docs/trader/concepts/data/), and the store itself is described in
[The history store](/docs/trader/concepts/hist-store).

Coverage is cheap on purpose. `SeriesCoverage`'s own doc states it is computed from the manifest
file-index with **no DataFusion scan**, which is why an inventory over a large store is a metadata
read rather than a query.

## Four fields the projection drops [#four-fields-the-projection-drops]

`SeriesCoverage` also carries `bytes`, `parts` and `dates`, and `SeriesId` carries `group`.
`tool_list_series` projects none of them.

<Callout type="warn" title="A grouped series reports an empty symbol">
  `SeriesId::group` is `Some(g)` for a **grouped** series — one part file holding many symbols, told
  apart by a row-level symbol column instead of one series per symbol. Its doc is explicit that
  `symbol` is **empty** in that case, deliberately, so a consumer scanning by `id.symbol` fails
  visibly rather than silently scanning `""`. The tool does not project `group`, so such a row
  arrives here as a blank `symbol` with no replacement label. `SeriesId::label` — group if grouped,
  else symbol — is the accessor that resolves it, and it is not on this wire. Treat a blank `symbol`
  as "grouped, ask the store", never as "no symbol".
</Callout>

## It needs a reachable datahub [#it-needs-a-reachable-datahub]

The address comes from `vike-cli mcp --addr <host:port>`, defaulting to `DEFAULT_ADDR`,
`127.0.0.1:7878`. If nothing is listening there the tool returns a clean error result whose text
begins `cannot connect to datahub at` — never a panic and never a dead stdio session.
`remote_run_tools_without_a_reachable_datahub_are_clean_errors` pins that for this tool alongside
`run_sweep` and `run_walk_forward`, by pointing the server at a port that refuses immediately.

The `vike-datahub` server is the process that holds the store; see
[its binary page](/docs/trader/reference/binaries/vike-datahub) for how it is run and
[Connect an agent](/docs/trader/guides/connect-an-agent) for wiring the MCP server up in the first
place.

## Where it sits in a session [#where-it-sits-in-a-session]

`list_series` is the first of the three remote read tools an authoring loop uses: this one says
what data exists, [`list_strategies`](/docs/ai/trader/tools/list_strategies) says which compiled
strategy names a profile can resolve, and
[`list_indicators`](/docs/ai/trader/tools/list_indicators) says what a Rhai script may actually call.
Only then does the profile you hand [`run_backtest`](/docs/ai/trader/tools/run_backtest) name a series
that is really in the store over a range that is really covered.

> What series does the datahub have for binance, and how far back does the 1m BTCUSDT bar data go?


# list_strategies (/docs/ai/trader/tools/list_strategies)



Asks the remote `vike-datahub` server which compiled **native** backtest strategies it offers —
the names a profile's `strategy.name` can resolve. Takes no arguments, requires a reachable
datahub at `--addr`, and answers from a compile-time constant rather than from the store.

## Input and output [#input-and-output]

The input schema is an empty object. `tool_list_strategies` connects like the run tools and calls
`DatahubClient::list_strategies`, which sends the `ListStrategies` verb and reads back
`Response::Strategies` — `vike_backtest::harness::STRATEGIES`, over RPC, **in its declared order**.
That order is a documented wire property, so the answer is stable across calls rather than
alphabetized by whoever rendered it.

```json
{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"list_strategies","arguments":{}}}
```

The result is `{ "strategies": [ … ] }` — a flat list of names. As the const stands in this
workspace, in declared order:

```json
{ "strategies": [
  "buy_hold", "rotation_top_k", "bracket_per_symbol", "gated_weights", "caps_sizers_mask",
  "tick_pair_mse", "cheap_catch_updown_fair_value", "sport_copy_follower", "grid",
  "dca_accumulate", "spread_maker", "gueant_maker", "trailing_scalper", "momentum",
  "funding_carry", "funding_capture", "pairs_zscore"
] }
```

Call the tool rather than copying that list: the roster belongs to the **server's** build, and
this tool exists so an agent can discover it instead of assuming it.

## What the roster is, and is not [#what-the-roster-is-and-is-not]

`STRATEGIES` is the union of two registry halves. The portable half lives in
`vike_strategy::registry` and is generic over the broker, so the same strategy a backtest ran can
be mounted by the live daemon. The simulator half stays in `vike-backtest` for two reasons that
`vike_strategy::SIMULATOR_ONLY` keeps apart: five names are `impl Strategy<SimBroker>` reference
strategies that reach the simulator's own machinery, and two are portable in principle but reach
that crate's internal modules. Either way, `vike-backtest` is the crate the live daemon
deliberately does not depend on, so those names backtest and do not mount.
[The portable registry](/docs/trader/strategies/the-registry) and
[simulator-only strategies](/docs/trader/strategies/simulator-only) are the two pages; each portable
name also has its own [template page](/docs/trader/strategies/templates) with its parameter keys.

<Callout type="warn" title="rhai is not in this list, and that is deliberate">
  The registry has a `"rhai"` arm, and it is the one a script runs through — but it needs a `src`
  param, so it is not resolvable with default params. Listing it would break every consumer that
  enumerates this roster and resolves each name with empty params. Scripts are the *other* route to
  the same engine: hand your source to [`run_backtest`](/docs/ai/trader/tools/run_backtest)'s `script`
  argument under `name = "rhai"`, and use [`list_templates`](/docs/ai/trader/tools/list_templates) for
  starters.
</Callout>

<Callout title="A user strategy the server can run is not in this answer">
  `strategy_by_name` tries the built-in arms first and then consults the user registry compiled from
  `user_data/strategies/rust`, so a user name resolves — but the wire verb returns
  `harness::STRATEGIES` and nothing else. The list is the built-in roster, not everything the server
  will accept. The harness's own "unknown strategy" error does name both sets, so a typo's message
  is more complete than this tool's answer.
</Callout>

## Failure modes [#failure-modes]

An unknown `strategy.name` is a validation error at profile load — the harness fails fast rather
than silently no-opping on a typo, which is why checking against this list before authoring a
profile is worth one call.

Unlike the three run verbs, `ListStrategies` is **observe** scope on the server: it returns a
compile-time const roster, not store contents, and is served on every build, DataFusion or not. It
is still reached here through `DatahubClient::connect`, so a datahub that advertises the `auth`
feature refuses at connect like every other tool on this plane. An unreachable server is a clean
tool error, never a panic —
`list_strategies_without_a_reachable_datahub_is_a_clean_error` is the pin, and
`list_strategies_is_advertised_read_only` holds its `readOnlyHint`.

## The prompt [#the-prompt]

> Which built-in strategies can I name in a profile on this server?

Then pair the name with [`list_series`](/docs/ai/trader/tools/list_series) to pick a `[data]` range,
and [`run_backtest`](/docs/ai/trader/tools/run_backtest) to run it.


# list_templates (/docs/ai/trader/tools/list_templates)



Returns the starter Rhai strategies as `{name, code}` rows. Offline — no server, no key, no
argument. Each starter is parameterized via `param()`, so it drops straight into
[`run_sweep`](/docs/ai/trader/tools/run_sweep) without editing.

```json
{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"list_templates","arguments":{}}}
```

## What comes back [#what-comes-back]

`{ "templates": [ { "name": …, "code": … }, … ] }`. The sources are static data in `mcp.rs`'s
`TEMPLATES`, so the payload is fixed by the build rather than by anything on disk. On the wire
each `code` is a JSON string with escaped newlines; unescaped, the three rows are:

**SMA cross**

```rust
let fast = param("fast", 5.0);
let slow = param("slow", 20.0);
fn on_bar() {
    let f = sma(fast.to_int()); let s = sma(slow.to_int());
    if s.is_nan() { return; }
    let target = if f > s { 1.0 } else { -1.0 };
    let delta = target - position();
    if abs(delta) > 1e-12 { market(if delta > 0.0 { 1 } else { -1 }, abs(delta)); }
}
```

**RSI reversion**

```rust
let len = param("len", 14.0);
let lo = param("lo", 30.0);
let hi = param("hi", 70.0);
fn on_bar() {
    let r = rsi(len.to_int());
    if r.is_nan() { return; }
    if r < lo && position() <= 0.0 { market(1, 1.0); }
    if r > hi && position() >= 0.0 { market(-1, 1.0); }
}
```

**Donchian breakout**

```rust
let len = param("len", 20.0);
fn on_bar() {
    let h = sma(len.to_int());   // symmetric proxy. donchian is NOT bound: it is multi-output
                                 // (upper/mid/lower) and the bridge binds single-output indicators
                                 // only, so `donchian(len)` is a function-not-found at the first
                                 // call rather than a silent upper-band read.
    if h.is_nan() { return; }
    if high() > h && position() <= 0.0 { market(1, 1.0); }
    if low() < h && position() >= 0.0 { market(-1, 1.0); }
}
```

Read all three as *shapes*, not as edges: each guards its warm-up with an `is_nan()` early return,
each reads its knobs at the top level where `param()` runs, and each does its trading inside
`fn on_bar()`.

## The gate that makes this list safe to copy [#the-gate-that-makes-this-list-safe-to-copy]

Two tests stand behind the rows, and the second is the one that matters. One compiles every
template and asserts it exposes `param()` knobs and defines `on_bar`. The other,
`every_shipped_template_reaches_the_broker`, mounts each one as a real `RhaiStrategy` over a
broker double, drives 80 strictly-rising bars through it, and asserts an order actually arrives —
routed to the bar's own symbol, with a side of exactly ±1 and a positive quantity.

Compiling is the wrong bar for a surface an agent copies from. The compile path runs a script's
top level only, so every call inside `on_bar` is unchecked, and an unbound name, a wrong arity or
a wrong argument type all compile cleanly and then raise on every bar until the strategy disables
itself. Only execution distinguishes that from a strategy that simply saw no signal — which is why
the gate runs the templates rather than parsing them.

<Callout type="warn" title="The Donchian starter does not call donchian, and its source says why">
  It stands in with `sma`, symmetrically. A bare multi-output call binds only when line 0 is the
  indicator's namesake line, and `donchian` declares `upper`/`mid`/`lower` — so `donchian(len)` is a
  function-not-found on the first bar rather than a silent upper-band read. Every line is separately
  reachable through a per-line accessor (`donchian_mid()` is the spelling). The template's own
  comment says "the bridge binds single-output indicators only", which was the rule when it was
  written: the host used to reject every multi-output indicator outright and has since narrowed to
  the namesake test — a multi-output indicator whose line 0 *is* its namesake now binds under its
  bare name, and `donchian` still does not. The conclusion the comment draws is unchanged. Check any
  indicator name against
  [`list_indicators`](/docs/ai/trader/tools/list_indicators) before you edit one in.
</Callout>

<Callout title="Two copies of these sources exist, and they are edited together">
  The MCP copy is a hand copy of `vike-studio-core`'s `templates`, because importing that crate
  would drag DataFusion into a deliberately DataFusion-free CLI. There is no cross-crate drift gate
  — each side instead carries its own execution gate over its own copy. If you are changing a
  starter in the product tree, change both.
</Callout>

## The prompt [#the-prompt]

> Show me the Vike Trader strategy templates and explain what each one trades.

The natural next step is to edit one and run
[`validate_strategy`](/docs/ai/trader/tools/validate_strategy), then
[`discover_params`](/docs/ai/trader/tools/discover_params) to confirm the knobs a `[sweep]` may vary.
[Scripting](/docs/trader/scripting) is the language reference; the same starters are what the Studio's
templates dropdown renders.


# market_exit (/docs/ai/trader/tools/market_exit)



`market_exit` is the get-me-out verb. Its own tool description calls it the panic button, and it is
the one command that empties the order book and the positions together. It previews unless a call
carries **both** `confirm: true` **and** the `preview_token` its own preview returned, and needs
`vike-cli mcp --node <host:port>` plus `VIKE_TRADEHUB_CONTROL_KEY`.

<Callout type="warn" title="The panic button is two calls, and the first one is not one of them">
  This verb is the one where the two-call gate costs something real: in an incident, a
  `confirm: true` sent without the `preview_token` does not fire the exit and does not complain — it
  hands back another preview. Take the preview, read `preview_token` out of it, and send the second
  call with both fields. Then read `will_execute`. The token is good for 60 seconds, which is the
  window this gate was sized for.
</Callout>

## Arguments [#arguments]

| Parameter       | Type    | Required | Notes                                                                                                            |
| --------------- | ------- | :------: | ---------------------------------------------------------------------------------------------------------------- |
| `venue`         | string  |    no    | Omit for every engine                                                                                            |
| `reason`        | string  |    no    | Rationale for the node's audit trail                                                                             |
| `confirm`       | boolean |    no    | Must be the JSON boolean `true` **and** be accompanied by `preview_token` — either one missing returns a preview |
| `preview_token` | string  |    no    | The token this tool's preview returned. Fires once, expires after 60s, bound to the command it previewed         |

Nothing is required. `market_exit_preview_allows_an_omitted_venue` pins that a call with an empty
argument object previews cleanly and produces a `MarketExit` wire command. `venue: None` is the
global exit across every engine; `Some(v)` scopes it to that venue's engine alone.

## It is a compound verb, expanded on the node [#it-is-a-compound-verb-expanded-on-the-node]

`OrderIntent::MarketExit` carries no state of its own and mints no orders directly. The runtime
expands it **at apply time** into the primitives that already exist:

1. one `MassCancel`, applied **first**;
2. then one `Flatten` per non-flat `BOTH`-side position, derived from the **post-cancel** account,
   in the account's own `(venue, symbol, position_side)` insertion order.

Hedge-mode `LONG`/`SHORT` rows are **skipped**. `Flatten` resolves its size at
`(venue, symbol, "BOTH")`, so a hedge leg would expand into a `Flatten` that resolves `0.0` and
no-ops. On an account whose venue reports only hedge buckets — binance perp's `positionSide`, OKX's
`posSide`, bybit's `positionIdx` — the mass-cancel still runs but the flatten half mints
**nothing**. Those venues need per-leg closing intents the primitive vocabulary does not carry yet.

Each leg is lowered through the *same* `apply_intent` site every other order takes, so mint →
`RiskGate` → client stays structural rather than being a special path for the emergency verb. A
flat, order-free book is a no-op beyond the mass-cancel.

## It works from a halted core [#it-works-from-a-halted-core]

<Callout title="No precondition — this is the reverse of what the verb documented for years">
  The `RiskGate` kill switch admits a position-covered reduce under `Halted`
  (`vike_model::is_covered_reduce`), which is exactly the shape a flatten leg mints: side opposite the
  position, quantity `|position|`. So the mass-cancel runs **and** every flatten leg is submitted,
  under `Active`, `Reducing` and `Halted` alike — though admission at that arm is all the covered
  shape buys: `RiskGate::check_inner`'s per-order notional and projected-exposure caps carry no
  covered-reduce bypass, so a leg over an armed `max_notional_per_order` or `max_total_exposure` is
  denied in any state. And one residual under `Halted` alone (`Reducing` trusts the flag): the gate
  re-takes its halt verdict against the **lot-rounded** size, so a position sitting off the lot grid
  (`|position| = 1.8` on a `1.0` lot) rounds its own leg up to `2.0`, which would flip the position,
  and that leg comes back `OrderDenied` with the reason `halted`. Every size this core mints is
  already lot-rounded, so reaching that residual takes an externally-sourced position — a venue
  liquidation, a reconcile fold. The runtime still logs a warning and a recent-events note when the
  exit runs under a halt — now saying it is *proceeding*.

  The gate used to deny every order under `Halted`, `reduce_only` included, so the panic button was
  disarmed in exactly the situations that reach `Halted` on their own — both dead-man's switches and
  the safe-state sweep halt — and an operator had to set the state back to active first, un-halting
  the strategy that got them there in order to escape it. A kill switch must stop you opening risk,
  never trap you in it.
</Callout>

## Best-effort, not atomic [#best-effort-not-atomic]

<Callout type="warn" title="A resting order can still fill after a flatten leg">
  Against a real venue the mass-cancel is fire-and-forget over the adapter's actor thread. Its
  acknowledgements land asynchronously, possibly **after** the flatten market orders are already on
  the wire. Ordering the legs is a local best effort, not a venue-side transaction.

  `OrderIntent::MarketExit`'s own instruction is the one to follow: &#x2A;*re-issue the exit if the board
  is not flat afterwards.** Read the board with
  [`node_snapshot`](/docs/ai/trader/tools/node_snapshot) rather than assuming the first exit finished the
  job.
</Callout>

## What the node does with it [#what-the-node-does-with-it]

`lower_command` maps `WireCommand::MarketExit` to the core intent with an **empty** coid — the
account-wide-verb convention, since there is no single order id to echo. `ControlLimits::vet`
consumes a rate token and applies no size cap: market-exit sits with cancel, flatten, mass-cancel
and trading-state among the risk-reducing verbs its doc says are never size-capped.

The preview's guardrail is `Guardrail::NoSize` for the same reason a flatten's is — there is no
order size on this side to check, and the orders this verb will produce do not exist yet. What the
preview *can* give you is the node's own dry-run (`node_verdict`, when there is a node to ask) and
the `preview_token` the confirming call has to carry;
[Live node](/docs/ai/trader/trading#what-the-token-is-and-what-it-is-not) sets out how that token
behaves.

## Outcomes [#outcomes]

`Server::execute` awaits this command's own ticket for two seconds. `accepted` returns
`sent: true` with an empty `client_order_id`; a refusal is an error result carrying the node's
reason; a timeout returns `outcome: "unknown"`; a dropped control connection is an error result
saying the outcome is unknown and it may have executed.

For this verb in particular, the ambiguous answers deserve the snapshot rather than a reflex retry
— though a second exit is the documented remedy for a board that is not flat, so the cost of
checking first is small and the cost of guessing is not.

## Related tools [#related-tools]

[`mass_cancel`](/docs/ai/trader/tools/mass_cancel) is the first half on its own — clear the orders,
leave the positions. [`flatten`](/docs/ai/trader/tools/flatten) is the second half for one book.
[`set_trading_state`](/docs/ai/trader/tools/set_trading_state) halts new risk without closing anything.
The gates each leg passes are described in
[Risk and arming](/docs/trader/concepts/risk-and-arming).

> Market exit everything on binance, right now — reason: feed outage.


# mass_cancel (/docs/ai/trader/tools/mass_cancel)



`mass_cancel` clears the order book without touching positions. It is the coarse companion to
[`cancel_order`](/docs/ai/trader/tools/cancel_order), and the first half of what
[`market_exit`](/docs/ai/trader/tools/market_exit) does. Annotated `destructiveHint: true`, it previews
unless a call carries **both** `confirm: true` **and** the `preview_token` its own preview
returned, and needs `vike-cli mcp --node <host:port>` plus `VIKE_TRADEHUB_CONTROL_KEY`.

## Arguments [#arguments]

| Parameter       | Type    | Required | Notes                                                                                                            |
| --------------- | ------- | :------: | ---------------------------------------------------------------------------------------------------------------- |
| `venue`         | string  |    no    | Omit for every venue                                                                                             |
| `symbol`        | string  |    no    | Omit for every symbol                                                                                            |
| `reason`        | string  |    no    | Rationale for the node's audit trail                                                                             |
| `confirm`       | boolean |    no    | Must be the JSON boolean `true` **and** be accompanied by `preview_token` — either one missing returns a preview |
| `preview_token` | string  |    no    | The token this tool's preview returned. Fires once, expires after 60s, bound to the command it previewed         |

Nothing is required. `mass_cancel_preview_allows_an_omitted_scope` pins that the empty argument
object previews cleanly and produces a `MassCancel` wire command with **both** `venue` and `symbol`
`null` — the whole account, shown as exactly that.

The preview also carries a &#x2A;*`preview_token`**, and clearing the book takes a second call with
**both** `confirm: true` **and** that token. `confirm: true` on its own is not an error and does
not cancel anything: it returns a fresh preview, which
`mass_cancel_confirm_without_a_token_is_a_preview_not_a_send` pins by name. Read `will_execute`
before believing the book is empty — or read it from
[`node_snapshot`](/docs/ai/trader/tools/node_snapshot), which is the real answer either way. The token's
rules — fires once, 60-second window, bound to this exact scope — are on
[Live node](/docs/ai/trader/trading#what-the-token-is-and-what-it-is-not).

## What each scope means [#what-each-scope-means]

`OrderIntent::MassCancel` is the authority, and it enumerates four combinations rather than three:

| `venue` | `symbol` | What happens                                                     |
| ------- | -------- | ---------------------------------------------------------------- |
| absent  | absent   | **all** engines, and all conditional books cleared               |
| present | present  | that engine, and that `(venue, symbol)` conditional book cleared |
| present | absent   | that engine, and that venue's conditional books cleared          |
| absent  | present  | **ignored**, surfaced to recent-events                           |

<Callout type="warn" title="A symbol with no venue cancels nothing">
  The fourth row is the one to carry. A `symbol` on its own does not mean "this symbol everywhere" —
  the intent is ignored, and the fact that it was ignored is surfaced to the node's recent-events
  rather than raised back to you as a refusal. The tool call itself succeeds, the node acknowledges
  the command, and no order is cancelled. Always name the `venue` when you name a `symbol`, and check
  [`node_snapshot`](/docs/ai/trader/tools/node_snapshot) if a scoped cancel appears to have done nothing.
</Callout>

## It clears armed conditionals too [#it-clears-armed-conditionals-too]

The scope table above is not only about resting venue orders. `MassCancel` is also the **coarse
verb** over the core-owned conditional book — the emulated stops and trailing orders a strategy
arms — and each scope clears the matching books as the table shows.
`OrderIntent::DisarmConditional` is the individual-cancel primitive that exists alongside it,
removing exactly one arm by the `arm_id` the runtime minted; `MassCancel` stays the blunt one. An
agent has no tool for the fine-grained disarm, so a mass cancel is how an emulated arm goes away
from this surface.

## What the node does with it [#what-the-node-does-with-it]

`lower_command` maps `WireCommand::MassCancel` to the core intent and echoes an **empty** coid —
the account-wide-verb convention, since there is no single order id to name. The accepted response
says as much in its own note.

`ControlLimits::vet` consumes a rate token, as it does for every command, and applies no size cap:
mass-cancel is listed with cancel, flatten, market-exit and trading-state among the risk-reducing
verbs its doc says are never size-capped. The preview's guardrail is correspondingly
`Guardrail::NoSize` — `within_limits: true`, with a note saying there is no order size to check for
this verb.

## Outcomes [#outcomes]

`Server::execute` awaits this command's own ticket for two seconds. `accepted` returns
`sent: true` with an empty `client_order_id`; a refusal is an error result carrying the node's
reason; a timeout returns `outcome: "unknown"`; a dropped control connection is an error result
saying the outcome is unknown and it may have executed. Both ambiguous cases end at
[`node_snapshot`](/docs/ai/trader/tools/node_snapshot) before a retry.

A repeat is cheap here — cancelling an already-empty book is nothing — but it still spends a rate
token, and the snapshot is the only thing that tells you whether the first one landed.

## Related tools [#related-tools]

[`cancel_order`](/docs/ai/trader/tools/cancel_order) withdraws one order by id.
[`market_exit`](/docs/ai/trader/tools/market_exit) runs a mass cancel and *then* flattens every one-way
position, in that order — hedge-mode `LONG`/`SHORT` legs are skipped.
[`flatten`](/docs/ai/trader/tools/flatten) closes one book's position without touching orders. What
happens to each cancelled order after the command lands is described in
[Order lifecycle](/docs/trader/concepts/order-lifecycle).

> Cancel all resting orders on okx — venue okx, no symbol scope.


# modify (/docs/ai/trader/tools/modify)



`modify` amends a resting order in place rather than cancelling and re-submitting it. Like every
write tool it is annotated `destructiveHint: true`, previews unless a call carries **both**
`confirm: true` **and** the `preview_token` its own preview returned, and needs
`vike-cli mcp --node <host:port>` plus `VIKE_TRADEHUB_CONTROL_KEY`.

## Arguments [#arguments]

| Parameter         | Type    | Required | Notes                                                                                                            |
| ----------------- | ------- | :------: | ---------------------------------------------------------------------------------------------------------------- |
| `client_order_id` | string  |    yes   | The order to amend                                                                                               |
| `new_qty`         | number  |    no    | New quantity — but see below for what that *means*                                                               |
| `new_price`       | number  |    no    | New price                                                                                                        |
| `reason`          | string  |    no    | Rationale for the node's audit trail                                                                             |
| `confirm`         | boolean |    no    | Must be the JSON boolean `true` **and** be accompanied by `preview_token` — either one missing returns a preview |
| `preview_token`   | string  |    no    | The token this tool's preview returned. Fires once, expires after 60s, bound to the command it previewed         |

At least one of `new_qty` / `new_price` is required. `verbs::verb_from_tool_args` refuses a modify
that changes nothing, mirroring the REPL's rule — a modify that changes nothing is an authoring
mistake, not a command — and `modify_with_nothing_to_change_is_a_tool_error` pins that the error
text names `new_qty` so the agent can act on it.

## The preview [#the-preview]

`modify_without_confirm_only_previews_the_shared_wire_command` is the pin for the whole path: a
call with `client_order_id: "c-1"` and `new_qty: 2.0` succeeds with no node configured, returns
`will_execute: false`, and shows a `wire_command` whose `Modify` carries `c-1`, `new_qty` `2.0` and
`new_price` `null`. Its guardrail reports `within_limits: true` — this verb has no order size for
the *client-side* check to look at.

That is exactly the same `WireCommand::Modify` the human REPL's `modify c-1 --qty 2` builds. Both
surfaces resolve through `verbs`' one construction site, `Verb::to_wire_command` — the tool path
reaching it via `wire_command_for` — which is why an agent and an operator issue the same command.

The preview also hands back a &#x2A;*`preview_token`**, and a call that actually amends the order must
carry **both** `confirm: true` **and** that token. Either one alone returns another preview rather
than an error, so `will_execute` is what tells you which call you just made. The token fires once,
expires after 60 seconds, and is bound to *this* modify — confirming a differently-sized amend with
it is refused, and consumes it.
[Live node](/docs/ai/trader/trading#what-the-token-is-and-what-it-is-not) is the full rule set.

<Callout type="warn" title="A re-priced amend needs a re-preview">
  The binding compares the whole wire command, so changing your mind about `new_price` between the
  preview and the confirm invalidates the token you were holding — deliberately. Preview the amend
  you actually intend to send, then confirm with *that* token.
</Callout>

## Under a notional ceiling, the node refuses a quantity raise with no price [#under-a-notional-ceiling-the-node-refuses-a-quantity-raise-with-no-price]

<Callout type="warn" title="Name a price whenever you change quantity">
  `ControlLimits::notional_reason` has a dedicated arm for a modify naming `new_qty` and **no**
  `new_price`: on a node whose `policy.toml` sets `max_notional_per_order`, it is refused, with a
  message naming that ceiling and telling you to re-send with an explicit price. A node with no
  ceiling set never reaches the arm — the check returns early with nothing to enforce. The reason is
  stated where the code performs it — this edge holds no order registry and no book, so it cannot
  resolve the resting price needed to size the projected order, and "I cannot evaluate this ceiling"
  must never render as "the ceiling passed". The shape used to fall through as "no price to size,
  therefore fine", which let a small in-cap order be placed and then modified straight past the
  node's one order-size ceiling.
</Callout>

A modify naming both a quantity and a price **is** size-checked, against
`|new_qty| × |new_price|` — magnitudes on both factors — and refused above the node's ceiling. A
modify naming only a price projects no quantity and matches none of the sizing arms, so it is not
notional-checked at this edge; the core `RiskGate` resolves the resting order's terms and is the
enforcing gate regardless. Every modify, whatever it names, still spends a rate token in
`ControlLimits::vet`.

## What the quantity means is a per-venue fact [#what-the-quantity-means-is-a-per-venue-fact]

`vike_model::venue_amend` exists to answer one question: &#x2A;what does an amend's quantity mean?*
Three conventions exist, and they disagree about how much more the order can still execute.

| Convention         | The order                                            | How much more can execute                              |
| ------------------ | ---------------------------------------------------- | ------------------------------------------------------ |
| `InPlaceTotal`     | survives, executions stay attached                   | `new_qty − filled_qty`                                 |
| `CancelReplace`    | dies; a fresh order rests                            | the whole `new_qty`, on top of what the dead order did |
| `InPlaceRemaining` | survives; the number replaces its *outstanding* size | the whole `new_qty`                                    |

Only `InPlaceTotal` changes any pre-trade verdict — `already_in_position` returns a non-zero value
for that variant and `0.0` for every other, including the two `AmendSemantics` variants that
declare no convention at all: `Unsupported`, where the venue has no native amend for a convention
to describe, and `Unknown`, the value an unrecognised venue string resolves to. The asymmetry is
the safety argument: the arithmetic errs conservative, so it can wrongly deny an amend and can
never wrongly admit one.

<Callout type="warn" title="A paper mount is not a made-up venue string">
  It is tempting to assume a paper mount runs under `sim` or `paper` and falls into the conservative
  fallback for free. It does not: `vike_mount::make_engine` builds the engine with the **real** venue
  string even when the absent-credentials gate fell back to the paper client. The paper book
  implements the third convention — its `modify` assigns the amend's quantity as the size that can
  still fill — so it declares `InPlaceRemaining` through the client rather than through the venue
  table.
</Callout>

## Outcomes [#outcomes]

`lower_command` maps `WireCommand::Modify` to the core's `OrderIntent::Modify` and echoes the
`client_order_id`, since this is an order-scoped verb. `Server::execute` then awaits that
command's own ticket for two seconds: `accepted` with the echoed id, an error result carrying the
node's refusal, `outcome: "unknown"` on a timeout, or an error result naming the outcome unknown
when the control connection dropped. Both ambiguous cases mean the same thing — call
[`node_snapshot`](/docs/ai/trader/tools/node_snapshot) before you retry, because a re-sent modify is not
idempotent the way a re-sent submit is.

If the amend is large enough to be a different order, consider
[`cancel_order`](/docs/ai/trader/tools/cancel_order) plus a fresh
[`submit_order`](/docs/ai/trader/tools/submit_order) instead; the states involved are described in
[Order lifecycle](/docs/trader/concepts/order-lifecycle).

> Move my resting bid to 59,800 and cut the size to 0.2 — name the price, it is a qty change.


# node_snapshot (/docs/ai/trader/tools/node_snapshot)



`node_snapshot` reads the live state of a running `vike-tradehub` node. It is the only read-only
tool in `vike-cli mcp` that talks to a node rather than to a datahub, annotated
`readOnlyHint: true` and `openWorldHint: true` in `tools/list`
(`crates/vike-cli/src/cmd/mcp.rs`'s `tools_spec`). It needs `--node <host:port>` and
`VIKE_TRADEHUB_OBSERVE_KEY` — the *observe* key, not the control key
(`crates/vike-cli/src/cmd/nodekeys.rs`'s `OBSERVE_KEY_ENV`).

## Input schema [#input-schema]

It takes no arguments: `"inputSchema": { "type": "object", "properties": {} }`. It is also the one
node tool with no `reason` property — a read has no rationale to file, and the tools/list test in
`crates/vike-cli/src/cmd/mcp.rs` asserts the property is absent.

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"node_snapshot","arguments":{}}}
```

## What comes back [#what-comes-back]

`Server::tool_node_snapshot` serializes the node's `WireSnapshot` as-is — "already a flat, serde
projection". The schema is `crates/vike-tradehub-client/src/wire.rs`'s `WireSnapshot`, a standalone
mirror of the core's rendered snapshot rather than the core type itself, so an internal refactor
cannot silently change what an agent reads:

| Field             | What it holds                                                                                                                                                           |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `seq`             | per-publish sequence number; `0` means no real frame has arrived yet                                                                                                    |
| `venue`, `symbol` | the primary engine's mount                                                                                                                                              |
| `trading_state`   | `Active`, `Reducing` or `Halted` for the primary engine                                                                                                                 |
| `balance`         | the primary venue's cash balance                                                                                                                                        |
| `equity_total`    | cross-venue total equity                                                                                                                                                |
| `venues`          | per-venue ledger blocks — balance, realized PnL, fees, funding, equity, unrealized, margin used, free buying power, that venue's own `trading_state`, and its positions |
| `orders`          | the order registry in insertion order, spanning **every** engine; `status` is the rendered string                                                                       |
| `positions`       | the primary venue's positions — the documented mirror of `venues[0].positions`                                                                                          |
| `held_exits`      | pending bracket exits held off the venue until their OTO parent fills; empty on non-bracket runs                                                                        |
| `recent_events`   | the bounded delivered-event tail, already rendered to lines                                                                                                             |
| `fault`           | set once a handler panicked — the core is halted in safe state                                                                                                          |
| `bars`            | bounded OHLCV tails for the chart                                                                                                                                       |
| `identity`        | which daemon, which strategy, paper or live, which build                                                                                                                |

`bars` and `identity` are `#[serde(default)]`, so a node that predates either field simply omits it.

Two bounds are applied node-side, in `crates/vike-tradehub/src/publish.rs`'s `project`. `bars` is
filtered to the **primary** `(venue, symbol)` only and tail-sliced to `CHART_BARS_CAP` closed bars
plus the forming candle — the core's own bar vector is unbounded and would eventually overflow the
framer. `recent_events` is the core's own bounded ring.

## How fresh it is, and what it is not [#how-fresh-it-is-and-what-it-is-not]

The observe connection is opened lazily on the first call and then **kept open** — it stays
subscribed so the node keeps pushing frames, which is why the MCP server holds persistent
connections rather than dialling per call. A freshly-subscribed connection answers with
`WireSnapshot::empty` (`seq: 0`) until the first frame lands, so `tool_node_snapshot` polls every
50 ms for up to about two seconds for a real one before returning.

<Callout type="warn" title="The observer is lossy by contract">
  You get the latest published state, never every intermediate one. The node's publisher samples the
  core's arc-swap cell on a `POLL_INTERVAL` of 15 ms against a core that publishes coalesced at 16 ms
  or slower, and each subscriber's mailbox is a bounded `MAILBOX_CAP` drop-**oldest** queue, so a slow
  reader loses old frames rather than back-pressuring the publisher
  (`crates/vike-tradehub/src/publish.rs`). Never treat two consecutive snapshots as a complete event
  history — `recent_events` is a tail, not a ledger.
</Callout>

Nothing here touches the core's hot fold. The publisher's only interaction with the core is one
atomic load of the already-published snapshot, on its own thread; reading a snapshot cannot slow the
node down.

## Its other job: settling an ambiguous write [#its-other-job-settling-an-ambiguous-write]

Every write tool points here when it cannot answer. `Server::execute` waits `ACK_WAIT` — two
seconds — for the node's verdict on the command it just sent, and two of the four outcomes are
genuinely unknown rather than failed: a timeout returns `outcome: "unknown"`, and a dropped control
connection returns an error saying the outcome is unknown and the command *may have executed*. Both
say the same thing: call `node_snapshot` **before** retrying, because retrying blind is how one
intent becomes two orders. Acceptance is the same story from the other side — it means the node took
the command, not that the order filled.

## When it errors [#when-it-errors]

Both failures are clean tool errors, never panics.

* **No node configured** — `ensure_observe` returns `no vike-tradehub node configured — pass --node`
  before any network work happens; `node_snapshot_without_node_is_a_clean_error` pins it.
* **No observe key** — the error names *both* places the key is looked for, the process environment
  and the credential store, and points at `vike-cli secrets path` and `vike-cli secrets list`. The
  message says both because it once said only "not set in the environment" while the daemon's own
  keys sat unread in the store.

A non-null `fault` is not a tool error but is the most important thing in the payload: the core
entered safe state, which halts every engine and sweeps its working orders
(`crates/vike-core/src/runtime/watchdog.rs`'s `enter_safe_state`).

Concepts: [Portfolio and snapshot](/docs/trader/concepts/portfolio-and-snapshot),
[The node protocol](/docs/trader/concepts/node-protocol). Tools:
[`set_trading_state`](/docs/ai/trader/tools/set_trading_state),
[`market_exit`](/docs/ai/trader/tools/market_exit).

> Show me the node snapshot — what is open, where is the equity, and is anything faulted?


# run_backtest (/docs/ai/trader/tools/run_backtest)



Runs one backtest on the remote `vike-datahub` server named by `--addr` and returns the
`BacktestReport` JSON. Read-only in the MCP sense — a backtest mutates nothing — and annotated
`readOnlyHint: true` in `tools_spec()`.

## Input [#input]

| Field     | Type   | Required | Meaning                                                              |
| --------- | ------ | :------: | -------------------------------------------------------------------- |
| `profile` | string |    yes   | A backtest profile TOML: `[data]`, `[strategy]`, optional `[engine]` |
| `script`  | string |    no    | Rhai source, injected as `[strategy.params].src`                     |

`tool_run_backtest` reads `profile`, and a missing one is a tool error before anything connects.
With `script` present it rewrites the profile through
`crate::cmd::backtest::inject_script_src`: the profile is parsed as a `toml::Value` (a malformed
one is a clean error, not a panic), `[strategy]` and `[strategy.params]` are created if absent,
and `src` is set — existing params, the numeric knobs a `[sweep]` varies, are preserved, and any
pre-existing inline `src` is overwritten.

<Callout type="warn" title="An injected script only runs if strategy.name is rhai">
  `src` is read by exactly one arm of `vike_backtest::harness::registry`'s `strategy_by_name` — the
  `"rhai"` arm, which is deliberately absent from the `STRATEGIES` roster because it is not
  resolvable with default params. Inject a script under `name = "buy_hold"` and the script is
  carried along as an unread param while the built-in strategy runs.
</Callout>

## A call [#a-call]

The transport is newline-delimited JSON-RPC 2.0 — one message per line, no embedded newlines — so
each of these goes on the wire as a single line.

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"run_backtest","arguments":{
  "profile": "[data]\nvenue = \"binance\"\nsymbols = [\"BTCUSDT\"]\nkind = \"bar\"\ninterval = \"1d\"\nfrom = \"2024-01-01T00\"\nto = \"2024-06-01T00\"\n\n[strategy]\nname = \"buy_hold\"\n"
}}}
```

The profile crosses the wire **verbatim**. The server's own `BacktestProfile::from_toml_str` is
the only parser in the loop, so a profile-shape error — a bad range, an unknown `strategy.name`, a
`[data]` table naming a series the store does not hold — arrives from the server as
`profile parse/validate failed: …` and reaches the agent as an `isError` result. One parser, one
error source. [Run profiles](/docs/trader/backtesting/run-profiles) documents the file itself.

## What comes back [#what-comes-back]

`{ "report": … }`, wrapping the `BacktestReport` exactly as the server serialized it. Its fields
are fixed by `vike_analytics::report::BacktestReport`; the numbers are your run's.

| Field                   | Meaning                                                                                                                                                       |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                  | the profile's free-form `name`, or `null`                                                                                                                     |
| `final_equity`          | closing equity                                                                                                                                                |
| `total_return`          | fractional return from the first to the last equity-curve point                                                                                               |
| `n_trades` · `win_rate` | trade count, and the fraction with positive PnL                                                                                                               |
| `sharpe`                | annualized Sharpe of per-bar returns; 252 for daily bars                                                                                                      |
| `max_drawdown`          | largest peak-to-trough drop, a positive fraction of the peak                                                                                                  |
| `profit_factor`         | gross profit over gross loss — **`null` when non-finite**, so a run with no losing trades but some profit reads as "no meaningful ratio" rather than a number |
| `funding_paid`          | net perp funding cashflow, received-positive; `0.0` for a spot run                                                                                            |
| `per_symbol_pnl`        | multi-symbol event runs only; empty otherwise                                                                                                                 |
| `zero_trade`            | present **only** when the run closed no trades *and* equity never moved — a ranked list of probable causes, not an empty stats block                          |

That last field is the one worth reading first on a disappointing run: `ZeroTradeReport::analyze`
composes it from diagnostic counters the run already carried, so "why did nothing happen" has an
answer instead of a table of zeros. [The report](/docs/trader/analytics/report) and
[metrics](/docs/trader/analytics/metrics) define every number.

<Callout type="warn" title="A keyed datahub refuses this tool at connect">
  Every `Run*` verb is **control** scope on the server, because it compiles client-supplied Rhai —
  `vike_datahub::server`'s `required_scope` says so, and calls that a design decision rather than an
  oversight. The MCP server connects with `DatahubClient::connect`, which against a datahub
  advertising the `auth` feature fails immediately with an actionable message rather than connecting
  and having every verb refused a round trip later. Against a key-less datahub — the default, and
  the usual localhost or SSH-tunnelled shape — nothing changes.
</Callout>

An unreachable server is likewise a clean tool error, never a panic: `tool_run_backtest` maps the
connect failure to `cannot connect to datahub at …`. The pin that drives that shape,
`remote_run_tools_without_a_reachable_datahub_are_clean_errors`, points at the sibling run tools —
`run_sweep`, `run_walk_forward` and `list_series` — rather than at this one.

## The prompt [#the-prompt]

> Backtest this script on BTCUSDT daily bars for the first half of 2024 and tell me whether it
> traded at all.

Pair it with [`validate_strategy`](/docs/ai/trader/tools/validate_strategy) before the run and
[`run_walk_forward`](/docs/ai/trader/tools/run_walk_forward) after it. The human twin of this tool is
[`vike-cli backtest`](/docs/trader/reference/cli/research/backtest), which ships the same TOML over the same
verb.


# run_sweep (/docs/ai/trader/tools/run_sweep)



Runs a parameter-grid sweep on the remote `vike-datahub` server and returns the ranked
`SweepReport`. Same input as [`run_backtest`](/docs/ai/trader/tools/run_backtest) — a profile TOML,
optionally with a Rhai script injected — plus one grid table and one ranking knob.

## Input [#input]

| Field     | Type   | Required | Meaning                                                                           |
| --------- | ------ | :------: | --------------------------------------------------------------------------------- |
| `profile` | string |    yes   | Profile TOML with `[data]`, `[strategy]` and `[sweep]` (plus optional `[engine]`) |
| `script`  | string |    no    | Rhai source, injected as `[strategy.params].src`                                  |
| `rank_by` | string |    no    | `sharpe` (default), `return`, `max_dd` or `equity` — applied server-side          |

The `[sweep]` table is the whole grid: each key names a `strategy.params` field and each value is
an array to cross-product over. `expand_sweep` turns the profile into that cartesian product of
single-run profiles, each with its params overridden per point and its own `sweep` field cleared —
so every expanded point is itself a plain, runnable single-backtest profile. A profile with no
`[sweep]` table comes back as a server-side error that quotes the fix.

```json
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"run_sweep","arguments":{
  "profile": "[data]\nvenue = \"binance\"\nsymbols = [\"BTCUSDT\"]\nkind = \"bar\"\nfrom = \"0\"\nto = \"100000\"\n\n[strategy]\nname = \"buy_hold\"\n\n[sweep]\nfast = [5, 10]\n",
  "rank_by": "sharpe"
}}}
```

`run_tools_reject_a_missing_profile_arg_before_any_connect` pins the local half: a missing
`profile`, or a `script` injection into unparsable TOML, errors before a socket is opened.
Everything else is the server's answer, because the TOML ships verbatim and
`BacktestProfile::from_toml_str` is the only parser.

## Ranking happens on the server [#ranking-happens-on-the-server]

`rank_by` is resolved by the canonical `harness::RankMetric::from_str_ci`. An unrecognized value is
a clean error naming the valid set — never a silent fallback to the default — and an omitted one
ranks by Sharpe, matching the shipped `backtest` bin. Direction is folded in: `sharpe`, `return`
and `equity` sort descending, `max_dd` ascending, because a smaller drawdown is better. A NaN key
— a Sharpe over a zero-variance curve, say — sorts last among the successes, so a degenerate point
can never rank first, and rows whose run failed always sort behind every success.

No client re-implements a metric. The ranking runs over real `BacktestReport`s with the canonical
comparator, which is the same rule that took sharpe and max-drawdown out of the `vike-cli sweep`
verb: nothing outside `vike-backtest` computes them.

## What comes back [#what-comes-back]

`{ "sweep": … }` wrapping a `SweepReport`: `rows` plus the `rank_by` it was ranked under. Each
`SweepRow` carries

* `overrides` — the `(key, value)` pairs that produced this point,
* `report` **or** `error` — never both; a point that failed records its error string and is not
  dropped,
* `score` — stamped only by the objective path, and skipped on serialization otherwise, so a
  default sweep's JSON is unchanged by the seam's existence.

Read the head of `rows` as the winner and the tail for what broke.
[Sweeps](/docs/trader/backtesting/sweeps) documents the expansion,
[objectives](/docs/trader/backtesting/objectives) the pluggable scalar the `score` field belongs to,
and [search](/docs/trader/backtesting/search) the successive-halving and TPE lanes that fold through
the same per-point plumbing.

## Determinism, and the memory shape [#determinism-and-the-memory-shape]

Points run on a rayon pool, and the ordering does not depend on scheduling: the collect is
order-preserving and the ranking sort is stable over that input, so a parallel sweep's bytes equal
the one-at-a-time loop's — `parallel_and_sequential_sweeps_are_byte_identical` is the pin.

<Callout type="warn" title="Parallelism multiplies the data slice, not just the CPU">
  The shared store handle is shared; the **data** is not. Every point independently re-scans and
  fully materializes its own slice, so peak memory and store I/O are `N_threads x slice`. The pool
  is therefore bounded rather than one worker per core — `min(4, available_parallelism())` by
  default, raised by `VIKE_SWEEP_THREADS` on the server, and pinned back to one at a time by
  `VIKE_SWEEP_SEQUENTIAL=1`. On a large recorded tick slice an uncapped sweep is an OOM shape, and
  these sweeps often run on a box that also hosts live trading. Size the multiplier against the
  slice, not against the core count.
</Callout>

The keyed-datahub and unreachable-server behaviour is identical to
[`run_backtest`](/docs/ai/trader/tools/run_backtest)'s: every `Run*` verb is control scope because it
compiles client-supplied Rhai, and a connect failure is a clean tool error.

## The prompt [#the-prompt]

> Sweep `fast` over 5, 10 and 20 against `slow` over 50 and 100, rank by Sharpe, and show me the
> top three rows with their parameters.

A grid returns its best row whether or not the edge survives out of sample — follow it with
[`run_walk_forward`](/docs/ai/trader/tools/run_walk_forward). The human twin is
[`vike-cli sweep`](/docs/trader/reference/cli/sweep); the guide is [Run a sweep on the data
service](/docs/trader/guides/sweep-on-the-service).


# run_walk_forward (/docs/ai/trader/tools/run_walk_forward)



Runs an anchored out-of-sample walk-forward on the remote `vike-datahub` server and returns the
stitched `WalkForwardReport`. This is the tool that asks whether a sweep's winner was an edge or a
fit: a grid search returns its best row either way.

## Input [#input]

| Field     | Type   | Required | Meaning                                                                                 |
| --------- | ------ | :------: | --------------------------------------------------------------------------------------- |
| `profile` | string |    yes   | Profile TOML with `[data]`, `[strategy]` and `[walkforward]` (plus optional `[engine]`) |
| `script`  | string |    no    | Rhai source, injected as `[strategy.params].src`                                        |

There is no split-count argument. The count rides **in** the profile, as `[walkforward].n_splits`,
a first-class section like `[sweep]` — so one file describes the whole run and the same text can
be shipped verbatim to a remote runner, which is the point of the compute-to-data verb. A profile
with no `[walkforward]` table is a clean server-side error that quotes the two lines to add;
`n_splits` must be at least 1, and `BacktestProfile::validate` rejects `0` at load.

Only the split count is configurable, deliberately: the mode is always `WalkMode::Anchored` and
the annualization is derived by `periods_per_year`. Those are the same two derivations the
Studio's walk-forward makes, so a profile cannot disagree with the Studio about what
"walk-forward" means.

```json
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"run_walk_forward","arguments":{
  "profile": "[data]\nvenue = \"binance\"\nsymbols = [\"BTCUSDT\"]\nkind = \"bar\"\ninterval = \"1d\"\nfrom = \"2023-01-01T00\"\nto = \"2024-06-01T00\"\n\n[strategy]\nname = \"buy_hold\"\n\n[walkforward]\nn_splits = 4\n"
}}}
```

## Bar mode, one series, by construction [#bar-mode-one-series-by-construction]

`walk_forward_strategy` splits a single `&[Bar]` series by index, so a tick-mode or multi-symbol
profile is a clean validation error — never a silent fall back to the first symbol. Every
precondition is checked *before* the window loop, because the loop's closure cannot return one.

What the profile route buys over the Studio's DTO-shaped walk-forward is the whole `[engine]`
surface: the fee **schedule**, `[engine.impact]`, `[engine.resolution]`, `[risk]`,
`snap_to_properties`, `attach_funding` — instead of the three flat `cash`/`fee_rate`/`slippage`
scalars a wire DTO can carry. The strategy resolves through the same `strategy_by_name` registry a
plain run uses — once up front as a pre-flight, so a bad name fails before the window loop, then
rebuilt inside the closure because each window needs a fresh strategy — the bars are loaded
through the same helpers, and each window is a fresh run at `engine.cash`, so a walk-forward can
never disagree with a single backtest about what the profile's `[engine]` meant.

## What comes back [#what-comes-back]

`{ "walkforward": … }` wrapping a `WalkForwardReport`:

| Field              | Meaning                                                                                              |
| ------------------ | ---------------------------------------------------------------------------------------------------- |
| `windows`          | one entry per OOS window: `test_range` as `(start, end)` bar indices, and that window's `oos_return` |
| `oos_equity_curve` | every window's curve rebased onto one running equity                                                 |
| `oos_return`       | the stitched fractional return over the whole walk                                                   |
| `oos_sharpe`       | Sharpe of the stitched curve, under the derived annualization                                        |
| `wf_consistency`   | the fraction of windows that were profitable out of sample                                           |

The stitch is what makes the curve readable as one line: each window runs fresh at `engine.cash`,
and its curve is rebased onto the running equity that the previous window ended at. So
`oos_return` compounds the windows rather than averaging them, and `wf_consistency` answers the
different question — how many windows worked, not how much they made. A strategy with one
enormous window and three losing ones has a good `oos_return` and a `wf_consistency` of 0.25, and
the second number is the one that should stop you.

<Callout title="Read wf_consistency as the overfitting input, not as a score">
  It is the input the overfitting verdict consumes, not a verdict itself. The anti-overfitting
  statistics live in [`analytics/overfitting`](/docs/trader/analytics/overfitting); walk-forward
  supplies them with honest out-of-sample windows.
</Callout>

## Failure modes [#failure-modes]

Identical to the other two run tools. The profile ships verbatim, so a shape error surfaces from
the server as `profile parse/validate failed: …` and arrives as an `isError` result; an
unreachable datahub is `cannot connect to datahub at …` and never a panic
(`remote_run_tools_without_a_reachable_datahub_are_clean_errors`); and every `Run*` verb is
control scope on the server because it compiles client-supplied Rhai, so a keyed datahub refuses
this tool at connect rather than one round trip later.

## The prompt [#the-prompt]

> Walk this strategy forward over four anchored splits and tell me whether the edge holds out of
> sample.

The natural order is [`run_sweep`](/docs/ai/trader/tools/run_sweep) to find a candidate, then this to
test it. [Walk-forward](/docs/trader/backtesting/walk-forward) is the concept page,
[`vike-cli walkforward`](/docs/trader/reference/cli/walkforward) the human twin, and [Sweep and
walk-forward](/docs/trader/tutorials/sweep-and-walk-forward) the worked run.


# set_trading_state (/docs/ai/trader/tools/set_trading_state)



`set_trading_state` sets the account trading state on a running `vike-tradehub` node. It is one of
the seven order-write tools `vike-cli mcp` exposes, annotated `destructiveHint` in `tools/list`, and
it needs `--node <host:port>` plus `VIKE_TRADEHUB_CONTROL_KEY` — taken from the process environment
first, then from the credential store the daemon itself reads
(`crates/vike-cli/src/cmd/mcp.rs`'s module header; `crates/vike-cli/src/cmd/nodekeys.rs`'s
`CONTROL_KEY_ENV`).

<Callout type="warn" title="It is the kill switch, and it is not a venue arming control">
  The tool's own description says both halves, and it says them because an agent reached for this
  tool to put a venue live. It moves an already-mounted account between `active`, `reducing` and
  `halted`; it cannot move a venue off the paper simulator, and neither can any other tool on this
  server. Which venues may go live is `policy.venues.<venue>` under `[venues]` in
  `<project>/settings/policy.toml`, read *above* the credential read by
  `crates/vike-mount/src/lib.rs`'s `make_engine` and only ever able to refuse
  (`crates/vike-config/src/venue_mode.rs`'s `VenueMode::cap` is a minimum, never a maximum). It is a
  file a human edits on the box, and nothing reachable from here can write it. The remedy an agent
  invents when it does not know that — "set it in the node's environment and restart" — arms nothing
  and leaves the operator on paper with no error. [Arm one venue](/docs/trader/guides/arm-a-venue) and
  [`policy.toml`](/docs/trader/reference/settings/policy) are the pages that do answer it.
</Callout>

## Input schema [#input-schema]

| Parameter       | Type    | Required | Notes                                                                                                            |
| --------------- | ------- | :------: | ---------------------------------------------------------------------------------------------------------------- |
| `state`         | string  |    yes   | `active`, `reducing` or `halted` — lower case. Anything else is a tool error naming the three                    |
| `reason`        | string  |    no    | The rationale recorded in the node's audit trail                                                                 |
| `confirm`       | boolean |    no    | Must be the JSON boolean `true` **and** be accompanied by `preview_token` — either one missing returns a preview |
| `preview_token` | string  |    no    | The token this tool's preview returned. Fires once, expires after 60s, bound to the command it previewed         |

The three spellings are the whole vocabulary: `crates/vike-cli/src/cmd/verbs.rs`'s
`verb_from_tool_args` matches `"active"` / `"reducing"` / `"halted"` and returns
`unknown state {other:?} (active | reducing | halted)` for everything else.

## What each state means [#what-each-state-means]

The states are a strict ladder — `Halted` admits less than `Reducing`, which admits less than
`Active` — enforced in the risk gate, not in this tool.
`crates/vike-exec/src/risk.rs`'s `TradingState` is the definition and `RiskGate`'s `check` is where
each one bites:

* **`active`** — normal trading.
* **`reducing`** — "only position-reducing orders allowed". An order that does not reduce is denied
  with the reason `reduce-only`.
* **`halted`** — "no new orders (kill switch)". Denied with `halted`, with one deliberate exception:
  a *position-covered* reduce (`vike_model::is_covered_reduce` — side opposite the position, size
  within it) is still admitted, so a halt stops you opening risk without trapping you in it.

## A call, and what comes back [#a-call-and-what-comes-back]

The transport is newline-delimited JSON-RPC 2.0 on stdin/stdout (`crates/vike-cli/src/cmd/mcp.rs`
hand-rolls it — no SDK). One line in, one line out:

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"set_trading_state","arguments":{"state":"halted","reason":"feed gap on the primary venue"}}}
```

With no `confirm`, nothing is sent. `Server::call_tool`'s write arm returns `preview_of(...)`,
whose `structuredContent` looks like this — the values below are from a server with **no** node
configured, which is why the verdict is absent:

```json
{
  "will_execute": false,
  "tool": "set_trading_state",
  "wire_command": { "SetTradingState": "Halted" },
  "guardrail": { "within_limits": true, "note": "no order size to check for this verb" },
  "node_verdict": null,
  "verified_by_node": false,
  "preview_token": "pv-1",
  "reason": "feed gap on the primary venue",
  "note": "PREVIEW ONLY — nothing was sent. ..."
}
```

`wire_command` is pinned by `set_trading_state_preview_maps_the_wire_command` in the same file. The
guardrail cell is `Guardrail::NoSize`: `verbs::guardrail_check` only sizes a `Submit`, so every
other verb reports trivially within limits. `node_verdict` is the node's own dry-run and is `null`
here only because there was no node address or control key to ask with; the `note` spells out the
confirm rule, names the node's own gates as the enforcing ones, and — on this unverified path —
says in words that the guardrail is a client-side estimate rather than an approval.

**To execute, send the same arguments again with both `"confirm": true` and that
`"preview_token"`.** Either field alone returns a fresh preview and moves nothing, which is not an
error and is easy to mistake for success — read `will_execute`. The token fires once, expires after
60 seconds, and is bound to this exact command, so a preview of `halted` cannot be used to confirm
`active`; [Live node](/docs/ai/trader/trading#what-the-token-is-and-what-it-is-not) is the full rule
set.

```json
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"set_trading_state","arguments":{"state":"halted","reason":"feed gap on the primary venue","confirm":true,"preview_token":"pv-1"}}}
```

`Server::execute` awaits the ticket that send returned
and answers for *that* command — `outcome: "accepted"` with an empty `client_order_id` (this is an
account-wide verb), `isError` on a refusal, or `outcome: "unknown"` after the two-second `ACK_WAIT`
deadline, in which case the command may still execute and
[`node_snapshot`](/docs/ai/trader/tools/node_snapshot) is what settles it.

## Scope: every engine, not one venue [#scope-every-engine-not-one-venue]

`crates/vike-core/src/runtime/mod.rs`'s `Command::SetTradingState` arm writes the primary engine's
`trading_state` and then every extra engine's. One call moves the whole node, which is why the
accepted response carries no client order id.

It is also never size-capped. `crates/vike-tradehub/src/server.rs`'s `ControlLimits::vet` consumes a
rate token on every command, but its notional ceiling applies only to the order-increasing verbs
that carry a price; cancel, flatten, mass-cancel, market-exit and set-trading-state are
risk-reducing and exempt by construction.

<Callout type="warn" title="You do not need `active` to escape a halt">
  `market_exit` and its mass-cancel are usable from a halted core with no precondition — the covered
  reduce a flatten mints is exactly the shape the gate admits under `Halted`
  (`crates/vike-exec/src/lanes.rs`'s `MarketExit`), with one residual: the gate re-takes that
  verdict against the **lot-rounded** size, so a position sitting off the lot grid rounds its own leg
  up past itself and that leg alone comes back denied with the reason `halted`. This is the reverse
  of the rule that held for the verb's whole life: the gate used to deny every order under `Halted`,
  so an operator had to un-halt first, re-arming the strategy that caused the halt in order to escape
  it. Reach for [`market_exit`](/docs/ai/trader/tools/market_exit), not for `set_trading_state active`.
</Callout>

<Callout type="warn" title="`active` does not clear the HALT file">
  The file sentinel (`crates/vike-bridge-core/src/halt.rs`) is a *separate*, cross-process kill switch
  checked at the `ExecActor` submit boundary, and it exists precisely to work when the runtime is
  wedged. Setting the trading state back to `active` does not remove it. Either dead-man's switch
  under the default `cancel_all_and_halt` action engages both at once — the silence one
  (`crates/vike-core/src/runtime/deadman.rs`) and the connection one
  (`crates/vike-core/src/runtime/link_deadman.rs`), which is armed unless `policy.toml` writes
  `link_deadman_grace_ms = 0` — so clearing one leaves the other armed, and on a mount where the
  connection switch arms this file can appear with no operator having touched anything.
</Callout>

<Callout title="Re-arming a latched drawdown">
  The optional drawdown latch sets every engine to `Reducing` and never un-latches itself. A manual
  `set_trading_state active` re-arms it against the *same running high-water mark*, so a still
  underwater account latches again on the next closed-bar sweep —
  `CoreThread::sweep_drawdown_latch` in `crates/vike-core/src/runtime/watchdog.rs` states the rule.
</Callout>

## What is recorded, and how to see the result [#what-is-recorded-and-how-to-see-the-result]

An accepted command is recorded under the kind `set_trading_state` with an empty coid
(`crates/vike-tradehub/src/audit.rs`'s `record`). Any `reason` is trimmed client-side, sanitized
server-side by `sanitize_reason` — control characters stripped, capped at `MAX_REASON_CHARS` — and
never reaches the order, the core fold, the journal or a venue.

The result is visible in the node's snapshot: `trading_state` at the top level and
`venues[].trading_state` per venue. Concepts: [Halt](/docs/trader/concepts/halt),
[Risk and arming](/docs/trader/concepts/risk-and-arming).

> Halt trading on the node — reason: the primary feed has gone quiet and I want to look before
> anything else goes out.


# submit_order (/docs/ai/trader/tools/submit_order)



`submit_order` is the write tool that opens risk. Everything else in the roster cancels, reduces
or reports, with one exception — [`modify`](/docs/ai/trader/tools/modify) can raise a resting order's
quantity, which is why the node sizes it against the same notional ceiling; this one puts a
brand-new order on a venue. It is annotated `destructiveHint: true` and `idempotentHint: false`,
and it needs `vike-cli mcp --node <host:port>` plus `VIKE_TRADEHUB_CONTROL_KEY`.

## Arguments [#arguments]

| Parameter         | Type    | Required | Notes                                                                                                            |
| ----------------- | ------- | :------: | ---------------------------------------------------------------------------------------------------------------- |
| `venue`           | string  |    yes   | Venue id                                                                                                         |
| `symbol`          | string  |    yes   | Instrument symbol                                                                                                |
| `side`            | integer |    yes   | `1` buy, `-1` sell                                                                                               |
| `qty`             | number  |    yes   | Order quantity                                                                                                   |
| `order_type`      | string  |    no    | `market` (default), `limit`, `stop`, `take_profit`                                                               |
| `price`           | number  |    no    | Limit price                                                                                                      |
| `trigger_price`   | number  |    no    | Stop / take-profit trigger                                                                                       |
| `reduce_only`     | boolean |    no    | Defaults to `false`                                                                                              |
| `client_order_id` | string  |    no    | Read by the builder, though the advertised schema does not list it                                               |
| `reason`          | string  |    no    | Rationale for the node's audit trail                                                                             |
| `confirm`         | boolean |    no    | Must be the JSON boolean `true` **and** be accompanied by `preview_token` — either one missing returns a preview |
| `preview_token`   | string  |    no    | The token this tool's preview returned. Fires once, expires after 60s, bound to the command it previewed         |

A missing required field is a tool error raised in `verbs::verb_from_tool_args` before any command
exists — `submit_order_missing_required_field_is_a_tool_error` pins it with a call that omits
`symbol`. The order kinds and what each one means have their own
[pages](/docs/trader/concepts/orders/).

## Two calls, and the second one carries two things [#two-calls-and-the-second-one-carries-two-things]

**Call one previews.** `Server::call_tool` builds the wire command, mints a client order id, asks
the node for its own dry-run, and returns `preview_of(...)` — `will_execute: false`, the fully
resolved `wire_command`, the advisory `guardrail`, the `node_verdict` and whether it was obtained,
the `reason&#x60; that would be recorded, a note, and the &#x2A;*`preview_token`** that confirms this exact
command. With no node configured it opens no socket at all:
`submit_order_without_confirm_only_previews_and_touches_no_network` proves a preview succeeds in
that state, and checks the guardrail's notional is `50.0` for a limit buy of `0.5` at `100.0`.

**Call two is the one that sends** — and it needs **both** `confirm: true` **and** that
`preview_token`:

```json
{ "venue": "binance", "symbol": "BTCUSDT", "side": 1, "qty": 0.001,
  "confirm": true, "preview_token": "pv-1" }
```

The token fires once, expires after 60 seconds and is bound to the command it previewed;
[Live node](/docs/ai/trader/trading#what-the-token-is-and-what-it-is-not) sets out all four rules and
why the token is deliberately not a secret.

<Callout type="warn" title="confirm: true without a token is a preview, not an error">
  Both conditions are read together — a token that arrives without `confirm: true`, and a `confirm`
  that arrives without a token, are the same case: the call returns a **fresh preview**,
  `will_execute: false`, a new token, and nothing on the wire.
  `confirm_alone_no_longer_executes_it_returns_a_preview` pins exactly that. So an agent that treats
  its second call as proof it traded, without reading `will_execute`, believes it holds an order it
  never placed. `confirm` is also read as a JSON boolean and nothing else, so `"true"`, `1` and
  `"yes"` fall through the same way.
</Callout>

A bad token is the loud case: a tool error carrying the reason. There are three messages, not
four — the store cannot tell an *unknown* token from an *already-used* one, because `take` removed
the used one, so both come back as `unknown or already used`. Read that one as possibly-already-sent
and settle it with `node_snapshot` rather than re-confirming. *Expired* and *mismatched* each have
their own message. Confirming with a valid token and no node reaches the connection and fails
there — a clean error, not a panic, and the fact that it got that far is what
`a_preview_token_fires_at_most_once` uses to prove the token passed the gate.

## The client order id [#the-client-order-id]

The node **refuses** a remote submit whose `client_order_id` is empty. `lower_command` says why: an
empty one would let the runtime mint, which is fine in-process, but a remote peer then has no
stable handle to cancel or dedup by. So `verbs::fill_client_order_id` mints one *before* the
preview branch, and the preview shows a real id.

The mint is `verbs::coid_minter` — the live core's own generator and wire form,
`<8-hex-session><seq>`. Its doc argues four properties: unique per order (the sequence
increments), no collision across sessions (the prefix is drawn from OS entropy per process),
typeable at 9–11 characters, and venue-safe against `^[A-Za-z0-9]{1,32}$`, the strictest common
denominator across the big crypto venues.

**The id in the preview is the id that gets sent.** A confirming call does mint a fresh one while
rebuilding the command — the mint runs on every call — but the rebuilt command is only ever
compared: `same_intent` excludes the `client_order_id` for exactly this reason, and the server then
executes the **stored** command. That is a stronger property than comparing the ids would have
been, because what reaches the venue is byte-for-byte what the preview displayed and the node
dry-ran. The `client_order_id` in the accepted response is still the authoritative one to keep.

(Passing the previewed id back explicitly is harmless and changes nothing — `same_intent` ignores
the field either way.)

<Callout type="warn" title="A supplied id is not charset-checked on this surface">
  The human `trade` REPL refuses a `--coid` outside that charset. This tool does not:
  `verbs::verb_from_tool_args` passes an agent-supplied `client_order_id` through unvalidated, and
  the node's `lower_command` requires only that it be non-empty. Re-sending the same id proves
  nothing and is not free: the core registry is coid-keyed, so a repeat leaves **one** row — but
  `gate_and_register` inserts over it rather than rejecting the duplicate, and `submit_order` calls
  `client.submit` both times, so on the default paper mount two orders rest.
</Callout>

## What checks the size [#what-checks-the-size]

The preview's `guardrail` is advisory and computed on **your** machine
(`verbs::guardrail_check`). `max_qty` comes from `VIKE_MAX_ORDER_QTY`, a local typo-catcher with no
enforcing counterpart anywhere; `max_notional` from this machine's `policy.toml`
(`max_notional_per_order`). A market order carries no price, so its notional is `null` and cannot
be checked client-side at all.

What refuses is server-side. `ControlLimits::vet` consumes a rate token on every command and then
applies the notional ceiling to a submit that carries a price — and to a `modify` naming both a new
qty and a new price — against the **node's** own `max_notional_per_order`, which is **unset by
default**: `notional_reason` opens on that `Option`, so a node whose `policy.toml` names no ceiling
skips this half entirely. Notional there is a magnitude — the check takes `.abs()` of every factor,
because a site that absed the quantity only let a negative price produce a negative notional that
could never trip the ceiling. Beneath it sits the core `RiskGate`. Neither is reachable from an
agent, and the ceiling is a settings key: see
[policy.toml](/docs/trader/reference/settings/policy) and
[Risk and arming](/docs/trader/concepts/risk-and-arming).

Arming is upstream of all of it. A venue with no credentials mounts as paper, and
`policy.venues.<venue>` defaults to `paper` and can only ever refuse.

## Outcomes [#outcomes]

`Server::execute` awaits the ticket that send returned and waits `ACK_WAIT`, two seconds — a
deadline, not a sleep. Accepted returns `sent: true`, `outcome: "accepted"` and the authoritative
`client_order_id`. A refusal is an error result carrying the node's reason. A timeout returns
`outcome: "unknown"`; a dropped control connection is an error result saying the outcome is unknown
and it may have executed. For both ambiguous cases, call
[`node_snapshot`](/docs/ai/trader/tools/node_snapshot) **before** retrying.

Then watch it: [order lifecycle](/docs/trader/concepts/order-lifecycle) describes the states the order
now moves through, and [`cancel_order`](/docs/ai/trader/tools/cancel_order),
[`modify`](/docs/ai/trader/tools/modify) and [`flatten`](/docs/ai/trader/tools/flatten) are what act on it.

> Preview a limit buy of 0.5 BTCUSDT at 60,000 on binance, then place it if the guardrail is clean.


# validate_strategy (/docs/ai/trader/tools/validate_strategy)



Compiles a Rhai strategy and answers whether it compiled. Compile *is* validation here: there is
no separate linter. Entirely offline — no `--addr`, no `--node`, no key, no socket.

## Input [#input]

| Field    | Type   | Required | Meaning              |
| -------- | ------ | :------: | -------------------- |
| `script` | string |    yes   | Rhai strategy source |

The argument is `script`, matching this server's sibling `discover_params`. A missing one is the
only `isError` this tool produces, and its message names the argument
(`validate_strategy_missing_script_arg_is_a_tool_error`).

```json
{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"validate_strategy","arguments":{
  "script": "let fast = param(\"fast\", 5.0);\nfn on_bar() {}"
}}}
```

## What comes back [#what-comes-back]

Two shapes, and both are successes:

```json
{ "ok": true }
```

```json
{ "ok": false, "error": "…the compiler's own message…" }
```

A bad script is an **answer**, not a tool failure — the agent reads the error and fixes the
script. `validate_strategy_answers_ok_and_compile_errors_offline` pins both halves, including that
`ok: false` arrives with `isError: false`.

## What the check actually is [#what-the-check-actually-is]

`tool_validate_strategy` goes through `vike_script::discover_params`, the broker-free public
compile path. That function compiles the source and then runs its **top level exactly once**,
which is the same error surface as mounting the strategy for real: `RhaiStrategy::compile` does
the same one-time top-level run, and the top level is where `param(name, default)` is called. So
the check covers the grammar, and it covers everything a script does outside a function.

<Callout type="warn" title="It cannot see inside fn on_bar() — and that is where the trading is">
  Rhai resolves a registered function when the line **runs**, not at compile time, and this path
  runs only the top level. Every call a strategy makes sits inside `fn on_bar()` and is therefore
  unchecked. Three mistakes land in that blind spot: an unbound **name** (a typo, or any indicator
  the host does not bind), a wrong **arity**, and a wrong **argument type**. Name and arity always
  raise `ErrorFunctionNotFound`, and so does a mistyped argument to an **order verb** —
  `register_verbs` binds `market` as `(i64, f64)`, rhai hashes each argument's `TypeId` and performs
  no int-to-float coercion for a registered function, so `market(1, 1)` misses exactly as hard as a
  misspelling. An **indicator** is the exception: `register_arity_forms` binds every arity with
  `rhai::Dynamic` parameters, so `sma(5.0)` resolves just like `sma(5)`, and only a non-numeric
  argument (`sma("20")`) fails — as a named runtime error rather than function-not-found. Each of
  them errors on every bar, `RhaiStrategy`'s hook runner swallows it fail-safe (zero orders that
  bar), and after 10 consecutive errors the strategy disables itself. It looks mounted and silently
  never trades.
</Callout>

That hazard is demonstrated rather than argued in the product tree:
`an_unbound_call_compiles_and_then_reaches_the_broker_with_nothing` takes the shipped SMA-cross
template, rewrites its `sma(` calls to a name nothing binds, and shows that it still compiles,
still reports its `param()` knobs, and reaches the broker with nothing over 80 rising bars.

## So what does close the gap [#so-what-does-close-the-gap]

Three things, in order of cost:

1. **Check every indicator name against
   [`list_indicators`](/docs/ai/trader/tools/list_indicators)**, not against memory. That tool lists
   the host-bound callable set, which is not the same as the indicator registry.
2. **Read the knobs back with
   [`discover_params`](/docs/ai/trader/tools/discover_params).** It shares this compile path, so it
   confirms the top level ran and tells you which names a `[sweep]` may vary. Note the deliberate
   asymmetry: there, a compile error *is* a tool error, because there are no parameters to report.
3. **Run it.** [`run_backtest`](/docs/ai/trader/tools/run_backtest) over a short slice, then look at
   `n_trades`. Zero trades with a populated `zero_trade` diagnosis is the shape a self-disabled
   strategy leaves behind, and that field exists precisely so the answer is not a table of zeros.

## The prompt [#the-prompt]

> Does this strategy compile? If not, fix it and try again.

An agent can loop on this tool freely — it opens nothing and costs nothing but its own turn.
[Scripting](/docs/trader/scripting) is the language surface, [the
cheatsheet](/docs/trader/scripting/cheatsheet) every host function and order verb in one page, and
[Rhai strategy from scratch](/docs/trader/tutorials/rhai-strategy-from-scratch) the worked build.


# Polymarket archive (/docs/endpoints/data/archive)



The archive is the one namespace with no JSON envelope and no OpenAPI operations. It is **three
paths** on `https://data.vike.io`, each serving files straight off disk. Two are open; the third
checks your credential before it opens anything.

That shape decides what these pages can tell you. There are no query parameters to table, no JSON
envelope and no response schema: the request is a path, and the answer is a status code and some
bytes. What varies is the **path**, and the path is a Hive partition.

<Callout type="warn" title="Archive downloads do not spend your hourly request budget">
  Every archive request is still authenticated and still recorded as a download against your key. It
  just no longer counts against the hourly ceiling, since 2026-09-02. Requests were the wrong unit:
  the credential is checked once per HTTP request, and a Parquet reader pointed at a URL issues one
  Range request per column chunk — **one 1.26 GB partition measured 20,237 of them**. See
  [Rate limits](/docs/data/rate-limits), which is where that counter is documented.

  This is not licence to read remotely. It is still thousands of round trips for one file, and
  [Downloading](/docs/data/archive/downloading) is the page that shows the fast way.
</Callout>

<Callout type="warn" title="The /archive/ prefix with a credential is the only way in">
  There is no second spelling of these paths. As of 2026-09-03 every URI that is not one of the
  three below returns **404** — including anything that drops the `/archive/` prefix — and the gated
  partitions are reachable only under that prefix, with a credential. Measured below,
  unauthenticated.
</Callout>

## Free — no credential [#free--no-credential]

Neither of these two paths is gated, so a request to them validates nothing, records no usage and
consumes nothing. They are the surface a prospective customer can read before buying.

| Path                                                              | What it is                                                                                                                                       |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`/archive/manifest.json`](/docs/endpoints/data/archive/manifest-json) | The index of everything in the archive, regenerated daily. It needs **no key**.                                                                  |
| [`/archive/samples/`](/docs/endpoints/data/archive/samples)            | A real slice of the full archive — one complete crypto up/down 5-minute market, both outcome tokens, open through resolution, all three streams. |

## Key-gated — the full archive [#key-gated--the-full-archive]

| Path                                                                  | What it is                                                                                                          |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| [`/archive/{partition path}`](/docs/endpoints/data/archive/partition-path) | One prefix covering the whole archive — two Hive partitionings of the same data behind one path, not two endpoints. |

## Status codes, measured [#status-codes-measured]

Every row below was probed against the live host on **2026-09-03 with no credential**. They are
the three behaviours worth internalising: free means free, gated means 401 rather than 404, and
everything outside the three documented paths is gone.

Re-run the whole table yourself — it needs no credential, and status codes are the only thing
being read, so nothing is downloaded:

```sh title="Re-run the table"
for p in \
  /archive/manifest.json \
  /archive/samples/ \
  /archive/samples/README.txt \
  /archive/samples \
  /archive/ \
  "/archive/venue=polymarket/date=2026-09-01/trades.parquet" \
  /archive \
  /manifest.json ; do
  printf '%-62s %s\n' "$p" "$(curl -s -o /dev/null -w '%{http_code}' "https://data.vike.io$p")"
done
```

| Request                                                             | Status  |
| ------------------------------------------------------------------- | ------- |
| `/archive/manifest.json`                                            | **200** |
| `/archive/samples/`                                                 | **200** |
| `/archive/samples/README.txt`                                       | **200** |
| `/archive/samples` — no trailing slash                              | **401** |
| `/archive/`                                                         | **401** |
| `/archive/venue=polymarket/date=2026-09-01/trades.parquet`          | **401** |
| `/archive` — no trailing slash                                      | **404** |
| `/manifest.json` — prefix dropped                                   | **404** |
| `/samples/README.txt` — prefix dropped                              | **404** |
| `/venue=polymarket/date=2026-09-01/trades.parquet` — prefix dropped | **404** |

**401 and 404 mean different things here.** A 401 says the path resolved and the credential did
not; a 404 says nothing is routed there at all. A 404 on an `/archive/`-prefixed path you believe
exists is a path bug — check it against `dates[]` or `families[]` in the manifest.

## Documented elsewhere [#documented-elsewhere]

These pages are the routing and the gate. The archive's substance has its own pages, and they are
not repeated here:

* **[Bulk archive](/docs/data/archive)** — the three streams, both Hive layouts, per-stream column
  schemas with their two decoding traps, current coverage, and the free samples.
* **[Downloading](/docs/data/archive/downloading)** — why a remote Parquet read is thousands of
  requests, worked `curl` and Python that are one, and how to fetch less by choosing a narrower
  file instead of a byte range.
* **[Polymarket](/docs/endpoints/data/polymarket)** — `/v1/polymarket/archive/datasets` and
  `/v1/polymarket/archive/url`, the two JSON endpoints that index exactly the files these pages
  serve. They are filed there because that is where they are routed, not because they are about
  something else.
* **[Rate limits](/docs/data/rate-limits)** — the one hourly counter, what it counts, and the archive's
  exclusion from it.


# /archive/manifest.json (/docs/endpoints/data/archive/manifest-json)



```
GET https://data.vike.io/archive/manifest.json
```

The index of everything in the archive, regenerated daily: coverage, both partitioning patterns,
the inline column schemas, the auth scheme, the licence, and one entry per partition carrying
byte size and row count. It needs **no key**. Fetch it first and enumerate it — it is what is
true today, where any figure written into a doc page is a snapshot.

```sh title="cURL"
curl "https://data.vike.io/archive/manifest.json" -o manifest.json
```

The missing `-H` is deliberate, not an omission: this is one of the two keyless paths, so the
request validates nothing and records nothing. The live response, fetched
**2026-09-03**, carries three elisions, marked inline and counted under the fence.

```json title="Example response (elided)"
{
  "venue": "polymarket",
  "generated_at": "2026-09-03T00:37:42Z",
  "license": {
    "name": "CC BY 4.0",
    "url": "https://creativecommons.org/licenses/by/4.0/",
    "attribution": "Polymarket L2 archive (c) Vike (vike.io/data), CC BY 4.0",
    "note": "Applies to the DATA files this manifest indexes. It grants no rights to any Vike source code."
  },
  "partitioning": "venue=polymarket/date=YYYY-MM-DD/{book_events,trades,l1_quotes}.parquet",
  "note": "Full L2 (book_events) + taker tape (trades) + derived top-of-book (l1_quotes) for the whole Polymarket universe (crypto up/down + sports + politics markets), one UTC day per partition.",
  "schema": {
    "book_events": [ /* 16 columns, elided */ ],
    "trades": [
      { "name": "token_id",     "type": "String"  },
      { "name": "condition_id", "type": "String"  },
      { "name": "ts",           "type": "Int64"   },
      { "name": "local_ts",     "type": "Int64"   },
      { "name": "seq",          "type": "UInt64"  },
      { "name": "price",        "type": "Float64" },
      { "name": "size",         "type": "Float64" },
      { "name": "side",         "type": "String"  }
    ],
    "l1_quotes": [ /* 8 columns, elided */ ]
  },
  "auth": {
    "scheme": "header",
    "header": "X-API-Key",
    "how_to_get_a_key": "Request access via vike.io — the same account/API-key system that gates data.vike.io/v1 and data.vike.io/mcp."
  },
  "range_requests": true,
  "free_sample": {
    "path": "/archive/samples/",
    "readme": "/archive/samples/README.txt",
    "note": "One full crypto up/down 5-minute market (both outcome tokens, open through resolution), regenerated daily — no key required."
  },
  "dates": [
    { "date": "2026-09-02", "streams": {
      "book_events": { "rows": 306994531, "bytes": 4799571940 },
      "trades":      { "rows": 1006555,   "bytes": 12314277 },
      "l1_quotes":   { "rows": 36596619,  "bytes": 373583589 } } },
    { "date": "2026-09-01", "streams": {
      "book_events": { "rows": 307245726, "bytes": 4826341757 },
      "trades":      { "rows": 1100045,   "bytes": 13459739 },
      "l1_quotes":   { "rows": 32065417,  "bytes": 335196889 } } }
    /* 38 more dates, newest first, ending 2026-07-25 */
  ],
  "family_partitioning": "venue=polymarket/asset=<asset>/tenor=<tenor>/date=YYYY-MM-DD/{book_events,trades,l1_quotes}.parquet",
  "family_partitioning_note": "ADDITIVE alternative layout (poly_export_family.sh) grouping the crypto up/down families (asset x tenor, e.g. asset=btc/tenor=5m) into their own small files so a single-family customer does not download the whole token-sorted date= file. asset=other/tenor=other is the catch-all for every market that is not a recognized up/down family (sports, politics, one-off events) — never silently dropped. Same schema as the date= layout (see `schema` above); not every (asset,tenor,date) is guaranteed present for every stream (a family with zero rows in a stream that day has no file for it).",
  "families": [
    { "asset": "xrp", "tenor": "5m", "date": "2026-09-02", "streams": {
      "book_events": { "rows": 8531385, "bytes": 104536361 },
      "trades":      { "rows": 33332,   "bytes": 555993 },
      "l1_quotes":   { "rows": 1699187, "bytes": 11729583 } } },
    { "asset": "xrp", "tenor": "5m", "date": "2026-09-01", "streams": {
      "book_events": { "rows": 7852908, "bytes": 99223946 },
      "trades":      { "rows": 33015,   "bytes": 544739 },
      "l1_quotes":   { "rows": 986897,  "bytes": 7096420 } } }
    /* 658 more families */
  ]
}
```

**What was elided, exactly.** The response is **262,424 bytes**. Every scalar and every object
above is verbatim; three arrays are cut, and nothing else is. `schema.book_events` (16 columns)
and `schema.l1_quotes` (8) are dropped — `schema.trades` is shown whole as the shape exemplar,
and the full column lists are on [Bulk archive](/docs/data/archive#column-schemas). `dates` carries
**40** entries and `families` **660**; two of each are shown, in the order the response returns
them, which is newest first.

⚠ **The two `type` vocabularies are ClickHouse's, not Parquet's** — visible above as `Int64` and
`Float64` on `trades`, and as `Decimal(9, 4)`, `LowCardinality(String)` and
`Enum8('book' = 1, …)` on the two elided streams. They describe the table the file was exported
from. What a Parquet reader hands back is the physical type, and the gap between the two is the
decoding trap that [Bulk archive](/docs/data/archive#column-schemas) works through.

The tail of `dates[]` is a different shape from its head, which is why the head alone would
mislead — the oldest partition in the same response:

```json title="The oldest dates[] row"
{ "date": "2026-07-25", "streams": {
  "book_events": { "rows": null, "bytes": 5235801848 },
  "trades":      { "rows": null, "bytes": 12139041 },
  "l1_quotes":   { "rows": null, "bytes": 357730559 } } }
```

**Parameters: none.** No query string is read, and no header changes the response. The path is
matched *exactly*, so `manifest.json` is the only keyless name under `/archive/`: any other name
in that directory is gated like the rest of the full archive, and answers **401** without a
credential.

Top-level keys, read from the live response fetched 2026-09-03:

| Key                                               | What it holds                                                            |
| ------------------------------------------------- | ------------------------------------------------------------------------ |
| `generated_at`                                    | UTC timestamp of this regeneration.                                      |
| `venue`                                           | `polymarket`.                                                            |
| `note`                                            | One sentence on what the three streams are.                              |
| `partitioning`                                    | The `date=` pattern string.                                              |
| `family_partitioning`, `family_partitioning_note` | The additive `asset=`/`tenor=` pattern and its caveats.                  |
| `dates`                                           | One row per UTC day, each with a `streams` object keyed by stream name.  |
| `families`                                        | One row per (`asset`, `tenor`, `date`), same `streams` shape.            |
| `schema`                                          | Column types per stream — `book_events`, `trades`, `l1_quotes`.          |
| `auth`                                            | `scheme`, `header` (`X-API-Key`) and how to get a key.                   |
| `free_sample`                                     | Paths to `/archive/samples/` and its `README.txt`.                       |
| `license`                                         | CC BY 4.0 with its attribution string, covering the **data files only**. |
| `range_requests`                                  | `true`.                                                                  |

A `dates[]` row, verbatim from that response:

```json title="One dates[] row, verbatim"
{"date":"2026-09-02","streams":{
  "book_events":{"rows":306994531,"bytes":4799571940},
  "trades":{"rows":1006555,"bytes":12314277},
  "l1_quotes":{"rows":36596619,"bytes":373583589}}}
```

⚠ &#x2A;*`rows` is optional, `bytes` is not.** The three oldest partitions carry a byte size and a
`null` row count — confirmed in today's manifest for 2026-07-25, 2026-07-26 and 2026-07-27. Code
that does arithmetic on `rows` without a null check breaks on the earliest dates and nowhere
else, which is the hardest kind of bug to find.

**Discovering partitions programmatically.** The manifest is not the only index. Two JSON
endpoints answer the same question over HTTP, with filters and paging —
[`/v1/polymarket/archive/datasets`](/docs/endpoints/data/polymarket) enumerates partitions across both
layouts, each row carrying the absolute download URL beside that file's byte and row counts, and
`/v1/polymarket/archive/url` resolves one already-known partition to the same information. They
are routed under the **polymarket** namespace rather than under `/archive/`, because the archive
carries only Polymarket data. There is no `/v1/archive/...` alias — that spelling is routed
nowhere and answers 404.

⚠ &#x2A;*Those two are ordinary API calls.** They need a credential and they *do* spend the hourly
budget that an archive download does not — see [Rate limits](/docs/data/rate-limits). This manifest
remains the keyless way to get the whole index in one request; the discovery endpoints are what
you want when you would rather filter server-side than parse 250 KB of JSON.


# /archive/{partition path} (/docs/endpoints/data/archive/partition-path)



```
GET https://data.vike.io/archive/venue=polymarket/date={YYYY-MM-DD}/{stream}.parquet
GET https://data.vike.io/archive/venue=polymarket/asset={asset}/tenor={tenor}/date={YYYY-MM-DD}/{stream}.parquet
```

One path prefix covering the whole archive. The two path shapes above are **two Hive
partitionings of the same data behind one path**, not two endpoints — full detail of both, and
which dates each covers, is on [Bulk archive](/docs/data/archive#two-layouts).

**There is no JSON response to show you.** The body is a binary Apache Parquet file — the one
that command downloads is 13,459,739 bytes. So the example below asks for the first 2 KB of the
next day's partition instead of the whole of it, which is enough to prove the route, the gate
and the file type without moving the file:

```sh title="cURL — probe with a 2 KB range"
curl -H "X-API-Key: $VIKE_API_KEY" \
  -r 0-2047 -D - -o /dev/null \
  "https://data.vike.io/archive/venue=polymarket/date=2026-09-02/trades.parquet"
```

Response headers, verbatim, 2026-09-03:

```http title="Response headers"
HTTP/1.1 206 Partial Content
Content-Type: application/octet-stream
Content-Length: 2048
Content-Range: bytes 0-2047/12314277
Last-Modified: Thu, 03 Sep 2026 00:32:06 GMT
ETag: "6a98c006-bbe6a5"
Cache-Control: private, no-store
Server: cloudflare
cf-cache-status: DYNAMIC
```

The first four bytes of that body are `50 41 52 31` — the ASCII `PAR1` every Parquet file opens
and closes with. The rest is zstd-compressed column data and is not readable as text.

Three of those headers are worth reading as confirmations rather than trivia. **`206` with a
`Content-Range` is the `Range` row of the table below, working** — the server served 2,048 bytes
of a file it told you is 12,314,277. That total is also the cross-check on
[`manifest.json`](/docs/endpoints/data/archive/manifest-json): its `dates` entry for `2026-09-02`
reports the `trades&#x60; stream at 1,006,555 rows and 12,314,277 bytes — the same total — so a size
read from the manifest is the size you will actually be billed bandwidth for. And &#x2A;*`cf-cache-status: DYNAMIC` beside
`Cache-Control: private, no-store`** is the third bullet below holding: Cloudflare saw the
response and declined to cache it.

Drop the credential and the same URL never reaches the file — the request is refused before the
file is opened. The status is **401 Authorization Required** and the body is a plain HTML error
page from the edge, not a JSON envelope:

```html title="Refused without a credential (401)"
<html>
<head><title>401 Authorization Required</title></head>
<body>
<center><h1>401 Authorization Required</h1></center>
</body>
</html>
```

⚠ &#x2A;*That 401 body is HTML, not the JSON error envelope the `/v1` endpoints return.** A client
that assumes every failure parses as JSON breaks here — see [Errors](/docs/data/errors). It is also
indistinguishable from the 401 a path that does not exist returns: probed keylessly on
2026-09-03, the real partition above and an invented
`date=1999-01-01/nosuchstream.parquet` both answered **401** with byte-identical bodies. Without
a credential you cannot tell a typo from a refusal, because the gate runs before the lookup.

There are no query parameters. What you can vary is the path and a small set of headers:

```sh title="cURL — download the partition"
curl -H "X-API-Key: $VIKE_API_KEY" \
  -o polymarket-trades-2026-09-01.parquet \
  "https://data.vike.io/archive/venue=polymarket/date=2026-09-01/trades.parquet"
```

<Params>
  <Param name="X-API-Key" loc="header">
    The API key. HTTP header names are case-insensitive; the REST spec spells it 

    `X-API-KEY`

     and the manifest 

    `X-API-Key`

     — same header, same key.
  </Param>

  <Param name="Authorization: Bearer vk_oat_…" loc="header">
    OAuth 2.1 access token. The bearer is tried 

    **first**

    , then the 

    `X-API-Key`

     header. Both reach the same account — see 

    [Authentication](/docs/data/authentication)

    .
  </Param>

  <Param name="Range" loc="header">
    Supported: responses carry 

    `Accept-Ranges: bytes`

    , and the manifest advertises 

    `range_requests: true`

    . It is there so an interrupted download can resume, not so a query engine can page a remote file.
  </Param>

  <Param name="venue" loc="path">
    `polymarket`

    . The only venue in the archive today.
  </Param>

  <Param name="date" loc="path">
    One UTC day, 

    `YYYY-MM-DD`

    . Enumerate 

    `dates[]`

     in the manifest; do not probe for dates.
  </Param>
</Params>

\| `asset` | path | family layout only | `btc`, `eth`, `sol`, `xrp`, `doge`, `bnb`, `hype`, `other` — read from today's manifest, which is the authority rather than this row. |
\| `tenor` | path | family layout only | `5m`, `15m`, `4h`, `other`, same caveat. |
\| `{stream}` | path | yes | `book_events`, `trades` or `l1_quotes`. Schemas differ per stream — [Bulk archive](/docs/data/archive#column-schemas). |

¹ One of the two credentials, not both.

**A missing file is a legitimate answer in the family layout.** A family with zero rows in a
stream on a given day has no file for that stream, and the family layout does not cover every
date the `date=` layout does. Enumerate `families[]` rather than assuming.

Three properties of this location worth knowing before you point a tool at it:

* **Responses carry `Cache-Control: private, no-store`**, on every response. An authenticated
  file must never be cached at the edge — a cached copy would bypass both the gate and the usage
  record — so do not expect a CDN to serve a repeat download for you.
* **A directory URL under `/archive/` returns a listing** rather than a 403, once you present a
  credential. The listing is HTML.
* **Throughput is capped at 50 MB/s per connection.** It is a bandwidth bound, not a request
  bound; parallel whole-file downloads are the supported way to go faster, and cost one recorded
  download each.

⚠ **This path never returns a rate-limit 429**: archive downloads do not draw on the hourly
budget at all. A refusal here is a credential problem, not a budget one — see
[Rate limits](/docs/data/rate-limits) and [Errors](/docs/data/errors).


# /archive/samples/ (/docs/endpoints/data/archive/samples)



```
GET https://data.vike.io/archive/samples/
GET https://data.vike.io/archive/samples/{file}
```

A real slice of the full archive — one complete crypto up/down 5-minute market, both outcome
tokens, open through resolution, all three streams — regenerated daily and served free. It is the
right place to write and debug a parser: same column schema as the key-gated files, at megabytes
rather than gigabytes.

Both forms are keyless — this path is not gated, so neither request below sends a credential,
spends budget or records usage.

```sh title="cURL — list the directory"
curl "https://data.vike.io/archive/samples/"
```

The response is a directory listing page, **HTML rather than JSON**. Verbatim, fetched
2026-09-03:

```html title="Directory listing (HTML)"
<html>
<head><title>Index of /archive/samples/</title></head>
<body>
<h1>Index of /archive/samples/</h1><hr><pre><a href="../">../</a>
<a href="README.txt">README.txt</a>                                         03-Sep-2026 00:32                1376
<a href="book_events.parquet">book_events.parquet</a>                                03-Sep-2026 00:32             6095263
<a href="l1_quotes.parquet">l1_quotes.parquet</a>                                  03-Sep-2026 00:32              631242
<a href="trades.parquet">trades.parquet</a>                                     03-Sep-2026 00:32               55905
</pre><hr></body>
</html>
```

There is no JSON form of this listing. Parsing it means parsing HTML — which is a reason to
enumerate the archive through `manifest.json` or the two
[discovery endpoints](/docs/endpoints/data/polymarket) instead, and to treat this path as the
place you *download* from rather than the place you *index* from.

The second form fetches one file by name. `README.txt` is the one to read first: it names the
market the current sample was cut from, which is the fact the listing above cannot tell you.

```sh title="cURL — fetch one file"
curl "https://data.vike.io/archive/samples/README.txt"
```

Verbatim, same fetch — 1,376 bytes, `Content-Type: text/plain`:

```text title="README.txt"
Polymarket L2 archive — FREE evaluation sample
================================================

This is a real, complete slice of the paid archive (not a synthetic or truncated demo): one
full crypto up/down 5-minute market — the busiest one of its kind (by book_events row count) on
the sample date below — with all three streams for BOTH outcome tokens (up + down) across that
market's entire lifecycle, open through resolution.

  market slug:    btc-updown-5m-1788358500
  condition_id:   0xbf68516768c5732dcc70a342c96eab9ecee9e1b423897070d1ad5385e34bacd7
  sample date:    2026-09-02 (UTC)
  generated at:   2026-09-03T00:32:22Z

Files (Hive/Parquet, same column schema as the paid archive — see /archive/manifest.json for the
exact schema and the full list of available dates):

  book_events.parquet   395640 rows, 6095263 bytes  — full L2: snapshots + price_change deltas + trades + status markers
  trades.parquet        3316 rows, 55905 bytes  — taker tape only
  l1_quotes.parquet     54726 rows, 631242 bytes  — derived top-of-book bid/ask

This sample is regenerated daily from a real recent day, not a fixed historical snapshot. The
paid archive covers the FULL Polymarket universe (crypto up/down + sports + politics markets) for
every date listed in /archive/manifest.json. Auth: an X-API-Key header; the manifest explains how
to request a key.
```

⚠ &#x2A;*Every specific in those two responses is a day old at most.** The slug, the `condition_id`,
the sample date and all six sizes are regenerated nightly — the capture above ran at 08:17 UTC
against files stamped 00:32 the same morning. They are shown so you can see the *shape* of what
you get; read the live `README.txt` for what you actually have.

⚠ &#x2A;*"Paid archive" in that file is stale wording.** The full archive is free: it needs a free API
key, and downloading it does not spend the key's hourly budget ([Rate limits](/docs/data/rate-limits)).
The capture above is kept verbatim.

**Parameters: none.** The directory URL returns the listing as **HTML**, not JSON; the file URLs
return the bytes. Today's listing:

```
README.txt              1,376 bytes
book_events.parquet 6,095,263 bytes
l1_quotes.parquet     631,242 bytes
trades.parquet         55,905 bytes
```

The sizes and the market change daily — `README.txt` names the market and date of the current
one. Do not pin them.

⚠ &#x2A;*The trailing slash is load-bearing.** The keyless path is `/archive/samples/`, slash
included; without it the request is treated as an ordinary gated `/archive/` path instead.
Measured today, unauthenticated: `/archive/samples/` → **200**, `/archive/samples` → **401**. The
same one-character mistake explains a 401 on a resource that is documented as free.


# /assets/hourly (/docs/endpoints/data/hyperliquid/assets-hourly)



```
GET https://data.vike.io/v1/hyperliquid/assets/hourly
```

Hourly close **plus** open interest, funding rate and premium, for many assets at once. This is the
join a research walk actually consumes; it exists so consumers stop stitching the price series
and the market-state series together by hand.

Truncated: `rows` holds **96** rows (2 assets x 48 hours); the first 4 are shown. They are the
positional arrays the trap below describes, ordered by `columns`.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/assets/hourly?symbols=BTC,ETH&days=2" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="symbols" loc="query">
    Comma-separated perp tickers, e.g. 

    `BTC,ETH,SOL`

    . Max 64
  </Param>

  <Param name="days" loc="query">
    Window length back from 

    `end`

    . Default 120, range 1–400
  </Param>

  <Param name="start" loc="query">
    ISO-8601 UTC or epoch s/ms, inclusive. 

    **Overrides `days`**
  </Param>

  <Param name="end" loc="query">
    ISO-8601 UTC or epoch s/ms, exclusive. Defaults to now
  </Param>
</Params>

```json title="Example response"
{
  "assets": [
    "BTC",
    "ETH"
  ],
  "tz": "UTC",
  "source": "1h fills rollup + hourly asset summary",
  "start": 1788250014,
  "end": 1788422814,
  "columns": [
    "ts",
    "asset",
    "close",
    "open_interest",
    "funding_rate",
    "premium"
  ],
  "rows": [
    [
      1788253200,
      "BTC",
      77899.0,
      38732.56691000003,
      0.000012500000000000004,
      -0.00005489032500000001
    ],
    [
      1788256800,
      "BTC",
      78024.0,
      38985.63194500007,
      0.000012500000000000004,
      -0.000063838675
    ],
    [
      1788260400,
      "BTC",
      78094.0,
      39051.50362166676,
      0.000012500000000000004,
      -0.00007857194999999999
    ],
    [
      1788264000,
      "BTC",
      78000.0,
      39224.664336666705,
      0.000012500000000000004,
      -0.00006519585833333333
    ]
  ]
}
```

⚠ **Rows are arrays, not objects**, ordered by the response's `columns` field:
`ts`, `asset`, `close`, `open_interest`, `funding_rate`, `premium`. A 120-day 10-asset window is
28,800 rows, and repeating six key names on each would triple the payload for nothing. This is a
bulk read, not a browsing endpoint.

⚠ &#x2A;*Nulls stay null.** The join is LEFT from the price side: a missing market-state row arrives as
`null`, never as `0.0`, because an open interest of zero is a real reading and substituting it for
"we did not sample this hour" turns a gap into a data point. Carry it through as a NaN.

⚠ &#x2A;*There is no cursor — an oversized request is refused, not paged.** The ceiling is 256,000 rows
(64 assets × 4,000 hours). Half a training window silently returned is worse than a refusal.

`close` comes from the fills rollup, not from the hourly summary's own OHLC grid. That grid is
built from a mid price sampled every 300s — 12 samples an hour, a midpoint nobody transacted at
— and a backtest priced off it books fills at prices that never existed. Only
`open_interest`, `funding_rate` and `premium`, which have no fills-side equivalent, come from the
summary.


# /builders/{builder}/fills (/docs/endpoints/data/hyperliquid/builders-builder-fills)



```
GET https://data.vike.io/v1/hyperliquid/builders/{builder}/fills
```

Raw builder-routed fills, newest first.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/builders/0xb84168cf3be63c6b8dad05ff5d755e97432ff80b/fills?limit=3" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="builder" loc="path">
    Builder address
  </Param>

  <Param name="coin" loc="query">
    HL coin ticker
  </Param>

  <Param name="side" loc="query">
    `buy`

     \| 

    `sell`
  </Param>

  <Param name="start` / `end" loc="query">
    ISO-8601 UTC bounds
  </Param>

  <Param name="limit" loc="query">
    Default 100, max 5000
  </Param>

  <Param name="cursor" loc="query">
    Keyset cursor
  </Param>
</Params>

```json title="Example response"
{
  "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b",
  "fills": [
    {
      "ts": "2026-09-03T08:06:53.487000+00:00",
      "wallet": "0xb52271dd584fbfcae3f0a051abaaf81797a0f303",
      "asset": "xyz:SKHX",
      "dex_name": "XYZ",
      "side": "buy",
      "size_token": 0.012,
      "price": 1179.3,
      "size_usd": 14.1516,
      "fee_usd": 0.007075,
      "deployer_fee_usd": 0.00055,
      "fee": 0.008297,
      "fee_token": "USDC",
      "closed_pnl": 0.0,
      "crossed": true,
      "order_id": 534782081176,
      "trade_id": 460836386307183
    },
    {
      "ts": "2026-09-03T08:06:48.794000+00:00",
      "wallet": "0xb2761bd82613b5bab1b2925b82b94cc8f3e17581",
      "asset": "XRP",
      "dex_name": "HL",
      "side": "sell",
      "size_token": 2748.0,
      "price": 1.3786,
      "size_usd": 3788.3928,
      "fee_usd": 1.894196,
      "deployer_fee_usd": 0.0,
      "fee": 3.598972,
      "fee_token": "USDC",
      "closed_pnl": 27.111768,
      "crossed": true,
      "order_id": 534782009091,
      "trade_id": 1000357728267580
    },
    {
      "ts": "2026-09-03T08:06:48.794000+00:00",
      "wallet": "0xb2761bd82613b5bab1b2925b82b94cc8f3e17581",
      "asset": "XRP",
      "dex_name": "HL",
      "side": "sell",
      "size_token": 1613.0,
      "price": 1.3786,
      "size_usd": 2223.6818000000003,
      "fee_usd": 1.11184,
      "deployer_fee_usd": 0.0,
      "fee": 2.112496,
      "fee_token": "USDC",
      "closed_pnl": 15.913858,
      "crossed": true,
      "order_id": 534782009091,
      "trade_id": 682445774914906
    }
  ],
  "nextCursor": "eyJpIjo2ODI0NDU3NzQ5MTQ5MDYsInQiOiIyMDI2LTA5LTAzIDA4OjA2OjQ4Ljc5NCIsInciOiIweGIyNzYxYmQ4MjYxM2I1YmFiMWIyOTI1YjgyYjk0Y2M4ZjNlMTc1ODEifQ"
}
```

⚠ &#x2A;*`fee` ships raw here, beside its own `fee_token`** — unlike every aggregate in this namespace.
0.95% of fills pay in a non-dollar token, so summing that column client-side without grouping by
`fee_token` produces nonsense. `fee_usd` (the builder's slice) is dollars on every row.


# /builders/{builder}/series (/docs/endpoints/data/hyperliquid/builders-builder-series)



```
GET https://data.vike.io/v1/hyperliquid/builders/{builder}/series
```

Fee, volume, users and fills per bucket for one builder, newest first.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/builders/0xb84168cf3be63c6b8dad05ff5d755e97432ff80b/series?bucket=1d&limit=3" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="builder" loc="path">
    Builder address
  </Param>

  <Param name="bucket" loc="query">
    `1h`

     \| 

    `1d`

    . Default 

    `1d`
  </Param>

  <Param name="start` / `end" loc="query">
    ISO-8601 UTC bounds
  </Param>

  <Param name="limit" loc="query">
    Default 500, max 2000
  </Param>

  <Param name="cursor" loc="query">
    Keyset cursor
  </Param>
</Params>

```json title="Example response"
{
  "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b",
  "bucket": "1d",
  "window": {
    "start": "2026-08-31T08:06:57.246000+00:00",
    "end": "2026-09-03T08:06:57.246000+00:00"
  },
  "series": [
    {
      "ts": "2026-09-03T00:00:00+00:00",
      "fee_usd": 7585.101829000003,
      "volume_usd": 15170213.438114015,
      "share_volume_usd": 15170213.438114015,
      "fills": 10814,
      "users": 1560,
      "revenue_per_user": 4.862244762179489,
      "fee_rate_bps": 4.9999967765404065,
      "fee_usd_node": 7585.101829000003,
      "trader_fee_usd": 13297.350062000005,
      "builder_routed_deployer_fee_usd": 281.00174499999997,
      "closed_pnl_usd": 10536.69776000002,
      "crossed_fills": 10476,
      "taker_pct": 96.87442204549657
    },
    {
      "ts": "2026-09-02T00:00:00+00:00",
      "fee_usd": 26885.466125999978,
      "volume_usd": 53770969.339224845,
      "share_volume_usd": 53770969.339224845,
      "fills": 40543,
      "users": 3854,
      "revenue_per_user": 6.975990172807467,
      "fee_rate_bps": 4.999996551370996,
      "fee_usd_node": 26885.466125999978,
      "trader_fee_usd": 46489.33583100012,
      "builder_routed_deployer_fee_usd": 1543.7487520000045,
      "closed_pnl_usd": 32176.18408099984,
      "crossed_fills": 40283,
      "taker_pct": 99.35870557186198
    },
    {
      "ts": "2026-09-01T00:00:00+00:00",
      "fee_usd": 46430.14683999935,
      "volume_usd": 92850044.21443081,
      "share_volume_usd": 92850044.21443081,
      "fills": 46510,
      "users": 4322,
      "revenue_per_user": 10.742745682554222,
      "fee_rate_bps": 5.000551936493656,
      "fee_usd_node": 46430.14683999935,
      "trader_fee_usd": 76360.59171799968,
      "builder_routed_deployer_fee_usd": 1868.793809000012,
      "closed_pnl_usd": 56504.743095999846,
      "crossed_fills": 45875,
      "taker_pct": 98.6347022145775
    }
  ],
  "nextCursor": "eyJ0IjoiMjAyNi0wOS0wMSAwMDowMDowMC4wMDAifQ"
}
```

⚠ &#x2A;*`users` is a distinct-wallet count per bucket and is not additive.** Summing the daily column
double-counts anyone who traded on two days. A period total comes from
[`/builders/{builder}`](/docs/endpoints/data/hyperliquid/builders-builder) over that period.


# /builders/{builder}/users (/docs/endpoints/data/hyperliquid/builders-builder-users)



```
GET https://data.vike.io/v1/hyperliquid/builders/{builder}/users
```

The wallets routing through one builder, ranked.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/builders/0xb84168cf3be63c6b8dad05ff5d755e97432ff80b/users?limit=3" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="builder" loc="path">
    Builder address
  </Param>

  <Param name="window" loc="query">
    `1d`

     \| 

    `7d`

     \| 

    `30d`

     \| 

    `all`

    . Default 

    `30d`
  </Param>

  <Param name="sort" loc="query">
    `volume`

     \| 

    `fees`

     \| 

    `pnl`

    . Default 

    `volume`
  </Param>

  <Param name="order" loc="query">
    `asc`

     \| 

    `desc`

    . Default 

    `desc`
  </Param>

  <Param name="limit" loc="query">
    Default 100, max 1000
  </Param>

  <Param name="cursor" loc="query">
    Keyset cursor
  </Param>
</Params>

```json title="Example response"
{
  "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b",
  "window": {
    "window": "30d",
    "start": "2026-08-04T08:06:57.246000+00:00",
    "end": "2026-09-03T08:06:57.246000+00:00"
  },
  "sort": "volume",
  "order": "desc",
  "users": [
    {
      "wallet": "0xe1b02144c101e4f6c41bc746f854214404efa23d",
      "rank": 1,
      "assets": 1,
      "fee_usd": 58025.66724299987,
      "volume_usd": 116051339.95361994,
      "share_volume_usd": 116051339.95361994,
      "fills": 6401,
      "fee_rate_bps": 4.999999764430975,
      "fee_usd_node": 58025.66724299987,
      "trader_fee_usd": 96609.87647999988,
      "builder_routed_deployer_fee_usd": 0.0,
      "closed_pnl_usd": -16109.553342999967,
      "active_days": 30,
      "crossed_fills": 6238,
      "taker_pct": 97.45352288704889,
      "first_seen": "2026-08-04T10:39:34.604000+00:00",
      "last_seen": "2026-09-02T19:18:12.778000+00:00"
    },
    {
      "wallet": "0xff573cc8d53d6ca48134c23da75df1984ff28c24",
      "rank": 2,
      "assets": 11,
      "fee_usd": 32611.176251000008,
      "volume_usd": 65043708.12699884,
      "share_volume_usd": 65043708.12699884,
      "fills": 13193,
      "fee_rate_bps": 5.013732640723094,
      "fee_usd_node": 32611.176251000008,
      "trader_fee_usd": 56593.81896899996,
      "builder_routed_deployer_fee_usd": 29.69778300000001,
      "closed_pnl_usd": 1960.3512290000253,
      "active_days": 17,
      "crossed_fills": 13193,
      "taker_pct": 100.0,
      "first_seen": "2026-08-04T08:10:00.798000+00:00",
      "last_seen": "2026-08-20T09:47:11.594000+00:00"
    },
    {
      "wallet": "0x30381168675a9c97dbeb108b8cde33aba434be4f",
      "rank": 3,
      "assets": 20,
      "fee_usd": 30719.542745999996,
      "volume_usd": 61419224.695899084,
      "share_volume_usd": 61419224.695899084,
      "fills": 5981,
      "fee_rate_bps": 5.001616822436236,
      "fee_usd_node": 30719.542745999996,
      "trader_fee_usd": 54596.672999999966,
      "builder_routed_deployer_fee_usd": 547.0871540000002,
      "closed_pnl_usd": 57038.65442500002,
      "active_days": 19,
      "crossed_fills": 5981,
      "taker_pct": 100.0,
      "first_seen": "2026-08-04T09:14:37.068000+00:00",
      "last_seen": "2026-08-23T03:42:46.452000+00:00"
    }
  ],
  "nextCursor": "eyJoaSI6IjIwMjYtMDktMDNUMDg6MDY6NTcuMjQ2MDAwKzAwOjAwIiwibG8iOiIyMDI2LTA4LTA0VDA4OjA2OjU3LjI0NjAwMCswMDowMCIsInIiOjMsInYiOjYxNDE5MjI0LjY5NTg5OTA4NCwidyI6IjB4MzAzODExNjg2NzVhOWM5N2RiZWIxMDhiOGNkZTMzYWJhNDM0YmU0ZiJ9"
}
```

⚠ `sort=pnl` ranks `sum(closed_pnl)` — the &#x2A;*traders'** realized result, not the builder's. It is
signed, and a builder whose users lose money is a different business from one whose users win.


# /builders/{builder} (/docs/endpoints/data/hyperliquid/builders-builder)



```
GET https://data.vike.io/v1/hyperliquid/builders/{builder}
```

One builder: window totals plus per-asset and per-dex breakdowns, and an unwindowed `lifetime`
block that is what makes a 30-day window interpretable.

Truncated: `by_asset` and `by_dex` each returned 3 rows (`breakdown_limit=3`), and
`user_volume_distribution` returned all 10 deciles; one row of each breakdown and the first 2
deciles are shown. `totals` and `lifetime` are complete.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/builders/0xb84168cf3be63c6b8dad05ff5d755e97432ff80b?window=30d&breakdown_limit=3" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="builder" loc="path">
    Builder address
  </Param>

  <Param name="window" loc="query">
    `1d`

     \| 

    `7d`

     \| 

    `30d`

     \| 

    `all`

    . Default 

    `30d`
  </Param>

  <Param name="breakdown_limit" loc="query">
    Rows per breakdown. Default 100, max 1000
  </Param>
</Params>

```json title="Example response"
{
  "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b",
  "window": {
    "window": "30d",
    "start": "2026-08-04T08:06:57.246000+00:00",
    "end": "2026-09-03T08:06:57.246000+00:00"
  },
  "totals": {
    "fee_usd": 1292173.7512559998,
    "volume_usd": 2459698781.897407,
    "share_volume_usd": 2459698781.897407,
    "fills": 1276030,
    "users": 28785,
    "revenue_per_user": 44.8905246224075,
    "fee_rate_bps": 5.253382083879472,
    "fee_usd_node": 1292173.7512559998,
    "trader_fee_usd": 2179038.6845209985,
    "builder_routed_deployer_fee_usd": 32029.181042999997,
    "active_days": 31,
    "crossed_fills": 1264333,
    "taker_pct": 99.08332876186296,
    "first_seen": "2026-08-04T08:06:58.003000+00:00",
    "last_seen": "2026-09-03T08:06:53.487000+00:00",
    "fee_rate_bps_p50": 4.99999153161867,
    "trader_fee_rate_bps": 8.858965579680014,
    "routed_closed_pnl_usd": 5411823.867884997,
    "assets": 281,
    "dexes": 3,
    "buy_volume_usd": 1235042429.759386,
    "sell_volume_usd": 1224656352.1380203,
    "non_usd_fee_fills": 0,
    "non_usd_fee_volume_usd": 0.0,
    "profitable_users": 14950,
    "profitable_users_pct": 51.93677262463089,
    "market_share_pct": 0.4897971159612295,
    "venue_volume_usd": 502187273412.22394,
    "market_share_window_start": "2026-08-04T08:06:57.246000+00:00",
    "biggest_day": {
      "date": "2026-08-21",
      "fee_usd": 109113.4776180001,
      "volume_usd": 218226896.66830376,
      "fills": 94276,
      "users": 6570
    }
  },
  "by_asset": [
    {
      "asset": "BTC",
      "fee_usd": 509022.96058600006,
      "volume_usd": 1018046131.9743183,
      "share_volume_usd": 1018046131.9743183,
      "fills": 242890,
      "users": 14148,
      "revenue_per_user": 35.97843939680521,
      "fee_rate_bps": 4.9999989646720735,
      "fee_usd_node": 509022.96058600006,
      "trader_fee_usd": 926359.8724370012,
      "builder_routed_deployer_fee_usd": 0.0,
      "closed_pnl_usd": 853354.1283130016,
      "active_days": 31,
      "crossed_fills": 241199,
      "taker_pct": 99.30380007410761,
      "first_seen": "2026-08-04T08:07:07.023000+00:00",
      "last_seen": "2026-09-03T08:06:34.662000+00:00",
      "fee_rate_bps_p50": 4.999993656788234
    }
  ],
  "by_dex": [
    {
      "dex_name": "HL",
      "fee_usd": 988497.2047849979,
      "volume_usd": 1976995273.7509472,
      "share_volume_usd": 1976995273.7509472,
      "fills": 983697,
      "users": 25961,
      "revenue_per_user": 38.076237617387534,
      "fee_rate_bps": 4.99999781440815,
      "fee_usd_node": 988497.2047849979,
      "trader_fee_usd": 1804190.5380139945,
      "builder_routed_deployer_fee_usd": 0.0,
      "closed_pnl_usd": 3855774.905621013,
      "active_days": 31,
      "crossed_fills": 976935,
      "taker_pct": 99.31259320705462,
      "first_seen": "2026-08-04T08:07:07.023000+00:00",
      "last_seen": "2026-09-03T08:06:48.794000+00:00",
      "fee_rate_bps_p50": 4.999988076025987
    }
  ],
  "user_volume_distribution": [
    {
      "decile": 1,
      "users": 2879,
      "volume_usd": 86655.32764499992,
      "volume_share_pct": 0.0035230056738148317,
      "fee_usd": 45.37262100000003,
      "min_volume_usd": 0.003927,
      "max_volume_usd": 54.04912,
      "profitable_users": 875,
      "profitable_users_pct": 30.392497394928796,
      "closed_pnl_usd": 271.7052880000002
    },
    {
      "decile": 2,
      "users": 2879,
      "volume_usd": 275014.79240599985,
      "volume_share_pct": 0.01118083215839356,
      "fee_usd": 143.7351350000003,
      "min_volume_usd": 54.053650000000005,
      "max_volume_usd": 148.43142,
      "profitable_users": 1157,
      "profitable_users_pct": 40.187565126780136,
      "closed_pnl_usd": 1358.2858930000023
    }
  ],
  "lifetime": {
    "first_seen": "2025-06-12T01:30:06+00:00",
    "last_seen": "2026-09-03T08:06:53.487000+00:00",
    "active_days": 449,
    "fills": 20546541,
    "users": 169550,
    "fee_usd": 25097457.752429612,
    "volume_usd": 49197763660.69259,
    "revenue_per_user": 148.0239324826282
  }
}
```

⚠ `fee_rate_bps` is the **realized effective** rate (fee ÷ volume); the venue's configured
per-order rate is not in the data. `fee_rate_bps_p50` — the median across fills that actually paid
a builder fee — is the closest observable thing to an advertised rate, because 21% of rows pay the
builder nothing and drag the mean.

`user_volume_distribution` splits users into volume deciles, so "19k users" and "one whale plus a
tail" stop looking the same. `profitable_users` is a per-**wallet** test (`sum(closed_pnl) > 0`),
not a per-fill one: a wallet that won once and lost once is one loser.


# /builders/stats (/docs/endpoints/data/hyperliquid/builders-stats)



```
GET https://data.vike.io/v1/hyperliquid/builders/stats
```

Builder-code economics for the whole venue — how many builders are active, how many distinct
traders route through one, what share of all Hyperliquid fill notional carries a builder code, and
how that moved day by day. `lifetime.fee_usd` is all-time and unwindowed.

Truncated: `daily` holds **31** buckets; the first 2 are shown. `totals` and `lifetime` are complete.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/builders/stats?window=30d" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="window" loc="query">
    `1d`

     \| 

    `7d`

     \| 

    `30d`

     \| 

    `all`

    . Default 

    `30d`
  </Param>
</Params>

```json title="Example response"
{
  "window": {
    "window": "30d",
    "start": "2026-08-04T08:06:47.379000+00:00",
    "end": "2026-09-03T08:06:47.379000+00:00"
  },
  "totals": {
    "fee_usd": 8905954.222539285,
    "volume_usd": 21384665654.34212,
    "share_volume_usd": 21384665654.34212,
    "fills": 21464158,
    "users": 175990,
    "revenue_per_user": 50.60488790578604,
    "fee_rate_bps": 4.1646450622579385,
    "fee_usd_node": 8905954.222539285,
    "trader_fee_usd": 15342433.846149018,
    "builder_routed_deployer_fee_usd": 276863.60111752996,
    "active_days": 31,
    "crossed_fills": 15039788,
    "taker_pct": 70.06931275850653,
    "first_seen": "2026-08-04T08:06:47.689000+00:00",
    "last_seen": "2026-09-03T08:06:47.379000+00:00",
    "builders": 773,
    "assets": 1189,
    "routed_closed_pnl_usd": 40440208.459194675,
    "venue_volume_usd": 502186586606.7108,
    "builder_routed_share_pct": 4.258310800142816,
    "market_share_window_start": "2026-08-04T08:06:47.379000+00:00"
  },
  "lifetime": {
    "fee_usd": 102158419.77212027,
    "first_seen": "2024-10-27T18:15:13+00:00",
    "last_seen": "2026-09-03T08:06:47.379000+00:00"
  },
  "daily": [
    {
      "date": "2026-09-03",
      "builders": 313,
      "assets": 416,
      "fee_usd": 68310.92594833038,
      "volume_usd": 189551581.736281,
      "share_volume_usd": 189551581.736281,
      "fills": 314223,
      "users": 14027,
      "revenue_per_user": 4.869959788146459,
      "fee_rate_bps": 3.6038172471369765,
      "fee_usd_node": 68310.92594833038,
      "trader_fee_usd": 119872.31359066741,
      "builder_routed_deployer_fee_usd": 3257.024262140485,
      "crossed_fills": 193620,
      "taker_pct": 61.618659359754055,
      "routed_closed_pnl_usd": -173991.42875996322
    },
    {
      "date": "2026-09-02",
      "builders": 426,
      "assets": 519,
      "fee_usd": 243552.30523937644,
      "volume_usd": 649788619.894209,
      "share_volume_usd": 649788619.894209,
      "fills": 960364,
      "users": 31046,
      "revenue_per_user": 7.8448851781027,
      "fee_rate_bps": 3.748177450061049,
      "fee_usd_node": 243552.30523937644,
      "trader_fee_usd": 436195.37178474676,
      "builder_routed_deployer_fee_usd": 15056.07115401947,
      "crossed_fills": 606377,
      "taker_pct": 63.14033012482767,
      "routed_closed_pnl_usd": -550294.1408118871
    }
  ]
}
```

⚠ &#x2A;*`stats` is a reserved segment on this path.** `/builders/stats` is always this route, never a
[`/builders/{builder}`](/docs/endpoints/data/hyperliquid/builders-builder) lookup — a builder address is
a hex string, so nothing is shadowed, but do not expect `{builder}` to accept the literal `stats`.

No coverage start date is quoted here, and none should be: builder history is imported from
Hyperliquid's published per-builder fee CSVs and both the totals and the start move as that import
proceeds. Read `lifetime.first_seen` for the actual coverage start — a coverage date quoted in
prose here was measured 40% low and eight months stale within a day of being written.


# /builders (/docs/endpoints/data/hyperliquid/builders)



```
GET https://data.vike.io/v1/hyperliquid/builders
```

The builder-code leaderboard: fee revenue, routed volume, unique traders, fills, `market_share_pct`.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/builders?limit=3" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="window" loc="query">
    `1d`

     \| 

    `7d`

     \| 

    `30d`

     \| 

    `all`

    . Default 

    `30d`
  </Param>

  <Param name="sort" loc="query">
    `fee`

     \| 

    `volume`

     \| 

    `users`

     \| 

    `fills`

    . Default 

    `fee`
  </Param>

  <Param name="order" loc="query">
    `asc`

     \| 

    `desc`

    . Default 

    `desc`
  </Param>

  <Param name="limit" loc="query">
    Default 50, max 500
  </Param>

  <Param name="cursor" loc="query">
    Keyset cursor
  </Param>
</Params>

```json title="Example response"
{
  "window": {
    "window": "30d",
    "start": "2026-08-04T08:06:47.379000+00:00",
    "end": "2026-09-03T08:06:47.379000+00:00"
  },
  "sort": "fee",
  "order": "desc",
  "venue_volume_usd": 502186586606.7108,
  "market_share_window_start": "2026-08-04T08:06:47.379000+00:00",
  "builders": [
    {
      "builder": "0xe95a5e31904e005066614247d309e00d8ad753aa",
      "rank": 1,
      "fee_usd": 1499518.2846610104,
      "volume_usd": 1618501175.9291677,
      "share_volume_usd": 1618501175.9291677,
      "fills": 529981,
      "users": 9437,
      "revenue_per_user": 158.89777309113177,
      "fee_rate_bps": 9.264857554398438,
      "fee_usd_node": 1499518.2846610104,
      "trader_fee_usd": 1911054.1162650166,
      "builder_routed_deployer_fee_usd": 21187.156330000034,
      "closed_pnl_usd": 4617426.625648984,
      "active_days": 31,
      "crossed_fills": 495218,
      "taker_pct": 93.44070825180525,
      "first_seen": "2026-08-04T08:07:13.004000+00:00",
      "last_seen": "2026-09-03T08:06:41.614000+00:00",
      "market_share_pct": 0.32229080168497265,
      "first_seen_lifetime": "2025-08-19T22:14:56+00:00"
    },
    {
      "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b",
      "rank": 2,
      "fee_usd": 1292163.5658959982,
      "volume_usd": 2459678115.583188,
      "share_volume_usd": 2459678115.583188,
      "fills": 1276026,
      "users": 28783,
      "revenue_per_user": 44.8932899939547,
      "fee_rate_bps": 5.253384813685782,
      "fee_usd_node": 1292163.5658959982,
      "trader_fee_usd": 2179019.0573659376,
      "builder_routed_deployer_fee_usd": 32029.19622199984,
      "closed_pnl_usd": 5411672.672201046,
      "active_days": 31,
      "crossed_fills": 1264329,
      "taker_pct": 99.08332588834396,
      "first_seen": "2026-08-04T08:06:50.331000+00:00",
      "last_seen": "2026-09-03T08:06:34.662000+00:00",
      "market_share_pct": 0.4897936705564566,
      "first_seen_lifetime": "2025-06-12T01:30:06+00:00"
    },
    {
      "builder": "0x5af1b5f44207784dcb850bbb4143c5dcd1885f71",
      "rank": 3,
      "fee_usd": 1061419.7763880126,
      "volume_usd": 1460325459.6318128,
      "share_volume_usd": 1460325459.6318128,
      "fills": 440461,
      "users": 9616,
      "revenue_per_user": 110.38059238644057,
      "fee_rate_bps": 7.268378219302051,
      "fee_usd_node": 1061419.7763880126,
      "trader_fee_usd": 1565598.9851990165,
      "builder_routed_deployer_fee_usd": 29707.97636299997,
      "closed_pnl_usd": 4744467.146989997,
      "active_days": 31,
      "crossed_fills": 429636,
      "taker_pct": 97.5423476766388,
      "first_seen": "2026-08-04T08:06:49.661000+00:00",
      "last_seen": "2026-09-03T08:06:47.072000+00:00",
      "market_share_pct": 0.29079340201005244,
      "first_seen_lifetime": "2026-04-09T17:31:47.951000+00:00"
    }
  ],
  "nextCursor": "eyJiIjoiMHg1YWYxYjVmNDQyMDc3ODRkY2I4NTBiYmI0MTQzYzVkY2QxODg1ZjcxIiwiaGkiOiIyMDI2LTA5LTAzVDA4OjA2OjQ3LjM3OTAwMCswMDowMCIsImxvIjoiMjAyNi0wOC0wNFQwODowNjo0Ny4zNzkwMDArMDA6MDAiLCJyIjozLCJ2IjoxMDYxNDE5Ljc3NjM4ODAxMjZ9"
}
```

`sort=fee` ranks the builder's own cut, not the trader's total cost, and the two orderings differ
materially — take rates range from roughly 0.2 bps to 3.4 bps across the top of the board.

⚠ &#x2A;*`market_share_pct` is measured over an overlap window that can start later than yours.** Its
denominator is all Hyperliquid fill notional, whose history is shorter than the builder-fill
history — the latter reaches months further back via Hyperliquid's published CSVs. That gap is
permanent, not a backlog, so the share is taken from `market_share_window_start` to `window.end`.
To audit it, divide the per-row `share_volume_usd` (the clamped numerator) by the top-level
`venue_volume_usd`. &#x2A;*Do not use `volume_usd`** — that is the row's full unclamped notional for the
requested window, so on `window=all` it can exceed the numerator by more than 2x.

⚠ `active_days` is on every row because the historical backfill of builder fills is still
running: a long window can currently cover fewer days than it names, and `active_days` beside the
resolved `window.start`/`window.end` is how you tell a quiet builder from an unfilled window.
`first_seen_lifetime` is **not** window-scoped (`first_seen` is) — it is the builder's genuine
first fill. Every `*_pct` field here is percentage points, 0–100.

The three fee columns are not interchangeable — see
[Builders](/docs/endpoints/data/hyperliquid#builders).


# /cohorts (/docs/endpoints/data/hyperliquid/cohorts)



```
GET https://data.vike.io/v1/hyperliquid/cohorts
```

The canonical cohort ladders as flat label sets — the exact strings `?cohort=` accepts. Takes no
parameters. The shape is `{"size": [...12], "pnl": [...12, "unknown"], "tier": [...10]}`, and it is
served from the same label set `?cohort=` is validated against — so a label is accepted on its axis
if and only if it appears here.

`unknown` rides the `pnl` set because it is a real, queryable bucket there (wallets under 10 closed
trades), not a rung of the ladder.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/cohorts" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

```json title="Example response"
{
  "size": [
    "4x whale",
    "3x whale",
    "2x whale",
    "whale",
    "2x shark",
    "shark",
    "2x dolphin",
    "dolphin",
    "2x fish",
    "fish",
    "2x shrimp",
    "shrimp"
  ],
  "pnl": [
    "3x smart",
    "2x smart",
    "smart",
    "3x winner",
    "2x winner",
    "winner",
    "loser",
    "2x loser",
    "3x loser",
    "rekt",
    "2x rekt",
    "3x rekt",
    "unknown"
  ],
  "tier": [
    ">$2.5m",
    "$1m-$2.5m",
    "$500k-$1m",
    "$250k-$500k",
    "$100k-$250k",
    "$50k-$100k",
    "$25k-$50k",
    "$10k-$25k",
    "$1k-$10k",
    "<$1k"
  ]
}
```

⚠ &#x2A;*`pnl_abs` is a valid `axis=` and is *not* in this response.** `/cohorts` publishes three
ladders; the dollar-banded `pnl_abs` ladder is published by
[`/segments`](/docs/endpoints/data/hyperliquid/segments) only. A client that enumerates axes from this
endpoint will miss it.


# /coins/{coin}/cohort-metrics (/docs/endpoints/data/hyperliquid/coins-coin-cohort-metrics)



```
GET https://data.vike.io/v1/hyperliquid/coins/{coin}/cohort-metrics
```

The full cohort matrix for one coin — every bucket on an axis, hourly.
[`/coins/{coin}/metrics`](/docs/endpoints/data/hyperliquid/coins-coin-metrics) returns one row per hour
for a single cohort or for all of them summed; rebuilding the matrix from it costs one request per
cohort (12 for `size`, 13 for `pnl`). This returns all of them in one.

Truncated: `metrics` holds **72** rows — 6 hourly buckets x 12 `size` cohorts, which is the matrix
this endpoint exists to return in one call; the first 2 are shown.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/coins/BTC/cohort-metrics?axis=size&hours=6" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="coin" loc="path">
    HL coin ticker
  </Param>

  <Param name="axis" loc="query">
    `size`

     \| 

    `pnl`

     \| 

    `pnl_abs`

     \| 

    `tier`

     \| 

    `pnl_unrealized`

    . Default 

    `size`
  </Param>

  <Param name="start` / `end" loc="query">
    ISO-8601 UTC bounds
  </Param>

  <Param name="openedWithin" loc="query">
    `24h`

     \| 

    `7d`

     \| 

    `30d`

     \| 

    `all`

    . Default 

    `all`
  </Param>

  <Param name="hours" loc="query">
    Number of hourly buckets. Default 168, max 8760
  </Param>

  <Param name="cursor" loc="query">
    Cursor over 

    **hours**
  </Param>

  <Param name="grading" loc="query">
    `realized`

     \| 

    `realized-pit`

     \| 

    `unrealized`

    . Refused on 

    `size`

    , 

    `tier`

    , 

    `pnl_abs`
  </Param>

  <Param name="labelBasis" loc="query">
    `current`

     \| 

    `point_in_time`

    . Default depends on the axis
  </Param>
</Params>

```json title="Example response"
{
  "axis": "size",
  "label_basis": "point_in_time",
  "metrics": [
    {
      "ts": "2026-09-03T07:00:00+00:00",
      "cohort": "4x whale",
      "position_count": 20,
      "position_count_long": 6,
      "total_position_value": 704156131.5,
      "total_position_value_long": 182556075.6,
      "total_unrealized_pnl": -24295055.1,
      "total_position_size": 9061.33228,
      "total_position_size_long": 2349.1967,
      "bias": -0.4814897793,
      "label_basis": "point_in_time",
      "grading": null
    },
    {
      "ts": "2026-09-03T07:00:00+00:00",
      "cohort": "3x whale",
      "position_count": 26,
      "position_count_long": 14,
      "total_position_value": 265561588.5,
      "total_position_value_long": 171376394.8,
      "total_unrealized_pnl": 20255408.17,
      "total_position_size": 3417.34125,
      "total_position_size_long": 2205.33258,
      "bias": 0.2906715594,
      "label_basis": "point_in_time",
      "grading": null
    }
  ],
  "hours": 6,
  "nextCursor": "eyJtIjoiY29ob3J0X21ldHJpY3MiLCJ0IjoiMjAyNi0wOS0wMyAwMjowMDowMCJ9",
  "grading": null,
  "freshness": {
    "newest_ts": "2026-09-03T07:00:00+00:00",
    "behind_hours": 1,
    "settled_lag_ceiling_hours": 3,
    "stale": false
  }
}
```

**Paginated by hour, not by row.** A row limit would cut a bucket in half and return an hour whose
cohorts do not sum to its total. `hours` bounds the buckets; every cohort in a returned bucket comes
with it.

**No `provisional` row here.** This is bulk history, and a partial hour inside a matrix that will
be differenced or z-scored produces a fake move at the right edge. Use
[`/coins/{coin}/metrics`](/docs/endpoints/data/hyperliquid/coins-coin-metrics) for the current value.

`axis=tier` is the per-position ladder — each row's own notional bucket, derived from its
`size_usd`, largest first: `>$2.5m`, `$1m-$2.5m`, `$500k-$1m`, `$250k-$500k`, `$100k-$250k`,
`$50k-$100k`, `$25k-$50k`, `$10k-$25k`, `$1k-$10k`, `<$1k`. It is a grouping **only here**, because
this endpoint aggregates position rows and each row sits in exactly one bucket; the per-wallet
endpoints keep rejecting it.

<Callout type="warn" title="The default labelling is lookahead for a backtest">
  By default the `pnl` cohort is resolved from the dictionary **at query time**, so a historical row
  carries today's grading. That is correct for "who is smart right now" and **wrong for a backtest**,
  because a wallet under the 10-closed-trade floor back then may be graded now. Pass
  `labelBasis=point_in_time` for each row's label as it was that hour.

  The point-in-time response then **omits five fields**, listed in `unavailable_fields`:
  `position_count`, `position_count_long`, `total_unrealized_pnl`, `total_position_size` and
  `total_position_size_long` — the frozen source does not carry them.

  `label_computed.lookahead` on the envelope states which of the two you got. Do not infer it.
</Callout>

**What each `grading` selects:**

* `grading=realized` (the default on `axis=pnl`) — the percentile ladder over cumulative realized
  PnL. With the default `labelBasis` this is resolved at query time and `label_computed.lookahead`
  is **true**. With `labelBasis=point_in_time` it is the frozen ladder, and `label_computed` names
  a **2026-08-06 seam**: before it the labels come from the 2026-08-17 point-in-time rebuild (daily
  resolution), from it they come from the row's own hourly column. Both halves are honest, but a
  series crossing the seam changes label *resolution* — a turnover count will read that as a regime
  change that is an artefact.
* `grading=realized-pit` — the same ladder graded point-in-time across the **whole** window (day D
  on the cumulative as of the end of D−1), which is what makes it the control for a study crossing
  that seam.
* `grading=unrealized` — "currently onside": hour H's rank over the wallet's last snapshot strictly
  before H. `axis=pnl_unrealized` is the legacy spelling of exactly this and keeps working; both
  reach one branch.

`realized-pit` and `unrealized` refuse `labelBasis=current` rather than silently overriding it.

<Callout type="warn" title="Read the age off freshness.behind_hours, never off a number in prose">
  On any window that reaches the present the envelope carries
  `{newest_ts, behind_hours, settled_lag_ceiling_hours, stale}`. `stale` is the pre-computed verdict,
  so a consumer does not have to re-derive the rollup's cadence.

  It exists because prose was not enough. `grading=realized-pit` reads a **frozen research
  artefact**: nothing has written to it since 2026-08-16 19:00 UTC. Ask it for an explicit recent
  window and it honestly answers with zero rows — but ask it the way a poller does
  (`?grading=realized-pit&hours=1`, no `start`) and it returns its own newest bucket, **identical in
  shape to a current one**, and days old. That gap is not a constant: it grows by 24 hours a day.

  For live trading use `grading=realized` with `labelBasis=point_in_time` — honest labels, and one
  hour behind the clock rather than days.

  A window ending in the **past** gets no `freshness` block at all: "the newest bar is four months
  old" answers a question a historical query did not ask, and would make every backtest fetch look
  broken.
</Callout>

⚠ &#x2A;*`axis=pnl_unrealized` grades positioning, not skill.** Each wallet is ranked by the unrealized
PnL of its open positions as a share of account value, over its last snapshot strictly before hour
H. That grading turns over about **44% of wallets per day** against the realized ladder's &#x2A;*2.4%**
— which is the point: it is a different axis, not a re-spelling. Twelve rungs, no `unknown`
(eligibility is a positive-equity snapshot, not a trade count), the same five omitted fields as the
frozen `pnl` source, coverage from 2026-04-04 with a known three-day hole (2026-06-28 to 06-30,
graded off days whose equity feed was down). It is **hourly**, and has been since the rollup moved
on 2026-08-19; anything describing it as a daily grading is stale.


# /coins/{coin}/liquidation-heatmap (/docs/endpoints/data/hyperliquid/coins-coin-liquidation-heatmap)



```
GET https://data.vike.io/v1/hyperliquid/coins/{coin}/liquidation-heatmap
```

Where liquidations *would* cluster if price moved: every open position's own liquidation price,
binned and weighted by notional.

Truncated: `bins` holds **10** rows (`bins=10`); the first 3 are shown. `window` and `coverage` are
complete.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/coins/BTC/liquidation-heatmap?bins=10" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="coin" loc="path">
    HL coin ticker
  </Param>

  <Param name="bins" loc="query">
    Number of price bins. Default 50, min 5, max 500
  </Param>
</Params>

```json title="Example response"
{
  "coin": "BTC",
  "mark_price": 78011.0,
  "snapshot_ts": "2026-09-03T07:44:00+00:00",
  "bins": [
    {
      "price_bin_index": 0,
      "price_bin_start": 39005.5,
      "price_bin_end": 46806.6,
      "liquidation_value_usd": 136593494.62892,
      "positions_count": 1669,
      "long_value_usd": 136338635.03225002,
      "short_value_usd": 254859.59667000003,
      "most_impacted_cohort": "whale"
    },
    {
      "price_bin_index": 1,
      "price_bin_start": 46806.6,
      "price_bin_end": 54607.7,
      "liquidation_value_usd": 235951565.08872,
      "positions_count": 2492,
      "long_value_usd": 235829551.98417,
      "short_value_usd": 122013.10455,
      "most_impacted_cohort": "4x whale"
    },
    {
      "price_bin_index": 2,
      "price_bin_start": 54607.7,
      "price_bin_end": 62408.8,
      "liquidation_value_usd": 118453087.38709,
      "positions_count": 2373,
      "long_value_usd": 118391459.4772,
      "short_value_usd": 61627.909889999995,
      "most_impacted_cohort": "whale"
    }
  ],
  "total_value_usd": 1975949798.55437,
  "cohort_axis": "size",
  "window": {
    "price_low": 39005.5,
    "price_high": 117016.5,
    "range_pct": 0.5,
    "bin_width": 7801.1,
    "spacing": "linear"
  },
  "coverage": {
    "open_value_usd": 3034690460.1413383,
    "open_positions": 36192,
    "no_liq_price_value_usd": 104748153.91258995,
    "no_liq_price_positions": 5383,
    "outside_window_value_usd": 953992507.6743784,
    "in_window_fraction_of_open": 0.6511207072046292,
    "in_window_fraction_of_priced": 0.6743988761668478
  }
}
```

⚠ This is **hypothetical**, not realized — it is the standing risk on the book right now, not a
record of anything that happened. [`/liquidations`](/docs/endpoints/data/hyperliquid/liquidations) is
the realized surface.

(Its path lives under `/coins/`, but it answers a liquidations question rather than a positioning
one, which is why it is filed here rather than beside the other `/coins/` routes.)


# /coins/{coin}/metrics (/docs/endpoints/data/hyperliquid/coins-coin-metrics)



```
GET https://data.vike.io/v1/hyperliquid/coins/{coin}/metrics
```

Hourly open-interest / position-count / bias series for one coin, optionally sliced to a single
cohort. This is the **current-value** endpoint;
[`/cohort-metrics`](/docs/endpoints/data/hyperliquid/coins-coin-cohort-metrics) is the bulk-history one.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/coins/BTC/metrics?limit=3" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="coin" loc="path">
    HL coin ticker
  </Param>

  <Param name="start` / `end" loc="query">
    ISO-8601 UTC bounds
  </Param>

  <Param name="axis" loc="query">
    `size`

     \| 

    `pnl`

     \| 

    `pnl_abs`

    . 

    **Omit for all cohorts combined**
  </Param>

  <Param name="cohort" loc="query">
    One label on that axis
  </Param>

  <Param name="openedWithin" loc="query">
    `24h`

     \| 

    `7d`

     \| 

    `30d`

     \| 

    `all`

    . Default 

    `all`
  </Param>

  <Param name="limit" loc="query">
    Default 500, max 5000
  </Param>

  <Param name="cursor" loc="query">
    Keyset cursor
  </Param>

  <Param name="labelBasis" loc="query">
    `current`

     only — see the refusal below
  </Param>
</Params>

```json title="Example response"
{
  "axis": "size",
  "label_basis": "point_in_time",
  "metrics": [
    {
      "ts": "2026-09-03T07:59:00+00:00",
      "position_count": 36124,
      "position_count_long": 22181,
      "total_position_value": 3009666609.0,
      "total_position_value_long": 1504833304.0,
      "total_unrealized_pnl": -25275224.09,
      "total_position_size": 38729.4635,
      "total_position_size_long": 19364.73175,
      "bias": -2.376528135E-16,
      "provisional": true,
      "label_basis": "point_in_time"
    },
    {
      "ts": "2026-09-03T07:00:00+00:00",
      "position_count": 37385,
      "position_count_long": 22704,
      "total_position_value": 3040705315.0,
      "total_position_value_long": 1524148585.0,
      "total_unrealized_pnl": -25163932.39,
      "total_position_size": 39127.71343,
      "total_position_size_long": 19612.467,
      "bias": 0.002496741284,
      "provisional": false,
      "label_basis": "point_in_time"
    },
    {
      "ts": "2026-09-03T06:00:00+00:00",
      "position_count": 36982,
      "position_count_long": 22508,
      "total_position_value": 3038908973.0,
      "total_position_value_long": 1518681456.0,
      "total_unrealized_pnl": -25099074.21,
      "total_position_size": 39060.76211,
      "total_position_size_long": 19520.44664,
      "bias": -0.0005087549732,
      "provisional": false,
      "label_basis": "point_in_time"
    },
    {
      "ts": "2026-09-03T05:00:00+00:00",
      "position_count": 37127,
      "position_count_long": 22594,
      "total_position_value": 3009207480.0,
      "total_position_value_long": 1496950278.0,
      "total_unrealized_pnl": -25051797.85,
      "total_position_size": 38755.01536,
      "total_position_size_long": 19278.62806,
      "bias": -0.005086696384,
      "provisional": false,
      "label_basis": "point_in_time"
    }
  ],
  "nextCursor": "eyJtIjoibWV0cmljcyIsInQiOiIyMDI2LTA5LTAzIDA1OjAwOjAwIn0"
}
```

`openedWithin` is **rolling per bucket, not relative to now**: each hour counts positions opened in
the window before *that* hour.

Hourly by construction. Summing the 5-minute snapshot table into hour buckets over-counts open
interest roughly 12x, which is what forced the previous cohort aggregate to be rebuilt.

⚠ **Every row carries `provisional`, and it is `true` on at most one of them** — the newest,
covering the hour still in progress. The hourly rollup lands 60–120 minutes late, so without that
row a "current positioning" read would be silently that stale. Its `ts` is a snapshot instant
rather than an hour boundary and it changes on every poll: &#x2A;*drop it when persisting a series.** It
is present only on the first page of a window reaching the present.

<Callout type="warn" title="This endpoint refuses labelBasis=point_in_time by name">
  Its cohort label is resolved from the wallet dictionary at **query time**, so every historical hour
  it returns carries today's grading. Measured 2026-04-20T12:00Z on BTC's `3x smart` bucket:
  938,495,920.6 of notional against 861,706,562.3 under the point-in-time labelling of the same hour
  — **8.91% inflated**. The 400 names
  [`/coins/{coin}/cohort-metrics`](/docs/endpoints/data/hyperliquid/coins-coin-cohort-metrics) with
  `axis=pnl&labelBasis=point_in_time`, which reads the frozen ladder.

  It refuses rather than serving it because the frozen column is 0% filled before 2026-08-06 and this
  endpoint's whole value is the long window: answering recent hours only would silently truncate some
  windows and not others.

  ⚠ **Before 2026-08-19 this route accepted no `labelBasis` at all**, and an unrecognised query
  parameter was ignored rather than refused — so `?labelBasis=point_in_time` returned **HTTP 200 with
  lookahead rows**. A caller who explicitly asked for the honest labelling was told yes and given the
  contaminated answer. If you have stored results from that period, they carry today's grading
  regardless of what you asked for. The refusal exists so that can no longer happen silently.
</Callout>


# /coins/{coin}/size-breakdown (/docs/endpoints/data/hyperliquid/coins-coin-size-breakdown)



```
GET https://data.vike.io/v1/hyperliquid/coins/{coin}/size-breakdown
```

Positioning for one coin split by the canonical ten position-size buckets — the same ladder,
spellings and bounds as
[`axis=tier` on `/coins/{coin}/cohort-metrics`](/docs/endpoints/data/hyperliquid/coins-coin-cohort-metrics).
Empty buckets come back zero-filled so the table shape is stable.

Truncated: the array holds all **10** tiers, largest first; the first 3 are shown.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/coins/BTC/size-breakdown" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="coin" loc="path">
    HL coin ticker
  </Param>
</Params>

```json title="Example response"
[
  {
    "tier": ">$2.5m",
    "min_size": 2500000.0,
    "max_size": null,
    "position_count": 177,
    "total_position_value": 2115975888.0,
    "total_position_value_long": 1033347966.0,
    "value_close_to_liquidation": 41070622.45,
    "bias": -0.02328946914
  },
  {
    "tier": "$1m-$2.5m",
    "min_size": 1000000.0,
    "max_size": 2500000.0,
    "position_count": 183,
    "total_position_value": 292004085.3,
    "total_position_value_long": 146257572.2,
    "value_close_to_liquidation": 17869289.39,
    "bias": 0.001750177871
  },
  {
    "tier": "$500k-$1m",
    "min_size": 500000.0,
    "max_size": 1000000.0,
    "position_count": 237,
    "total_position_value": 162494247.6,
    "total_position_value_long": 91367908.78,
    "value_close_to_liquidation": 10808042.57,
    "bias": 0.1245679168
  }
]
```

No query parameters.


# /heatmap (/docs/endpoints/data/hyperliquid/heatmap)



```
GET https://data.vike.io/v1/hyperliquid/heatmap
```

The coin × cohort positioning matrix — the whole board in one call.

Truncated: `heatmap` holds **313** coins and the full response is **879,265 bytes** — worth knowing
before you call the whole board in one request. One coin with the first 2 of its 12 segments is
shown; `totals` is complete. A coin carries only the cohorts that actually hold it, so the per-coin
segment count ranges from 2 to 12 across this response.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/heatmap?axis=size" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="axis" loc="query">
    `size`

     \| 

    `pnl`

     \| 

    `pnl_abs`

    . Default 

    `size`

    . 

    `trade_size`

     is rejected
  </Param>

  <Param name="openedWithin" loc="query">
    `24h`

     \| 

    `7d`

     \| 

    `30d`

     \| 

    `all`

    . Default 

    `all`
  </Param>
</Params>

```json title="Example response"
{
  "axis": "size",
  "opened_within": "all",
  "snapshot_ts": "2026-09-03T08:04:00Z",
  "source": "latest position snapshot",
  "totals": {
    "total_value": 13836781540.0,
    "total_long_value": 6925016569.0,
    "total_short_value": 6911764971.0,
    "bias": 0.0009577081042,
    "count": 359587,
    "n_coins": 313,
    "n_wallets": 123747,
    "n_wallets_source": "precomputed totals"
  },
  "heatmap": [
    {
      "coin": "BTC",
      "total_value": 3026943358.0,
      "total_long_value": 1518666445.0,
      "total_short_value": 1508276913.0,
      "count": 36436,
      "count_long": 22334,
      "count_short": 14102,
      "n_wallets": 36348,
      "bias": 0.003432351074,
      "segments": [
        {
          "cohort": "4x whale",
          "rank": 1,
          "total_value": 704160990.8,
          "total_long_value": 182556075.6,
          "total_short_value": 521604915.2,
          "count": 21,
          "count_long": 6,
          "count_short": 15,
          "n_wallets": 20,
          "bias": -0.4814933575,
          "share_of_coin": 0.23263104313286428
        },
        {
          "cohort": "3x whale",
          "rank": 2,
          "total_value": 295869139.7,
          "total_long_value": 203749222.9,
          "total_short_value": 92119916.83,
          "count": 26,
          "count_long": 15,
          "count_short": 11,
          "n_wallets": 26,
          "bias": 0.3772928335,
          "share_of_coin": 0.0977451854207464
        }
      ]
    }
  ]
}
```

Per-wallet ladders only — this groups wallets, and a wallet straddles position-size buckets. Check
the `groupable` field on [`/segments`](/docs/endpoints/data/hyperliquid/segments).


# /hype/holders (/docs/endpoints/data/hyperliquid/hype-holders)



```
GET https://data.vike.io/v1/hyperliquid/hype/holders
```

The HYPE holder leaderboard — spot balance plus staked, per wallet. A wallet appearing in only one
of the two sources is still a holder, so the two are unioned rather than joined.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/hype/holders?limit=3" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="order" loc="query">
    `asc`

     \| 

    `desc`

    . Default 

    `desc`
  </Param>

  <Param name="limit" loc="query">
    Default 100, max 500
  </Param>

  <Param name="cursor" loc="query">
    Keyset cursor
  </Param>
</Params>

```json title="Example response"
{
  "holders": [
    {
      "wallet": "0x43e9abea1910387c4292bca4b94de81462f8a251",
      "rank": 1,
      "spot_amount": 3.00327328,
      "spot_amount_usd": 246.15128130208,
      "staked_amount": 241107400.82591507,
      "staked_amount_usd": 19761403679.092823,
      "total_amount": 241107403.82918835,
      "total_amount_usd": 19761403925.244106,
      "account_value": 0.0,
      "size_cohort": null,
      "pnl_cohort": "unknown"
    },
    {
      "wallet": "0xd57ecca444a9acb7208d286be439de12dd09de5d",
      "rank": 2,
      "spot_amount": 4.4E-7,
      "spot_amount_usd": 0.00003606284,
      "staked_amount": 60365562.87615384,
      "staked_amount_usd": 4947621898.892445,
      "total_amount": 60365562.87615428,
      "total_amount_usd": 4947621898.892481,
      "account_value": 0.0,
      "size_cohort": null,
      "pnl_cohort": "unknown"
    },
    {
      "wallet": "0x2222222222222222222222222222222222222222",
      "rank": 3,
      "spot_amount": 54535484.50059421,
      "spot_amount_usd": 4469782845.153202,
      "staked_amount": 0.0,
      "staked_amount_usd": 0.0,
      "total_amount": 54535484.50059421,
      "total_amount_usd": 4469782845.153202,
      "account_value": 0.0,
      "size_cohort": null,
      "pnl_cohort": "unknown"
    }
  ],
  "hype_price_usd": 81.961,
  "label_basis": "current",
  "label_computed": {
    "grading": "realized",
    "label_basis": "current",
    "when": "at query time",
    "lookahead": false,
    "source": "live wallet realized-PnL ladder",
    "detail": "Balances are last-known FINAL state and the label is resolved now: row and label are both 'now'. There is no time axis here, so a current label cannot contaminate an earlier row — the lookahead hazard the liquidation listing declares does not exist on this shape.",
    "caveat": "Balances are last-known, not simultaneous: each wallet carries whatever its most recent poll saw, so a stale balance can sit beside a fresh label."
  },
  "nextCursor": "eyJyYW5rIjozLCJ0b3RhbCI6NTQ1MzU0ODQuNTAwNTk0MjEsInciOiIweDIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIifQ"
}
```

`rank` is position in the **requested** ordering: 1 is the largest holder under `order=desc` and
the smallest under `order=asc`.

⚠ &#x2A;*Balances are last-known and the USD column is not.** The USD figure applies a single current
HYPE price to every row rather than each row's own recorded `mark_price` — a wallet last polled in
June would otherwise carry a June price and the column would be non-comparable row to row. The
balance itself is still whatever was last seen, so a stale balance can sit beside a fresh price.
Staked balance is `amount_delegated` only; `pending_rewards` is excluded because it is 0 across the
whole table today, and folding it in would silently change the definition the day it stops being 0.

`pnl_cohort` here is resolved at query time and the envelope says so (`label_basis: "current"` plus
`label_computed`). That is correct rather than a fallback: the leaderboard has no time axis, so
there is no earlier row for a current label to contaminate.


# Hyperliquid REST (/docs/endpoints/data/hyperliquid)



Thirty-five operations, every one a `GET`, all under `https://data.vike.io/v1/hyperliquid/`.
This is the largest namespace in the API by some distance, and the only one with per-wallet
history: who holds what, at what entry, with what realized PnL.

Every path in this namespace is written &#x2A;*relative to `https://data.vike.io/v1/hyperliquid`**. The
fenced line at the top of each endpoint's page carries the full path.

## Before you call anything [#before-you-call-anything]

**Auth.** `X-API-Key: vk_...` or `Authorization: Bearer vk_oat_...`; either alone is enough. See
[Authentication](/docs/data/authentication). Every call spends one unit of the shared hourly counter —
see [Rate limits](/docs/data/rate-limits).

**Errors.** Every route in this namespace maps failures the same way: input the service rejected is
a **400**, an upstream data failure is a **503**, and a rate-limit trip is a **429**. A failure is
never reported as a 200 with an empty body — a silent empty list is indistinguishable from "no
data", which is how bad backfills get built on top of an outage. See [Errors](/docs/data/errors).

**Pagination is keyset, not offset.** The position-snapshot history is 7.3 billion rows and the
fill history 1.07 billion; an offset re-reads and discards every skipped row, so deep pages cost
linearly more and a concurrent insert shifts rows across page boundaries. Every list route returns
`nextCursor` — **pass it back verbatim**, do not construct one.

**Aggregates are snapped to a canonical precision before they leave.** A large floating-point sum
is not reproduced bit-for-bit run to run, so without that step two identical requests could come
back differing in their last digits. Snapping them is what makes a response safe to cache, diff or
content-address.

<Callout type="warn" title="Where a documented bound and the real one disagree, the real one wins">
  Two routes in this namespace advertise a bound that the service then clamps harder:
  [`/traders`](/docs/endpoints/data/hyperliquid/traders) documents `size` up to 100 and caps it at 20, and
  [`/positions/match`](/docs/endpoints/data/hyperliquid/positions-match) documents `limit` up to 500 and
  caps it at 50. Both are noted on their own pages. A request above the effective cap is not
  rejected — it is silently served at the cap.
</Callout>

## The cohort vocabulary [#the-cohort-vocabulary]

Four query parameters recur across this namespace and mean specific things. Getting them wrong is
the most expensive mistake available here, because most of the wrong answers are **200s**.

### `axis` — which ladder buckets a wallet [#axis--which-ladder-buckets-a-wallet]

The general routes accept `size`, `pnl` and `pnl_abs`;
[`/coins/{coin}/cohort-metrics`](/docs/endpoints/data/hyperliquid/coins-coin-cohort-metrics) accepts two
more.

| Axis             | What it buckets                                                                                                                                  | Where accepted                      |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------- |
| `size`           | Absolute-$ account-value tier. A stored column, so always point-in-time.                                                                         | Everywhere an `axis=` exists        |
| `pnl`            | **Percentile rank** of a wallet's cumulative realized PnL. A dictionary lookup, not a column; `unknown` below 10 closed trades.                  | Everywhere                          |
| `pnl_abs`        | The *same* cumulative realized PnL banded in **dollars** (`$1m+` … `<-$1m`). Always resolved at query time — no frozen source exists.            | Everywhere                          |
| `tier`           | The per-**position** notional bucket, derived from the row's `size_usd`.                                                                         | `/coins/{coin}/cohort-metrics` only |
| `pnl_unrealized` | Rank by unrealized PnL of open positions as a share of account value — "currently onside".                                                       | `/coins/{coin}/cohort-metrics` only |
| `trade_size`     | Published by `/segments` as a real ladder, but **rejected as `axis=` everywhere** — a wallet straddles buckets. Filter on the `groupable` field. | Nowhere                             |

<Callout type="warn" title="pnl and pnl_abs band the same number and are not comparable">
  They are a re-labelling of one quantity, not two measurements — which is why the catalogue reports
  a distinct `basis` string for each. One ladder's `$100k-$1m` and the other's `smart` are not the
  same population. A client porting from a competitor whose PnL cohorts are absolute-dollar bands
  must read [`/segments`](/docs/endpoints/data/hyperliquid/segments) rather than assume the boundaries:
  the bucket *names* are similar and the *definitions* are not. The unrealized-PnL ladder that used
  to back `axis=pnl` was dropped 2026-08-03.
</Callout>

### `cohort` — one bucket on that ladder [#cohort--one-bucket-on-that-ladder]

[`/cohorts`](/docs/endpoints/data/hyperliquid/cohorts) returns the exact strings `?cohort=` accepts, and
it is generated from the same label set `?cohort=` is validated against, so a label listed here
is a label the parameter accepts. Slugs from [`/segments`](/docs/endpoints/data/hyperliquid/segments) are
accepted too. The retired `micro`/`small`/`medium`/`large`/`mega` vocabulary is gone: sending one
gets a 400 naming its replacement rather than a generic refusal.

### `labelBasis` — *when* the label was computed [#labelbasis--when-the-label-was-computed]

`current` (resolved from the wallet dictionary at query time) or `point_in_time` (the label as it
stood in that row's own hour). Three axes are fixed and reject a conflicting value rather than
silently overriding it: `size`, `tier` and `pnl_unrealized` are always `point_in_time`; `pnl_abs`
is always `current`.

### `grading` — *which* PnL ladder does the labelling [#grading--which-pnl-ladder-does-the-labelling]

`realized` | `realized-pit` | `unrealized`, on
[`/coins/{coin}/cohort-metrics`](/docs/endpoints/data/hyperliquid/coins-coin-cohort-metrics) only, and
refused on the axes that rank no PnL (`size`, `tier`, `pnl_abs`).

<Callout type="warn" title="grading and labelBasis are independent">
  A grading name is neutral by design — `realized` does not say whether the label is today's or the
  hour's. That is why every response carries a `label_computed` block on the envelope and on every
  row: the name is not allowed to travel alone.
</Callout>

***

## Wallets [#wallets]

Seven routes. `{address}` is a Hyperliquid wallet address.

| Path                                                                                              | What it answers                                                                                                                             |
| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| [`/wallets/{address}`](/docs/endpoints/data/hyperliquid/wallets-address)                               | One wallet in one call: equity, its cohort labels on each ladder, the risk-metric set, lifetime external flow and the open-positions block. |
| [`/wallets/{address}/trades`](/docs/endpoints/data/hyperliquid/wallets-address-trades)                 | Closed round-trip trades for one wallet, newest first, cursor-paged.                                                                        |
| [`/wallets/{address}/trades/summary`](/docs/endpoints/data/hyperliquid/wallets-address-trades-summary) | Trade statistics for one wallet, overall **and per coin**.                                                                                  |
| [`/wallets/{address}/fills`](/docs/endpoints/data/hyperliquid/wallets-address-fills)                   | Raw fills — the level below round-trip trades.                                                                                              |
| [`/wallets/{address}/funding`](/docs/endpoints/data/hyperliquid/wallets-address-funding)               | Funding paid and received by one wallet.                                                                                                    |
| [`/wallets/{address}/ledger`](/docs/endpoints/data/hyperliquid/wallets-address-ledger)                 | Deposits, withdrawals, transfers and vault events.                                                                                          |
| [`/wallets/{address}/builders`](/docs/endpoints/data/hyperliquid/wallets-address-builders)             | Reverse lookup: which builders this wallet's flow is routed through.                                                                        |

***

## Builders [#builders]

A builder is a front-end or bot that attaches its address to an order and is paid a slice of the
taker fee for it. Six routes over builder-routed fills.

<Callout type="warn" title="Three fee columns, none interchangeable">
  `fee_usd` is the builder's **own revenue**. `trader_fee_usd` is the **total the trader paid**.
  `builder_routed_deployer_fee_usd` is the deployer's cut **on builder-routed flow only** — a lower
  bound on deployer revenue, never the whole of it.
</Callout>

| Path                                                                                | What it answers                                                                                       |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| [`/builders`](/docs/endpoints/data/hyperliquid/builders)                                 | The builder-code leaderboard: fee revenue, routed volume, unique traders, fills, `market_share_pct`.  |
| [`/builders/stats`](/docs/endpoints/data/hyperliquid/builders-stats)                     | Builder-code economics for the whole venue.                                                           |
| [`/builders/{builder}`](/docs/endpoints/data/hyperliquid/builders-builder)               | One builder: window totals plus per-asset and per-dex breakdowns, and an unwindowed `lifetime` block. |
| [`/builders/{builder}/users`](/docs/endpoints/data/hyperliquid/builders-builder-users)   | The wallets routing through one builder, ranked.                                                      |
| [`/builders/{builder}/fills`](/docs/endpoints/data/hyperliquid/builders-builder-fills)   | Raw builder-routed fills, newest first.                                                               |
| [`/builders/{builder}/series`](/docs/endpoints/data/hyperliquid/builders-builder-series) | Fee, volume, users and fills per bucket for one builder, newest first.                                |

***

## Cohorts and segments [#cohorts-and-segments]

Three self-describing routes. Read these before hard-coding any bucket name.

| Path                                                                                | What it answers                                                                                                     |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| [`/cohorts`](/docs/endpoints/data/hyperliquid/cohorts)                                   | The canonical cohort ladders as flat label sets — the exact strings `?cohort=` accepts.                             |
| [`/segments`](/docs/endpoints/data/hyperliquid/segments)                                 | The detailed catalogue: every bucket on every axis with its boundaries, slug, rank, `basis` and a `groupable` flag. |
| [`/segments/{cohort}/summary`](/docs/endpoints/data/hyperliquid/segments-cohort-summary) | Aggregate positioning for one cohort at the latest snapshot.                                                        |

***

## Coins [#coins]

Hourly positioning series for one coin. `{coin}` is an HL coin ticker such as `BTC`.

| Path                                                                                    | What it answers                                                                                         |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| [`/coins/{coin}/metrics`](/docs/endpoints/data/hyperliquid/coins-coin-metrics)               | Hourly open-interest / position-count / bias series for one coin, optionally sliced to a single cohort. |
| [`/coins/{coin}/cohort-metrics`](/docs/endpoints/data/hyperliquid/coins-coin-cohort-metrics) | The full cohort matrix for one coin — every bucket on an axis, hourly.                                  |
| [`/coins/{coin}/size-breakdown`](/docs/endpoints/data/hyperliquid/coins-coin-size-breakdown) | Positioning for one coin split by the canonical ten position-size buckets.                              |

***

## Positions [#positions]

| Path                                                              | What it answers                                                                                                                          |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| [`/positions`](/docs/endpoints/data/hyperliquid/positions)             | Position rows, current or historical.                                                                                                    |
| [`/positions/coins`](/docs/endpoints/data/hyperliquid/positions-coins) | Market-wide open interest per coin at the latest snapshot, with the venue's own OI alongside our aggregate so the two can be reconciled. |
| [`/positions/match`](/docs/endpoints/data/hyperliquid/positions-match) | "Who else is in this trade" — open positions matching a coin/side/leverage/entry profile.                                                |

***

## Leaderboards [#leaderboards]

| Path                                                                                  | What it answers                                                                                                                                 |
| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| [`/traders`](/docs/endpoints/data/hyperliquid/traders)                                     | Top HL perp traders by the requested metric over a window.                                                                                      |
| [`/leaderboard`](/docs/endpoints/data/hyperliquid/leaderboard)                             | The trader leaderboard carrying the full risk-metric set — drawdown, Calmar, recovery factor, profit factor, expectancy and streaks beside PnL. |
| [`/leaderboard/flow-adjusted`](/docs/endpoints/data/hyperliquid/leaderboard-flow-adjusted) | Ranked on **fills-derived realized PnL**, with external flow reported beside it.                                                                |

***

## Liquidations [#liquidations]

Three routes, and they answer two different questions — one realized, two hypothetical.

| Path                                                                                              | What it answers                                                                                                                  |
| ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| [`/liquidations`](/docs/endpoints/data/hyperliquid/liquidations)                                       | Realized liquidation fills — what actually got liquidated.                                                                       |
| [`/coins/{coin}/liquidation-heatmap`](/docs/endpoints/data/hyperliquid/coins-coin-liquidation-heatmap) | Where liquidations *would* cluster if price moved: every open position's own liquidation price, binned and weighted by notional. |
| [`/liquidations/risk`](/docs/endpoints/data/hyperliquid/liquidations-risk)                             | Share of each coin's open interest sitting close to liquidation, optionally for one cohort.                                      |

***

## Ecosystem aggregates [#ecosystem-aggregates]

| Path                                                          | What it answers                                                                         |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| [`/stats`](/docs/endpoints/data/hyperliquid/stats)                 | Ecosystem time series: perp equity, open interest, position counts.                     |
| [`/stats/volume`](/docs/endpoints/data/hyperliquid/stats-volume)   | Hourly perp volume — the whole venue, or one coin.                                      |
| [`/hype/holders`](/docs/endpoints/data/hyperliquid/hype-holders)   | The HYPE holder leaderboard — spot balance plus staked, per wallet.                     |
| [`/heatmap`](/docs/endpoints/data/hyperliquid/heatmap)             | The coin × cohort positioning matrix — the whole board in one call.                     |
| [`/assets/hourly`](/docs/endpoints/data/hyperliquid/assets-hourly) | Hourly close **plus** open interest, funding rate and premium, for many assets at once. |

***

## Candles [#candles]

Two routes, and they are the whole crypto candle surface: Hyperliquid candles, built from the fills
our own node sees. There is no second venue's candle route to reconcile the numbers against, so the
parameter table and the response envelope on the endpoint's own page are the entire contract.

| Path                                                        | What it answers                                   |
| ----------------------------------------------------------- | ------------------------------------------------- |
| [`/ohlcv`](/docs/endpoints/data/hyperliquid/ohlcv)               | Hyperliquid candles, derived from executed fills. |
| [`/ohlcv/export`](/docs/endpoints/data/hyperliquid/ohlcv-export) | Streams the same single page as NDJSON.           |

***

## Related [#related]

* [Data MCP server](/docs/ai/data) — `hl_perp_top_traders` and `hl_position_match` run the same code as
  [`/traders`](/docs/endpoints/data/hyperliquid/traders) and
  [`/positions/match`](/docs/endpoints/data/hyperliquid/positions-match), agent-shaped.
* [Rate limits](/docs/data/rate-limits) — the shared hourly counter these calls spend.
* [Errors](/docs/data/errors) — the status codes and the error envelope.


# /leaderboard/flow-adjusted (/docs/endpoints/data/hyperliquid/leaderboard-flow-adjusted)



```
GET https://data.vike.io/v1/hyperliquid/leaderboard/flow-adjusted
```

Ranked on **fills-derived realized PnL**, with external flow reported beside it.

Truncated: `traders` holds 3 rows (`limit=3`); the first is shown in full, including the deposit and
withdrawal figures and the `flow_unbalanced` flag described below.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/leaderboard/flow-adjusted?limit=3&window=30d" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="window" loc="query">
    `1d`

     \| 

    `7d`

     \| 

    `30d`

     \| 

    `all`

    . Default 

    `30d`
  </Param>

  <Param name="limit" loc="query">
    Default 25, max 500
  </Param>

  <Param name="cursor" loc="query">
    Keyset cursor
  </Param>
</Params>

```json title="Example response"
{
  "traders": [
    {
      "wallet": "0x9bbb821a51d9c0ef24dd8592e9caad7fc469bbf2",
      "rank": 1,
      "account_value": 0.0,
      "total_realized_pnl": 2152061.802894,
      "cum_realized_pnl": 4018227.3687610077,
      "roi": 0.0,
      "pnl_pct": null,
      "total_volume": 45909810.173497,
      "total_fee": 3873.5595550000003,
      "trade_count": 10,
      "win_count": 7,
      "loss_count": 3,
      "win_rate": 0.699999988079071,
      "long_win_rate": 0.6000000238418579,
      "short_win_rate": 0.800000011920929,
      "long_pnl": 1163849.598942,
      "short_pnl": 988212.203952,
      "profit_factor": 32.784751892089844,
      "expectancy": 215206.18028939998,
      "max_drawdown_pct": 154.60000610351562,
      "current_drawdown_pct": 100.0,
      "calmar_ratio": 0.0,
      "recovery_factor": 999.0,
      "max_win_streak": 7,
      "max_loss_streak": 3,
      "avg_leverage": 0.0,
      "avg_duration_seconds": 82171,
      "size_cohort": "shrimp",
      "pnl_cohort": "3x smart",
      "pnl_cohort_tag": "consistent_winner",
      "style_cohort_tag": "whale_hunter",
      "attributed": {
        "trading_pnl_total": -225513.68282699987,
        "realized_trading_pnl": -296967.9990569999,
        "delta_unrealized_pnl": 71454.31623000004,
        "funding_paid_usd": 0.0,
        "delta_account_value": -858691.0119069999,
        "account_value_eod": 0.0,
        "active_days": 2,
        "last_day": "2026-08-24",
        "perps_trading_pnl": -225513.6828269998
      },
      "flow": {
        "deposit_usd": 0.0,
        "withdraw_usd": 0.0,
        "net_external_flow_usd": -633177.32908,
        "net_total_flow_usd": -633177.32908
      },
      "flow_unbalanced": true
    }
  ],
  "totalCount": 145165,
  "nextCursor": "eyJrIjoiZmxvd2FkanwzMGQiLCJyIjozLCJ2IjoxMTc5NzcxLjYzNzU2Mjk5OTcsInciOiIweDAwNGVkY2Q0MDM2MGUyOTNlNGNmMjYwZDJlYmRmOGM3MDc2YzFiYjgifQ",
  "ranked_by": "total_realized_pnl (fills-derived; excludes deposits by construction)"
}
```

An account-value delta is not a trading result: a wallet that deposits $1M and loses $50k reads as
+$950k on any equity-delta ranking. The rank here comes from the sum of closed round-trip PnL, which
excludes deposits **by construction** — there is no flow term in it to corrupt. Deposits,
withdrawals and the daily attribution figures come back in the same row, so a caller can see what
was excluded rather than trust that something was.

⚠ &#x2A;*`flow_unbalanced` is a per-row honesty flag, not a filter.** It is true when the wallet had a
`send` in the window, which is when the *attributed* block beside the rank is unreliable —
the ledger records `send` one-sided (measured 2026-08-04: 1,010,263 negative rows against
835,295 positive over 30 days, netting −$1.27B, while `spotTransfer`, `internalTransfer` and
`subAccountTransfer` each net about 0). &#x2A;*The rank itself does not depend on attribution and is
unaffected.** The flag is reported and never used to filter: active traders move money constantly,
and excluding them would empty the board rather than clean it.


# /leaderboard (/docs/endpoints/data/hyperliquid/leaderboard)



```
GET https://data.vike.io/v1/hyperliquid/leaderboard
```

The trader leaderboard carrying the full risk-metric set — drawdown, Calmar, recovery factor,
profit factor, expectancy and streaks beside PnL. A wallet up 300% through a 70% drawdown is not
the same find as one up 300% without, and a PnL-only board cannot tell them apart.

Truncated: `traders` holds 3 rows (`limit=3`); the first is shown in full, so the whole
risk-metric set is visible.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/leaderboard?limit=3&window=30d" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="window" loc="query">
    `1d`

     \| 

    `7d`

     \| 

    `30d`

     \| 

    `all`

    . Default 

    `30d`
  </Param>

  <Param name="sort" loc="query">
    One of the 20 keys below. Default 

    `pnl`
  </Param>

  <Param name="order" loc="query">
    `asc`

     \| 

    `desc`

    . Default 

    `desc`
  </Param>

  <Param name="cohort" loc="query">
    One label on 

    `axis`
  </Param>

  <Param name="axis" loc="query">
    `size`

     \| 

    `pnl`

     \| 

    `pnl_abs`

    . Default 

    `size`
  </Param>

  <Param name="min_trades" loc="query">
    Minimum closed trades. Default 0 (no floor here)
  </Param>

  <Param name="min_win_rate" loc="query">
    Minimum win rate
  </Param>

  <Param name="min_volume" loc="query">
    Minimum total volume
  </Param>

  <Param name="limit" loc="query">
    Default 25, max 500
  </Param>

  <Param name="cursor" loc="query">
    Keyset cursor
  </Param>
</Params>

```json title="Example response"
{
  "traders": [
    {
      "wallet": "0x9bbb821a51d9c0ef24dd8592e9caad7fc469bbf2",
      "rank": 1,
      "account_value": 0.0,
      "total_realized_pnl": 2152061.802894,
      "cum_realized_pnl": 4018227.3687610077,
      "roi": 0.0,
      "pnl_pct": null,
      "total_volume": 45909810.173497,
      "total_fee": 3873.5595550000003,
      "trade_count": 10,
      "win_count": 7,
      "loss_count": 3,
      "win_rate": 0.699999988079071,
      "long_win_rate": 0.6000000238418579,
      "short_win_rate": 0.800000011920929,
      "long_pnl": 1163849.598942,
      "short_pnl": 988212.203952,
      "profit_factor": 32.784751892089844,
      "expectancy": 215206.18028939998,
      "max_drawdown_pct": 154.60000610351562,
      "current_drawdown_pct": 100.0,
      "calmar_ratio": 0.0,
      "recovery_factor": 999.0,
      "max_win_streak": 7,
      "max_loss_streak": 3,
      "avg_leverage": 0.0,
      "avg_duration_seconds": 82171,
      "size_cohort": "shrimp",
      "pnl_cohort": "3x smart",
      "pnl_cohort_tag": "consistent_winner",
      "style_cohort_tag": "whale_hunter"
    }
  ],
  "totalCount": 414029,
  "nextCursor": "eyJrIjoiMzBkfHBubHxkZXNjfHNpemV8IiwiciI6MywidiI6MTE3OTc3MS42Mzc1NjI5OTk3LCJ3IjoiMHgwMDRlZGNkNDAzNjBlMjkzZTRjZjI2MGQyZWJkZjhjNzA3NmMxYmI4In0"
}
```

`sort` is a closed allow-list. An unknown key gets a **400, not a clamped default** — sorting by
something other than what was asked for is a wrong answer that looks like a right one.
The 20 accepted keys: `pnl`, `realized_pnl`, `roi`, `volume`, `trades`, `win_rate`,
`long_win_rate`, `short_win_rate`, `account_value`, `profit_factor`, `expectancy`, `calmar`,
`recovery_factor`, `max_drawdown`, `current_drawdown`, `avg_leverage`, `avg_duration`, `fees`,
`win_streak`, `loss_streak`.

Both cohort labels are returned regardless of which axis you filtered on. `pnl_pct` is a
null-guarded ROI: the stored `roi` is raw even when equity is a rounding error (values like 4.8e10
occur), so `pnl_pct` is `null` below $1 of equity and a client can display one column without
special-casing.


# /liquidations/risk (/docs/endpoints/data/hyperliquid/liquidations-risk)



```
GET https://data.vike.io/v1/hyperliquid/liquidations/risk
```

Share of each coin's open interest sitting close to liquidation, optionally for one cohort.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/liquidations/risk?limit=3" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="axis" loc="query">
    `size`

     \| 

    `pnl`

     \| 

    `pnl_abs`

    . Default 

    `size`
  </Param>

  <Param name="cohort" loc="query">
    One label on that axis
  </Param>

  <Param name="limit" loc="query">
    Default 100, max 500
  </Param>
</Params>

```json title="Example response"
[
  {
    "asset": "xyz:SHAZ",
    "total_value_usd": 3730692.188159999,
    "risk_value_usd": 1715452.21152,
    "percent_risk": 0.45982142857142866,
    "positions_count": 176,
    "at_risk_count": 12,
    "cohort_axis": "size",
    "cohort": null
  },
  {
    "asset": "para:LRCX",
    "total_value_usd": 221490.99839999998,
    "risk_value_usd": 97883.91440000001,
    "percent_risk": 0.441931794551882,
    "positions_count": 22,
    "at_risk_count": 4,
    "cohort_axis": "size",
    "cohort": null
  },
  {
    "asset": "xyz:BB",
    "total_value_usd": 8408334.176679997,
    "risk_value_usd": 3530097.7598200003,
    "percent_risk": 0.4198331899807826,
    "positions_count": 325,
    "at_risk_count": 83,
    "cohort_axis": "size",
    "cohort": null
  }
]
```


# /liquidations (/docs/endpoints/data/hyperliquid/liquidations)



```
GET https://data.vike.io/v1/hyperliquid/liquidations
```

Realized liquidation fills — what actually got liquidated.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/liquidations?limit=3" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="coin" loc="query">
    HL coin ticker
  </Param>

  <Param name="wallet" loc="query">
    One wallet
  </Param>

  <Param name="direction" loc="query">
    `long`

     \| 

    `short`
  </Param>

  <Param name="start` / `end" loc="query">
    ISO-8601 UTC bounds
  </Param>

  <Param name="limit" loc="query">
    Default 100, max 5000
  </Param>

  <Param name="cursor" loc="query">
    Keyset cursor
  </Param>
</Params>

```json title="Example response"
{
  "liquidations": [
    {
      "liq_ts": "2026-09-03T07:54:00+00:00",
      "wallet": "0xffbdde0c5392ae87f4a56c2095787e96fb241546",
      "asset": "BTC",
      "side": "long",
      "size_token": 0.05124,
      "size_usd": 3997.28364,
      "mark_price": 78011.0,
      "size_cohort": null,
      "pnl_cohort": "unknown",
      "pnl_cohort_basis": "point_in_time"
    },
    {
      "liq_ts": "2026-09-03T07:54:00+00:00",
      "wallet": "0xfd8b9b4d81d5783dd525d8af2a3566428b6a75c9",
      "asset": "BTC",
      "side": "long",
      "size_token": 0.04319,
      "size_usd": 3369.29509,
      "mark_price": 78011.0,
      "size_cohort": null,
      "pnl_cohort": "3x winner",
      "pnl_cohort_basis": "point_in_time"
    },
    {
      "liq_ts": "2026-09-03T07:54:00+00:00",
      "wallet": "0xfc6a4b0024249e6450723cdcd25f76ad2e565980",
      "asset": "SUI",
      "side": "short",
      "size_token": 313.8,
      "size_usd": 243.58725,
      "mark_price": 0.77625,
      "size_cohort": "shrimp",
      "pnl_cohort": "3x winner",
      "pnl_cohort_basis": "point_in_time"
    }
  ],
  "label_computed": {
    "grading": "realized",
    "when": "at the row's own hour where an hourly label exists for it; at query time for the rows it does not (see caveat)",
    "lookahead": false,
    "resolution": "hourly",
    "source": "hourly point-in-time label set (fallback: live wallet realized-PnL ladder)",
    "detail": "Each row's pnl_cohort is the realized ladder as it stood at the liquidation's own hour, read from the hourly point-in-time label set; pnl_cohort_basis='point_in_time' on those rows. Rows that set does not cover fall back to the live ladder — today's label stamped on a historical event, which IS lookahead — and declare it with pnl_cohort_basis='current'. A wallet in neither source carries null for both fields.",
    "caveat": "Two windows have no point-in-time label and always fall back: rows before 2026-04-07 (liquidations reach back to 2026-01-01, point-in-time labels start 2026-04-07), and the newest hours not yet labelled. In steady state that is only the current incomplete hour — a label is published at hour close — but a backfill or recovery can temporarily widen it (observed 2026-08-21: labels 7h45m behind the wall clock for the duration), so the trailing window is however far the newest label lags now, not a constant."
  },
  "nextCursor": "eyJ0cyI6IjIwMjYtMDktMDMgMDc6NTQ6MDAuMDAwIiwidyI6IjB4ZmM2YTRiMDAyNDI0OWU2NDUwNzIzY2RjZDI1Zjc2YWQyZTU2NTk4MCJ9"
}
```

Each row's `pnl_cohort` is **point-in-time** — the label as it stood at the liquidation's own hour
— wherever an hourly label exists for it, and the query-time label where one does not.
`pnl_cohort_basis` says which, per row.

⚠ The envelope's `label_computed` block declares the two windows the hourly labelling does **not**
cover: rows before 2026-04-07, and the newest hours not yet labelled. Rows in
those windows carry a current label, not a point-in-time one.


# /ohlcv/export (/docs/endpoints/data/hyperliquid/ohlcv-export)



```
GET https://data.vike.io/v1/hyperliquid/ohlcv/export
```

Streams the same single page as NDJSON: one header line naming what answered (`symbol`, `asset`,
`market`, `dex`, `interval`, `tz`, `source`), then one line per bar. Sent with a
`Content-Disposition` attachment filename. Lines arrive as they are produced rather than buffered
until the response is complete, and a stream is allowed to stay open for up to 300 seconds — long
enough for the largest page this route will return.

Shown as sent — NDJSON, one object per line rather than a single JSON document: the header line
first, then one line per bar. Nothing is truncated: all 6 lines are shown — the header plus the 5
bars `limit=5` asked for.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/ohlcv/export?symbol=BTC&interval=1h&limit=5" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="symbol" loc="query">
    As on 

    [`/ohlcv`](/docs/endpoints/data/hyperliquid/ohlcv)
  </Param>

  <Param name="interval" loc="query">
    As on 

    [`/ohlcv`](/docs/endpoints/data/hyperliquid/ohlcv)

    . Default 

    `1h`
  </Param>

  <Param name="market" loc="query">
    As on 

    [`/ohlcv`](/docs/endpoints/data/hyperliquid/ohlcv)

    . Default 

    `perp`
  </Param>

  <Param name="dex" loc="query">
    As on 

    [`/ohlcv`](/docs/endpoints/data/hyperliquid/ohlcv)

    . Default 

    `HL`
  </Param>

  <Param name="start` / `end" loc="query">
    As on 

    [`/ohlcv`](/docs/endpoints/data/hyperliquid/ohlcv)
  </Param>

  <Param name="limit" loc="query">
    Defaults to the maximum, 5000
  </Param>
</Params>

```json title="Example response"
{"symbol":"BTC","asset":"BTC","market":"perp","dex":"HL","interval":"1h","tz":"UTC","source":"1h fills rollup"}
{"ts":1788408000000,"open":77685.0,"high":77826.0,"low":77518.0,"close":77761.0,"volume":1638.383539999999,"volume_usd":127187806.34586997,"n_trades":11502}
{"ts":1788411600000,"open":77767.0,"high":77827.0,"low":77090.0,"close":77799.0,"volume":2381.401280000001,"volume_usd":184414000.1971202,"n_trades":20200}
{"ts":1788415200000,"open":77800.0,"high":77839.0,"low":77679.0,"close":77822.0,"volume":742.5236199999999,"volume_usd":57737530.938200004,"n_trades":11927}
{"ts":1788418800000,"open":77823.0,"high":78177.0,"low":77569.0,"close":77635.0,"volume":2354.81572,"volume_usd":183533988.69679,"n_trades":23209}
{"ts":1788422400000,"open":77636.0,"high":78019.0,"low":77636.0,"close":78018.0,"volume":415.8346900000001,"volume_usd":32390151.983540002,"n_trades":3954}
```

⚠ **Billed 2 credits up front**, before the first byte. The response is a stream, so the row count
is unknown at the moment the charge is recorded — it is a flat 2 credits whatever the page turns
out to hold, and it is not reconciled afterwards.

⚠ It is **not** an unbounded whole-window export, despite the name. It streams exactly the same
single clamped page [`/ohlcv`](/docs/endpoints/data/hyperliquid/ohlcv) returns — only the encoding
differs. To cover a window wider than one page, walk it yourself with `start` / `end`.


# /ohlcv (/docs/endpoints/data/hyperliquid/ohlcv)



```
GET https://data.vike.io/v1/hyperliquid/ohlcv
```

Hyperliquid candles, derived from executed fills.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/ohlcv?symbol=BTC&interval=1h&limit=3" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="symbol" loc="query">
    Perp ticker (

    `BTC`

    ), spot token (

    `HYPE`

    ) or raw index (

    `@107`

    )
  </Param>

  <Param name="interval" loc="query">
    `1m`

     \| 

    `5m`

     \| 

    `15m`

     \| 

    `30m`

     \| 

    `1h`

     \| 

    `4h`

     \| 

    `1d`

    , or 

    `Nt`

     for N-trade bars. Default 

    `1h`
  </Param>

  <Param name="market" loc="query">
    `perp`

     \| 

    `spot`

    . Default 

    `perp`
  </Param>

  <Param name="dex" loc="query">
    HL core or a HIP-3 perp DEX. Default 

    `HL`

     — see below
  </Param>

  <Param name="start" loc="query">
    ISO-8601 UTC or epoch ms, inclusive
  </Param>

  <Param name="end" loc="query">
    ISO-8601 UTC or epoch ms, exclusive
  </Param>

  <Param name="limit" loc="query">
    Default 500, clamped to 5000
  </Param>
</Params>

```json title="Example response"
{
  "symbol": "BTC",
  "asset": "BTC",
  "market": "perp",
  "dex": "HL",
  "interval": "1h",
  "tz": "UTC",
  "source": "1h fills rollup",
  "candles": [
    {
      "ts": 1788415200000,
      "open": 77800.0,
      "high": 77839.0,
      "low": 77679.0,
      "close": 77822.0,
      "volume": 742.5236199999999,
      "volume_usd": 57737530.938200004,
      "n_trades": 11927
    },
    {
      "ts": 1788418800000,
      "open": 77823.0,
      "high": 78177.0,
      "low": 77569.0,
      "close": 77635.0,
      "volume": 2354.81572,
      "volume_usd": 183533988.69679,
      "n_trades": 23209
    },
    {
      "ts": 1788422400000,
      "open": 77636.0,
      "high": 78019.0,
      "low": 77636.0,
      "close": 77993.0,
      "volume": 398.0436600000001,
      "volume_usd": 31002407.180790003,
      "n_trades": 3884
    }
  ]
}
```

**There is no `cursor`.** The engine returns one page clamped to 5000 bars; page by moving
`start`/`end` yourself.

⚠ &#x2A;*Do not hard-code the `dex` list.** The route's own parameter description enumerates
`HL | XYZ | PARA | MKTS | HYNA`, and that is a partial list: builder DEXs are deployed
permissionlessly, so the accepted set is refreshed from the live deployments (within 10 minutes)
rather than fixed. An earlier three-hour sample saw only five of the nine DEXs a static list would
have carried — which is exactly how a hard-coded list 400s a venue that is live and trading. An
unknown `dex` returns a 400 **naming the known set**; ask for one and read the answer.

⚠ &#x2A;*An unsupported `interval` is a 400, never a default.** Tick bars (`Nt`, 1 to 100,000 trades)
and time bars are not interchangeable downstream: time bars come from the pre-aggregated
minute/hour rollups, tick bars have to walk the raw fill history, **which is retained 12 months
where the rollups are not**. The response's `source` field names which of the two answered, so a
series that stopped early is distinguishable from an asset that stopped trading.

This is the API's crypto candle surface — Hyperliquid's own bars, off the fills our node sees.
[`/ohlcv/export`](/docs/endpoints/data/hyperliquid/ohlcv-export) streams the same single page as NDJSON.


# /positions/coins (/docs/endpoints/data/hyperliquid/positions-coins)



```
GET https://data.vike.io/v1/hyperliquid/positions/coins
```

Market-wide open interest per coin at the latest snapshot, with the venue's own OI alongside our
aggregate so the two can be reconciled. No parameters.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/positions/coins" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

Truncated: the array holds **313** coins; the first 3 are shown.

```json title="Example response"
[
  {
    "coin": "BTC",
    "total_value": 3026943358.0,
    "total_value_long": 1518666445.0,
    "total_value_short": 1508276913.0,
    "count": 36436,
    "count_long": 22334,
    "count_short": 14102,
    "venue_open_interest_usd": 3010625139.0
  },
  {
    "coin": "ETH",
    "total_value": 2213433684.0,
    "total_value_long": 1107299108.0,
    "total_value_short": 1106134576.0,
    "count": 17829,
    "count_long": 11830,
    "count_short": 5999,
    "venue_open_interest_usd": 2217262604.0
  },
  {
    "coin": "HYPE",
    "total_value": 1856962139.0,
    "total_value_long": 928654781.4,
    "total_value_short": 928307357.8,
    "count": 18134,
    "count_long": 13648,
    "count_short": 4486,
    "venue_open_interest_usd": 1861716866.0
  }
]
```


# /positions/match (/docs/endpoints/data/hyperliquid/positions-match)



```
GET https://data.vike.io/v1/hyperliquid/positions/match
```

"Who else is in this trade" — open positions matching a coin/side/leverage/entry profile, the
reverse lookup from a shared position card. Runs the same implementation as the `hl_position_match`
tool on the [Data MCP server](/docs/ai/data).

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/positions/match?coin=BTC&side=long&leverage=40&entry_price=78001.68&mark_price=77710&limit=3" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="coin" loc="query">
    HL coin ticker, e.g. 

    `BTC`
  </Param>

  <Param name="side" loc="query">
    `long`

     \| 

    `short`
  </Param>

  <Param name="leverage" loc="query">
    Numeric, positive. Matched within ±0.5 absolute
  </Param>

  <Param name="entry_price" loc="query">
    Numeric, positive
  </Param>

  <Param name="mark_price" loc="query">
    Ranks the matches. 

    **Defaults to `entry_price`**

     when omitted
  </Param>

  <Param name="limit" loc="query">
    Declared default 50, declared max 500 — see below
  </Param>
</Params>

```json title="Example response"
{
  "matches": [
    {
      "address": "0x0000005178d55139ba21423218ea7290a7ccdc81",
      "coin": "BTC",
      "side": "long",
      "snapshot_ts": 1788422340,
      "size_token": 0.00467,
      "size_usd": 362.90569999999997,
      "entry_price": 78001.6773019272,
      "mark_price": 77710.0,
      "leverage": 40.0,
      "liquidation_price": 77064.4662131028,
      "unrealized_pnl": -1.362132999999992,
      "entry_dist_pct": 0.0
    },
    {
      "address": "0xf94d1cfd380bbaa0d7ca33e00700e7e6be836ab1",
      "coin": "BTC",
      "side": "long",
      "snapshot_ts": 1788422340,
      "size_token": 0.035,
      "size_usd": 2719.8500000000004,
      "entry_price": 78001.85714285714,
      "mark_price": 77710.0,
      "leverage": 40.0,
      "liquidation_price": 0.0,
      "unrealized_pnl": -10.215000000000074,
      "entry_dist_pct": 0.0002
    },
    {
      "address": "0x76d81fdfc8226f371529d596f52d208279127663",
      "coin": "BTC",
      "side": "long",
      "snapshot_ts": 1788422340,
      "size_token": 0.00015,
      "size_usd": 11.6565,
      "entry_price": 78002.0,
      "mark_price": 77710.0,
      "leverage": 40.0,
      "liquidation_price": 77077.3805907173,
      "unrealized_pnl": -0.0438,
      "entry_dist_pct": 0.0004
    }
  ],
  "match_count": 3,
  "tolerance_used": "tight",
  "query": {
    "coin": "BTC",
    "side": "long",
    "leverage": 40.0,
    "entry_price": 78001.68,
    "mark_price_hint": 77710.0
  }
}
```

⚠ &#x2A;*`limit` is documented as max 500 and clamped to 50.** The parameter is accepted up to 500 and
then clamped into 1–50. A larger request is served at 50, not rejected.

**It walks three widening tolerance bands** on entry price — tight 0.05%, then 0.5%, then a 1.0%
fallback — and returns the first band that matches, ranked by mark-price proximity. So a match is
not necessarily a 0.05% match; check the reported band.

⚠ &#x2A;*A 15-minute freshness gate is why this returns fewer rows than the position history holds.**
The latest-state view keeps a wallet's last-known row forever — 89.8% of it measured more than a
day stale, the oldest ghost 2026-04-02 — so without the gate this matched months-closed positions
as open. The gate is anchored on the newest snapshot **batch** rather than on the wall clock, so
ingestion lag cannot empty the result.


# /positions (/docs/endpoints/data/hyperliquid/positions)



```
GET https://data.vike.io/v1/hyperliquid/positions
```

Position rows, current or historical.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/positions?coin=BTC&limit=3" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="coin" loc="query">
    HL coin ticker
  </Param>

  <Param name="wallet" loc="query">
    One wallet
  </Param>

  <Param name="cohort" loc="query">
    One label on 

    `axis`
  </Param>

  <Param name="axis" loc="query">
    `size`

     \| 

    `pnl`

     \| 

    `pnl_abs`

    . Default 

    `size`
  </Param>

  <Param name="open_only" loc="query">
    Boolean, default 

    `true`

    . Latest open positions only
  </Param>

  <Param name="start` / `end" loc="query">
    ISO-8601 UTC. Setting either switches to history
  </Param>

  <Param name="limit" loc="query">
    Default 100, max 5000
  </Param>

  <Param name="cursor" loc="query">
    Keyset cursor
  </Param>
</Params>

```json title="Example response"
{
  "positions": [
    {
      "wallet": "0x0000000000bdc2fd416def2d8688069052eb0f87",
      "asset": "BTC",
      "direction": "long",
      "size_token": 0.00553,
      "size_usd": 429.7363,
      "entry_price": 69452.7555153707,
      "mark_price": 77710.0,
      "liquidation_price": 0.0,
      "unrealized_pnl": 45.662561999999994,
      "leverage": 0.0,
      "leverage_type": "cross",
      "margin_used": 429.7363,
      "size_cohort": "shrimp",
      "pnl_cohort": "rekt",
      "pnl_abs_cohort": "-$10k-$0",
      "liq_progress": 0.0,
      "dex_name": "HL",
      "snapshot_ts": "2026-09-03T07:59:00+00:00",
      "pnl_cohort_as_of": null,
      "pnl_cohort_basis": "current",
      "opened_at": "2026-04-02T08:36:00+00:00"
    },
    {
      "wallet": "0x0000005178d55139ba21423218ea7290a7ccdc81",
      "asset": "BTC",
      "direction": "long",
      "size_token": 0.00467,
      "size_usd": 362.90569999999997,
      "entry_price": 78001.6773019272,
      "mark_price": 77710.0,
      "liquidation_price": 77064.4662131028,
      "unrealized_pnl": -1.362132999999992,
      "leverage": 40.0,
      "leverage_type": "isolated",
      "margin_used": 9.072642499999999,
      "size_cohort": "shrimp",
      "pnl_cohort": "3x loser",
      "pnl_abs_cohort": "-$10k-$0",
      "liq_progress": 0.31121836415002746,
      "dex_name": "HL",
      "snapshot_ts": "2026-09-03T07:59:00+00:00",
      "pnl_cohort_as_of": null,
      "pnl_cohort_basis": "current",
      "opened_at": "2026-04-02T08:36:00+00:00"
    },
    {
      "wallet": "0x0000fb4e763a5a617e12930c67877e9d25fcf460",
      "asset": "BTC",
      "direction": "long",
      "size_token": 1.6409,
      "size_usd": 127514.339,
      "entry_price": 63987.60771101226,
      "mark_price": 77710.0,
      "liquidation_price": 52473.2111772561,
      "unrealized_pnl": 22517.073506999986,
      "leverage": 5.0,
      "leverage_type": "isolated",
      "margin_used": 25502.8678,
      "size_cohort": "2x fish",
      "pnl_cohort": "2x smart",
      "pnl_abs_cohort": "$0-$10k",
      "liq_progress": 0.0,
      "dex_name": "HL",
      "snapshot_ts": "2026-09-03T07:59:00+00:00",
      "pnl_cohort_as_of": null,
      "pnl_cohort_basis": "current",
      "opened_at": "2026-04-10T12:37:00+00:00"
    }
  ],
  "nextCursor": "eyJhIjoiQlRDIiwiZCI6MSwibSI6ImxhdGVzdCIsInQiOiIyMDI2LTA5LTAzIDA3OjU5OjAwIiwidyI6IjB4MDAwMGZiNGU3NjNhNWE2MTdlMTI5MzBjNjc4NzdlOWQyNWZjZjQ2MCJ9",
  "label_computed": {
    "grading": "realized",
    "label_basis": "current",
    "when": "at query time",
    "lookahead": false,
    "resolution": "none — one label per wallet, today's",
    "source": "live wallet realized-PnL ladder",
    "detail": "Current mode serves the latest snapshot labelled with the live dictionary: the label and the row describe the same instant, so a live row labelled live has nothing to look ahead over. The same dictionary applied to a HISTORICAL row would be lookahead, which is why historical mode reads the hourly point-in-time labels instead."
  }
}
```

⚠ &#x2A;*Passing `start`/`end` changes which table answers.** `open_only=true` reads the latest-state
table; a time bound switches to the historical snapshot table, which is **8.7 billion rows** —
bound it by `coin` or `wallet`, or expect it to be slow.

⚠ **A historical `pnl` or `pnl_abs` cohort filter requires `coin` or `wallet` alongside it**, because
it is answered from the same hourly label table.

Every row declares its own label provenance: `pnl_cohort_basis` (`point_in_time` | `current`) and
`pnl_cohort_as_of` (the ISO hour the label was computed at, or null). Historical rows carry the
point-in-time label from the hourly label table — not today's dictionary standing — with the
current unlabelled tail (the newest hour or two) falling back to the dictionary and **saying so per
row**. The envelope's `label_computed` block states the mode's source once.


# /segments/{cohort}/summary (/docs/endpoints/data/hyperliquid/segments-cohort-summary)



```
GET https://data.vike.io/v1/hyperliquid/segments/{cohort}/summary
```

Aggregate positioning for one cohort at the latest snapshot.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/segments/shrimp/summary?axis=size" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="cohort" loc="path">
    A label or slug from 

    [`/cohorts`](/docs/endpoints/data/hyperliquid/cohorts)

     / 

    [`/segments`](/docs/endpoints/data/hyperliquid/segments)
  </Param>

  <Param name="axis" loc="query">
    `size`

     \| 

    `pnl`

     \| 

    `pnl_abs`

    . Default 

    `size`

    . 

    `trade_size`

     is rejected
  </Param>

  <Param name="openedWithin" loc="query">
    `24h`

     \| 

    `7d`

     \| 

    `30d`

     \| 

    `all`

    . Default 

    `all`
  </Param>
</Params>

```json title="Example response"
{
  "axis": "size",
  "cohort": "shrimp",
  "opened_within": "all",
  "snapshot_ts": "2026-09-03T07:59:00Z",
  "total_long_usd": 65653615.07,
  "total_short_usd": 36290036.09,
  "total_value": 101943651.2,
  "bias": 0.2880373485,
  "n_positions": 177573,
  "n_wallets": 90696,
  "n_wallets_in_profit": 47253,
  "pct_wallets_in_profit": 0.5210042339,
  "total_margin_used": 24105649.81,
  "total_equity": 9911731.106,
  "n_wallets_with_equity": 68060,
  "exposure_ratio": 4.229035597,
  "total_unrealized_pnl": -994085.9799,
  "by_side": {
    "long": {
      "value_usd": 65653615.07,
      "share": 0.6440186743,
      "n_positions": 125103,
      "n_wallets": 68812,
      "margin_used": 14244413.93,
      "unrealized_pnl": -370747.1081
    },
    "short": {
      "value_usd": 36290036.09,
      "share": 0.3559813257,
      "n_positions": 52470,
      "n_wallets": 29885,
      "margin_used": 9861235.882,
      "unrealized_pnl": -623338.8718
    }
  }
}
```

⚠ `axis` defaults to `size`, so a valid `pnl` label sent without its axis reads back as "not on the
size ladder" — which describes the default, not your mistake. The 400 names the label's real home.


# /segments (/docs/endpoints/data/hyperliquid/segments)



```
GET https://data.vike.io/v1/hyperliquid/segments
```

The detailed catalogue: every bucket on every axis with its boundaries, slug, rank, `basis` and a
`groupable` flag. Takes no parameters.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/segments" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

Truncated: the array holds **44** rows — every bucket on all four axes (`size`, `pnl`, `pnl_abs`,
`trade_size`); the first 3 are shown.

```json title="Example response"
[
  {
    "axis": "size",
    "cohort": "4x whale",
    "slug": "4x_whale",
    "rank": 1,
    "basis": "account_value_usd",
    "applies_to": "wallet",
    "groupable": true,
    "min_usd": 10000000.0,
    "max_usd": null,
    "percentile_min": null,
    "percentile_max": null,
    "min_closed_trades": null
  },
  {
    "axis": "size",
    "cohort": "3x whale",
    "slug": "3x_whale",
    "rank": 2,
    "basis": "account_value_usd",
    "applies_to": "wallet",
    "groupable": true,
    "min_usd": 5000000.0,
    "max_usd": 10000000.0,
    "percentile_min": null,
    "percentile_max": null,
    "min_closed_trades": null
  },
  {
    "axis": "size",
    "cohort": "2x whale",
    "slug": "2x_whale",
    "rank": 3,
    "basis": "account_value_usd",
    "applies_to": "wallet",
    "groupable": true,
    "min_usd": 2500000.0,
    "max_usd": 5000000.0,
    "percentile_min": null,
    "percentile_max": null,
    "min_closed_trades": null
  }
]
```

⚠ &#x2A;*Filter on `groupable`.** It is true for the per-wallet ladders and false for `trade_size`,
which buckets a position rather than a wallet and is rejected as `?axis=` by
[`/heatmap`](/docs/endpoints/data/hyperliquid/heatmap) and
[`/segments/{cohort}/summary`](/docs/endpoints/data/hyperliquid/segments-cohort-summary). A client
generating code off this endpoint that assumes every published axis is a valid grouping key will
emit calls that 400.


# /stats/volume (/docs/endpoints/data/hyperliquid/stats-volume)



```
GET https://data.vike.io/v1/hyperliquid/stats/volume
```

Hourly perp volume — the whole venue, or one coin.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/stats/volume?coin=BTC&limit=3" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="coin" loc="query">
    HL coin ticker. Omit for the whole venue
  </Param>

  <Param name="start` / `end" loc="query">
    ISO-8601 UTC bounds
  </Param>

  <Param name="limit" loc="query">
    Default 500, max 5000
  </Param>

  <Param name="cursor" loc="query">
    Keyset cursor
  </Param>
</Params>

```json title="Example response"
{
  "volume": [
    {
      "ts": "2026-09-03T08:00:00+00:00",
      "volume": 61952806.20848002,
      "n_fills": 7662,
      "coin": "BTC"
    },
    {
      "ts": "2026-09-03T07:00:00+00:00",
      "volume": 367067977.39358,
      "n_fills": 46418,
      "coin": "BTC"
    },
    {
      "ts": "2026-09-03T06:00:00+00:00",
      "volume": 115475061.87640005,
      "n_fills": 23854,
      "coin": "BTC"
    }
  ],
  "nextCursor": "eyJ0cyI6IjIwMjYtMDktMDMgMDY6MDA6MDAifQ"
}
```


# /stats (/docs/endpoints/data/hyperliquid/stats)



```
GET https://data.vike.io/v1/hyperliquid/stats
```

Ecosystem time series: perp equity, open interest, position counts.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/stats?limit=3" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="start` / `end" loc="query">
    ISO-8601 UTC bounds
  </Param>

  <Param name="limit" loc="query">
    Default 500, max 5000
  </Param>

  <Param name="cursor" loc="query">
    Keyset cursor
  </Param>
</Params>

```json title="Example response"
{
  "metrics": [
    {
      "ts": "2026-09-03T07:00:00+00:00",
      "total_perp_equity": 2178980170.7294016,
      "count_wallets": 125165,
      "count_open_positions": 362781,
      "count_long": 237331,
      "count_short": 125450,
      "open_interest": 13869169131.74862,
      "open_interest_long": 6939683497.517567,
      "open_interest_short": 6929485634.231054,
      "count_positions_in_profit": 189633
    },
    {
      "ts": "2026-09-03T06:00:00+00:00",
      "total_perp_equity": 2187765497.7367554,
      "count_wallets": 124626,
      "count_open_positions": 361533,
      "count_long": 236634,
      "count_short": 124899,
      "open_interest": 13875586056.264666,
      "open_interest_long": 6938701711.02817,
      "open_interest_short": 6936884345.236498,
      "count_positions_in_profit": 191147
    },
    {
      "ts": "2026-09-03T05:00:00+00:00",
      "total_perp_equity": 2175650033.332754,
      "count_wallets": 124837,
      "count_open_positions": 362198,
      "count_long": 237231,
      "count_short": 124967,
      "open_interest": 13829590200.787807,
      "open_interest_long": 6914317028.5549555,
      "open_interest_short": 6915273172.232853,
      "count_positions_in_profit": 191243
    }
  ],
  "nextCursor": "eyJ0cyI6IjIwMjYtMDktMDMgMDU6MDA6MDAifQ"
}
```


# /traders (/docs/endpoints/data/hyperliquid/traders)



```
GET https://data.vike.io/v1/hyperliquid/traders
```

Top HL perp traders by the requested metric over a window. Runs the same implementation as the
`hl_perp_top_traders` tool on the [Data MCP server](/docs/ai/data), deliberately: a second ranking that
disagreed with the one the assistant quotes would be worse than a near-duplicate route.
[`/leaderboard`](/docs/endpoints/data/hyperliquid/leaderboard) is the richer, cursor-paged version.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/traders?size=3&window=30d" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="window" loc="query">
    `1d`

     \| 

    `7d`

     \| 

    `30d`

     \| 

    `all`

    . Effective default 

    `30d`
  </Param>

  <Param name="sort" loc="query">
    `pnl`

     \| 

    `roi`

     \| 

    `win_rate`

     \| 

    `volume`

     \| 

    `trade_count`

     \| 

    `drawdown`

     \| 

    `account_value`

     \| 

    `long_pnl`

     \| 

    `short_pnl`

    . Default 

    `pnl`
  </Param>

  <Param name="order" loc="query">
    `asc`

     \| 

    `desc`

    . Default 

    `desc`
  </Param>

  <Param name="min_trades" loc="query">
    Minimum closed trades — see the floor below
  </Param>

  <Param name="min_win_rate" loc="query">
    **Percent, 0–100**

    , not a fraction
  </Param>

  <Param name="min_volume" loc="query">
    Minimum total volume
  </Param>

  <Param name="size" loc="query">
    Declared max 100, clamped to 20 — see below
  </Param>
</Params>

```json title="Example response"
{
  "traders": [
    {
      "address": "0x020ca66c30bec2c4fe3861a94e4db4a498a35872",
      "total_realized_pnl": 771490.2187940001,
      "roi_pct": 1752.226,
      "win_rate_pct": 67.88,
      "long_win_rate_pct": 72.16,
      "short_win_rate_pct": 61.76,
      "win_count": 112,
      "loss_count": 53,
      "trade_count": 165,
      "total_volume": 132982230.79802103,
      "long_pnl": 569640.7646920001,
      "short_pnl": 201849.454102,
      "max_drawdown_pct": 10000.0,
      "account_value": 4402914.84891,
      "avg_leverage": 0.0
    },
    {
      "address": "0x25773676902085225ae5751075e4161369334897",
      "total_realized_pnl": 720180.041582607,
      "roi_pct": 4309.738,
      "win_rate_pct": 52.71,
      "long_win_rate_pct": 52.63,
      "short_win_rate_pct": 52.78,
      "win_count": 13157,
      "loss_count": 11805,
      "trade_count": 24962,
      "total_volume": 2447047515.9331417,
      "long_pnl": 391309.8679779798,
      "short_pnl": 328870.17360462697,
      "max_drawdown_pct": 10000.0,
      "account_value": 1671052.77246,
      "avg_leverage": 0.0
    },
    {
      "address": "0xfc27136e42af1732ddc9ce2605ea9bff1b959d9d",
      "total_realized_pnl": 449283.75011699996,
      "roi_pct": 261.879,
      "win_rate_pct": 50.26,
      "long_win_rate_pct": 49.96,
      "short_win_rate_pct": 50.54,
      "win_count": 2549,
      "loss_count": 2523,
      "trade_count": 5072,
      "total_volume": 356717539.01556593,
      "long_pnl": 455601.4763099999,
      "short_pnl": -6317.726193000033,
      "max_drawdown_pct": 10000.0,
      "account_value": 17156179.333347,
      "avg_leverage": 0.0
    }
  ],
  "total": 18587
}
```

⚠ **Two bounds differ from what the parameter table declares**, and both are applied silently:

* `size` is documented as max 100 and clamped to **20**. Asking for 100 returns 20.
* `min_trades` is floored at **3**. Omitting it, or passing 0, 1 or 2, all give 3.

⚠ &#x2A;*An unrecognised `sort` is not a 400 here.** It falls back to the default PnL ranking silently,
so a typo returns a correct-looking answer sorted by something you did not ask for.
[`/leaderboard`](/docs/endpoints/data/hyperliquid/leaderboard) rejects the same mistake outright — the
two routes disagree.

An omitted string parameter and an empty one (`&sort=`) are treated identically: both fall through
to the default in the table above rather than being rejected.


# /wallets/{address}/builders (/docs/endpoints/data/hyperliquid/wallets-address-builders)



```
GET https://data.vike.io/v1/hyperliquid/wallets/{address}/builders
```

Reverse lookup: which builders this wallet's flow is routed through.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/wallets/0x25773676902085225ae5751075e4161369334897/builders?limit=3" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="address" loc="path">
    The wallet
  </Param>

  <Param name="window" loc="query">
    `1d`

     \| 

    `7d`

     \| 

    `30d`

     \| 

    `all`

    . Default 

    `all`
  </Param>

  <Param name="limit" loc="query">
    Default 50, max 500
  </Param>

  <Param name="cursor" loc="query">
    Keyset cursor
  </Param>
</Params>

```json title="Example response"
{
  "wallet": "0x25773676902085225ae5751075e4161369334897",
  "window": {
    "window": "all",
    "start": "2024-10-27T18:15:13+00:00",
    "end": "2026-09-03T08:07:49.353000+00:00"
  },
  "builders": [
    {
      "builder": "0xab5dbc057628bc18523c4cdfc0e1e2ebdbecb704",
      "assets": 42,
      "share_of_volume": 1.0,
      "fee_usd": 0.0,
      "volume_usd": 183419.57242000004,
      "share_volume_usd": 183419.57242000004,
      "fills": 2126,
      "fee_rate_bps": 0.0,
      "fee_usd_node": 0.0,
      "trader_fee_usd": 3.961064089999999,
      "builder_routed_deployer_fee_usd": 1.9780274800000002,
      "closed_pnl_usd": 4463.86290756,
      "active_days": 2,
      "crossed_fills": 966,
      "taker_pct": 45.437441204139226,
      "first_seen": "2026-09-02T19:45:15.814000+00:00",
      "last_seen": "2026-09-03T08:07:27.555000+00:00"
    }
  ],
  "nextCursor": null
}
```

⚠ `share_of_volume` is the share of the wallet's **builder-routed** volume, not of its total
trading. Fills placed without a builder code never enter this dataset at all.


# /wallets/{address}/fills (/docs/endpoints/data/hyperliquid/wallets-address-fills)



```
GET https://data.vike.io/v1/hyperliquid/wallets/{address}/fills
```

Raw fills — the level below round-trip trades.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/wallets/0x25773676902085225ae5751075e4161369334897/fills?limit=3" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="address" loc="path">
    The wallet
  </Param>

  <Param name="coin" loc="query">
    HL coin ticker
  </Param>

  <Param name="side" loc="query">
    `buy`

     \| 

    `sell`
  </Param>

  <Param name="start` / `end" loc="query">
    ISO-8601 UTC bounds
  </Param>

  <Param name="limit" loc="query">
    Default 100, max 5000
  </Param>

  <Param name="cursor" loc="query">
    Keyset cursor
  </Param>
</Params>

```json title="Example response"
{
  "wallet": "0x25773676902085225ae5751075e4161369334897",
  "items": [
    {
      "ts": "2026-09-03T08:07:48.351000+00:00",
      "asset": "xyz:PLATINUM",
      "side": "sell",
      "direction": "sell",
      "size_token": 0.1,
      "price": 1789.3,
      "size_usd": 178.93,
      "fee": -0.000178,
      "fee_token": "USDC",
      "is_maker": true,
      "crossed": false,
      "closed_pnl": 1.387,
      "order_id": 534782948640,
      "trade_id": 629173489889533,
      "dex_name": "XYZ"
    },
    {
      "ts": "2026-09-03T08:07:41.879000+00:00",
      "asset": "xyz:PLATINUM",
      "side": "sell",
      "direction": "sell",
      "size_token": 0.025,
      "price": 1789.2,
      "size_usd": 44.730000000000004,
      "fee": 0.001502,
      "fee_token": "USDC",
      "is_maker": false,
      "crossed": true,
      "closed_pnl": 0.34425,
      "order_id": 534782918094,
      "trade_id": 440416105012118,
      "dex_name": "XYZ"
    },
    {
      "ts": "2026-09-03T08:07:41.054000+00:00",
      "asset": "xyz:SKHX",
      "side": "sell",
      "direction": "sell",
      "size_token": 0.646,
      "price": 1181.0,
      "size_usd": 762.926,
      "fee": -0.000762,
      "fee_token": "USDC",
      "is_maker": true,
      "crossed": false,
      "closed_pnl": 0.0,
      "order_id": 534782865245,
      "trade_id": 1107832820522232,
      "dex_name": "XYZ"
    }
  ],
  "nextCursor": "eyJpIjoxMTA3ODMyODIwNTIyMjMyLCJ0IjoiMjAyNi0wOS0wMyAwODowNzo0MS4wNTQifQ"
}
```


# /wallets/{address}/funding (/docs/endpoints/data/hyperliquid/wallets-address-funding)



```
GET https://data.vike.io/v1/hyperliquid/wallets/{address}/funding
```

Funding paid and received by one wallet.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/wallets/0x25773676902085225ae5751075e4161369334897/funding?limit=3" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="address" loc="path">
    The wallet
  </Param>

  <Param name="coin" loc="query">
    HL coin ticker
  </Param>

  <Param name="start` / `end" loc="query">
    ISO-8601 UTC bounds
  </Param>

  <Param name="limit" loc="query">
    Default 100, max 5000
  </Param>

  <Param name="cursor" loc="query">
    Keyset cursor
  </Param>
</Params>

```json title="Example response"
{
  "wallet": "0x25773676902085225ae5751075e4161369334897",
  "items": [
    {
      "ts": "2026-08-28T13:00:00+00:00",
      "asset": "xyz:ZM",
      "payment_usd": -1.897955,
      "position_size": -95.101,
      "funding_rate": -0.0001990948,
      "dex_name": "HL"
    },
    {
      "ts": "2026-08-28T13:00:00+00:00",
      "asset": "xyz:XYZ100",
      "payment_usd": 0.000018,
      "position_size": -0.0001,
      "funding_rate": 0.00000625,
      "dex_name": "HL"
    },
    {
      "ts": "2026-08-28T13:00:00+00:00",
      "asset": "xyz:XLE",
      "payment_usd": 0.253792,
      "position_size": -467.0,
      "funding_rate": 0.000008719,
      "dex_name": "HL"
    }
  ],
  "nextCursor": "eyJhIjoieHl6OlhMRSIsInQiOiIyMDI2LTA4LTI4IDEzOjAwOjAwIn0"
}
```


# /wallets/{address}/ledger (/docs/endpoints/data/hyperliquid/wallets-address-ledger)



```
GET https://data.vike.io/v1/hyperliquid/wallets/{address}/ledger
```

Deposits, withdrawals, transfers and vault events. Keyset on `(ts, hash)`.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/wallets/0x25773676902085225ae5751075e4161369334897/ledger?limit=3" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="address" loc="path">
    The wallet
  </Param>

  <Param name="event_type" loc="query">
    One of the 14 observed types below
  </Param>

  <Param name="start` / `end" loc="query">
    ISO-8601 UTC bounds
  </Param>

  <Param name="limit" loc="query">
    Default 100, max 5000
  </Param>

  <Param name="cursor" loc="query">
    Keyset cursor
  </Param>
</Params>

```json title="Example response"
{
  "wallet": "0x25773676902085225ae5751075e4161369334897",
  "items": [
    {
      "ts": "2026-09-03T00:31:21.150000+00:00",
      "event_type": "send",
      "amount_usd": -10000.0,
      "fee": 0.0,
      "token": "USDC",
      "counterparty": null,
      "hash": "0x1648cc076d05cb6d17c204438ee76502036f00ed0808ea3fba11775a2c09a557"
    },
    {
      "ts": "2026-09-03T00:31:21.015000+00:00",
      "event_type": "send",
      "amount_usd": -10000.0,
      "fee": 0.0,
      "token": "USDC",
      "counterparty": null,
      "hash": "0xaec6e68724b1831cb04004438ee76302012c006cbfb4a1ee528f91d9e3b55d07"
    },
    {
      "ts": "2026-09-03T00:31:20.817000+00:00",
      "event_type": "send",
      "amount_usd": -10000.0,
      "fee": 0.0,
      "token": "USDC",
      "counterparty": null,
      "hash": "0x5bc25cde8ff2319b5d3c04438ee76002034f00c42af5506dff8b08314ef60b85"
    }
  ],
  "nextCursor": "eyJoIjoiMHg1YmMyNWNkZThmZjIzMTliNWQzYzA0NDM4ZWU3NjAwMjAzNGYwMGM0MmFmNTUwNmRmZjhiMDgzMTRlZjYwYjg1IiwidCI6IjIwMjYtMDktMDMgMDA6MzE6MjAuODE3In0"
}
```

`event_type` is validated against a fixed set rather than passed through, because an unknown value
would return an empty list indistinguishable from "this wallet never did that". The accepted set is:
`deposit`, `withdraw`, `send`, `spotTransfer`, `internalTransfer`, `subAccountTransfer`,
`accountClassTransfer`, `vaultDeposit`, `vaultWithdraw`, `vaultCreate`, `vaultDistribution`,
`vaultLeaderCommission`, `borrowLend`, `rewardsClaim`.

⚠ `send` is recorded **one-sided** — the outflow is seen while the matching inflow is not. That is
the same defect the `flow_unbalanced` flag on
[`/leaderboard/flow-adjusted`](/docs/endpoints/data/hyperliquid/leaderboard-flow-adjusted) reports.


# /wallets/{address}/trades/summary (/docs/endpoints/data/hyperliquid/wallets-address-trades-summary)



```
GET https://data.vike.io/v1/hyperliquid/wallets/{address}/trades/summary
```

Trade statistics for one wallet, overall **and per coin**.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/wallets/0x25773676902085225ae5751075e4161369334897/trades/summary?window=all" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="address" loc="path">
    The wallet
  </Param>

  <Param name="window" loc="query">
    `1d`

     \| 

    `7d`

     \| 

    `30d`

     \| 

    `all`

    . Default 

    `all`
  </Param>
</Params>

Truncated: `by_coin` holds **730** rows and the full response is **686,955 bytes** — a per-wallet
summary is not a small object. `overall` is complete; one `by_coin` row is shown.

```json title="Example response"
{
  "wallet": "0x25773676902085225ae5751075e4161369334897",
  "window": "all",
  "overall": {
    "trade_count": 194059,
    "closed_trade_count": 143614,
    "open_trade_count": 50445,
    "fill_count": 12950561,
    "wins": 93514,
    "losses": 84375,
    "win_rate": 0.48188437537037704,
    "long_trades": 96776,
    "short_trades": 97283,
    "long_win_rate": 0.4904108456642143,
    "short_win_rate": 0.4734023416218661,
    "net_pnl": 4012369.098752309,
    "total_winning_pnl": 31301555.306204822,
    "total_losing_pnl": -27289186.20745252,
    "avg_gain": 334.7258731976477,
    "avg_loss": -323.42739208832614,
    "median_gain": 8.475151,
    "median_loss": -7.714446000000001,
    "median_duration": 139,
    "avg_duration": 5520.710223237289,
    "max_duration": 9171206,
    "median_size_usd": 7987.900000000001,
    "avg_trade_size": 52618.05303111898,
    "max_trade_size_usd": 22907390.75299998,
    "profit_factor": 1.1470314676388755,
    "payoff_ratio": 1.0349335937082162,
    "expectancy": 20.676026871994132,
    "total_fees": 1188580.8811811705,
    "total_volume": 36620085194.54977,
    "volume_share_pct": 100.0,
    "first_trade_ts": "2026-01-02T12:03:58.812000+00:00",
    "last_trade_ts": "2026-09-03T07:45:37.776000+00:00",
    "first_open_ts": "2026-01-02T12:03:58.812000+00:00",
    "last_close_ts": "2026-09-03T07:44:53.266000+00:00"
  },
  "by_coin": [
    {
      "trade_count": 26946,
      "closed_trade_count": 26292,
      "open_trade_count": 654,
      "fill_count": 1965539,
      "wins": 13367,
      "losses": 12757,
      "win_rate": 0.4960662064870482,
      "long_trades": 13597,
      "short_trades": 13349,
      "long_win_rate": 0.49202029859527835,
      "short_win_rate": 0.5001872799460634,
      "net_pnl": -113790.09055999969,
      "total_winning_pnl": 413414.5836639994,
      "total_losing_pnl": -527204.6742239995,
      "avg_gain": 30.92800057335224,
      "avg_loss": -41.32669704664102,
      "median_gain": 1.3275439999999998,
      "median_loss": -0.838675,
      "median_duration": 27,
      "avg_duration": 548.5271945839038,
      "max_duration": 6423232,
      "median_size_usd": 10717.174800000581,
      "avg_trade_size": 44350.39012839752,
      "max_trade_size_usd": 16950533.750400003,
      "profit_factor": 0.7841633503582087,
      "payoff_ratio": 0.7483782344968705,
      "expectancy": -4.222893585689887,
      "total_fees": 121978.92007200004,
      "total_volume": 5416660000.848094,
      "volume_share_pct": 14.791500271152469,
      "first_trade_ts": "2026-01-02T12:03:58.812000+00:00",
      "last_trade_ts": "2026-09-03T07:18:07.783000+00:00",
      "first_open_ts": "2026-01-02T12:03:58.812000+00:00",
      "last_close_ts": "2026-09-03T07:00:58.017000+00:00",
      "asset": "xyz:XYZ100"
    }
  ],
  "coin_count": 730,
  "net_pnl": 4012369.098752309
}
```

Carries medians as well as means, deliberately: one $4M outlier drags the mean trade size far from
anything the wallet typically does, and the mean is where most leaderboards stop.


# /wallets/{address}/trades (/docs/endpoints/data/hyperliquid/wallets-address-trades)



```
GET https://data.vike.io/v1/hyperliquid/wallets/{address}/trades
```

Closed round-trip trades for one wallet, newest first, cursor-paged.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/wallets/0x25773676902085225ae5751075e4161369334897/trades?limit=3" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="address" loc="path">
    The wallet
  </Param>

  <Param name="coin" loc="query">
    HL coin ticker, e.g. 

    `BTC`

    . Omit for all
  </Param>

  <Param name="start` / `end" loc="query">
    ISO-8601 UTC bounds
  </Param>

  <Param name="limit" loc="query">
    Default 100, max 5000
  </Param>

  <Param name="cursor" loc="query">
    `nextCursor`

     from the previous page, verbatim
  </Param>
</Params>

```json title="Example response"
{
  "wallet": "0x25773676902085225ae5751075e4161369334897",
  "trades": [
    {
      "asset": "io:SNDK",
      "direction": "short",
      "open_ts": "2026-09-03T07:20:22.487000+00:00",
      "close_ts": "2026-09-03T07:44:53.266000+00:00",
      "duration_seconds": 1470,
      "entry_price": 1545.0404275385101,
      "exit_price": 1544.4,
      "max_size_token": 3.3660999999999994,
      "max_size_usd": 5200.624499999999,
      "volume_usd": 7988.22181,
      "realized_pnl": -17.077995,
      "total_fee": 0.052302,
      "fill_count": 14,
      "is_complete": true
    },
    {
      "asset": "xyz:SP500",
      "direction": "short",
      "open_ts": "2026-09-03T07:25:31.682000+00:00",
      "close_ts": "2026-09-03T07:44:46.388000+00:00",
      "duration_seconds": 1154,
      "entry_price": 7668.138927427963,
      "exit_price": 7676.2,
      "max_size_token": 7.4959999999999996,
      "max_size_usd": 57477.4812,
      "volume_usd": 114989.9841,
      "realized_pnl": -29.252252,
      "total_fee": 1.873843,
      "fill_count": 39,
      "is_complete": true
    },
    {
      "asset": "xyz:HYUNDAI",
      "direction": "long",
      "open_ts": "2026-09-03T07:41:59.151000+00:00",
      "close_ts": "2026-09-03T07:44:15.479000+00:00",
      "duration_seconds": 136,
      "entry_price": 281.88,
      "exit_price": 281.77,
      "max_size_token": 2.4,
      "max_size_usd": 676.512,
      "volume_usd": 1355.04746,
      "realized_pnl": -0.156,
      "total_fee": 0.022122,
      "fill_count": 7,
      "is_complete": true
    }
  ],
  "nextCursor": "eyJhIjoieHl6OkhZVU5EQUkiLCJjIjoiMjAyNi0wOS0wMyAwNzo0NDoxNS40NzkiLCJkIjoxLCJvIjoiMjAyNi0wOS0wMyAwNzo0MTo1OS4xNTEifQ"
}
```


# /wallets/{address} (/docs/endpoints/data/hyperliquid/wallets-address)



```
GET https://data.vike.io/v1/hyperliquid/wallets/{address}
```

One wallet in one call: equity, its cohort labels on each ladder, the risk-metric set, lifetime
external flow and the open-positions block. The entry point for any per-wallet investigation.

```sh title="cURL"
curl -s "https://data.vike.io/v1/hyperliquid/wallets/0x25773676902085225ae5751075e4161369334897?window=all&openedWithin=all" \
  -H "X-API-KEY: $VIKE_API_KEY"
```

<Params>
  <Param name="address" loc="path">
    The wallet
  </Param>

  <Param name="window" loc="query">
    `1d`

     \| 

    `7d`

     \| 

    `30d`

     \| 

    `all`

    . Default 

    `all`
  </Param>

  <Param name="openedWithin" loc="query">
    `24h`

     \| 

    `7d`

     \| 

    `30d`

     \| 

    `all`

    . Default 

    `all`
  </Param>
</Params>

```json title="Example response"
{
  "wallet": "0x25773676902085225ae5751075e4161369334897",
  "window": "all",
  "metrics_updated_at": "2026-09-03T08:05:59+00:00",
  "has_metrics": true,
  "equity": {
    "as_of": "2026-09-03T08:04:00+00:00",
    "account_value": 1661040.506568,
    "margin_used": 753469.656636,
    "cash_balance_usd": 5073036.012782,
    "total_unrealized_pnl": -127149.9813,
    "num_positions": 140
  },
  "open_positions": {
    "count": 143,
    "notional_usd": 11949787.046935001,
    "unrealized_pnl": -127250.71641500016,
    "margin_used": 1303534.4115760627,
    "as_of": "2026-09-03T07:59:00+00:00",
    "dexes": [
      "HL",
      "IO",
      "XYZ",
      "PARA"
    ],
    "opened_within": "all",
    "oldest_opened_at": "2026-04-02T08:36:00+00:00",
    "newest_opened_at": "2026-09-02T19:38:00+00:00",
    "with_known_open_ts": 143
  },
  "cohorts": {
    "size": "3x whale",
    "pnl": "3x smart",
    "pnl_tag": "drawdown_recovery",
    "style_tag": "streak_trader"
  },
  "lifetime": {
    "cum_realized_pnl": 3917992.366811535,
    "cum_fills": 6417096,
    "last_fill_ts": "2026-09-03T08:07:48.351000+00:00",
    "deposit_usd": 0.0,
    "withdraw_usd": 0.0,
    "net_deposit_usd": 0.0,
    "vault_deposit_usd": 0.0,
    "vault_withdraw_usd": 0.0,
    "ledger_events": 457
  },
  "ledger_by_type": [
    {
      "event_type": "send",
      "amount_usd": -11658895.529263001,
      "fee_usd": 0.0,
      "count": 457,
      "first_ts": "2026-01-14T19:00:57.067000+00:00",
      "last_ts": "2026-09-03T00:31:21.150000+00:00"
    }
  ],
  "metrics": {
    "wallet": "0x25773676902085225ae5751075e4161369334897",
    "account_value": 1671052.77246,
    "total_realized_pnl": 3716145.2005327553,
    "roi": 222.38347356691327,
    "pnl_pct": 222.38347356691327,
    "total_volume": 26290176002.307007,
    "total_fee": 930945.91746686,
    "trade_count": 135740,
    "win_count": 70654,
    "loss_count": 65086,
    "win_rate": 0.5205097794532776,
    "long_win_rate": 0.5239437818527222,
    "short_win_rate": 0.5170527696609497,
    "long_pnl": 1892139.8385331659,
    "short_pnl": 1824005.3619995913,
    "profit_factor": 1.2365819215774536,
    "expectancy": 27.376935321443607,
    "max_drawdown_pct": 100.0,
    "current_drawdown_pct": 36.20000076293945,
    "calmar_ratio": 2.223834753036499,
    "recovery_factor": 2.223834753036499,
    "max_win_streak": 28,
    "max_loss_streak": 77,
    "avg_leverage": 0.0,
    "avg_duration_seconds": 4492,
    "pnl_cohort_tag": "drawdown_recovery",
    "style_cohort_tag": "streak_trader"
  }
}
```

⚠ `openedWithin` bounds the **open-positions block only**. The equity, lifetime and metrics blocks
are wallet-level totals with nothing per-position to filter, and bounding them would return a
number that looks bounded and is not. Positions with no known open time are excluded from every
bounded bucket — the same rule [`/segments`](/docs/endpoints/data/hyperliquid/segments) and
[`/heatmap`](/docs/endpoints/data/hyperliquid/heatmap) apply, so cohort comparisons stay like-for-like.


# On-chain REST (/docs/endpoints/data/onchain)



`/v1/onchain/` answers questions about EVM addresses and ERC-20 tokens: what a wallet holds, who it
trades with, where its money went, who is accumulating a token, and which labelled institution sits
behind an address. Fifteen endpoints, all on `https://data.vike.io`, all behind the
[API key](/docs/data/authentication) and the [shared hourly budget](/docs/data/rate-limits).

The chain is a **filter, not a namespace** — `?chain=ethereum|bsc|base` on most routes, because the
data behind this namespace is multi-chain by design. ⚠ One route accepts `chain` and then ignores
it: [`POST /labels/batch`](/docs/endpoints/data/onchain/labels-batch) is Ethereum-only whatever you send.

Every call carries the credential in a header — `X-API-Key: vk_...` or
`Authorization: Bearer vk_oat_...`, either alone is enough
([Authentication](/docs/data/authentication)) — and spends one unit of the shared hourly counter
([Rate limits](/docs/data/rate-limits)):

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/onchain/wallets/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/counterparties?window=7d&limit=20"
```

Each endpoint has its own page, carrying its full request line in a fence at the top; the page
titles are written as the path, without the method.

<Callout title="Full MCP parity — the REST and MCP answers cannot drift">
  The 15 endpoints on this namespace map one-to-one onto 15 of the tools the MCP server at `vike.io/mcp`
  advertises, and each pair is answered by the same query — there is no second implementation to drift.

  So a REST call and the matching MCP tool call return **the same payload**. What they do *not* share
  is the HTTP contract on top: parameter names, defaults, ceilings and billing differ, and the three
  sections below are about exactly those differences.
</Callout>

## Conventions on this namespace [#conventions-on-this-namespace]

### Omitting a parameter is not the same as passing zero [#omitting-a-parameter-is-not-the-same-as-passing-zero]

A numeric parameter sent as `0` — or as an empty string — is treated exactly like one you did not
send at all: the endpoint falls back to its own default, and that default is not always zero.

| Parameter                            | Passing `0`, or omitting it, resolves to |
| ------------------------------------ | ---------------------------------------- |
| `min_usd` on `/trace`                | **10,000 USD**                           |
| `min_usd` on `/balances`             | **1.0 USD**                              |
| `min_usd` on `/transactions`         | 0 (no floor)                             |
| `days` on `/pnl` and `/transactions` | 30                                       |
| `depth` / `width` on `/trace`        | 2 / 5                                    |

⚠ The consequence worth carrying: &#x2A;*you cannot ask `/trace` or `/balances` for a floor of exactly
zero.** `min_usd=0` selects the default floor instead of removing it. Pass a small positive number
(`min_usd=0.01`) if you want everything.

### Two ceilings, and the lower one is silent [#two-ceilings-and-the-lower-one-is-silent]

The `limit` a route *accepts* and the `limit` it *applies* are two different numbers. The request
validator enforces the higher one; the query underneath then quietly caps at the lower one. Nothing
rejects an over-cap value and nothing reports the cap — a request for 1,000 rows returns 50 and looks
exactly like a wallet with only 50 counterparties.

| Endpoint                            | Parameter         | HTTP accepts               | Actually applied   |
| ----------------------------------- | ----------------- | -------------------------- | ------------------ |
| `/wallets/compare`                  | `limit`           | ≤ 1000 (route default 100) | **≤ 50**           |
| `/wallets/{address}/transactions`   | `limit`           | ≤ 1000 (route default 100) | **≤ 500**          |
| `/wallets/{address}/counterparties` | `limit`           | ≤ 1000 (route default 100) | **≤ 50**           |
| `/wallets/{address}/pnl`            | `days`            | any integer                | **1–365**          |
| `/wallets/{address}/trace`          | `depth` / `width` | any integer                | **1–5** / **1–10** |
| `/tokens/screener`                  | `limit`           | ≤ 500 (route default 50)   | **≤ 100**          |
| `/tokens/{token_address}/holders`   | `limit`           | ≤ 500 (route default 50)   | **≤ 50**           |

⚠ This is also where REST and MCP produce **different default row counts from the same query**. A
REST route always applies its own `limit` default, even when you send none, so
`/wallets/{address}/counterparties` defaults to 100 and caps at 50 rows, while the
`wallet_counterparties` MCP tool defaults to 10. Same data, different page size. Set `limit`
explicitly if you care.

### Credits are counted differently from MCP [#credits-are-counted-differently-from-mcp]

**Every on-chain REST call logs one credit**, whatever it cost to serve — no route on this namespace
charges more. Over MCP the same work is priced by tool instead, from 0 (`token_search`) to 4
(`wallet_trace`, the heaviest graph traversal). The hourly request budget is separate again and
charges one unit per request on every surface, this namespace included.

### Errors [#errors]

Status codes and the error envelope are namespace-wide and documented under [Errors](/docs/data/errors).
The mapping: a rejected input becomes **400** carrying the reason, and any other failure becomes
**503**.

⚠ &#x2A;*Not every failure arrives as a 4xx.** Some errors on this namespace come back as **HTTP 200**
carrying a one-element array whose single entry describes the problem, so a client that branches on
the status code alone will read a failure as an empty-ish success. The reachable case here is
[`POST /labels/batch`](/docs/endpoints/data/onchain/labels-batch) — see that endpoint's own page.

A malformed address on the two routes that reach outside ClickHouse (`/balances` and `/ens`) *does* arrive
as a **400**, with a message reading `Bad EVM address: …`. The check is strict: a `0x` prefix and
exactly 42 characters.

## Wallets [#wallets]

Nine endpoints. `/wallets/compare` and `/wallets/discover` are literal paths rather than addresses —
they take no `{address}` segment.

| Endpoint                                                                                          | What it answers                                                                                      |
| ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| [`GET /wallets/{address}`](/docs/endpoints/data/onchain/wallets-address)                               | Aggregate metrics for one wallet across the 24h / 7d / 30d / 90d / all windows in a single response  |
| [`GET /wallets/{address}/transactions`](/docs/endpoints/data/onchain/wallets-address-transactions)     | The raw transfer list for a wallet: individual transfers, not aggregates                             |
| [`GET /wallets/{address}/counterparties`](/docs/endpoints/data/onchain/wallets-address-counterparties) | The addresses this wallet transacted with most, by combined transfer volume over a window            |
| [`GET /wallets/{address}/pnl`](/docs/endpoints/data/onchain/wallets-address-pnl)                       | A daily net-flow series for the wallet — net inflow USD, cumulative, gross volume, transaction count |
| [`GET /wallets/{address}/balances`](/docs/endpoints/data/onchain/wallets-address-balances)             | Current ERC-20 balances across the major EVM chains, with a USD value and price per holding          |
| [`GET /wallets/{address}/trace`](/docs/endpoints/data/onchain/wallets-address-trace)                   | Follow the money outward — top counterparties per hop, up to `depth` hops                            |
| [`GET /wallets/{address}/ens`](/docs/endpoints/data/onchain/wallets-address-ens)                       | Reverse ENS lookup — turn an address into `vitalik.eth`                                              |
| [`GET /wallets/compare`](/docs/endpoints/data/onchain/wallets-compare)                                 | Are these two wallets related? Shared counterparties and shared tokens within a window               |
| [`GET /wallets/discover`](/docs/endpoints/data/onchain/wallets-discover)                               | The leaderboard: most active wallets over a window, ranked by the metric you pick                    |

## Tokens [#tokens]

| Endpoint                                                                                          | What it answers                                                                                  |
| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| [`GET /tokens/search`](/docs/endpoints/data/onchain/tokens-search)                                     | Resolve a symbol, name or contract address to the tokens we know about                           |
| [`GET /tokens/screener`](/docs/endpoints/data/onchain/tokens-screener)                                 | Find tokens by activity within a window — volume, net inflow, holder count or smart-money inflow |
| [`GET /tokens/{token_address}/transfers`](/docs/endpoints/data/onchain/tokens-token-address-transfers) | Who bought and who sold a token over a period — the top buyers or the top sellers                |
| [`GET /tokens/{token_address}/holders`](/docs/endpoints/data/onchain/tokens-token-address-holders)     | The holder leaderboard for a token, ranked by cumulative net inflow USD                          |

## Labels [#labels]

| Endpoint                                                                                | What it answers                                                                             |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| [`POST /labels/batch`](/docs/endpoints/data/onchain/labels-batch)                            | Enrich a list of addresses in one call — entity, wallet type, risk flag and 30-day activity |
| [`GET /labels/{address}/provenance`](/docs/endpoints/data/onchain/labels-address-provenance) | The full label cascade for one address, with per-source attribution                         |


# /labels/{address}/provenance (/docs/endpoints/data/onchain/labels-address-provenance)



```
GET https://data.vike.io/v1/onchain/labels/{address}/provenance
```

The full label cascade for one address, with per-source attribution: what Arkham, OLI, Blockscout,
Dune, the MEW darklist, Etherscan and our own heuristic classifier each claimed, plus a consensus
entity and type. Use it when you need to know *who said* an address is a given exchange, not merely
that something did.

This capture is a good illustration of the ⚠ above, because it is a **thin** result for an address
nobody would call obscure: one of the most-transacted exchange hot wallets on Ethereum resolves to
`source_count: 1`. Whether the other named sources genuinely do not carry it or were mid-rebuild at
capture time cannot be told from the response — which is exactly the ambiguity the warning describes.

Two structural notes:

* **`sources[]` entries are not the same shape as `consensus`.** A source carries
  `{source, label, entity, category}` in the provider's own vocabulary — note `"entity": "Binance"`
  capitalised and `"category": "Hot Wallet"` — while `consensus` carries the normalised
  `{entity, wallet_type, cex_product, user_subtype, risk_flag, confidence}` with `"entity":
  "binance"` lower-cased and `"wallet_type": "cex"`. Join on the consensus fields; the source fields
  are free text.
* **The captured `source` reads `provider_a`, not a vendor name.** The sources are anonymised on
  the wire, so you cannot use this route to tell which of the named providers made a claim — only
  how many distinct sources did, and what each said.

`found: true` with `source_count: 1` is a successful lookup. An address genuinely unknown to the
cascade is the case to test your handling against separately.

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/onchain/labels/0x28C6c06298d514Db089934071355E5743bf21d60/provenance"
```

<Params>
  <Param name="address" loc="path">
    Wallet address, 0x-prefixed hex
  </Param>
</Params>

The complete response for the Binance 14 hot wallet, captured 2026-09-03.

```json title="Example response"
{
  "address": "0x28C6c06298d514Db089934071355E5743bf21d60",
  "found": true,
  "consensus": {
    "entity": "binance",
    "wallet_type": "cex",
    "cex_product": "retail",
    "user_subtype": "active",
    "risk_flag": null,
    "confidence": "medium"
  },
  "sources": [
    {
      "source": "provider_a",
      "label": "Binance: Hot Wallet (0x28C)",
      "entity": "Binance",
      "category": "Hot Wallet"
    }
  ],
  "source_count": 1
}
```

⚠ It degrades rather than erroring: when an upstream label dump is mid-rebuild the route returns
**fewer rows** instead of a failure. A thin provenance list is therefore ambiguous between *few
sources know this address* and *a source is rebuilding* — re-query before concluding an address is
unlabelled.


# /labels/batch (/docs/endpoints/data/onchain/labels-batch)



```
POST https://data.vike.io/v1/onchain/labels/batch
```

Enrich a list of addresses in one call: entity, wallet type, risk flag, 30-day net flow, 30-day
volume and 30-day transaction count, one row per input address **in input order**. This is the route
for a CSV of addresses rather than a single wallet.

The rows come back **in input order** as documented, and each echoes its own `wallet` — so you can
verify the alignment rather than trusting the ordering. The echoed address is lower-cased, while the
first address was sent checksummed; compare case-insensitively.

This is also the shape to check against the ⚠ above: a successful row carries `found: true` and no
`error` key. A **rejected** batch returns HTTP 200 carrying `[{"error": "..."}]` — one element, one
key — so the test is `"error" in rows[0]`, and it must be run before treating the array as data.

Two field notes from the capture. `risk_flag` is the **empty string** rather than `null` on both
clean rows, so a truthiness check is the right test and an `is None` check is not. And
`wallet_type` is a classification of *behaviour*, not of ownership: `vitalik.eth` is typed `dex`
here, which describes where its transfers land rather than what the address is — do not read
`wallet_type` as "this address is a DEX".

```sh title="cURL"
curl -X POST -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/onchain/labels/batch?addresses=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045,0xbbbbbbbbbb9cc5e90e3b3af64bdaf62c37eeffcb"
```

<Params>
  <Param name="addresses" loc="query">
    Comma-separated addresses. Capped at 100
  </Param>

  <Param name="chain" loc="query">
    Accepted and 

    **ignored**

    . Results are always Ethereum — see below
  </Param>
</Params>

Note the `-X POST` and the &#x2A;*absent `-d`** — as described earlier, this route is a POST with no body,
so `curl` must be told the method explicitly. The complete response covers two addresses,
captured 2026-09-03.

```json title="Example response"
[
  {
    "entity": "vitalik buterin",
    "wallet_type": "dex",
    "confidence": "medium",
    "risk_flag": "",
    "net_30d_usd": -70023.25164,
    "volume_30d_usd": 70046.74836,
    "tx_30d": 454,
    "tokens_30d_count": 157,
    "wallet": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
    "found": true
  },
  {
    "entity": "morpho",
    "wallet_type": "defi",
    "confidence": "medium",
    "risk_flag": "",
    "net_30d_usd": -357800362.784802,
    "volume_30d_usd": 2359366854024.6597,
    "tx_30d": 409814,
    "tokens_30d_count": 235,
    "wallet": "0xbbbbbbbbbb9cc5e90e3b3af64bdaf62c37eeffcb",
    "found": true
  }
]
```

⚠ &#x2A;*`chain` does nothing on this route.** The value is accepted and then never applied — labels and
features are always read from Ethereum. So `chain=bsc` and `chain=base` return **Ethereum labels
rather than an error**. The `wallet_batch_labels` MCP tool advertises the same three-value enum and
behaves identically. This is the one dead `chain` in the namespace: `/wallets/{address}/counterparties`,
`/tokens/{token_address}/holders` and `/tokens/screener` each genuinely honour it.

<Callout type="warn" title="POST, but the addresses go in the query string">
  This is the **only non-GET route in the `/v1` REST surface** — the published OpenAPI spec declares 61
  GET operations and this one POST. Despite the method it takes **no request body**: `addresses` is a
  comma-separated query parameter, and the spec declares no `requestBody`. A JSON body is ignored.

  Because the addresses ride in the URL, a long batch makes a long URL. Split large batches across
  several calls rather than assuming the 100-address cap is reachable in one.
</Callout>

⚠ &#x2A;*A rejected batch arrives as HTTP 200, not 400.** Send more than 100 addresses and the response is
a successful one carrying a one-element array whose single key is `error`, reading
`batch capped at 100 addresses`. An empty `addresses` value behaves the same way, with
`addresses (list) is required`. **Check for an `error` key in the first element before treating the
array as data** — the status code will not tell you.


# /tokens/screener (/docs/endpoints/data/onchain/tokens-screener)



```
GET https://data.vike.io/v1/onchain/tokens/screener
```

Find tokens by activity within a window — rank by volume, net inflow, holder count or smart-money
inflow, with floors on volume and holder count and a smart-money-only toggle.

⚠ **`symbol` is empty and `name` is `null` on every captured row** — including USDC, WBTC and WETH,
the three most identifiable ERC-20s on Ethereum. The screener identifies tokens **by address only**.
Plan to resolve names yourself via
[`/tokens/search`](/docs/endpoints/data/onchain/tokens-search) (which does carry `symbol`, `name` and a
logo), and do not build a UI that assumes these two fields are populated. The addresses above are
USDC, WBTC and WETH respectively.

⚠ **`net_flow_usd` is `0.0` on two of the three rows**, with `in_usd` exactly equal to `out_usd` to
the cent. Where a token's flow nets to zero this precisely, the figures are almost certainly a
double-counted transfer volume rather than a directional flow — every transfer landing on both
sides. Sorting by `net_inflow` will rank such tokens at zero regardless of what actually moved.

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/onchain/tokens/screener?limit=3&window=24h"
```

<Params>
  <Param name="chain" loc="query">
    `ethereum`

     \| 

    `bsc`

     \| 

    `base`

    . Default 

    `ethereum`
  </Param>

  <Param name="window" loc="query">
    `24h`

     \| 

    `7d`

     \| 

    `30d`

     \| 

    `90d`

    . Default 

    `24h`
  </Param>

  <Param name="sort" loc="query">
    `volume`

     \| 

    `net_inflow`

     \| 

    `holders`

     \| 

    `smart_inflow`

    . Default 

    `volume`
  </Param>

  <Param name="min_volume_usd" loc="query">
    Drop tokens below this window volume
  </Param>

  <Param name="min_holders" loc="query">
    Drop tokens below this holder count
  </Param>

  <Param name="smart_money_only" loc="query">
    Boolean. Restrict to smart-money cohort flows
  </Param>

  <Param name="limit" loc="query">
    Route default 50; 

    **applied cap 100**
  </Param>
</Params>

The complete response for `limit=3`, captured 2026-09-03, is a bare array.

```json title="Example response"
[
  {
    "token_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "symbol": "",
    "name": null,
    "volume_usd": 137340073415.62,
    "net_flow_usd": -36603751.18,
    "in_usd": 68651734832.22,
    "out_usd": 68688338583.4,
    "unique_holders": 262663,
    "tx_count": 1706155
  },
  {
    "token_address": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599",
    "symbol": "",
    "name": null,
    "volume_usd": 127606890479.48,
    "net_flow_usd": 0.0,
    "in_usd": 63803445239.74,
    "out_usd": 63803445239.74,
    "unique_holders": 2785,
    "tx_count": 72340
  },
  {
    "token_address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "symbol": "",
    "name": null,
    "volume_usd": 107747906503.82,
    "net_flow_usd": 0.0,
    "in_usd": 53873953251.91,
    "out_usd": 53873953251.91,
    "unique_holders": 17781,
    "tx_count": 775235
  }
]
```


# /tokens/search (/docs/endpoints/data/onchain/tokens-search)



```
GET https://data.vike.io/v1/onchain/tokens/search
```

Resolve a symbol, name or contract address to the tokens we know about. The entry point for the two
address-keyed routes —
[`/tokens/{token_address}/transfers`](/docs/endpoints/data/onchain/tokens-token-address-transfers) and
[`/tokens/{token_address}/holders`](/docs/endpoints/data/onchain/tokens-token-address-holders).

⚠ **`token_address` comes back without the `0x` prefix**, while every route that consumes it —
[`/tokens/{token_address}/holders`](/docs/endpoints/data/onchain/tokens-token-address-holders) and
[`/tokens/{token_address}/transfers`](/docs/endpoints/data/onchain/tokens-token-address-transfers) —
documents its path parameter as "0x-prefixed". Piping this field straight into those routes means
prepending `0x` yourself. This is the first thing to check if a search result appears not to resolve.

⚠ &#x2A;*An exact symbol match returns one row, not a ranked list.** `q=USDC` with `limit=3` returned a
single token, so a short result is not a truncation artifact and a `limit` above the match count
costs nothing. It also means this route will not by itself warn you about symbol collisions across
chains — pass `chain` explicitly when the symbol is ambiguous.

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/onchain/tokens/search?q=USDC&limit=3"
```

<Params>
  <Param name="q" loc="query">
    Symbol, name, or address
  </Param>

  <Param name="chain" loc="query">
    `ethereum`

     \| 

    `bsc`

     \| 

    `base`

    . Default 

    `ethereum`
  </Param>

  <Param name="limit" loc="query">
    Default 10, max 100
  </Param>
</Params>

The complete response, captured 2026-09-03. `limit=3`, but only **one** token matched `USDC`.

```json title="Example response"
[
  {
    "symbol": "USDC",
    "name": "USD Coin",
    "token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "logo": "https://pub-468f7b552e104638ac0daeddde8a6aab.r2.dev/logos/coins/USDC.png"
  }
]
```

⚠ The parameter is `q` here and `query` on the MCP tool — same search, different spelling. This is
also the only endpoint in the namespace that MCP prices at **0 credits**; over REST it logs 1 like
every other route.


# /tokens/{token_address}/holders (/docs/endpoints/data/onchain/tokens-token-address-holders)



```
GET https://data.vike.io/v1/onchain/tokens/{token_address}/holders
```

The holder leaderboard for a token, ranked by cumulative net inflow USD. Returns wallet, net flow
USD, volume USD, transaction count, first and last seen dates, and known labels.

The capture makes the ⚠ above concrete. Every one of the top three USDC "holders" is an
intermediary, not an owner: a Coinbase wallet, the Morpho lending protocol and an MEV bot. The
second row moved **11.3 trillion USD** of volume to net 45.5 billion — a ratio that only makes sense
for a contract money passes through. Read this route as *who moves the most of this token*, and use
[`/wallets/{address}/balances`](/docs/endpoints/data/onchain/wallets-address-balances) when you mean who
holds it.

Note `entity` and `wallet_type` are populated on all three rows here (`coinbase`/`cex`,
`morpho`/`defi`, `mev bot`/`mev`), which is what makes the list interpretable — an unlabelled
address at the top of this ranking tells you very little on its own.

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/onchain/tokens/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/holders?limit=3"
```

<Params>
  <Param name="token_address" loc="path">
    Token contract address, 0x-prefixed
  </Param>

  <Param name="chain" loc="query">
    `ethereum`

     \| 

    `bsc`

     \| 

    `base`

    . Default 

    `ethereum`
  </Param>

  <Param name="limit" loc="query">
    Route default 50; 

    **applied cap 50**
  </Param>
</Params>

The USDC holder leaderboard, captured 2026-09-03 — the complete response for `limit=3`.

```json title="Example response"
[
  {
    "wallet": "0xa9d1e08c7793af67e9d92fe308d5697fb81d3e43",
    "net_flow_usd": 85269157826.77954,
    "volume_usd": 1920884159776.6255,
    "tx_count": 11431454,
    "first_seen": "2022-07-19",
    "last_active": "2026-09-03",
    "entity": "coinbase",
    "wallet_type": "cex"
  },
  {
    "wallet": "0xbbbbbbbbbb9cc5e90e3b3af64bdaf62c37eeffcb",
    "net_flow_usd": 45553365504.30071,
    "volume_usd": 11301542548648.928,
    "tx_count": 2150944,
    "first_seen": "2024-01-03",
    "last_active": "2026-09-03",
    "entity": "morpho",
    "wallet_type": "defi"
  },
  {
    "wallet": "0x06cff7088619c7178f5e14f0b119458d08d2f5ef",
    "net_flow_usd": 27999681851.978294,
    "volume_usd": 5320232364455.69,
    "tx_count": 641309,
    "first_seen": "2025-02-06",
    "last_active": "2026-09-03",
    "entity": "mev bot",
    "wallet_type": "mev"
  }
]
```

⚠ Ranked by *net inflow accumulated over our recorded transfer history*, not by current on-chain
balance. A wallet that accumulated and then exited still ranks by what it moved through. For the
present holdings of one specific wallet, use
[`/wallets/{address}/balances`](/docs/endpoints/data/onchain/wallets-address-balances).


# /tokens/{token_address}/transfers (/docs/endpoints/data/onchain/tokens-token-address-transfers)



```
GET https://data.vike.io/v1/onchain/tokens/{token_address}/transfers
```

Who bought and who sold a token over a period — the top buyers or the top sellers with quantities and
USD values. `tab` selects which side you get; it is one side per call, not both.

⚠ &#x2A;*Half these fields are presentation, not data.** `addr_short`, the six `*_fmt` strings,
`net_usd_raw` and `net_bar_pct` are pre-rendered for a UI — `net_bar_pct: 7` is a bar width, and
`net_usd_fmt: "$-0.0"` on the second row is a formatted string, not a number. A machine consumer
wants `address`, `bought`, `sold`, `net_tokens`, `usd_spent`, `usd_received`, `net_usd` and `chains`,
and should ignore the rest.

⚠ &#x2A;*`net_usd` and `net_usd_raw` disagree by a factor of 1e6, and they disagree in sign too.** Row 1
reports `net_usd: 2954179998100` against `net_usd_raw: 2954180.0` — the `_raw` field is the smaller
of the two, despite its name, and `net_usd_fmt` renders as `"$2.95M"`, agreeing with `net_usd_raw`.
So the field the formatter trusts is `net_usd_raw`; `net_usd` carries the un-scaled figure. On row 1
the sign also flips: `net_tokens` is `-2954179998100` while `net_usd` is `+2954179998100`.

⚠ **`bought` and `usd_spent` are byte-identical on every captured row**, as are `sold` and
`usd_received` — a token quantity and a USD amount reported as the same number. For a stablecoin
those are legitimately close, but they are *exactly* equal here, so do not assume `usd_spent` has
been priced independently of the token count.

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/onchain/tokens/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/transfers?period=24h&tab=sold"
```

<Params>
  <Param name="token_address" loc="path">
    Token contract address, 0x-prefixed
  </Param>

  <Param name="period" loc="query">
    `1h`

     \| 

    `24h`

     \| 

    `7d`

     \| 

    `30d`

    . Default 

    `24h`
  </Param>

  <Param name="tab" loc="query">
    `bought`

     \| 

    `sold`

    . Default 

    `sold`
  </Param>

  <Param name="chain" loc="query">
    `ethereum`

     \| 

    `bsc`

     \| 

    `base`

     \| 

    `all`

    . Default 

    `ethereum`
  </Param>
</Params>

USDC sellers over 24h, captured 2026-09-03. The response is a bare array of **exactly 10 rows** —
confirming the fixed limit above. The first two rows are shown verbatim; the other eight have the
same 18 fields.

```json title="Example response"
[
  {
    "address": "0xbbbbbbbbbb9cc5e90e3b3af64bdaf62c37eeffcb",
    "bought": 14742019759758039,
    "sold": 14744973939756139,
    "net_tokens": -2954179998100,
    "usd_spent": 14742019759758039,
    "usd_received": 14744973939756139,
    "net_usd": 2954179998100,
    "chains": [
      "eth"
    ],
    "title": null,
    "addr_short": "0xbbbb...ffcb",
    "bought_fmt": "14.74B",
    "sold_fmt": "14.74B",
    "net_tokens_fmt": "2.95M",
    "usd_spent_fmt": "$14.74B",
    "usd_received_fmt": "$14.74B",
    "net_usd_raw": 2954180.0,
    "net_usd_fmt": "$2.95M",
    "net_bar_pct": 7
  },
  {
    "address": "0x06cff7088619c7178f5e14f0b119458d08d2f5ef",
    "bought": 6138936624396122,
    "sold": 6138936624396121,
    "net_tokens": 1,
    "usd_spent": 6138936624396122,
    "usd_received": 6138936624396121,
    "net_usd": -1,
    "chains": [
      "eth"
    ],
    "title": null,
    "addr_short": "0x06cf...f5ef",
    "bought_fmt": "6.14B",
    "sold_fmt": "6.14B",
    "net_tokens_fmt": "0.0",
    "usd_spent_fmt": "$6.14B",
    "usd_received_fmt": "$6.14B",
    "net_usd_raw": -0.0,
    "net_usd_fmt": "$-0.0",
    "net_bar_pct": 0
  }
]
```

⚠ &#x2A;*The row count is fixed at 10 and there is no way to change it.** The route exposes no `limit`
parameter, and the MCP tool ignores one if you send it. For a longer ranking, use
[`/holders`](/docs/endpoints/data/onchain/tokens-token-address-holders).


# /wallets/{address}/balances (/docs/endpoints/data/onchain/wallets-address-balances)



```
GET https://data.vike.io/v1/onchain/wallets/{address}/balances
```

Current token balances for one wallet, read from the chain when you ask. The candidate token set
comes from our own transfer index; the amounts come from `balanceOf` on the node, so a balance is
what the contract says it is at that block rather than a figure derived from history.

<Callout type="warn" title="Two chains, and the list is the answer — not a default">
  `ethereum` and `bsc` are the chains this route can answer for, because they are the two the
  transfer index covers and the index is what supplies the candidate tokens. `chains_scanned` in
  the response names what was actually read.

  Ask for a chain outside that set and it comes back named in `chain_errors` — **not** silently
  scanned and empty. A wallet reported as holding nothing because nobody looked is the one answer
  this endpoint must never give.
</Callout>

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/onchain/wallets/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balances?min_usd=3000"
```

<Params>
  <Param name="address" loc="path">
    Wallet address, 0x-prefixed, exactly 42 characters
  </Param>

  <Param name="chains" loc="query">
    Comma-separated. 

    `ethereum`

     and 

    `bsc`

    ; the aliases 

    `eth`

    , 

    `mainnet`

    , 

    `bnb`

     and 

    `binance`

     are accepted. Omit for both.
  </Param>

  <Param name="min_usd" loc="query">
    Hide holdings worth less than this. Default 

    `0`

    , which filters nothing. ⚠ Any floor above 

    `0`

     also excludes holdings we cannot price, since an unpriced holding cannot be shown to clear it.
  </Param>
</Params>

A live response, captured 2026-09-04 for `vitalik.eth` at `min_usd=3000`.

```json title="Example response"
{
  "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  "total_usd": 10532.82,
  "chains_scanned": ["ethereum"],
  "holdings": [
    {
      "chain": "ethereum",
      "symbol": "ENS",
      "name": "Ethereum Name Service",
      "address": "0xc18360217d8f7ab5e7c516566761ea12ce7f9d72",
      "balance": 1144.0360760636715,
      "balance_raw": "1144036076063671431479",
      "usd_value": 6843.62,
      "usd_price": 5.982
    },
    {
      "chain": "ethereum",
      "symbol": "WETH",
      "name": "Wrapped Ether",
      "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "balance": 1.461898164019089,
      "balance_raw": "1461898164019088870",
      "usd_value": 3689.2,
      "usd_price": 2523.57
    },
    {
      "chain": "ethereum",
      "symbol": "WEI",
      "name": "Wei Name Service",
      "address": "0x0000000000696760e15f265e828db644a0c242eb",
      "balance": 1.0,
      "balance_raw": "1",
      "usd_value": null,
      "usd_price": null
    }
  ]
}
```

## `usd_value: null` is a holding, not an error [#usd_value-null-is-a-holding-not-an-error]

A balance is measured; a price is looked up, and most tokens do not have one — **434 of the
tokens traded on Ethereum carry a price feed**, out of the hundreds of thousands that exist. A
holding we cannot price is still listed, with `usd_value` and `usd_price` both `null`, because
dropping it would under-report the wallet.

`total_usd` therefore sums only the priced holdings. Read it as a floor, never as net worth, and
never infer "worthless" from a `null` — it means *unpriced here*.

⚠ &#x2A;*This is why `min_usd` above `0` drops unpriced holdings, and why it defaults to `1`.** Most
tokens in a long-lived wallet are unpriced airdrops — `vitalik.eth` carries over seven thousand
of them. A value floor that kept everything it could not price would return all of them and
filter almost nothing.

`min_usd=0` is the way to ask for the complete list, and it is honoured: an omitted floor and an
explicit zero are different requests.

`balance_raw` is the integer the contract returned, as a string. Use it when you need exactness:
`balance` is that integer divided by the token's decimals and is a float, so it loses precision
on large balances.

## The native coin [#the-native-coin]

ETH on `ethereum` and BNB on `bsc` are included when non-zero, with `address: null` — a native
coin has no contract. Neither is priced by this route today, so both carry `usd_value: null`.

## What this route cannot see [#what-this-route-cannot-see]

A token the wallet holds but which never appeared in our transfer index is invisible here: the
index supplies the candidate list, and `balanceOf` is only called for tokens on it. That fails
toward **omission** — a missing row, never a wrong number.

It is the narrower of the two available gaps, and deliberately chosen. Until 2026-09-04 this
route was served by a third-party API; a period when that vendor was unavailable returned
`200` with an empty `holdings` array and `total_usd: 0.0`, which reads exactly like an empty
wallet. Both shapes are on the [changelog](/docs/changelog/data).

## Related [#related]

* [`/wallets/{address}`](/docs/endpoints/data/onchain/wallets-address) — the wallet summary
* [`/wallets/{address}/transactions`](/docs/endpoints/data/onchain/wallets-address-transactions) — the transfer history the candidate list is drawn from
* [Rate limits](/docs/data/rate-limits) · [Authentication](/docs/data/authentication)


# /wallets/{address}/counterparties (/docs/endpoints/data/onchain/wallets-address-counterparties)



```
GET https://data.vike.io/v1/onchain/wallets/{address}/counterparties
```

The addresses this wallet transacted with most, by combined transfer volume over a window. Returns
counterparty address, total volume, amount sent and received, transaction count, first and last seen,
and labels where the label cascade knows the address.

All three rows, as returned for `limit=3`.

⚠ &#x2A;*`first_seen` is the first contact *inside the window*, not the first ever.** In the capture above
every `first_seen` lands within half an hour of `2026-08-04T08:00`, which is exactly 30 days before
the call — the `window=30d` boundary, not a fact about the relationship. Widen the window and these
dates move. For a genuine lifetime first-seen, use
[`/wallets/{address}`](/docs/endpoints/data/onchain/wallets-address), whose `all` block carries one.

<Callout type="warn" title="Measured: the USD figures on this route arrive un-scaled">
  USD on [`/discover`](/docs/endpoints/data/onchain/wallets-discover) reaches you already scaled to plain
  dollars. On the evidence of these captures, **this route does not scale it** — the numbers arrive in
  **micro-USD**. The same wallet pair, the same 30-day window, measured on the same day by two routes:

  | Route                                                                     | Reported volume        | `tx_count` |
  | ------------------------------------------------------------------------- | ---------------------- | ---------- |
  | `/counterparties` (above)                                                 | `4.51759577437892E+16` | 6078       |
  | [`/trace`](/docs/endpoints/data/onchain/wallets-address-trace) edge, same pair | `45175937046.39`       | 6074       |

  `4.5175957743789e16 / 1e6 = 45,175,957,743.79` — the two agree to within 20,697 USD, and `/trace`
  is the smaller of the pair, consistent with its default 10,000 USD `min_usd` floor and the four
  fewer transfers it counts. So the two are one quantity at two scales, and this route reports the
  micro-USD one.
  **Divide `total_volume_usd`, `sent_usd` and `received_usd` by 1,000,000 to get USD**, and note the
  values also serialize in scientific notation (`4.51E+16`) — a strict JSON-number parser is fine
  with that, but a naive integer parse is not.
</Callout>

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/onchain/wallets/0x28C6c06298d514Db089934071355E5743bf21d60/counterparties?limit=3&window=30d"
```

<Params>
  <Param name="address" loc="path">
    Wallet address
  </Param>

  <Param name="chain" loc="query">
    `ethereum`

     \| 

    `bsc`

     \| 

    `base`

    . Default 

    `ethereum`
  </Param>

  <Param name="window" loc="query">
    `24h`

     \| 

    `7d`

     \| 

    `30d`

     \| 

    `90d`

     \| 

    `180d`

     \| 

    `all`

    . Default 

    `30d`
  </Param>

  <Param name="limit" loc="query">
    Route default 100; 

    **applied cap 50**
  </Param>
</Params>

A live response for the Binance 14 hot wallet, captured 2026-09-03. The response is a bare JSON
array, not an object with a wrapper key.

```json title="Example response"
[
  {
    "wallet": "0xeae7380dd4cef6fbd1144f49e4d1e6964258a4f4",
    "total_volume_usd": 4.51759577437892E+16,
    "sent_usd": 0.0,
    "received_usd": 4.51759577437892E+16,
    "tx_count": 6078,
    "first_seen": "2026-08-04T08:30:11",
    "last_seen": "2026-09-03T08:00:11",
    "entity": "wintermute",
    "wallet_type": "market_maker"
  },
  {
    "wallet": "0x21a31ee1afc51d94c2efccaa2092ad1028285549",
    "total_volume_usd": 4.216311846904386E+16,
    "sent_usd": 4.216311846904386E+16,
    "received_usd": 0.0,
    "tx_count": 2517,
    "first_seen": "2026-08-04T09:03:23",
    "last_seen": "2026-09-03T08:02:47",
    "entity": "binance",
    "wallet_type": "cex"
  },
  {
    "wallet": "0xdfd5293d8e347dfe59e90efd55b2956a1343963d",
    "total_volume_usd": 4.006098785039075E+16,
    "sent_usd": 4.006098785039075E+16,
    "received_usd": 0.0,
    "tx_count": 2539,
    "first_seen": "2026-08-04T08:23:23",
    "last_seen": "2026-09-03T08:02:47",
    "entity": "binance",
    "wallet_type": "cex"
  }
]
```


# /wallets/{address}/ens (/docs/endpoints/data/onchain/wallets-address-ens)



```
GET https://data.vike.io/v1/onchain/wallets/{address}/ens
```

Reverse ENS lookup — turn an address into `vitalik.eth`. Returns null where the address has no ENS
name set. Already-resolved names are answered from our own store and only an unknown address falls
back to an external lookup, so the common case is fast and the slow case is the one that reaches
upstream.

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/onchain/wallets/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/ens"
```

<Params>
  <Param name="address" loc="path">
    Wallet address, 0x-prefixed, exactly 42 characters
  </Param>
</Params>

⚠ &#x2A;*No successful response could be captured for this route.** On 2026-09-03 this route's call — for
`vitalik.eth`, the example in this page's own description, and the address most likely to be in any
pre-resolved table — returned **HTTP 400**. A second address (a Binance hot wallet) returned the same
error. What came back was a single `detail` string carrying the upstream failure verbatim.

```json title="Example response"
{
  "detail": "local miss + external lookup failed: Moralis HTTP 401: {\"message\":\"Your Moralis Free usage is paused. Upgrade to a paid plan to resume usage. Your existing setup remains in place - no migration or reconfiguration required: https://admin.moralis.com/settin"
}
```

This is the documented fallback path failing at its second step, and the message says so precisely:
the local table **missed**, the external lookup was attempted, and the provider answered 401 because
its account is suspended. It is an upstream outage rather than a bad input, and it is the same
outage that also affected [`/balances`](/docs/endpoints/data/onchain/wallets-address-balances); both now resolve against our own node.

Three things to take from it:

* **This route fails loudly where its two siblings fail quietly.** A local miss plus an external
  failure is a **400**, not a 200 with `null`. So `null` genuinely means *no ENS name is set*, and an
  error genuinely means *we could not find out* — a cleaner contract than `/balances` offers, and
  worth relying on.
* **`vitalik.eth` missing from the local table** suggests the pre-resolved table is narrower than
  "the common case is local and fast" implies. Budget for the external path being taken.
* ⚠ **The upstream vendor's message is passed through verbatim to the caller**, including the
  provider's name and a link to its admin console, and is clipped mid-word at `/settin`. Do not
  parse `detail` — its content is an upstream string that will change without notice.


# /wallets/{address}/pnl (/docs/endpoints/data/onchain/wallets-address-pnl)



```
GET https://data.vike.io/v1/onchain/wallets/{address}/pnl
```

A daily net-flow series for the wallet — per-day net inflow USD, a cumulative figure, gross volume
and transaction count.

<Callout type="warn" title="This is net flow, not realized PnL">
  The `wallet_pnl_history&#x60; tool says so itself: &#x2A;"this is net inflow USD, not true realized PnL (which
  would require WAC accounting per token). Useful as a directional indicator."* A wallet that buys and
  holds shows a large negative net flow while being up on the position. Read the series as the
  direction and size of flow, not as profit.
</Callout>

The remaining 8 points run to `2026-09-01`, ending at `cumulative_net_flow_usd: 18.27` — which
matches the `total_net_flow_usd` at the top, so the header figure is the last cumulative value
rather than an independent sum.

⚠ &#x2A;*The series is sparse: one point per day *with activity*, not one point per day in the range.**
`days=30` returned 11 points, and the dates jump — `08-08`, `08-10`, `08-12`, then a six-day gap
between `08-14` and `08-20`. A chart or a diff that assumes 30 consecutive daily rows will misalign.
Zero-fill the calendar yourself if you need a dense series. Note also that a day can carry
`net_flow_usd: 0.0` with a non-zero `tx_count` (the captured `2026-08-14` has `tx_count: 2`), so
a present-but-zero point is not the same as an absent one.

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/onchain/wallets/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/pnl?days=30"
```

<Params>
  <Param name="address" loc="path">
    Wallet address
  </Param>

  <Param name="chain" loc="query">
    `ethereum`

     \| 

    `bsc`

     \| 

    `base`

    . Default 

    `ethereum`
  </Param>

  <Param name="days" loc="query">
    Days back. Default 30, clamped to the range 1–365
  </Param>
</Params>

A live response for `vitalik.eth`, captured 2026-09-03. First three of **11** series points.

```json title="Example response"
{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "chain": "ethereum",
  "days": 30,
  "total_net_flow_usd": 18.27,
  "series": [
    {
      "date": "2026-08-08",
      "net_flow_usd": 0.02,
      "gross_volume_usd": 0.02,
      "tx_count": 1,
      "unique_tokens": 1,
      "cumulative_net_flow_usd": 0.02
    },
    {
      "date": "2026-08-10",
      "net_flow_usd": 0.19,
      "gross_volume_usd": 0.19,
      "tx_count": 1,
      "unique_tokens": 1,
      "cumulative_net_flow_usd": 0.21
    },
    {
      "date": "2026-08-12",
      "net_flow_usd": 0.01,
      "gross_volume_usd": 0.01,
      "tx_count": 1,
      "unique_tokens": 1,
      "cumulative_net_flow_usd": 0.22
    }
  ]
}
```


# /wallets/{address}/trace (/docs/endpoints/data/onchain/wallets-address-trace)



```
GET https://data.vike.io/v1/onchain/wallets/{address}/trace
```

Follow the money outward. Starting at `address`, expand at each hop to the top `width` counterparties
by USD volume, up to `depth` hops. The response shape is
`{root, depth, width, nodes, edges, stats}`, where nodes carry
`{address, depth, label, wallet_type, total_volume_usd}` and edges carry
`{from, to, volume_usd, tx_count}`.

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/onchain/wallets/0x28C6c06298d514Db089934071355E5743bf21d60/trace?depth=2&width=3&window=30d"
```

<Params>
  <Param name="address" loc="path">
    Root wallet to trace from
  </Param>

  <Param name="chain" loc="query">
    `ethereum`

     \| 

    `bsc`

     \| 

    `base`

    . Default 

    `ethereum`
  </Param>

  <Param name="depth" loc="query">
    Hops to follow. Default 2, clamped to 1–5
  </Param>

  <Param name="width" loc="query">
    Top N counterparties per hop. Default 5, clamped to 1–10
  </Param>

  <Param name="window" loc="query">
    `24h`

     \| 

    `7d`

     \| 

    `30d`

     \| 

    `90d`

     \| 

    `all`

    . Default 

    `30d`
  </Param>

  <Param name="min_usd" loc="query">
    Minimum USD per transfer to follow. Default 

    **10,000**
  </Param>
</Params>

A live response for the Binance 14 hot wallet, captured 2026-09-03. The full response carries **7
nodes and 12 edges**; the capture carries the root plus its three depth-1 nodes, the first three
edges, and the closing `stats` block verbatim.

```json title="Example response"
{
  "root": "0x28C6c06298d514Db089934071355E5743bf21d60",
  "depth": 2,
  "width": 3,
  "window": "30d",
  "min_usd": 10000.0,
  "nodes": [
    {
      "address": "0x28c6c06298d514db089934071355e5743bf21d60",
      "depth": 0,
      "total_volume_usd": 127397751311.68404,
      "label": "binance",
      "wallet_type": "cex"
    },
    {
      "address": "0xeae7380dd4cef6fbd1144f49e4d1e6964258a4f4",
      "depth": 1,
      "total_volume_usd": 45175937046.3857,
      "label": "wintermute",
      "wallet_type": "market_maker"
    },
    {
      "address": "0x21a31ee1afc51d94c2efccaa2092ad1028285549",
      "depth": 1,
      "total_volume_usd": 42162018604.0239,
      "label": "binance",
      "wallet_type": "cex"
    },
    {
      "address": "0xdfd5293d8e347dfe59e90efd55b2956a1343963d",
      "depth": 1,
      "total_volume_usd": 40059795661.27443,
      "label": "binance",
      "wallet_type": "cex"
    }
  ],
  "edges": [
    {
      "from": "0x28c6c06298d514db089934071355e5743bf21d60",
      "to": "0xeae7380dd4cef6fbd1144f49e4d1e6964258a4f4",
      "volume_usd": 45175937046.39,
      "out_usd": 0.0,
      "in_usd": 45175937046.39,
      "tx_count": 6074
    },
    {
      "from": "0x28c6c06298d514db089934071355e5743bf21d60",
      "to": "0x21a31ee1afc51d94c2efccaa2092ad1028285549",
      "volume_usd": 42162018604.02,
      "out_usd": 42162018604.02,
      "in_usd": 0.0,
      "tx_count": 2268
    },
    {
      "from": "0x28c6c06298d514db089934071355e5743bf21d60",
      "to": "0xdfd5293d8e347dfe59e90efd55b2956a1343963d",
      "volume_usd": 40059795661.27,
      "out_usd": 40059795661.27,
      "in_usd": 0.0,
      "tx_count": 2263
    }
  ],
  "stats": {
    "node_count": 7,
    "edge_count": 12,
    "max_depth_reached": 2
  }
}
```

Three things that `{root, depth, width, nodes, edges, stats}` summary does not tell you, all
visible above:

* **The echoed request is part of the response.** `depth`, `width`, `window` and the resolved
  `min_usd` come back at the top level, so a response records the floor it was taken under — useful
  given that omitting `min_usd` silently selects 10,000 rather than 0.
* **Edges carry a direction breakdown** that summary omits: `out_usd` and `in_usd` alongside
  `volume_usd`. The first captured edge is `in_usd` only — money flowing *toward* the root — so
  "trace" is not outbound-only despite the name.
* **`depth=2, width=3` yielded 7 nodes, not the 1 + 3 + 9 = 13 the arithmetic suggests.** Expansion
  is deduplicated and bounded by what actually clears `min_usd`; read `stats.node_count` rather than
  predicting it. `max_depth_reached` tells you whether the graph ran out before `depth` did.

⚠ &#x2A;*Unrecognised values fall back silently rather than erroring.** A misspelled `chain` reads
Ethereum and a misspelled `window` reads 30 days — both with a **200** and no warning, so a typo
returns plausible data for the wrong question. Spell these from the enums above.

Cost is the product of `depth` and `width`, so this is the heaviest route in the namespace; the MCP
tool prices it at 4 credits against a namespace median of 2.


# /wallets/{address}/transactions (/docs/endpoints/data/onchain/wallets-address-transactions)



```
GET https://data.vike.io/v1/onchain/wallets/{address}/transactions
```

The raw transfer list for a wallet: individual transfers, not aggregates. The `wallet_transactions`
tool description names the fields it returns — time, tx\_hash, from, to, token\_address, value\_usd,
direction, block. This is the forensic route;
[`/counterparties`](/docs/endpoints/data/onchain/wallets-address-counterparties) is the summarised view of
the same underlying transfers.

⚠ &#x2A;*Three field names differ from the tool description quoted above.*&#x2A; The wire keys measured on
this route are &#x2A;*`usd`** (not `value_usd&#x60;), &#x2A;*`from_address`*&#x2A; and &#x2A;*`to_address`** (not `from` /
`to`). Bind your parser to the wire names, not to the tool's prose — `from` could not be the wire
name in any case without colliding with a reserved word in several client languages.

⚠ **`usd` is `0.0` on all three captured rows**, including a USDT transfer from an exchange hot
wallet, so a zero here means *not priced* rather than *worthless*. The consequence is on
`min_usd`: if that floor filters on this same field, any `min_usd` above zero would have dropped
all three of these rows. Verify against your own data before relying on `min_usd` to mean "large
transfers only" — on this evidence it may equally mean "rows that got a price at all".

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/onchain/wallets/0x28C6c06298d514Db089934071355E5743bf21d60/transactions?limit=3&days=30"
```

<Params>
  <Param name="address" loc="path">
    Wallet address
  </Param>

  <Param name="chain" loc="query">
    `ethereum`

     \| 

    `bsc`

     \| 

    `base`

    . Default 

    `ethereum`
  </Param>

  <Param name="direction" loc="query">
    `in`

     \| 

    `out`

    . Omit for both directions
  </Param>

  <Param name="days" loc="query">
    Days back. Default 30, clamped to 365
  </Param>

  <Param name="min_usd" loc="query">
    Drop transfers below this USD value. Default 0
  </Param>

  <Param name="token_address" loc="query">
    Restrict to a single token contract
  </Param>

  <Param name="limit" loc="query">
    Route default 100; 

    **applied cap 500**
  </Param>
</Params>

A live response for the Binance 14 hot wallet, captured 2026-09-03 — a bare array, three rows for
`limit=3`.

```json title="Example response"
[
  {
    "time": "2026-09-03T08:09:47",
    "tx_hash": "0x4a8eee513cd07ca136e89877e14f1cebb4dd87d2e034c1f27158d461fdafbd24",
    "usd": 0.0,
    "block": 25895491,
    "from_address": "0x28c6c06298d514db089934071355e5743bf21d60",
    "to_address": "0xf857b69686cca09049d7732e9d21a5fe7752f919",
    "token_address": "0x0000000000000000000000000000000000000000",
    "direction": "out"
  },
  {
    "time": "2026-09-03T08:09:47",
    "tx_hash": "0x56e3b5cd7cb4ab29ac062eaa8f027951619ee4f47c3875c56da3f1689f486ae1",
    "usd": 0.0,
    "block": 25895491,
    "from_address": "0x28c6c06298d514db089934071355e5743bf21d60",
    "to_address": "0xc5fe50deb784983b0967b22fafbf239841518829",
    "token_address": "0x888888848b652b3e3a0f34c96e00eec0f3a23f72",
    "direction": "out"
  },
  {
    "time": "2026-09-03T08:09:47",
    "tx_hash": "0xc3df2299b2f1cd0b15eb7d6f3ea6b064e1f504c5a2cf1d52e03d62e9eb3764f4",
    "usd": 0.0,
    "block": 25895491,
    "from_address": "0x28c6c06298d514db089934071355e5743bf21d60",
    "to_address": "0x120ecaf0cb973718cd6dee36ba0b8c42fbde7ca1",
    "token_address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
    "direction": "out"
  }
]
```


# /wallets/{address} (/docs/endpoints/data/onchain/wallets-address)



```
GET https://data.vike.io/v1/onchain/wallets/{address}
```

Aggregate metrics for one wallet — volume, inflow, outflow, net flow, transaction count and tokens
traded, across the 24h / 7d / 30d / 90d / all windows in a single response. The cheapest way to size
up an address before spending calls on its detail routes.

A live response for `vitalik.eth`, captured 2026-09-03. All five windows come back in one object;
`24h` is present and zeroed rather than omitted, and `first_seen` / `last_active` / `tokens_traded`
repeat the all-time figure inside every window rather than being recomputed per window — read those
three from `all` and ignore the copies:

That is the whole response, not an excerpt. Note the shape of a long-lived but currently quiet
address: 932,913 lifetime transactions against 18 in the last 30 days. Sizing a wallet up on `all`
alone will mislead you about whether it is active *now* — which is what the window breakdown is for.

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/onchain/wallets/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
```

<Params>
  <Param name="address" loc="path">
    Wallet address, 0x-prefixed hex
  </Param>
</Params>

```json title="Example response"
{
  "all": {
    "total_volume": 172096152.066662,
    "total_inflow": 59024302.03353,
    "total_outflow": 113071850.033132,
    "net_flow": -54047547.999602,
    "tx_count": 932913,
    "tokens_traded": 12365,
    "first_seen": "2016-08-05",
    "last_active": "2026-09-01"
  },
  "90d": {
    "total_volume": 273.294302,
    "total_inflow": 87.693162,
    "total_outflow": 185.60114,
    "net_flow": -97.907978,
    "tx_count": 91,
    "tokens_traded": 12365,
    "first_seen": "2016-08-05",
    "last_active": "2026-09-01"
  },
  "30d": {
    "total_volume": 18.272136,
    "total_inflow": 18.272136,
    "total_outflow": 0.0,
    "net_flow": 18.272136,
    "tx_count": 18,
    "tokens_traded": 12365,
    "first_seen": "2016-08-05",
    "last_active": "2026-09-01"
  },
  "7d": {
    "total_volume": 0.1,
    "total_inflow": 0.1,
    "total_outflow": 0.0,
    "net_flow": 0.1,
    "tx_count": 1,
    "tokens_traded": 12365,
    "first_seen": "2016-08-05",
    "last_active": "2026-09-01"
  },
  "24h": {
    "total_volume": 0.0,
    "total_inflow": 0.0,
    "total_outflow": 0.0,
    "net_flow": 0.0,
    "tx_count": 0,
    "tokens_traded": 12365,
    "first_seen": "2016-08-05",
    "last_active": "2026-09-01"
  }
}
```

No query parameters — the windows are all returned together rather than selected.


# /wallets/compare (/docs/endpoints/data/onchain/wallets-compare)



```
GET https://data.vike.io/v1/onchain/wallets/compare
```

Are these two wallets related? Returns the counterparties both wallets transacted with and the tokens
both touched, within a window. Declared before `/wallets/{address}` so that `compare` is not read as
an address.

⚠ &#x2A;*`summary` counts what was returned, not what exists.** Both counts read `3` against a `limit=3`
call — they are the length of the returned arrays, already truncated by `limit`. A `shared_token_count`
of 3 therefore does not mean these two wallets share exactly three tokens; it means you asked for
three. Raise `limit` (applied cap 50) until the count stops rising if you need the true overlap.

⚠ &#x2A;*Choose both addresses for activity, or the answer is empty and says nothing.** Run against a
quiet address and `shared_counterparties` comes back `[]` — a truthful result that reads identically
to "unrelated". The captured pair are both high-traffic wallets, which is why the overlap is
populated. `a_volume_usd` of `101.77817` against `b_volume_usd` of `782907715.73` on the third row is
the useful shape here: a shared counterparty can be central to one wallet and incidental to the
other, so weigh the two columns rather than treating any shared row as evidence of a link.

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/onchain/wallets/compare?address_a=0x28C6c06298d514Db089934071355E5743bf21d60&address_b=0xeae7380dd4cef6fbd1144f49e4d1e6964258a4f4&limit=3&window=30d"
```

<Params>
  <Param name="address_a" loc="query">
    First wallet
  </Param>

  <Param name="address_b" loc="query">
    Second wallet
  </Param>

  <Param name="chain" loc="query">
    `ethereum`

     \| 

    `bsc`

     \| 

    `base`

    . Default 

    `ethereum`
  </Param>

  <Param name="window" loc="query">
    `24h`

     \| 

    `7d`

     \| 

    `30d`

     \| 

    `90d`

     \| 

    `180d`

     \| 

    `all`

    . Default 

    `30d`
  </Param>

  <Param name="limit" loc="query">
    Max shared items per category. Route default 100; 

    **applied cap 50**
  </Param>
</Params>

Binance 14 against a Wintermute market-making wallet, captured 2026-09-03. The full response is
shown except that `shared_tokens` is trimmed from three entries to one.

```json title="Example response"
{
  "address_a": "0x28C6c06298d514Db089934071355E5743bf21d60",
  "address_b": "0xeae7380dd4cef6fbd1144f49e4d1e6964258a4f4",
  "window": "30d",
  "chain": "ethereum",
  "shared_counterparties": [
    {
      "wallet": "0x51c72848c68a965f66fa7a88855f9f7784502a7f",
      "a_volume_usd": 3124737069.567188,
      "b_volume_usd": 27413487685.73743,
      "a_tx_count": 361,
      "b_tx_count": 1434,
      "entity": "wintermute",
      "wallet_type": "market_maker"
    },
    {
      "wallet": "0xf8191d98ae98d2f7abdfb63a9b0b812b93c873aa",
      "a_volume_usd": 8952220569.76122,
      "b_volume_usd": 6464235700.270625,
      "a_tx_count": 518,
      "b_tx_count": 1472,
      "entity": "wintermute",
      "wallet_type": "market_maker"
    },
    {
      "wallet": "0xa9d1e08c7793af67e9d92fe308d5697fb81d3e43",
      "a_volume_usd": 101.77817,
      "b_volume_usd": 782907715.73214,
      "a_tx_count": 3,
      "b_tx_count": 752,
      "entity": "coinbase",
      "wallet_type": "cex"
    }
  ],
  "shared_tokens": [
    {
      "token_address": "0x5a98fcbea516cf06857215779fd812ca3bef1b32",
      "a_volume_usd": 261683883072.97073,
      "b_volume_usd": 80125236671.59358,
      "a_tx_count": 2266,
      "b_tx_count": 378
    }
  ],
  "summary": {
    "shared_counterparty_count": 3,
    "shared_token_count": 3
  }
}
```

Both addresses are required, and both are query parameters rather than path segments. Omitting either
is a **422** carrying a validation list
(`{"detail":[{"type":"missing","loc":["query","address_b"],…}]}`, measured live). Sending both but
leaving one *blank* is a different failure: a **400** reading `address_a and address_b are required`.


# /wallets/discover (/docs/endpoints/data/onchain/wallets-discover)



```
GET https://data.vike.io/v1/onchain/wallets/discover
```

The leaderboard: most active wallets over a window, ranked by the metric you pick. Use it to find
addresses worth investigating, then move to the
[per-wallet routes](/docs/endpoints/data/onchain#wallets).

`total` is the size of the matching population — 8,330,571 wallets — not the number of rows
returned. With `size` capped at 20 this route is a *top-of-leaderboard* view; there is no way to page
deep into that population from here.

⚠ &#x2A;*`realized_pnl` is not on the same scale as the USD columns beside it.** Row 1 reports `volume`
of 2.55e12 alongside
`realized_pnl` of 1.13e16 — a realized profit four thousand times the wallet's own gross volume,
which cannot be a USD reading. Divide by 1e6 and it lands near 1.1e10 — still large, but now below
the wallet's own volume rather than four thousand times above it, which is at least a shape a
profit figure could take. Treat `realized_pnl` as a **ranking key rather than a dollar figure**
unless you have confirmed its scale, and note `pnl_available: 1` only asserts that a value was
computed, not that it is denominated as you expect.

⚠ &#x2A;*`first_seen` here is not a lifetime first-seen either.** All three rows report June 2026 against
a `window=30d` call — earlier than the window, so it is not simply clamped to it as on
[`/counterparties`](/docs/endpoints/data/onchain/wallets-address-counterparties), but it is also far too
recent for wallets of this size to be genuinely new. Read it as "first seen in the dataset behind
this route". [`/wallets/{address}`](/docs/endpoints/data/onchain/wallets-address) reported `2016-08-05`
for a wallet on the same day, so the two routes do not agree on what the field means.

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/onchain/wallets/discover?size=3&window=30d"
```

<Params>
  <Param name="window" loc="query">
    `24h`

     \| 

    `7d`

     \| 

    `30d`

     \| 

    `90d`

     \| 

    `all`

    . Default 

    `30d`
  </Param>

  <Param name="sort" loc="query">
    `volume`

     \| 

    `inflow`

     \| 

    `outflow`

     \| 

    `net_flow`

     \| 

    `tx_count`

     \| 

    `pnl`

    . Default 

    `volume`
  </Param>

  <Param name="order" loc="query">
    `asc`

     \| 

    `desc`

    . Default 

    `desc`
  </Param>

  <Param name="chain" loc="query">
    `ethereum`

     \| 

    `bsc`

    . Default 

    `ethereum`
  </Param>

  <Param name="size" loc="query">
    Results per page. Default 10, max 20 — one of the two routes in this namespace whose accepted and applied caps agree, alongside 

    [`/tokens/search`](/docs/endpoints/data/onchain/tokens-search)
  </Param>
</Params>

The full response for `size=3`, captured 2026-09-03 — all three wallets plus the `total`.

```json title="Example response"
{
  "wallets": [
    {
      "address": "0xbbbbbbbbbb9cc5e90e3b3af64bdaf62c37eeffcb",
      "volume": 2552546474138.343,
      "inflow": 1276307059282.2302,
      "outflow": 1276239414856.1125,
      "net_flow": 67644426.117664,
      "tx_count": 367347,
      "tokens_traded": 33,
      "first_seen": "2026-06-04",
      "last_active": "2026-09-02",
      "realized_pnl": 11268691976748202,
      "tokens_profitable": 18,
      "pnl_available": 1
    },
    {
      "address": "0x06cff7088619c7178f5e14f0b119458d08d2f5ef",
      "volume": 695617826252.817,
      "inflow": 347809463499.2067,
      "outflow": 347808362753.6103,
      "net_flow": 1100745.596406,
      "tx_count": 174226,
      "tokens_traded": 245,
      "first_seen": "2026-06-04",
      "last_active": "2026-09-02",
      "realized_pnl": 2399649170518083.5,
      "tokens_profitable": 76,
      "pnl_available": 1
    },
    {
      "address": "0xd226997439ecfbeff8e110c8c78c8a7eefd19f89",
      "volume": 424200696674.0756,
      "inflow": 212100372292.9297,
      "outflow": 212100324381.146,
      "net_flow": 47911.7837,
      "tx_count": 70510,
      "tokens_traded": 155,
      "first_seen": "2026-06-05",
      "last_active": "2026-09-03",
      "realized_pnl": 3120711434553757.0,
      "tokens_profitable": 33,
      "pnl_available": 1
    }
  ],
  "total": 8330571
}
```

Note the parameter is `size`, not `limit`, and the chain enum is narrower here than elsewhere in the
namespace: `ethereum` and `bsc` only, no `base`.

Each row carries `address`, `volume`, `inflow`, `outflow`, `net_flow`, `tx_count`, `tokens_traded`,
`first_seen`, `last_active`, `realized_pnl`, `tokens_profitable` and `pnl_available`, alongside a
`total`. ⚠ Every USD-denominated column reaches you as **plain USD**, already scaled — do not
rescale them.


# /archive/datasets (/docs/endpoints/data/polymarket/archive-datasets)



```
GET /v1/polymarket/archive/datasets
```

A JSON index of every downloadable archive partition, across **both** Hive layouts: the flat
`venue=polymarket/date=.../` layout (every recorded market that day — the only discoverable path
for anything outside a crypto up/down family, such as sports or politics) and the family-partitioned
`venue=polymarket/asset=<asset>/tenor=<tenor>/date=.../` layout (one crypto up/down family's own
much smaller file). Rows arrive newest date first.

The unfiltered call — no parameters at all, which is the one worth seeing first because it shows
what the defaults do:

**Truncated for the page: `datasets` held 200 rows; the first two are shown.** The envelope is
complete and is the part that matters — sending no `limit` returned `"limit": 200`, the default
echoed back, and `"total": 2100` against 200 rows delivered. **That first page is under a tenth of
the archive**, which is the paging point made with real numbers: page until
`offset + len(datasets) >= total`.

Rows arrive newest date first, and the two shown are the same date's two streams. Note the first
one's size — &#x2A;*4,799,571,940 bytes and 306,994,531 rows for a single day of `book_events`.** This
is why `bytes` and `rows` are in the index at all: a day of book events is a 4.8 GB download, and
[the archive's download guidance](/docs/data/archive/downloading) matters before you fetch one.

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/polymarket/archive/datasets"
```

<Params>
  <Param name="asset" loc="query">
    Matches 

    **family-layout rows only**

    , e.g. 

    `btc`

    . Supplying it excludes every flat row.
  </Param>

  <Param name="tenor" loc="query">
    Matches 

    **family-layout rows only**

    , e.g. 

    `5m`

    .
  </Param>

  <Param name="stream" loc="query">
    One of 

    `book_events`

    , 

    `trades`

    , 

    `l1_quotes`

    .
  </Param>

  <Param name="from" loc="query">
    `YYYY-MM-DD`

    , inclusive lower date bound.
  </Param>

  <Param name="to" loc="query">
    `YYYY-MM-DD`

    , inclusive upper date bound.
  </Param>

  <Param name="limit" loc="query">
    Max rows. Default 

    `200`

    , hard cap 

    `1000`

    .
  </Param>

  <Param name="offset" loc="query">
    Skip this many matching rows. Default 

    `0`

    .
  </Param>
</Params>

```json title="Example response"
{
  "datasets": [
    {
      "bytes": 4799571940,
      "date": "2026-09-02",
      "layout": "flat",
      "rows": 306994531,
      "stream": "book_events",
      "url": "https://data.vike.io/archive/venue=polymarket/date=2026-09-02/book_events.parquet",
      "venue": "polymarket"
    },
    {
      "bytes": 12314277,
      "date": "2026-09-02",
      "layout": "flat",
      "rows": 1006555,
      "stream": "trades",
      "url": "https://data.vike.io/archive/venue=polymarket/date=2026-09-02/trades.parquet",
      "venue": "polymarket"
    }
  ],
  "limit": 200,
  "offset": 0,
  "total": 2100
}
```

Response — an object carrying the matching rows under `datasets`, each row with the absolute
download URL alongside the known size and row count, so you can budget a download before starting
it. This is `?limit=1&stream=trades`, fetched from the running service:

```json title="Example response — limit=1, stream=trades"
{
  "datasets": [
    {
      "bytes": 12314277,
      "date": "2026-09-02",
      "layout": "flat",
      "rows": 1006555,
      "stream": "trades",
      "url": "https://data.vike.io/archive/venue=polymarket/date=2026-09-02/trades.parquet",
      "venue": "polymarket"
    }
  ],
  "limit": 1,
  "offset": 0,
  "total": 700
}
```

`limit` and `offset` echo back the values actually in force — `limit` reports the default `200&#x60;
when you send none. **`total` is the count of rows matching your filters before `limit` and
`offset` are applied**, and it is the only field that tells you when to stop: page until
`offset + len(datasets) >= total`. It follows the filters rather than the page — measured in the
same minute, an unfiltered call reported `2100`, `?stream=trades` `700`, and `?asset=btc` `270`.

<Callout type="warn" title="Three parameters that look right and are silently ignored">
  Measured against the live service: &#x2A;*`date=`, `layout=` and `venue=` are not parameters here.** A
  request carrying them returns the *unfiltered* result with status `200` and no warning —
  `?date=2026-09-01` came back with all 40 recorded dates, and `?venue=bogus` came back with a full
  page of Polymarket rows.

  Use &#x2A;*`from` and `to`*&#x2A; for dates, and note they take &#x2A;*`YYYY-MM-DD`**, not the epoch milliseconds
  that `from`/`to` mean on [`/ohlcv`](/docs/endpoints/data/polymarket/ohlcv). Layout is not selected
  directly: it follows from `asset`/`tenor`, which restrict the result to family rows.

  Because the default page is 200 rows out of considerably more, an unfiltered first page is not the
  whole archive. Page with `limit` and `offset`, or filter first.
</Callout>


# /archive/url (/docs/endpoints/data/polymarket/archive-url)



```
GET /v1/polymarket/archive/url?date={YYYY-MM-DD}&stream={stream}
```

Resolves **one** partition to its absolute download URL plus that file's known byte and row
counts. Use it when you already know the partition you want and do not need to enumerate; use
[`/archive/datasets`](/docs/endpoints/data/polymarket/archive-datasets) when you are discovering.

The **flat** layout — a date and a stream, no `asset`/`tenor`:

`layout` echoes back which of the two shapes you resolved, and `bytes`/`rows` are that file's real
size — 12.3 MB and 1,006,555 rows here — so you can budget the download before starting it. Note
that `asset` and `tenor` are simply absent from a flat response rather than present and null.

The **family** layout answers with the same fields plus those two.

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/polymarket/archive/url?date=2026-09-02&stream=trades"
```

<Params>
  <Param name="date" loc="query">
    `YYYY-MM-DD`

    . Omitting it returns 

    `400 {"error":"get_archive_url requires date"}`

    .
  </Param>

  <Param name="stream" loc="query">
    One of 

    `book_events`

    , 

    `trades`

    , 

    `l1_quotes`

    .
  </Param>

  <Param name="asset" loc="query">
    Supply 

    **both**

     

    `asset`

     and 

    `tenor`

     to resolve the family layout, or 

    **neither**

     to resolve the flat layout.
  </Param>

  <Param name="tenor" loc="query">
    As above.
  </Param>

  <Param name="redirect" loc="query">
    `true`

     returns 

    `302`

     with the file in 

    `Location`

     instead of the JSON body.
  </Param>
</Params>

```json title="Example response — date layout"
{
  "bytes": 12314277,
  "date": "2026-09-02",
  "layout": "flat",
  "rows": 1006555,
  "stream": "trades",
  "url": "https://data.vike.io/archive/venue=polymarket/date=2026-09-02/trades.parquet",
  "venue": "polymarket"
}
```

```json title="Example response — asset/tenor layout"
{
  "asset": "btc",
  "bytes": 5448402,
  "date": "2026-09-01",
  "layout": "family",
  "rows": 490669,
  "stream": "trades",
  "tenor": "5m",
  "url": "https://data.vike.io/archive/venue=polymarket/asset=btc/tenor=5m/date=2026-09-01/trades.parquet",
  "venue": "polymarket"
}
```

<Callout type="warn">
  **`asset` and `tenor` are all-or-nothing.** Supplying only one is refused rather than guessed:
  `400 {"error":"get_archive_url requires BOTH asset and tenor (family layout) or NEITHER (flat layout) — supplying only one is ambiguous"}`.

  **A partition that does not exist is a `400`, not a `404`** — `{"error":"no flat dataset found for date=1999-01-01 stream=trades"}`.
  This is a real answer, not necessarily a mistake: a family with zero rows in a stream on a given
  day has **no file** that day, which the archive documents as expected behaviour.
</Callout>


# /events (/docs/endpoints/data/polymarket/events)



```
GET /v1/polymarket/events?token_id={token_id}&from_ms={from}&to_ms={to}
```

The raw per-market event tape: book snapshots and deltas, trade prints, tick-size changes and
stream-health status markers, ordered by `(local_ts, seq, token_id)`. This is the finest grain
the API offers, for one token or a family of up to 100 over a bounded window.

**Truncated for the page: `limit=3` returned three events; the first two are shown, and
`next_cursor` above is the real one from that three-event page** (it names the third event's
`local_ts:seq:token_id`). `has_more` is `true` — with a `limit` this small it is true almost
immediately, which is the point: it reflects the *page*, not the window.

The window was chosen from [`/market_stats`](/docs/endpoints/data/polymarket/market-stats), which is
the intended order of operations: `to_ms` here is that token's `last_ms` exactly, and `from_ms` is
roughly an hour earlier. Asking for a window at the current wall clock would have returned an
empty page for this token.

⚠ &#x2A;*`bids` and `asks` are JSON-encoded *strings*, not arrays.** `"bids": "[[0.782,0.0]]"` must be
parsed a second time to become `[[0.782, 0.0]]`, and an event that carries no book side sends the
empty string `""` rather than `null` or `[]`.

⚠ &#x2A;*Unpopulated numeric fields are `0`, not `null`.** These `price_change` rows carry
`"best_ask": 0` and `"best_bid": 0` — that is "this event type does not populate the field", not
"the best bid is zero". `status` is `""` for the same reason. Read fields according to
`event_type`; do not treat a zero here as a price.

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/polymarket/events?token_id=95532524407959903145510583684979049735028502452973932716346555811355282494630&from_ms=1787180000000&to_ms=1787183633324&limit=3"
```

<Params>
  <Param name="token_id" loc="query">
    A single token — sugar for a one-element 

    `token_ids`

    .
  </Param>

  <Param name="token_ids" loc="query">
    Comma-separated token ids, 

    **max 100 per request**

    . Wins over 

    `token_id`

     if both are given.
  </Param>

  <Param name="from_ms" loc="query">
    Window start, epoch ms, 

    **inclusive**

    .
  </Param>

  <Param name="to_ms" loc="query">
    Window end, epoch ms, 

    **exclusive**

    . Must be greater than 

    `from_ms`

    .
  </Param>

  <Param name="event_type" loc="query">
    Filter to one of 

    `book`

    , 

    `price_change`

    , 

    `trade`

    , 

    `tick_size_change`

    , 

    `status`

    .
  </Param>

  <Param name="limit" loc="query">
    Max rows per page. Default 

    `5000`

    , hard cap 

    `50000`

    .
  </Param>

  <Param name="cursor" loc="query">
    Resume strictly after this 

    `local_ts:seq:token_id`

     triple, taken from a previous page's 

    `next_cursor`

    .
  </Param>
</Params>

```json title="Example response"
{
  "events": [
    {
      "asks": "",
      "best_ask": 0,
      "best_bid": 0,
      "bids": "[[0.782,0.0]]",
      "event_type": "price_change",
      "is_snapshot": 0,
      "local_ts": 1787180056379,
      "price": 0.782,
      "seq": 8404,
      "side": "buy",
      "size": 0,
      "status": "",
      "token_id": "95532524407959903145510583684979049735028502452973932716346555811355282494630",
      "ts": 1787180056368
    },
    {
      "asks": "",
      "best_ask": 0,
      "best_bid": 0,
      "bids": "[[0.782,6.25]]",
      "event_type": "price_change",
      "is_snapshot": 0,
      "local_ts": 1787180056894,
      "price": 0.782,
      "seq": 8405,
      "side": "buy",
      "size": 6.25,
      "status": "",
      "token_id": "95532524407959903145510583684979049735028502452973932716346555811355282494630",
      "ts": 1787180056883
    }
  ],
  "has_more": true,
  "next_cursor": "1787180122865:8406:95532524407959903145510583684979049735028502452973932716346555811355282494630"
}
```

<Callout type="warn" title="Two things unique to this endpoint">
  **The window is capped at 24 hours.** A wider request is refused outright:
  `{"error":"get_events window too wide: 800000000000ms requested, max 86400000ms (24h)"}`. Page
  across days by moving the window, not by widening it. A request for more than 100 tokens is
  refused the same way, naming the count.

  **It is the only endpoint here that returns a paging envelope.** Every other endpoint in this
  namespace returns a bare array; this one returns an object — `{"events": [...], "next_cursor": "...", "has_more": true}`.
  Follow `has_more` and feed `next_cursor` back as `cursor`; do not assume a short page means the
  end of the window.
</Callout>

If you want a whole day, or many days, of this tape, do not page it here — the same events are
published as Parquet in the [bulk archive](/docs/data/archive), which is a single download instead of
tens of thousands of pages.


# Polymarket (/docs/endpoints/data/polymarket)



Eleven endpoints under `https://data.vike.io/v1/polymarket/`. Nine are over the Polymarket CLOB as
**recorded by Vike** — not a proxy of Polymarket's own API; two are trader routes over the on-chain
trade tape. They answer on the same host, behind the same API
key and the same hourly budget as every other namespace.

<Callout title="Querying is one of two ways in — the other is bulk">
  These eleven answer a question at a time, in JSON. The &#x2A;*[Polymarket archive](/docs/endpoints/data/archive)**
  serves the same recording as Parquet files, a day at a time — 411 GB of book events, trades and
  L1 quotes, read with pyarrow or DuckDB rather than curl.

  ⚠ Reach for the archive whenever the answer is "every row in a window". A ranged file read does
  **not** spend the hourly request budget, while paging the same history through these endpoints
  does — and a Parquet reader issuing one Range request per column chunk is how a single 1.26 GB
  file once cost 20,237 units.
</Callout>

<Callout title="In the OpenAPI spec, but without response schemas">
  `/v1/openapi.json` lists every endpoint here, but like the rest of `/v1` it declares no response
  bodies — which is why these pages exist and why every request line, field and status code on them
  was read off the live API rather than generated.
</Callout>

Every endpoint here is `GET`. Any other method returns `405 {"error":"only GET is supported here"}`,
and an unrouted path returns `404 {"error":"no such route"}`.

## One spelling [#one-spelling]

`/v1/polymarket/...` is the only form. Seven older flat paths — `/v1/markets`,
`/v1/markets/{condition_id}`, `/v1/market_stats`, `/v1/ohlcv`, `/v1/orderbook`,
`/v1/settlements/{condition_id}` and `/v1/events` — answered until **2026-09-03** and now return
`404`. They predated the namespace and were retired once the usage record showed no caller had
ever used them.

⚠ If you have code on a flat path, add `/polymarket` after `/v1`; nothing else changes. The
namespaced form matches `onchain` and `hyperliquid`, and cannot collide with a future route in
those namespaces.

<Callout type="warn" title="Two traps in the flat spelling">
  **The archive endpoints have no flat alias.** `/v1/archive/datasets` and `/v1/archive/url` are
  **404** — those two are reachable **only** through `/v1/polymarket/archive/...`.

  **Bare `/v1/settlements` is routed but dead.** An authenticated caller pays the round trip and
  receives `404 {"error":"no such route"}`. The working form carries a condition id:
  `/v1/settlements/{condition_id}`. Do not call the bare path.
</Callout>

## Identifiers: `condition_id` and `token_id` [#identifiers-condition_id-and-token_id]

Two different ids appear here and they are not interchangeable.

* **`condition_id`** — a `0x`-prefixed hex string identifying a *market*. It is what the two
  path-parameter endpoints take.
* **`token_id`** — a long decimal string identifying one *outcome token*. A binary market has two,
  returned in `token_ids`. It is what every query-parameter endpoint takes.

Get both from [`/markets`](/docs/endpoints/data/polymarket/markets). The
[older reference page](/docs/data/reference/polymarket) carries an annotated example row.

One call gets you both, and it is the right first call in this namespace:

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/polymarket/markets?query=bitcoin&limit=3"
```

Each row carries the market's `condition_id` and its two `token_ids`; every other endpoint here
takes one or the other. [`/markets`](/docs/endpoints/data/polymarket/markets) shows the response.

<Callout type="warn" title="A wrong or unknown id is not an error">
  `/markets/{condition_id}` and `/settlements/{condition_id}&#x60; answer &#x2A;*`200` with an empty array
  `[]`** for an id they do not know — including a well-formed `token_id` passed where a
  `condition_id` belongs, which is a silent empty result rather than a rejection. Both were measured
  against the live service. Check for an empty array; do not rely on a 404.
</Callout>

## The eleven endpoints [#the-eleven-endpoints]

| Endpoint                                                                             | What it does                                                                                                                                |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| [`/markets`](/docs/endpoints/data/polymarket/markets)                                     | The market directory — search and filter the recorded market universe by slug.                                                              |
| [`/markets/{condition_id}`](/docs/endpoints/data/polymarket/markets-condition-id)         | One market's detail — the same row shape as the directory, for a single market.                                                             |
| [`/market_stats`](/docs/endpoints/data/polymarket/market-stats)                           | Aggregate recorded activity for one outcome token in a single row.                                                                          |
| [`/ohlcv`](/docs/endpoints/data/polymarket/ohlcv)                                         | Candles for one outcome token, priced in probability, 0–1.                                                                                  |
| [`/orderbook`](/docs/endpoints/data/polymarket/orderbook)                                 | An order-book **snapshot** for one outcome token.                                                                                           |
| [`/events`](/docs/endpoints/data/polymarket/events)                                       | The raw per-market event tape: book snapshots and deltas, trade prints, tick-size changes and stream-health status markers.                 |
| [`/settlements/{condition_id}`](/docs/endpoints/data/polymarket/settlements-condition-id) | The **on-chain settlement** of one market: which outcome won, what the payout vector was, and the block and timestamp at which it resolved. |
| [`/wallets/{address}`](/docs/endpoints/data/polymarket/wallets-address)                   | One trader's profile — lifetime volume, realized P\&L and hit rate over a chosen window, markets, trades, positions and an equity curve.    |
| [`/smart_money`](/docs/endpoints/data/polymarket/smart-money)                             | Smart-money signals: markets the profitable cohort is buying (`flows`) or bought below the mid (`mispricings`).                             |
| [`/archive/datasets`](/docs/endpoints/data/polymarket/archive-datasets)                   | A JSON index of every downloadable archive partition, across **both** Hive layouts.                                                         |
| [`/archive/url`](/docs/endpoints/data/polymarket/archive-url)                             | Resolves **one** partition to its absolute download URL plus that file's known byte and row counts.                                         |

## Bulk archive discovery [#bulk-archive-discovery]

Two endpoints that index the Parquet archive rather than serving market data. They tell you what
partitions exist and where to download them; the files themselves are served from
`https://data.vike.io/archive/`, and [the archive pages](/docs/data/archive) cover the layouts, the
schemas and — importantly — [how to download without exhausting your budget](/docs/data/archive/downloading).

Both are namespaced-spelling only. There is no `/v1/archive/...` flat alias.

## Metering [#metering]

Every call in this namespace spends one unit of the same hourly budget as MCP and the other `/v1`
namespaces — see [Rate limits](/docs/data/rate-limits). Archive *downloads* from
`https://data.vike.io/archive/` do not spend it, but the two discovery endpoints above are
ordinary API calls and do.

The mistake this namespace invites is worth repeating from that page: if you want book history
rather than a snapshot, download whole archive partitions and read them locally. Pointing a
Parquet client at an archive URL issues a request per column chunk, and one file can produce tens
of thousands of them.

## REST and MCP: which routes share code [#rest-and-mcp-which-routes-share-code]

Both surfaces are served from the same code where it matters, and they are **not** one-to-one:

| REST endpoint                                                                         | MCP tool (`https://vike.io/mcp`) | Same implementation?                                                                               |
| ------------------------------------------------------------------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------- |
| `/ohlcv`                                                                              | `polymarket_ohlcv`               | Yes — the same query.                                                                              |
| `/wallets/{address}`                                                                  | `polymarket_wallet`              | Yes — the route runs the tool.                                                                     |
| `/smart_money`                                                                        | `polymarket_smart_money`         | Yes — the route runs the tool.                                                                     |
| `/markets`                                                                            | `polymarket_markets`             | **No.** REST searches the recorded universe by slug; the tool ranks the top markets by 24h volume. |
| `/markets/{condition_id}`                                                             | `polymarket_market_detail`       | **No.** Different row shapes.                                                                      |
| `/market_stats`, `/orderbook`, `/events`, `/settlements/{condition_id}`, `/archive/*` | —                                | REST only.                                                                                         |

The second Polymarket MCP server that once answered at `data.vike.io/mcp` (nine tools, one per
route) was retired on 2026-09-03 with zero authenticated calls in its history. There is one MCP
server, and the [Polymarket tools](/docs/ai/data/polymarket) are on it; `data.vike.io/mcp` now reaches
that same server.

## Related [#related]

* [Polymarket REST (original reference)](/docs/data/reference/polymarket) — the earlier hand-written
  page, with an annotated `/markets` response.
* [Bulk archive](/docs/data/archive) — full L2 book events, the taker tape and derived top-of-book as
  Parquet, and the download guidance the two discovery endpoints above lead to.
* [Rate limits](/docs/data/rate-limits) · [Authentication](/docs/data/authentication)


# /market_stats (/docs/endpoints/data/polymarket/market-stats)



```
GET /v1/polymarket/market_stats?token_id={token_id}
```

Aggregate recorded activity for one outcome token in a single row — total events, trade count,
trade volume, first and last event timestamps, and how many book snapshots were captured. This is
the cheap orientation call: it tells you whether a token has any recorded history, and over what
span, before you request the tape itself.

Read the two timestamps before anything else. Here they are 2026-07-25T03:51:50Z and
2026-08-19T23:53:53Z — so this token's recorded tape &#x2A;*ends well before "now"**, and a
[`/events`](/docs/endpoints/data/polymarket/events) or [`/orderbook`](/docs/endpoints/data/polymarket/orderbook)
request aimed at the current hour would return nothing for it while a request inside that window
returns plenty. That is exactly what this call is for: `last_ms` is not a promise of freshness, it
is the end of what was recorded.

Note also how far apart the counts sit — 202,244 events and 10,674 snapshots against just 302
trades. Event volume is dominated by book activity, not by prints.

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/polymarket/market_stats?token_id=95532524407959903145510583684979049735028502452973932716346555811355282494630"
```

<Params>
  <Param name="token_id" loc="query">
    The outcome token. Omitting it returns 

    `400 {"error":"market_stats requires token_id"}`

    .
  </Param>
</Params>

```json title="Example response"
[
  {
    "first_ms": 1784951510849,
    "last_ms": 1787183633324,
    "snapshots": 10674,
    "total_events": 202244,
    "trade_volume": 39301.396175,
    "trades": 302
  }
]
```

Returns a one-element array whose row carries `total_events`, `trades`, `trade_volume`,
`first_ms`, `last_ms` and `snapshots`. The two timestamps are epoch milliseconds and bound the
recorded window — they are the range [`/events`](/docs/endpoints/data/polymarket/events) can serve for
that token.


# /markets/{condition_id} (/docs/endpoints/data/polymarket/markets-condition-id)



```
GET /v1/polymarket/markets/{condition_id}
```

One market's detail — the same row shape as the directory, for a single market. Call it when you
already hold a `condition_id` (from a Polymarket URL, a settlement row, or a stored id) and want
its `token_ids`, tick size and lifecycle flags without searching.

Note the shape: &#x2A;*a one-element array, not a bare object.** Even for a single market you index
`[0]`. It is the same row the directory returns, which is why an unknown id is an empty array
rather than a 404 — see the callout below.

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/polymarket/markets/0x7b9072e6a9cdcf022c4f098564e8ee612d544e179e4a33dcc2790fbaa778daa8"
```

<Params>
  <Param name="condition_id" loc="path">
    The 

    `0x`

    -prefixed market condition id.
  </Param>
</Params>

```json title="Example response"
[
  {
    "active": 1,
    "closed": 0,
    "condition_id": "0x7b9072e6a9cdcf022c4f098564e8ee612d544e179e4a33dcc2790fbaa778daa8",
    "end_date": 1798779600000,
    "neg_risk": 1,
    "slug": "will-bitcoin-reach-70000-by-december-31-2026-from-june-8",
    "tick_size": 0.001,
    "token_ids": [
      "95532524407959903145510583684979049735028502452973932716346555811355282494630",
      "107869950127184141743772429738701578723770582686430100389837827512148691029625"
    ]
  }
]
```

<Callout type="warn">
  **The path segment is matched as a `condition_id` only.** The MCP twin `get_market` accepts either
  a condition id or any of the market's token ids; the REST path form does not. A `token_id` in this
  position returns `[]` with status `200` — measured. There is no query-parameter form: a
  `?token_id=` on this path is ignored.
</Callout>


# /markets (/docs/endpoints/data/polymarket/markets)



```
GET /v1/polymarket/markets
```

The market directory — search and filter the recorded market universe by slug. Returns a bare
JSON array ordered by `end_date` descending, each row carrying `condition_id`, `slug`,
`token_ids`, `tick_size`, `neg_risk`, `active`, `closed` and `end_date`. This is the entry point:
almost every other endpoint here needs an id that only this one hands out.

All three rows are shown — `limit=3` bounded the response. The `token_ids` in the first row are
what every query-parameter endpoint in this namespace takes; the `condition_id` is what the two
path-parameter endpoints take. `end_date` is epoch milliseconds (`1798779600000` is
2027-01-01T05:00:00Z, i.e. the end of 2026 in US Eastern time).

The third slug is not a transcription error: some slugs carry a long numeric tail, and a client
that assumes a short human-readable slug will be surprised by one.

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/polymarket/markets?query=bitcoin&limit=3"
```

<Params>
  <Param name="query" loc="query">
    Case-insensitive substring match on the market slug.
  </Param>

  <Param name="active" loc="query">
    `true`

     \= only active, 

    `false`

     \= only inactive, omit = all.
  </Param>

  <Param name="limit" loc="query">
    Max rows. Default 

    `50`

    , 

    **hard cap 100**

     — a larger value is silently clamped, not rejected.
  </Param>
</Params>

```json title="Example response"
[
  {
    "active": 1,
    "closed": 0,
    "condition_id": "0x7b9072e6a9cdcf022c4f098564e8ee612d544e179e4a33dcc2790fbaa778daa8",
    "end_date": 1798779600000,
    "neg_risk": 1,
    "slug": "will-bitcoin-reach-70000-by-december-31-2026-from-june-8",
    "tick_size": 0.001,
    "token_ids": [
      "95532524407959903145510583684979049735028502452973932716346555811355282494630",
      "107869950127184141743772429738701578723770582686430100389837827512148691029625"
    ]
  },
  {
    "active": 1,
    "closed": 0,
    "condition_id": "0x84fdc3f917e34acca874f93d978e84ed0c08969903ddf40a5d65274b3a5b4fdf",
    "end_date": 1798779600000,
    "neg_risk": 1,
    "slug": "will-bitcoin-reach-75000-by-december-31-2026-from-june-8",
    "tick_size": 0.001,
    "token_ids": [
      "110439449768613802110790243898351375650535979513820669361590931221457616396762",
      "71940078455524699585822697954608343130226662273950516751010200431921477907081"
    ]
  },
  {
    "active": 1,
    "closed": 0,
    "condition_id": "0x752fa61c93f16c4b15e85b0bd438d9c684176b0ea7b319a84c8aca34616e8a8c",
    "end_date": 1798779600000,
    "neg_risk": 1,
    "slug": "will-bitcoin-dip-to-55000-by-december-31-2026-527-627-868-745-188-361-314-673-612-946-821-624-855-557-684-381-884-939-182-939-516",
    "tick_size": 0.01,
    "token_ids": [
      "115462087336983275104521488923966022755348986822352694745153736621832003960847",
      "48849252416222520684793262794712201381742900852794310345084361317209768152557"
    ]
  }
]
```

An annotated example response, and what `tick_size` and `neg_risk` mean, are on the
[older reference page](/docs/data/reference/polymarket).


# /ohlcv (/docs/endpoints/data/polymarket/ohlcv)



```
GET /v1/polymarket/ohlcv?token_id={token_id}&interval={interval}
```

Candles for one outcome token. Rows carry `ts`, `open`, `high`, `low`, `close`, `volume` and
`trades`.

All three bars are shown — `limit=3` bounded the response. The OHLC values are the probabilities
the warning below describes: `0.73` is 73%, not $0.73. `volume` is in USDC and is *not* on that
scale, so the two number families in one row mean different things.

⚠ &#x2A;*Bars are only emitted for intervals that traded, so `ts` is not a fixed-step series.** The
first two bars above are `1784970000000` and `1785009600000` — 39,600,000 ms apart, eleven hours
on a `1h` interval. A client that assumes consecutive rows are one interval apart, or that
back-fills gaps by index, will misread this tape. Step by `ts`, never by position.

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/polymarket/ohlcv?token_id=95532524407959903145510583684979049735028502452973932716346555811355282494630&interval=1h&limit=3"
```

<Params>
  <Param name="token_id" loc="query">
    The outcome token.
  </Param>

  <Param name="interval" loc="query">
    One of 

    `1m`

    , 

    `5m`

    , 

    `1h`

    , 

    `1d`

    . Anything else returns 

    `400`

     naming the four accepted values.
  </Param>

  <Param name="from" loc="query">
    Window start, epoch ms, 

    **inclusive**

    .
  </Param>

  <Param name="to" loc="query">
    Window end, epoch ms, 

    **inclusive**

    .
  </Param>

  <Param name="limit" loc="query">
    Max bars. Default 

    `500`

    , hard cap 

    `1000`

    .
  </Param>
</Params>

```json title="Example response"
[
  {
    "close": 0.74,
    "high": 0.74,
    "low": 0.73,
    "open": 0.73,
    "trades": 3,
    "ts": 1784970000000,
    "volume": 279.729667
  },
  {
    "close": 0.73,
    "high": 0.73,
    "low": 0.73,
    "open": 0.73,
    "trades": 1,
    "ts": 1785009600000,
    "volume": 499.99
  },
  {
    "close": 0.73,
    "high": 0.73,
    "low": 0.73,
    "open": 0.73,
    "trades": 1,
    "ts": 1785013200000,
    "volume": 3.28767
  }
]
```

<Callout type="warn">
  **These candles are priced in probability, 0–1** — not in currency. They are a different endpoint
  and a different store from
  [`/v1/hyperliquid/ohlcv`](/docs/endpoints/data/hyperliquid/ohlcv), which serves Hyperliquid perp candles
  in currency. Same word, different data.

  Note also that this window is **inclusive at both ends**, while
  [`/events`](/docs/endpoints/data/polymarket/events) is half-open. The two endpoints do not share a
  convention.
</Callout>


# /orderbook (/docs/endpoints/data/polymarket/orderbook)



```
GET /v1/polymarket/orderbook?token_id={token_id}
```

An order-book **snapshot** for one outcome token, taken from the nearest recorded book snapshot
at or before `ts` — the latest one if `ts` is omitted. Rows carry `as_of_ts`, `side`, `level`,
`price` and `size`, with `level` numbering outward from the touch, starting at 1 on each side.

**Truncated for the page: 25 rows were returned, levels 1 through 25; the first three are shown.**

Three things in this capture are worth more than the row shape:

**`as_of_ts` was two weeks stale.** No `ts` was passed, so this is "the latest snapshot" — and the
latest is `1787183491190`, 2026-08-19T23:51:31Z, for a call made on 2026-09-03. That is the
paragraph above made concrete: the endpoint answered `200` with a perfectly well-formed book that
was a fortnight old, and nothing but `as_of_ts` said so.

**This response has no duplication at all** — 25 rows, 25 distinct `(side, level)` pairs. That is
the factor-1 case the warning below describes. Do not read it as evidence the duplication is
fixed; de-duplicate anyway, because the factor is per-token and moves day to day.

⚠ &#x2A;*Every one of the 25 rows is a `bid` — there is no `ask` row in the response.** Whether that is
a genuinely one-sided book or `depth` bounding the *total* row count rather than each side is not
settled by this single capture, and the two readings are not equivalent for a client computing a
spread. Do not assume a response contains both sides: group by `side` and handle an absent one.

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/polymarket/orderbook?token_id=95532524407959903145510583684979049735028502452973932716346555811355282494630"
```

<Params>
  <Param name="token_id" loc="query">
    The outcome token.
  </Param>

  <Param name="ts" loc="query">
    As-of epoch ms. The nearest snapshot at-or-before it is used; omit for the latest.
  </Param>

  <Param name="depth" loc="query">
    Levels per side. Default 

    `25`

    , hard cap 

    `25`

    .
  </Param>
</Params>

```json title="Example response"
[
  {
    "as_of_ts": 1787183491190,
    "level": 1,
    "price": 0.999,
    "side": "bid",
    "size": 303284.22
  },
  {
    "as_of_ts": 1787183491190,
    "level": 2,
    "price": 0.991,
    "side": "bid",
    "size": 10077
  },
  {
    "as_of_ts": 1787183491190,
    "level": 3,
    "price": 0.99,
    "side": "bid",
    "size": 20105
  }
]
```

`as_of_ts` is the snapshot's own timestamp, not the `ts` you asked for — read it, because the
nearest snapshot may be considerably older than your request. A book shallower than `depth`
returns fewer levels; that is the real depth, not truncation.

⚠ &#x2A;*The same (`side`, `level`) can arrive several times as byte-identical rows — de-duplicate on
(`side`, `level`) before summing `size`.** The repeats are not extra depth, and a client that sums
the raw array overstates the book several-fold. **The multiplier is per-token and is not stable
over time**, so do not code against a fixed factor: twelve tokens sampled in one minute on
2026-09-03 returned factors of 1 (no duplication at all), 2, 5, 9 and 11, and the token that
returned 6 copies per level on 2026-09-02 returned 9 the next day. Every row in a response shares a
single `as_of_ts`, so the repeats are one snapshot fanned out, not successive ones. Read the depth
of a side as its `max(level)`, never as a row count.

For book *history* rather than a snapshot, use the [bulk archive](/docs/data/archive) — it carries
every book event, and it is far cheaper than replaying snapshots through this endpoint.


# /settlements/{condition_id} (/docs/endpoints/data/polymarket/settlements-condition-id)



```
GET /v1/polymarket/settlements/{condition_id}
```

The **on-chain settlement** of one market: which outcome won, what the payout vector was, and the
block and timestamp at which it resolved. Call it to determine, from chain truth, how a market
actually ended.

That is the call behind this page's response — a market that has already resolved on chain, so
its payout vector is immutable and this example cannot go stale.

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/polymarket/settlements/0x69e0442186b71c5cac4fa6304311e39101ed048983a200fc8e376a9dadd7de13"
```

<Params>
  <Param name="condition_id" loc="path">
    The 

    `0x`

    -prefixed market condition id. As with 

    [`/markets/{condition_id}`](/docs/endpoints/data/polymarket/markets-condition-id)

    , a 

    `token_id`

     here returns 

    `[]`

    .
  </Param>
</Params>

A real response, fetched from the running service.

```json title="Example response"
[
  {
    "condition_id": "0x69e0442186b71c5cac4fa6304311e39101ed048983a200fc8e376a9dadd7de13",
    "payouts": [0, 1],
    "resolved_block": 93138611,
    "resolved_ts_ms": 1788412950000,
    "slug": "will-donna-vekic-win-the-2026-womens-us-open",
    "token_ids": ["100208760979006815700821365554623989048585541964271047036444923380678560443951", "43437917871736289675135437047499696002273396903387531260510673476203211904981"],
    "winning_index": 1,
    "winning_token_id": "43437917871736289675135437047499696002273396903387531260510673476203211904981"
  }
]
```

`winning_index` indexes into `token_ids`, and `winning_token_id` is that entry resolved for you.
`payouts` is the on-chain payout vector in the same order.

<Callout type="warn" title="Settlement is chain truth; the market row may disagree">
  This is the on-chain resolution, **not** the market's own lifecycle flags. This page's market was
  resolved on chain at block 93,138,611, yet `/markets/{condition_id}` still reports `"active": 1,
  "closed": 0` for it. The two sources answer different questions and can disagree for a market that
  has settled but not yet been reaped from the directory. &#x2A;*For "how did this end", this endpoint is
  the authority.**
</Callout>

<Callout type="warn" title="Correction to an earlier page">
  The [older reference page](/docs/data/reference/polymarket) carries a struck-through section stating
  that `/v1/settlements` is routed but not implemented and that "nothing behind it has ever
  existed", directing readers to `/v1/polymarket/events` instead. **That is wrong for the
  `/{condition_id}` form**, which is what this page documents — this page's response was measured
  live. The claim is correct only for the *bare* path `/v1/settlements`, which is a dead word in the
  legacy regex and does return `404 {"error":"no such route"}`. That page's correction is pending.
</Callout>


# /smart_money (/docs/endpoints/data/polymarket/smart-money)



```
GET /v1/polymarket/smart_money
```

Where the wallets that have historically made money are putting it. The **cohort** is the set of
wallets with at least $1,000 of realized P\&L, at least five resolved markets and at least $5,000 of
volume; the route reports what that cohort is doing, in one of two modes. It is the same answer the
[`polymarket_smart_money`](/docs/ai/data/polymarket) MCP tool gives — the route runs that tool.

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/polymarket/smart_money?mode=flows&hours=24&limit=2"
```

<Params>
  <Param name="mode" loc="query">
    `flows`

     (default) — markets with the largest net cohort inflow in the window. 

    `mispricings`

     — markets where the cohort bought meaningfully below the current mid. Any other value is a 

    `400`

    .
  </Param>

  <Param name="hours" loc="query">
    Lookback window in hours, an integer from 1 to 720. Default 24. Anything else is a 

    `400`

    .
  </Param>

  <Param name="category" loc="query">
    Restrict to one market category (at most 64 characters). Default: all. An unknown category returns 

    `[]`

    , not an error.
  </Param>

  <Param name="limit" loc="query">
    Maximum rows, a positive integer. Default 10; values above 20 are capped at 20.
  </Param>
</Params>

A real response for `mode=flows`.

```json title="Example response (mode=flows)"
[
  {
    "condition_id": "0xe0b5bd8eef80fe8976e2c287e0b76a5cda138ddc437acf95f9ba91112dbc983d",
    "title": "Seahawks vs. Broncos",
    "slug": "nfl-sea-den-2026-10-16",
    "smart_wallets": 227,
    "buy_inflow": 3819464.49,
    "sell_outflow": 166081.01,
    "net_inflow": 3653383.48,
    "trades": 4576,
    "last_ts": "2026-10-16 03:49:49",
    "yes_mid": 0.015
  }
]
```

And a real response for `mode=mispricings`.

```json title="Example response (mode=mispricings)"
[
  {
    "condition_id": "0x6a93a3190840da7ad3545168388c83c2244c4b5279bbe8ef537f1a091bcec7a0",
    "title": "Solana Up or Down - October 15, 10:50AM-10:55AM ET",
    "slug": "sol-updown-5m-1792075800",
    "smart_wallets": 49,
    "last_buy_ts": "2026-10-15 14:55:16",
    "total_buy_value": 1548.59,
    "side": "YES",
    "avg_buy_price": 0.2466,
    "current_mid": 0.985,
    "delta": 0.7384,
    "buy_value": 384.66
  }
]
```

## Reading it [#reading-it]

* **`net_inflow` is dollars, not shares**: cohort buys minus cohort sells in the window.
* **`yes_mid` can be `null`** — the market has no recorded mid yet. It is absent data, not zero.
* **`mispricings` only lists clear cases.** A market appears when the cohort put at least $500 into
  it and the current mid is at least 0.03 away from their average entry in their favour. `delta` is
  `current_mid - avg_buy_price` for the side they bought; a large positive value means the market
  has already moved toward the cohort. It records where they were early and is not a forecast.
* **`side` is the outcome position, not a literal Yes/No.** `YES` is the first outcome of the market
  and `NO` the second, so on an Over/Under or a two-team market read them as "outcome 1" and
  "outcome 2" and take the names from the market.
* **A short-dated market can dominate.** Five-minute "up or down" markets resolve fast and show
  large deltas; filter with `category` when you want slower markets.

## Errors [#errors]

| Status        | When                                                                                                                                                 |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`         | `mode`, `hours` or `limit` is outside the values above, `category` is too long, or an unknown query parameter is sent. The body is `{"error": "…"}`. |
| `401` / `429` | No or bad credential, or the hourly budget is spent — see [Authentication](/docs/data/authentication) and [Rate limits](/docs/data/rate-limits).               |
| `503`         | The store behind it is unavailable. The body carries no driver text.                                                                                 |


# /wallets/{address} (/docs/endpoints/data/polymarket/wallets-address)



```
GET /v1/polymarket/wallets/{address}
```

One Polymarket trader, profiled from the **on-chain trade tape**: lifetime volume and trade counts,
realized P\&L and hit rate over a chosen window, the markets the wallet traded, its recent trades,
open positions and a daily equity curve. It is the same answer the
[`polymarket_wallet`](/docs/ai/data/polymarket) MCP tool gives — the route runs that tool.

```sh title="cURL"
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/polymarket/wallets/0x204f72f35326db932158cba6adff0b9a1da95e14?window=30d"
```

<Params>
  <Param name="address" loc="path">
    The wallet's 

    `0x`

    -prefixed proxy-wallet address (40 hex digits). Anything else is a 

    `400`

    .
  </Param>

  <Param name="window" loc="query">
    `24h`

    , 

    `7d`

    , 

    `30d`

     or 

    `all`

    . Default 

    `all`

    . Any other value is a 

    `400`

    . See 

    *What the window moves*

     for which fields it changes.
  </Param>
</Params>

The response is large — up to 100 trades, 30 markets and a few hundred equity-curve points — so the
real one is abridged in this example, each list cut to its first element.

```json title="Example response (abridged)"
{
  "proxy_wallet": "0x204f72f35326db932158cba6adff0b9a1da95e14",
  "window": "30d",
  "trades_window": 0,
  "trades_all": 4331238,
  "volume_window_usd": 0.0,
  "volume_all_usd": 611448374.69,
  "avg_trade_usd": 141.17,
  "markets_count": 150749,
  "first_seen": "2026-01-01 00:00:37",
  "last_seen": "2026-08-26 09:17:49",
  "realized_pnl_usd": 379.10,
  "resolved_markets": 34,
  "hit_rate": 0.4105,
  "hit_rate_ci": 0.157,
  "open_positions": [],
  "open_exposure_usd": 0,
  "markets": [ { "condition_id": "0x392b…", "title": "…", "trades": 673, "volume_usd": 1575609.82, "net_shares": 1971349.29, "resolved": true, "winning_outcome": "Argentina", "realized_pnl": 384904.21 } ],
  "trades": [ "…" ],
  "equity_curve": [ "…" ],
  "category_breakdown": [ "…" ],
  "daily_activity": [ "…" ],
  "correlated": [ "…" ],
  "tags": [ "…" ],
  "is_active": false,
  "streak": { "n": 6, "kind": "win" }
}
```

## What the window moves [#what-the-window-moves]

`window` scopes **some** fields and leaves the rest alone.

| Field                                                                                                                | Scoped by `window`? | Cut by                                                              |
| -------------------------------------------------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------- |
| `trades_window`, `volume_window_usd`                                                                                 | Yes                 | trade time                                                          |
| `realized_pnl_usd`, `resolved_markets`, `hit_rate`, `hit_rate_ci`                                                    | Yes                 | **resolution** time — only markets resolved inside the window count |
| `trades_all`, `volume_all_usd`, `avg_trade_usd`, `markets_count`, `first_seen`, `last_seen`, share and dollar totals | No                  | lifetime                                                            |
| `markets`, `trades`, `open_positions`, `equity_curve`, `category_breakdown`, `daily_activity`, `correlated`          | No                  | full history                                                        |

A wallet that traded long ago but resolved nothing inside the window reports `trades_window: 0`
and `realized_pnl_usd: 0` — zeros that mean "nothing in this window", not "no activity".

## Reading it [#reading-it]

* **`hit_rate` is volume-weighted, not a count of wins.** It is the share of the wallet's
  *resolved dollar volume* that sat in markets where it made money. With `resolved_markets: 34` an
  integer number of won markets will not reproduce it. `hit_rate_ci` is the Wilson confidence
  half-width on that rate; with few resolved markets it is wide, so do not rank on the point value.
* **`realized_pnl_usd` is realized only.** An open position contributes nothing until its market
  resolves. Markets that resolved *invalid* are excluded from P\&L, hit rate and the resolved count.
* **`open_positions` and `open_exposure_usd` understate.** A position is priced from a recent
  top-of-book quote (the last hour); one with no fresh quote is left out.
* **Lists are capped.** `markets` and `open_positions` hold at most 30 rows, `trades` at most 100,
  however large `markets_count` is. `correlated` lists up to 8 wallets that trade many of the same
  markets.
* **Not comparable with the L2 routes.** This reads the trade tape; [`/market_stats`](/docs/endpoints/data/polymarket/market-stats)
  and [`/ohlcv`](/docs/endpoints/data/polymarket/ohlcv) read the recorded book, so the same wallet's
  volume can differ between them.

## Errors [#errors]

| Status        | When                                                                                                                                                                                            |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`         | The address is not `0x` plus 40 hex digits, `window` is not one of the four values, an unknown query parameter is sent, **or the wallet has no recorded trades**. The body is `{"error": "…"}`. |
| `401` / `429` | No or bad credential, or the hourly budget is spent — see [Authentication](/docs/data/authentication) and [Rate limits](/docs/data/rate-limits).                                                          |
| `503`         | The store behind it is unavailable. The body carries no driver text.                                                                                                                            |

This is a heavier call than its single budget unit suggests: the `correlated` list alone scans
hundreds of MiB. Cache the answer rather than polling it.


# /v1/docs (/docs/endpoints/data/schema/docs)



```
GET https://data.vike.io/v1/docs
```

Swagger UI over the same document: the interactive, one-operation-at-a-time view, with an
**Authorize** dialog that attaches your key to *Try it out* calls now that the spec declares
`ApiKeyHeader`.

No parameters. Serves `text/html`.

A live call and what it returned, captured 2026-09-03.

```sh title="cURL"
curl -H "X-API-KEY: $VIKE_API_KEY" https://data.vike.io/v1/docs
```

`200`, 1,018 bytes — and `text/html`, not JSON, so it is shown as the HTML it is. This is the
complete body, verbatim; nothing is elided.

```html title="Example response"

    <!DOCTYPE html>
    <html>
    <head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link type="text/css" rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css">
    <link rel="shortcut icon" href="https://fastapi.tiangolo.com/img/favicon.png">
    <title>vike.io Data API - Swagger UI</title>
    </head>
    <body>
    <div id="swagger-ui">
    </div>
    <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
    <!-- `SwaggerUIBundle` is now available on the page -->
    <script>
    const ui = SwaggerUIBundle({
        url: '/v1/openapi.json',
    "dom_id": "#swagger-ui",
"layout": "BaseLayout",
"deepLinking": true,
"showExtensions": true,
"showCommonExtensions": true,
oauth2RedirectUrl: window.location.origin + '/docs/oauth2-redirect',
    presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIBundle.SwaggerUIStandalonePreset
        ],
    })
    </script>
    </body>
    </html>
    
```

That is the whole of it: a shell with no API data in it at all. Everything a reader recognises as
Swagger UI arrives afterwards, from two `cdn.jsdelivr.net` script and stylesheet fetches and one
fetch of the spec, all issued by the browser.

Two lines in those bytes are worth reading against the warnings above. **`url: '/v1/openapi.json'`
is host-relative**, so the browser fetches the spec from `data.vike.io` itself — a second request,
behind the same header-only gate, carrying no `X-API-KEY&#x60; of its own. Getting this HTML rendered is
therefore not sufficient: a header-injecting extension or proxy has to cover the spec fetch too, not
just the page load. And &#x2A;*`oauth2RedirectUrl: window.location.origin + '/docs/oauth2-redirect'`** is
the un-moved route described below, present in the served bytes — the shell asks the browser to build
a callback URL under the bare `/docs/` prefix, which this host does not route anywhere.

⚠ The browser trap on [Schema and spec](/docs/endpoints/data/schema) bites here first — this is the page
people try to open by hand, and by hand it 401s. There is a second, harmless oddity behind it:
the framework also mounts `/docs/oauth2-redirect`, its default OAuth2 authorization-code callback, and
that route alone was never moved under `/v1/`. It is unreachable at the edge (measured 404 on
2026-09-03) and unused — the published `OAuth2Bearer` scheme is `type: http`, a token pasted into
the Authorize box, which needs no redirect.

What the document declares, what it leaves out, and the gate in front of it:
[Schema and spec](/docs/endpoints/data/schema).


# Schema and spec (/docs/endpoints/data/schema)



Three surfaces describe the REST API, and all three live under `/v1/` on `data.vike.io`, served by
the same application as the operations they describe. They sit under `/v1/` rather than at the
framework's default bare paths, because `/v1/` is the only prefix that reaches that application on
this host — the bare paths are routed nowhere and answer 404. Both halves of that placement are
pinned by tests, so neither moves quietly.

All three are unauthenticated **at the application** and gated **at the edge**: the credential check
covers the whole `/v1/` prefix, with no exemption for the schema paths. Measured with no credential
on 2026-09-03: `/v1/openapi.json`, `/v1/docs` and `/v1/redoc` each answered **401**;
`/openapi.json`, `/docs` and `/redoc` each answered **404**.

<Callout type="warn" title="A browser cannot open the interactive pages">
  The gate is **header-only**: exactly two headers are read, `Authorization` and `X-API-KEY`. No
  cookie, no session and no `?token=` query parameter authenticates a request to this host, so being
  signed in to vike.io in the same browser does nothing here. Swagger UI and ReDoc are HTML pages
  behind that header gate: typing either URL into a browser returns 401. Reach them with a
  header-injecting extension or proxy, or read the spec with `curl` and work from the file.
</Callout>

Every request to these three paths is metered like any other `/v1` call and spends one unit of
[the hourly budget](/docs/data/rate-limits), each under its own usage label. Fetching the spec is a
normal API call, not a free one.

## The three surfaces [#the-three-surfaces]

| Path                                                      | What it is                                                                                 |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| [`/v1/openapi.json`](/docs/endpoints/data/schema/openapi-json) | The live OpenAPI 3.1.0 document for the `/v1` REST API — the machine-readable surface.     |
| [`/v1/docs`](/docs/endpoints/data/schema/docs)                 | Swagger UI over the same document: the interactive, one-operation-at-a-time view.          |
| [`/v1/redoc`](/docs/endpoints/data/schema/redoc)               | ReDoc over the same document: one scrollable reference page rather than a request console. |

## What the spec declares [#what-the-spec-declares]

Counted on 2026-10-17 from the application's own `openapi()` — the document `/v1/openapi.json`
serves, which is behind the key gate and was not fetched for this count. It has changed before and
will again: the Polymarket routes joined it on 2026-09-03, `/wallets/{address}/defi` (2026-09-04)
and `/funds/holdings` (2026-10-16) left it, and two Polymarket trader routes were added
(2026-10-16).

| Field                               | Value                                                                                  |
| ----------------------------------- | -------------------------------------------------------------------------------------- |
| OpenAPI version                     | `3.1.0`                                                                                |
| `info.title` / `info.version`       | `vike.io Data API` / `1.0.0`                                                           |
| `servers`                           | one entry, `https://data.vike.io`                                                      |
| Paths / operations                  | 61 / 61 — 60 `GET` and one `POST` (`/v1/onchain/labels/batch`)                         |
| Namespace split                     | hyperliquid 35 · onchain 15 · polymarket 11 — all of them documented in this reference |
| Operations carrying a `summary`     | 61 of 61                                                                               |
| Operations carrying a `description` | **47 of 61**                                                                           |
| Declared parameters                 | 258, of which **89** carry a description                                               |
| `components.schemas`                | **2** — `HTTPValidationError` and `ValidationError`                                    |
| Declared response codes             | `200` on all 61, `422` on 58                                                           |
| 2xx bodies declaring a schema       | **0**                                                                                  |
| `securitySchemes`                   | `OAuth2Bearer`, `ApiKeyHeader`                                                         |

Those counts are reproducible from the live document — this prints six of the rows above, and run
against the document as captured on 2026-09-03 it agreed with every one of them.

```sh title="cURL"
curl -s -H "X-API-KEY: $VIKE_API_KEY" https://data.vike.io/v1/openapi.json | jq '{
  paths: (.paths | length),
  described: [.paths[][] | select(.description)] | length,
  params: [.paths[][].parameters // [] | .[]] | length,
  params_described: [.paths[][].parameters // [] | .[] | select(.description)] | length,
  schemas: (.components.schemas | keys),
  codes: [.paths[][].responses | keys[]] | unique
}'
```

```json title="Example response"
{
  "paths": 61,
  "described": 47,
  "params": 258,
  "params_described": 89,
  "schemas": [
    "HTTPValidationError",
    "ValidationError"
  ],
  "codes": [
    "200",
    "422"
  ]
}
```

Every path in the document starts with `/v1/`. Internal operational routes are excluded from the
spec by design; nothing outside `/v1/` is API a key-holder can call. The three surfaces in this
namespace are excluded too, so the document does not describe itself.

Every one of its 61 operations is a `hyperliquid`, `onchain` or `polymarket` endpoint these pages
document, so the whole-document counts above describe exactly this reference's REST surface.

Parameters are the part the spec does carry: all 258 declare a name, a location, a type and whether
they are required, which is enough for a generator to build correct request signatures. Only 89 of
them carry prose explaining what they do. Three operations declare no parameters at all —
`/v1/hyperliquid/cohorts`, `/v1/hyperliquid/segments` and `/v1/hyperliquid/positions/coins`.

**The auth block is real, and it is what makes generation viable at all.** The document publishes
both credentials — `ApiKeyHeader` (`apiKey`, in `header`, named `X-API-KEY`) and `OAuth2Bearer`
(`http`/`bearer`, `bearerFormat: vk_oat_...`) — and the top-level `security` is a **list** of
single-key requirements, which in OpenAPI means *either*, not *both*. A generated client therefore
sends a credential header instead of 401ing on its first call. It is schema only: it declares the
auth the API already enforces, and adding or removing a scheme cannot change whether a call is
accepted. No operation opts out with `security: []`, and a test holds that true. Both schemes
landed on 2026-09-02; before that the document declared no authentication at all, on a key-gated,
per-call-billed API.

## The four gaps [#the-four-gaps]

Be clear-eyed about these before planning to generate anything from the document.

**1. There are no response schemas.** `components.schemas` holds exactly two entries and both are
error types, reached only from the `422` response that 58 operations declare. (The three operations
with no `422` are exactly the three that take no parameters, so there is nothing to validate.)
Every `200` in the document is `{"schema": {}}`, an undeclared object, so a generated client gives
you typed *requests* and untyped *responses*. That is a deliberate property of the API rather than
an oversight in the export: responses are undeclared objects, and no count of "schema gaps" can
make them otherwise. Where a response field matters, these pages state it; the document will not.

**2. Fourteen operations carry no description.** The gap is not spread evenly: onchain is missing
13 of 15, hyperliquid 1 of 35 and polymarket none of 11. Every operation has a `summary`, so
nothing is nameless, but across most of `onchain` the summary is all there is. The namespace pages
in this reference are where that prose lives.

**3. Only success and validation failure are declared.** The document declares `200` and `422` and
nothing else, while the API really returns `400` for rejected input, `401` for a bad or missing
credential, `429` for the hourly limit and `503` for an upstream failure — see
[Errors](/docs/data/errors). Error handling is the part of a generated client you write yourself, and a
generator that treats an undeclared status as a protocol violation will treat a normal rate-limit
trip as one.

**4. It covers 61 of the 68 endpoints in this reference.** Every one of the missing 7 is missing
for a structural reason, not because someone forgot:

| Absent from the spec                 | Count | Why                                                                                                                                                       |
| ------------------------------------ | ----: | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [archive](/docs/endpoints/data/archive)   |     3 | Files served directly. There is no application operation to describe.                                                                                     |
| [stream](/docs/endpoints/data/stream)     |     1 | A different application on a different host (`vike.io`), which this document does not cover — and OpenAPI has no WebSocket operation to emit in any case. |
| The three surfaces in this namespace |     3 | Excluded from the document by design.                                                                                                                     |

<Callout type="warn" title="The spec is behind the same gate as the data">
  Nothing under `/v1/` is readable without a credential, the document included. A prospective user
  cannot inspect the API's shape before holding a key, and no public copy is published today — see
  below. If you need to show someone the surface without giving them a key, send them these pages.
</Callout>

## `data.vike.io/openapi.json` is not shipped [#datavikeioopenapijson-is-not-shipped]

There is no keyless copy of the spec at the bare path on this host. &#x2A;*That URL does not work.**

```
$ curl -s -o /dev/null -w '%{http_code}\n' https://data.vike.io/openapi.json
404
```

Measured 2026-09-03. The host root behaves the same way: `https://data.vike.io/` returns 404 too —
nothing but `/v1/` and `/archive/` is routed on this host. Use
[`/v1/openapi.json`](/docs/endpoints/data/schema/openapi-json) with a key; it is the only published
copy, and no curated public variant exists today.

## Related [#related]

* [Authentication](/docs/data/authentication) — the two credentials, and where to create a key.
* [Rate limits](/docs/data/rate-limits) — the one hourly counter these three surfaces spend from.
* [Errors](/docs/data/errors) — the status codes the spec does not declare.
* [Endpoint overview](/docs/endpoints/data) — the namespace table every endpoint in this reference sits in.


# /v1/openapi.json (/docs/endpoints/data/schema/openapi-json)



```
GET https://data.vike.io/v1/openapi.json
```

The live OpenAPI 3.1.0 document for the `/v1` REST API. This is the machine-readable surface: fetch
it once to generate a client or drive a request tool, or diff it after a deploy to see what moved.

No path or query parameters — the only input that matters is the credential header.

```sh title="cURL"
curl -H "X-API-KEY: $VIKE_API_KEY" \
  https://data.vike.io/v1/openapi.json -o openapi.json
```

`200`, 84,924 bytes of `application/json` when captured on 2026-09-03. Too large to show whole, so
it is split below into the three parts worth reading; the entries under `paths`, the two schemas under
`components.schemas` and the one prose string noted below are elided, and every other byte shown is
verbatim from that response.

The envelope — the document with `paths` and `components` removed and one prose string elided.

```json title="Example response — the envelope"
{
  "openapi": "3.1.0",
  "info": {
    "title": "vike.io Data API",
    "description": "<elided — see the note below>",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://data.vike.io"
    }
  ],
  "security": [
    {
      "OAuth2Bearer": []
    },
    {
      "ApiKeyHeader": []
    }
  ]
}
```

⚠ `info.description` is the one string elided from the envelope above. It is a hand-written summary
the document carries rather than derives, and it has fallen behind the routes the application
actually serves — it still names surfaces that were removed. Read `paths` for what the API covers,
or the namespace pages under [API endpoints](/docs/endpoints/data); do not read that string.

`components.securitySchemes`, the block that makes client generation viable — both credentials, each
carrying its own prose, and a top-level `security` (above) that is a **list** of single-key
requirements, i.e. *either*, not *both*:

```json title="components.securitySchemes"
{
  "OAuth2Bearer": {
    "type": "http",
    "scheme": "bearer",
    "bearerFormat": "vk_oat_...",
    "description": "OAuth 2.1 access token: `Authorization: Bearer vk_oat_...`. Issued by vike.io — discovery at `https://vike.io/.well-known/oauth-authorization-server`. Tried first; an invalid bearer falls through to the API-key header, so a request may carry either or both."
  },
  "ApiKeyHeader": {
    "type": "apiKey",
    "in": "header",
    "name": "X-API-KEY",
    "description": "Long-lived API key: `X-API-KEY: vk_...`. Create and revoke keys at https://vike.io/account?tab=api-keys. Every call is metered against the key and subject to an hourly rate limit; a trip is HTTP 429 with a `Retry-After` header."
  }
}
```

`components.schemas` is elided: it holds exactly the two entries the table on
[Schema and spec](/docs/endpoints/data/schema) names, `HTTPValidationError` and `ValidationError`, and
both are the framework's own request-validation error shapes.

One entry under `paths`, verbatim — `/v1/onchain/wallets/{address}`, chosen because it
is the smallest complete operation in the document and shows three of the four gaps at once:

```json title="One entry from paths"
{
  "get": {
    "tags": [
      "onchain"
    ],
    "summary": "Wallet Summary",
    "operationId": "wallet_summary_v1_onchain_wallets__address__get",
    "parameters": [
      {
        "name": "address",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "title": "Address"
        }
      }
    ],
    "responses": {
      "200": {
        "description": "Successful Response",
        "content": {
          "application/json": {
            "schema": {}
          }
        }
      },
      "422": {
        "description": "Validation Error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/HTTPValidationError"
            }
          }
        }
      }
    }
  }
}
```

The parameter is fully typed and marked `required`, which is the part a generator can use. But there
is no `description` on the operation (it is one of the 14 without) and none on the parameter (one of
the 169 without); the `200` body is `"schema": {}`, an undeclared object; and the only other declared
response is the `422`, whose `$ref` reaches one of the two error schemas. A generated client gets a
correct request signature and an untyped response — [the four
gaps](/docs/endpoints/data/schema#the-four-gaps) is the fuller account.

The table on [Schema and spec](/docs/endpoints/data/schema#what-the-spec-declares) carries the current
counts, taken on 2026-10-17 from the application's own `openapi()` that this document is built from:
61 paths and 61 operations (60 `GET`, the one `POST` being `/v1/onchain/labels/batch`), the
35 · 15 · 11 namespace split, 47 of 61 descriptions, 258 parameters of which 89 are described,
`200` on all 61 and `422` on 58, zero 2xx bodies declaring a schema, and no declared status code
anywhere in the document other than those two.

It is generated, not hand-written, and it cannot drift from the routes that serve it: it is the
framework's own document with the two security schemes added, then cached. Fetching it queries no
data store, so it costs a request and nothing more.

What the document declares, what it leaves out, and the gate in front of it:
[Schema and spec](/docs/endpoints/data/schema).


# /v1/redoc (/docs/endpoints/data/schema/redoc)



```
GET https://data.vike.io/v1/redoc
```

ReDoc over the same document: one scrollable reference page rather than a request console. Prefer it
for reading, [`/v1/docs`](/docs/endpoints/data/schema/docs) for calling.

No parameters. Serves `text/html`.

A live call and what it returned, captured 2026-09-03.

```sh title="cURL"
curl -H "X-API-KEY: $VIKE_API_KEY" https://data.vike.io/v1/redoc
```

`200`, 900 bytes — `text/html`, not JSON, so it is shown as the HTML it is. This is the complete
body, verbatim; nothing is elided.

```html title="Example response"

    <!DOCTYPE html>
    <html>
    <head>
    <title>vike.io Data API - ReDoc</title>
    <!-- needed for adaptive design -->
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    
    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
    
    <link rel="shortcut icon" href="https://fastapi.tiangolo.com/img/favicon.png">
    <!--
    ReDoc doesn't change outer page styles
    -->
    <style>
      body {
        margin: 0;
        padding: 0;
      }
    </style>
    </head>
    <body>
    <noscript>
        ReDoc requires Javascript to function. Please enable it to browse the documentation.
    </noscript>
    <redoc spec-url="/v1/openapi.json"></redoc>
    <script src="https://cdn.jsdelivr.net/npm/redoc@2/bundles/redoc.standalone.js"> </script>
    </body>
    </html>
    
```

The served bytes are the thinnest of the three surfaces — 118 bytes less than
[`/v1/docs`](/docs/endpoints/data/schema/docs) — and they carry the reading-versus-calling split in a
single element.

**`<redoc spec-url="/v1/openapi.json">`** is the entire application: no Authorize dialog, no
`oauth2RedirectUrl`, no request console, nothing that could submit a call. That is the difference
between this page and Swagger UI stated in markup rather than in prose.

`spec-url` is host-relative, exactly as on `/v1/docs`, so the same consequence follows: the browser
issues a second request to `data.vike.io` for the spec, and that request is behind the same
header-only gate and carries no `X-API-KEY` of its own. Rendering this HTML is not enough on its own.

Note also the `<noscript>` line in the body: ReDoc renders nothing without JavaScript, so `curl`
alone can never show you the reference — the 900 bytes above are all a non-browser client will ever
receive. To read the surface from a terminal, fetch
[`/v1/openapi.json`](/docs/endpoints/data/schema/openapi-json) instead.

ReDoc was the one surface left at the framework default when the other two moved under `/v1/`. It
joined them on 2026-09-02, in the change that also added the security schemes.

What the document declares, what it leaves out, and the gate in front of it:
[Schema and spec](/docs/endpoints/data/schema).


# bar (/docs/trader/concepts/data/bar)




`bar` is one of the shapes the historical store holds. A stored series lives under a
`kind=` path segment, and that segment is the layout contract its producers and its consumers
have to agree on: the columns, how the leaf is partitioned, and what `venue` and `symbol` mean
for this particular kind. All of it is below, rendered from the same table the runtime dispatches
on.

One decoded row becomes a `vike_model::Bar`. The codec that owns the schema is `BarCodec`; the
store writes through `append_bars` and reads through `load_bars`.

## Identity [#identity]

**venue = the bridge venue id; symbol = the instrument; interval = the bar step, a REAL sub-partition and not a column**

This is the field most often assumed and most often wrong, which is why it is stated per kind
rather than once for the store.

## Columns [#columns]

Every Arrow column today's writer emits, in schema order, with the codec flavor that picks its
Arrow type and nullability.

| Column    | Flavor     | Note                                  |
| --------- | ---------- | ------------------------------------- |
| `ts`      | `i64`      | —                                     |
| `open`    | `f64`      | —                                     |
| `high`    | `f64`      | —                                     |
| `low`     | `f64`      | —                                     |
| `close`   | `f64`      | —                                     |
| `volume`  | `f64`      | —                                     |
| `funding` | `f64_null` | always PRESENT, and may hold SQL NULL |

## Layout [#layout]

| Property                      | Value                    |
| ----------------------------- | ------------------------ |
| Partitioning                  | `symbol-interval`        |
| Grouped form                  | no — one series per part |
| In the cross-kind tick report | no                       |

## Traps [#traps]

⚠ TWO different facts are called funding, and THIS row is the market one. The MARKET funding-RATE history is a BAR series under the reserved label `interval=funding`, carrying the rate on `Bar::funding` with OHLCV and volume all 0.0 — `crates/vike-backfill/src/funding_rate.rs`'s `point_to_bar` writes it and `crates/vike-backtest/src/harness/run.rs` reads it back with `load_bars(venue, symbol, "funding", …)`. The ACCOUNT's realized payments are a different series entirely, and since decision 0080 they no longer share a word: that kind is `exec_funding`. The market side was deliberately NOT renamed — `interval` is part of `SeriesId` and bar series exist, so only the account side was free to move. The label is deliberately NOT a cadence, because funding cadence varies by venue and by symbol and can be re-cadenced over time. ⚠ No `symbol_col` column exists here, so a bar series can never be grouped. ⚠ `crates/vike-backfill/src/ibkr.rs`'s `backfill_commit_key` keys on a `what` the SERIES does not discriminate (`trades`/`bid`/…), so two `--what` runs land in ONE series while each believes its key is fresh.

Pinned rather than fixed: the contradiction is recorded with both sides named, so a reader meets it here instead of in production.

## Known producers [#known-producers]

Idempotency in this store is batch-level and keyed on a commit-key string, never on per-row value
dedup. Two producers that collide on one template silently no-op each other's appends, and a
producer that changes its template re-admits history it already wrote — both invisible unless the
shapes are written side by side.

| Producer                                       | Commit-key template                                                |
| ---------------------------------------------- | ------------------------------------------------------------------ |
| `crates/vike-backfill/src/klines.rs`           | `{venue}:{symbol}:{interval}:{start_ms}-{end_ms}`                  |
| `crates/vike-backfill/src/dukascopy.rs`        | `dukascopy-resample:{symbol}:{interval}:{}-{}`                     |
| `crates/vike-backfill/src/funding_rate.rs`     | `funding_rate:{venue}:{symbol}:{start_ms}-{end_ms}`                |
| `crates/vike-backfill/src/ibkr.rs`             | `ibkr-backfill:{venue}:{symbol}:{interval}:{what}:{window_end_ms}` |
| `crates/vike-backfill/src/bin/eod_backfill.rs` | `{}:{sym}:{}y:{today}`                                             |
| `crates/vike-backfill/src/databento/ingest.rs` | `databento:{}:{symbol}:{window}`                                   |
| `crates/vike-data/src/demo.rs`                 | `demo-tape:v{DEMO_TAPE_VERSION}:{}:{}`                             |

⚠ That list is **observed, not exhaustive**, and no gate can make it so: a commit key is an
ordinary string argument, so proving the list complete would mean following every call in the
workspace. What is gated per listed entry is that the producer exists and spells the template
verbatim. Read it as "these producers write this kind", never as "only these do".

## Where this comes from [#where-this-comes-from]

`vike_data::store_kind::STORE_KINDS`, exported as `rosters.json` at every release. The store's
own gate derives the live kind set from the code — the series directory literals, the compaction
dispatch and the write verbs — and fails until a new kind has a row, so this page cannot describe
a shape the store does not write.


# book (/docs/trader/concepts/data/book)




`book` is one of the shapes the historical store holds. A stored series lives under a
`kind=` path segment, and that segment is the layout contract its producers and its consumers
have to agree on: the columns, how the leaf is partitioned, and what `venue` and `symbol` mean
for this particular kind. All of it is below, rendered from the same table the runtime dispatches
on.

One decoded row becomes a `BookRow (exploded from vike_model::BookUpdate — ONE ROW PER LEVEL)`. The codec that owns the schema is `BookCodec`; the
store writes through `append_book_updates` and reads through `scan_book_updates`, and parts carry the Parquet metadata key `vike.schema.book`.

## Identity [#identity]

**venue = the bridge venue id; symbol = the instrument. The LOSSLESS L2 lane: every delta present, `seq` contiguous, gaps detectable. ⚠ CONTRADICTED by the pmxt Polymarket archive, and PINNED here rather than quietly fixed: `crates/vike-data/src/cheap_np_book.rs` — which moved into this crate in #2017 and so now sits beside this row — records that the pmxt mapper assigns `seq` per asset per HOURLY FILE, so it restarts at 0 every hour. This row describes the LIVE recorder's output; the archive ingested from pmxt does not satisfy it, and that file's `a_recorded_seq_restart_does_not_drop_later_deltas` is what holds the fold correct across the restart**

This is the field most often assumed and most often wrong, which is why it is stated per kind
rather than once for the store.

## Columns [#columns]

Every Arrow column today's writer emits, in schema order, with the codec flavor that picks its
Arrow type and nullability.

| Column       | Flavor    | Note                                                                  |
| ------------ | --------- | --------------------------------------------------------------------- |
| `ts`         | `i64`     | —                                                                     |
| `local_ts`   | `i64`     | —                                                                     |
| `seq`        | `i64`     | —                                                                     |
| `kind`       | `i8`      | —                                                                     |
| `is_bid`     | `bool`    | —                                                                     |
| `price`      | `f64`     | —                                                                     |
| `size`       | `f64`     | —                                                                     |
| `tick_size`  | `f64`     | —                                                                     |
| `symbol_col` | `str_add` | may be ABSENT ENTIRELY from a part sealed before the column was added |

## Layout [#layout]

| Property                      | Value                                                                   |
| ----------------------------- | ----------------------------------------------------------------------- |
| Partitioning                  | `symbol`                                                                |
| Grouped form                  | yes — many symbols in one part, told apart by a row-level symbol column |
| In the cross-kind tick report | yes                                                                     |

## Traps [#traps]

⚠ The APPEND and the SCAN count different things: `append_book_updates` returns EVENTS while the part holds one row per LEVEL, and a zero-level event (a status marker, or a degenerate empty snapshot) is stored as ONE placeholder row with `is_bid=true, price=0.0, size=0.0` that decodes back to empty level vectors. A consumer counting rows is not counting events. The `kind` column is an Int8 CODE, not the series kind — `crates/vike-data/src/datafusion_hist/codec.rs`'s `book_kind_code` is the mapping, and the §B stream-health markers (`GapStart`/`Stale`/`LiveResume`) ride this lane as those codes.

Pinned rather than fixed: the contradiction is recorded with both sides named, so a reader meets it here instead of in production.

## Known producers [#known-producers]

Idempotency in this store is batch-level and keyed on a commit-key string, never on per-row value
dedup. Two producers that collide on one template silently no-op each other's appends, and a
producer that changes its template re-admits history it already wrote — both invisible unless the
shapes are written side by side.

| Producer                                       | Commit-key template                                   |
| ---------------------------------------------- | ----------------------------------------------------- |
| `crates/vike-data/src/live_rec.rs`             | `live-{venue}-{symbol}-{}-{first_ts}-{last_ts}-{seq}` |
| `crates/vike-backfill/src/pmxt/ingest.rs`      | `pmxt:book:{asset}:{hour}`                            |
| `crates/vike-backfill/src/vike_archive.rs`     | `vikearchive:{}:{date}:rg{rg_idx}`                    |
| `crates/vike-backfill/src/events_api.rs`       | `eventsapi:book:{symbol}:{day}`                       |
| `crates/vike-backfill/src/tardis/ingest.rs`    | `tardis:{}:{symbol}:{day}`                            |
| `crates/vike-backfill/src/databento/ingest.rs` | `databento:{}:{symbol}:{window}`                      |

⚠ That list is **observed, not exhaustive**, and no gate can make it so: a commit key is an
ordinary string argument, so proving the list complete would mean following every call in the
workspace. What is gated per listed entry is that the producer exists and spells the template
verbatim. Read it as "these producers write this kind", never as "only these do".

## Where this comes from [#where-this-comes-from]

`vike_data::store_kind::STORE_KINDS`, exported as `rosters.json` at every release. The store's
own gate derives the live kind set from the code — the series directory literals, the compaction
dispatch and the write verbs — and fails until a new kind has a row, so this page cannot describe
a shape the store does not write.


# chain (/docs/trader/concepts/data/chain)




`chain` is one of the shapes the historical store holds. A stored series lives under a
`kind=` path segment, and that segment is the layout contract its producers and its consumers
have to agree on: the columns, how the leaf is partitioned, and what `venue` and `symbol` mean
for this particular kind. All of it is below, rendered from the same table the runtime dispatches
on.

One decoded row becomes a `crate::chain_log::ChainRow`. The codec that owns the schema is `ChainCodec`; the
store writes through `append_chain_snapshot` and reads through `scan_chain`, and parts carry the Parquet metadata key `vike.schema.chain`.

## Identity [#identity]

**venue = the options venue; symbol = the UNDERLYING (and `underlying` is ALSO a row column). All rows of one snapshot share `ts`, so this kind is the only one where a single timestamp legitimately covers hundreds of rows**

This is the field most often assumed and most often wrong, which is why it is stated per kind
rather than once for the store.

## Columns [#columns]

Every Arrow column today's writer emits, in schema order, with the codec flavor that picks its
Arrow type and nullability.

| Column          | Flavor     | Note                                  |
| --------------- | ---------- | ------------------------------------- |
| `ts`            | `i64`      | —                                     |
| `underlying`    | `str`      | —                                     |
| `instrument`    | `str`      | —                                     |
| `expiry_ms`     | `i64`      | —                                     |
| `strike`        | `f64`      | —                                     |
| `is_call`       | `bool`     | —                                     |
| `bid`           | `f64_null` | always PRESENT, and may hold SQL NULL |
| `ask`           | `f64_null` | always PRESENT, and may hold SQL NULL |
| `mark`          | `f64_null` | always PRESENT, and may hold SQL NULL |
| `iv`            | `f64_null` | always PRESENT, and may hold SQL NULL |
| `open_interest` | `f64_null` | always PRESENT, and may hold SQL NULL |
| `volume`        | `f64_null` | always PRESENT, and may hold SQL NULL |
| `delta`         | `f64_null` | always PRESENT, and may hold SQL NULL |
| `gamma`         | `f64_null` | always PRESENT, and may hold SQL NULL |
| `theta`         | `f64_null` | always PRESENT, and may hold SQL NULL |
| `vega`          | `f64_null` | always PRESENT, and may hold SQL NULL |

## Layout [#layout]

| Property                      | Value                    |
| ----------------------------- | ------------------------ |
| Partitioning                  | `symbol`                 |
| Grouped form                  | no — one series per part |
| In the cross-kind tick report | no                       |

## Traps [#traps]

⚠ Volume warning, not a contradiction: at the recorder's default cadence one underlying is hundreds of rows per minute, so the unbounded point-in-time read `crate::HistStore`'s `chain_as_of` decodes every row ever recorded on each call. `chain_as_of_within` is the bounded twin and is what a backtest should use.

Pinned rather than fixed: the contradiction is recorded with both sides named, so a reader meets it here instead of in production.

## Known producers [#known-producers]

Idempotency in this store is batch-level and keyed on a commit-key string, never on per-row value
dedup. Two producers that collide on one template silently no-op each other's appends, and a
producer that changes its template re-admits history it already wrote — both invisible unless the
shapes are written side by side.

| Producer                            | Commit-key template                            |
| ----------------------------------- | ---------------------------------------------- |
| `crates/vike-data/src/chain_rec.rs` | `chain:{venue}:{underlying}:{expiry}:{bucket}` |

⚠ That list is **observed, not exhaustive**, and no gate can make it so: a commit key is an
ordinary string argument, so proving the list complete would mean following every call in the
workspace. What is gated per listed entry is that the producer exists and spells the template
verbatim. Read it as "these producers write this kind", never as "only these do".

## Where this comes from [#where-this-comes-from]

`vike_data::store_kind::STORE_KINDS`, exported as `rosters.json` at every release. The store's
own gate derives the live kind set from the code — the series directory literals, the compaction
dispatch and the write verbs — and fails until a new kind has a row, so this page cannot describe
a shape the store does not write.


# cohort (/docs/trader/concepts/data/cohort)




`cohort` is one of the shapes the historical store holds. A stored series lives under a
`kind=` path segment, and that segment is the layout contract its producers and its consumers
have to agree on: the columns, how the leaf is partitioned, and what `venue` and `symbol` mean
for this particular kind. All of it is below, rendered from the same table the runtime dispatches
on.

One decoded row becomes a `crate::cohort_log::CohortRow`. The codec that owns the schema is `CohortCodec`; the
store writes through `append_cohort` and reads through `scan_cohort`, and parts carry the Parquet metadata key `vike.schema.cohort`.

## Identity [#identity]

**venue = the EXCHANGE whose positions were graded (`hyperliquid`), never the metrics service that served the grading; symbol = the ASSET (`BTC`), which is ALSO the `asset` row column. Every other dimension — axis, label, grading, label basis — is a COLUMN and not a path segment, because one decode context string cannot re-inject five**

This is the field most often assumed and most often wrong, which is why it is stated per kind
rather than once for the store.

## Columns [#columns]

Every Arrow column today's writer emits, in schema order, with the codec flavor that picks its
Arrow type and nullability.

| Column        | Flavor | Note |
| ------------- | ------ | ---- |
| `ts`          | `i64`  | —    |
| `asset`       | `str`  | —    |
| `axis`        | `str`  | —    |
| `cohort`      | `str`  | —    |
| `grading`     | `str`  | —    |
| `label_basis` | `str`  | —    |
| `long_usd`    | `f64`  | —    |
| `total_usd`   | `f64`  | —    |

## Layout [#layout]

| Property                      | Value                    |
| ----------------------------- | ------------------------ |
| Partitioning                  | `symbol`                 |
| Grouped form                  | no — one series per part |
| In the cross-kind tick report | no                       |

## Traps [#traps]

⚠ A LONG ROW on purpose — the label taxonomy is DATA, not schema. `crates/vike-backfill/src/vikedata/parse.rs`'s `SIZE_COHORTS` (12), `PNL_COHORTS` (12), `PNL_UNRANKABLE` (2) and `TIER_COHORTS` (10) admit 36 labels between them, each carrying the two wire numbers this row stores: 73 columns at one grading, and 129 once the pnl ladder is graded three ways (`Grading`'s variants; the size and tier axes are ungraded), against a store whose widest kind — `chain` — has 16. `crates/vike-data/tests/store_kind_gate.rs`'s `every_row_matches_its_codec_field_list` compares \[`StoreKind::columns`] VERBATIM against the codec's field list, so a column-per-label schema would make every taxonomy revision — one new rung, one retired bucket — a SCHEMA MIGRATION. The long row keeps the label in the `cohort` column, so a taxonomy change writes rows rather than columns. ⚠ NOT grouped, and grouping is not the escape it looks like: `crates/vike-data/src/series.rs`'s `SeriesId` makes `symbol` and `group` ALTERNATIVES (exactly one is meaningful, and `symbol` is EMPTY when grouped), so a grouped form RELOCATES the symbol dimension rather than adding one. Spending it on the cohort label would leave the ASSET homeless — one read of `group=Whale` would merge every asset's rows under that label. ⚠ `grading` and `label_basis` are per-FETCH facts, and they are columns for the reason the other five dimensions are: the three gradings produce SHAPE-IDENTICAL rows over the same (venue, asset) series at the same `ts`, so without them a re-graded fetch silently ALIASES a realized one — the same batch of hours, overwriting nothing and distinguishable by nothing. The commit key carries both for the same reason; `crates/vike-data/src/cohort_rec.rs`'s `commit_key` is where that argument is made against the code that builds it. ⚠ NOT the same subject as `perp_metrics` below, despite both being called open interest in conversation: this kind is a GRADED POSITIONING panel from a metrics service (who is long, by cohort), while that one is the venue's own per-interval context for a perp. ⚠ ONE producer: `CohortRecorder` is the write-side entry point this series has, in the shape `ChainRecorder` and `PropertiesRecorder` already use, and `crates/vike-backfill/src/vikedata/ingest.rs`'s `backfill_cohort` is what feeds it — the `data.vike.io` cohort-metrics collector, behind vike-backfill's `vikedata` feature. ⚠ Its idempotency is therefore BATCH-level on the WINDOW, like every other collector here: re-running one command is a no-op, two OVERLAPPING windows are two keys and their shared hours land twice.

Pinned rather than fixed: the contradiction is recorded with both sides named, so a reader meets it here instead of in production.

## Known producers [#known-producers]

Idempotency in this store is batch-level and keyed on a commit-key string, never on per-row value
dedup. Two producers that collide on one template silently no-op each other's appends, and a
producer that changes its template re-admits history it already wrote — both invisible unless the
shapes are written side by side.

| Producer                             | Commit-key template                                                         |
| ------------------------------------ | --------------------------------------------------------------------------- |
| `crates/vike-data/src/cohort_rec.rs` | `cohort:{venue}:{asset}:{axis}:{grading}:{label_basis}:{start_ms}-{end_ms}` |

⚠ That list is **observed, not exhaustive**, and no gate can make it so: a commit key is an
ordinary string argument, so proving the list complete would mean following every call in the
workspace. What is gated per listed entry is that the producer exists and spells the template
verbatim. Read it as "these producers write this kind", never as "only these do".

## Where this comes from [#where-this-comes-from]

`vike_data::store_kind::STORE_KINDS`, exported as `rosters.json` at every release. The store's
own gate derives the live kind set from the code — the series directory literals, the compaction
dispatch and the write verbs — and fails until a new kind has a row, so this page cannot describe
a shape the store does not write.


# depth (/docs/trader/concepts/data/depth)




`depth` is one of the shapes the historical store holds. A stored series lives under a
`kind=` path segment, and that segment is the layout contract its producers and its consumers
have to agree on: the columns, how the leaf is partitioned, and what `venue` and `symbol` mean
for this particular kind. All of it is below, rendered from the same table the runtime dispatches
on.

One decoded row becomes a `BookRow (exploded from vike_model::BookUpdate — ONE ROW PER LEVEL)`. The codec that owns the schema is `BookCodec`; the
store writes through `append_depth` and reads through `scan_depth`, and parts carry the Parquet metadata key `vike.schema.book`.

## Identity [#identity]

**venue = the bridge venue id; symbol = the instrument. The CONFLATING L2 lane — a periodic full snapshot with every intermediate book state discarded. Same rows and same codec as `book`, a DIFFERENT series on purpose: the path IS the disclosure, so a consumer asking for `book` never receives conflated data**

This is the field most often assumed and most often wrong, which is why it is stated per kind
rather than once for the store.

## Columns [#columns]

Every Arrow column today's writer emits, in schema order, with the codec flavor that picks its
Arrow type and nullability.

| Column       | Flavor    | Note                                                                  |
| ------------ | --------- | --------------------------------------------------------------------- |
| `ts`         | `i64`     | —                                                                     |
| `local_ts`   | `i64`     | —                                                                     |
| `seq`        | `i64`     | —                                                                     |
| `kind`       | `i8`      | —                                                                     |
| `is_bid`     | `bool`    | —                                                                     |
| `price`      | `f64`     | —                                                                     |
| `size`       | `f64`     | —                                                                     |
| `tick_size`  | `f64`     | —                                                                     |
| `symbol_col` | `str_add` | may be ABSENT ENTIRELY from a part sealed before the column was added |

## Layout [#layout]

| Property                      | Value                    |
| ----------------------------- | ------------------------ |
| Partitioning                  | `symbol`                 |
| Grouped form                  | no — one series per part |
| In the cross-kind tick report | yes                      |

## Traps [#traps]

⚠ CONTRADICTION, pinned: `crates/vike-backfill/src/regroup.rs`'s `GROUPABLE_KINDS` lists `depth` as having a grouped form, and the store does not have one. There is no `append_depth_grouped`; `crates/vike-data/src/live_rec.rs`'s `DEPTH` carries `append_grouped: None`; and `crates/vike-data/src/datafusion_hist.rs`'s `migrate_series_to_group` has no `depth` arm, so a planned fold reaches its catch-all and fails with `has no grouped form`. The consequence is a `migrate_to_group` dry run printing a depth plan that a real run cannot execute (it reports FAILED and leaves the source in place — no data loss). ⚠ Both halves of this kind's seam REFUSE by default: `append_depth` always has, and `scan_depth` joined it once its empty `Ok` was read as the fabricated "no data" it was. ⚠ And no backfill source serves this kind at all — `crates/vike-backfill/src/caps.rs`'s `PLANNABLE_KINDS` deliberately omits it, so a depth gap can only ever be re-recorded live. ⚠ The §B stream-health markers (`GapStart`/`Stale`/`LiveResume`) ride THIS lane too since 2026-09-10, as the same zero-level `seq: 0` placeholder rows the `book` row describes. They did not until then, and their absence is why a forty-day binance perp reconnect loop left a series that reads 40/40 days complete — this lane needs them MORE than `book` does, not less: `book` is a lossless chain a reader can audit for itself, while a hole in a conflating snapshot lane is invisible by construction.

Pinned rather than fixed: the contradiction is recorded with both sides named, so a reader meets it here instead of in production.

## Known producers [#known-producers]

Idempotency in this store is batch-level and keyed on a commit-key string, never on per-row value
dedup. Two producers that collide on one template silently no-op each other's appends, and a
producer that changes its template re-admits history it already wrote — both invisible unless the
shapes are written side by side.

| Producer                           | Commit-key template                                   |
| ---------------------------------- | ----------------------------------------------------- |
| `crates/vike-data/src/live_rec.rs` | `live-{venue}-{symbol}-{}-{first_ts}-{last_ts}-{seq}` |

⚠ That list is **observed, not exhaustive**, and no gate can make it so: a commit key is an
ordinary string argument, so proving the list complete would mean following every call in the
workspace. What is gated per listed entry is that the producer exists and spells the template
verbatim. Read it as "these producers write this kind", never as "only these do".

## Where this comes from [#where-this-comes-from]

`vike_data::store_kind::STORE_KINDS`, exported as `rosters.json` at every release. The store's
own gate derives the live kind set from the code — the series directory literals, the compaction
dispatch and the write verbs — and fails until a new kind has a row, so this page cannot describe
a shape the store does not write.


# equity (/docs/trader/concepts/data/equity)




`equity` is one of the shapes the historical store holds. A stored series lives under a
`kind=` path segment, and that segment is the layout contract its producers and its consumers
have to agree on: the columns, how the leaf is partitioned, and what `venue` and `symbol` mean
for this particular kind. All of it is below, rendered from the same table the runtime dispatches
on.

One decoded row becomes a `vike_model::EquitySample`. The codec that owns the schema is `EquityCodec`; the
store writes through `append_equity` and reads through `scan_equity`, and parts carry the Parquet metadata key `vike.schema.equity`.

## Identity [#identity]

**⚠ NEITHER field means what it says. `venue` is the fixed namespace string `portfolio`, and `symbol` carries the per-exchange venue name or the cross-venue `TOTAL` rollup — the scan's `symbol` argument is what the decoder re-injects as `EquitySample::venue`**

This is the field most often assumed and most often wrong, which is why it is stated per kind
rather than once for the store.

## Columns [#columns]

Every Arrow column today's writer emits, in schema order, with the codec flavor that picks its
Arrow type and nullability.

| Column           | Flavor | Note |
| ---------------- | ------ | ---- |
| `ts`             | `i64`  | —    |
| `equity`         | `f64`  | —    |
| `realized`       | `f64`  | —    |
| `unrealized`     | `f64`  | —    |
| `missing_prices` | `i64`  | —    |

## Layout [#layout]

| Property                      | Value                    |
| ----------------------------- | ------------------------ |
| Partitioning                  | `symbol`                 |
| Grouped form                  | no — one series per part |
| In the cross-kind tick report | no                       |

## Traps [#traps]

A consumer that iterates `list_series()` and treats `SeriesId::venue` as a venue sees a venue called `portfolio` holding instruments called `binance`, `okx` and `TOTAL`. That is the layout, not a bug — but it is why an inventory view must key display off the kind before the venue.

Pinned rather than fixed: the contradiction is recorded with both sides named, so a reader meets it here instead of in production.

## Known producers [#known-producers]

Idempotency in this store is batch-level and keyed on a commit-key string, never on per-row value
dedup. Two producers that collide on one template silently no-op each other's appends, and a
producer that changes its template re-admits history it already wrote — both invisible unless the
shapes are written side by side.

| Producer                           | Commit-key template                                   |
| ---------------------------------- | ----------------------------------------------------- |
| `crates/vike-data/src/live_rec.rs` | `live-{venue}-{symbol}-{}-{first_ts}-{last_ts}-{seq}` |

⚠ That list is **observed, not exhaustive**, and no gate can make it so: a commit key is an
ordinary string argument, so proving the list complete would mean following every call in the
workspace. What is gated per listed entry is that the producer exists and spells the template
verbatim. Read it as "these producers write this kind", never as "only these do".

## Where this comes from [#where-this-comes-from]

`vike_data::store_kind::STORE_KINDS`, exported as `rosters.json` at every release. The store's
own gate derives the live kind set from the code — the series directory literals, the compaction
dispatch and the write verbs — and fails until a new kind has a row, so this page cannot describe
a shape the store does not write.


# exec_fill (/docs/trader/concepts/data/exec-fill)




`exec_fill` is one of the shapes the historical store holds. A stored series lives under a
`kind=` path segment, and that segment is the layout contract its producers and its consumers
have to agree on: the columns, how the leaf is partitioned, and what `venue` and `symbol` mean
for this particular kind. All of it is below, rendered from the same table the runtime dispatches
on.

One decoded row becomes a `crate::exec_log::ExecFillRow`. The codec that owns the schema is `ExecFillCodec`; the
store writes through `append_exec_fills` and reads through `scan_exec_fills`.

## Identity [#identity]

**venue/symbol are the account's execution venue and instrument — and are ALSO stored as row COLUMNS, because one decode context string cannot re-inject two values. Nothing checks the path and the columns agree**

This is the field most often assumed and most often wrong, which is why it is stated per kind
rather than once for the store.

## Columns [#columns]

Every Arrow column today's writer emits, in schema order, with the codec flavor that picks its
Arrow type and nullability.

| Column             | Flavor    | Note                                                                  |
| ------------------ | --------- | --------------------------------------------------------------------- |
| `ts`               | `i64`     | —                                                                     |
| `trade_id`         | `str`     | —                                                                     |
| `client_order_id`  | `str`     | —                                                                     |
| `venue`            | `str`     | —                                                                     |
| `symbol`           | `str`     | —                                                                     |
| `side`             | `i64`     | —                                                                     |
| `qty`              | `f64`     | —                                                                     |
| `px`               | `f64`     | —                                                                     |
| `commission`       | `f64`     | —                                                                     |
| `mark_price`       | `f64_add` | may be ABSENT ENTIRELY from a part sealed before the column was added |
| `liquidity_side`   | `str_add` | may be ABSENT ENTIRELY from a part sealed before the column was added |
| `commission_asset` | `str_add` | may be ABSENT ENTIRELY from a part sealed before the column was added |

## Layout [#layout]

| Property                      | Value                    |
| ----------------------------- | ------------------------ |
| Partitioning                  | `symbol`                 |
| Grouped form                  | no — one series per part |
| In the cross-kind tick report | no                       |

## Traps [#traps]

The ACCOUNT fill log, NOT market prints — a distinct kind from `trade` precisely so the two never collide on one (venue, symbol). `scan_exec_fills` takes no `TsRange`: it and `scan_exec_orders` are the only two members of the `scan_*`/`load_*` SERIES-READ family that do not (every other one takes a range — `crates/vike-data/tests/store_kind_gate.rs`'s `only_the_exec_reads_take_no_range` is the gate), so a caller wanting a window filters after the scan. ⚠ That is a claim about the series-read family and NOT about the seam: the point-in-time and inventory verbs `properties_as_of`, `chain_as_of`, `list_series`, `inventory` and `series_gaps` take no range either, and for `chain_as_of` that is the unbounded-read trap the `chain` row warns about.

Pinned rather than fixed: the contradiction is recorded with both sides named, so a reader meets it here instead of in production.

## Known producers [#known-producers]

Idempotency in this store is batch-level and keyed on a commit-key string, never on per-row value
dedup. Two producers that collide on one template silently no-op each other's appends, and a
producer that changes its template re-admits history it already wrote — both invisible unless the
shapes are written side by side.

| Producer                                              | Commit-key template                           |
| ----------------------------------------------------- | --------------------------------------------- |
| `crates/vike-ops/src/journal_mat.rs`                  | `mat-fill-{venue}-{symbol}-{after}-{max_seq}` |
| `crates/vike-backfill/src/bin/exec_trade_backfill.rs` | `import-{venue}-{symbol}-{first}-{last}`      |

⚠ That list is **observed, not exhaustive**, and no gate can make it so: a commit key is an
ordinary string argument, so proving the list complete would mean following every call in the
workspace. What is gated per listed entry is that the producer exists and spells the template
verbatim. Read it as "these producers write this kind", never as "only these do".

## Where this comes from [#where-this-comes-from]

`vike_data::store_kind::STORE_KINDS`, exported as `rosters.json` at every release. The store's
own gate derives the live kind set from the code — the series directory literals, the compaction
dispatch and the write verbs — and fails until a new kind has a row, so this page cannot describe
a shape the store does not write.


# exec_funding (/docs/trader/concepts/data/exec-funding)




`exec_funding` is one of the shapes the historical store holds. A stored series lives under a
`kind=` path segment, and that segment is the layout contract its producers and its consumers
have to agree on: the columns, how the leaf is partitioned, and what `venue` and `symbol` mean
for this particular kind. All of it is below, rendered from the same table the runtime dispatches
on.

One decoded row becomes a `crate::funding_log::FundingRow`. The codec that owns the schema is `FundingCodec`; the
store writes through `append_funding` and reads through `scan_funding`.

## Identity [#identity]

**venue = the perp venue; symbol = the venue COIN (`BTC`, not `BTCUSDT`), which is why this series never collides with that symbol's public prints**

This is the field most often assumed and most often wrong, which is why it is stated per kind
rather than once for the store.

## Columns [#columns]

Every Arrow column today's writer emits, in schema order, with the codec flavor that picks its
Arrow type and nullability.

| Column         | Flavor | Note |
| -------------- | ------ | ---- |
| `ts`           | `i64`  | —    |
| `account`      | `str`  | —    |
| `usdc`         | `f64`  | —    |
| `szi`          | `f64`  | —    |
| `funding_rate` | `f64`  | —    |
| `hash`         | `str`  | —    |

## Layout [#layout]

| Property                      | Value                    |
| ----------------------------- | ------------------------ |
| Partitioning                  | `symbol`                 |
| Grouped form                  | no — one series per part |
| In the cross-kind tick report | no                       |

## Traps [#traps]

The ACCOUNT's REALIZED funding — what this account actually paid or received. ⚠ The NAME COLLISION this row used to carry is RESOLVED by decision 0080: the bare word `funding` sat on this, the SPECIALISED case, while the MARKET funding-RATE history lives in the `bar` row above under `interval=funding`. The account plane's prefix now does the work, so `exec_fill`/`exec_order`/`exec_funding` share one and a reader can see which side a kind is on. The market rate was deliberately NOT renamed — `interval` is part of `SeriesId` and bar series exist, so that migration is not free. ⚠ The partition key is (venue, coin) and the account is NOT in it; the ACCOUNT COLUMN is what makes two accounts' payments for one coin separable, because `hash` is the venue TRANSACTION hash and names no account — before that column a main account's -1200 and a test account's -30 read back as -1230, unsubtractable. Whether to ALSO partition per account is left open by 0079 and is now a convenience question. ⚠ `hist rm` REFUSES this kind by name, as it does every account kind, because it deletes by SERIES and one series holds both accounts. ⚠ The trait default no longer lies: `append_funding`/`scan_funding` return `DataError::Unsupported` rather than `Ok(0)`/`Ok(vec![])`, so a store that cannot hold this kind says so instead of reporting a successful write of nothing.

Pinned rather than fixed: the contradiction is recorded with both sides named, so a reader meets it here instead of in production.

## Known producers [#known-producers]

Idempotency in this store is batch-level and keyed on a commit-key string, never on per-row value
dedup. Two producers that collide on one template silently no-op each other's appends, and a
producer that changes its template re-admits history it already wrote — both invisible unless the
shapes are written side by side.

| Producer                                  | Commit-key template                                         |
| ----------------------------------------- | ----------------------------------------------------------- |
| `crates/vike-backfill/src/hyperliquid.rs` | `{VENUE}:exec_funding:{account}:{coin}:{start_ms}-{end_ms}` |

⚠ That list is **observed, not exhaustive**, and no gate can make it so: a commit key is an
ordinary string argument, so proving the list complete would mean following every call in the
workspace. What is gated per listed entry is that the producer exists and spells the template
verbatim. Read it as "these producers write this kind", never as "only these do".

## Where this comes from [#where-this-comes-from]

`vike_data::store_kind::STORE_KINDS`, exported as `rosters.json` at every release. The store's
own gate derives the live kind set from the code — the series directory literals, the compaction
dispatch and the write verbs — and fails until a new kind has a row, so this page cannot describe
a shape the store does not write.


# exec_order (/docs/trader/concepts/data/exec-order)




`exec_order` is one of the shapes the historical store holds. A stored series lives under a
`kind=` path segment, and that segment is the layout contract its producers and its consumers
have to agree on: the columns, how the leaf is partitioned, and what `venue` and `symbol` mean
for this particular kind. All of it is below, rendered from the same table the runtime dispatches
on.

One decoded row becomes a `crate::exec_log::ExecOrderRow`. The codec that owns the schema is `ExecOrderCodec`; the
store writes through `append_exec_orders` and reads through `scan_exec_orders`.

## Identity [#identity]

**venue/symbol as for `exec_fill`, duplicated into row columns the same way. Rows are order LIFECYCLE SNAPSHOTS, so one `client_order_id` appears many times with different `status`**

This is the field most often assumed and most often wrong, which is why it is stated per kind
rather than once for the store.

## Columns [#columns]

Every Arrow column today's writer emits, in schema order, with the codec flavor that picks its
Arrow type and nullability.

| Column            | Flavor     | Note                                  |
| ----------------- | ---------- | ------------------------------------- |
| `ts`              | `i64`      | —                                     |
| `client_order_id` | `str`      | —                                     |
| `venue`           | `str`      | —                                     |
| `symbol`          | `str`      | —                                     |
| `side`            | `i64`      | —                                     |
| `qty`             | `f64`      | —                                     |
| `order_type`      | `str`      | —                                     |
| `status`          | `str`      | —                                     |
| `price`           | `f64_null` | always PRESENT, and may hold SQL NULL |
| `trigger_price`   | `f64_null` | always PRESENT, and may hold SQL NULL |
| `venue_order_id`  | `str_null` | always PRESENT, and may hold SQL NULL |
| `filled_qty`      | `f64`      | —                                     |
| `avg_fill_px`     | `f64`      | —                                     |

## Layout [#layout]

| Property                      | Value                    |
| ----------------------------- | ------------------------ |
| Partitioning                  | `symbol`                 |
| Grouped form                  | no — one series per part |
| In the cross-kind tick report | no                       |

## Traps [#traps]

`price`/`trigger_price`/`venue_order_id` are `_null`, not `_add`: the columns are always PRESENT and a NULL means the order genuinely had no such value (a market order has no price). Reading them as absent-tolerant would conflate 'the venue never told us' with 'an older part'.

Pinned rather than fixed: the contradiction is recorded with both sides named, so a reader meets it here instead of in production.

## Known producers [#known-producers]

Idempotency in this store is batch-level and keyed on a commit-key string, never on per-row value
dedup. Two producers that collide on one template silently no-op each other's appends, and a
producer that changes its template re-admits history it already wrote — both invisible unless the
shapes are written side by side.

| Producer                             | Commit-key template                            |
| ------------------------------------ | ---------------------------------------------- |
| `crates/vike-ops/src/journal_mat.rs` | `mat-order-{venue}-{symbol}-{after}-{max_seq}` |

⚠ That list is **observed, not exhaustive**, and no gate can make it so: a commit key is an
ordinary string argument, so proving the list complete would mean following every call in the
workspace. What is gated per listed entry is that the producer exists and spells the template
verbatim. Read it as "these producers write this kind", never as "only these do".

## Where this comes from [#where-this-comes-from]

`vike_data::store_kind::STORE_KINDS`, exported as `rosters.json` at every release. The store's
own gate derives the live kind set from the code — the series directory literals, the compaction
dispatch and the write verbs — and fails until a new kind has a row, so this page cannot describe
a shape the store does not write.


# Store kinds (/docs/trader/concepts/data)



Everything Vike Trader keeps on disk as history lives under a store root in a `kind=` path segment,
and that segment is a contract between two ends that never meet: the live recorder, the property
and chain recorders, the backfill collectors and the journal materializer on one side; tick replay,
the reads a data node serves, and the Data Manager and Studio inventory views on the other.
`crates/vike-data/src/store_kind.rs`'s `STORE_KINDS` is where that contract is written down — one
row per stored kind, thirteen of them today, each with its own page here. That producer list is
illustrative and not a census: a producer is anything holding a `HistStore`, so the header declines
to claim any list can be complete.

Until that file existed, **no site named the contract**, and its header records what that cost.
`crates/vike-data/src/coverage.rs`'s `TICK_KINDS` was missing `depth`, so a whole kind was invisible
to the cross-kind coverage report while its rows sat on disk. Five Data Manager verbs built their
path from `SeriesId::symbol`, which is empty for a grouped series, so each silently operated on a
series that does not exist — delete was a no-op that returned `Ok(())`.

## What a row declares [#what-a-row-declares]

One `StoreKind` names the domain type a decoded row becomes, every Arrow column today's writer
emits in schema order with the `series_codec!` flavor that picks its type and nullability, the
Parquet schema-metadata key the kind stamps when it stamps one, how the leaf is partitioned,
whether a grouped form exists, what `venue` and `symbol` actually mean for that kind, and the
commit-key shapes its known producers use.

Two column flavors bite a consumer. A `_null` column is always present and may hold SQL NULL; an
`_add` column may be **absent entirely** from a part sealed before it was added, because the `_add`
flavors read through an absent-tolerant column reader. A kind's columns are what *today's* writer
emits, so nothing may assume an `_add` column is present in an old part.

## Partitioning, stated once [#partitioning-stated-once]

Parts are `date=`-partitioned identically for every kind — `<series leaf>/date=YYYY-MM-DD/` — so no
per-kind page repeats it. What the partition guarantees is that a part never spans a UTC day:
`crates/vike-data/src/datafusion_hist/manifest.rs`'s `seal_into_manifest` groups a batch's rows by
day and seals one part per group.

<Callout type="warn" title="A date partition holds many parts, not one">
  A writer seals one part per commit, so the live recorder — committing per buffer flush — produces
  one every few seconds, and compaction merges them into `part-c…` outputs alongside. Measured
  read-only on the live production tape:
  `kind=book/venue=polymarket/group=btc-updown-5m/date=2026-08-08` held 103 parquet files and
  `date=2026-08-07` held 130. `manifest.rs`'s `next_part_name` is the authority — a per-date index,
  one above the highest still live, a counter precisely because there are many. A consumer that
  builds a reader for one-file-per-day mishandles the real 130-file case.
</Callout>

Below the shared `kind=…/venue=…` prefix the leaf has two spellings. The per-symbol form is
`symbol=…`, and `bar` alone adds `interval=…` beneath it so a `1m` and a `1d` series of one
instrument never interleave — the table's only `Partition::SymbolInterval` row. The grouped form is
`kind=…/venue=…/group=…`, written by `DataFusionHist`'s `group_dir`, where one part holds many
symbols told apart by the row-level `symbol_col` column. The two are siblings under one parent and
a store can hold both at once, so anything building or parsing a path must **branch on `group`
first** — `series_dir_of` is the one function that does it correctly, and the five verbs that did
not are the incident above. In the same vein, `SeriesId::symbol` is empty for a grouped series,
`SeriesId::group` carries the name, and `SeriesId::label` answers for both.

## Declare today's reality; pin the contradictions [#declare-todays-reality-pin-the-contradictions]

The table is step one of the workspace's two-step playbook for a capability table: it merged
byte-identical in behaviour and writes down what the code does today, **including where two sites
disagree**. Each disagreement is named in a row's `notes` with both sides cited, and a test asserts
it still exists, so whoever resolves one is told to update the table rather than leave a stale
warning behind. Two rows carry such a note today. The `depth` row's is labelled a pinned
contradiction: `crates/vike-backfill/src/regroup.rs`'s `GROUPABLE_KINDS` lists
[`depth`](/docs/trader/concepts/data/depth) as having a grouped form and the store has none. The
`funding` row's is labelled a pinned name collision — two unrelated series are called funding:
`kind=funding` is the account's realized payments, while the market funding-*rate* history is a
`bar` series under the reserved `interval=funding` label, carrying the rate on `Bar::funding` with
OHLCV and volume all zero.

The gate's pinned section holds four tests, not two. The other pair pins no row disagreement:
`both_depth_defaults_refuse` and `both_catalog_defaults_refuse` hold `append_depth`/`scan_depth`,
and `list_series`/`inventory`, to an `Err` rather than a fabricated empty read.

This is deliberately **not** schema versioning. `crates/vike-data/src/store_kind.rs`'s header is
emphatic about the difference and says versioning must stay deferred: a row records a metadata key a kind already writes, and introduces no version
negotiation, no migration and no new on-disk byte.

## The gate [#the-gate]

`crates/vike-data/tests/store_kind_gate.rs` derives the live kind set from the code and fails until
a row exists — three independent derivations, because each is blind to a different mistake: the
`kind=` segments the store actually writes, read off the first argument of every
`series_dir`/`ticks_dir`/`group_dir` call in the backend module tree; the strings each compaction
dispatch accepts, **each dispatch checked on its own**; and the `fn append_*` verbs on the
always-compiled `HistStore` trait, which reddens first when a kind is added the ordinary way. Shape
is gated separately, by parsing the `series_codec!` invocations and comparing each row's columns and
schema-metadata key against the field list they were read from. Every check reads source text on
purpose — the codecs sit behind the `hist-datafusion` feature while the test runs in the default
lane, and `regroup.rs` is in a crate `vike-data` cannot depend on.

Two residuals are declared, and the declaration is the point. Dataflow is not followed, and that is
measured: a `SeriesId` with `kind: "oracle"` handed to the declared `series_dir_of` site builds a
`kind=oracle` directory with no compaction arm and no append verb while the gate stays at 25 passed,
0 failed. And the scope is this crate's `src` — another crate holding a store root can build a
directory with a plain join, and a store written by a newer build already holds kinds no source
here mentions.

## The thirteen kinds [#the-thirteen-kinds]

Four line up in the cross-kind coverage report — `TICK_KINDS` is `trade`, `quote`, `book` and
`depth`. Three kind ids carry underscores on disk (`exec_fill`, `exec_order`, `perp_metrics`) where
their page slugs use hyphens. Most seam verbs state their own default on the trait method; the one
pair worth carrying here is `depth`, where **both** `append_depth` and `scan_depth` return an `Err`
in a store that does not implement them, because a store with no depth *lane* and a store with no
depth *rows* must not read identically to a caller.

[bar](/docs/trader/concepts/data/bar) · [quote](/docs/trader/concepts/data/quote) ·
[trade](/docs/trader/concepts/data/trade) · [book](/docs/trader/concepts/data/book) ·
[depth](/docs/trader/concepts/data/depth) · [properties](/docs/trader/concepts/data/properties) ·
[equity](/docs/trader/concepts/data/equity) · [exec-fill](/docs/trader/concepts/data/exec-fill) ·
[exec-order](/docs/trader/concepts/data/exec-order) · [funding](/docs/trader/concepts/data/funding) ·
[chain](/docs/trader/concepts/data/chain) · [cohort](/docs/trader/concepts/data/cohort) ·
[perp-metrics](/docs/trader/concepts/data/perp-metrics)

The seam itself, and where a store root resolves when nobody says, are on
[The history store](/docs/trader/concepts/hist-store); its live mirror is
[the live data seam](/docs/trader/concepts/live-data-seam). What fills a store is
[data providers](/docs/trader/data-providers) and
[store maintenance](/docs/trader/data-providers/store-maintenance); what reads it back is
[tick replay](/docs/trader/backtesting/tick-replay) and the Data Manager's
[coverage view](/docs/trader/gui/data-manager/coverage).


# perp_metrics (/docs/trader/concepts/data/perp-metrics)




`perp_metrics` is one of the shapes the historical store holds. A stored series lives under a
`kind=` path segment, and that segment is the layout contract its producers and its consumers
have to agree on: the columns, how the leaf is partitioned, and what `venue` and `symbol` mean
for this particular kind. All of it is below, rendered from the same table the runtime dispatches
on.

One decoded row becomes a `crate::perp_metrics_log::PerpMetricRow`. The codec that owns the schema is `PerpMetricsCodec`; the
store writes through `append_perp_metrics` and reads through `scan_perp_metrics`, and parts carry the Parquet metadata key `vike.schema.perp_metrics`.

## Identity [#identity]

**venue = the perp venue; symbol = the SAME store symbol the market funding-rate series uses for that perp, so the two align by `ts` without a translation step — `crates/vike-backfill/src/funding_rate.rs`'s `backfill_funding_rate` writes both from one response and passes its `symbol` argument to each**

This is the field most often assumed and most often wrong, which is why it is stated per kind
rather than once for the store.

## Columns [#columns]

Every Arrow column today's writer emits, in schema order, with the codec flavor that picks its
Arrow type and nullability.

| Column          | Flavor    | Note                                                                  |
| --------------- | --------- | --------------------------------------------------------------------- |
| `ts`            | `i64`     | —                                                                     |
| `premium`       | `f64`     | —                                                                     |
| `open_interest` | `f64_add` | may be ABSENT ENTIRELY from a part sealed before the column was added |

## Layout [#layout]

| Property                      | Value                    |
| ----------------------------- | ------------------------ |
| Partitioning                  | `symbol`                 |
| Grouped form                  | no — one series per part |
| In the cross-kind tick report | no                       |

## Traps [#traps]

⚠ THE NARROWEST KIND IN THE STORE — one timestamp, one number — and both of the numbers a reader expects beside it are missing on purpose. ⚠ The market funding RATE is NOT here: it rides `vike_model::Bar::funding` in the `bar` row above, under the reserved `interval=funding` label, and the premium and the rate arrive in the SAME Hyperliquid `fundingHistory` row at the same `ts`. Storing the rate here too would give one number two homes that can disagree, which is a worse version of the name collision the `funding` row already pins. ⚠ `open_interest` JOINED as the additive column this note always promised: the revisit condition was A SOURCE, and one arrived — `data.vike.io`'s `/v1/hyperliquid/assets/hourly` panel serves hourly OI history from its own HL node. The paragraph below KEEPS its facts because they still hold for the VENUE'S OWN surface — which is why the column is nullable and only the panel collector fills it. Hyperliquid publishes open interest only as a CURRENT snapshot — the `POST /info \{"type":"metaAndAssetCtxs"}` body and the `activeAssetCtx` websocket channel — and its `/info` surface has no historical open-interest verb, so no backfill can reconstruct a past value at any granularity. BINANCE is the opposite case and the note exists so nobody re-derives it: its keyless REST `GET /futures/data/openInterestHist` holds only \~30 rolling days (a `startTime` 31 days back is refused with `code -1130`, measured), but its public archive at `data.binance.vision` publishes a `metrics` dataset carrying `sum_open_interest`/`sum_open_interest_value` at FIVE-MINUTE cadence back to 2020-09-01 for BTCUSDT — free, keyless, and read by nothing in this workspace today. That is a different VENUE's open interest, so it is not a drop-in for a Hyperliquid study; it is a live option rather than a dead end. This row is shaped so either could later join as a COLUMN rather than as a second kind: an added `open_interest` takes an `_add` flavor, whose absent-column tolerance is what lets it read the parts written today. ⚠ Identity is the PATH only — no column repeats `venue` or `symbol`, unlike `cohort` and `chain`, because this row carries no further dimension that has to be stored anyway (the `funding` row's shape, not theirs).

Pinned rather than fixed: the contradiction is recorded with both sides named, so a reader meets it here instead of in production.

## Known producers [#known-producers]

Idempotency in this store is batch-level and keyed on a commit-key string, never on per-row value
dedup. Two producers that collide on one template silently no-op each other's appends, and a
producer that changes its template re-admits history it already wrote — both invisible unless the
shapes are written side by side.

| Producer                                     | Commit-key template                                     |
| -------------------------------------------- | ------------------------------------------------------- |
| `crates/vike-backfill/src/funding_rate.rs`   | `perp_metrics:{venue}:{symbol}:{start_ms}-{end_ms}`     |
| `crates/vike-backfill/src/vikedata/panel.rs` | `perp_panel:{exchange}:{asset}:{start_secs}-{end_secs}` |

⚠ That list is **observed, not exhaustive**, and no gate can make it so: a commit key is an
ordinary string argument, so proving the list complete would mean following every call in the
workspace. What is gated per listed entry is that the producer exists and spells the template
verbatim. Read it as "these producers write this kind", never as "only these do".

## Where this comes from [#where-this-comes-from]

`vike_data::store_kind::STORE_KINDS`, exported as `rosters.json` at every release. The store's
own gate derives the live kind set from the code — the series directory literals, the compaction
dispatch and the write verbs — and fails until a new kind has a row, so this page cannot describe
a shape the store does not write.


# properties (/docs/trader/concepts/data/properties)




`properties` is one of the shapes the historical store holds. A stored series lives under a
`kind=` path segment, and that segment is the layout contract its producers and its consumers
have to agree on: the columns, how the leaf is partitioned, and what `venue` and `symbol` mean
for this particular kind. All of it is below, rendered from the same table the runtime dispatches
on.

One decoded row becomes a `(i64, vike_model::SymbolProperties)`. The codec that owns the schema is `PropertiesCodec`; the
store writes through `append_symbol_properties` and reads through `scan_symbol_properties`, and parts carry the Parquet metadata key `vike.schema.properties`.

## Identity [#identity]

**venue = the bridge venue id; symbol = the instrument. Point-in-time, \~one row per symbol per UTC day — the observed instrument GRID over time, not a tape**

This is the field most often assumed and most often wrong, which is why it is stated per kind
rather than once for the store.

## Columns [#columns]

Every Arrow column today's writer emits, in schema order, with the codec flavor that picks its
Arrow type and nullability.

| Column          | Flavor         | Note                                                                  |
| --------------- | -------------- | --------------------------------------------------------------------- |
| `ts`            | `i64`          | —                                                                     |
| `tick_size`     | `f64`          | —                                                                     |
| `step_size`     | `f64`          | —                                                                     |
| `min_qty`       | `f64`          | —                                                                     |
| `max_qty`       | `f64`          | —                                                                     |
| `min_notional`  | `f64`          | —                                                                     |
| `contract_size` | `f64_add`      | may be ABSENT ENTIRELY from a part sealed before the column was added |
| `taker_hold_ms` | `i64_add_null` | always PRESENT, and may hold SQL NULL                                 |
| `tick_scheme`   | `str_add_null` | always PRESENT, and may hold SQL NULL                                 |
| `asset_class`   | `str_add_null` | always PRESENT, and may hold SQL NULL                                 |

## Layout [#layout]

| Property                      | Value                    |
| ----------------------------- | ------------------------ |
| Partitioning                  | `symbol`                 |
| Grouped form                  | no — one series per part |
| In the cross-kind tick report | no                       |

## Traps [#traps]

⚠ A `SymbolProperties` field with no column here is SILENTLY DROPPED on every store round-trip — no error, just loss. `contract_size`, `taker_hold_ms`, `tick_scheme` and `asset_class` are each an additive column added to close exactly that hole, so adding a field to the model without adding its column here is the trap, not the exception. ⚠ `asset_class` is the one column here whose cell is a WORD off a closed vocabulary (`vike_model::AssetClass::sql_word`) rather than a number or a JSON blob: an unrecognised word makes the row REFUSE to decode rather than degrading to unclassified, so renaming a variant is a tape-compatibility decision, not a rename. ⚠ Its producer's commit key carries NO namespace prefix (`\{venue}:\{symbol}:\{date}`), so it matches the `bar` row's klines window key (`\{venue}:\{symbol}:\{interval}:\{start_ms}-\{end_ms}`) segment-for-segment up to the third — harmless only because the two never write the same series. This note used to say those were the only TWO such templates in this table; they are not, and \[`PREFIXLESS_TEMPLATES`] is the gated roster that found the others. No count is written here on purpose.

Pinned rather than fixed: the contradiction is recorded with both sides named, so a reader meets it here instead of in production.

## Known producers [#known-producers]

Idempotency in this store is batch-level and keyed on a commit-key string, never on per-row value
dedup. Two producers that collide on one template silently no-op each other's appends, and a
producer that changes its template re-admits history it already wrote — both invisible unless the
shapes are written side by side.

| Producer                                 | Commit-key template       |
| ---------------------------------------- | ------------------------- |
| `crates/vike-data/src/properties_rec.rs` | `{venue}:{symbol}:{date}` |

⚠ That list is **observed, not exhaustive**, and no gate can make it so: a commit key is an
ordinary string argument, so proving the list complete would mean following every call in the
workspace. What is gated per listed entry is that the producer exists and spells the template
verbatim. Read it as "these producers write this kind", never as "only these do".

## Where this comes from [#where-this-comes-from]

`vike_data::store_kind::STORE_KINDS`, exported as `rosters.json` at every release. The store's
own gate derives the live kind set from the code — the series directory literals, the compaction
dispatch and the write verbs — and fails until a new kind has a row, so this page cannot describe
a shape the store does not write.


# quote (/docs/trader/concepts/data/quote)




`quote` is one of the shapes the historical store holds. A stored series lives under a
`kind=` path segment, and that segment is the layout contract its producers and its consumers
have to agree on: the columns, how the leaf is partitioned, and what `venue` and `symbol` mean
for this particular kind. All of it is below, rendered from the same table the runtime dispatches
on.

One decoded row becomes a `vike_model::QuoteTick`. The codec that owns the schema is `QuoteCodec`; the
store writes through `append_quotes` and reads through `scan_quotes`.

## Identity [#identity]

**venue = the bridge venue id; symbol = the instrument, or EMPTY on a row that the per-symbol path tags on read — which is exactly why a GROUPED append rejects an empty symbol**

This is the field most often assumed and most often wrong, which is why it is stated per kind
rather than once for the store.

## Columns [#columns]

Every Arrow column today's writer emits, in schema order, with the codec flavor that picks its
Arrow type and nullability.

| Column       | Flavor    | Note                                                                  |
| ------------ | --------- | --------------------------------------------------------------------- |
| `ts`         | `i64`     | —                                                                     |
| `bid`        | `f64`     | —                                                                     |
| `ask`        | `f64`     | —                                                                     |
| `bid_size`   | `f64`     | —                                                                     |
| `ask_size`   | `f64`     | —                                                                     |
| `local_ts`   | `i64_add` | may be ABSENT ENTIRELY from a part sealed before the column was added |
| `symbol_col` | `str_add` | may be ABSENT ENTIRELY from a part sealed before the column was added |

## Layout [#layout]

| Property                      | Value                                                                   |
| ----------------------------- | ----------------------------------------------------------------------- |
| Partitioning                  | `symbol`                                                                |
| Grouped form                  | yes — many symbols in one part, told apart by a row-level symbol column |
| In the cross-kind tick report | yes                                                                     |

## Traps [#traps]

⚠ NO clickhouse producer writes this kind any more — both are deleted (spot 2026-09-19, poly 2026-09-20: data is fetched by API or from the venue, never by reaching ClickHouse) — and the RULE they left behind is what this note is for: a `clickhouse:` producer had to pick a second segment no sibling used, because the namespace is shared and only that segment told two apart. One keyed a Polymarket TOKEN (`clickhouse:quote:\{token}:\{day}`), the other a SYMBOL (`clickhouse:spot:\{symbol}:\{day}`), and nothing but that segment separated them. Rows written under either key are still readable and `--produced-by` still accepts the prefix; nothing mints a new one. The hazard is dormant rather than gone: a second producer re-creates it. The recorder's commit key interpolates the kind tag POSITIONALLY (`\{}` fed from `crates/vike-data/src/live_rec.rs`'s `RecKind`), so quote/trade/book/depth/equity share one template and differ only in that slot. `local_ts` is the LOCAL receive time and is 0 in any part sealed before the column existed.

Pinned rather than fixed: the contradiction is recorded with both sides named, so a reader meets it here instead of in production.

## Known producers [#known-producers]

Idempotency in this store is batch-level and keyed on a commit-key string, never on per-row value
dedup. Two producers that collide on one template silently no-op each other's appends, and a
producer that changes its template re-admits history it already wrote — both invisible unless the
shapes are written side by side.

| Producer                                       | Commit-key template                                   |
| ---------------------------------------------- | ----------------------------------------------------- |
| `crates/vike-data/src/live_rec.rs`             | `live-{venue}-{symbol}-{}-{first_ts}-{last_ts}-{seq}` |
| `crates/vike-backfill/src/pmxt/ingest.rs`      | `pmxt:quote:{asset}:{hour}`                           |
| `crates/vike-backfill/src/events_api.rs`       | `eventsapi:quote:{symbol}:{day}`                      |
| `crates/vike-backfill/src/dukascopy.rs`        | `dukascopy:{symbol}:{start_ms}-{end_ms}`              |
| `crates/vike-backfill/src/vike_archive.rs`     | `vikearchive:{}:{date}:rg{rg_idx}`                    |
| `crates/vike-backfill/src/tardis/ingest.rs`    | `tardis:{}:{symbol}:{day}`                            |
| `crates/vike-backfill/src/databento/ingest.rs` | `databento:{}:{symbol}:{window}`                      |

⚠ That list is **observed, not exhaustive**, and no gate can make it so: a commit key is an
ordinary string argument, so proving the list complete would mean following every call in the
workspace. What is gated per listed entry is that the producer exists and spells the template
verbatim. Read it as "these producers write this kind", never as "only these do".

## Where this comes from [#where-this-comes-from]

`vike_data::store_kind::STORE_KINDS`, exported as `rosters.json` at every release. The store's
own gate derives the live kind set from the code — the series directory literals, the compaction
dispatch and the write verbs — and fails until a new kind has a row, so this page cannot describe
a shape the store does not write.


# trade (/docs/trader/concepts/data/trade)




`trade` is one of the shapes the historical store holds. A stored series lives under a
`kind=` path segment, and that segment is the layout contract its producers and its consumers
have to agree on: the columns, how the leaf is partitioned, and what `venue` and `symbol` mean
for this particular kind. All of it is below, rendered from the same table the runtime dispatches
on.

One decoded row becomes a `vike_model::TradeTick`. The codec that owns the schema is `TradeCodec`; the
store writes through `append_trades` and reads through `scan_trades`.

## Identity [#identity]

**venue = the bridge venue id; symbol = the instrument. This is the MARKET print tape — an account's OWN executions are `kind=exec_fill`, a different series that never collides with it even when (venue, symbol) match**

This is the field most often assumed and most often wrong, which is why it is stated per kind
rather than once for the store.

## Columns [#columns]

Every Arrow column today's writer emits, in schema order, with the codec flavor that picks its
Arrow type and nullability.

| Column           | Flavor    | Note                                                                  |
| ---------------- | --------- | --------------------------------------------------------------------- |
| `ts`             | `i64`     | —                                                                     |
| `price`          | `f64`     | —                                                                     |
| `size`           | `f64`     | —                                                                     |
| `is_buyer_maker` | `bool`    | —                                                                     |
| `local_ts`       | `i64_add` | may be ABSENT ENTIRELY from a part sealed before the column was added |
| `symbol_col`     | `str_add` | may be ABSENT ENTIRELY from a part sealed before the column was added |

## Layout [#layout]

| Property                      | Value                                                                   |
| ----------------------------- | ----------------------------------------------------------------------- |
| Partitioning                  | `symbol`                                                                |
| Grouped form                  | yes — many symbols in one part, told apart by a row-level symbol column |
| In the cross-kind tick report | yes                                                                     |

## Traps [#traps]

⚠ Not every `kind=trade` series is a print tape. `crates/bridges/deribit/src/dvol.rs` writes Deribit's DVOL INDEX through `append_trades`, one synthetic tick per bucket, because this kind is the store's only (ts, price) lane — a consumer that assumes every trade row was a matched execution is wrong for that venue. Bars are DERIVED from this kind (`resample_trades_to_bars`), which is why `crate::coverage::TICK_KINDS` excludes `bar`: a missing bar day beside a present trade day is an un-run resample, not a hole in the tape.

Pinned rather than fixed: the contradiction is recorded with both sides named, so a reader meets it here instead of in production.

## Known producers [#known-producers]

Idempotency in this store is batch-level and keyed on a commit-key string, never on per-row value
dedup. Two producers that collide on one template silently no-op each other's appends, and a
producer that changes its template re-admits history it already wrote — both invisible unless the
shapes are written side by side.

| Producer                                       | Commit-key template                                   |
| ---------------------------------------------- | ----------------------------------------------------- |
| `crates/vike-data/src/live_rec.rs`             | `live-{venue}-{symbol}-{}-{first_ts}-{last_ts}-{seq}` |
| `crates/vike-backfill/src/pmxt/ingest.rs`      | `pmxt:trade:{asset}:{hour}`                           |
| `crates/vike-backfill/src/tardis/ingest.rs`    | `tardis:{}:{symbol}:{day}`                            |
| `crates/vike-backfill/src/databento/ingest.rs` | `databento:{}:{symbol}:{window}`                      |
| `crates/vike-backfill/src/events_api.rs`       | `eventsapi:trade:{symbol}:{day}`                      |
| `crates/vike-backfill/src/vike_archive.rs`     | `vikearchive:{}:{date}:rg{rg_idx}`                    |
| `crates/bridges/deribit/src/dvol.rs`           | `dvol:{}:{symbol}:{bucket}`                           |

⚠ That list is **observed, not exhaustive**, and no gate can make it so: a commit key is an
ordinary string argument, so proving the list complete would mean following every call in the
workspace. What is gated per listed entry is that the producer exists and spells the template
verbatim. Read it as "these producers write this kind", never as "only these do".

## Where this comes from [#where-this-comes-from]

`vike_data::store_kind::STORE_KINDS`, exported as `rosters.json` at every release. The store's
own gate derives the live kind set from the code — the series directory literals, the compaction
dispatch and the write verbs — and fails until a new kind has a row, so this page cannot describe
a shape the store does not write.


# AccountState (/docs/trader/concepts/events/account-state)




`AccountState` is one of the 20 variants of the tagged union every part of Vike Trader
speaks: `vike_model::Event`. The core loop consumes it, the journal replays it, and fixtures pin
it — one vocabulary from a venue's socket to a strategy's callback.

## The payload [#the-payload]

It carries a `AccountState`. On the wire the frame is tagged `AccountState`, the variant name.

## Who emits it [#who-emits-it]

**The venue side.** Emitted by the venue side — a bridge adapter maps the venue's own message onto this canonical shape and pushes it through the ingest channel. Every venue produces it in its own words; the mapping is that bridge's `event_mapper`, and the conformance harness folds the result through the real order state machine.

## Where it lands [#where-it-lands]

Events reach the core through one ingest channel and are folded in arrival order. It moves state without ending an order's life.

The [order lifecycle](/docs/trader/concepts/order-lifecycle) walks the sequence a working order produces;
the [execution client seam](/docs/trader/concepts/execution-client-seam) is the contract every venue
adapter implements to produce these; and the [journal](/docs/trader/concepts/journal) is what makes a
session of them replayable.

## Where this comes from [#where-this-comes-from]

`vike_model::Event` — the variant, its payload type and its wire tag, exported as `rosters.json`
at every release. The wire tags are checked against the enum's own source at build time, so a
renamed variant or a changed tag reddens the product tree before it could reach this page.


# Fill (/docs/trader/concepts/events/fill)




`Fill` is one of the 20 variants of the tagged union every part of Vike Trader
speaks: `vike_model::Event`. The core loop consumes it, the journal replays it, and fixtures pin
it — one vocabulary from a venue's socket to a strategy's callback.

## The payload [#the-payload]

It carries a `FillEvent`. On the wire the frame is tagged `FillEvent` — NOT `Fill`. The tag predates the Rust spelling and is pinned by fixtures and the execution journal, so only the variant was shortened; a consumer matches on the tag.

## Who emits it [#who-emits-it]

**The venue side.** Emitted by the venue side — a bridge adapter maps the venue's own message onto this canonical shape and pushes it through the ingest channel. Every venue produces it in its own words; the mapping is that bridge's `event_mapper`, and the conformance harness folds the result through the real order state machine.

## Where it lands [#where-it-lands]

Events reach the core through one ingest channel and are folded in arrival order. It moves state without ending an order's life.

The [order lifecycle](/docs/trader/concepts/order-lifecycle) walks the sequence a working order produces;
the [execution client seam](/docs/trader/concepts/execution-client-seam) is the contract every venue
adapter implements to produce these; and the [journal](/docs/trader/concepts/journal) is what makes a
session of them replayable.

## Where this comes from [#where-this-comes-from]

`vike_model::Event` — the variant, its payload type and its wire tag, exported as `rosters.json`
at every release. The wire tags are checked against the enum's own source at build time, so a
renamed variant or a changed tag reddens the product tree before it could reach this page.


# Funding (/docs/trader/concepts/events/funding)




`Funding` is one of the 20 variants of the tagged union every part of Vike Trader
speaks: `vike_model::Event`. The core loop consumes it, the journal replays it, and fixtures pin
it — one vocabulary from a venue's socket to a strategy's callback.

## The payload [#the-payload]

It carries a `FundingEvent`. On the wire the frame is tagged `FundingEvent` — NOT `Funding`. The tag predates the Rust spelling and is pinned by fixtures and the execution journal, so only the variant was shortened; a consumer matches on the tag.

## Who emits it [#who-emits-it]

**The venue side.** Emitted by the venue side — a bridge adapter maps the venue's own message onto this canonical shape and pushes it through the ingest channel. Every venue produces it in its own words; the mapping is that bridge's `event_mapper`, and the conformance harness folds the result through the real order state machine.

## Where it lands [#where-it-lands]

Events reach the core through one ingest channel and are folded in arrival order. It moves state without ending an order's life.

The [order lifecycle](/docs/trader/concepts/order-lifecycle) walks the sequence a working order produces;
the [execution client seam](/docs/trader/concepts/execution-client-seam) is the contract every venue
adapter implements to produce these; and the [journal](/docs/trader/concepts/journal) is what makes a
session of them replayable.

## Where this comes from [#where-this-comes-from]

`vike_model::Event` — the variant, its payload type and its wire tag, exported as `rosters.json`
at every release. The wire tags are checked against the enum's own source at build time, so a
renamed variant or a changed tag reddens the product tree before it could reach this page.


# Events (/docs/trader/concepts/events)



Everything that happens to an order, a position or an account balance arrives as one value from
one enum. `vike_model::Event` is, in its own words, "the tagged union the core loop consumes (and
fixtures replay)" — 20 variants, serialized with `#[serde(tag = "type")]`, spoken identically by a
venue socket, the command journal and a frozen parity fixture. There is no per-venue dialect: a
bridge's job is to translate its venue into this enum and stop there.

A mounted strategy is the one consumer that does *not* see the enum. `Strategy::on_order_event`
takes an `OrderLifecycle`, "an INTERNAL, strategy-facing view the runtime derives from the venue
events it already folds" — not part of the wire union, and not variant-for-variant with it:
`OrderLifecycle::from_event` returns `None` for every fill event, because fills flow the richer
`Strategy::on_fill` path (`crates/vike-model/src/strategy/mod.rs`).

Every payload is a plain value struct — `Clone`, no interior references — "so events are copy-safe
across the channel boundary", which is what lets the single-writer core own them without sharing
anything back (`crates/vike-model/src/events.rs`).

## The three rules [#the-three-rules]

The venue-adapter contract is not prose that adapters are trusted to follow. It is a scenario table
run against every covered venue's real `event_mapper` and the shared exec plumbing —
`crates/vike-bridge-core/tests/bridge_conformance.rs`, whose header states all three:

**Emitter split.** Rust emits `OrderSubmitted` synchronously at submit; the venue emits
`OrderAccepted / Rejected / Canceled / (Partially)Filled`. The local side owns two events the venue
never sees, both of them a RiskGate veto raised *before* the venue:

* a vetoed submit publishes `OrderDenied` — `ExecutionEngine::submit_order` "calls the gate and
  publishes `OrderDenied` on veto or `client.submit` on ok";
* a vetoed modify publishes `OrderModifyRejected` with a `risk:` reason instead, and "nothing
  reaches the venue" — `ExecutionEngine::modify_order` returns without calling `client.modify`.

The engine publishes no other event (`crates/vike-exec/src/execution_engine/mod.rs`).

**No silent vanish.** A dead venue path *must* synthesize a terminal `OrderRejected`. The
conformance suite's `TransportDeath` scenario kills the path through the exact shared seam each
venue really uses — `ExecActor` for command venues, `resolve_ambiguous_submit` for REST-poll
venues — and requires a terminal out the other side. An order that was submitted and then simply
stopped existing is the failure this rule exists to make impossible.

**Exactly one terminal.** The oracle is the real state machine, not a mock: `ManagedOrder::apply`
is "the ONLY mutator of order state" (`crates/vike-exec/src/order.rs`), and there are five terminal
statuses — `Filled`, `Canceled`, `Rejected`, `Denied`, `Expired`
(`crates/vike-exec/src/order.rs`'s `OrderStatus::is_terminal`). `Liquidated` is deliberately
excluded from that set: it is a live perp force-close state, not a closed one. Illegal or
out-of-order events are dropped idempotently rather than corrupting the single terminal — a late
venue `OrderCanceled` replay and a late `OrderCancelRejected` advisory arriving after the order
already closed are both dropped by one row of that four-row table, `CancelAfterClose`.

Two variants are advisories that end nothing. `OrderCancelRejected` is a venue or transport failure
of a cancel request and is **non-terminal — the order stays live**; `OrderModifyRejected` is the
same shape for a modify, and **the order keeps its terms** (`crates/vike-model/src/events.rs`'s
`Event`). Both exist because a failed cancel that is swallowed is indistinguishable from one that
worked.

`OrderModifyRejected` is not always the venue's word, though: the local modify veto above arrives
on it too, with `risk:` in front of the reason.

Which venues are held to this is itself gated: the covered and deferred lists are checked
exhaustive against the canonical roster `vike_model::VENUES`, so a new bridge crate cannot join the
[venue roster](/docs/trader/venues) and quietly escape the harness. Four are deferred with a written
reason rather than faked — polymarket, dukascopy, ibkr and ctrader, each for a shape that does not
fit the stateless decode seam.

## How an event travels [#how-an-event-travels]

Producers hold fire-and-forget senders from `crates/vike-exec/src/lanes.rs` — "the producer-side
ingest lanes… the consumer (the single-writer core thread) lives in vike-core", which is why
bridges depend on `vike-exec` and never on `vike-core`. The event lane is **lossless**:
`EventSender::send` is an "async lossless send (venue WS tasks) — back-pressures the task, never
drops", with `blocking_send` as the twin for non-async producers. A producer that outruns the core
waits; it does not discard. See [ingest lanes](/docs/trader/concepts/ingest-lanes) and the
[execution client seam](/docs/trader/concepts/execution-client-seam).

<Callout type="warn" title="Two wire tags are not their variant names">
  `Event::Fill` serializes as `"FillEvent"` and `Event::Funding` as `"FundingEvent"` — the tags
  predate the Rust spellings and are pinned by fixtures and the execution journal, so only the
  variant names were shortened. A consumer matches on the tag, not on the Rust identifier
  (`crates/vike-model/src/events.rs`'s `Event`).
</Callout>

<Callout type="warn" title="trade_id is a type, and it cannot be empty">
  `venue` and `symbol` are interned (`Ustr`) because their distinct-value sets are bounded over a
  process lifetime; `trade_id` is deliberately **not**, because it is minted per fill and unbounded.
  It is also `TradeId`, a newtype that implements no `Default` — so `unwrap_or_default()` cannot name
  it. An empty id did not dedup badly, it **skipped dedup entirely**: the measured consequence on a
  live daemon was re-applied fills double-booking commission and realized PnL, and on the reconcile
  side an empty id can never match, manufacturing a `MissingFill` divergence
  (`crates/vike-model/src/events.rs`'s `TradeId`). See [reconciliation](/docs/trader/concepts/reconciliation).
</Callout>

## The pages in this section [#the-pages-in-this-section]

One page per variant, generated from the enum itself: who emits it, what it carries, and whether it
ends an order's life. For how the variants compose into a working order's life, read the
[order lifecycle](/docs/trader/concepts/order-lifecycle); for what the fill lane does to positions and
realized PnL, the [account](/docs/trader/concepts/account); for how a whole session of events becomes
replayable, the [journal](/docs/trader/concepts/journal).


# OrderAccepted (/docs/trader/concepts/events/order-accepted)




`OrderAccepted` is one of the 20 variants of the tagged union every part of Vike Trader
speaks: `vike_model::Event`. The core loop consumes it, the journal replays it, and fixtures pin
it — one vocabulary from a venue's socket to a strategy's callback.

## The payload [#the-payload]

It carries a `OrderAccepted`. On the wire the frame is tagged `OrderAccepted`, the variant name.

## Who emits it [#who-emits-it]

**The venue side.** Emitted by the venue side — a bridge adapter maps the venue's own message onto this canonical shape and pushes it through the ingest channel. Every venue produces it in its own words; the mapping is that bridge's `event_mapper`, and the conformance harness folds the result through the real order state machine.

## Where it lands [#where-it-lands]

Events reach the core through one ingest channel and are folded in arrival order. It moves state without ending an order's life.

The [order lifecycle](/docs/trader/concepts/order-lifecycle) walks the sequence a working order produces;
the [execution client seam](/docs/trader/concepts/execution-client-seam) is the contract every venue
adapter implements to produce these; and the [journal](/docs/trader/concepts/journal) is what makes a
session of them replayable.

## Where this comes from [#where-this-comes-from]

`vike_model::Event` — the variant, its payload type and its wire tag, exported as `rosters.json`
at every release. The wire tags are checked against the enum's own source at build time, so a
renamed variant or a changed tag reddens the product tree before it could reach this page.


# OrderCancelRejected (/docs/trader/concepts/events/order-cancel-rejected)




`OrderCancelRejected` is one of the 20 variants of the tagged union every part of Vike Trader
speaks: `vike_model::Event`. The core loop consumes it, the journal replays it, and fixtures pin
it — one vocabulary from a venue's socket to a strategy's callback.

## The payload [#the-payload]

It carries a `OrderCancelRejected`. On the wire the frame is tagged `OrderCancelRejected`, the variant name.

## Who emits it [#who-emits-it]

**The venue side.** Emitted by the venue side — a bridge adapter maps the venue's own message onto this canonical shape and pushes it through the ingest channel. Every venue produces it in its own words; the mapping is that bridge's `event_mapper`, and the conformance harness folds the result through the real order state machine.

## Where it lands [#where-it-lands]

Events reach the core through one ingest channel and are folded in arrival order. &#x2A;*NON-TERMINAL, and that is the point: a cancel request failed at the venue or in transport, so the order is still live and still working. Treating it as an ending would leave a resting order nobody is watching.**

The [order lifecycle](/docs/trader/concepts/order-lifecycle) walks the sequence a working order produces;
the [execution client seam](/docs/trader/concepts/execution-client-seam) is the contract every venue
adapter implements to produce these; and the [journal](/docs/trader/concepts/journal) is what makes a
session of them replayable.

## Where this comes from [#where-this-comes-from]

`vike_model::Event` — the variant, its payload type and its wire tag, exported as `rosters.json`
at every release. The wire tags are checked against the enum's own source at build time, so a
renamed variant or a changed tag reddens the product tree before it could reach this page.


# OrderCanceled (/docs/trader/concepts/events/order-canceled)




`OrderCanceled` is one of the 20 variants of the tagged union every part of Vike Trader
speaks: `vike_model::Event`. The core loop consumes it, the journal replays it, and fixtures pin
it — one vocabulary from a venue's socket to a strategy's callback.

## The payload [#the-payload]

It carries a `OrderCanceled`. On the wire the frame is tagged `OrderCanceled`, the variant name.

## Who emits it [#who-emits-it]

**The venue side.** Emitted by the venue side — a bridge adapter maps the venue's own message onto this canonical shape and pushes it through the ingest channel. Every venue produces it in its own words; the mapping is that bridge's `event_mapper`, and the conformance harness folds the result through the real order state machine.

## Where it lands [#where-it-lands]

Events reach the core through one ingest channel and are folded in arrival order. This one is **terminal**: it ends the order's life, and the contract every adapter is held to is exactly-one-terminal — an order may not reach two, and it may not silently reach none. A dead venue path has to synthesize a rejection rather than let the order vanish.

The [order lifecycle](/docs/trader/concepts/order-lifecycle) walks the sequence a working order produces;
the [execution client seam](/docs/trader/concepts/execution-client-seam) is the contract every venue
adapter implements to produce these; and the [journal](/docs/trader/concepts/journal) is what makes a
session of them replayable.

## Where this comes from [#where-this-comes-from]

`vike_model::Event` — the variant, its payload type and its wire tag, exported as `rosters.json`
at every release. The wire tags are checked against the enum's own source at build time, so a
renamed variant or a changed tag reddens the product tree before it could reach this page.


# OrderDenied (/docs/trader/concepts/events/order-denied)




`OrderDenied` is one of the 20 variants of the tagged union every part of Vike Trader
speaks: `vike_model::Event`. The core loop consumes it, the journal replays it, and fixtures pin
it — one vocabulary from a venue's socket to a strategy's callback.

## The payload [#the-payload]

It carries a `OrderDenied`. On the wire the frame is tagged `OrderDenied`, the variant name.

## Who emits it [#who-emits-it]

**Rust, before the wire.** The risk gate refused the order, so nothing was sent. A denial is terminal and local: no venue ever saw it.

## Where it lands [#where-it-lands]

Events reach the core through one ingest channel and are folded in arrival order. This one is **terminal**: it ends the order's life, and the contract every adapter is held to is exactly-one-terminal — an order may not reach two, and it may not silently reach none. A dead venue path has to synthesize a rejection rather than let the order vanish.

The [order lifecycle](/docs/trader/concepts/order-lifecycle) walks the sequence a working order produces;
the [execution client seam](/docs/trader/concepts/execution-client-seam) is the contract every venue
adapter implements to produce these; and the [journal](/docs/trader/concepts/journal) is what makes a
session of them replayable.

## Where this comes from [#where-this-comes-from]

`vike_model::Event` — the variant, its payload type and its wire tag, exported as `rosters.json`
at every release. The wire tags are checked against the enum's own source at build time, so a
renamed variant or a changed tag reddens the product tree before it could reach this page.


# OrderExpired (/docs/trader/concepts/events/order-expired)




`OrderExpired` is one of the 20 variants of the tagged union every part of Vike Trader
speaks: `vike_model::Event`. The core loop consumes it, the journal replays it, and fixtures pin
it — one vocabulary from a venue's socket to a strategy's callback.

## The payload [#the-payload]

It carries a `OrderExpired`. On the wire the frame is tagged `OrderExpired`, the variant name.

## Who emits it [#who-emits-it]

**The venue side.** Emitted by the venue side — a bridge adapter maps the venue's own message onto this canonical shape and pushes it through the ingest channel. Every venue produces it in its own words; the mapping is that bridge's `event_mapper`, and the conformance harness folds the result through the real order state machine.

## Where it lands [#where-it-lands]

Events reach the core through one ingest channel and are folded in arrival order. This one is **terminal**: it ends the order's life, and the contract every adapter is held to is exactly-one-terminal — an order may not reach two, and it may not silently reach none. A dead venue path has to synthesize a rejection rather than let the order vanish.

The [order lifecycle](/docs/trader/concepts/order-lifecycle) walks the sequence a working order produces;
the [execution client seam](/docs/trader/concepts/execution-client-seam) is the contract every venue
adapter implements to produce these; and the [journal](/docs/trader/concepts/journal) is what makes a
session of them replayable.

## Where this comes from [#where-this-comes-from]

`vike_model::Event` — the variant, its payload type and its wire tag, exported as `rosters.json`
at every release. The wire tags are checked against the enum's own source at build time, so a
renamed variant or a changed tag reddens the product tree before it could reach this page.


# OrderFilled (/docs/trader/concepts/events/order-filled)




`OrderFilled` is one of the 20 variants of the tagged union every part of Vike Trader
speaks: `vike_model::Event`. The core loop consumes it, the journal replays it, and fixtures pin
it — one vocabulary from a venue's socket to a strategy's callback.

## The payload [#the-payload]

It carries a `OrderFilled`. On the wire the frame is tagged `OrderFilled`, the variant name.

## Who emits it [#who-emits-it]

**The venue side.** Emitted by the venue side — a bridge adapter maps the venue's own message onto this canonical shape and pushes it through the ingest channel. Every venue produces it in its own words; the mapping is that bridge's `event_mapper`, and the conformance harness folds the result through the real order state machine.

## Where it lands [#where-it-lands]

Events reach the core through one ingest channel and are folded in arrival order. This one is **terminal**: it ends the order's life, and the contract every adapter is held to is exactly-one-terminal — an order may not reach two, and it may not silently reach none. A dead venue path has to synthesize a rejection rather than let the order vanish.

The [order lifecycle](/docs/trader/concepts/order-lifecycle) walks the sequence a working order produces;
the [execution client seam](/docs/trader/concepts/execution-client-seam) is the contract every venue
adapter implements to produce these; and the [journal](/docs/trader/concepts/journal) is what makes a
session of them replayable.

## Where this comes from [#where-this-comes-from]

`vike_model::Event` — the variant, its payload type and its wire tag, exported as `rosters.json`
at every release. The wire tags are checked against the enum's own source at build time, so a
renamed variant or a changed tag reddens the product tree before it could reach this page.


# OrderLiquidated (/docs/trader/concepts/events/order-liquidated)




`OrderLiquidated` is one of the 20 variants of the tagged union every part of Vike Trader
speaks: `vike_model::Event`. The core loop consumes it, the journal replays it, and fixtures pin
it — one vocabulary from a venue's socket to a strategy's callback.

## The payload [#the-payload]

It carries a `OrderLiquidated`. On the wire the frame is tagged `OrderLiquidated`, the variant name.

## Who emits it [#who-emits-it]

**The venue side.** Emitted by the venue side — a bridge adapter maps the venue's own message onto this canonical shape and pushes it through the ingest channel. Every venue produces it in its own words; the mapping is that bridge's `event_mapper`, and the conformance harness folds the result through the real order state machine.

## Where it lands [#where-it-lands]

Events reach the core through one ingest channel and are folded in arrival order. This one is **terminal**: it ends the order's life, and the contract every adapter is held to is exactly-one-terminal — an order may not reach two, and it may not silently reach none. A dead venue path has to synthesize a rejection rather than let the order vanish.

The [order lifecycle](/docs/trader/concepts/order-lifecycle) walks the sequence a working order produces;
the [execution client seam](/docs/trader/concepts/execution-client-seam) is the contract every venue
adapter implements to produce these; and the [journal](/docs/trader/concepts/journal) is what makes a
session of them replayable.

## Where this comes from [#where-this-comes-from]

`vike_model::Event` — the variant, its payload type and its wire tag, exported as `rosters.json`
at every release. The wire tags are checked against the enum's own source at build time, so a
renamed variant or a changed tag reddens the product tree before it could reach this page.


# OrderModified (/docs/trader/concepts/events/order-modified)




`OrderModified` is one of the 20 variants of the tagged union every part of Vike Trader
speaks: `vike_model::Event`. The core loop consumes it, the journal replays it, and fixtures pin
it — one vocabulary from a venue's socket to a strategy's callback.

## The payload [#the-payload]

It carries a `OrderModified`. On the wire the frame is tagged `OrderModified`, the variant name.

## Who emits it [#who-emits-it]

**The venue side.** Emitted by the venue side — a bridge adapter maps the venue's own message onto this canonical shape and pushes it through the ingest channel. Every venue produces it in its own words; the mapping is that bridge's `event_mapper`, and the conformance harness folds the result through the real order state machine.

## Where it lands [#where-it-lands]

Events reach the core through one ingest channel and are folded in arrival order. It moves state without ending an order's life.

The [order lifecycle](/docs/trader/concepts/order-lifecycle) walks the sequence a working order produces;
the [execution client seam](/docs/trader/concepts/execution-client-seam) is the contract every venue
adapter implements to produce these; and the [journal](/docs/trader/concepts/journal) is what makes a
session of them replayable.

## Where this comes from [#where-this-comes-from]

`vike_model::Event` — the variant, its payload type and its wire tag, exported as `rosters.json`
at every release. The wire tags are checked against the enum's own source at build time, so a
renamed variant or a changed tag reddens the product tree before it could reach this page.


# OrderModifyRejected (/docs/trader/concepts/events/order-modify-rejected)




`OrderModifyRejected` is one of the 20 variants of the tagged union every part of Vike Trader
speaks: `vike_model::Event`. The core loop consumes it, the journal replays it, and fixtures pin
it — one vocabulary from a venue's socket to a strategy's callback.

## The payload [#the-payload]

It carries a `OrderModifyRejected`. On the wire the frame is tagged `OrderModifyRejected`, the variant name.

## Who emits it [#who-emits-it]

**The venue side.** Emitted by the venue side — a bridge adapter maps the venue's own message onto this canonical shape and pushes it through the ingest channel. Every venue produces it in its own words; the mapping is that bridge's `event_mapper`, and the conformance harness folds the result through the real order state machine.

## Where it lands [#where-it-lands]

Events reach the core through one ingest channel and are folded in arrival order. &#x2A;*NON-TERMINAL: the amend was refused, so the order stands with its previous terms.**

The [order lifecycle](/docs/trader/concepts/order-lifecycle) walks the sequence a working order produces;
the [execution client seam](/docs/trader/concepts/execution-client-seam) is the contract every venue
adapter implements to produce these; and the [journal](/docs/trader/concepts/journal) is what makes a
session of them replayable.

## Where this comes from [#where-this-comes-from]

`vike_model::Event` — the variant, its payload type and its wire tag, exported as `rosters.json`
at every release. The wire tags are checked against the enum's own source at build time, so a
renamed variant or a changed tag reddens the product tree before it could reach this page.


# OrderPartiallyFilled (/docs/trader/concepts/events/order-partially-filled)




`OrderPartiallyFilled` is one of the 20 variants of the tagged union every part of Vike Trader
speaks: `vike_model::Event`. The core loop consumes it, the journal replays it, and fixtures pin
it — one vocabulary from a venue's socket to a strategy's callback.

## The payload [#the-payload]

It carries a `OrderPartiallyFilled`. On the wire the frame is tagged `OrderPartiallyFilled`, the variant name.

## Who emits it [#who-emits-it]

**The venue side.** Emitted by the venue side — a bridge adapter maps the venue's own message onto this canonical shape and pushes it through the ingest channel. Every venue produces it in its own words; the mapping is that bridge's `event_mapper`, and the conformance harness folds the result through the real order state machine.

## Where it lands [#where-it-lands]

Events reach the core through one ingest channel and are folded in arrival order. &#x2A;*NON-TERMINAL: quantity has traded and the remainder is still working.**

The [order lifecycle](/docs/trader/concepts/order-lifecycle) walks the sequence a working order produces;
the [execution client seam](/docs/trader/concepts/execution-client-seam) is the contract every venue
adapter implements to produce these; and the [journal](/docs/trader/concepts/journal) is what makes a
session of them replayable.

## Where this comes from [#where-this-comes-from]

`vike_model::Event` — the variant, its payload type and its wire tag, exported as `rosters.json`
at every release. The wire tags are checked against the enum's own source at build time, so a
renamed variant or a changed tag reddens the product tree before it could reach this page.


# OrderRejected (/docs/trader/concepts/events/order-rejected)




`OrderRejected` is one of the 20 variants of the tagged union every part of Vike Trader
speaks: `vike_model::Event`. The core loop consumes it, the journal replays it, and fixtures pin
it — one vocabulary from a venue's socket to a strategy's callback.

## The payload [#the-payload]

It carries a `OrderRejected`. On the wire the frame is tagged `OrderRejected`, the variant name.

## Who emits it [#who-emits-it]

**The venue side.** Emitted by the venue side — a bridge adapter maps the venue's own message onto this canonical shape and pushes it through the ingest channel. Every venue produces it in its own words; the mapping is that bridge's `event_mapper`, and the conformance harness folds the result through the real order state machine.

## Where it lands [#where-it-lands]

Events reach the core through one ingest channel and are folded in arrival order. This one is **terminal**: it ends the order's life, and the contract every adapter is held to is exactly-one-terminal — an order may not reach two, and it may not silently reach none. A dead venue path has to synthesize a rejection rather than let the order vanish.

The [order lifecycle](/docs/trader/concepts/order-lifecycle) walks the sequence a working order produces;
the [execution client seam](/docs/trader/concepts/execution-client-seam) is the contract every venue
adapter implements to produce these; and the [journal](/docs/trader/concepts/journal) is what makes a
session of them replayable.

## Where this comes from [#where-this-comes-from]

`vike_model::Event` — the variant, its payload type and its wire tag, exported as `rosters.json`
at every release. The wire tags are checked against the enum's own source at build time, so a
renamed variant or a changed tag reddens the product tree before it could reach this page.


# OrderSubmitted (/docs/trader/concepts/events/order-submitted)




`OrderSubmitted` is one of the 20 variants of the tagged union every part of Vike Trader
speaks: `vike_model::Event`. The core loop consumes it, the journal replays it, and fixtures pin
it — one vocabulary from a venue's socket to a strategy's callback.

## The payload [#the-payload]

It carries a `OrderSubmitted`. On the wire the frame is tagged `OrderSubmitted`, the variant name.

## Who emits it [#who-emits-it]

**Rust, synchronously at submit.** The one event the local side emits itself. `vike_exec::ExecutionEngine` writes it the moment an order is handed to a venue adapter, before any wire round trip, so the order exists in local state even if the venue never answers.

## Where it lands [#where-it-lands]

Events reach the core through one ingest channel and are folded in arrival order. It moves state without ending an order's life.

The [order lifecycle](/docs/trader/concepts/order-lifecycle) walks the sequence a working order produces;
the [execution client seam](/docs/trader/concepts/execution-client-seam) is the contract every venue
adapter implements to produce these; and the [journal](/docs/trader/concepts/journal) is what makes a
session of them replayable.

## Where this comes from [#where-this-comes-from]

`vike_model::Event` — the variant, its payload type and its wire tag, exported as `rosters.json`
at every release. The wire tags are checked against the enum's own source at build time, so a
renamed variant or a changed tag reddens the product tree before it could reach this page.


# OrderTriggered (/docs/trader/concepts/events/order-triggered)




`OrderTriggered` is one of the 20 variants of the tagged union every part of Vike Trader
speaks: `vike_model::Event`. The core loop consumes it, the journal replays it, and fixtures pin
it — one vocabulary from a venue's socket to a strategy's callback.

## The payload [#the-payload]

It carries a `OrderTriggered`. On the wire the frame is tagged `OrderTriggered`, the variant name.

## Who emits it [#who-emits-it]

**The venue side.** Emitted by the venue side — a bridge adapter maps the venue's own message onto this canonical shape and pushes it through the ingest channel. Every venue produces it in its own words; the mapping is that bridge's `event_mapper`, and the conformance harness folds the result through the real order state machine.

## Where it lands [#where-it-lands]

Events reach the core through one ingest channel and are folded in arrival order. It moves state without ending an order's life.

The [order lifecycle](/docs/trader/concepts/order-lifecycle) walks the sequence a working order produces;
the [execution client seam](/docs/trader/concepts/execution-client-seam) is the contract every venue
adapter implements to produce these; and the [journal](/docs/trader/concepts/journal) is what makes a
session of them replayable.

## Where this comes from [#where-this-comes-from]

`vike_model::Event` — the variant, its payload type and its wire tag, exported as `rosters.json`
at every release. The wire tags are checked against the enum's own source at build time, so a
renamed variant or a changed tag reddens the product tree before it could reach this page.


# PositionChanged (/docs/trader/concepts/events/position-changed)




`PositionChanged` is one of the 20 variants of the tagged union every part of Vike Trader
speaks: `vike_model::Event`. The core loop consumes it, the journal replays it, and fixtures pin
it — one vocabulary from a venue's socket to a strategy's callback.

## The payload [#the-payload]

It carries a `PositionChanged`. On the wire the frame is tagged `PositionChanged`, the variant name.

## Who emits it [#who-emits-it]

**The venue side.** Emitted by the venue side — a bridge adapter maps the venue's own message onto this canonical shape and pushes it through the ingest channel. Every venue produces it in its own words; the mapping is that bridge's `event_mapper`, and the conformance harness folds the result through the real order state machine.

## Where it lands [#where-it-lands]

Events reach the core through one ingest channel and are folded in arrival order. It moves state without ending an order's life.

The [order lifecycle](/docs/trader/concepts/order-lifecycle) walks the sequence a working order produces;
the [execution client seam](/docs/trader/concepts/execution-client-seam) is the contract every venue
adapter implements to produce these; and the [journal](/docs/trader/concepts/journal) is what makes a
session of them replayable.

## Where this comes from [#where-this-comes-from]

`vike_model::Event` — the variant, its payload type and its wire tag, exported as `rosters.json`
at every release. The wire tags are checked against the enum's own source at build time, so a
renamed variant or a changed tag reddens the product tree before it could reach this page.


# PositionClosed (/docs/trader/concepts/events/position-closed)




`PositionClosed` is one of the 20 variants of the tagged union every part of Vike Trader
speaks: `vike_model::Event`. The core loop consumes it, the journal replays it, and fixtures pin
it — one vocabulary from a venue's socket to a strategy's callback.

## The payload [#the-payload]

It carries a `PositionClosed`. On the wire the frame is tagged `PositionClosed`, the variant name.

## Who emits it [#who-emits-it]

**The venue side.** Emitted by the venue side — a bridge adapter maps the venue's own message onto this canonical shape and pushes it through the ingest channel. Every venue produces it in its own words; the mapping is that bridge's `event_mapper`, and the conformance harness folds the result through the real order state machine.

## Where it lands [#where-it-lands]

Events reach the core through one ingest channel and are folded in arrival order. It moves state without ending an order's life.

The [order lifecycle](/docs/trader/concepts/order-lifecycle) walks the sequence a working order produces;
the [execution client seam](/docs/trader/concepts/execution-client-seam) is the contract every venue
adapter implements to produce these; and the [journal](/docs/trader/concepts/journal) is what makes a
session of them replayable.

## Where this comes from [#where-this-comes-from]

`vike_model::Event` — the variant, its payload type and its wire tag, exported as `rosters.json`
at every release. The wire tags are checked against the enum's own source at build time, so a
renamed variant or a changed tag reddens the product tree before it could reach this page.


# PositionLiquidated (/docs/trader/concepts/events/position-liquidated)




`PositionLiquidated` is one of the 20 variants of the tagged union every part of Vike Trader
speaks: `vike_model::Event`. The core loop consumes it, the journal replays it, and fixtures pin
it — one vocabulary from a venue's socket to a strategy's callback.

## The payload [#the-payload]

It carries a `PositionLiquidated`. On the wire the frame is tagged `PositionLiquidated`, the variant name.

## Who emits it [#who-emits-it]

**The venue side.** Emitted by the venue side — a bridge adapter maps the venue's own message onto this canonical shape and pushes it through the ingest channel. Every venue produces it in its own words; the mapping is that bridge's `event_mapper`, and the conformance harness folds the result through the real order state machine.

## Where it lands [#where-it-lands]

Events reach the core through one ingest channel and are folded in arrival order. It moves state without ending an order's life.

The [order lifecycle](/docs/trader/concepts/order-lifecycle) walks the sequence a working order produces;
the [execution client seam](/docs/trader/concepts/execution-client-seam) is the contract every venue
adapter implements to produce these; and the [journal](/docs/trader/concepts/journal) is what makes a
session of them replayable.

## Where this comes from [#where-this-comes-from]

`vike_model::Event` — the variant, its payload type and its wire tag, exported as `rosters.json`
at every release. The wire tags are checked against the enum's own source at build time, so a
renamed variant or a changed tag reddens the product tree before it could reach this page.


# PositionOpened (/docs/trader/concepts/events/position-opened)




`PositionOpened` is one of the 20 variants of the tagged union every part of Vike Trader
speaks: `vike_model::Event`. The core loop consumes it, the journal replays it, and fixtures pin
it — one vocabulary from a venue's socket to a strategy's callback.

## The payload [#the-payload]

It carries a `PositionOpened`. On the wire the frame is tagged `PositionOpened`, the variant name.

## Who emits it [#who-emits-it]

**The venue side.** Emitted by the venue side — a bridge adapter maps the venue's own message onto this canonical shape and pushes it through the ingest channel. Every venue produces it in its own words; the mapping is that bridge's `event_mapper`, and the conformance harness folds the result through the real order state machine.

## Where it lands [#where-it-lands]

Events reach the core through one ingest channel and are folded in arrival order. It moves state without ending an order's life.

The [order lifecycle](/docs/trader/concepts/order-lifecycle) walks the sequence a working order produces;
the [execution client seam](/docs/trader/concepts/execution-client-seam) is the contract every venue
adapter implements to produce these; and the [journal](/docs/trader/concepts/journal) is what makes a
session of them replayable.

## Where this comes from [#where-this-comes-from]

`vike_model::Event` — the variant, its payload type and its wire tag, exported as `rosters.json`
at every release. The wire tags are checked against the enum's own source at build time, so a
renamed variant or a changed tag reddens the product tree before it could reach this page.


# Frames (/docs/trader/concepts/journal/frames)



A segment is a 16-byte header — the magic `VJL1`, the format version, and the first record seq —
followed by frames laid end to end. `crates/vike-core/src/journal/frame.rs` owns the codec:
`[len: u32 LE][check: u32 FNV-1a32(payload)][payload: serde_json(record)]`. The check is
`fnv1a32`, a 32-bit FNV-1a over the payload bytes and nothing else. The payload is one
[record](/docs/trader/concepts/journal/records).

## How a frame is written [#how-a-frame-is-written]

`CommandJournal::write_framed` in `crates/vike-core/src/journal/writer.rs` writes the check, then
the payload, and the length **last** — so a reader can never see a length that points at an
unwritten payload. If the frame would not fit, the journal rolls to a fresh
[segment](/docs/trader/concepts/journal/segments) first. Every `flush_every` records (256 at the
default) it issues one `flush_async`, never per record: that syscall on every append would blow
the [latency gate](/docs/trader/concepts/latency-gate). The blocking flushes are a separate story,
told on [Sync policy](/docs/trader/concepts/journal/sync-policy).

## One walk, three readers [#one-walk-three-readers]

`walk_frames` is the single frame walk in the module. The resume scan that finds the write cursor
on open (`scan_written`), the full read that feeds replay (`read_all`) and the per-segment seq
bounds the prune computes (`scan_segment_seqs`) all layer their own aggregation over it. That
single-siting is the point: the torn-tail decision is made in exactly one place, and the three
former copies cannot drift apart. The walk starts at an offset, hands every successfully decoded
record to a callback, and returns where it stopped together with why — a `WalkEnd`.

`WalkEnd::Clean` is the ordinary end of a segment's written data: a zero length (segments are
zero-filled at creation) or the buffer's end. It is not corruption, and a caller that spans
segments crosses to the next one. `WalkEnd::Corrupt` means the walk stopped at the last valid
record and never advanced into the suspect bytes, and it carries which of three conditions fired.

## The three causes [#the-three-causes]

`CorruptCause` exists because the walk already knows which check failed and used to throw that
away, leaving a reader unable to tell an expected post-crash truncation from a payload written by
a different build. Each cause has a stable log token and a one-line operator reading:

| cause           | token            | what it means                                                                                                                                                                                               |
| --------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OobLen`        | `oob_len`        | the length prefix claims more bytes than the segment holds — a torn length write, the process died between the length and the payload. Expected and benign after a crash; every record before it is intact  |
| `CheckMismatch` | `check_mismatch` | the FNV check over the payload does not match the stored one — a torn payload write (benign after a crash), or bytes that rotted on disk (not benign)                                                       |
| `ParseFailed`   | `parse_failed`   | the payload **passed** its check, so nothing tore, and still did not deserialize as a `JournalRecord` — a schema mismatch: these bytes came from a different build, and the version header did not catch it |

The order of the checks is what makes the third distinguishable at all: the check gates the parse,
so by the time deserialization is attempted the bytes are known to be exactly what was written.

<Callout type="warn" title="The cause is diagnostic only; the halt is the same for all three">
  Carrying the cause out changed no caller's behaviour. `read_all` halts journal-wide at the first
  corrupt frame — nothing at or after that offset is replayed, in that segment or any later one —
  while the single-segment callers simply end their fold. An out-of-bounds length is deliberately
  classified as corrupt rather than clean so that a multi-segment reader stops there instead of
  crossing into a later segment past a corruption gap. The cross-segment test in this file exists
  precisely because every other corruption test is single-segment, and a per-file `break` would pass
  all of them.
</Callout>

## Where the halt is reported [#where-the-halt-is-reported]

The seam that acts on the halt is `CommandJournal::read_all_reporting`, which logs once per call —
naming the segment, the halt offset, the cause token, how many records were kept, and the
reading — with the message `journal read halted at a corrupt frame`. Before that warning existed
the decision was taken in silence; a reader of a live node's logs could not tell that replay had
stopped early, let alone why. Nothing on this path runs on the fold thread: `read_all` is an
offline and startup reader.

The same cause reaches the determinism fence. A truncated read makes the last readable `Snap` a
mid-session checkpoint rather than the session's exit `Snap`, so re-folding the tail past it
cannot reproduce the recorded hash. [Replay](/docs/trader/concepts/journal/replay) reports that as
`ReplayError::Truncated` carrying the `CorruptCause`, instead of the `HashMismatch` it used to
surface as — "the engine diverged" being a misreading of the ordinary consequence of a crash when
the cause is `oob_len`, and the right reading when it is `parse_failed`.

## What the header gates before any frame is read [#what-the-header-gates-before-any-frame-is-read]

A file without the magic is skipped as foreign. A file with the magic is one of ours, and its
version is gated by `check_version` before a single frame is walked: a supported older version
reads normally — it simply contains none of the variants added since — while an unsupported one,
older than the floor or newer than this build, is an explicit `InvalidData` error rather than a
best-effort parse or a silent drop as a torn tail. That gate and `ParseFailed` are complementary:
the header catches a declared version step, and the parse failure catches a frame whose build did
not declare one.


# The command journal (/docs/trader/concepts/journal)



The [execution core](/docs/trader/concepts/execution-core) can keep a write-ahead command journal. Off
by default, it costs nothing: `crates/vike-core/src/runtime/mod.rs`'s `JournalConfig` is `None`
in the default `CoreConfig`, no journal is opened, and the fold path is byte-identical. Turned on,
it opens a `CommandJournal` at construction and journals every exec-lane message **before** that
message folds. The authority for this tree is `crates/vike-core/src/journal/mod.rs`, whose
header describes the format as pre-allocated mmap segments with one frame per
record: `[len: u32 LE][check: u32 FNV-1a32(payload)][payload: serde_json(JournalRecord)]`. A
length of zero means the end of written data (segments are zero-filled at creation), and a record
that fails its check is a torn tail — reading stops at the last valid record and never panics.

## What is journaled, and when [#what-is-journaled-and-when]

The append sits in `CoreThread::dispatch`, after the wall-clock stamp and before the `match` that
folds the message, so a crash mid-fold still finds the message on disk. Only exec-lane verbs are
journaled: venue events and commands. Market, bar and tick lanes are not command state and never
touch the journal; a runtime mount or unmount is session topology, recorded in the mount sidecar
instead; `Command::Shutdown` never reaches the append — it gets a `Snap`, not a `Cmd`. The
wall-clock waker is journaled only when a state-mutating sweep can ride it (the stuck-order
[watchdog](/docs/trader/concepts/watchdog) or either [dead-man's switch](/docs/trader/concepts/dead-mans-switch)),
because that record is what makes a session refuse to replay. The cadence snapshot decision is
deferred to *after* the fold, so a `Snap` reflects the message that triggered it.

<Callout type="warn" title="It is a write-ahead journal, not a log of what happened">
  Because the record is appended before `ExecutionEngine::on_event` folds it, the journal
  necessarily contains events the live state machine went on to refuse — an amend-ack racing the
  fill that already terminalized the order, for one. `crates/vike-ops/src/journal_mat.rs`'s header
  spells out the consequence: any reader that re-derives order state must fold through the real
  `ManagedOrder::apply`, guards included, or it records transitions that never happened. Nothing in
  the journal is an observation of the screen; it is the input to the fold, plus checkpoints.
</Callout>

## Turning it on [#turning-it-on]

`crates/vike-core/src/run_profile.rs`'s `journal_config_from_env` resolves the sink for a
production binary. `VIKE_RUN_PROFILE=<run.toml>` loads a [run profile](/docs/trader/backtesting/run-profiles)
and its `[sinks.journal]` section decides — a profile is authoritative even when that means "no
journal", and a set-but-broken profile disables journaling with a warning rather than falling
through. Absent a profile, `VIKE_JOURNAL_DIR=<dir>` is the single-knob opt-in, with
`VIKE_JOURNAL_SNAPSHOT_EVERY=<n>` optionally overriding the checkpoint cadence. Neither set means
off. The defaults both paths share are `JournalConfig::at`'s: 64 MiB segments, an async flush
every 256 records, and a full-state `Snap` every 1024 records (plus always one on shutdown). The
`config.journal_dir` key exists in `config.toml` but is declared unconsumed in
`crates/vike-config/src/consumed.rs` — the directory stays an environment variable until the
three-variable family moves together — so set the variable, not the key.

## The compatibility contract [#the-compatibility-contract]

Each segment header stamps a format `VERSION`. This build writes `VERSION` and reads and resumes
anything in `MIN_READABLE_VERSION..=VERSION` (`check_version`): an older supported journal is
opened and appended to in place, restamped, so upgrading the binary never costs an operator their
live journal. Two things remain hard errors — a version below the floor, and any version above
`VERSION`, written by a later build that may carry variants this one does not know. The rule that
makes the range safe: a version step may only *add* a `JournalRecord` variant, or add a
`#[serde(default)]`-guarded field to an existing one; anything that renames, removes or reshapes
must raise the floor in the same commit. The range today is 4 through 15, and the module's
`readable_version_range_is_4_to_15` test is the tripwire that makes moving either end a reviewed
edit. Determinism is unaffected by reading an older journal: the added variants are ones the older
build never wrote.

## Durability, stated honestly [#durability-stated-honestly]

Appending is a bounded memcpy into a mapped page. The `msync` that forces those pages to disk
costs time proportional to dirty bytes — measured at roughly 8.6 ms for 1 MB, 100 ms for 16 MB and
292 ms (max 432 ms) for a dirty 64 MB segment — and the journal is appended from the fold thread
the [latency gate](/docs/trader/concepts/latency-gate) protects. So every blocking `msync` runs on a
dedicated syncer thread the appender never joins; [Sync policy](/docs/trader/concepts/journal/sync-policy)
is that contract. What makes a late sync safe is the durability contract the header cites: the
mapped pages belong to the OS page cache, so a process crash, an OOM kill, memory-pressure eviction
and a clean reboot all lose nothing with zero `msync`. Only a hard power cut loses the un-synced
tail, and that tail is repaired by the post-replay venue [reconcile](/docs/trader/concepts/reconciliation/).
The sync is latency shaping — it bounds how much dirty data one `msync` ever has to move — not the
durability mechanism. A graceful stop still syncs the tail: `CommandJournal`'s `Drop` publishes
the final watermark, closes the channel and joins, which is what carries the exit `Snap` to disk.

## One writer [#one-writer]

`CommandJournal::open` takes an exclusive advisory lock on the directory (`<dir>/LOCK`) and holds
it for the journal's lifetime, so a double-launched instance fails fast instead of interleaving
frames into a live journal. The read-only entry points take no lock at all, so offline inspection
and replay against a directory a live core owns keep working. [Locking](/docs/trader/concepts/journal/locking)
carries the argument.

## The pages in this tree [#the-pages-in-this-tree]

The module is a directory with one job per file, and this tree follows it:

| page                                                | what it covers                                                                                         |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| [Records](/docs/trader/concepts/journal/records)         | `JournalRecord`, the externally-tagged enum every frame carries, and the contract for adding a variant |
| [Frames](/docs/trader/concepts/journal/frames)           | the `[len][check][payload]` codec, the one frame walk, and the three torn-tail causes                  |
| [Segments](/docs/trader/concepts/journal/segments)       | naming, the `.prep` staging name, pre-allocation, the roll, and the prune                              |
| [Sync policy](/docs/trader/concepts/journal/sync-policy) | the fold-path latency contract and why the syncer is a thread                                          |
| [Reading](/docs/trader/concepts/journal/reading)         | `read_since`, the materializer checkpoint, and every reader that takes no lock                         |
| [Replay](/docs/trader/concepts/journal/replay)           | deterministic replay through the real core, and the fences                                             |
| [Locking](/docs/trader/concepts/journal/locking)         | the duplicate-instance interlock                                                                       |

The payoff is the last of those: a recorded session re-derived through the same single-writer
runtime and fenced on a state hash, which both gates the format — any nondeterminism in the fold
surfaces as a mismatch — and is the substrate the crash restart restores from.


# Locking (/docs/trader/concepts/journal/locking)



`crates/vike-core/src/journal_lock.rs` states the contract in one line: at most **one** writer may
hold a journal directory at a time — one `CommandJournal`, in one process. Vike Trader is a
desktop product, so a double launch is not hypothetical: a second shortcut click, an operator
restarting before the old process has died, a stray `cargo run`. Two writers on one journal is
silent corruption in four distinct ways, each named on the module: interleaved frames break the
[replay](/docs/trader/concepts/journal/replay) determinism fence; the two client-order-id generators
resume the same session and mint duplicate ids; two mounted makers quote against each other on one
venue account; and both reconcile drivers fold the same divergence twice.

## The mechanism [#the-mechanism]

`JournalLock::acquire` takes an exclusive advisory lock through `std::fs::File::try_lock` on a
sentinel file, `<journal_dir>/LOCK` (`LOCK_FILE`). On Unix that is `flock(LOCK_EX | LOCK_NB)`; on
Windows it is `LockFileEx` with the exclusive and fail-immediately flags. On both platforms the
lock is keyed on the open file description or handle, not on the process — so a second
`CommandJournal` in the *same* process is refused exactly like a second process, which is what
makes the interlock unit-testable at all. The module is careful to call that a property of those
two primitives rather than a universal one: a port to a target whose `try_lock` is backed by POSIX
`fcntl` record locks would key on the process instead, and would have to re-verify the paragraph
rather than inherit it. It is deliberately standard-library only — no new dependency, no `unsafe`,
no platform fork — because the crate is `unsafe_code = "deny"` with only a small audited set of
carve-outs (the journal's two, the segment mapping and the block reservation, plus the counter
mirror's writer and reader maps in `crates/vike-core/src/counters.rs`), and the lock must not
widen that set.

The sentinel is opened read-and-write, never append, because Windows refuses to lock an
append-opened handle; and without truncation, because the file's bytes are meaningless but a file
another process currently holds must never be rewritten.

## Failure is fast and loud [#failure-is-fast-and-loud]

A refused acquire is an `io::ErrorKind::AddrInUse` error whose message names the directory and
the lock file and says what to do about it:

> another vike instance is already writing the journal directory … (lock file …). Exactly one
> process may write a journal: two writers interleave WAL frames (replay's determinism fence then
> fails), re-mint the same client order ids, and double-fold reconciliation. Close the other
> instance, or point this one at a different journal directory.

Never a silent second writer, never a bare panic. Any other failure — the sentinel could not be
created or opened, or the platform refused the lock — is surfaced verbatim rather than degraded
into "no lock".

<Callout title="A leftover LOCK file is never stale">
  The guard is held for the writer's lifetime and releases when the file handle closes, which is
  documented `std::fs::File` behaviour. That covers a hard crash: the operating system closes the
  handle, so the file persisting on disk carries no state — only the live lock does. No cleanup or
  unlink is attempted, because unlinking a lock file is a race, not a tidy-up. The module's test
  `the_lock_releases_on_drop_and_a_leftover_sentinel_is_not_stale` pins exactly that: the sentinel
  survives, and the next instance acquires cleanly.
</Callout>

## Where the writer takes it, and how it survives a roll [#where-the-writer-takes-it-and-how-it-survives-a-roll]

`CommandJournal::open` in `crates/vike-core/src/journal/writer.rs` acquires the lock first, before
any segment is scanned or mapped, so a refused second instance never touches the live journal's
files — let alone extends or restamps one — and a failed open leaves no lock held. The guard then
has to survive every segment roll: `map_segment` is a segment constructor, not a directory-writer
constructor, and returns a value with no lock (re-acquiring inside it would self-conflict, since
the process already holds the directory), so `roll` moves the guard from the superseded value to
its successor. Without that move the lock would be released on the first roll and a second
instance could slip in mid-session. The move happens only after the new segment mapped
successfully, so a failed roll leaves the lock exactly where it was. The syncer thread crosses the
roll the same way — [Segments](/docs/trader/concepts/journal/segments) and
[Sync policy](/docs/trader/concepts/journal/sync-policy) carry those halves.

## Only the write path locks [#only-the-write-path-locks]

The scope is deliberately narrow. `read_all`, `latest_segment_version`, `read_since` and
`prune_before_latest_snap` take no lock, so offline inspection and replay tooling keep working
against a directory a live core owns, exactly as before the interlock existed. The sentinel is
invisible to all of them: every [reader](/docs/trader/concepts/journal/reading) selects segments by the
`journal-` prefix and `.vjl` suffix, and `LOCK` matches neither. Two different directories lock
independently — the interlock is per journal directory, not global — which is the last of the
module's four tests.


# Reading (/docs/trader/concepts/journal/reading)



`crates/vike-core/src/journal/read.rs` is the offline half of the journal: `read_since`, the
incremental tail-read a materializer resumes from, and `MaterializeCheckpoint`, the small durable
file it resumes with. Neither takes the journal directory's writer lock, and neither runs on the
fold thread. The full read they build on, `CommandJournal::read_all`, lives with the writer in
`crates/vike-core/src/journal/writer.rs` and is what [replay](/docs/trader/concepts/journal/replay)
consumes.

## `read_all` [#read_all]

`read_all` returns every valid record across every segment, in seq order, walking the segments by
index. A file without the magic is skipped; a file with it has its version gated before a frame
is read. It stops at the first torn record — journal-wide, so later segments past a corruption gap
are never returned — and `read_all_reporting` is the same read with the halt cause carried out
instead of discarded, logged exactly once per call with the segment, the offset and the reading.
[Frames](/docs/trader/concepts/journal/frames) carries the three causes. `latest_segment_version`
answers one narrow question beside it: the format version stamped on the highest-indexed segment,
which is the shape the journal's last `Snap` was written under. It exists for a single consumer,
replay's conditional-book fence, which must tell "the field was absent" from "the field was
present and empty" for a field that was defaulted in at version 8.

## `read_since` [#read_since]

`read_since(dir, after_seq)` returns every valid record whose seq is strictly greater than
`after_seq`, in seq order. The bound is strict because `after_seq` is the last seq already
*consumed*, which is the resume semantic a checkpoint needs. The implementation is the simplest
correct one — `read_all`, then filter by `record_seq` — and it is O(journal): every segment is
read and deserialized. That stays bounded because the journal is snapshot-compacted;
`prune_before_latest_snap` drops fully superseded [segments](/docs/trader/concepts/journal/segments),
so the live journal never grows without limit. A streaming reader that seeks to `after_seq` is a
declared later optimization, not needed for correctness.

<Callout type="warn" title="The first record is seq 0, and read_since(dir, 0) skips it">
  A cold-start consumer that has never checkpointed loads `0` and, with a strict lower bound, never
  sees the seq-0 record. In practice the materializer is seeded from the latest `Snap`, whose seq is
  its exclusive base, so this is benign — but a caller that must include seq 0 keys off
  `MaterializeCheckpoint::exists`, which distinguishes "no checkpoint yet" from "materialized up to
  seq 0", and chooses a full read.
</Callout>

## The checkpoint [#the-checkpoint]

`MaterializeCheckpoint` is `<dir>/materializer.ckpt`: the last seq a materializer has consumed,
so it can resume its tail across process restarts. `load` returns the stored seq, or `0` when the
file is absent or unparseable — it never errors, and a consumer that finds no checkpoint simply
re-materializes from the beginning of the compacted journal. `store` writes a temp file, fsyncs it
and renames it into place, so a torn write leaves the old checkpoint intact rather than a
half-written seq; the rename replaces the destination atomically on both Unix and Windows. The
file sits beside the segments and is independent of them: replay and restore never read it, and
pruning never modifies it — though the prune does honour it as a retention floor, keeping any
segment that holds records the materializer has not consumed.

## The materializer that resumes from it [#the-materializer-that-resumes-from-it]

The consumer these two were built for is `vike_ops::journal_mat`'s `JournalMaterializer`, in
`crates/vike-ops/src/journal_mat.rs`. It is a strict off-fold tail-follower: it drains the tail on
a cadence measured in seconds (five by default), and materializes fills into the
[history store](/docs/trader/concepts/hist-store)'s execution trade log and order lifecycles into its
order log, so reporting and reconciliation read a columnar store instead of re-scanning the
journal. Durability is at-least-once — the checkpoint plus the store's commit-key idempotency — so
a crash and resume re-processes only the un-materialized tail and never double-appends.

Its header states the rule any journal reader that derives state must follow. Because the journal
is write-ahead, it contains events the live state machine went on to refuse, so the materializer
folds every lifecycle event through the real `ManagedOrder::apply` — the same guarded mutator the
live engine folds through — and owns no transition table of its own. The concrete case it used to
get wrong was an `OrderModified` arriving on an already-terminal order, an amend acknowledgement
racing the fill that terminalized it: the live order kept its terms, and the old copy appended a
row carrying a quantity the order never had. The `MintedSubmit` record on
[Records](/docs/trader/concepts/journal/records) exists for this reader, tying a server-minted coid to
its terms so an order that terminalizes without ever filling still lands in the log. The declared
bound on a restart is staleness, never corruption: the tracker rebuilds empty from the
post-checkpoint tail, and an order open across the restart may carry a slightly stale snapshot
until its next resolved event.

## Readers never lock [#readers-never-lock]

`read_all`, `latest_segment_version`, `read_since` and `prune_before_latest_snap` take no lock,
so offline inspection and replay tooling keep working against a directory a live core owns. The
`LOCK` sentinel is not a `.vjl` file and is invisible to every scanner —
[Locking](/docs/trader/concepts/journal/locking) covers the writer side. What a reader sees is the page
cache, not the disk: a materializer or a restart reading these segments with `std::fs::read`
observes every appended byte whether or not the syncer has forced it out yet, which is one half of
why the [sync policy](/docs/trader/concepts/journal/sync-policy) is latency shaping rather than
durability. Two more readers are named on `JournalRecord`'s own contract as single-variant lookups
deliberately left as catch-alls: the [incident](/docs/trader/reference/binaries/incident) tool's
latest-`Snap` lookup, and `vike_report::journal_read::fills_from_journal`.


# Records (/docs/trader/concepts/journal/records)



Every frame's payload is one `JournalRecord`, the externally-tagged `serde_json` enum defined in
`crates/vike-core/src/journal/record.rs`. Every variant carries a `seq` — the globally monotonic
record number `record_seq` reads back — and a `now_ms`, the wall clock the core stamped for the
dispatch. The writer never serializes an owned `JournalRecord`: it serializes `JournalRecordRef`,
a borrowed twin with identical variant and field names, so a hot-path `Ingest` and a snapshot's
engine slice go to bytes by reference with no clone on the fold. The two must match exactly or a
frame would not deserialize back, which is the first of the hand-checked items below.

## The eleven variants [#the-eleven-variants]

Four of these are commands the [replay](/docs/trader/concepts/journal/replay) re-applies; the rest are
checkpoints, observations or decision markers that move no fenced state.

| variant               | what it is                                                                                                                                                                                                                            | on replay                                                                                               |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `Cmd`                 | one exec-lane ingest message — a venue event or a command                                                                                                                                                                             | re-applied                                                                                              |
| `Snap`                | the full-state checkpoint: every engine's snapshot, the client-order-id session and counter, the arm-id counter, the resting conditional books, the OTO/OCO contingency book, the per-mount attribution ledgers, and the `state_hash` | the restore base, never re-applied                                                                      |
| `StrategySubmit`      | a mounted strategy's already-resolved order intent, journaled at the `drain_broker` boundary with its `mount_id` as provenance                                                                                                        | re-applied through the same `apply_intent` site a `Cmd` order takes                                     |
| `MintedSubmit`        | a server-minted submit's resolved request, written right after the coid is minted — the durable tie between a minted coid and its terms                                                                                               | neutral: the mint is re-derived by re-applying the empty-coid submit                                    |
| `PortfolioSnap`       | a compact cross-venue portfolio observation on the opt-in `CoreConfig::portfolio_snapshot_interval` cadence                                                                                                                           | neutral: carries no engine state and is not a replay base                                               |
| `ConditionalArmed`    | an emulated conditional's resolved terms after its `arm_id` is minted, including a trailing arm's mark-seeded extreme                                                                                                                 | neutral: the arm replays from its own write-ahead intent                                                |
| `ConditionalFire`     | the trigger *decision*, written ahead of the release it causes, with the released request's coid still empty                                                                                                                          | re-applied as a submit; the trigger itself is never re-evaluated                                        |
| `ConditionalDisarmed` | an actual disarm, written ahead of the book mutation                                                                                                                                                                                  | neutral: the disarm intent carries the whole `arm_id`                                                   |
| `MarginCallLiquidate` | a margin-call sweep's released reduce-only market order; `mount_id` is `None` for the account-wide sweep and `Some` for a per-mount budget latch's flatten                                                                            | re-applied as a submit; the breach is never re-evaluated                                                |
| `GtdExpire`           | a managed GTD/Day expiry decision, written ahead of the cancel it issues                                                                                                                                                              | neutral: `cancel_order` publishes nothing locally; the venue's `OrderCanceled` replays as its own `Cmd` |
| `ScheduleFire`        | a wall-clock schedule fire decision, written ahead of the `on_schedule` it drives                                                                                                                                                     | neutral: the orders it produces ride their own `StrategySubmit` records                                 |

The [emulated-order](/docs/trader/concepts/emulated-orders) fire and the
[margin-call](/docs/trader/concepts/margin-call) liquidation exist for one reason: each is a runtime
reaction to market data, which is deliberately never journaled, so before `ConditionalFire` and
`MarginCallLiquidate` existed a session that fired a stop or a liquidation could not be replayed.
Recording the *decision* — never the tick or the bar that caused it — lets replay re-mint the
identical order without re-deciding anything. The other two emulated-order records serve readers
rather than replay: `ConditionalArmed` is the durable tie between the minted `arm_id` and the
terms the book actually holds, which the write-ahead intent cannot carry for a trailing arm whose
extreme is seeded from a mark; `ConditionalDisarmed` completes that arm's record lifecycle, so a
reader folding the conditional records can reconstruct the resting book at any point without
re-evaluating a trigger. `GtdExpire` and `ScheduleFire` go one step further: their only local effect is journaled
elsewhere, so they are audit markers that let a reader tell a venue-side cancel from a
clock-driven one, and a bar-driven submit from a scheduled one.

## What rides the Snap, and why most of it is not hashed [#what-rides-the-snap-and-why-most-of-it-is-not-hashed]

`Snap.hash` is `state_hash` over the engine snapshots alone. The books and ledgers that also ride
the record are deliberately outside it, each for a stated reason on its field: the conditional
books can move fenced state only through a fire, and every fire journals its own record; the
contingency book moves it only through a fill that releases a held child or cancels a sibling, and
every such fill is a journaled `Cmd`; the attribution ledgers are a read-only view folded from
fills that are themselves journaled. Each of those fields is `#[serde(default)]`, which is the
compatibility seam — a `Snap` written before the field existed reads back empty, and the restore
behaves exactly as it did before the feature, never as an error.

<Callout type="warn" title="Absent and zero are different things">
  `Snap.arm_seq` is an `Option`: a pre-v7 frame has no such field and reads back `None`, meaning
  absent, never `Some(0)`. The restore path then falls back to a prune-safe bound (the maximum
  global record seq plus one). The pre-v7 formula — counting currently readable records — was
  prune-unsafe, because `prune_before_latest_snap` deletes whole early segments, so a restart after
  a prune undercounted the ids already spent and re-minted duplicates. Since the arm id is the
  disarm key, a duplicate lets a stale disarm remove a fresh stop.
</Callout>

## Adding a variant: the no-silent-drop contract [#adding-a-variant-the-no-silent-drop-contract]

Three independent places interpret this enum — the writer here, the replay fold in the same crate,
and `vike_ops::journal_mat`'s materializer in a different one — and both fold sites used to end in
a `_ =>` catch-all. A variant added to only the writer therefore compiled everywhere, was written
to disk, and was *dropped* at recovery, so restored state silently diverged from pre-crash state.
Not hypothetical: `MarginCallLiquidate` carried no `mount_id` for weeks, so replay restored the
order unattributed and its fill vanished into the residual row. The catch-alls are gone from every
site that makes a per-variant decision, so a new variant is a compile error until each of these
names it and records its answer:

| site                                | the decision it forces                                      |
| ----------------------------------- | ----------------------------------------------------------- |
| `record_seq`                        | which field carries the global seq                          |
| `vike_ops::journal_mat::record_seq` | the same, in the materializer's crate                       |
| `replay_from`'s tail extraction     | re-apply on replay, or replay-neutral?                      |
| `fold_coid_mounts`                  | does it open, close or leave alone coid-to-mount ownership? |
| `fold_conditionals`                 | does it change conditional-book membership?                 |
| `OrderTracker::fold_record`         | does it produce an order-log row?                           |

"Nothing" is a perfectly good answer, written as an explicit arm with a one-line reason; the point
is that it is recorded rather than defaulted. Four things the compiler will not catch are listed on
the enum: the `JournalRecordRef` mirror, the `VERSION` bump, the single-variant lookups left as
catch-alls because they ask "is this the `Snap`?" rather than dispatching, and the materializer's
fill extraction, an `if let` on `Cmd` that no exhaustiveness check can reach. The version rule is
on the [index](/docs/trader/concepts/journal): a purely additive variant leaves the readable floor
where it is.

## The wire, pinned as bytes [#the-wire-pinned-as-bytes]

One test in this file compares a frame's bytes against a literal rather than against the types: a
default-account balance snapshot must serialize with no `route_key` key at all, so a default-account
box writes exactly the frame it always wrote, and the version bump that added the field exists so
a *downgraded* build refuses such a segment rather than parsing it wrong. The codec around each
payload is on [Frames](/docs/trader/concepts/journal/frames).


# Replay (/docs/trader/concepts/journal/replay)



`crates/vike-core/src/replay.rs` is the payoff of the journal: a recorded session re-derived
through the same runtime it was recorded on, and proven bit-identical. Its header says what that
buys twice over — it gates the journal format, because any nondeterminism in the fold surfaces as
a mismatch, and it is the substrate the crash restart restores from. Two entry points share one
engine, `replay_from`. `replay_offline` restores from the **first** `Snap`, re-folds the whole
tail, and fences the reproduced final hash against the source journal's **last** `Snap`.
`restore_from_journal` restores from the **latest** `Snap`, re-folds only the crash tail after
it — empty on a clean shutdown — and applies no fence, because it is a restore.

## The mechanism [#the-mechanism]

Restoring from the first checkpoint is what makes the fence worth anything: restoring from the
latest would leave nothing to replay on a clean run, since the exit `Snap` already reflects
everything. Cadence `Snap`s are taken after the fold, so every command before the first one is
already folded into it and every command after it is re-folded forward. From that engine
`replay_from` spawns a real core with three substitutions. `ReplayClient` is a pure no-op
`ExecutionClient`: it suppresses every venue side effect and synthesizes no events — the original
venue events are already in the journal as `Ingest::Event` records and are re-pumped, so a client
that also emitted them would double the state and correctly break the fence. `QueueClock` replays
the tail's recorded `now_ms` stamps in order, so timestamp-derived state such as an order's
`created_ms` matches. The temp journal is opened with `snapshot_every = u64::MAX`, so only the
exit `Snap` fires and carries the reproduced hash. The tail is pumped through the handle in journal
order — events and commands feed one FIFO queue, so dispatch order equals record order — then the
core is shut down and joined, and its exit `Snap` is read back. The replay core runs no strategy
hook: only a strategy's already-decided orders need to reproduce, and those are on disk. When the
base `Snap` came from a mounted-strategy session, `replay_from` does mount an `InertStrategy` —
every hook at its no-op default, and never invoked, since the tail pump sends no market data —
solely so `spawn_core`'s mount-presence derivation of `collect_applied_fills`, a field the hash
does cover, matches the source rather than diverging on a perfectly faithful fold.

## What replays and what is neutral [#what-replays-and-what-is-neutral]

The tail extraction is an exhaustive match with no catch-all — a new [record](/docs/trader/concepts/journal/records)
variant fails to compile until someone decides. Four variants re-apply: `Cmd`, `StrategySubmit`
(as an order command through the same `apply_intent` site), and `ConditionalFire` and
`MarginCallLiquidate`, each as a submit whose coid is still empty, so the replay core re-mints the
identical id from the restored generator. The trigger and the breach are never re-evaluated; the
replay core pumps no market data, so its equity never moves. Everything else is replay-neutral at
any position: `Snap` is the base, `MintedSubmit`'s mint is re-derived, `PortfolioSnap` carries no
engine state, the arm and disarm records only resolve terms, and `GtdExpire` and `ScheduleFire`
are decision markers whose effects arrive as their own records — re-issuing them would double a
cancel or a set of submits. Market data is never journaled, and neither is what a strategy's hooks
saw; what is journaled is what they decided.

## The three fences [#the-three-fences]

The engine fence is `vike_exec::state_hash`, defined in `crates/vike-exec/src/engine_snapshot.rs`:
an FNV-1a64 over the canonical JSON of the engine snapshots, with two fields cleared before
hashing — the top-level `now_ms`, which is stamped by every ingest message including
non-journaled market ticks, and the account's mark-price cache, which mark ticks mutate. Neither
is reproducible by re-folding the exec lane alone, so hashing them would fail the fence on a
perfectly valid journal; everything else stays hashed. The fence verifies the recoverable order
and account state, which is the point. A mismatch is `ReplayError::HashMismatch`.

That covered one thing while the restore handed back three more, so `replay_offline` adds two
fences over the same oracle, the source journal's last `Snap`. `conditionals_hash` compares the
reproduced resting conditional books with the recorded ones, clearing a trailing arm's ratcheted
extreme, which moves on non-journaled market data as the marks do; it is gated on version 8 or
later through `latest_segment_version`, because an older `Snap` reads back empty books whether or
not the live session had arms. And the two id counters are fenced as **floors** by `fence_floor`:
an overshoot only wastes ids, while an undercount means a restored session re-mints an id the
pre-crash run already spent — and an arm id is the disarm key, so a duplicate lets a stale disarm
remove a fresh stop. Both surface as `ReplayError::RestoreMismatch` naming the field, distinct
from the engine mismatch on purpose: the two have different triage paths.

<Callout type="warn" title="A truncated journal is reported as truncated, not as a divergence">
  When the frame walk halts at a torn frame, the last readable `Snap` is a mid-session checkpoint,
  so the honestly re-folded tail cannot match it. That is `ReplayError::Truncated` carrying the
  `CorruptCause` from [Frames](/docs/trader/concepts/journal/frames): a torn length prefix is the
  ordinary consequence of a crash, a checksum-valid frame that does not parse came from a different
  build. A truncated journal whose fences all pass — a tear strictly after the exit `Snap` — still
  succeeds. Two shapes are `Unsupported`: a multi-engine base, whose extra engines' seed cash is not
  in their snapshots, and a tail carrying the wall-clock waker — journaled only when the stuck-order
  watchdog or either dead-man's switch is enabled, precisely so such a session refuses. A journal with
  no `Snap` is `Empty`.
</Callout>

## The restore [#the-restore]

`restore_from_journal` returns a `RestoredState`: the engines, the coid session and counter to
resume so post-restart ids never collide with a still-open prior id, the arm counter, the resting
conditional books, the OTO/OCO contingency book, the per-mount attribution ledgers, and the
coid-to-mount origin map. Membership of the conditional books is a pure fold of the journal's
records (`fold_conditionals`), never the replay core's own book — that core neither fires nor
arms a trailing stop faithfully, the records do. The contingency book is read from the replay
core's exit `Snap` instead, because it is driven purely by journaled fills. The origin map is
folded from the `StrategySubmit` and `MintedSubmit` provenance already on disk (`fold_coid_mounts`),
which is what lets an order still resting across the restart book its eventual fill into the mount
that placed it. The caller pattern on its doc: rebuild the engine from the snapshot with the real
client, spawn the core with the restored session and books, point the journal at the same
directory so appends resume, and let venue [reconciliation](/docs/trader/concepts/reconciliation/)
repair whatever the venue saw while the process was down. Two residuals are declared: a trailing
arm re-arms at its last-snapshot extreme, slightly looser than it died, and re-tightens as live
data resumes; and on an unclean crash the attribution ledgers are the base `Snap`'s value, the gap
showing in the published residual row rather than vanishing.

## The tool [#the-tool]

`crates/vike-core/src/bin/replay_journal.rs` is `replay_offline` at a command line:

```sh
cargo run -p vike-core --bin replay_journal -- <journal-dir>
```

It prints the source journal's total record count, the number of snapshots verified (one — the
final hash), the reproduced hash, and one line per engine with open orders, positions and balance;
a failure prints `REPLAY FAILED` with the error and exits 1. The replay core's own journal is a
fresh directory under the system temp directory, removed on every path including a panic. The
[binary page](/docs/trader/reference/binaries/replay-journal) and the
[determinism tutorial](/docs/trader/tutorials/journal-replay-determinism) run it end to end.


# Segments (/docs/trader/concepts/journal/segments)



A journal directory holds numbered segment files, `journal-{idx:08}.vjl`, each pre-sized to
`segment_bytes` (64 MiB at the default) and zero-filled. `crates/vike-core/src/journal/segment.rs`
owns the naming and the block reservation; the lifecycle — mapping, preparing the successor, the
roll — stays with the writer in `crates/vike-core/src/journal/writer.rs`, because it is inseparable
from the `CommandJournal` state it swaps. Sequence numbers are global across segments: each
segment's header stamps its `first_seq`, and each roll carries the seq forward.

## The staging name is load-bearing [#the-staging-name-is-load-bearing]

Every scanner in the module resolves a segment index by stripping the `journal-` prefix and the
`.vjl` suffix — the resume scan in `open`, `latest_segment_version`, `read_since`,
`prune_before_latest_snap`. A segment under construction lives at `journal-{idx:08}.vjl.prep`
(`prep_path`), which fails that suffix and is invisible to all of them. Were it named `.vjl`, a
crash between preparation and roll would leave an empty highest-index segment; `open` would resume
into it, find no magic, treat it as fresh and stamp `first_seq = 0` — restarting the sequence at
zero while earlier segments hold higher seqs. A leftover `.prep` after a crash is inert; the next
preparation truncates and reuses it. The `LOCK` sentinel from
[Locking](/docs/trader/concepts/journal/locking) is invisible for the same reason.

## Pre-allocation, and why it is a window [#pre-allocation-and-why-it-is-a-window]

`std::fs::File::set_len` only moves the size marker; the extents stay unallocated, so the
filesystem defers each block allocation to the first write fault on that page — landing it on the
append path the [latency gate](/docs/trader/concepts/latency-gate) measures. `reserve_blocks` calls
`posix_fallocate` at open so that work moves to one metadata operation. Measured against this
journal, a sparse segment took 3–9 appends over 100 µs with a 220 µs maximum; reserved, 0–1 and
about 40 µs. It is deliberately infallible: a filesystem with no `fallocate` degrades to sparse
rather than refusing to open, and on Windows it is a no-op.

Reservation removes the allocation from the fault, not the fault itself. A shared mapping starts
with no page-table entries, so the first store into each 4 KiB page still traps into the kernel.
`warm_ahead` populates those entries writable with `MADV_POPULATE_WRITE` — not `WILLNEED` or
`MAP_POPULATE`, which populate for reading and still trap on the first write. Warming a 256 MiB
segment whole cost 694 ms at open against a 1.7 ms baseline, to serve a run that touched 9 MiB of
it, which is why it is a window. `warm_ahead_bytes` sizes that window from the sync chunk — four
chunks, floored at 8 MiB — so it outlasts one blocking `msync` plus the chunk that follows. The
fixed 8 MiB it replaced was outrun every chunk: the appender runs at roughly 430 MB/s while the
syncer's `msync` blocks for 36–141 ms, and the refresh was aimed at the synced watermark, behind a
cursor that had already run past it. The A/B of that fix, medians over eight interleaved reps on
the reserved-core box, took the `journal` variant's p99.9 from 37 150 ns to 3 342 ns — where the
journal-free baseline's own p99.9 of 3–7 µs sits. The cost is at open, 41 ms to 135 ms on a
256 MiB segment as the window grew from 8 to 64 MiB and one eighth of that for the production
segment, paid once at session start and on the syncer thread for every segment after the first. A
kernel below 5.14 has no `MADV_POPULATE_WRITE` and degrades to first-touch faults; Windows has no
`madvise` at all.

## The roll [#the-roll]

When a frame would not fit, `write_framed` calls `roll`. Reserving a 64 MB segment inline
measured a median 1.7 ms (max 2.8 ms) against about 160 µs for a bare size-and-map, and `roll`
runs inside the append path — so `map_segment` is called with `reserve = false` there, and the
reservation happens ahead of time instead. Once the live segment crosses `PREP_WATERMARK_PCT`
(75 %), `prepare_next` spawns one worker thread, `vjl-prep`, to size and reserve the successor
under its staging name; on a 64 MB segment that leaves roughly 150 000 appends against about
1.7 ms of work, and a journal that never fills a segment never spawns it. The roll joins the
worker (so nothing is still resizing a file about to be mapped), renames the `.prep` file into
place if it is the right size, maps it, and moves two things across: the directory lock — without
that move the guard would be released on the first roll — and the syncer, which is handed the new
mapping and told to seal the old one. What is no longer in `roll` is the whole-segment `msync`
that used to open it, 292 ms (max 432 ms) on a dirty 64 MB segment, on the fold thread. The same
`msync` still happens on the same bytes; only the thread changed — see
[Sync policy](/docs/trader/concepts/journal/sync-policy), which also warms the rolled segment's window
after the seal.

## Resume [#resume]

`open` finds the highest existing index, maps it, and walks its frames to find the cursor and the
next seq. The sync debt is rebased onto that cursor on both sides, because those bytes were already
written by whoever appended them and re-syncing a nearly full segment at startup would move the
very stall the chunking exists to prevent. The warm window is re-aimed at the resumed cursor for
the same reason. A supported older version is restamped to the current one, since every frame
already in it is a valid frame under the additive rule on the [index](/docs/trader/concepts/journal).

## Pruning [#pruning]

`prune_before_latest_snap` deletes whole segment files that the latest checkpoint fully
supersedes: those whose maximum record seq is strictly below the latest `Snap`'s seq. It never
touches the segment holding that `Snap` or any later one, which carry the restore base and its
tail. It is conservative — a segment whose records cannot be positively bounded (unreadable, no
magic, torn from the start, empty) is kept — and it honours a second floor: when a materializer
checkpoint exists, no segment holding records past that checkpoint is dropped, so the
[trade log](/docs/trader/concepts/journal/reading) can still be fed from any surviving segment.

<Callout type="warn" title="Prune with no live core in the directory, and expect growth on an idle core">
  Call the prune only when no core is journaling into the directory — at a successful restart,
  before re-opening — because deleting a segment another handle has mapped fails on Windows. And
  `snapshot_every` counts folded commands; `PortfolioSnap` records deliberately do not bump it. An
  otherwise idle journaling core therefore never writes a cadence `Snap`, so there is no floor to
  prune to and segments accumulate until the shutdown `Snap`. `CoreConfig::portfolio_snapshot_interval`'s
  own doc puts a number on it: a one-second cadence on a silent weekend is about 86 000 unprunable
  records a day. Size that cadence in seconds to minutes, not sub-second.
</Callout>


# Sync policy (/docs/trader/concepts/journal/sync-policy)



`crates/vike-core/src/journal/sync.rs` opens with the sentence the rest of the journal is built
around: every blocking `msync` this journal performs happens in that file, on a thread the
appender never joins. The reason is where the appender runs. `CommandJournal` is appended to from
the [execution core](/docs/trader/concepts/execution-core)'s fold thread, the one the
[latency gate](/docs/trader/concepts/latency-gate) holds to a `p99 < 10µs` core hop, and an `msync`
costs time proportional to dirty bytes — measured at about 8.6 ms for 1 MB, 100 ms for 16 MB, and
292 ms (max 432 ms) for a dirty 64 MB segment.

## Three stalls that used to be inline [#three-stalls-that-used-to-be-inline]

The parent module's header lists them, each found by measurement rather than by reading. The
per-chunk sync in `write_framed` put a single stall of about 141 ms into the measured hop, at hop
58 518 of 100 000. `roll`'s opening whole-segment flush was the 292 ms one. And the checkpoint
flush ending every cadence `Snap` — `CoreThread::write_snap` calling `CommandJournal::flush` —
survived the first fix, because the latency harness pinned `snapshot_every` to never fire while
the production default is 1024. Once looked for: the `journal-snap` variant's p99.9 was 153.9 µs
against 38.6 µs, its maximum 14.1 ms against 77.7 µs, with 102 hops over 100 µs — one per
snapshot, the worst around 1 400 times the budget. All three now go through
`CommandJournal::queue_sync`, and that variant stays a gate so the call cannot come back unnoticed.

## A watermark, not a queue [#a-watermark-not-a-queue]

The appender's hand-off is `Syncer::request`: store the target byte offset into
`SyncShared::target`, swap a `wake_pending` flag, and send one `Wake` if no wake is already queued.
That is the entirety of what a chunk boundary costs the fold — one atomic store, one atomic swap,
at most one channel send; never an `msync`, never a wait. The design holds because the work is a
*watermark*: `target` is a monotonic offset, the syncer always reads the newest value when it gets
round to it, so a wake that coalesces with an earlier one drops no work. The backlog therefore
cannot grow no matter how far behind the disk falls, which is why the appender never has to block
to apply back-pressure. The channel is unbounded and carries at most one un-consumed wake plus one
message per segment roll.

<Callout type="warn" title="Adding a wait, an msync, or a blocking send to the append side reintroduces the defect — and the unit tests cannot catch it">
  The tests at the bottom of `sync.rs` pin that each of the three `msync` sites still happens and
  happens on the syncer (counters written by that thread and nowhere else), and that the data
  survives. What no unit test there proves is the latency claim: "the appender does not wait" needs
  a slow disk and a measured hop. The gate for that is `crates/vike-core/tests/runtime_latency.rs`'s
  journal variant. `CommandJournal::flush` — the blocking whole-mapping `msync` — survives for tools
  and tests that want a barrier on their own thread, and no fold-path caller may be added back; a
  new site that wants a checkpoint wants `queue_sync`.
</Callout>

## How much is owed at once [#how-much-is-owed-at-once]

`sync_chunk_bytes` bounds the un-synced debt at one sixteenth of the segment
(`SYNC_CHUNK_DIVISOR`), floored at 4 MiB (`SYNC_CHUNK_MIN`) — 4 MiB on the production 64 MiB
segment. It is a fraction for a measured reason: a fixed 4 MiB made every journal pay, including
ones that never roll and so have no seal to bound, and while the sync was inline it put about
three forced syncs of roughly 30 ms each into the gate, at a hop index that was exactly the chunk
boundary. A fraction keeps a constant sixteen syncs per segment whatever the size, and a segment
smaller than the floor never forces a sync at all. Deferring until a segment is nearly full does
not remove the work, it concentrates it into a burst the syncer can fall behind on. The checkpoint
reuses the same watermark — "sync up to the snap" and "sync up to this boundary" are one statement
about a different offset — and at the production defaults it fires about fourteen times more often
than the chunk (1024 records at roughly 287 B is about 287 KB): smaller, more frequent `msync`s,
and a syncer that falls behind coalesces the extra wakes.

## The thread's three jobs [#the-threads-three-jobs]

`run_syncer` is panic-free by construction; an `msync` failure is logged and retried on the next
wake, never unwrapped, and the region stays owed. On a `Wake` it warms the page-table window ahead
of the *appender's* cursor, flushes the owed range, then warms again aimed at wherever the appender
is now — the before-flush warm is the half that carries the fold thread through a 36–141 ms
`msync`, and `warm_from` takes the maximum of appender and watermark so a clamped target can never
aim the window backwards. [Segments](/docs/trader/concepts/journal/segments) carries that measurement.
On a `Roll` it seals the segment it holds with one whole-segment flush, adopts the new mapping and
warms it; `Syncer::hand_over` rebases `target` to the header offset *before* sending, so a stale
old-segment watermark can never mark fresh bytes as synced. When the channel closes it drains,
performs one final whole-segment flush and exits. One thread serves a directory for its whole
life; `roll` moves the handle rather than respawning, and a vanished syncer is warned about once —
durability degrades to kernel writeback.

## What a graceful stop guarantees, and what durability was never about [#what-a-graceful-stop-guarantees-and-what-durability-was-never-about]

`Syncer::shutdown_and_join` publishes the final watermark, drops the sender and joins. The join is
the point: `recv` returns an error only once the queue is drained and every sender is gone, so the
final flush covers the tail, and a shutdown that is about to prune the directory or hand it to a
reader finds the bytes on disk. `CoreThread::run` takes itself by value, so the teardown `Snap` is
appended and the whole journal drops inside the core thread — the final `msync` completes before
`CoreHandle::shutdown_and_join` returns.

A snap is not more durable than any other record, and never was. The mapped pages belong to the
page cache: a process crash, an OOM kill and a clean reboot lose nothing with zero `msync`; only a
hard power cut loses the un-synced tail, a torn tail already stops
[reading](/docs/trader/concepts/journal/reading) at the last valid record, and the lost tail is
repaired by venue reconcile. The blocking checkpoint flush bought ordering against nothing — an
`msync` of one range implies nothing about later pages — and readability against nothing either,
since a reader sees the page cache, not the disk. The sync is latency shaping.


# CFD (/docs/trader/concepts/instruments/cfd)




**CFD** — a contract for difference: the price move without the underlying. It is one of 11 asset classes in Vike Trader's taxonomy
(`vike_catalog::AssetClass`), and every instrument carries exactly one.

The taxonomy is deliberately an enum over one parametric `Instrument`, not a type per product.
That is the modelling decision the whole [instruments](/docs/trader/concepts/instruments) tree turns on:
an instrument is a row of properties — tick size, lot step, minimum notional, session calendar —
and its class says how to read them, rather than a separate Rust type per product with its own
duplicated placement rules.

## What the class drives [#what-the-class-drives]

* **The Symbol picker**: this class appears under the **Forex** tab.
* **Symbology**: what a symbol for this class looks like per venue, and which field map decodes it.
* **Market hours**: which session calendar applies, and therefore when an order can rest.

## Where this comes from [#where-this-comes-from]

`vike_catalog::AssetClass` and its picker-tab mapping, exported as `rosters.json` at every
release. Which venues carry which class is a property of each venue's catalog rather than of the
class, so it is on the [venue pages](/docs/trader/venues) instead of here.


# Crypto future (/docs/trader/concepts/instruments/crypto-future)




**Crypto future** — a dated crypto futures contract, which expires and settles. It is one of 11 asset classes in Vike Trader's taxonomy
(`vike_catalog::AssetClass`), and every instrument carries exactly one.

The taxonomy is deliberately an enum over one parametric `Instrument`, not a type per product.
That is the modelling decision the whole [instruments](/docs/trader/concepts/instruments) tree turns on:
an instrument is a row of properties — tick size, lot step, minimum notional, session calendar —
and its class says how to read them, rather than a separate Rust type per product with its own
duplicated placement rules.

## What the class drives [#what-the-class-drives]

* **The Symbol picker**: this class appears under the **Perps** tab.
* **Symbology**: what a symbol for this class looks like per venue, and which field map decodes it.
* **Market hours**: which session calendar applies, and therefore when an order can rest.

## Where this comes from [#where-this-comes-from]

`vike_catalog::AssetClass` and its picker-tab mapping, exported as `rosters.json` at every
release. Which venues carry which class is a property of each venue's catalog rather than of the
class, so it is on the [venue pages](/docs/trader/venues) instead of here.


# Crypto perpetual (/docs/trader/concepts/instruments/crypto-perp)




**Crypto perpetual** — a perpetual swap: a futures-like contract with no expiry, held in line with spot by a periodic funding payment. It is one of 11 asset classes in Vike Trader's taxonomy
(`vike_catalog::AssetClass`), and every instrument carries exactly one.

The taxonomy is deliberately an enum over one parametric `Instrument`, not a type per product.
That is the modelling decision the whole [instruments](/docs/trader/concepts/instruments) tree turns on:
an instrument is a row of properties — tick size, lot step, minimum notional, session calendar —
and its class says how to read them, rather than a separate Rust type per product with its own
duplicated placement rules.

## What the class drives [#what-the-class-drives]

* **The Symbol picker**: this class appears under the **Perps** tab.
* **Symbology**: what a symbol for this class looks like per venue, and which field map decodes it.
* **Market hours**: which session calendar applies, and therefore when an order can rest.

## Where this comes from [#where-this-comes-from]

`vike_catalog::AssetClass` and its picker-tab mapping, exported as `rosters.json` at every
release. Which venues carry which class is a property of each venue's catalog rather than of the
class, so it is on the [venue pages](/docs/trader/venues) instead of here.


# Crypto spot (/docs/trader/concepts/instruments/crypto-spot)




**Crypto spot** — a crypto asset bought and held outright, settled on delivery. It is one of 11 asset classes in Vike Trader's taxonomy
(`vike_catalog::AssetClass`), and every instrument carries exactly one.

The taxonomy is deliberately an enum over one parametric `Instrument`, not a type per product.
That is the modelling decision the whole [instruments](/docs/trader/concepts/instruments) tree turns on:
an instrument is a row of properties — tick size, lot step, minimum notional, session calendar —
and its class says how to read them, rather than a separate Rust type per product with its own
duplicated placement rules.

## What the class drives [#what-the-class-drives]

* **The Symbol picker**: this class appears under the **Crypto** tab.
* **Symbology**: what a symbol for this class looks like per venue, and which field map decodes it.
* **Market hours**: which session calendar applies, and therefore when an order can rest.

## Where this comes from [#where-this-comes-from]

`vike_catalog::AssetClass` and its picker-tab mapping, exported as `rosters.json` at every
release. Which venues carry which class is a property of each venue's catalog rather than of the
class, so it is on the [venue pages](/docs/trader/venues) instead of here.


# Equity (/docs/trader/concepts/instruments/equity)




**Equity** — a share in a company, traded on a stock exchange. It is one of 11 asset classes in Vike Trader's taxonomy
(`vike_catalog::AssetClass`), and every instrument carries exactly one.

The taxonomy is deliberately an enum over one parametric `Instrument`, not a type per product.
That is the modelling decision the whole [instruments](/docs/trader/concepts/instruments) tree turns on:
an instrument is a row of properties — tick size, lot step, minimum notional, session calendar —
and its class says how to read them, rather than a separate Rust type per product with its own
duplicated placement rules.

## What the class drives [#what-the-class-drives]

* **The Symbol picker**: this class appears under the **Stocks** tab.
* **Symbology**: what a symbol for this class looks like per venue, and which field map decodes it.
* **Market hours**: which session calendar applies, and therefore when an order can rest.

## Where this comes from [#where-this-comes-from]

`vike_catalog::AssetClass` and its picker-tab mapping, exported as `rosters.json` at every
release. Which venues carry which class is a property of each venue's catalog rather than of the
class, so it is on the [venue pages](/docs/trader/venues) instead of here.


# ETF (/docs/trader/concepts/instruments/etf)




**ETF** — an exchange-traded fund — a basket that trades like a share. It is one of 11 asset classes in Vike Trader's taxonomy
(`vike_catalog::AssetClass`), and every instrument carries exactly one.

The taxonomy is deliberately an enum over one parametric `Instrument`, not a type per product.
That is the modelling decision the whole [instruments](/docs/trader/concepts/instruments) tree turns on:
an instrument is a row of properties — tick size, lot step, minimum notional, session calendar —
and its class says how to read them, rather than a separate Rust type per product with its own
duplicated placement rules.

## What the class drives [#what-the-class-drives]

* **The Symbol picker**: this class appears under the **Stocks** tab.
* **Symbology**: what a symbol for this class looks like per venue, and which field map decodes it.
* **Market hours**: which session calendar applies, and therefore when an order can rest.

## Where this comes from [#where-this-comes-from]

`vike_catalog::AssetClass` and its picker-tab mapping, exported as `rosters.json` at every
release. Which venues carry which class is a property of each venue's catalog rather than of the
class, so it is on the [venue pages](/docs/trader/venues) instead of here.


# Future (/docs/trader/concepts/instruments/future)




**Future** — a dated contract on an underlying, traded on a futures exchange. It is one of 11 asset classes in Vike Trader's taxonomy
(`vike_catalog::AssetClass`), and every instrument carries exactly one.

The taxonomy is deliberately an enum over one parametric `Instrument`, not a type per product.
That is the modelling decision the whole [instruments](/docs/trader/concepts/instruments) tree turns on:
an instrument is a row of properties — tick size, lot step, minimum notional, session calendar —
and its class says how to read them, rather than a separate Rust type per product with its own
duplicated placement rules.

## What the class drives [#what-the-class-drives]

* **The Symbol picker**: this class appears under the **Futures** tab.
* **Symbology**: what a symbol for this class looks like per venue, and which field map decodes it.
* **Market hours**: which session calendar applies, and therefore when an order can rest.

## Where this comes from [#where-this-comes-from]

`vike_catalog::AssetClass` and its picker-tab mapping, exported as `rosters.json` at every
release. Which venues carry which class is a property of each venue's catalog rather than of the
class, so it is on the [venue pages](/docs/trader/venues) instead of here.


# FX (/docs/trader/concepts/instruments/fx)




**FX** — a currency pair, quoted one currency against another. It is one of 11 asset classes in Vike Trader's taxonomy
(`vike_catalog::AssetClass`), and every instrument carries exactly one.

The taxonomy is deliberately an enum over one parametric `Instrument`, not a type per product.
That is the modelling decision the whole [instruments](/docs/trader/concepts/instruments) tree turns on:
an instrument is a row of properties — tick size, lot step, minimum notional, session calendar —
and its class says how to read them, rather than a separate Rust type per product with its own
duplicated placement rules.

## What the class drives [#what-the-class-drives]

* **The Symbol picker**: this class appears under the **Forex** tab.
* **Symbology**: what a symbol for this class looks like per venue, and which field map decodes it.
* **Market hours**: which session calendar applies, and therefore when an order can rest.

## Where this comes from [#where-this-comes-from]

`vike_catalog::AssetClass` and its picker-tab mapping, exported as `rosters.json` at every
release. Which venues carry which class is a property of each venue's catalog rather than of the
class, so it is on the [venue pages](/docs/trader/venues) instead of here.


# Index (/docs/trader/concepts/instruments/index-instrument)




**Index** — a computed level rather than a tradable deliverable. It is one of 11 asset classes in Vike Trader's taxonomy
(`vike_catalog::AssetClass`), and every instrument carries exactly one.

The taxonomy is deliberately an enum over one parametric `Instrument`, not a type per product.
That is the modelling decision the whole [instruments](/docs/trader/concepts/instruments) tree turns on:
an instrument is a row of properties — tick size, lot step, minimum notional, session calendar —
and its class says how to read them, rather than a separate Rust type per product with its own
duplicated placement rules.

## What the class drives [#what-the-class-drives]

* **The Symbol picker**: this class appears under the **Indices** tab.
* **Symbology**: what a symbol for this class looks like per venue, and which field map decodes it.
* **Market hours**: which session calendar applies, and therefore when an order can rest.

<Callout type="warn" title="The slug is index-instrument">
  This class is `AssetClass::Index` in the code and `index-instrument` everywhere a page is keyed on it. A member slugged `index` would shadow its own tree's landing page, so the exporter renders the longer form and asserts it.
</Callout>

## Where this comes from [#where-this-comes-from]

`vike_catalog::AssetClass` and its picker-tab mapping, exported as `rosters.json` at every
release. Which venues carry which class is a property of each venue's catalog rather than of the
class, so it is on the [venue pages](/docs/trader/venues) instead of here.


# Instruments (/docs/trader/concepts/instruments)



Every tradable thing in Vike Trader is the same Rust record. `vike-catalog` describes itself as the
"universal cross-venue instrument catalog" and is deliberately bridge-free — it depends on
`vike-model` only, so the per-venue bridge crates and the chart crate can all depend on it
down-only (`crates/vike-catalog/src/lib.rs`). It holds the `Instrument` model, the `AssetClass`
taxonomy, a two-mode `CatalogProvider` trait, a declarative venue registry, and the tiered fuzzy
search the Symbol picker renders from.

## One record, not twenty types [#one-record-not-twenty-types]

`crates/vike-catalog/src/instrument.rs`'s `Instrument` is seven fields: `venue`, `raw_symbol`,
`asset_class`, `base`, `quote`, `description`, and a `SymbolProperties` grid that "may be `Default`
until fetched". Product differences are carried in those fields and in the class tag, not in a type
hierarchy — the `AssetClass` doc states its whole job in one line: it "drives picker tabs,
symbology expectations, and market-hours". Those three consequences are the three pages beside this
one: [symbology](/docs/trader/concepts/instruments/symbology), the placement grid on
[symbol properties](/docs/trader/concepts/instruments/symbol-properties), and
[sessions](/docs/trader/concepts/instruments/sessions).

Identity follows a `{symbol}.{venue}` shape. `Instrument::id` renders `format!("{}.{}",
raw_symbol, venue.to_uppercase())` — `BTCUSDT.BINANCE`, `AAPL.ALPACA`. A derivative stays distinct
from its spot twin because its `raw_symbol` is already distinct: OKX's dashed `BTC-USDT-SWAP`,
Deribit's instrument names, and a `.P`-suffixed perp symbol on the venues that reuse one string for
both. No extra product suffix is applied at `id()` time: the body is that one `format!`, and the
test `id_disambiguates_perp_from_spot_via_distinct_raw_symbol` in the same file pins distinctness
to `raw_symbol`. The opening line of that method's own rustdoc still describes an earlier design in
which `id()` appended `.P`/`.F`/`.O`; the code under it does not.

## Eleven classes, eight tabs [#eleven-classes-eight-tabs]

`crates/vike-model/src/asset_class.rs`'s `AssetClass` has eleven variants: `Equity`, `Etf`,
`CryptoSpot`, `CryptoPerp`, `CryptoFuture`, `Option`, `Fx`, `Future`, `Index`, `PredictionMarket`,
`Cfd`. Each has its own page in this section.

`AssetClass::tab` folds them onto eight picker tabs: Stocks takes `Equity` and `Etf`; Forex takes
`Fx` and `Cfd`; Crypto takes `CryptoSpot`; &#x2A;*Perps takes both `CryptoPerp` and `CryptoFuture`**;
Options, Futures, Indices and Prediction take their single class each. The "All" tab is not a `Tab`
variant — it is `Option::None` in a filter, which the `Tab` doc says outright.

<Callout title="The Index class is slugged index-instrument">
  `AssetClass::Index` is documented at
  [index-instrument](/docs/trader/concepts/instruments/index-instrument), because the `index` slug is this
  page.
</Callout>

## How a venue contributes [#how-a-venue-contributes]

`crates/vike-catalog/src/provider.rs`'s `CatalogProvider` is the venue contribution seam: `venue()`,
`asset_classes()` and `mode()` are required, while `list_instruments` and `search_remote` both ship
default impls returning an empty vector, so a venue implements only the half its mode uses.

`CatalogMode` has two variants, and its doc says the choice is made by "API shape + size, NOT asset
class":

* **`Enumerable`** — a bulk list endpoint and a cacheable universe, so the whole set is fetched
  once and searched locally. Bybit's provider, for instance, reads the keyless public
  `/v5/market/instruments-info` with unsigned GETs for `category=spot` and `category=linear`
  (`crates/bridges/bybit/src/catalog.rs`).
* **`QueryBacked`** — no bulk endpoint, or a universe too big for one (the provider doc names IBKR
  as the case). The venue's own server is searched per query and nothing is cached.

`CatalogSource` is the orthogonal client-side axis — `Direct` or `ServerBacked` — and its doc marks
the server-backed path as a later phase, with the type present now so the design is stable.

Providers are constructed by hand per binary. `crates/vike-model/src/venues.rs` says so plainly:
there is no central provider registry to enumerate, which is why `BRIDGE_VENUES` is a flat slug
list rather than something derived from the impls. That list is literally `vike_model::VENUES`, the
canonical roster the [venue pages](/docs/trader/venues) are generated from, and a set-equality test
(`mirrors_the_canonical_roster`) fails if a future edit ever re-points it at a private copy. It once
had a private copy: Hyperliquid's bridge merged without being added here, so that venue never
appeared in the credential grid at all.

## Search and cache [#search-and-cache]

`crates/vike-catalog/src/catalog.rs`'s `tier` ranks a hit in five bands — exact symbol, symbol
prefix, base prefix, substring, no match — and `quote_rank` breaks ties among equal-tier hits in
the order USDT, USDC, USD, BTC, everything else.

The Enumerable half is cached on disk as a `CatalogCache` plus one `VenueStamp` per venue.
`crates/vike-catalog/src/persist.rs` states the refresh discipline: the cache is "loaded instantly
at startup; rewritten only on an explicit user refresh (no auto/background re-fetch)", and
QueryBacked venues are never cached. Each stamp carries the venue, its last refresh time and its
instrument count, which is what the [Data Manager catalog view](/docs/trader/gui/data-manager/catalog)
renders.


# Option (/docs/trader/concepts/instruments/option)




**Option** — a contract giving the right, not the obligation, to trade at a strike. It is one of 11 asset classes in Vike Trader's taxonomy
(`vike_catalog::AssetClass`), and every instrument carries exactly one.

The taxonomy is deliberately an enum over one parametric `Instrument`, not a type per product.
That is the modelling decision the whole [instruments](/docs/trader/concepts/instruments) tree turns on:
an instrument is a row of properties — tick size, lot step, minimum notional, session calendar —
and its class says how to read them, rather than a separate Rust type per product with its own
duplicated placement rules.

## What the class drives [#what-the-class-drives]

* **The Symbol picker**: this class appears under the **Options** tab.
* **Symbology**: what a symbol for this class looks like per venue, and which field map decodes it.
* **Market hours**: which session calendar applies, and therefore when an order can rest.

## Where this comes from [#where-this-comes-from]

`vike_catalog::AssetClass` and its picker-tab mapping, exported as `rosters.json` at every
release. Which venues carry which class is a property of each venue's catalog rather than of the
class, so it is on the [venue pages](/docs/trader/venues) instead of here.


# Prediction market (/docs/trader/concepts/instruments/prediction-market)




**Prediction market** — a binary outcome that settles at 0 or 1 — a probability you can trade. It is one of 11 asset classes in Vike Trader's taxonomy
(`vike_catalog::AssetClass`), and every instrument carries exactly one.

The taxonomy is deliberately an enum over one parametric `Instrument`, not a type per product.
That is the modelling decision the whole [instruments](/docs/trader/concepts/instruments) tree turns on:
an instrument is a row of properties — tick size, lot step, minimum notional, session calendar —
and its class says how to read them, rather than a separate Rust type per product with its own
duplicated placement rules.

## What the class drives [#what-the-class-drives]

* **The Symbol picker**: this class appears under the **Prediction** tab.
* **Symbology**: what a symbol for this class looks like per venue, and which field map decodes it.
* **Market hours**: which session calendar applies, and therefore when an order can rest.

## Where this comes from [#where-this-comes-from]

`vike_catalog::AssetClass` and its picker-tab mapping, exported as `rosters.json` at every
release. Which venues carry which class is a property of each venue's catalog rather than of the
class, so it is on the [venue pages](/docs/trader/venues) instead of here.


# Sessions and market hours (/docs/trader/concepts/instruments/sessions)



Before `SessionCalendar&#x60; existed, nothing in the workspace could answer &#x2A;"is this venue open at
`ts`?"*. `crates/vike-model/src/session.rs` records what that cost: the FX week existed as a prose
comment in one venue's live-smoke test, live execution discovered a closed market only as a venue
**rejection**, and a backtest discovered it only as a data **gap** — two discovery mechanisms for
one fact.

The shape is policy as data plus one pure query: a declarative table, and `SessionCalendar::is_open`.
There is deliberately no second session codepath — a consumer either calls that query or it is not
consulting the law.

## Week-minutes, no timezone database [#week-minutes-no-timezone-database]

A calendar is a set of half-open `SessionSegment`s over the trading week, measured in minutes since
Monday 00:00 UTC (`0 .. 10_080`). Timestamps are epoch-ms UTC, and the only calendar arithmetic is
the day division `vike-model` already owns — no `chrono`, no tz database, no hand-rolled civil math.
Resolution is one minute. Segments never wrap, so a session spanning Sunday into Monday is declared
as *two* segments, which keeps every query an ordered scan with no modular interval arithmetic.

Three rows cover the roster:

* **`CRYPTO_24_7`** — binance, bybit, okx, deribit, aster, hyperliquid, polymarket. No weekly close
  at all; the only interruptions are unscheduled maintenance windows, which a static calendar cannot
  predict and which surface as rejections or feed gaps anyway.
* **`FX_WEEK`** — dukascopy, oanda, ig, fxcm, ctrader. The boundary tracks the New York 17:00 close,
  which is 21:00 UTC under EDT and 22:00 UTC under EST, so the row opens at the earlier
  (Sunday 21:00 UTC) and closes at the later (Friday 22:00 UTC). The weekend gap it blocks is
  Friday 22:00 → Sunday 21:00 UTC.
* **`US_EQUITY_REGULAR`** — 09:30–16:00 `America/New_York`, Monday through Friday, declared in UTC
  as **13:30–21:00**, the union of the EDT and EST windows.

<Callout type="warn" title="The DST rule: under-block, never over-block">
  Where a real boundary moves with daylight saving, the declared segment is the **union*&#x2A; of both
  offsets. The module states the consequence once, for the whole table: &#x2A;"The gate may UNDER-block by
  up to one hour. It can never OVER-block."* Under-blocking leaves an hour of genuinely closed time
  looking open — the pre-existing behaviour, since nothing blocked at all before. Over-blocking would
  silently delete fills that really happened in-session and quietly corrupt a backtest.
</Callout>

Every resolver here is fail-**permissive**: an unpinned session answers `SessionCalendar::ALWAYS_OPEN`,
the deliberate opposite of the capability tables' fail-closed default. The module argues why the two
differ — a capability we cannot confirm must not be *offered*, but a session we have no data for
must not silently *block* a venue that in reality trades fine.

## Keyed by venue **and** asset class [#keyed-by-venue-and-asset-class]

The correct key is `(venue, asset class)`, never the venue alone. Alpaca trades cash equities and
24/7 crypto on one venue and IBKR is a global multi-asset book, so "what venue is this?" cannot
answer "when is it open?".

`AssetClass` is a `vike-catalog` concept and `vike-catalog` depends on `vike-model` down-only, so
the map cannot live beside the rows without inverting the layering. It lives one layer up instead:
`crates/vike-catalog/src/session.rs`'s `session_calendar_for` is the one keying site, and
`vike-model` takes the resolved calendar as a caller-supplied parameter. Continuous classes
(`CryptoSpot`, `CryptoPerp`, `CryptoFuture`, `PredictionMarket`) resolve 24/7 regardless of venue;
`Fx` and `Cfd` resolve the FX week; `Equity` and `Etf` resolve the US regular session for alpaca
and always-open for anything else. Listed options, futures and index products resolve 24/7 on the
crypto-native venues that `is_crypto_native` names — deribit, binance, bybit, okx, aster,
hyperliquid — and always-open elsewhere. So `(alpaca, CryptoSpot)` and `(alpaca, Equity)` return
different calendars from the same venue, and an IBKR equity, whose region is not inferable from
that pair, is left open rather than blocked wrongly.

`session_for(venue)` remains as the venue-only convenience default, and answers `ALWAYS_OPEN` for
the mixed-asset venues on purpose. `venue_is_open` composes the two for a "venue closed" badge and
is explicitly read-only: nothing in the live order path consults it today. `next_open` and
`next_close` answer "from when may I trade?", returning the given instant verbatim when it already
matches.

## The backtest gate [#the-backtest-gate]

`EngineParams::session_gate` is opt-in and defaults to `false`, which leaves every fill lane
byte-identical. Turned on, each *symbol* resolves to its own calendar and nothing on that symbol
fills on an event outside its session — resting orders, the tagged maker lane and protective stops
alike, on the frozen fill lanes and their opt-in queue-model tick twins. Resolution order is the
per-symbol `session_calendars` override, then `session_for(default_venue)`, then always-open. That
means the `(venue, asset class)` keying lives in the caller: build the map from
`session_calendar_for` per symbol. Enabling the knob with neither a default venue nor an override is
a silent no-op, not an error — a run whose `session_deferrals` stays `0` is how you see it. See
[the sim broker](/docs/trader/backtesting/sim-broker).

## Deliberately not built [#deliberately-not-built]

Holiday calendars and half-days are not modelled: every row is a plain recurring week, so a US
holiday reads as open. Non-US regional equity sessions and listed-derivative extended hours are
follow-ups, resolved fail-permissively until their rows land. `SessionState` has only `Open` and
`Closed` — no pre- or post-market variant, because no shipped row carries extended-hours data to
distinguish them with, and adding the variant first would be a field that is never set.


# Symbol properties (/docs/trader/concepts/instruments/symbol-properties)



`SymbolProperties` is the venue-neutral half of an instrument. Its module calls it "the per-symbol
order-placement bounds every venue REST parser fills from its own instrument endpoint", naming four
of them by shape: Binance `/exchangeInfo` filters, Bybit `lotSizeFilter`, OKX `tickSz`/`lotSz`,
Deribit `min_trade_amount` (`crates/vike-model/src/instrument.rs`). It lives in `vike-model` rather
than in the bridge crates because it is pure domain data consumed on the venue-neutral side of the
execution seam; each venue's parse function stays with its venue.

## The fields, and what a zero means [#the-fields-and-what-a-zero-means]

`tick_size`, `step_size`, `min_qty`, `max_qty` and `min_notional` are the original five. Three more
arrived later: `contract_size`, `tick_scheme` and `taker_hold_ms`.

Every field is `Default`-zero, and the convention is stated on the type: absent venue properties
stay `0.0&#x60;, so &#x2A;*`0.0` means "the venue did not constrain this"**, not "the constraint is zero".
`crates/vike-model/src/scalar.rs`'s `nz_step` is where that convention becomes a type — it turns
`0.0` into `None` and passes everything else through — and `round_to` then falls through to
identity for `None`, a zero step or a negative one.

<Callout type="warn" title="Never construct it with an exhaustive literal">
  Use functional-update syntax (`SymbolProperties { tick_size, step_size, ..Default::default() }`).
  The struct grows, and the type's own doc records the cost of the alternative: adding
  `taker_hold_ms` alone broke **14 crates / \~32 sites**. Two families deliberately keep the
  exhaustive literal, because there the compile error is the feature — the `vike-data`
  `kind=properties` Parquet codec, and this module's own serde round-trip tests. `#[non_exhaustive]`
  was considered and rejected: it forbids cross-crate functional update too.
</Callout>

## Contract size [#contract-size]

`contract_size` is the notional multiplier — how much underlying one unit of `qty` controls. A
Deribit BTC option is 1 BTC per contract and an ETH option 1 ETH, so true notional is
`|qty| * |price| * contract_size`. It follows the absent-is-zero convention rather than defaulting
to `1.0`, which keeps "the venue did not tell us" distinguishable from "the venue said 1.0";
`SymbolProperties::multiplier` is the one place absent folds to the inert `1.0`, and it treats
non-finite and non-positive values as absent too, so a malformed venue value can never zero out or
invert a notional cap.

## Tiered ticks [#tiered-ticks]

`tick_scheme` is an optional tiered price grid — the minimum increment as a *function* of price.
`None`, which its doc says is every venue but a Deribit option today, means the scalar `tick_size`
is the whole grid. Deribit's `public/get_instrument` returns `tick_size` plus `tick_size_steps`
(`0.0005` above `0.005` for BTC options), and a limit price above that boundary snapped onto the
base grid is venue-rejected. `effective_tick(price)` asks for the tick *at* a price;
`round_price(price)` is the tier-aware rounder, exactly the flat expression when no scheme is
attached.

<Callout type="warn" title="Attaching a scheme is a caller invariant">
  `with_tick_scheme` requires the scheme's `base_tick` to equal the scalar `tick_size`, because once
  a scheme is attached, `effective_tick` and `round_price` read the **scheme only** — the scalar
  stops participating in price rounding. Nothing in the type ties them together, so a mismatch is a
  silently wrong grid (wrong-tick prices on the wire, venue rejects) rather than a compile error.
  Only a `debug_assert` catches it; a release build trusts the caller, because this is on the order
  path.
</Callout>

## The venue's own hold [#the-venues-own-hold]

`taker_hold_ms` is how long the *exchange* deliberately sits on an incoming order before matching or
booking it. Its doc is emphatic that this is not a network estimate, not a tunable and not latency:
it is a property the venue declares per market. Polymarket declares it through two separate,
independent mechanisms, both measured live on 2026-07-23:

* **`itode` → 250 ms** on the crypto up/down markets. The flag lives only on the CLOB
  `clob-markets/{condition_id}` payload, not on `/markets/{condition_id}` and not on Gamma, so
  probing those makes crypto look delay-free. While the order is pending, a cancel is rejected; it
  survives a dropped connection, then is re-validated and either matched or placed on the book.
* **`seconds_delay` → 3 s** on sports *game* markets. **400 of 400** markets carrying a
  `game_start_time` report `seconds_delay: 3`, while 191 of 192 futures and props report `0` — the
  discriminator is exactly "has a game start".

## Who reads the grid [#who-reads-the-grid]

`crates/vike-exec/src/risk.rs`'s `RiskLimits::from_properties` maps four fields into the live gate —
`tick_size` to `tick_size`, `step_size` to `lot_size`, `min_qty` and `min_notional` unchanged — with
every other knob inheriting the `new()` defaults. `SymbolGrid::from_properties` is the per-leg twin
over the same four fields, and carries one asymmetry: there a `0.0` becomes `None`, and `None`
means *inherit the mount scalar*, not *unconstrained*. See
[risk and arming](/docs/trader/concepts/risk-and-arming).

Rounding to the grid is not the last step. `crates/vike-bridge-core/src/format.rs` notes that the
risk gate rounds to tick and lot but leaves IEEE artifacts — `0.30000000000000004` — that trigger
Binance `-1111 BAD_PRECISION`, so `format_to_step` quantizes **down** to the step's decimal places
and emits a plain, non-exponent string. Down, never up, so a limit is never overshot.

The same module flags the other half: the truncation is `(value / step).trunc()`, so a value one
ULP *below* a grid point emits a whole step less — silent, where an overshoot is what the venue
rejects.

Properties are also point-in-time data, recorded on the
[`kind=properties` series](/docs/trader/concepts/data/properties), where
`crates/vike-data/src/hist.rs`'s `properties_as_of` reads back the most recent observation at or
before a timestamp, so a replay rounds on the grid that was actually in force. One caveat survives
there: a part written before the tick-scheme column existed reads back `None`, so an old part is not
evidence that the parser emitted no scheme.


# Symbology (/docs/trader/concepts/instruments/symbology)



A **core symbol** names an instrument unambiguously across the whole workspace; an **exchange
symbol** is what goes on the wire. For most instruments they are identical, and
`crates/vike-catalog/src/symbol.rs` owns the conversion in one place.

## Where the two diverge [#where-the-two-diverge]

They diverge for perpetuals on venues whose raw symbol does not distinguish a perp from its spot
twin. Binance lists `BTCUSDT` on spot **and** `BTCUSDT` as a USDⓈ-M perp, so the core vocabulary
appends `PERP_SUFFIX` — `.P` — and calls the perp `BTCUSDT.P`. Siblings exist in the same convention
(`.F` for futures, `.O` for options), but the constant's doc records that no venue adapter maps them
today, so only `.P` is named.

`split_perp` is the conversion: `"BTCUSDT.P"` becomes `("BTCUSDT", true)`, `"BTCUSDT"` becomes
`("BTCUSDT", false)`. The returned symbol *borrows* from the input and is the wire form — URLs,
stream names, REST params — while the caller's original suffixed string stays the series and sink
label, so a perp's series key never collides with its spot twin's. It is a trailing marker only:
`BTC.PERP` and `XPUSDT` are not perps.

<Callout type="warn" title="Why this is a module and not an idiom">
  It was an idiom, written out at **eight call sites across three bridges**, twice behind a local
  helper under a different name. Every one of them was correct. The bug that motivated the module is
  the site that did none of it: Binance's depth feed passed the raw core symbol straight into its
  stream-name builder, producing `btcusdt.p@depth@100ms` — a stream no venue resolves. It connected,
  streamed nothing, and the recorder wrote placeholder rows for hours without a single error. An idiom
  repeated eight times cannot be checked; a named function with one home can be grepped for, and its
  absence at a wire-facing call site is visible.
</Callout>

## Which venues suffix [#which-venues-suffix]

`uses_perp_suffix` answers per venue, and today the suffixing venues are **binance, bybit and
aster**. It is declared rather than inferred, so a new venue trips the roster test until somebody
decides which side it is on. `false` does not mean "no perps" — it means the venue's own symbols are
already unambiguous, so a suffix would be noise the adapter would immediately strip again. Two
worked cases, both read from their adapters:

* **OKX** uses dashed instIds, `BTC-USDT` for spot against `BTC-USDT-SWAP` for the swap — a key
  namespace its catalog notes is distinct from Binance's concatenated one, so chart keys never
  collide (`crates/bridges/okx/src/catalog.rs`).
* **Hyperliquid** puts perps and spot in disjoint namespaces outright: a perp is the bare coin
  (`BTC`), a spot pair is `BASE/QUOTE` (`HYPE/USDC`), so `BTC.HYPERLIQUID` and
  `HYPE/USDC.HYPERLIQUID` cannot collide and no suffix is applied
  (`crates/bridges/hyperliquid/src/catalog.rs`).

## The fee lane [#the-fee-lane]

The same split keys the fee table. `fee_lane(venue, symbol)` returns the venue unchanged for a
single-lane venue, and a lane sub-key — `binance-perp`, `aster-perp`, `aster-perp-usd1` — for a `.P`
symbol on a dual-lane venue. A venue is dual-lane exactly when its `exec.rs` branches on the suffix.
Bybit uses the suffix but its exec is V5 linear-perp only, with no spot arm to route to, so its
single fee row already *is* its perp row.

Aster has three lanes rather than two: a live sweep of the venue's own `GET
/fapi/v3/commissionRate` across 17 symbols on 2026-08-05 found crypto at **4 bps**, equity/ETF/
commodity at **0.9 bps** and USD1-settled at **0.5 bps**. Only the USD1 class is decidable from the
symbol, because the settlement asset is part of the name (`BTCUSD1` settles in USD1, `BTCUSDT` in
USDT). The equity class is deliberately not resolved: `AAPLUSDT` and `ASTERUSDT` are the same string
shape, and only the venue's `exchangeInfo` separates them, so a pure string function has no honest
way to know.

<Callout type="warn" title="USD1 is matched as a suffix, never a substring">
  The match runs against the exchange symbol *after* the `.P` strip. `USD1USDT` is USDT-settled with
  USD1 as the base asset and must keep the crypto lane.
</Callout>

## The field map [#the-field-map]

Most Enumerable venues serve a flat JSON list, and `crates/vike-catalog/src/field_map.rs` turns that
into a declaration rather than a parser. A `FieldMap` names the `list_path` to walk, the `symbol`,
`base` and `quote` fields, and an optional `active` gate given as a `(field, expected)` pair — rows
whose field does not equal the expectation are skipped. `parse_with` produces `Instrument`s,
upper-casing symbol, base and quote, and returns an empty vector for a missing or malformed payload
rather than panicking. Venues whose payloads are nested, computed or protobuf skip the map and
provide their own parse function.

Binance and Aster share the same `exchangeInfo` grammar, so the mapping lives once in
`crates/bridges/binance/src/family/catalog.rs`, with the venue a caller-supplied parameter and the
endpoint URLs deliberately outside the module. Its `SPOT_MAP` walks `["symbols"]` and reads
`symbol`, `baseAsset`, `quoteAsset`, gated on `status == "TRADING"`. Bybit's `SPOT_MAP` walks
`["result", "list"]` and reads `symbol`, `baseCoin`, `quoteCoin`, gated on `status == "Trading"`.

Perp parsing is where the map runs out. Both venues need a second condition, each for its own
reason: Binance gates on `contractType == "PERPETUAL"` because delivery futures share its futures
endpoint, Bybit on `"LinearPerpetual"` because its `linear` category also lists inverse and other
contract types. So each is a small function instead, the documented escape hatch for a venue whose
"active" test needs more than one field. Binance's perp parser is also where the `.P` is stamped
on. Which venues carry which classes is on the [venue pages](/docs/trader/venues).


# Orders (/docs/trader/concepts/orders)



An order leaves a strategy as an `OrderRequest` — the single serde schema authority for order
intents, `crates/vike-model/src/order.rs`'s `OrderRequest` — whose `order_type` is a plain `String`.
The canonical vocabulary that string is drawn from has five words, and
`crates/vike-model/src/venue_caps.rs`'s `ORDER_KINDS` is the authority for it: "every canonical
`OrderRequest.order_type` string the platform produces, lowercase — the vocabulary
`preflight_order` classifies". The field's own comment in `order.rs` names four of them —
`stop_limit`, which alpaca and hyperliquid both declare, is the one it omits.

* [Market](/docs/trader/concepts/orders/market) — `market`
* [Limit](/docs/trader/concepts/orders/limit) — `limit`
* [Stop](/docs/trader/concepts/orders/stop) — `stop`
* [Stop-limit](/docs/trader/concepts/orders/stop-limit) — `stop_limit`
* [Take-profit](/docs/trader/concepts/orders/take-profit) — `take_profit`

These names are Vike Trader's, not any exchange's wire strings; a bridge translates them at the
edge. A string *outside* the list is deliberately not refused — the `ORDER_KINDS` doc says "a string
OUTSIDE this list is deliberately NOT preflight-refused (no declared row can know it) — the
venue-side path keeps owning it".

## Triggers are a subset, and an empty row is a refusal [#triggers-are-a-subset-and-an-empty-row-is-a-refusal]

`TRIGGER_KINDS` is declared as "the trigger subset of `ORDER_KINDS`": `stop`, `stop_limit`,
`take_profit`. The venue holds the trigger, and `crates/vike-model/src/venue_caps.rs`'s
`TriggerType` has exactly two variants — `StopLoss` (`order_type: "stop"`, `trigger_price` armed
venue-side, firing "as market, or as limit where the adapter also wires a `stop_limit` kind") and
`TakeProfit` (whose doc names hyperliquid's `tpsl:"tp"` as "the one adapter that wires it natively
today"). An EMPTY `trigger_types` slice means trigger orders are unsupported on that adapter: the
preflight refuses them "rather than letting a 'stop' silently coerce into an immediate market/limit
order".

The two axes cannot drift apart: `expanded_axes_invariants_hold` asserts, for every roster venue,
that a non-empty `trigger_types` holds exactly when `supported_order_kinds` contains one of the
three trigger strings.

Which price series a trigger watches is a separate field. `OrderRequest::trigger_by` is an
`Option<TriggerBy>` over `Last`, `Mark` and `Index`; `None` means the venue's default series, which
that enum's doc records per adapter — bybit hardcodes `triggerBy: "LastPrice"`, binance perp and okx
send no field and inherit a last-price default, hyperliquid "no field exists — triggers evaluate
against MARK by venue law". `Some(source)` asks the adapter to honor that source, and one that
cannot express it "must synthesize a terminal `OrderRejected` (deny loudly — never silently
substitute a different trigger series)".

## Preflight: refused before the wire, with a reason a machine can read [#preflight-refused-before-the-wire-with-a-reason-a-machine-can-read]

`crates/vike-model/src/venue_caps.rs`'s `preflight_order` is the core-edge capability check: it
validates an outgoing request against its venue's declared `VenueCaps` row *before* the request
reaches the [ExecutionClient seam](/docs/trader/concepts/execution-client-seam). An `Err` means the
caller "must synthesize a loud TERMINAL refusal ... never send the order, and never let it silently
vanish".

`PreflightDeny` carries one variant per checked axis, and its `Display` is machine-readable —
`CATEGORY_CONDITION: key=value ...`, e.g. `TIF_UNSUPPORTED: tif=Fok venue=ig` — "so an operator
surface or a log grep can dispatch on the prefix without parsing prose".

| Prefix                    | Raised when                                                              |
| ------------------------- | ------------------------------------------------------------------------ |
| `ORDER_KIND_UNSUPPORTED`  | `order_type` is a known non-trigger kind the venue adapter does not wire |
| `TRIGGER_UNSUPPORTED`     | `order_type` is a trigger kind the venue adapter does not wire           |
| `TIF_UNSUPPORTED`         | a limit order's `time_in_force` is outside the venue's `accepted_tifs`   |
| `MARGIN_MODE_UNSUPPORTED` | an explicit `margin_mode` request the venue adapter cannot honor         |

`ORDER_KIND_UNSUPPORTED` is declared but unreachable today. `preflight_refuses_the_silent_lie_class`
asserts that every roster venue wires both `market` and `limit`, and an undeclared venue is skipped
outright, so no request can raise it. The variant is kept so that a future row dropping one of those
two kinds re-arms the class.

The function is built around a compat law its own doc states: "it refuses NOTHING a venue adapter
accepts-and-honors today". An unknown venue string passes untouched; a combo request passes (the
`OrderIntent::Combo` lowering already resolved `supports_combo`); an `order_type` outside
`ORDER_KINDS` passes; the TIF check runs on the limit path only, since "no venue reads a request TIF
on its market/trigger paths"; coerced-but-live TIFs sit in `accepted_tifs` and so pass; a
`margin_mode` of `None` always passes, meaning "the venue's default behavior". What is refused is
"the silent-lie class": kinds an adapter would coerce into different semantics, TIFs it would
silently ignore, margin modes no adapter honors.

The refusal is a full lifecycle, not an error return.
`crates/vike-core/src/runtime/apply.rs`'s `synthesize_capability_reject` registers the order so the
FSM has an entry to advance, then publishes `OrderSubmitted` followed by `OrderRejected` carrying
that reason string — see [order lifecycle](/docs/trader/concepts/order-lifecycle) and the per-event pages
under [events](/docs/trader/concepts/events). It runs after the journal write on purpose: "a refused
order is exactly the audit trail worth keeping".

## The row is a fact about an exchange, not about a route [#the-row-is-a-fact-about-an-exchange-not-about-a-route]

`preflight_order_at` takes the capability venue explicitly, because `OrderRequest::venue` "does two
jobs at once" — it is what the core routes on and what selects the caps row — while routing is a
per-account question and a caps row is a per-exchange fact. Should a routing key ever name something
outside the canonical roster, the unknown-venue affordance answers `Ok(())`, which is "EVERY check
below skipped, silently, for one account of one exchange". The live core therefore resolves the
engine first and passes `ExecutionEngine::venue`.

<Callout type="warn" title="Post-only is declared but unreachable">
  `VenueCaps::supports_post_only` is `false` for every venue on the roster, and the field's doc gives
  the reason: `OrderRequest` has no post-only field, "so no adapter can wire one (hyperliquid's `Alo`
  and bybit's `PostOnly` exist at the venues but are unreachable); the axis is declared now so the
  field's arrival flips rows, not schemas". The matrix pin asserts it venue by venue —
  "post-only is inexpressible via `OrderRequest`".
</Callout>

<Callout type="warn" title="A capability row states what the adapter wires, not what the exchange offers">
  The module's honesty rule: "every field reflects what the ADAPTER wires TODAY, not what the exchange
  could theoretically do", and an unverifiable capability is declared conservatively `false`. Note too
  what a bridge's own `caps_test` proves — it asserts the same constant against itself through
  `caps_for`, so it "does not execute the adapter" and "cannot catch a row that was wrong when
  written, nor one that went stale when the adapter changed underneath it". The per-venue rows are
  rendered on the [venue pages](/docs/trader/venues).
</Callout>


# Limit (/docs/trader/concepts/orders/limit)




**Limit** — rests at a price and fills only at that price or better. It is one of the five canonical order kinds
(`vike_model::venue_caps::ORDER_KINDS`), the vocabulary a strategy submits in and every venue
adapter translates from. The names are the platform's, not any venue's wire strings: a bridge maps
`limit` onto whatever its exchange calls the same thing, and refuses the order outright where
the venue has no equivalent.

A limit order is the maker's instrument: it joins the book and waits, so it earns the maker side of the fee schedule and takes queue risk instead of spread cost. Whether it may ONLY make is the post-only capability, which is per venue.

## Which venues take it [#which-venues-take-it]

Rendered from each venue's capability row, which is read from what its adapter actually wires —
not from what the exchange documents.

| Venue                                     | Supported |   |
| ----------------------------------------- | --------- | - |
| [binance](/docs/trader/venues/binance)         | yes       | — |
| [bybit](/docs/trader/venues/bybit)             | yes       | — |
| [okx](/docs/trader/venues/okx)                 | yes       | — |
| [deribit](/docs/trader/venues/deribit)         | yes       | — |
| [oanda](/docs/trader/venues/oanda)             | yes       | — |
| [ig](/docs/trader/venues/ig)                   | yes       | — |
| [fxcm](/docs/trader/venues/fxcm)               | yes       | — |
| [dukascopy](/docs/trader/venues/dukascopy)     | yes       | — |
| [polymarket](/docs/trader/venues/polymarket)   | yes       | — |
| [ibkr](/docs/trader/venues/ibkr)               | yes       | — |
| [ctrader](/docs/trader/venues/ctrader)         | yes       | — |
| [alpaca](/docs/trader/venues/alpaca)           | yes       | — |
| [aster](/docs/trader/venues/aster)             | yes       | — |
| [hyperliquid](/docs/trader/venues/hyperliquid) | yes       | — |

14 of 14 venues wire it today.

## Before it reaches a venue [#before-it-reaches-a-venue]

Every order passes a preflight that refuses what a venue cannot do, with a machine-readable reason
rather than a wire error: an unsupported kind, an unsupported time in force, a reduce-only flag on
a venue that has none. That is what makes an unsupported combination a local, immediate, explicable
refusal instead of a silent divergence between what you asked for and what rests on the book.

## Where this comes from [#where-this-comes-from]

`vike_model::venue_caps`'s `ORDER_KINDS` and each venue's `supported_order_kinds`, exported as
`rosters.json` and `venues.json` at every release. Adding a venue reddens the capability table's
completeness test until its row is filled in, so the matrix above cannot be missing a venue.


# Market (/docs/trader/concepts/orders/market)




**Market** — takes liquidity immediately at whatever the book offers. It is one of the five canonical order kinds
(`vike_model::venue_caps::ORDER_KINDS`), the vocabulary a strategy submits in and every venue
adapter translates from. The names are the platform's, not any venue's wire strings: a bridge maps
`market` onto whatever its exchange calls the same thing, and refuses the order outright where
the venue has no equivalent.

A market order names no price. It crosses the spread and fills against resting size, so it is the one kind whose fill price is not something you chose — the [cost model](/docs/trader/backtesting/cost-model) and the [fill models](/docs/trader/backtesting/fill-models) are how a backtest charges for that.

## Which venues take it [#which-venues-take-it]

Rendered from each venue's capability row, which is read from what its adapter actually wires —
not from what the exchange documents.

| Venue                                     | Supported |   |
| ----------------------------------------- | --------- | - |
| [binance](/docs/trader/venues/binance)         | yes       | — |
| [bybit](/docs/trader/venues/bybit)             | yes       | — |
| [okx](/docs/trader/venues/okx)                 | yes       | — |
| [deribit](/docs/trader/venues/deribit)         | yes       | — |
| [oanda](/docs/trader/venues/oanda)             | yes       | — |
| [ig](/docs/trader/venues/ig)                   | yes       | — |
| [fxcm](/docs/trader/venues/fxcm)               | yes       | — |
| [dukascopy](/docs/trader/venues/dukascopy)     | yes       | — |
| [polymarket](/docs/trader/venues/polymarket)   | yes       | — |
| [ibkr](/docs/trader/venues/ibkr)               | yes       | — |
| [ctrader](/docs/trader/venues/ctrader)         | yes       | — |
| [alpaca](/docs/trader/venues/alpaca)           | yes       | — |
| [aster](/docs/trader/venues/aster)             | yes       | — |
| [hyperliquid](/docs/trader/venues/hyperliquid) | yes       | — |

14 of 14 venues wire it today.

## Before it reaches a venue [#before-it-reaches-a-venue]

Every order passes a preflight that refuses what a venue cannot do, with a machine-readable reason
rather than a wire error: an unsupported kind, an unsupported time in force, a reduce-only flag on
a venue that has none. That is what makes an unsupported combination a local, immediate, explicable
refusal instead of a silent divergence between what you asked for and what rests on the book.

## Where this comes from [#where-this-comes-from]

`vike_model::venue_caps`'s `ORDER_KINDS` and each venue's `supported_order_kinds`, exported as
`rosters.json` and `venues.json` at every release. Adding a venue reddens the capability table's
completeness test until its row is filled in, so the matrix above cannot be missing a venue.


# Stop-limit (/docs/trader/concepts/orders/stop-limit)




**Stop-limit** — sleeps until a trigger price is touched, then rests as a limit order. It is one of the five canonical order kinds
(`vike_model::venue_caps::ORDER_KINDS`), the vocabulary a strategy submits in and every venue
adapter translates from. The names are the platform's, not any venue's wire strings: a bridge maps
`stop_limit` onto whatever its exchange calls the same thing, and refuses the order outright where
the venue has no equivalent.

The same trigger with a limit as its payload: it bounds the fill price at the cost of possibly not filling at all.

This is a **trigger kind**: it carries a trigger price and a trigger type, and the type column below says which types each venue wires.

## Which venues take it [#which-venues-take-it]

Rendered from each venue's capability row, which is read from what its adapter actually wires —
not from what the exchange documents.

| Venue                                     | Supported | Trigger types              |
| ----------------------------------------- | --------- | -------------------------- |
| [binance](/docs/trader/venues/binance)         | no        | `stop-loss`                |
| [bybit](/docs/trader/venues/bybit)             | no        | `stop-loss`                |
| [okx](/docs/trader/venues/okx)                 | no        | `stop-loss`                |
| [deribit](/docs/trader/venues/deribit)         | no        | —                          |
| [oanda](/docs/trader/venues/oanda)             | no        | `stop-loss`                |
| [ig](/docs/trader/venues/ig)                   | no        | `stop-loss`                |
| [fxcm](/docs/trader/venues/fxcm)               | no        | —                          |
| [dukascopy](/docs/trader/venues/dukascopy)     | no        | —                          |
| [polymarket](/docs/trader/venues/polymarket)   | no        | —                          |
| [ibkr](/docs/trader/venues/ibkr)               | no        | `stop-loss`                |
| [ctrader](/docs/trader/venues/ctrader)         | no        | `stop-loss`                |
| [alpaca](/docs/trader/venues/alpaca)           | yes       | `stop-loss`                |
| [aster](/docs/trader/venues/aster)             | no        | `stop-loss`                |
| [hyperliquid](/docs/trader/venues/hyperliquid) | yes       | `stop-loss`, `take-profit` |

2 of 14 venues wire it today.

## Before it reaches a venue [#before-it-reaches-a-venue]

Every order passes a preflight that refuses what a venue cannot do, with a machine-readable reason
rather than a wire error: an unsupported kind, an unsupported time in force, a reduce-only flag on
a venue that has none. That is what makes an unsupported combination a local, immediate, explicable
refusal instead of a silent divergence between what you asked for and what rests on the book.

## Where this comes from [#where-this-comes-from]

`vike_model::venue_caps`'s `ORDER_KINDS` and each venue's `supported_order_kinds`, exported as
`rosters.json` and `venues.json` at every release. Adding a venue reddens the capability table's
completeness test until its row is filled in, so the matrix above cannot be missing a venue.


# Stop (/docs/trader/concepts/orders/stop)




**Stop** — sleeps until a trigger price is touched, then becomes a market order. It is one of the five canonical order kinds
(`vike_model::venue_caps::ORDER_KINDS`), the vocabulary a strategy submits in and every venue
adapter translates from. The names are the platform's, not any venue's wire strings: a bridge maps
`stop` onto whatever its exchange calls the same thing, and refuses the order outright where
the venue has no equivalent.

A stop is two orders in one: a trigger condition and the order it releases. Until the trigger fires nothing rests on the book.

This is a **trigger kind**: it carries a trigger price and a trigger type, and the type column below says which types each venue wires.

## Which venues take it [#which-venues-take-it]

Rendered from each venue's capability row, which is read from what its adapter actually wires —
not from what the exchange documents.

| Venue                                     | Supported | Trigger types              |
| ----------------------------------------- | --------- | -------------------------- |
| [binance](/docs/trader/venues/binance)         | yes       | `stop-loss`                |
| [bybit](/docs/trader/venues/bybit)             | yes       | `stop-loss`                |
| [okx](/docs/trader/venues/okx)                 | yes       | `stop-loss`                |
| [deribit](/docs/trader/venues/deribit)         | no        | —                          |
| [oanda](/docs/trader/venues/oanda)             | yes       | `stop-loss`                |
| [ig](/docs/trader/venues/ig)                   | yes       | `stop-loss`                |
| [fxcm](/docs/trader/venues/fxcm)               | no        | —                          |
| [dukascopy](/docs/trader/venues/dukascopy)     | no        | —                          |
| [polymarket](/docs/trader/venues/polymarket)   | no        | —                          |
| [ibkr](/docs/trader/venues/ibkr)               | yes       | `stop-loss`                |
| [ctrader](/docs/trader/venues/ctrader)         | yes       | `stop-loss`                |
| [alpaca](/docs/trader/venues/alpaca)           | yes       | `stop-loss`                |
| [aster](/docs/trader/venues/aster)             | yes       | `stop-loss`                |
| [hyperliquid](/docs/trader/venues/hyperliquid) | yes       | `stop-loss`, `take-profit` |

10 of 14 venues wire it today.

## Before it reaches a venue [#before-it-reaches-a-venue]

Every order passes a preflight that refuses what a venue cannot do, with a machine-readable reason
rather than a wire error: an unsupported kind, an unsupported time in force, a reduce-only flag on
a venue that has none. That is what makes an unsupported combination a local, immediate, explicable
refusal instead of a silent divergence between what you asked for and what rests on the book.

## Where this comes from [#where-this-comes-from]

`vike_model::venue_caps`'s `ORDER_KINDS` and each venue's `supported_order_kinds`, exported as
`rosters.json` and `venues.json` at every release. Adding a venue reddens the capability table's
completeness test until its row is filled in, so the matrix above cannot be missing a venue.


# Take-profit (/docs/trader/concepts/orders/take-profit)




**Take-profit** — sleeps until a favourable trigger price is touched, then closes into it. It is one of the five canonical order kinds
(`vike_model::venue_caps::ORDER_KINDS`), the vocabulary a strategy submits in and every venue
adapter translates from. The names are the platform's, not any venue's wire strings: a bridge maps
`take_profit` onto whatever its exchange calls the same thing, and refuses the order outright where
the venue has no equivalent.

The mirror of a stop, armed on the profitable side.

This is a **trigger kind**: it carries a trigger price and a trigger type, and the type column below says which types each venue wires.

## Which venues take it [#which-venues-take-it]

Rendered from each venue's capability row, which is read from what its adapter actually wires —
not from what the exchange documents.

| Venue                                     | Supported | Trigger types              |
| ----------------------------------------- | --------- | -------------------------- |
| [binance](/docs/trader/venues/binance)         | no        | `stop-loss`                |
| [bybit](/docs/trader/venues/bybit)             | no        | `stop-loss`                |
| [okx](/docs/trader/venues/okx)                 | no        | `stop-loss`                |
| [deribit](/docs/trader/venues/deribit)         | no        | —                          |
| [oanda](/docs/trader/venues/oanda)             | no        | `stop-loss`                |
| [ig](/docs/trader/venues/ig)                   | no        | `stop-loss`                |
| [fxcm](/docs/trader/venues/fxcm)               | no        | —                          |
| [dukascopy](/docs/trader/venues/dukascopy)     | no        | —                          |
| [polymarket](/docs/trader/venues/polymarket)   | no        | —                          |
| [ibkr](/docs/trader/venues/ibkr)               | no        | `stop-loss`                |
| [ctrader](/docs/trader/venues/ctrader)         | no        | `stop-loss`                |
| [alpaca](/docs/trader/venues/alpaca)           | no        | `stop-loss`                |
| [aster](/docs/trader/venues/aster)             | no        | `stop-loss`                |
| [hyperliquid](/docs/trader/venues/hyperliquid) | yes       | `stop-loss`, `take-profit` |

1 of 14 venues wire it today.

## Before it reaches a venue [#before-it-reaches-a-venue]

Every order passes a preflight that refuses what a venue cannot do, with a machine-readable reason
rather than a wire error: an unsupported kind, an unsupported time in force, a reduce-only flag on
a venue that has none. That is what makes an unsupported combination a local, immediate, explicable
refusal instead of a silent divergence between what you asked for and what rests on the book.

## Where this comes from [#where-this-comes-from]

`vike_model::venue_caps`'s `ORDER_KINDS` and each venue's `supported_order_kinds`, exported as
`rosters.json` and `venues.json` at every release. Adding a venue reddens the capability table's
completeness test until its row is filled in, so the matrix above cannot be missing a venue.


# Balance drift (/docs/trader/concepts/reconciliation/balance-drift)




**Balance drift** — venue cash and the realized-PnL-corrected local balance disagree. It is one of the divergence kinds a reconciliation pass can raise
(`vike_exec::recon::DivergenceKind`): the pass fetches the venue's own order, fill, position and
balance reports for a lookback window, diffs them against local state, and classifies every
disagreement.

Cash as a first-class diffed dimension rather than a silent authoritative overwrite. Off by default, and quarantined by default when armed.

## What each policy does with it [#what-each-policy-does-with-it]

| Policy                | Verdict               |
| --------------------- | --------------------- |
| `hybrid`              | holds for an operator |
| `synthesize`          | **auto-applies**      |
| `quarantine`          | holds for an operator |
| `external-quarantine` | holds for an operator |

Every verdict above is **computed** from the policy the runtime actually applies, not written down
beside it. That is not decoration: the opposite claim about the default policy was stated in six
places in this codebase and was false in all six, so the export asks the function and the docs
render the answer.

When this kind auto-applies it produces real events, which is why the verdict above matters operationally.

Held means an operator sees an alert carrying the events the pass WOULD have folded, and confirming it folds exactly those — the same events, with a person in front of them.

## Reading this in an incident [#reading-this-in-an-incident]

The [policies page](/docs/trader/concepts/reconciliation/policies) covers the four presets and when to
choose each; the rollout rule for a newly wired venue is to start under `quarantine` until that
venue's position reports are proven complete, precisely because position drift auto-applies under
the default.

## Where this comes from [#where-this-comes-from]

`vike_exec::recon::DivergenceKind` and its origin class — this kind's evidence is
external — the evidence is venue activity the local core did not originate — with every policy verdict computed through
`vike_exec::recon::mode_applies`, exported as `rosters.json` at every release.


# Reconciliation (/docs/trader/concepts/reconciliation)



A live core's books are built from messages. Messages get lost, arrive while the process is down,
or arrive twice. **Reconciliation is the periodic proof that the local book still matches what the
venue itself says** — and, where it does not, a classified disagreement with a policy attached.

The engine is pure. `crates/vike-exec/src/recon/mod.rs`'s header states the split: `diff` turns
venue reports plus a `LocalView` into `Divergence`s, `resolve` turns those plus a `ReconPolicy`
into a `Recon`, and **both are pure functions with no I/O**. That is what makes golden-fixture
tests and the three-way journal cross-check possible at all — `crates/vike-exec/src/recon/types.rs`
says so in its own first line.

## What one pass fetches [#what-one-pass-fetches]

`crates/vike-exec/src/recon/client.rs`'s `ReconClient` is the venue-facing report seam, and it is
blocking REST. Three fetches are required — `fetch_order_status_reports`, `fetch_fill_reports`,
`fetch_position_status_reports`. Two more default to `Ok(None)`, so an unwired client stays inert
rather than failing a pass:

* `fetch_balance` — the venue's absolute cash truth. A venue that reports none still has its
  orders, fills and positions diffed.
* `fetch_fee_rates` — the account-actual maker/taker schedule, overridden by binance, bybit, okx,
  deribit and aster — the last on its spot lane only, its perp lane staying inert. Unwired, the
  caller keeps the static `vike_model::fee_schedule_for` default.

`fetch_mass_status` composes the three required fetches into one `MassStatus` bundle in a fixed
order (orders → fills → positions); a venue with a genuine atomic bulk endpoint may override it,
and that doc records that **no current venue does**. `run_pass` composes fetch → diff → resolve in
one function — the offline twin the golden fixtures run. The live driver reaches the same three
stages across two threads instead, which the next section describes.

## Where the work runs [#where-the-work-runs]

`crates/vike-core/src/recon_manager.rs`'s header names the design *reports-in, compute-on-fold*.
The manager runs on its **own thread** and does only the blocking fetch — it must never touch the
p99 \< 10 µs fold. It then enqueues the raw reports as `Command::ReconcileReports`; the fold thread
reads its own `local_view()`, runs the pure diff and resolve, and folds each synthesized event
through the **same** `publish_to` path real venue events take
(`crates/vike-core/src/runtime/mod.rs`'s `reconcile_reports`). Diff and resolve therefore sit on
the same thread as the state they read: no cross-thread snapshot, no staleness window.

<Callout type="warn" title="The pass deliberately avoids ApplySnapshot">
  `reconcile_reports` explains why it does not route through `Command::ApplySnapshot`:
  `ExecutionEngine::apply_snapshot`'s order reap terminalizes any live local order absent from
  `snapshot.open_orders`, so pushing an all-empty-except-balance snapshot through that arm would
  **cancel every live order on the venue** as a side effect. Balance is seeded directly onto
  `Account::balance` instead — the narrowest path that updates cash without touching positions or
  the order registry.
</Callout>

## Cadence, and why repetition is safe [#cadence-and-why-repetition-is-safe]

Three cadences share one pass (`ReconManager::run_startup_pass`): a startup pass after
`startup_delay`; an on-demand pass whenever a bridge pokes the reconcile trigger, typically wired
to a reconnect; and `ReconConfig::interval`, which re-runs the same pass on a fixed cadence.
`ReconConfig::audit_interval` is a fourth arm that runs **no** reconcile pass at all — it pokes the
core's existing stuck-order [watchdog](/docs/trader/concepts/watchdog) waker instead.

That makes idempotency load-bearing rather than convenient, and the header says where it comes
from: `diff` dedups fills by `trade_id` against the engine's `seen_trade_ids`, so a tick that finds
nothing new folds nothing new.

## The health gate is per venue [#the-health-gate-is-per-venue]

`ReconManager::should_reconcile` is consulted **before each venue's leg** of every pass — startup,
trigger and interval alike. With no probe wired it returns `true`; otherwise it asks the probe for
that venue and suppresses the leg on `ReconHealth::Degraded`. Suppression defers that venue only:
it sets no pending flag and never blocks a different healthy venue in the same pass.

The probe itself is built in `crates/vike-ops/src/reconcile_config.rs`'s `build_recon_config` over
a per-venue map of feed-status handles, so a bybit feed gap suppresses only bybit's leg. &#x2A;*A venue
with no entry in the map reads `Healthy`** — an ungated venue is never blocked, which is how the
exec-only venues (no market feed of their own) keep reconciling. `health_from_feed_status` is
fail-soft: only an error state, or a disconnected one whose status string literally says so, reads
`Degraded`.

## Which venues reconcile [#which-venues-reconcile]

The mount is the composition root, and `crates/vike-mount/src/lib.rs`'s header describes a layout
of three kinds, not two:

* `build_recon_client` is a thin dispatch over the bybit, okx and binance bridges' own
  `recon_client` factories.
* Hyperliquid is built by `crates/vike-mount/src/hyperliquid.rs`'s `hyperliquid_live_client`,
  which returns the exec client and the `ReconClient` together — it calls the bridge's
  `recon_client` only once its `instruments` fetch has resolved the product, which the shared
  dispatch cannot do without a second network round trip.
* deribit, aster, cTrader, Alpaca, IG, OANDA — and, behind the `ibkr` and `polymarket` features,
  IBKR and Polymarket — call their own factory **inline** in `make_engine`'s arm, each needing a
  non-REST, bespoke-signer or non-generic-credentials handshake the shared dispatch cannot produce.

A paper venue returns `None` and reconciles nothing, and there are two independent ways to be one.
The per-venue arming ceiling (`policy.venues.<venue>`) is read *first*, above the credential read:
a `paper` venue returns the paper client having loaded no credential and opened no socket. Only
behind it does the older rule apply — absent credentials are the live gate. Both, in that order,
are the [risk and arming](/docs/trader/concepts/risk-and-arming) page's subject.

Five of those inline factories (deribit, cTrader, IG, OANDA, IBKR) perform a blocking
*authenticated* handshake just to construct the client, so the mount gates them on its resolved
reconcile verdict through `recon_if_enabled`: with reconciliation off they are never called and
the venue does no authenticated network work at mount. That gate is an explicit parameter and
deliberately not "does this venue have a reconnect trigger" — the trigger is wired for four venues
only, so inferring the global gate from it would silently stop reconciling those five.

## The output an operator sees [#the-output-an-operator-sees]

Events the policy auto-applies fold immediately. Everything held becomes a `ReconAlert` carrying
`proposed_events` — *the events `resolve` would have folded* — that an operator confirm folds
later through the same publish path, byte-identically to what an immediate fold would have
produced (`confirm_recon`). Which is which is the
[policies](/docs/trader/concepts/reconciliation/policies) page's subject, and each kind has a page.

<Callout title="A held divergence is a state, not an event">
  `crates/vike-core/src/runtime/recon_held.rs`'s header carries the measurement that forced this:
  under a hold-everything policy a divergence nothing heals is re-held every interval forever, and
  the live box logged **396 identical warnings on 2026-08-25 and 345 on 2026-08-24, every one of
  them the same bybit external-position divergence**. The log now announces transitions — one line
  when a divergence enters the held set, one when it leaves — with a much slower periodic summary so
  a standing backlog stays visible without being repeated at pass cadence. The held store has the
  same shape: a re-raise refreshes its row in place, so it is bounded by distinct divergence
  identities rather than by uptime.
</Callout>


# Journal divergence (/docs/trader/concepts/reconciliation/journal-divergence)




**Journal divergence** — the command journal and the reconciled state disagree. It is one of the divergence kinds a reconciliation pass can raise
(`vike_exec::recon::DivergenceKind`): the pass fetches the venue's own order, fill, position and
balance reports for a lookback window, diffs them against local state, and classifies every
disagreement.

Held before the policy is even consulted: it short-circuits into an investigative alert, because a journal that disagrees with reality is a question for a human rather than something to fold.

## What each policy does with it [#what-each-policy-does-with-it]

| Policy                | Verdict               |
| --------------------- | --------------------- |
| `hybrid`              | **auto-applies**      |
| `synthesize`          | **auto-applies**      |
| `quarantine`          | holds for an operator |
| `external-quarantine` | **auto-applies**      |

Every verdict above is **computed** from the policy the runtime actually applies, not written down
beside it. That is not decoration: the opposite claim about the default policy was stated in six
places in this codebase and was false in all six, so the export asks the function and the docs
render the answer.

⚠ &#x2A;*Auto-applying is not the same as doing something.** This kind resolves to an EMPTY event list, so even under a policy that folds it, nothing changes — and because it folded rather than held, it does not raise an operator alert either.

## Reading this in an incident [#reading-this-in-an-incident]

The [policies page](/docs/trader/concepts/reconciliation/policies) covers the four presets and when to
choose each; the rollout rule for a newly wired venue is to start under `quarantine` until that
venue's position reports are proven complete, precisely because position drift auto-applies under
the default.

## Where this comes from [#where-this-comes-from]

`vike_exec::recon::DivergenceKind` and its origin class — this kind's evidence is
an absence — the evidence is something NOT reported, the weakest class of evidence — with every policy verdict computed through
`vike_exec::recon::mode_applies`, exported as `rosters.json` at every release.


# Missing fill (/docs/trader/concepts/reconciliation/missing-fill)




**Missing fill** — the venue reports a fill local state has never seen. It is one of the divergence kinds a reconciliation pass can raise
(`vike_exec::recon::DivergenceKind`): the pass fetches the venue's own order, fill, position and
balance reports for a lookback window, diffs them against local state, and classifies every
disagreement.

The commonest real divergence and the one reconciliation exists for: an execution happened, the message never arrived or arrived while the process was down, and the local book is a fill behind.

## What each policy does with it [#what-each-policy-does-with-it]

| Policy                | Verdict               |
| --------------------- | --------------------- |
| `hybrid`              | **auto-applies**      |
| `synthesize`          | **auto-applies**      |
| `quarantine`          | holds for an operator |
| `external-quarantine` | **auto-applies**      |

Every verdict above is **computed** from the policy the runtime actually applies, not written down
beside it. That is not decoration: the opposite claim about the default policy was stated in six
places in this codebase and was false in all six, so the export asks the function and the docs
render the answer.

When this kind auto-applies it produces real events, which is why the verdict above matters operationally.

## Reading this in an incident [#reading-this-in-an-incident]

The [policies page](/docs/trader/concepts/reconciliation/policies) covers the four presets and when to
choose each; the rollout rule for a newly wired venue is to start under `quarantine` until that
venue's position reports are proven complete, precisely because position drift auto-applies under
the default.

## Where this comes from [#where-this-comes-from]

`vike_exec::recon::DivergenceKind` and its origin class — this kind's evidence is
materialized by reconciliation itself — the pass is what produced the local-origin evidence — with every policy verdict computed through
`vike_exec::recon::mode_applies`, exported as `rosters.json` at every release.


# Missing terminal (/docs/trader/concepts/reconciliation/missing-terminal)




**Missing terminal** — the venue says an order is finished and local state still has it working. It is one of the divergence kinds a reconciliation pass can raise
(`vike_exec::recon::DivergenceKind`): the pass fetches the venue's own order, fill, position and
balance reports for a lookback window, diffs them against local state, and classifies every
disagreement.

The order ended — filled, cancelled, expired — and the ending never reached the core.

## What each policy does with it [#what-each-policy-does-with-it]

| Policy                | Verdict               |
| --------------------- | --------------------- |
| `hybrid`              | **auto-applies**      |
| `synthesize`          | **auto-applies**      |
| `quarantine`          | holds for an operator |
| `external-quarantine` | **auto-applies**      |

Every verdict above is **computed** from the policy the runtime actually applies, not written down
beside it. That is not decoration: the opposite claim about the default policy was stated in six
places in this codebase and was false in all six, so the export asks the function and the docs
render the answer.

⚠ &#x2A;*Auto-applying is not the same as doing something.** This kind resolves to an EMPTY event list, so even under a policy that folds it, nothing changes — and because it folded rather than held, it does not raise an operator alert either.

## Reading this in an incident [#reading-this-in-an-incident]

The [policies page](/docs/trader/concepts/reconciliation/policies) covers the four presets and when to
choose each; the rollout rule for a newly wired venue is to start under `quarantine` until that
venue's position reports are proven complete, precisely because position drift auto-applies under
the default.

## Where this comes from [#where-this-comes-from]

`vike_exec::recon::DivergenceKind` and its origin class — this kind's evidence is
materialized by reconciliation itself — the pass is what produced the local-origin evidence — with every policy verdict computed through
`vike_exec::recon::mode_applies`, exported as `rosters.json` at every release.


# Orphan local order (/docs/trader/concepts/reconciliation/orphan-local-order)




**Orphan local order** — local state holds a working order the venue does not report. It is one of the divergence kinds a reconciliation pass can raise
(`vike_exec::recon::DivergenceKind`): the pass fetches the venue's own order, fill, position and
balance reports for a lookback window, diffs them against local state, and classifies every
disagreement.

Evidence of an ABSENCE, which is the weakest kind there is: a venue report that omits an order is not the same as a venue that denies it. That is why this kind resolves to no events under every policy — see the verdicts below.

## What each policy does with it [#what-each-policy-does-with-it]

| Policy                | Verdict               |
| --------------------- | --------------------- |
| `hybrid`              | holds for an operator |
| `synthesize`          | **auto-applies**      |
| `quarantine`          | holds for an operator |
| `external-quarantine` | holds for an operator |

Every verdict above is **computed** from the policy the runtime actually applies, not written down
beside it. That is not decoration: the opposite claim about the default policy was stated in six
places in this codebase and was false in all six, so the export asks the function and the docs
render the answer.

⚠ &#x2A;*Auto-applying is not the same as doing something.** This kind resolves to an EMPTY event list, so even under a policy that folds it, nothing changes — and because it folded rather than held, it does not raise an operator alert either.

Held means an operator sees an alert carrying the events the pass WOULD have folded, and confirming it folds exactly those — the same events, with a person in front of them.

## Reading this in an incident [#reading-this-in-an-incident]

The [policies page](/docs/trader/concepts/reconciliation/policies) covers the four presets and when to
choose each; the rollout rule for a newly wired venue is to start under `quarantine` until that
venue's position reports are proven complete, precisely because position drift auto-applies under
the default.

## Where this comes from [#where-this-comes-from]

`vike_exec::recon::DivergenceKind` and its origin class — this kind's evidence is
an absence — the evidence is something NOT reported, the weakest class of evidence — with every policy verdict computed through
`vike_exec::recon::mode_applies`, exported as `rosters.json` at every release.


# Orphan local position (/docs/trader/concepts/reconciliation/orphan-local-position)




**Orphan local position** — local state holds a position the venue does not report. It is one of the divergence kinds a reconciliation pass can raise
(`vike_exec::recon::DivergenceKind`): the pass fetches the venue's own order, fill, position and
balance reports for a lookback window, diffs them against local state, and classifies every
disagreement.

The exempt kind: it folds NOTHING under any policy, and its sweep is gated on the venue having reported at least one position row at all — an empty report is an outage, not an assertion that you are flat.

## What each policy does with it [#what-each-policy-does-with-it]

| Policy                | Verdict               |
| --------------------- | --------------------- |
| `hybrid`              | holds for an operator |
| `synthesize`          | **auto-applies**      |
| `quarantine`          | holds for an operator |
| `external-quarantine` | holds for an operator |

Every verdict above is **computed** from the policy the runtime actually applies, not written down
beside it. That is not decoration: the opposite claim about the default policy was stated in six
places in this codebase and was false in all six, so the export asks the function and the docs
render the answer.

⚠ &#x2A;*Auto-applying is not the same as doing something.** This kind resolves to an EMPTY event list, so even under a policy that folds it, nothing changes — and because it folded rather than held, it does not raise an operator alert either.

Held means an operator sees an alert carrying the events the pass WOULD have folded, and confirming it folds exactly those — the same events, with a person in front of them.

## Reading this in an incident [#reading-this-in-an-incident]

The [policies page](/docs/trader/concepts/reconciliation/policies) covers the four presets and when to
choose each; the rollout rule for a newly wired venue is to start under `quarantine` until that
venue's position reports are proven complete, precisely because position drift auto-applies under
the default.

## Where this comes from [#where-this-comes-from]

`vike_exec::recon::DivergenceKind` and its origin class — this kind's evidence is
an absence — the evidence is something NOT reported, the weakest class of evidence — with every policy verdict computed through
`vike_exec::recon::mode_applies`, exported as `rosters.json` at every release.


# Reconciliation policies (/docs/trader/concepts/reconciliation/policies)



A policy answers one question per divergence: &#x2A;*fold it now, or hold it for an operator?**
`crates/vike-exec/src/recon/types.rs` gives that answer three shapes. `ReconMode::Synthesize` emits
the synthesized events and folds immediately; `ReconMode::Quarantine` emits nothing and surfaces a
`ReconAlert` for operator confirm; `ReconMode::Hybrid` is per kind — local-origin kinds synthesize,
no-local-origin kinds quarantine. A `ReconPolicy` is a default mode plus per-kind overrides.

`VIKE_RECONCILE_POLICY` selects one of four, case-insensitively, one spelling each and no aliases
(`crates/vike-ops/src/reconcile_config.rs`'s `parse_policy`):

| Value                 | What it builds                                                                    |
| --------------------- | --------------------------------------------------------------------------------- |
| `hybrid` (default)    | `ReconPolicy::hybrid()` — the per-kind preset                                     |
| `synthesize`          | `ReconPolicy::default()` — mode `Synthesize`, no overrides: fold everything       |
| `quarantine`          | mode `Quarantine`, no overrides: hold everything                                  |
| `external-quarantine` | `ReconPolicy::external_quarantine()` — `hybrid`, with foreign venue activity held |

<Callout type="warn" title="A misspelling gives you MORE auto-folding, not less">
  `parse_policy` falls back to `hybrid` for an unrecognized value as well as an absent one. For a
  mis-spelled hold-first policy — `external_quarantine`, `external` — the process therefore folds
  *more* than the operator intended, silently. The startup line below is the check that a spelling
  took.
</Callout>

## Under `hybrid`, exactly two kinds fold anything [#under-hybrid-exactly-two-kinds-fold-anything]

This is the fact everyone gets wrong first, and the code is arranged so nobody has to take prose's
word for it. `vike_exec::recon::mode_applies` is `pub` *because* it was private once: its own doc
records that while it was, "what does `hybrid` actually fold?" could only be answered by reading
`resolve`, and **two independent reviews of the same code reached opposite answers** about one kind
— one of which had already propagated into six documents and a rollout policy.

`vike_ops::reconcile_config::auto_applied_kinds` therefore *computes* the answer, filtering a
five-kind candidate list through `mode_applies`. Under `hybrid` the result is `MissingFill` and
`PositionDrift`, and nothing else. That `PositionDrift` — a no-local-origin kind — folds at all is
argued on the variant itself: unlike every other no-local-origin kind its evidence is a **positive
venue position row rather than an absence**, and it is the only path that re-converges quantity
after a fill older than the reconcile lookback.

<Callout type="warn" title="Auto-apply is not the same as doing something">
  Four kinds never appear in the auto-applied list even when their mode *is* auto-apply, because
  naming a kind that folds nothing misinforms in exactly the direction `mode_applies` exists to stop:

  * **`MissingTerminal`** auto-applies under `hybrid` and resolves to an **empty** event list —
    `resolve`'s `events_for` has no arm for it, so it lands in the catch-all.
  * **`OrphanLocalOrder`*&#x2A; and &#x2A;*`OrphanLocalPosition`** fold nothing under *any* policy. A
    synthesized cancel would terminalize an order that may still be resting at the venue; a
    synthesized flattening leg would have to invent a price and book fabricated realized PnL. Held
    policies surface a dedup-keyed alert instead, and confirming one is a pure acknowledgement.
  * **`JournalDivergence`** short-circuits into an investigative alert *before* the policy is
    consulted, so its mode is decorative: no auto-apply of a persistence bug.
</Callout>

## Every kind is named, and one hand-built policy disagrees [#every-kind-is-named-and-one-hand-built-policy-disagrees]

`ReconPolicy::hybrid`'s doc carries a rule with a scar behind it: &#x2A;*every kind gets a named row;
none may reach its mode through `default`.** A fall-through is indistinguishable from a kind nobody
classified — which is what happened to `PositionDrift`, auto-applying on ten venues through
`default` with no row and no assertion, while the only test of the preset named six kinds and
omitted it. `crates/vike-exec/tests/recon/recon_policy_pin.rs` now gates the rule and pins every
kind's mode with an exhaustive match.

<Callout type="warn" title="A bare Hybrid is not the hybrid preset">
  `resolve`'s `is_local_origin` lists only `MissingFill` and `MissingTerminal`, so a hand-built
  `ReconPolicy { default: Hybrid, .. }` **quarantines what the preset folds** for `PositionDrift`.
  Nothing in the workspace builds one, so it is a latent trap rather than a live divergence — pinned
  as such by `bare_hybrid_and_the_preset_disagree_about_position_drift`. `VIKE_RECONCILE_POLICY`
  cannot reach it.
</Callout>

## `external-quarantine` [#external-quarantine]

`ReconPolicy::external_quarantine` is `hybrid` with every kind whose `DivergenceOrigin` is
`External` — foreign venue activity nothing local explains — forced to `Quarantine`. It is
**computed** from `DivergenceKind::origin` over `hybrid()`'s rows rather than enumerated, so a
future External kind is held by construction. At the kind level exactly one thing changes:
`PositionDrift` stops folding. The other External kinds were already quarantined, and every
non-External kind keeps its `hybrid` row verbatim.

One sub-case changes at the *instance* level. This is the only constructor that sets
`hold_external_instances`, which makes `mode_applies_divergence` additionally hold a &#x2A;*coid-less
`MissingFill`** — a foreign order's fill inside the lookback, whose instance origin reads External
while its kind's does not — while coid-linked ones, our own orders' fills, keep folding. The
`MissingFill` mode row is deliberately unchanged: the refinement is per-divergence, not a mode edit,
which keeps the journaled per-kind map stable, and the startup line renders it as
`MissingFill (coid-linked only)`. For every policy that does not opt in, that function is
definitionally `mode_applies(policy, d.kind())`, so the other three are byte-identical by
construction rather than by test.

Claiming a held divergence needs no new machinery: `resolve` computes a divergence's events
*before* consulting the mode, so the held alert proposes exactly what `hybrid` would have folded.

## The startup line [#the-startup-line]

`log_policy_effect` emits one line from `build_recon_config`, the single place every composition
root resolves the policy. An empty fold set logs at INFO — *nothing auto-folds*; a non-empty one
logs at WARN naming the kinds. It exists because "is my configuration safe?" used to be answerable
only by reading `resolve`, and the one venue warning that tried printed identical text for a
quarantined and an auto-applying policy, while also naming the wrong kind.

## Rolling out a newly wired venue [#rolling-out-a-newly-wired-venue]

Start a newly wired venue under `quarantine` until that venue's position-report completeness is
proven live, then graduate to `hybrid`. The reason is `PositionDrift`: it is the one
no-local-origin kind `hybrid` folds with no operator in front of it, and the fold is destructive —
it rewrites local position size onto the venue's number and books realized PnL at the venue's
average price.

What an unproven fetch costs you is a row that arrives and is *wrong*, not one that never arrives.
`crates/vike-exec/src/recon/diff.rs`'s `diff` raises `PositionDrift` only from a venue row that is
**present** — an explicitly flat `qty == 0` row included. A row the venue simply omits raises
`OrphanLocalPosition` instead, which folds nothing under any policy, precisely because most wired
position fetches are symbol-scoped and "no row" routinely means "not asked about" rather than
"flat" (`resolve`'s module doc).

<Callout type="warn" title="The corrected reason">
  This rule used to be justified by an order-side hazard that does not exist: that `hybrid`
  auto-cancels orphaned local orders. It does not. `resolve` synthesizes no `OrderCanceled` for any
  kind under any policy — `no_policy_ever_synthesizes_a_cancel_for_an_orphan_local_order` pins that —
  and the reconcile lane never calls the venue: everything it emits is a local fold. The advice
  survives unchanged; only its justification moves, from an order-side hazard to a position-side one
  that is real.
</Callout>

Each kind has its own page, with the four verdicts computed rather than restated — start from
[position drift](/docs/trader/concepts/reconciliation/position-drift), or from the
[index](/docs/trader/concepts/reconciliation) for the pass that raises them.


# Position drift (/docs/trader/concepts/reconciliation/position-drift)




**Position drift** — the venue and local state disagree about position size. It is one of the divergence kinds a reconciliation pass can raise
(`vike_exec::recon::DivergenceKind`): the pass fetches the venue's own order, fill, position and
balance reports for a lookback window, diffs them against local state, and classifies every
disagreement.

The one no-local-origin kind the hybrid policy auto-applies, and deliberately so: its evidence is a POSITIVE venue position row rather than an absence, and it is the only path that re-converges quantity after a fill older than the lookback window. It rewrites local size onto the venue's number and books realized PnL at the venue's average price.

## What each policy does with it [#what-each-policy-does-with-it]

| Policy                | Verdict               |
| --------------------- | --------------------- |
| `hybrid`              | **auto-applies**      |
| `synthesize`          | **auto-applies**      |
| `quarantine`          | holds for an operator |
| `external-quarantine` | holds for an operator |

Every verdict above is **computed** from the policy the runtime actually applies, not written down
beside it. That is not decoration: the opposite claim about the default policy was stated in six
places in this codebase and was false in all six, so the export asks the function and the docs
render the answer.

When this kind auto-applies it produces real events, which is why the verdict above matters operationally.

## Reading this in an incident [#reading-this-in-an-incident]

The [policies page](/docs/trader/concepts/reconciliation/policies) covers the four presets and when to
choose each; the rollout rule for a newly wired venue is to start under `quarantine` until that
venue's position reports are proven complete, precisely because position drift auto-applies under
the default.

## Where this comes from [#where-this-comes-from]

`vike_exec::recon::DivergenceKind` and its origin class — this kind's evidence is
external — the evidence is venue activity the local core did not originate — with every policy verdict computed through
`vike_exec::recon::mode_applies`, exported as `rosters.json` at every release.


# Position only external (/docs/trader/concepts/reconciliation/position-only-external)




**Position only external** — the venue reports a position on an instrument local state holds none of. It is one of the divergence kinds a reconciliation pass can raise
(`vike_exec::recon::DivergenceKind`): the pass fetches the venue's own order, fill, position and
balance reports for a lookback window, diffs them against local state, and classifies every
disagreement.

A position that arrived by a route the local core never saw.

## What each policy does with it [#what-each-policy-does-with-it]

| Policy                | Verdict               |
| --------------------- | --------------------- |
| `hybrid`              | holds for an operator |
| `synthesize`          | **auto-applies**      |
| `quarantine`          | holds for an operator |
| `external-quarantine` | holds for an operator |

Every verdict above is **computed** from the policy the runtime actually applies, not written down
beside it. That is not decoration: the opposite claim about the default policy was stated in six
places in this codebase and was false in all six, so the export asks the function and the docs
render the answer.

When this kind auto-applies it produces real events, which is why the verdict above matters operationally.

Held means an operator sees an alert carrying the events the pass WOULD have folded, and confirming it folds exactly those — the same events, with a person in front of them.

## Reading this in an incident [#reading-this-in-an-incident]

The [policies page](/docs/trader/concepts/reconciliation/policies) covers the four presets and when to
choose each; the rollout rule for a newly wired venue is to start under `quarantine` until that
venue's position reports are proven complete, precisely because position drift auto-applies under
the default.

## Where this comes from [#where-this-comes-from]

`vike_exec::recon::DivergenceKind` and its origin class — this kind's evidence is
external — the evidence is venue activity the local core did not originate — with every policy verdict computed through
`vike_exec::recon::mode_applies`, exported as `rosters.json` at every release.


# Unknown order (/docs/trader/concepts/reconciliation/unknown-order)




**Unknown order** — the venue reports an order local state has no record of. It is one of the divergence kinds a reconciliation pass can raise
(`vike_exec::recon::DivergenceKind`): the pass fetches the venue's own order, fill, position and
balance reports for a lookback window, diffs them against local state, and classifies every
disagreement.

Somebody else's order on the same account, or one of ours from before the local record began. Adoption is off by default and deliberately narrow when armed.

## What each policy does with it [#what-each-policy-does-with-it]

| Policy                | Verdict               |
| --------------------- | --------------------- |
| `hybrid`              | holds for an operator |
| `synthesize`          | **auto-applies**      |
| `quarantine`          | holds for an operator |
| `external-quarantine` | holds for an operator |

Every verdict above is **computed** from the policy the runtime actually applies, not written down
beside it. That is not decoration: the opposite claim about the default policy was stated in six
places in this codebase and was false in all six, so the export asks the function and the docs
render the answer.

When this kind auto-applies it produces real events, which is why the verdict above matters operationally.

Held means an operator sees an alert carrying the events the pass WOULD have folded, and confirming it folds exactly those — the same events, with a person in front of them.

## Reading this in an incident [#reading-this-in-an-incident]

The [policies page](/docs/trader/concepts/reconciliation/policies) covers the four presets and when to
choose each; the rollout rule for a newly wired venue is to start under `quarantine` until that
venue's position reports are proven complete, precisely because position drift auto-applies under
the default.

## Where this comes from [#where-this-comes-from]

`vike_exec::recon::DivergenceKind` and its origin class — this kind's evidence is
external — the evidence is venue activity the local core did not originate — with every policy verdict computed through
`vike_exec::recon::mode_applies`, exported as `rosters.json` at every release.


# The exec contract (/docs/trader/developer/testing/exec-contract)



The venue-adapter execution contract spans every bridge crate and lives in none of them, so its
harness is hosted one layer down, in `crates/vike-bridge-core/tests/bridge_conformance.rs`. Before
it existed the contract was verified ad hoc, per venue. Now it is one scenario table run against
every covered venue's **real**, fixture-tested `event_mapper`, folded through the **real**
`vike_exec::ManagedOrder` FSM — the same code the live core folds through. Only the venue-native
JSON frames and the mapper are venue-specific; the scenarios, the folds and the assertions are
shared.

## The three clauses under test [#the-three-clauses-under-test]

The file's header states them as the contract:

* **Emitter split** — Rust emits `OrderSubmitted` synchronously at submit; the venue emits
  `OrderAccepted`, `OrderRejected`, `OrderCanceled` and the fill events.
* **No silent vanish** — a dead venue path must synthesize a terminal `OrderRejected`.
* **Exactly one terminal** — the FSM must reach exactly one of `Filled`, `Canceled`, `Rejected`,
  `Denied` or `Expired`. Illegal or out-of-order events are dropped idempotently, never corrupting
  the single terminal.

The oracle is not a re-implementation. `ContractOrder` wraps the real FSM and mirrors
`ExecutionEngine::on_event`'s thin per-order policy: the bare-fill versus wrap-fill split, trade-id
dedup so a reconnect replay never double-counts, and a counter for the one genuinely bad case — a
terminal event that failed to apply while the order was still live. That counter must end at zero
in every healthy scenario, and the terminal count must end at exactly one.

## The four scenarios [#the-four-scenarios]

1. **Lifecycle** — submit, accept, partial fill, full fill reaches `Filled` with one terminal.
2. **TransportDeath** — a dead venue path still synthesizes a terminal, driven through the exact
   shared seam each venue really uses: `ExecActor` for command venues, `resolve_ambiguous_submit`
   for REST-poll venues.
3. **CancelAfterClose** — a late venue `OrderCanceled` replay *and* a late `OrderCancelRejected`
   advisory arriving after the order already closed are both dropped without corrupting the single
   terminal.
4. **ReconnectMidOrder** — driven through the real shared pump `run_user_data_forever` with a
   scripted drop and reconnect that replays the mid-order partial: no duplicate terminal, no
   double-counted fill, no lost terminal.

## The two axes [#the-two-axes]

`ExecKind` selects which no-vanish seam TransportDeath exercises — `CommandActor` (a dead thread
synthesizes `OrderRejected`) or `RestPoll` (an ambiguous or timed-out submit resolves through the
shared `resolve_ambiguous_submit`).

`FillShape` is the orthogonal axis, and it exists because fill granularity genuinely differs.
Crypto venues stream `Cumulative` partials — each piece a distinct `OrderPartiallyFilled` before the
terminal `OrderFilled`. The FX, CFD and equity venues fill `Whole`: one execution reports the full
quantity, and their real mappers have no partial-fill path at all. Alpaca even folds a
`"partial_fill"` SSE event into `OrderFilled`. Lifecycle and ReconnectMidOrder branch on this so a
whole-fill venue is exercised faithfully instead of being asserted into a state it can never emit;
TransportDeath and CancelAfterClose are already shape-agnostic.

<Callout title="A doc comment is not a declaration">
  `ExecKind`'s own comment records why it names no venue list: the list that used to live there named
  four of the seven `CommandActor` venues, was written when the table held six, and never grew when
  three more joined. `FillShape` is the counter-example it points at — its variants name venues, but
  each name carries the *reason* (that venue's real mapper has no partial-fill path), so it reads as
  evidence rather than as a roster somebody must keep in sync.
</Callout>

## Covered and deferred [#covered-and-deferred]

`covered_bridges()` returns the venues in the table; `DEFERRED` records the rest with a reason each.
No coverage fraction is written anywhere — the two lists partition the roster, so their own lengths
are the count, and `coverage_matrix` prints the whole grid under `--nocapture` together with the
deferral reasons, so what did *not* run is explicit. The
[roster gate](/docs/trader/developer/testing/roster-exhaustiveness) then holds the partition exact
against `vike_model::VENUES`.

<Callout type="warn" title="Deferring a venue: name the shape, never a feature gate">
  The FXCM row is the worked example, and its removal is recorded in `DEFERRED`'s own doc comment.
  The old reason read "behind the `fxcm` feature; default build is an Unavailable stub — no real
  event\_mapper is compiled to drive". Every clause of that was false: the crate declares its module
  tree with no `cfg` at all, `map_fxcm_event` was always compiled in every build, and the feature
  gates nothing but `build.rs`. The obstacle was one keyword, `mod` instead of `pub mod`, behind a
  reason nobody re-read for as long as it sounded plausible. A feature is a claim about a build, and a
  build is exactly the thing a stale reason stops describing.
</Callout>

FXCM is now covered, and its row is instructive for the opposite reason: its "frames" are JSON
envelopes the C++ shim builds, its accept is the synchronous return of a placement FFI call, and its
comment states plainly what a green row does **not** say — nothing about the shim, the FFI, or any
ForexConnect behaviour behind it, because no CI machine has ever linked that SDK. The row covers the
venue's pure layer, which is where its last four recorded defects lived.

## Frames from real wire [#frames-from-real-wire]

A venue's frame methods may source their template from that venue's committed sanitized capture
under `crates/bridges/<venue>/tests/fixtures/captured/`, written by the venue's opt-in capture smoke
and consumed here through `captured_template`. The harness loads the first captured frame as a
*structure* template — the real envelope, field set and value types — and patches only the
scenario-driven leaves through the type-preserving `patch_f64` and `patch_str`. Absent a fixture it
falls back to the hand-authored frame, byte-identical to before. The coverage printout names which
venues sourced captured templates, so what ran against real wire is never a guess.

Related: [the order lifecycle](/docs/trader/concepts/order-lifecycle),
[the ExecutionClient seam](/docs/trader/concepts/execution-client-seam),
[test doubles](/docs/trader/developer/testing/test-doubles).


# Testing (/docs/trader/developer/testing)



Verification in this workspace is layered, and the layers are not interchangeable. A unit test pins
an example. A property test pins a law. A conformance harness pins a contract that spans crates and
belongs to none of them. A gate pins a claim about the repository itself, including claims made in
prose. A smoke test proves a real venue still answers the way the adapter believes. A latency gate
proves a tail. Each tier catches a failure class the tier below it structurally cannot see, which is
why all six exist rather than one very large test suite.

## The tiers [#the-tiers]

| tier           | what it proves                                                         | where it lives                                                                                                                                                                                                                          |
| -------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| unit           | one example, one function                                              | `#[cfg(test)]` modules beside the code                                                                                                                                                                                                  |
| golden fixture | this arithmetic has not moved, bit-for-bit                             | `fixtures/`, replayed from the crate each round gates — r1/r3/r4 by `crates/vike-backtest/tests/parity.rs`, r0 by `crates/vike-model/tests/fill_parity.rs`, r5 by `crates/vike-exec/tests/parity/r5_parity.rs`, r6 by the bridge crates |
| property       | a law over random inputs the examples never reach                      | the `proptest` suites                                                                                                                                                                                                                   |
| conformance    | a contract every venue adapter must satisfy                            | `crates/vike-bridge-core/tests/bridge_conformance.rs` and its market-data twin                                                                                                                                                          |
| gate           | a claim about the tree — rosters, layering, prose, generated artifacts | `crates/vike-ops/tests/` and its siblings                                                                                                                                                                                               |
| smoke          | the live venue still behaves as the adapter assumes                    | `crates/bridges/<venue>/tests/*_smoke.rs`                                                                                                                                                                                               |
| latency        | the core hop's tail, in nanoseconds                                    | `crates/vike-core/tests/runtime_latency.rs`                                                                                                                                                                                             |

## Unit and golden [#unit-and-golden]

The bottom tier is ordinary: `#[cfg(test)]` modules next to the function they pin. Above them sit
the frozen golden fixtures — exported once, then frozen, with every exporter deleted from the tree,
so the committed bytes *are* the oracle and the comparisons stay exact. Floats are IEEE-754 hex bit
patterns, and the rule that governs them is a review rule rather than a mechanical one: never widen
a tolerance to make a test pass. The [parity gate](/docs/trader/concepts/parity-gate) is what that means
in full, and [adding to the parity suite](/docs/trader/developer/testing/parity) is the procedure.

## Property [#property]

Golden fixtures pin examples somebody chose. `proptest` suites pin the laws those examples were
supposed to illustrate, over inputs nobody chose. `crates/vike-exec/tests/order_fsm_props.rs` folds
arbitrary lifecycle-event sequences through the order FSM and asserts six laws including terminal
absorption and error purity; `crates/vike-model/tests/scalar_props.rs` asserts grid-rounding
idempotence with *exact* equality. The workspace convention is that a counterexample is a real
finding: stop, report, and commit the generated `proptest-regressions/` seed so it reproduces.
See [property tests](/docs/trader/developer/testing/property-tests).

## Conformance [#conformance]

Two harnesses in `crates/vike-bridge-core/tests/` machine-check the venue-adapter contract that no
single venue crate contains. The [exec contract](/docs/trader/developer/testing/exec-contract) runs one
scenario table against every covered venue's real event mapper folded through the real
`vike_exec::ManagedOrder` FSM. The
[market-data contract](/docs/trader/developer/testing/market-data-contract) runs one invariant table
against every covered venue's real L2-book normalizer. Each carries a
[roster gate](/docs/trader/developer/testing/roster-exhaustiveness) so a new venue is either covered or
deferred with a written reason — never silently absent.

## Gate [#gate]

A gate is a test whose subject is the repository. Layering, the derived CI crate roster, the
settings registry, the per-venue capability tables, the committed generated artifacts, and prose
itself — citations, unrun commands, duplicated constants — all have one. The whole family, and how
to read a failure from each, is the [developer guide](/docs/trader/developer). Two gates belong to this
section specifically: the [wire quantizers](/docs/trader/developer/testing/wire-quantizers) source gate,
and the smoke-lane credential guard described under [live smokes](/docs/trader/developer/testing/live-smokes).

## Smoke [#smoke]

Every venue's `*_smoke.rs` is `#[ignore]`d, so an ordinary `cargo test` never runs one. Most are
credential-gated on top of that and self-skip unless demo credentials are present in the project
credential store. The keyless ones are not: where a smoke reaches no account — public streams and
REST, or a local accepting client — there is no credential to gate on and `#[ignore]` is the only
gate; Polymarket's Gamma catalog smoke gates on an explicit `POLY_GAMMA_SMOKE=1` instead. Some place
real orders on demo accounts. They are the only tier that can catch a venue changing its wire, and
the only tier that touches an account, which is why they are never run casually.

## Latency [#latency]

`crates/vike-core/tests/runtime_latency.rs` holds both gates and measurements, and its header is
explicit that only three of its tests assert a derived ceiling. Everything else measures: the
submit, book and coid variants assert nothing about timing at all, and the snapshot-build one keeps
a 1 ms p50 sanity ceiling its own comment calls a liveness check rather than a budget. The split is
deliberate — as that file puts it, an uncalibrated ceiling is a flaky gate, "which is worse than no
gate at all because people learn to re-run it rather than read it." The meaning is
[the latency gate](/docs/trader/concepts/latency-gate); the procedure is
[running the latency gate](/docs/trader/developer/testing/latency).

## Two rules that cut across every tier [#two-rules-that-cut-across-every-tier]

<Callout title="One owned double, behind a feature">
  Shared test doubles live in exactly one place each and sit behind a `test-support` cargo feature
  that a default build never compiles. `crates/vike-bridge-core/src/scripted.rs` replaced roughly
  eight private copies of the same scripted WS stream. See
  [test doubles](/docs/trader/developer/testing/test-doubles).
</Callout>

<Callout type="warn" title="A property suite may not join a grouped test binary">
  `crates/vike-backtest`'s `tests/` are grouped into shared binaries to cut link time, and the
  admission rule for joining a group is: the file must be plain — no `#![cfg]`
  feature gate, no `#[ignore]`d test, no `proptest` regression sidecar, and no process-global mutation
  such as `env::set_var`, because one binary runs its tests as threads in one process. Property
  suites, feature-gated files, store-backed files and `#[ignore]`d files each stay their own binary.
</Callout>


# Running the latency gate (/docs/trader/developer/testing/latency)



The core-hop tail gate is a microsecond timing assertion over the live runtime's fold loop, and
running it is not an ordinary test invocation. This page is the procedure. What it *means* — which
numbers gate, which only measure, and why the split is deliberate — is
[The latency gate](/docs/trader/concepts/latency-gate).

## Run it [#run-it]

`crates/vike-core/tests/runtime_latency.rs` is a release-only harness. Every test in it carries
`#[ignore = "release-only latency harness (see module doc)"]`, so a default test run compiles it and
executes nothing.

```sh
cargo test -p vike-core --release --test runtime_latency -- --ignored --test-threads=1 --nocapture
```

Two of those flags are load-bearing; the third is not:

* **`--release`.** The module header says it outright: timing-sensitive, skipped in the debug run.
* **`--test-threads=1`.** Correctness, not tidiness. Every harness thread busy-spins waiting for
  *its* core worker, and the gate runs pinned to a small core set, so the default parallelism puts
  N spinners plus N workers on those few cores and the spinners starve the workers they wait on.
  Priority inversion, not slowness — measured 2026-07-29, three tests ran in 0.94 s and a fourth
  livelocked the binary at 380 % CPU for five minutes, the incident
  `crates/vike-core/tests/runtime_latency.rs`'s `SPIN_DEADLINE` records. It also makes the numbers
  honest: run in parallel, these tests contend for the very cores whose p99 they report, noise that
  once hid a 27× tail regression.
* **`--nocapture`.** Habit, not a requirement — nothing in the harness depends on it. `HopStats::report`
  writes its `LATENCY-GATE` line straight to the stderr *handle* rather than through `eprintln!`,
  precisely so the numbers survive libtest's capture on a **pass**: a gate whose figures are legible
  only when it is red cannot be trended. The CI step has never passed the flag, and every variant's
  line is in its logs regardless.

## Reading a red run [#reading-a-red-run]

Only three tests assert a derived ceiling — `p99_core_hop_under_10us`,
`p99_core_hop_under_10us_with_journal` and `p99_core_hop_under_10us_with_journal_snapshots`,
reporting the variants `baseline`, `journal` and `journal-snap`. The submit-lane, book-lane and
coid harnesses beside them assert nothing about timing, deliberately, and snapshot-build only the
1 ms p50 sanity ceiling it inherited — a liveness check with \~100× headroom, not a derived budget:
deriving `JOURNAL_P99_NS` cost 98 CI attempts, and an uncalibrated ceiling is a flaky gate — worse
than no gate, the header says, because people learn to re-run it rather than read it.

Each variant reports its whole distribution over `HOP_SAMPLES` hops, so read the failure line rather
than the first assertion. `assert_hop_budget` checks p99 first, which on the journal variants is the
*least* informative number in the file: 15 of the 18 red attempts in the 2026-08-05 calibration
carried a `hops > 100 µs` and/or p99.9 cause instead, and `JOURNAL_HOPS_OVER_100US` is the ceiling
that binds today. `JOURNAL_P99_NS` was derived at 2.0× the worst *green* observation, from green
observations only — a figure from a red attempt is evidence of how badly the gate can be disturbed,
never of how the code behaves when healthy.

<Callout type="warn" title="A red run is not yet a regression">
  Three attempts inside one job on one box is three samples. The module header's rule is that a
  genuine confirmation is reproduction in a separate later run, and the in-band discriminator is the
  `baseline` variant's p99 — the journal-free canary no journal change can move, denormalized onto
  every persisted row as `baseline_p99_ns`. A `baseline` that moved with the rest means the box was
  disturbed, not that the code regressed.
</Callout>

## Reading the persisted series [#reading-the-persisted-series]

`HopStats::report` writes one `LATENCY-GATE` line per variant straight to the stderr handle, and the
CI latency step appends one JSON row per (run, attempt, variant) to a durable series file on the
measurement box — on pass and fail alike, every `k=v` after the marker carried verbatim. Read that
series; do not re-scrape job logs. Three traps come with it:

* The schema is **flat**, with a `variant` field. `.journal.p999_ns` matches nothing and fails
  silently — the query is `select(.variant=="journal") | .p999_ns`.
* A pull-request row's `sha` is an ephemeral merge commit, so the code trend filters
  `event=="push" and branch=="main"`; and a row whose `pin` differs from its `pin_requested` was
  measured on the wrong cores.
* `p50_ns` is indifferent to box load — 1 353–1 523 ns across every load bucket measured 08-15 to
  08-24 — while only the tail moves. A four- or six-figure "p50" quoted anywhere is a p99.9 that has
  been mislabelled.

## Adding a variant [#adding-a-variant]

A new measurement variant needs **no workflow change**: printing the report line is the whole of
joining the series. Two things about the label are gated rather than commented, at the one choke
point every label passes through — `check_report_line`, called from `HopStats::report`. A label
containing whitespace does not produce a mangled row, it produces a plausible row filed under a
truncated name; and two harnesses sharing a label merge two distributions into one trend line with
nothing to separate them afterwards.

The trap a new harness hits first is growth. The runtime publishes whenever the core is about to go
idle, and this file's request/response pacing makes it idle between every message, so
`CoreSnapshot::build` runs once per message and walks the whole order registry. A harness that
submits N orders under N distinct client-order-ids is O(N²), and its tail reports index-map growth
rather than the lane it claims to — `run_submit_hop` pins the registry by reusing one coid.

## An honest A/B [#an-honest-ab]

The shape is what matters, not the exact commands: dedicate a small core set by shrinking the
system slices onto the rest, run the built test binary in a scope of its own holding those cores,
and release them afterwards — releasing is mandatory. The scope needs its **own** top-level slice,
because a child cgroup cannot hold CPUs its parent lacks, and scopes reject exec properties, so
real-time priority comes from `chrt`. That fence is the one the harness already assumes:
`crates/vike-core/tests/runtime_latency.rs`'s module doc describes the binary as running "under
`chrt -f 50` on four reserved cores" of a box that also carries ClickHouse and the live recorders.

Then **interleave the variants and take medians of at least eight reps**: single runs and four-rep
samples produced contradictory rankings all day. A real A/B in this tree was measured that way and
records it — `crates/vike-core/src/runtime/mod.rs`'s `note_event` cites "shielded cores, SCHED\_FIFO
50, `--test-threads=1`, 8 interleaved reps" for the change that took the baseline core-hop p99 from
2,024 ns to 802 ns. Shielding does not make the gate deterministic either — the dominant noise is
memory bandwidth and last-level cache, shared box-wide regardless of pinning, which is why the CI
job retries three times with a settle between attempts.

<Callout type="warn" title="Cancelling a run orphans the process">
  Cancelling the job kills the runner's worker but not the real-time child, which is re-parented and
  keeps running at SCHED\_FIFO on the reserved cores — one was found alive 25 minutes at 380 % CPU. Two
  of them wedge the box, taking a `/proc` scan from 53 ms to over two minutes. The gate reaps them
  before measuring with an anchored `pkill`; kill any stragglers by hand after cancelling your own.
</Callout>


# Live smokes (/docs/trader/developer/testing/live-smokes)



Every venue's `*_smoke.rs` lives under `crates/bridges/<venue>/tests/` and is the only tier that can
catch a venue changing its wire. It is also the only tier that reaches an account, and the ones that
do are gated twice over; none of them runs by accident.

## The double gate [#the-double-gate]

**`#[ignore]`** — an ordinary `cargo test` never runs one. It must be named with `--ignored`.

**Credentials** — a smoke that reaches an account self-skips unless demo credentials are present in the
project credential store. A skip is a `tracing::warn!` and an early return, not a failure, because an
absent store is the ordinary unconfigured state. The keyless ones — public streams and REST, or a local
accepting client — reach no account and have nothing to gate on, so `#[ignore]` is their whole gate;
Polymarket's Gamma catalog smoke gates on the explicit string `POLY_GAMMA_SMOKE=1` instead.

Some smokes add a third gate. The capture arms are triple-gated: `#[ignore]`, plus credentials, plus
the exact environment string `VIKE_CAPTURE_FIXTURES=1` — so a plain `--ignored` run self-skips and the
committed fixture files can never be rewritten by accident.

Read-only and order-placing smokes are kept in separate tests. Binance's reconcile smoke is the
pattern: two read-only fetch tests that build the real reconcile client in both its spot and perp modes
and call all four report methods, and one clearly separated order-lifecycle test that rests a
far-from-market limit order — at half the live mark, sized to clear the minimum notional, so it can
never fill — then proves it appears through the report fetch, cancels it, and proves it is gone.

<Callout title="A venue's own rules ride on top">
  Dukascopy's smokes must be run one at a time, because each spawns its own sidecar login and the venue
  may reject concurrent sessions on one demo account. Its ladder is also weekend-tolerant: FX is closed
  from Friday evening to Sunday evening, and a market order then comes back venue-rejected — which still
  proves the full submit-to-event round trip, so the test logs it and passes, and only the fill and
  close legs need an open market.
</Callout>

## The two CI lanes, and why neither is scheduled [#the-two-ci-lanes-and-why-neither-is-scheduled]

A subset runs in CI through one workflow with two lanes: a **read-only** lane (every wired venue's
reconcile fetch smoke plus the credential-less public market-data smokes) and an
**order-lifecycle** lane (the leave-flat trio — rest a far-from-market demo limit order and cancel it;
one also amends first). Both are dispatched by hand and fire on no schedule and on no push,
deliberately, because one of them submits orders.

<Callout type="warn" title="The job keys name a cadence that does not exist">
  The workflow's two jobs are still keyed `readonly-nightly` and `weekly-order-lifecycle`. Those names
  are historical: the file once carried a schedule block, the block was deleted and every prose mention
  rewritten, and the job keys — the loudest place a reader meets a cadence claim — were left, because
  they are identifiers an operator page already cites and renaming them must land in the same commit as
  that page. The file's own header states the correction in the repository's usual shape: say what the
  name claims, say that it is false, and leave the name findable.
</Callout>

An empty lane can never read green. Because a store-absent run makes every credential-gated smoke
self-skip, a skip-honesty step fails the run **by name** for every required venue that skipped: a lane
that proved nothing for a venue must not report success for it.

## The credential refusal [#the-credential-refusal]

Both lanes run one shared guard over the store before anything is linked, and it exists as a file
because it was once written twice and the two copies disagreed.

The rule had been upgraded in the read-only lane from a venue list to a property — and the
**order-placing** lane kept the old by-name test. For that window a live or mainnet key sitting in the
smoke store was refused by the lane that only reads and waved through by the lane that submits orders.
The read-only lane's own comment described that hole as belonging to "an earlier version", a hundred
lines above the lane that still had it. As the script's header puts it: a law spelled twice is a law
that drifts.

The rule is a **property**, not a venue list: any key naming a live or mainnet environment, whatever
venue it belongs to, plus two by-name families whose demo spelling is still a real account.

Two of its behaviours are worth carrying:

* an **absent** store exits clean — refusing there would fail every run on a box that simply has no
  store, and the credential-gated smokes self-skip anyway;
* a store that **exists and cannot be read** is refused outright. That was measured against an
  unreadable file holding a live key: `grep` exits 2 on a permission error, the status was swallowed,
  and the guard printed "no live/mainnet credential family present" and exited zero. That is a guard
  reporting *safe* when it does not know, which is the one answer a guard must never give.

## The gate that runs the guard [#the-gate-that-runs-the-guard]

`crates/vike-ops/tests/smoke_guard_gate.rs` holds the guard to one spelling — and it does so by
**executing** it, which is the second defect it was written for. Everything it originally asserted was
a text scan, and a mutation campaign measured the cost: deleting the single line `exit 1` from the
script left all four checks green. Nothing constructed a process and nothing examined an exit status,
so the one property the guard exists to have — *it fails the step* — was asserted nowhere. With that
line gone the script falls through to its closing message and exits zero: the lane prints a red error
annotation, links the store anyway, and the order-placing lane goes on to submit orders.

The gate now runs the real script against both a dirty store and a clean one, checks that the refusal
names the key and never the value, asserts both lanes call the one guard and that no lane re-inlines
the pattern, and asserts neither guard step can be defeated by its lane. Its header also declares the
mutants that still pass — step ordering is not checked, and a hypothetical third lane is not required
to carry a guard — because a declared limit is a finding and an undeclared one is the defect the file
was written about.

Related: [test doubles](/docs/trader/developer/testing/test-doubles) for what a capture smoke writes, and
[the venues tree](/docs/trader/venues).


# The market-data contract (/docs/trader/developer/testing/market-data-contract)



`crates/vike-bridge-core/tests/market_data_conformance.rs` is the market-data twin of the
[exec contract](/docs/trader/developer/testing/exec-contract). Where that harness machine-checks the
event contract, this one machine-checks the book seam: the L2 invariants each covered venue's
**real** `market_data::route_frame` normalizer must uphold. One invariant table, parameterized over
the `vike_bridge_core::pump_spec` roster, so a new venue cannot silently escape classification.

## The three invariants [#the-three-invariants]

1. **Monotonic sequence** — book updates fold in the venue's sequence order. A delta-sync venue
   folds a contiguous delta and *drops* a stale or duplicate one, so the book's `last_seq` never
   regresses. A snapshot-full venue's frame advances `last_seq` to the frame's timestamp and
   replaces the book.
2. **Gap triggers a resnapshot** — a sequence gap answers `MdEvent::Resync`, never a silent fold
   across the gap. The gapped delta is not applied and the book — best bid, best ask and `last_seq`
   — is left exactly as it was, so the pump re-seeds from a fresh snapshot rather than serving a
   corrupt book. Delta-sync venues only.
3. **Derived L1 consistency** — for a venue whose live pump derives top-of-book from the L2 book
   rather than from a dedicated book-ticker channel, that derived quote must equal the book's real
   best bid and ask; a one-sided book derives no quote.

## Why one table needs two book models [#why-one-table-needs-two-book-models]

The covered venues do not share one book protocol, and `BookModel` is the axis that admits it.

**`DeltaSync`** — a snapshot seeds the book, then incremental deltas fold under a per-event
sequence rule and a gap triggers a resync. Three shapes sit inside that one variant:

* **binance and aster** seed `lastUpdateId` from a REST snapshot, then fold `@depth` diffs under the
  `U`/`u` span rule; a diff whose `U` exceeds `last_seq + 1` is a gap. L1 rides a separate
  `@bookTicker` channel, so invariant 3 is not applicable.
* **bybit** takes an `orderbook.50` snapshot then strict `u += 1` deltas through
  `L2Book::delta_decision(Strict)`; both a forward jump and a `u` regression (a venue restart) are
  gaps. Bybit has no book-ticker channel, so its quote is derived from the L2 top through
  `quote_from_book` — it is the one covered venue that exercises invariant 3.
* **deribit** opens with a `type:"snapshot"` frame anchored on `change_id`, then chains `change`
  frames on `prev_change_id` matching the previous frame's `change_id`. Its contiguity is an explicit
  **back-pointer**, not a numeric step: `change_id` is venue-global and jumps arbitrarily between
  frames. Stale is judged *first*, before the chain check, because a replayed frame's
  `prev_change_id` no longer matches the advanced anchor either, and a chain-first reading would
  report a harmless duplicate as a gap.

**`SnapshotFull`** — okx's `books5` channel pushes a full top-five snapshot every frame with `ts` as
the sequence, so there are no deltas to gap across. Invariant 2 is recorded as not applicable rather
than skipped, and invariant 1 asserts the full-state advance.

<Callout title="Deribit is what keeps the table honest">
  It is the covered row whose contiguity is a back-pointer rather than an arithmetic step. Without it
  the shared invariant table would quietly assume numeric sequence contiguity, which three of the four
  covered venues happen to have.
</Callout>

## The bybit row is a retired bug, guarded [#the-bybit-row-is-a-retired-bug-guarded]

The live-versus-backtest divergence ledger once carried "Bybit book fold has no gap arm — binance
and okx resync, bybit folds across dropped frames silently until the five-minute reseed." That was
resolved when bybit's delta was routed through the shared `L2Book::delta_decision(Strict)`, so bybit
now answers `MdEvent::Resync` on a gap exactly like binance. The harness therefore covers bybit as a
**passing** delta-sync row, which turns a retired ledger item into a permanent regression guard: if
bybit's gap arm is ever removed, `gap_triggers_resync_all_delta_sync_venues` goes red. The task brief
that commissioned this harness expected bybit to be deferred as a known divergence; the file's own
header records the decision to guard the fix instead of documenting a bug that no longer exists.

## Deferrals, and the two kinds of them [#deferrals-and-the-two-kinds-of-them]

Every other roster venue carries a `DEFERRED` row with a written reason, and the reasons split into
two genuinely different categories.

**Not on this seam.** Aster's market data is a verbatim re-export of binance's
`family::depth::route_frame`, so the shared normalizer and its gap arm are already exercised through
the binance row and a dedicated aster row would re-run byte-identical assertions. Hyperliquid has an
`l2Book` feed, but it decodes in its own market-feed module rather than through this `route_frame`
seam. Polymarket's book sits behind its crate feature and uses a feed-local sequence convention the
feed derives itself. Each becomes a drop-in row the day its decoder is lifted to this shape.

**No book at all, structurally.** Oanda's pricing stream serves an *unsequenced* top-of-book ladder
— no sequence id, no delta grammar, every frame a full snapshot of the top — so all three invariants
are inexpressible, and its quote path is covered instead by its own decoder fixtures and
freshness tests. IG is a dealer venue publishing its own two-sided price: L1 and candles, no ladder.
Alpaca, cTrader and IBKR deliver bars, quotes and trades on their own pumps. FXCM has no live
market-data lane of any kind — `pump_spec` classifies it `NoPump` and its capability row declares
`live_data: LiveDataCaps::NONE`.

## The roster gate [#the-roster-gate]

`md_conformance_roster_is_exhaustive` asserts that covered and deferred partition
`vike_model::VENUES` exactly once, that every deferral reason is non-empty, and — the check unique to
this harness — that every **covered** venue is `MarketPumpSpec::OnDriver` in `pump_spec`, because a
venue must have a live market feed before its book can be conformed. See
[roster exhaustiveness](/docs/trader/developer/testing/roster-exhaustiveness) and
[the data model](/docs/trader/concepts/data-model).


# Adding to the parity suite (/docs/trader/developer/testing/parity)



The parity suite is the set of tests that pin arithmetic exactly rather than approximately. This
page is how to add to it. What the suite *is* — frozen bytes, the retired oracle, why bit-exactness
is still the criterion — is [The parity gate](/docs/trader/concepts/parity-gate).

## Where a new test goes [#where-a-new-test-goes]

`crates/vike-backtest/tests/parity.rs` is one binary over five member files included as plain
modules; the tests, their names and their fixtures are byte-unchanged from when each was its own
binary, so only the `--test` slot moved. Filtering still works by name:

```sh
cargo test -p vike-backtest --test parity -- broker_sim_bit_parity
```

The eligibility rule for joining a grouped binary, stated in that header: the file must be
**plain** — no `#![cfg]` feature gate, no `#[ignore]`d live or heavy test, no `proptest` regression
sidecar, no process-global mutation (`env::set_var`, `set_current_dir`). A plain test run executes
one binary's tests as threads in a single process, so a file mutating process state would turn
independent binaries into a race.
Everything else — store-backed, feature-gated, ignored, and every property suite — stays its own
binary on purpose.

## A new golden fixture [#a-new-golden-fixture]

<Callout type="warn" title="The frozen rounds cannot be regenerated">
  `fixtures/r0` through `r6` were exported from the Python app while it was still the source of truth,
  and every exporter was deleted from this tree. The committed bytes **are** the oracle: a changed
  fixture byte is a changed contract, not a refresh. `r1_parity`'s loader asserts only that the
  manifest records the exporting oracle's SHA as provenance. A missing file is a deleted or moved
  fixture, never a stale one — and the dead exporter path stays named in the panic message on purpose,
  because it is the evidence for where the bytes came from. A citation whose target was genuinely
  deleted goes in the citation gate's exception table; it is never simply removed.
</Callout>

New golden expectations are still authored — just not by re-running an oracle. `fixtures/recon/` is
the sanctioned shape: hand-written scenarios with no manifest, auto-discovered at run time by
`crates/vike-exec/tests/recon/recon_fixtures.rs`'s `recon_golden_fixtures`, where adding a directory
is authoring a new expectation rather than regenerating an oracle.

Whatever you add must be *replayed*. `crates/vike-ops/tests/fixture_consumption_gate.rs` fails CI on
any committed file under `fixtures/` that no test under `crates/` consumes, unless it carries a
written exception row saying why. The check is text-only and recognises three shapes: the full
relative path spelled verbatim in one file; the directory and the bare file name in the **same**
file; or a fixture under a `DISCOVERY_ROOTS` entry whose consumer enumerates directories and names
no file. Two files each holding one half do not count. The gate exists because a retired engine took
its parity suite with it and left four fixtures behind, reading as coverage and pinning nothing.

Floats go in as IEEE-754 hex bit patterns — `vike_model::f64_from_hex_bits` decodes them, and its
doc gives the reason: fixtures carry `f64::to_bits` hex so a last-ulp divergence is unambiguous.

## What a new assertion may claim [#what-a-new-assertion-may-claim]

Two tiers, and neither is ever widened. Pure `+ − × ÷ sqrt` paths assert **exact** equality, because
IEEE 754 requires those operations to be correctly rounded. Outputs derived from `erf`, `exp` or
`log&#x60; gate at **≤ 1e-12 relative** — `crates/vike-options/tests/oracle_parity.rs`'s `assert_rel` is
the shape, and that file's header states the tier and the never-widen rule together.

Portability is the trap underneath. `crates/vike-backtest/tests/libm_platform_probe.rs` spells it
out: IEEE 754 requires nothing of `ln`/`exp`/`pow`/`cos`, so an `f64` *method* call reaches whichever
libm the platform ships, and two platforms disagree in the last bit. Transcendentals therefore come
from the `libm` crate, pinned per crate by a probe file. The frozen `r1`/`r3`/`r4` rounds are
portable by construction only because every module they drive reaches no transcendental and no
`powi` at any arity — the `parity.rs` header lists those modules and tells you to grep them before
trusting the paragraph.

One porting rule outlives the oracle: `vike_model::py_sum` is the CPython builtin `sum()` twin,
Neumaier-compensated since CPython 3.12 rather than a naive left fold. A ported site the original
wrote as builtin `sum(...)` over floats must use it; an explicit accumulate loop stays a naive fold.

## A second oracle instead of a fixture [#a-second-oracle-instead-of-a-fixture]

Where no frozen bytes exist, reconcile two implementations. `engine_kernel_parity` runs the event
engine and the vectorized kernel over identical synthetic bars and requires the same trade count and
a bit-identical final equity — its header says plainly: never widen this to a tolerance.
`riskgate_simbroker_parity` is the risk-model twin, and its discipline is the one to copy: for each
row the two sides must agree, or the row must **pin** the difference with a named reason.
`Row::divergence` is `None` exactly when they agree, so an unpinned divergence fails the test and a
newly pinned one is a loud, reviewable diff rather than a silent behaviour change.

## A new property test [#a-new-property-test]

Property suites randomize the pure cores where golden fixtures only pin examples; the roster is on
[Property tests](/docs/trader/developer/testing/property-tests), and the decimal wire sites on
[Wire quantizers](/docs/trader/developer/testing/wire-quantizers). Three authoring rules travel with them:

* **Bound the domain to the real one, then assert exactly.** `scalar_props` keeps values and steps
  inside the price/tick range so `value/step` stays under f64's exact-integer ceiling, then asserts
  idempotence with no tolerance at all; `format_props` draws only terminating-decimal steps, so the
  internal decimal division is exact and every assertion is an exact comparison. A bounded domain
  buys the exactness — it is not a fudge factor.
* **Commit the regression seed.** A counterexample lands as a `proptest-regressions/` sidecar, and
  the workspace convention is to commit it so a CI-found case reproduces. That sidecar is also what
  disqualifies the file from a grouped binary, above.
* **A counterexample is a finding, not a spec bug.** `order_fsm_props`'s failure policy is the
  model: stop and report with the printed seed, and never adjust the subject to satisfy a property
  without an explicit decision. It also ships a generator-coverage witness, because a property over
  an arm the generator never reaches is vacuously green — worth copying whenever a generator
  enumerates a variant set.

## Relaxing an existing assertion [#relaxing-an-existing-assertion]

Retiring the Python oracle licensed nothing here, and the record that retired it is what a
relaxation is argued against. Four guards, all four required: the comparison stays **exact** — bits
against bits of a stated function of the reference's own values, never a tolerance band; the
reference's raw value is still bounded as the pre-image of that function; a control fails if the
transformation is a no-op on the fixture; and the fixture bytes are untouched. A widened tolerance,
a deleted assertion, or an "expected" value quietly recomputed from the port is not covered by that
record and never was. How to read one is on [Decision records](/docs/trader/developer/decision-records).


# Property tests (/docs/trader/developer/testing/property-tests)



Golden fixtures pin examples somebody chose. Property tests pin the laws those examples were meant
to illustrate, over inputs nobody chose. `proptest` is a workspace dev-dependency, pinned in the root
manifest with its rationale: randomized inputs over the pure cores — sizing, the pinned round and
format wire sites, the risk-gate parity — find edges the golden fixtures miss. It is dev-only, so it
never reaches the shipped order-signing binary's embedded SBOM, though it does join the
source-lockfile supply-chain tree, which the manifest records as the accepted cost of the workspace's
first property framework.

## The suites and the laws they hold [#the-suites-and-the-laws-they-hold]

**`crates/vike-model/tests/scalar_props.rs`** — the grid-rounding primitives every live order's price
and quantity flows through. Idempotence is the central law and also the robust statement that the
result lies exactly *on* the step grid: a rounded value is a fixed point of the rounding. It is
asserted with exact equality, no tolerance.

**`crates/vike-bridge-core/tests/format_props.rs`** — the primary pinned Decimal wire site. Every
step in its generator is a terminating decimal, so the internal Decimal division is exact for these
inputs, which is what lets every assertion be an exact Decimal comparison with **no numeric
tolerance**. As the header puts it, a failure is therefore a genuine wire bug — a real overshoot or
precision leak — never a rounding artifact to be papered over.

**`crates/vike-analytics/tests/sizing_props.rs`** — the eight position sizers. Its header records why
it exists: `Sizer::size` had *zero* direct tests, touched only indirectly by one golden run, making it
the largest money-path coverage hole in the workspace.

**`crates/vike-backtest/tests/riskgate_simbroker_parity.rs`** — the randomized live-versus-backtest
risk parity. Four real money bugs were found on one day in 2026 by manually asking "where is this
rule implemented twice?", and not one had been caught by a test. The suite's own framing is that
**the pinning is the value**: an unpinned divergence fails the test, and a newly pinned one is a
loud, reviewable diff rather than a silent behaviour change.

**`crates/vike-exec/tests/order_fsm_props.rs`** — six laws folded over arbitrary lifecycle-event
sequences against the one mutator of order state: terminal absorption, error purity (a refused apply
never mutates), fill monotonicity and VWAP boundedness, at most one live-to-terminal transition, the
liquidated trap, and the fill-derived restore.

**Parser totality suites** — `crates/bridges/binance/tests/mapper_props.rs` and its bybit twin feed
the real mappers arbitrary JSON, arbitrary text, and every deterministic mutation of every committed
captured fixture. The property is totality: a hostile or truncated frame may decode to nothing, but
it must never panic the user-data pump thread and must never fabricate an event flood — bounded by
`MAX_EVENTS_PER_FRAME`. `crates/bridges/ctrader/tests/framing_props.rs` does the same for the wire
framing every inbound byte crosses first, including the length-prefix denial-of-service edge: a
claimed four-gibibyte frame must not be allocated up front.

## The three rules [#the-three-rules]

<Callout type="warn" title="A counterexample is a real finding, not a property to relax">
  The FSM suite states the failure policy for all of them: stop and report with the seed `proptest`
  prints; never adjust the subject to satisfy a property without an explicit decision. Widening a
  tolerance to make a property pass is the same move the
  [parity gate](/docs/trader/concepts/parity-gate) forbids, arriving from a different direction.
</Callout>

**Commit the regression seed.** The workspace convention, stated in the root manifest beside the
dependency itself, is that any generated `proptest-regressions/` file is committed, so a CI-found
counterexample reproduces on the next run and on every developer's box.

**A slack is documented or it is a fudge.** `scalar_props` allows exactly one floating-point
epsilon — a half-step bound whose slack covers the multiply's rounding, orders of magnitude below the
half-step it guards, so it cannot hide a genuinely off-grid result. Everything else in that file and
all of `format_props` is exact. The sizing suite carries a few-ULP round-trip epsilon on its two cap
properties and says so inline.

**A domain bound is an argument, not a convenience.** `scalar_props` keeps values and steps inside
the real price and tick range so `value / step` stays under the exact-integer ceiling of `f64`.
Beyond that ceiling the multiple itself is unrepresentable and idempotence would fail as a
fundamental floating-point limit rather than a bug — and no venue quotes a `1e-8` tick on a `1e6`
price.

## The trap a property suite is uniquely prone to [#the-trap-a-property-suite-is-uniquely-prone-to]

A property over an arm the generator never reaches is **vacuously green**. The FSM suite answers that
with a generator-coverage witness that fails **by name** when a lifecycle variant goes missing from
its event generator. The binance parser suite answers it differently, by mixing real dispatch keys
into the generator so it actually reaches the mapper's arms instead of bouncing off the first lookup.
Both are the same defence: a randomized suite must prove its randomness arrives somewhere.

## Where a property suite may live [#where-a-property-suite-may-live]

Property suites always get their own test binary. `crates/vike-backtest`'s `tests/` are grouped into
shared binaries to cut link time, and the admission rule in that crate's own notes excludes a file
carrying a `proptest` regression sidecar — along with `#![cfg]` feature gates, `#[ignore]`d tests and
any process-global mutation — because one binary runs its tests as threads in one process. See
[testing](/docs/trader/developer/testing) for the tiers, and
[adding to the parity suite](/docs/trader/developer/testing/parity) for the procedure.


# Roster exhaustiveness (/docs/trader/developer/testing/roster-exhaustiveness)



The workspace has a recurring failure mode with a single cure. A per-venue table grows, each table
keeps its own private copy of the venue list inside its rows and its tests, and adding a venue forces
nothing globally. `crates/vike-model/src/venues.rs` records what that cost: four capability tables
each carried their own list, and the lists **had already drifted** — cTrader was absent from three of
the four.

## The one roster [#the-one-roster]

`vike_model::VENUES` is the authority on "every venue Vike Trader has a bridge crate for", by
canonical lowercase venue id. Its module header states the contract plainly: every per-venue table's
completeness test iterates `VENUES` and asserts a declared row exists for each entry, so adding a
venue there fails **every** table's tests until its rows land, and a new bridge crate cannot ship
without declaring its capabilities.

Registry fallback arms still exist for genuinely unknown strings — `VenueCaps::UNSUPPORTED`,
`VenueMarginSupport::UNKNOWN`, `TifOutcome::NotEmitted`, `FeeSchedule::Free`.

<Callout title="A named row is the declaration that a venue was classified">
  No roster venue may silently ride a fallback. Its row is always named, **even when its value equals
  the fallback** — the named row is the evidence that somebody looked, not that somebody forgot.
</Callout>

## The completeness shape [#the-completeness-shape]

The pattern repeats across the tree under several names, so a grep for any one of them misses the
rest. `every_roster_venue_is_classified` is the most common — `vike_bridge_core::tif`, `pump_spec`,
`mainnet` and `venue_passphrase`, plus `vike_model::attribution` and `vike_catalog::symbol`.
`vike_model`'s capability tables spell theirs `every_roster_venue_has_a_declared_row` — `venue_caps`,
`venue_margin_support`, `venue_amend` and `venue_rate_limits` — while `fees` and `halt_admit` each
carry a one-off of their own (`every_roster_venue_has_a_fee_schedule`,
`every_roster_venue_has_a_named_halt_verify_row`). Each iterates the roster, asserts per venue, and
names the missing one on failure — never a silent fallback.

## The two conformance harnesses [#the-two-conformance-harnesses]

Both `crates/vike-bridge-core/tests/` harnesses carry the same gate, and it is stricter than a
presence check. `conformance_roster_is_exhaustive` and `md_conformance_roster_is_exhaustive` each
assert four things:

1. every deferral reason is non-empty — no blank placeholder deferrals;
2. no duplicate venue id appears in the deferred list;
3. the covered set and the deferred set are **disjoint** — no venue is both;
4. their sizes sum to `VENUES.len()`, and then, per venue, `is_covered` **exclusive-or**
   `is_deferred` holds.

The length assertion is deliberately separate from the per-venue loop, so a stray entry in either
list — a venue id that is not on the roster at all — trips before the loop even runs. The exclusive-or
is the load-bearing check: a new roster venue in neither set fails there, and must be either wired in
or deliberately deferred with a reason.

The market-data harness adds a fifth: every **covered** venue must be `MarketPumpSpec::OnDriver` in
`pump_spec`, because a venue needs a live market feed before its book can be conformed at all.

## Deferral is a first-class answer [#deferral-is-a-first-class-answer]

Neither harness pretends to universal coverage, and neither fakes a venue to reach it. A deferral is
recorded, never silent, and the printed coverage matrix lists the deferred venues with their reasons
beside the grid of cells that actually ran — so what was **not** proven is as visible as what was.

<Callout type="warn" title="Name the shape that does not fit, never a feature gate">
  The exec harness's `DEFERRED` doc comment carries the incident. The FXCM row read "behind the `fxcm`
  feature; default/CI build is an Unavailable stub — no real event\_mapper is compiled to drive", and
  every clause was false: the crate's module tree has no `cfg` at all, its mapper compiled in every
  build, and the feature gates only `build.rs`. The real obstacle was one keyword. The rule that came
  out of it: a deferral names the *shape* that does not fit the seam — a stateful mapper needing a
  two-message join, a protobuf-framed event type, a sidecar over JSON-lines — because a feature is a
  claim about a build, and a build is exactly the thing a stale reason stops describing.
</Callout>

Reasons that pass that bar read like the surviving rows do: IBKR's mapper is stateful and its fills
need an `execDetails` plus `commissionReport` join keyed by exec id over typed, non-JSON reports, so
there is no stateless `decode(&Value)` shape; cTrader's Open API is protobuf-framed and its event
converter takes proto structs and a symbol map rather than JSON.

## The pattern is roster-shaped, not venue-shaped [#the-pattern-is-roster-shaped-not-venue-shaped]

Venues were the first roster to get this treatment; they are not the only one.
`crates/vike-data/src/store_kind.rs`'s `STORE_KINDS` is the history store's layout authority, and
`crates/vike-data/tests/store_kind_gate.rs` derives the live kind set from the code the way the venue
gates derive theirs from `VENUES`. It landed the same way, too — byte-identical, pinning the
disagreements it found rather than fixing them, because a table that changes behaviour on the way in
cannot be reviewed as a table.

Adding a venue is therefore a form to fill in rather than a scavenger hunt: the sites are discovered
one red test at a time, and the scaffold generates a conservative placeholder row in every table so
the author fills in content rather than shape. See
[adding a venue](/docs/trader/developer/adding-a-venue), the
[exec contract](/docs/trader/developer/testing/exec-contract), the
[market-data contract](/docs/trader/developer/testing/market-data-contract), and the per-venue pages
under [venues](/docs/trader/venues).


# Test doubles (/docs/trader/developer/testing/test-doubles)



The rule is one sentence: **one owned double per seam, behind a `test-support` feature**. It exists
because the alternative was measured. Before `crates/vike-bridge-core/src/scripted.rs`, every
consumer hand-rolled the same two doubles — the user-data pump tests each carried a private scripted
queue, and the market and depth drivers plus a pump tap and a re-parse harness each carried a private
canned-text stream. One drift-prone shape, roughly eight copies. The shared
`RecordingSink` in `vike_data::test_support` tells the same story on the live-data seam: one
capturing sink instead of the roughly thirteen inline copies the venue bridges carried.

Every double is gated `#[cfg(any(test, feature = "test-support"))]`, so in-crate unit tests see it
always, and a downstream crate reaches it by enabling the feature **as a dev-dependency**. A normal
build never compiles any of it, and no dev-dependency edge can reach a shipped binary.

## The four homes [#the-four-homes]

**`vike_bridge_core::scripted`** — the scripted stream doubles for the three WS seams: `UserStream`,
`MarketStream` and `DepthStream`. Its behaviour pins are carried verbatim from the copies it
replaced, and they are the interesting part:

* exhausting the script is a **stream-closed error**, the same shape a real disconnect takes, so a
  driver returning an error at the end of a script is expected rather than a failure;
* `send_text` records what the driver sent — subscribe frames, keepalive pings — into a log the test
  reads back, shareable across sessions for the reconnect-test shape;
* an optional shared clock advances before every read, so consuming the script ages an ack or
  freshness watchdog **with zero real sleeps**;
* a timeout step can escalate the reported stall the moment it is popped, because a synchronous
  session gives a test no re-entry point to mutate the stream mid-call.

**`vike_data::test_support`** — a DataFusion-free in-memory `HistStore`, plus the shared
`RecordingSink` and `NoopSink` live-data doubles. Venue bridges build a properties recorder over it
to assert their opt-in recording wiring without pulling the Arrow and DataFusion tree into a test
build.

**`vike_model::strategy::MockBroker`** — a minimal recording `Broker` for the strategy layer. It
captures every market and limit submit and lets a test script the clock, the mark and the position;
the rest of the surface is inert. It lives in the trait's own home, consolidated from near-identical
per-crate copies, so a new strategy-layer test inherits it instead of declaring another broker.

**`vike_bridge_core::capture`** — a separate feature, and a different kind of tool: it writes
fixtures rather than standing in for something. See below.

<Callout type="warn" title="A double's job is fidelity, not convenience">
  The in-memory store is the worked example, and its header argues each choice. Bars are erased on
  append of exactly the fields the real bar schema never persists, so the round trip loses precisely
  what the real store's does. An empty batch returns zero **without consuming the commit key**,
  matching the real store — a double that burned the key would turn a later real append under that key
  into a no-op that happens only in tests. The catalog verbs answer with a real fold over the held
  seams rather than inheriting a default, because the empty default they replaced had a *seeded* double
  answering "no series" while holding rows. And the parts that hold nothing say so honestly: quotes,
  trades and book read empty, and the resample verbs return zero rather than fabricating, because
  resampling zero ticks derives zero bars on the real store too.
</Callout>

## The capture feature: real wire as a fixture [#the-capture-feature-real-wire-as-a-fixture]

`vike_bridge_core::capture` takes a verbatim venue frame and returns it with wire **structure**
preserved exactly — field names, value types, nesting, casing — because the structure is the
drift-sensitive part a hand-authored fixture can never witness. Only a known-sensitive leaf key set
is redacted, and the placeholder depends on the **key**, never on the secret value, so two captures
taken with different session keys sanitize to identical bytes and a re-capture diff shows real wire
drift rather than secret churn.

Venue order ids, trade ids, prices, quantities and timestamps are deliberately **kept** — they are
the fixture's fidelity, and a demo-account order id identifies nothing. Key order inside a frame is
sorted on write, since JSON key order is not wire semantics and sorting keeps diffs minimal.

Fixtures land under `crates/bridges/<venue>/tests/fixtures/captured/` with a provenance stamp,
written by that venue's opt-in capture smoke and then consumed twice: by the venue's normal, CI-run
`captured_wire_replay` test, and as frame templates by the
[exec contract](/docs/trader/developer/testing/exec-contract) harness. The replay test is not
`#[ignore]`d, needs no network and no credentials — and a **missing** committed fixture is a failure,
because a deleted gate must not pass silently.

## Which features imply what [#which-features-imply-what]

`vike-bridge-core`'s `test-support` implies its `full` feature, for a structural reason: the doubles
*are* depth, market-pump and user-data streams, so without `full` there is nothing for them to
double. `capture` implies nothing — standard library and `serde_json` only — and is gated so the
shipped order-signing binary never compiles the fixture writer. `vike-model` and `vike-data` both
declare an empty, additive `test-support`.

The crate also carries a self-referential dev-dependency on itself with `test-support` enabled, which
is the standard cargo idiom for making a feature-gated module visible to the crate's own integration
tests: an integration test compiles the library without `cfg(test)`, so the feature is the only way
in. It never affects a normal build.

Related: [live smokes](/docs/trader/developer/testing/live-smokes) for where captures come from, and
[the live data seam](/docs/trader/concepts/live-data-seam) for what the sink doubles stand in for.


# Wire quantizers (/docs/trader/developer/testing/wire-quantizers)



A wire quantizer is any place in this workspace where an `f64` crosses into `rust_decimal` and comes
back out as the string that is **sent** to a venue or **signed** into an order hash.
`crates/vike-bridge-core/tests/wire_quantizer_probe.rs` is both the measurement probe and the
committed gate over that family. It exists because a survey of the non-`f64` numeric surface reported
nothing to fix — and reached that verdict by *reading source*, which is exactly what this program
exists to distrust.

## The roster is a constant, not a sentence [#the-roster-is-a-constant-not-a-sentence]

`vike-bridge-core`'s own `format.rs` header used to end "`rust_decimal` exists only here and at OKX",
and that had stopped being true. There are three files, not two, and the third —
`crates/bridges/hyperliquid/src/px.rs` — is a whole module of quantizers whose own doc had called
itself the twin of `format_to_step` since it was written. The correction was not to fix the sentence
but to delete it: the probe's `WIRE_FILES` constant is the list, its source gate walks exactly those
files, and the prose points at the constant.

## What these functions amplify [#what-these-functions-amplify]

The probe's own table names the cliff at each site, and it is the reason the family gets a gate
rather than a comment:

| site                                | the decision                                         | one ULP upstream becomes                        |
| ----------------------------------- | ---------------------------------------------------- | ----------------------------------------------- |
| `format_to_step` and its float twin | `(value / step).trunc()`                             | a whole tick or lot                             |
| `format_scaled_to_step_f`           | the same truncation, after an exact rational rescale | a whole step                                    |
| okx's `to_contracts`                | a truncation through contract size and step          | a whole contract step                           |
| hyperliquid's `clamp_price`         | midpoint-away-from-zero                              | a whole tick, **inside the signed action hash** |
| hyperliquid's `round_size`          | toward zero                                          | a whole lot                                     |
| polymarket's `to_base_units`        | a round at an exact half                             | one micro-unit, **inside the signed order**     |

<Callout type="warn" title="Why this is not a last-bit problem">
  Two boxes disagreeing by one ULP produce two prices that differ in the sixteenth digit — invisible,
  and arguably harmless. Push those same two prices through a quantizer whose decision is a truncation
  or an exact-midpoint comparison and the two boxes emit **different wire strings**: a different limit
  price, a different size, and for the two signing venues a different signature over a different order.
</Callout>

The truncation cuts both ways, and the silent direction is the one the header adds. Quantizing *down*
stops an overshoot past a limit, which a venue rejects loudly; the opposite artifact is quiet, since a
value sitting one ULP *below* a grid point emits a whole step less. Whether the ordinary
round-then-format chain ever hit that was unmeasured until this probe measured it — the answer was
**150 of 4096**, a whole step dropped on a value already on the grid, with no perturbation applied at
all. That measurement produced the cure, and the row records `0/4096` today.

## The source gate [#the-source-gate]

`the_wire_quantizers_reach_decimal_through_a_string` is the half that runs on every ordinary test
pass, and it has three arms.

**A required spelling.** Every file in `WIRE_FILES` must contain `Decimal::from_str`. This is the
non-vacuity arm: a scan that opened the wrong path, or read an empty file, would report a confident
zero banned hits, so a positive hit is demanded to make that failure loud.

**A banned set, in two families.** `Decimal::from_f64` and `Decimal::from_f32` are the wrong *door*
into Decimal — they convert the binary value's full noise, where the string route converts the number
the caller meant, and at an exact decimal midpoint the two round opposite ways. The second family is
an enumerated set of platform-libm method spellings: a wire quantizer's job is exact arithmetic, and
a transcendental appearing in one would put a platform-dependent value **inside** the amplifier
rather than upstream of it. Square root is deliberately absent, because the standard requires it
correctly rounded.

**A reached-file roster.** `round_size`'s grid witness calls into hyperliquid's instruments module for
its lot step, deliberately — the witness can only ask its question against the same `f64` the grid was
built from. The cost is a `powi` on the path of a quantizer whose output is signed, in a file
`WIRE_FILES` does not scan. `REACHED_FILES` puts it under the libm half of the ban, because before
that roster the only thing standing between a signed order size and a runtime-base `powf` was prose.
The one exemption is a literal base ten with an exponent the witness itself bounds at 22, where every
power of ten is exactly representable — measured bit-identical across both platforms. The rule
generalizes: a literal `10` or `2` needs nothing, an arbitrary runtime base needs the `libm` crate.

## The hash pin, and what it does not claim [#the-hash-pin-and-what-it-does-not-claim]

The probe also hashes each quantizer's output over a fixed corpus. That corpus is **pure arithmetic**
— a linear congruential generator and the four operations, never a transcendental — because generating
inputs with platform-dependent functions would make every column diverge because of the *inputs*
rather than the subject, a false positive that reads exactly like a real one. A control row hashes the
generator's own output, so a table where every other row moved is a function regression, while one
where the control moved too is a broken corpus. Each row carries a distinctness floor, so a collapsed
corpus cannot pass as agreement, and unrecorded rows read `"RECORD"` — a placeholder that cannot match
a sixteen-character hex hash on length or on content, so an unfinished recording is never mistakable
for a measured value.

One site is covered by the source gate and **not** by the hash pin, for a stated reason: okx's
`to_contracts` is a method on a client, so calling it means standing up a signer and a transport
double. It is not unpinned either — `crates/bridges/okx/tests/offline/r6_okx_parity.rs` compares it
bit-for-bit against the frozen `fixtures/r6` export, a stronger statement than a hash for the values
that fixture carries and a weaker one for every value it does not.

Polymarket's `to_base_units` is reached by **neither** half. It is private, its public caller sits
behind a crate feature this crate does not take, and `WIRE_FILES` names neither its file nor any file
reaching it — so the sharpest cliff in the table above is the one this probe cannot see, and the
header says outright that it deserves a probe in its own crate. Both gaps are declared rather than
left implied.

Related: [the data model](/docs/trader/concepts/data-model) and [the venues tree](/docs/trader/venues).


# Backfill from the GUI (/docs/trader/gui/data-manager/backfill)



Select rows in the Stored grid and the bulk bar offers **Backfill** and **Update**. Both take the
same path: `ToolView::stored_backfill`'s doc records that they alias for now, there being no
separate "ignore gaps, always refetch to now" mode yet, and that unlike Delete the action needs no
confirm — a network fetch plus an idempotent ingest is non-destructive. The selection drains into
`crates/vike-desktop/src/app_methods.rs`'s `maybe_spawn_stored_backfill`, which plans the jobs and
then decides where they run; the authority for that decision is
`crates/vike-app-core/src/backfill_route.rs`.

## Planning [#planning]

`crates/vike-app-core/src/backfill_plan.rs` maps the selection to jobs. Its header states the
gate: only `kind == "bar"` series are backfillable, and on the local route only on a venue in
`SUPPORTED_BACKFILL_VENUES` — `binance`, `bybit`, `okx`, the three the backfill crate has a keyless
kline collector for, over public REST with no credentials. Every other selected series — a quote,
trade or book series, or a venue with no collector yet — is counted as skipped, never silently
dropped from the tally the status line reports.

Each job targets the series' known gap ranges when it has any, and otherwise a single window
ending now; `maybe_spawn_stored_backfill`'s doc fixes that default lookback at 30 days. A run is
one at a time — a click while one is in flight, or with an empty selection, is a silent no-op —
and completion re-triggers the Stored refresh so the coverage bars and gap cut-outs reflect what
landed.

## The route [#the-route]

`backfill_route` is a pure function of one input: the resolved data-service address. `Some` means
the GUI sits on a remote store, so a backfill written anywhere else would be invisible to every
reader, and the jobs go over the wire; `None` means the local store, exactly the path that existed
before routing did. The same resolution decides which store the Studio opens and which the Stored
grid reads, so the plane a backfill *writes* and the store the grid *shows* cannot disagree —
`crates/vike-app-core/src/stored_mode.rs`'s header records the incident that forced this: a wire
backfill once landed its rows in the server's store while the grid kept reading the local one, and
the freshly backfilled series never appeared.

The address is `crates/vike-app-core/src/datahub_resolve.rs`'s `resolve_datahub_addr`, the one
adoption rule: an explicit `config.datahub_addr` always wins; absent it, the active backend's
`Welcome` advertisement fills in; absent both, there is no data service. Explicit-wins is
deliberate — an address the operator wrote into their own config must never be silently replaced
by whatever a daemon claims; an advertisement is a default, not an override. The advertisement
arrives only at a backend handshake, and a link drop clears it. See
[config.toml](/docs/trader/reference/settings/config) for the key and
[Remote runs](/docs/trader/gui/studio/remote-runs) for the Studio's side of the same address.

## Local [#local]

`spawn_stored_backfill_local` runs the backfill crate's kline collectors —
`backfill_binance_klines` and its bybit and okx siblings — against a fresh local store handle on a
worker thread. The status slot reads `Backfilling N series (M skipped)…`, then
`Backfill done: N backfilled, M failed, K skipped`. This arm takes the WIRE route: the binary links no
collector and no local store engine, so the work happens in the datahub and the status slot names
the fix when no datahub answers —
set `config.datahub_addr`, or connect a backend that advertises one. See
[Observe mode](/docs/trader/gui/observe-mode).

## Over the wire [#over-the-wire]

`crates/vike-app-core/src/backfill_wire.rs`'s `run_wire_backfill` makes one backfill verb call per
planned range against the resolved address — "History is fetched by the backend, once, into the
store — clients request, never fetch." The rows are in the server's store before the `BackfillDone`
frame is written, so nothing streams back, and completion re-reads the remote store as the local
arm does. There is no client-side venue gate on this route: which venues have collectors is the
server's roster, `crates/vike-datahub/src/backfill.rs`'s `BackfillTable`, so an off-roster venue is
planned, sent, and answered by the server's own refusal naming its supported set. The production
table is the same three collectors, writing through the handle the server serves, so a backfilled
range is visible to the next bars request on any connection. The `kind == "bar"` gate still
applies — the verb is klines-only.

The capability check happens once, up front. The verb shipped without a protocol-version bump, so
a server must advertise `FEATURE_BACKFILL` in its `Welcome` — only a `backfill-serve` build with
collectors mounted does — and an unadvertised server is refused client-side with zero request
frames sent. `render_wire_backfill_status` gives every outcome a sentence naming its fix:

* unreachable — `Backfill failed: datahub <addr> unreachable (…) — nothing was sent`;
* too old — the server "predates backfill-on-demand", with its advertised features listed and two
  remedies: upgrade it to a `backfill-serve` build, or unset `config.datahub_addr` to backfill the
  local store;
* ran — `Backfill done via datahub: N backfilled (R rows), F failed, S skipped`, with the first
  error appended verbatim, so a server-side refusal reaches the operator instead of dissolving into
  a count.

A per-range failure marks its job failed and the run continues, so one bad venue never strands the
rest of the selection. The same seam serves a chart's own gap requests — the header names the
Data-Manager and chart-gap kline backfill together.

<Callout type="warn" title="What a venue backfill cannot repair">
  `crates/vike-backfill/src/caps.rs`'s header is the finding behind the `kind == "bar"` gate: no
  venue-direct backfill in this workspace serves `trade` or `book` at all. Every collector that talks
  to a venue writes bars, dukascopy resampling them from ticks it also writes as quotes; trades and L2
  come only from archives and paid vendors. So a hole in a recorded tape generally cannot be filled
  from the venue — the recorder writes the kinds a venue backfill never does — and Polymarket is the
  sharpest case, with no price-history endpoint at all. That is why the grid counts those rows as
  skipped rather than offering a refill it could not perform, and why the Partial column on
  [Coverage](/docs/trader/gui/data-manager/coverage) exists. [Data providers](/docs/trader/data-providers)
  covers the sources that do serve them.
</Callout>

## DataSets and the universe [#datasets-and-the-universe]

The Symbols tab defines a universe rather than fetching one. `crates/vike-data/src/datasets.rs`'s
header describes a DataSet as symbols plus a default provider, interval and benchmark, persisted
to `storage/datasets.json` and seeded with Crypto Majors and FX Majors on first run, so the Data
Manager can edit or test a whole set at once. Their names are what the Stored sidebar lists under
Watchlists — a label only today, since the grid receives names and not membership. Backfill itself
is driven from the grid's selection: "select all (filtered)" over a search is how a universe
becomes a job list.


# The catalog (/docs/trader/gui/data-manager/catalog)



The Stored tab's grid is `crates/vike-data-manager/src/view.rs`, and its header states the shape:
a dense, sortable, venue-grouped grid over the tree `crates/vike-data-manager/src/model.rs`'s
`build_tree` produces, searchable by venue or symbol, with a click-to-select row. This page is
what you see and what each control does; [Coverage](/docs/trader/gui/data-manager/coverage) takes the
Coverage and Partial columns on their own, because they carry the most information.

## Rows [#rows]

The grid is a flat table, not a tree. The header records the density rewrite that replaced a
per-symbol collapsing tree — "chunky, awkward at hundreds/thousands of symbols" — with one thin
rollup header row per venue (about 22 px) followed by one row of about 26 px per (symbol, series)
pair. The venue header carries the venue name and its rollup, in the shape `venue_rollup_label`'s
doc gives: `430 series · 2.1B rows · 18.4 GB`.

Each series row is one `kind`, or `kind/interval` for a bar series (`kind_label`), under its
symbol. What counts as a symbol is decided in the model: `SymbolNode`'s doc says the label is the
symbol for a per-symbol series and the group name for a grouped one, and the node is keyed on the
pair (label, grouped) because a grouped series and a per-symbol series can share a name while being
genuinely different instruments — different directories, different manifests, and a family
mid-migration with history in both. Keying on the bare symbol would have collapsed every grouped
series in a venue into one blank node. The tree is sorted deterministically, so the initial render
is stable across refreshes.

## Columns [#columns]

`header_row_cells` renders six sortable headers: **Symbol**, **Kind**, **Coverage**, **Rows**,
**Size**, **Updated**. Clicking a header sorts ascending; clicking the active header flips the
direction (`header_cell`). Sorting is per venue group — each group is ordered independently under
its own header. `SortColumn`'s default is Symbol ascending, chosen so that the first render matches
`build_tree`'s own order, and `cmp_flat_row` breaks ties by symbol, then kind and interval, so rows
with equal keys still land in a deterministic order. The plain picker keeps its sort state in egui
temp memory keyed off the widget id, because `stored_catalog_ui`'s signature is a two-mount
contract that cannot grow a parameter; the rich grid keeps it in `GridState` instead.

The Coverage cell is a thin span bar; hovering it shows `coverage_label`'s text — for example
`1234 rows, 2024-01-01 → 2024-03-01`, or `no data` for an empty series rather than an epoch-derived
nonsense range — rendered identically in both mounts. The rich grid adds a seventh, unsortable
**Partial** column after Coverage: a glyph rather than text so it stays narrow, with the count and
the missing kinds in its tooltip. `header_row_cells`'s doc explains why it has no sort — it is an
instrument-level flag, so every row of one instrument carries the same value and sorting would
only cluster instruments, which the grouping already does.

## Search [#search]

The search box filters by venue or symbol only. `matches_query` is a case-insensitive substring
match against those two fields; kind and interval are deliberately not searched, and an empty
query matches everything.

## Selection and the bulk bar [#selection-and-the-bulk-bar]

Two entry points render the same rows. `stored_catalog_ui` is the plain picker: a search box, the
sorted grid, and `Some(StoredSelection)` on the frame a row is clicked — venue, symbol, kind and
interval, which `StoredSelection`'s doc calls enough for a caller to load it, whether that means
opening a chart or feeding a slice picker. The Studio uses this one.

`stored_catalog_grid` is the app-only rich grid. Its doc lists what it adds: a leading checkbox
column that toggles `state.selected`, a header "select all (filtered)" checkbox, and a bulk-action
bar shown once anything is selected. The selection is a `BTreeSet<SeriesKey>` — the same four
fields as a `StoredSelection`, kept as a distinct type because a selection set's element and a
one-shot click result are different roles. `bulk_action_bar` shows an "N selected" count and three
buttons: **Backfill**, **Update**, **Delete**. `BulkAction`'s doc is explicit that the grid only
reports which button was clicked; the app owns what each does. Backfill and Update go to
[Backfill from the GUI](/docs/trader/gui/data-manager/backfill). Delete is confirm-gated in the app,
driven by either a single row open or the bulk action, and the bar accepts a `delete_disabled`
reason that grays the button with hover text — passed when the grid is showing a remote store,
since delete is a local-store operation.

<Callout type="warn" title="Delete removes data on disk">
  The app's delete path is the only destructive action on the Stored tab; the Symbols tab carries its
  own Delete, which removes a DataSet from `storage/datasets.json` (`Store::delete`) and touches no
  series. The Stored delete is confirm-gated, and the bulk variant snapshots the selection at the
  moment Delete was clicked, so a selection change while the modal is open cannot silently widen or
  narrow what gets deleted
  (`ToolView::stored_confirm_bulk_delete`).
</Callout>

## The views sidebar [#the-views-sidebar]

Beside the rich grid, `views_sidebar` is a thin selector over `ViewFilter`: **All**, one entry per
venue with its series count, the smart views **Has gaps** and **Stale**, and a **Watchlists** group
built from names the app passes in — which, per `stored_tool_content`'s doc, are the DataSet names
from the Symbols tab. Clicking an entry sets the active view; the grid re-filters on the next
frame through `filter_tree`. `ViewFilter`'s doc is candid about two placeholders: `Watchlist` and
`AssetClass` are carried in the type but the sidebar only receives watchlist *names*, not their
symbol membership, and the display tree has no asset-class tag, so both currently behave like
All. Has gaps and Stale are real, and are described on [Coverage](/docs/trader/gui/data-manager/coverage).

## What is tested [#what-is-tested]

The header states the discipline: everything above the actual paint calls — formatters, the stale
and gap predicates, flatten and sort, the coverage label — is pure and unit-tested; the two egui
render functions, it says, are not. That second half has been overtaken by the tests: `view.rs`'s
own test module renders `stored_catalog_grid` in real headless egui frames and reads the text it
paints back out (the Partial column's tests), and drives a real pointer press-and-release over
`bulk_action_bar`'s button rects to prove a click resolves to a `BulkAction`. `stored_catalog_ui`,
the plain picker, is the one with no render test. `model.rs` pins its own grouping, including a
grouped series showing under its group name rather than a blank node.


# Coverage (/docs/trader/gui/data-manager/coverage)



One cell answers three questions — how much of the store's timeline a series spans, whether it
has stopped, and whether it has holes — and a fourth, whether an *instrument* has days where one
kind is present and another is not, cannot be answered per series and gets its own column. The
authorities are `crates/vike-data-manager/src/view.rs` for the rendering and
`crates/vike-data-manager/src/model.rs` for the rollups the scale is built from.

## The span bar [#the-span-bar]

`paint_coverage_bar` paints a background track and a filled segment spanning the series'
`[first_ts, last_ts]`, mapped over the tree-wide window `[global_first, global_last]`. That window
is `global_span`: the earliest first and latest last across every venue with at least one series,
folded from the `RollUp` each node carries. The header gives the reason for a shared scale: bars
are painted over the tree-wide window "so bars are comparable across every row". A zero-row series
paints an empty track, and when nothing has data the window is inert and every bar is empty.

## Stale [#stale]

A series reads as stale when its `last_ts` lags more than 35 % of the tree-wide span behind the
global maximum, and its bar takes the warning colour. `is_stale`'s doc calls the fraction arbitrary
but conservative: recent data is typically within a few percent of the newest, and anything more
than a third of the whole window behind is very likely an abandoned or broken feed rather than
yesterday's close. It is a fraction of the span you hold, not a number of days.

## Gap cut-outs [#gap-cut-outs]

The rich grid takes a `GapMap`: per-series missing-day ranges keyed by the same `SeriesKey` the
selection uses. `paint_coverage_bar` overpaints each range as a dark cut-out inside the filled
segment, so a hole reads as missing against the span. Fetching the map is the caller's job — the
header is explicit that this crate never calls `series_gaps` itself — and `has_gaps`'s doc states
the conservative default: a series absent from the map, never fetched or failed, is treated as
gap-free, so the bar never flags a series it has no data for.

What a gap *is* comes from `crates/vike-data/src/datafusion_hist.rs`'s `series_gaps`: the ranges
missing within a series' recorded span, derived purely from the manifest's `date=` file index with
no Parquet scan, as cheap as a coverage read. Contiguous coverage, fewer than two distinct days, or
no data at all return an empty list; it never errors on "no data". The finder underneath is
`crates/vike-data/src/coverage.rs`'s `find_gaps`, whose doc example is the whole rule: present days
`[1, 2, 5, 6]` give one gap, `(3, 4)`.

<Callout type="warn" title="A gap is a missing day, not a missing row">
  The index knows which days exist and nothing finer. `coverage.rs`'s header draws the line: a day
  that is present but was recorded through a feed outage is a row-level trust question, answered by
  the `quality` module over scanned rows, not by this fold. A day the recorder half-covered shows as
  present here.
</Callout>

The app fetches the map alongside the tree: `crates/vike-app-core/src/stored_load.rs`'s
`load_stored_tree` probes `series_gaps` once per listed series — manifest-only locally, one small
RPC per series on a remote store — and a failed probe skips that one entry rather than failing the
refresh, which runs on the tab's first render and on Refresh, never per frame.

## Partial days [#partial-days]

`PartialDayMap` is keyed one level above the gap map, by `vike_data::InstrumentKey` — venue, label
and the grouped flag. Its doc explains why it is a second map rather than more gap entries: the two
answer different questions and neither derives from the other. A gap says *this series is missing
days 3–4*, a hole in one kind's own timeline. A partial day says *on day 11 the instrument has
trades but no book* — invisible per series, because each series is perfectly contiguous on its
own. The doc's example is the case that motivated the column: a Polymarket venue backfill restores
the trade tape and nothing else, since no venue-direct source serves `book`, so the trade series
closes its gap, the book series never had one, and only the join shows that a market-making
backtest over that window would run on no book at all.

The join is `coverage.rs`'s `InstrumentCoverage::partial_days`, and two of its rules shape the
column:

* **Only tick kinds are lined up.** `TICK_KINDS` is `trade`, `quote`, `book`, `depth`. Bars are
  excluded on purpose: they derive from trades, so a missing bar day beside a present trade day is
  a resample not yet run, not a hole in the tape. `depth` is included because that is where some
  feeds' L2 lands — omitting it once made the report claim an instrument had no L2 while 34 rows
  of it sat on disk.
* **Days are held against the instrument's own recorded kinds.** An instrument with no book series
  at all is not partial on every day it will ever have — the doc calls that "a permanent ⚠ carrying
  no day-to-day information, which is precisely how an operator learns to ignore a warning
  column"; the absence is already visible as a missing `book` row. With fewer than two recorded
  kinds nothing is partial.

The report is a manifest fold in the same cost class as the inventory — one manifest read per
series, no Parquet scan — so the Data Manager runs it on open. The column shows a ⚠ glyph and puts
the detail in the tooltip, in `partial_days_label`'s shape: `3 partial days (book, quote)`. It is
an instrument-level flag, so every row of one instrument carries the same value.

<Callout title="Over the wire, the column has three states">
  `crates/vike-app-core/src/stored_mode.rs` decides them. Local: rendered from the local fold.
  Remote, verb served: rendered from the wire answer. Remote, verb not served: a note in its place —
  "Partial column unavailable: the connected datahub did not answer the cross-kind coverage verb (an
  older server, or a read failure — see the log)". The verb is capability-negotiated rather than
  version-gated, so a refusal means the peer predates it, and an empty column is never substituted,
  because empty would claim "nothing is partial" — a different and possibly false fact.
</Callout>

## The smart views [#the-smart-views]

`filter_tree` applies the sidebar's choice. **Has gaps** keeps only series with a non-empty gap
list; **Stale** keeps only series whose coverage lags the tree-wide span, reusing `is_stale`; a
venue entry keeps only that venue. Both smart views drop symbols left with nothing and venues that
empty out, and — the detail `filter_stale_venue`'s doc insists on — rebuild the rollups over the
surviving rows, so the filtered tree's header summaries and span bars stay internally consistent
rather than describing rows you can no longer see.


# Data Manager (/docs/trader/gui/data-manager)



Data Manager is the desktop app's window onto data: which symbols you care about, which live
feeds are cached, where history comes from, and — on its Stored tab — what the
[history store](/docs/trader/concepts/hist-store) actually holds on disk. The Stored tab is the part
with a crate of its own, `vike-data-manager`, and that crate is the authority for this section:
`crates/vike-data-manager/src/lib.rs`'s header describes it as the cached-series catalog,
extracted from the app so that the Studio can mount the identical view and so that it runs in
CI at all — it uses egui and no wgpu, the same arrangement that lets the chart and Studio crates
be tested on GPU-less runners.

## The window [#the-window]

The window body is `crates/vike-app-core/src/tool_views/data.rs`'s `data_tool_content`: the
Symbols (DataSet) editor, the Cached-Series catalog of live feeds, the provider sub-tabs, and the
Stored sub-tab, which hands off to `stored_tool_content`. Its `TABS` array names seven sub-tabs
in this order — **Symbols**, **Cached Series**, **Historical Providers**, **Event Providers**,
**Streaming Providers**, **Stored**, and the per-venue arming tab **Venues**. The order is
load-bearing: `ToolView::data_subtab` is a bare index that two constants name by number —
`crates/vike-app-core/src/startup.rs`'s `DATA_SUBTAB_STORED` for Stored and
`crates/vike-app-core/src/tool_views/data.rs`'s `DATA_SUBTAB_VENUES` for Venues — so a new tab is
appended and never inserted; `data_tool_content` `debug_assert`s that `DATA_SUBTAB_STORED` still
points at "Stored", so a reordering trips a test rather than silently selecting the wrong pane.
Nothing persists the index: `workspace::persist`'s `capture` saves chart windows only, and tool
windows are deliberately skipped as launcher-recreatable runtime state. The Venues tab is the last
one, and `data_tab_reads_arming` is how the shell knows whether this frame needs the
credential-store read and settings load that tab alone requires — see
[Arm one venue](/docs/trader/guides/arm-a-venue) for what the arming rows mean.

**Symbols** edits DataSets: `crates/vike-data/src/datasets.rs`'s header defines a DataSet as a
named symbol collection bundling symbols with a default provider, interval and benchmark, so the
Data Manager can edit or test a whole universe at once. They persist to `storage/datasets.json`
and are seeded with Crypto Majors and FX Majors on first run. The symbols box takes free text:
`parse_symbols` splits on commas, semicolons, whitespace and newlines, upper-cases, de-duplicates
and keeps order. The "Ask the AI" box is `suggest_symbols` — its doc calls it a deterministic local
suggester that parses a count and an asset class out of the prompt and answers from a built-in
universe, an honest stand-in rather than a model call.

## The Stored tab [#the-stored-tab]

Two modules split the work. `crates/vike-data-manager/src/model.rs` is pure: it groups the flat
inventory a `HistStore` reports — `DataFusionHist::inventory` is `list_series` plus one
`series_coverage` per series, computed from the manifest file-index with no DataFusion scan,
`bytes` being the summed on-disk size of the part files — into a venue → symbol → (kind, interval)
tree with per-node rollups. Nothing in it does I/O; the caller fetches the inventory off-thread
and hands it over. `crates/vike-data-manager/src/view.rs` renders that
tree as the grid described on [The catalog](/docs/trader/gui/data-manager/catalog), with the span
bars, gap cut-outs and partial-day flags described on [Coverage](/docs/trader/gui/data-manager/coverage).

The view is deliberately not coupled to the app's tool-view state or live feeds. It takes a slice
of venue nodes and a query string and returns a plain `StoredSelection` — venue, symbol, kind,
interval — and the caller decides what a click means. That is what lets it be mounted twice:

* **The app's Stored tab** (`crates/vike-app-core/src/tool_views/stored.rs`'s
  `stored_tool_content`) mounts the rich `stored_catalog_grid` with its views sidebar, and wraps
  it in the controls the shared crate excludes: a Refresh button, a rows-and-bytes totals summary,
  and a confirm-gated Delete. A click opens a chart. The store I/O — the background load, the
  deletes, the chart open — happens in the app, never in the view.
* **The Studio's Data pane** (`crates/vike-studio/src/data_browser.rs`'s `DataBrowserPane`)
  mounts the plain `stored_catalog_ui` as a picker: clicking a bar-series row selects it as the
  run slice, and a tick-series row, which carries no interval, selects nothing. See
  [Data and slices](/docs/trader/gui/studio/data-and-slices).

Loading is never per-frame. `crates/vike-desktop/src/app_methods.rs`'s `refresh_stored` runs on the
tab's first render, on every Refresh click and after a delete; a failed open or inventory scan
degrades to an empty tree rather than a "Loading…" that never ends. Which store it reads — the
local one, or a remote data service — is decided by the same resolved address that routes a
backfill, which is the subject of [Backfill from the GUI](/docs/trader/gui/data-manager/backfill).

<Callout title="The Polymarket proxy box lives here">
  The Stored tab also carries `polymarket_proxy_ui`: a label, one line, and Save. Its doc states the
  two constraints the help line prints to the operator — SOCKS5 only, because
  `vike_bridge_core::ws_proxy::WsProxy::parse` refuses every other scheme, and `socks5h://` rather
  than `socks5://`, because plain `socks5` resolves DNS locally, which is exactly what a DNS-based
  geo-block catches. An emptied box stores the sentinel `none` (`PROXY_DIRECT`) rather than nothing,
  because the resolver's built-in default is proxy-on at a localhost tunnel, and writing nothing
  would leave a user who is not geo-blocked dialling a tunnel that does not exist. The value is shown
  plainly, embedded credentials included; the app performs the `POLY_SOCKS_PROXY` write, since only a
  binary may touch the credential store, and the change takes effect after a restart.
</Callout>

## Where the rest is [#where-the-rest-is]

* [The catalog](/docs/trader/gui/data-manager/catalog) — the grid: columns, sorting, search, selection
  and the bulk bar.
* [Coverage](/docs/trader/gui/data-manager/coverage) — the span bar, gap cut-outs, the stale tint,
  partial days and the smart views.
* [Backfill from the GUI](/docs/trader/gui/data-manager/backfill) — what the Backfill button plans,
  and where it runs.
* [The history store](/docs/trader/concepts/hist-store) and the [data kinds](/docs/trader/concepts/data)
  it lays out; [Data providers](/docs/trader/data-providers) for what fills them.


# The AI copilot (/docs/trader/gui/studio/ai-copilot)



The chat pane is a thin front over one library loop. `crates/vike-studio/src/chat.rs`'s `ChatPane`
owns the transcript, the provider selector and the last result; the work happens in `vike-ai`'s
`develop_strategy` loop (`crates/vike-ai/src/agent.rs`) — generate, compile-validate, backtest
out-of-sample, repair. The pane runs it the way the Run toolbar runs a backtest:
`ChatPane::send` spawns a worker thread and hands back a receiver, and `StudioState::poll` drains
it beside the run, sweep and walk-forward receivers.

## What Send needs [#what-send-needs]

Send is enabled only when four things hold at once: no chat round trip is already running, the
selected provider has a key, the input is non-empty, and a data slice is selected in the picker.
The last is not decoration — `StudioState::start_chat_send` says the model needs a
`(venue, symbol, interval)` to backtest against, the same slice the Run toolbar uses (see
[Data and slices](/docs/trader/gui/studio/data-and-slices)).

## Providers and keys [#providers-and-keys]

`crates/vike-ai/src/provider.rs`'s `Provider` offers two: Anthropic, the default, and Cerebras. Each
needs one key — `ANTHROPIC_API_KEY` or `CEREBRAS_API_KEY`, the names `chat.rs`'s `key_env_var` fixes
for both the lookup and the "no key" error, so the failure message names the variable to set.

`ChatApiKeys` says where they come from: `<project>/settings/secrets.env`, the same store every
venue credential lives in, resolved by the same walk. The pane itself opens no store and reads no
environment — the desktop app resolves the keys from the credential map it already loads and hands
them in as a parameter. And they are not venue credentials: absent, the pane offers no provider and Send stays disabled, and
nothing about trading changes.

<Callout type="warn" title="Keys are read once, at construction">
  The provider list is computed when the pane is built, not per frame. A key added to the store
  afterwards needs a restart — and a present-but-blank line (`ANTHROPIC_API_KEY=`) counts as
  present: the provider is offered and the request fails at the provider. The doc pins that
  deliberately rather than silently changing which providers the picker lists.
</Callout>

## What the model is told [#what-the-model-is-told]

Two things precede every message. The system prompt, `agent.rs`'s `STRATEGY_SYSTEM_PROMPT`, is the
Rhai contract (the [scripting](/docs/trader/scripting) tree's host surface): define `fn on_bar()`; read
`position()`, `price()` and the host-bound indicators (`NaN` until warmed up); order with
`market(dir, qty)` or `buy`/`sell`; declare sweepable knobs with `param("x", default)`; submit
through a `submit_strategy` tool carrying `code` and a one-line `explanation`. An unbound name
raises on the first call rather than returning a plausible number.

Then `chat.rs`'s `grounding_preamble`: the target slice — venue, symbol, interval — a note that the
strategy is backtested on that instrument's out-of-sample data, and one valid template as a worked
example. It deliberately does not enumerate the indicator registry. The doc records that the reason
inverted: the host used to bind only three indicators; now it binds most of the
[registry](/docs/trader/indicators), and what remains is a token budget — a fixed roster in every message
crowds out the context specific to this chat.

## The loop, and how it scores [#the-loop-and-how-it-scores]

`develop_strategy` scores only on the out-of-sample tail the model never saw (`holdout_frac`). A
rejected submission goes back with the compile error or the reason it did not trade, and the model
resubmits. `max_repairs` caps the number of submission attempts actually compiled and backtested —
not the number of tool calls — and once the cap is reached every further `submit_strategy` is
refused with a terminal message.

## Reviewing the result [#reviewing-the-result]

The transcript line is `summary_of`'s: accepted, with the OOS Sharpe and trade count; not accepted
after N attempts, with the problems; or an error. Below it the pane shows a result chip and a
**Review changes** section — `diff_rows`, a line-level diff of the current editor buffer against
the generated script. `apply_result`'s doc states the contract: the diff comes first so Apply is a
reviewed action rather than a blind clobber, and the write itself is still a whole-buffer replace
once you accept. Until you press **Apply to editor**, the [editor](/docs/trader/gui/studio/editor) is
untouched.

## Memory across sessions [#memory-across-sessions]

The loop has a ledger. `crates/vike-ai/src/ledger.rs` keeps two best-effort JSON files under the
store root — `ai_trials.json` and `ai_learnings.json` — colocated with `studio_strategies.json`
(see [Saved strategies and workspace](/docs/trader/gui/studio/saved-and-workspace)); the Studio resolves
the path with `LedgerPaths::under` because the library reads no environment. Per `agent.rs`'s
ledger section it buys two things: prompt grounding, so the loop stops rediscovering duds it
already rejected on this exact slice, and cross-session deflation — the deflated Sharpe ratio
(Bailey and López de Prado, 2014) counts every prior accepted trial on the same
`(venue, symbol, interval)`, so a single-candidate chat that is accepted on a slice already carrying
an accepted trial gets a real `deflated_sharpe` instead of the `0.0` a ledger-less call reports.
Fewer than two trials in total — the first chat on a fresh slice included — leaves deflation
undefined and the field at `0.0`. With a ledger present the model is also offered a
`record_learning` tool for notes future sessions read; without one it is not advertised.

The ledger is bounded — `MAX_TRIALS` 500 rows, oldest dropped first; equity curves kept on the
newest `MAX_CURVE_ROWS` 50 accepted rows; `MAX_LEARNINGS` 200 notes of at most `MAX_LEARNING_TEXT`
1024 bytes — and best-effort: a missing file is empty, a corrupt one is empty plus a warning, a
failed write is a warning. The loop never fails because the ledger is unavailable.

`ChatOutcome`'s error arm covers the no-key case and a worker that panicked; both land in the
transcript as a readable line rather than a silent stop. The **Connect to Claude** button at the
bottom of the pane uses none of these keys and has [its own page](/docs/trader/gui/studio/connect-claude).


# Connect your own Claude (/docs/trader/gui/studio/connect-claude)



The copilot pane ends with a **Connect to Claude** button, and it is a different thing from the
copilot above it. The [copilot](/docs/trader/gui/studio/ai-copilot) spends your API key on a hosted
model inside the app; this button wires a Claude you already run on your machine to Vike Trader's
MCP server, so that Claude can validate scripts, run backtests and — behind a preview gate — trade,
through tools. The server is `vike-cli mcp`; the button only writes the command that registers it.

## What the button generates [#what-the-button-generates]

`crates/vike-studio/src/connect.rs` is the whole helper: `server_entry` builds the executable plus
its argv tail — the `mcp` subcommand, then `--addr <host:port>` when the Studio has a datahub
address to give — and `claude_code_add_command` renders the copy-pasteable line for Claude Code:

```sh
claude mcp add <name> -- <path-to-vike-cli> mcp --addr 127.0.0.1:7878
```

The pane shows the result in a single-line field under the button. There is no Claude Desktop
config merge: the module header records that the retired predecessor crate's JSON helper was
dropped, because the Studio only ever surfaced the command. For Claude Desktop, the JSON block on
[Connect an agent](/docs/trader/guides/connect-an-agent) is the same server registered by hand.

## Why it carries a datahub address and not a store path [#why-it-carries-a-datahub-address-and-not-a-store-path]

`vike-cli mcp`'s run and list tools — `run_backtest`, `run_sweep`, `run_walk_forward`,
`list_strategies`, `list_series` — go over a running `vike-datahub` server, not an in-process store
(`crates/vike-cli/src/cmd/mcp.rs`'s header; that is what keeps the CLI free of the query engine).
So the generated command carries the data service's address and never a history-store path.
`ChatPane::connect_to_claude` reads it off the Studio's
[Remote backend](/docs/trader/gui/studio/remote-runs): with Remote selected, its address rides as
`--addr`, so the spawned server dials the same datahub the Studio offloads to; with Local selected
no `--addr` is written, and the server falls back to its own default, `127.0.0.1:7878` — the same
default `vike-cli`'s `backtest` verb uses.

The optional node keys, `VIKE_TRADEHUB_OBSERVE_KEY` and `VIKE_TRADEHUB_CONTROL_KEY`, are — per
`server_entry`'s doc — the operator's process-environment concern, never something the Studio
writes into a generated command. `--node`, the running trading node the trade tools reach, is not
generated either; add it by hand if you want the live tools, as the guide shows. The scoping flags
are in the same position: `--profile read-only` (or `--deny-tool NAME`) goes on the generated line
by hand, and it is what withholds the order-write tools from the Claude you are wiring up rather
than merely gating them.

<Callout type="warn" title="The executable path is a guess">
  `connect_to_claude`'s doc marks it a stub: the command names the `vike-cli` binary as the sibling
  of the running executable — right when the two ship side by side, but not a resolved install path.
  Check the path before pasting.
</Callout>

## Whether your build has it [#whether-your-build-has-it]

The generator is compiled only under `vike-studio`'s non-default `mcp` feature — a plain code gate
over the `connect` module, no extra dependency; the crate manifest and its `lib.rs` both say so.
Without the feature the button still exists and still responds: it writes a note into the same
field instead of a command — "MCP connect helper not compiled in — rebuild vike-studio with
`--features mcp` to generate the `claude mcp add` command that registers `vike-cli mcp` (needs a
running vike-datahub server)" — so the pane renders identically minus the copyable line.

<Callout type="warn" title="The default desktop build leaves the feature off">
  `crates/vike-desktop/Cargo.toml` takes `vike-studio` with no features. In the app as built by default,
  pressing the button produces the rebuild note. That costs you the convenience and nothing else: the
  command it would have written is the one line above with your own path and address filled in, and
  the [guide](/docs/trader/guides/connect-an-agent) has it ready to paste.
</Callout>

## What you get once it is registered [#what-you-get-once-it-is-registered]

`vike-cli mcp` is a local stdio MCP server — newline-delimited JSON-RPC, hand-rolled, no SDK. Its
tools split into read-only ones (compile-validate a script, discover its `param()` knobs, list the
templates and the host-bound indicators — all offline — plus the datahub-backed run and list tools
and a node snapshot) and order-writing ones behind a mandatory preview: a write executes only on a
call carrying **both** `confirm: true` **and** the `preview_token` an earlier preview of that same
command returned, and anything less previews again rather than failing — so the Claude you wired up
here cannot place an order in one call, and a confirming call with no token comes back
`will_execute: false` rather than as an error. If it should not be able to place one at all, add
`--profile read-only` to the generated line: the seven write tools then never appear in
`tools/list`, and are refused if called anyway. The tool-by-tool reference is
[Trader tools](/docs/ai/trader/tools);
the verb itself is [`vike-cli mcp`](/docs/trader/reference/cli/mcp); the service the run tools need is
[vike-datahub](/docs/trader/reference/binaries/vike-datahub).


# Data and slices (/docs/trader/gui/studio/data-and-slices)



A Studio run needs a slice: one venue, one or more symbols, a kind, a range. Two surfaces produce
one. The picker in the toolbar (`crates/vike-studio/src/picker.rs`'s `SlicePicker`) is the
authority on what is runnable; the Data tool (`crates/vike-studio/src/data_browser.rs`'s
`DataBrowserPane`) browses everything the store holds, and a click there feeds the picker.

## What the picker lists [#what-the-picker-lists]

`SlicePicker::refresh` enumerates the store through `HistStore::list_series` — the trait, so a
remote RPC store lists exactly like the local one — and the three filters it applies live once in
`crates/vike-studio-core/src/run.rs`. Two families are pickable, in this order:

* **Bars** — every `kind=bar` `(venue, symbol, interval)` (`bar_series`), picked as a
  `SliceKind::Bars` slice and replayed through the strategy engine; shown as
  `binance · BTCUSDT · 1m`.
* **Ticks** — every `(venue, symbol)` with a recorded series in `REPLAYABLE_TICK_KINDS`, which is
  `quote`, `trade` and `book` (`tick_series`), picked as a `SliceKind::Ticks` slice and replayed
  through [tick replay](/docs/trader/backtesting/tick-replay). One row per pair: the replay scans all
  three lanes for a symbol and merges them, so a symbol recorded as quotes *and* trades must not
  appear twice. Shown as `polymarket · TKN · ticks`.

The picker's header records that before the tick family existed, tick series were listed nowhere
and the Studio had no tick path at all.

A third family is **disclosed without being pickable**: instruments the store holds *only* as
`kind=depth` (`depth_only_series`). They render greyed under the pickable rows and as a
`⚠ depth-only` chip in the toolbar, with `DEPTH_NOT_REPLAYABLE` on hover — placed on the surface
because the person who needs it is staring at a picker that does not list an instrument they know
they recorded:

> Recorded, but not replayable. `kind=depth` is the CONFLATING L2 lane — periodic full snapshots
> with every intermediate book state discarded — and a backtest over teleporting depth reports
> fills it could never have got, so the tick replay reads the lossless quote/trade/book lanes only.
> Record one of those for this instrument to make it runnable.

`tick_series`'s doc gives the two independent reasons the arm is refused even though it would
compile: the replay has no depth lane to read, and folding depth into the book lane would hand a
strategy conflated snapshots under the name of a lossless book. The `depth` and `book` layouts in
the [store kinds](/docs/trader/concepts/data/) are the store's own statement of that difference.

## Range and extra symbols [#range-and-extra-symbols]

The picker loads the whole series range — `TsRange::all()`; the header names a date-range
sub-picker as a follow-up. A tick pick can carry extra symbols: the `+ symbols (a, b)` box beside
the combo folds a comma-separated list into one tick slice, deduplicated, so a cross-instrument
tick strategy gets all its series in a single run. The box is inert for a bar row, deliberately:
multi-symbol bar runs need aligned bar counts, which a free-text box cannot promise, and
`load_slice_bars` rejects a misaligned set with a readable error rather than letting the engine's
own assert panic a worker thread.

<Callout type="warn" title="A tick slice over a remote store runs remotely">
  With a `RemoteHistStore`, a tick slice on the Local backend is refused before dispatch: "tick
  slices over a remote store run remotely: switch Backend to Remote — a local run would have to pull
  the raw tick tape over the wire." `crates/vike-studio/src/remote.rs`'s `remote_store_tick_refusal`
  is the rule, and it never refuses a local store, a bar slice (its `load_bars` read is a small served
  verb, not the tape), or the Remote backend itself. See [Remote runs](/docs/trader/gui/studio/remote-runs).
</Callout>

## A failed scan is not an empty store [#a-failed-scan-is-not-an-empty-store]

The picker's header carries the hazard in its own words: an enumeration that failed and a store
that is genuinely empty are different facts, and this picker renders them differently. It used to
`unwrap_or_default()` both lists, so a store that could not be read drew the same empty combo — and
the same "no data in store" text — as one holding nothing, and the operator read "backfill some
history" off a surface whose real problem was that the datahub had gone away.

So the combo has four states, not two: `series scan failed` (plus a `⚠ scan failed` chip whose
hover carries `SERIES_SCAN_ADVICE` — fix the store, and for a remote datahub, is the server up? —
then ⟳ Refresh), `no data in store` when nothing at all is recorded, `nothing replayable` when the
store holds only depth, and `select data…`. The empty results panel asks the same question in the
same order.

Refresh is a one-shot walk, on open and on ⟳ Refresh, never per frame. One thing it cannot do: the
store root is resolved once at startup, so changing the environment variable and clicking Refresh
does nothing — the Data pane's comment says so where the old hint used to suggest it.

## The Data tool [#the-data-tool]

The Data tab renders the same venue → symbol → series catalog the Data Manager's Stored tab
renders — `vike_data_manager::stored_catalog_ui`, the de-duplicated extraction — so what you see
here is the [catalog](/docs/trader/gui/data-manager/catalog): Symbol | Kind | Coverage | Rows | Size |
Updated, one rollup header per venue, sortable columns. `DataBrowserPane::refresh` walks the *full*
inventory, every kind and not just bars, through `HistStore::inventory`, a manifest-only read with
no data scan that the remote store serves over RPC. The grid's natural width is about 690 px
against a 340 px panel, so it scrolls horizontally rather than squeezing its fixed cells into a
broken clip.

Click a bar-series row and the shell selects it as the run slice through
`SlicePicker::select_by_key`. A tick-series row, which carries no interval, yields nothing here —
there is no `DataSlice` for it through this route yet; pick ticks from the combo. An inventory scan
that fails renders "Inventory scan failed" with the reason, never the "no data yet" hint; an empty
store says to backfill history — the Data Manager's [Backfill](/docs/trader/gui/data-manager/backfill),
or `vike-backfill` — then Refresh.


# The editor (/docs/trader/gui/studio/editor)



`crates/vike-studio/src/editor.rs`'s `EditorPane` is one widget — `egui_code_editor`'s
`CodeEditor` bound to the strategy source string — and the pieces around it are what make it an
editor rather than a text box: a compile status, an error banner, a save baseline, and the
workspace that restores it.

## What you see [#what-you-see]

The editor renders in the Gruvbox colour theme with line numbers at a 13-pixel font, and it fills
whatever height the panel leaves. `rows_for_height` is the sizing rule and its doc carries the
measurement: the widget's real row pitch is about `font_size × 1.16`, measured from a screenshot
capture — 45 rows over roughly 680 logical pixels at font 13 — after a first-guess factor of 1.5
left a dead gap of about a fifth of the panel. The result is clamped to 8..=400 rows so a
degenerate height never yields a zero-row editor.

Highlighting is Rust's. `crates/vike-studio/src/syntax.rs`'s header states the reason: Rhai's
surface — `fn`, `let`, `const`, `if`/`else`, `while`, `return`, `//` comments, strings, numbers —
is a subset of Rust's, so the built-in Rust syntax highlights it well; a bespoke Rhai syntax that
colours the host verbs specially is a documented follow-up.

A fresh Studio opens on `DEFAULT_SCRIPT`, an SMA crossover: `FAST = 5`, `SLOW = 20`, `QTY = 1.0`,
long above and short below, reaching the target through `market(...)` by the delta from
`position()`. On later launches the workspace restores the last buffer instead — unless that buffer
was empty, in which case the starter script is kept rather than the editor blanked
([saved and workspace](/docs/trader/gui/studio/saved-and-workspace)).

## The compile status [#the-compile-status]

`compile_status` compiles the buffer as a `RhaiStrategy` — the same compile path `run_slice` uses
— and collapses the outcome to `Ok`/`Err(message)`. Rhai has no notion of warnings, so this is a
strict green/red split. The shell recompiles in `StudioState::poll` only when the source has
drifted since the last compile: a single compile costs milliseconds, but compiling every frame
regardless of keystrokes would still be wasteful. The restored script is compiled eagerly at
construction, so the first frame never shows a stale status.

The verdict has two renderings. The chip beside the "Editor" title reads `● compiles` in green, or
`● error · line N` in red — `● error` when no line is recoverable — with the full message on hover
either way. Under the header — above the editor, not below it, so the editor's row estimate can
never push it off the panel bottom — a failing compile also gets an inline banner:
`✗ line N · message`, or `✗ message` when no line is recoverable.

<Callout title="Where the line number comes from">
  `error_line` parses it out of the message text. `vike_script::ScriptError` is a stringified `rhai`
  error with no structured position to read, and the parser's doc records the empirical fact it
  relies on: verified against `rhai` 1.25.1, both parse errors and top-level runtime errors end with
  a `(line N, position M)` suffix. It never assumes the suffix is present — a message without one, or
  a malformed one, yields `None` and the banner shows the message alone. `format_compile_error` drops
  the redundant suffix from the body once the prefix already carries the line.
</Callout>

## Saving, and the amber dot [#saving-and-the-amber-dot]

`StudioState::saved_source` is the buffer as of the last Save, Load or template load; while
`editor.source` differs from it, an amber `● unsaved` chip sits beside the compile chip with the
hover "Unsaved changes — Ctrl+S saves to the Saved list". `Ctrl+S` snapshots the buffer under the
name in the Saved pane's box. With an empty box it re-saves under the *last* saved name, falling
back to `untitled` only when the session has never saved — the shell's comment records the
misfiling this replaced: save `momo-1`, keep editing, `Ctrl+S` again, and the edits landed under
`untitled` while `momo-1` kept the stale code. Loading a saved entry or a template re-baselines the
dot.

The buffer is also part of the workspace snapshot, written to disk once per drift rather than once
per frame, so the editor reopens where you left it.

## Collapsing [#collapsing]

The ◀ button collapses the editor to a 28-pixel rail with a ▶ to expand it. The collapsed rail is a
different panel from the expanded editor on purpose: egui persists panel width by id, and sharing
one would store the 28-pixel width and reopen the editor as a minimum-width sliver instead of at
the width you dragged.

## What the buffer becomes [#what-the-buffer-becomes]

When the Strategy tool says "Rhai script", the toolbar chip reads `🧩 rhai` and every Run, Sweep
and Walk-Forward compiles this buffer; a sweep compiles it once per grid point with that point's
`param()` overrides bound (`crates/vike-studio-core/src/run.rs`'s `build_strategy_with`). The
language, the order verbs a script may call, and the resource ceilings the engine enforces are the
[scripting](/docs/trader/scripting) tree's: [writing a strategy](/docs/trader/scripting/writing-a-strategy),
[the order vocabulary](/docs/trader/scripting/order-vocabulary), [limits](/docs/trader/scripting/limits).


# Studio (/docs/trader/gui/studio)



Studio is one tool window of the desktop app, opened from the launcher row's studio icon
(`crates/vike-desktop/src/main.rs`'s `LAUNCHERS`), titled "Studio" and painted in the violet that
`crates/vike-app-core/src/workspace/state.rs`'s `WinKind::Studio` assigns. What it holds is stated
by `crates/vike-studio/src/lib.rs`'s header: a Rhai editor, a store-backed slice picker, a
worker-thread Run over the history store, and tabbed backtest results — egui without a window
system of its own, so the crate is CI-testable and `vike-desktop` mounts it.

## The shell [#the-shell]

`crates/vike-studio/src/studio.rs`'s `StudioState` is the shell: a Run toolbar across the top, the
editor on the left, a tools panel on the right, the results in the centre.

The toolbar carries, left to right, the data-slice picker, a chip naming which strategy ▶ Run will
execute (`🧩 rhai` for the editor buffer, or the native registry name — clicking it jumps to the
Strategy tool), ▶ Run, and ⟳ Refresh, which re-scans the store. Everything transient — the spinner,
✖ Cancel, and the "running backtest…", "running sweep…", "running walk-forward…", "running study…"
or "comparing saved…" label — is right-aligned so the left half never jumps mid-run. A second line
selects the backend: Local, in-process over the store, or Remote, which offloads a Run, Sweep or
Walk-Forward to a `vike-datahub` server ([Remote runs](/docs/trader/gui/studio/remote-runs)).

The right-hand side is two sibling panels in the activity-bar shape of a code editor: a 40 px icon
rail and a 340 px tools panel. Seven tools share the one tabbed panel — `RightTab`'s doc records
why: simultaneous side panels crushed the editor and results to a sliver. In rail order: Sweep &
Validate, Strategy, Data, Indicators, Saved, Research, AI Chat. Clicking the active tool's icon
collapses the panel; clicking any other selects it and expands. Each page in this tree covers one:
[the editor](/docs/trader/gui/studio/editor), [data and slices](/docs/trader/gui/studio/data-and-slices),
[the indicators pane](/docs/trader/gui/studio/indicators-pane),
[the templates gallery](/docs/trader/gui/studio/templates-gallery),
[the research pane](/docs/trader/gui/studio/research-pane), [results](/docs/trader/gui/studio/results),
[saved strategies and the workspace](/docs/trader/gui/studio/saved-and-workspace), and
[the AI copilot](/docs/trader/gui/studio/ai-copilot).

Three shortcuts are checked once per frame, `Ctrl` on Windows and Linux and `Cmd` on macOS:
`Ctrl+Enter` runs the backtest, `Ctrl+S` saves the editor buffer to the Saved list, `Ctrl+/`
cycles the tool tab and expands the panel, so the shortcut always shows its effect.

## What Run executes [#what-run-executes]

`StudioState::current_spec` is the one place the choice becomes a runnable `StrategySpec`. The
Strategy tool's "Rhai script" runs the editor buffer; "Native (Rust)" runs a compiled strategy
from the backtest [harness registry](/docs/trader/backtesting/harness-registry), with its parameters
typed as free-form key/value rows. The rows are free-form on purpose —
`crates/vike-studio-core/src/spec.rs`'s header: the harness has no parameter spec to generate a
form from, so a typed form would be a second source of truth no strategy is obliged to honour.
`params_from_rows` types each cell (`3` an integer, `2.5` a float, `true` a bool, bare text a
string), and the pane echoes the resolved table so the fallback is visible rather than surprising.

Sweep & Validate holds the parameter grid. "Seed from params" fills it from the script's `param()`
declarations — or, for a native strategy, from the numeric rows you typed, since no
`discover_params` twin exists for the registry. ▶ Run Sweep backtests every grid combination and
ranks by Sharpe; Walk-Forward is a four-split anchored out-of-sample validation
(`StudioState::start_walkforward` fixes `n_splits` at 4, and
`crates/vike-studio-core/src/run.rs`'s `run_walkforward_slice_with_params` runs
`WalkMode::Anchored`). The templates dropdown and gallery live in the same pane.

## Nothing runs on the update loop [#nothing-runs-on-the-update-loop]

Run, Sweep, Walk-Forward, Compare all and a study each spawn a worker thread and hand back a
receiver; `StudioState::poll`, called once per frame, folds whatever arrived. A worker that panics
or drops its sender is a terminal failure surfaced as "run failed (worker terminated)" rather than
a spinner that never stops.

<Callout type="warn" title="Cancel abandons; it does not kill">
  `StudioState::cancel` drops the receivers and resets the running state so the UI is usable the
  next frame, but there is no cooperative-cancellation hook into the engine: the spawned thread keeps
  executing the backtest to completion in the background, and its result is discarded on arrival.
  The CPU time is not reclaimed. A true kill would need a cancellation token threaded through the
  engine and the script strategy, which that method's doc names as out of scope.
</Callout>

## Two result surfaces [#two-result-surfaces]

The centre panel shows one of two producers, and `CenterView`'s doc is explicit that the split is
deliberate: a backtest's numbers come from the event-driven simulator and a study's do not, so
`results_ui` renders a `BacktestResult` and `study_result_ui` renders a `StudyRun`, each naming its
own producer. Every dispatch claims the panel for its own surface, so you see the result of the
thing you last asked for rather than the winner of a precedence rule. Before any result exists the
panel reads "1 Pick a data slice · 2 Write or load a strategy · 3 Run" and offers ▶ Run backtest
and Load a template directly — and it asks the picker whether its scan *failed* before it asks
whether the list is *empty*, because an unreadable store leaves the list empty too, and the old
emptiness test sent an operator whose datahub had gone away off to backfill history.

## The store, and where it comes from [#the-store-and-where-it-comes-from]

The Studio holds its history store as a trait handle — `StudioState::store`'s doc: a local
`DataFusionHist` or an RPC-backed `RemoteHistStore`, every pane reading through `HistStore` verbs
only. `vike-desktop` opens it lazily, once, the first time the window is shown; success and failure
both stick, so a broken store never retries the open on every frame. With a resolved datahub
address the app dials a remote store, probes it with one `list_series`, and — since the same server
serves the store verbs and the run verbs — seeds the backend to Remote and arms the tick rule.
Without one there is no local arm to fall back to — the binary links no store engine — so the open
is an error naming both fixes — set `config.datahub_addr`, or connect a
backend that advertises its datahub. `crates/vike-desktop/src/main.rs`'s `open_studio_store` is the
authority; see [the history store](/docs/trader/concepts/hist-store) and
[observe mode](/docs/trader/gui/observe-mode).

The library reads no credential store, and the constructor takes its configuration as parameters —
`StudioState::new`'s doc: the per-store state directory, the AI-provider keys, and the two
headless-capture hooks are values the binary resolves and passes in. What the crate still reads
from the environment is where the workspace snapshot lives, and the constructor reaches it through
`load_workspace`: `crates/vike-studio/src/workspace.rs`'s `state_root_override` reads
`$VIKE_STATE_ROOT`, and its `project_state_dir` walks up from the working directory —
[saved strategies and the workspace](/docs/trader/gui/studio/saved-and-workspace) covers where the file
lands.


# The indicators pane (/docs/trader/gui/studio/indicators-pane)



`crates/vike-studio/src/indicators.rs` is the Studio's window onto the indicator registry. Its
header describes a pane that browses the single-series indicators, configures a selection's
parameters, and previews the computed series over the currently loaded bars; the browse and
compute helpers are pure and unit-tested, and the egui render is thin over them. The registry
itself, every indicator with its parameters and defaults, is the [indicators](/docs/trader/indicators/)
tree.

## Browsing [#browsing]

The search box's hint reads "Search 171 indicators…" — the count the pane's header states for the
registry's single-series entries. `grouped_search` is the one list-building function: a
case-insensitive substring match over an indicator's short name and its pretty name (an empty
query matches everything), grouped by category in a fixed display order, skipping empty groups.
The order is `CATEGORY_ORDER`'s — Trend, Momentum, Volatility, Volume, Statistics, Patterns,
Price, Structure — with the labels `Category::label` in `crates/vike-indicators/src/registry.rs`
gives them (the first is the `Overlap` category). It is a fixed array rather than a map because
`Category` is a plain discriminant enum with no ordering of its own.

Each group renders as an accent-coloured heading over selectable rows showing the pretty name; the
selected entry's pretty name and `(short_name)` sit above its parameters. A selection is stored by
*name*, so it survives re-filtering the search box.

## Parameters [#parameters]

`IndicatorsPane::select` resets the parameters to the registry's defaults — `default_params`, in
the order the indicator's constructor takes them, and empty for parameterless indicators such as
`vwap` or `obv` — and clears any stale preview or error. Each parameter becomes a slider over the
registry's declared `min..=max` with its `step` and its name as the trailing label; the slider is
sized to the panel so a long parameter name cannot push the icon rail off-screen, which the pane's
comment records as exactly the over-wide row the old layout allowed.

## Compute and preview [#compute-and-preview]

The Compute button returns `true` to the shell for one frame, and the shell does the rest —
`IndicatorsPane::ui` never touches the store, which is what keeps the pane's logic testable.
`StudioState::compute_indicator_preview` loads the picked slice's bars synchronously; the compute
is linear in the bar count and cheap, so unlike Run it needs no worker thread. Three refusals
surface as the pane's own error line:

* no slice picked — "pick a data slice first";
* a tick slice — "indicators need a bar slice — pick one from the Data combo", because indicators
  are bar-series maths;
* a load failure, with the store's message.

`compute_indicator` coerces the raw slider values against the parameter specs, builds a fresh
instance, and batch-computes it over the bars with `vectorize` — one output vector per declared
output line, empty vectors for empty input. The explicit coercion is cheap and idempotent even
though every registry constructor coerces internally; the registry's own doc asks external callers
to do it anyway. `compute_indicator_matches_a_hand_computed_sma` pins the result against a
hand-computed mean.

The preview is a 160-pixel plot, one line per output series named from the indicator's output list
(falling back to the indicator's name), with NaN samples — the warm-up — filtered out of the points
rather than drawn. Until Compute is pressed the pane says "Press Compute to preview."

<Callout title="Batch here, streaming in a strategy">
  What the pane previews is the batch `vectorize` path; a script calling the same indicator from
  `on_bar` gets the streaming one, and whether the two agree is the [indicators](/docs/trader/indicators/)
  index's subject. An indicator you write yourself in Rhai — [writing an indicator](/docs/trader/scripting/writing-an-indicator)
  — is loaded from `user_data/indicators/` per [loading indicators](/docs/trader/scripting/loading-indicators);
  `crates/vike-model/src/state_path.rs`'s `PROJECT_USER_DATA_DIR` doc records that each such file
  compiles to a real registry `Indicator` and is callable from a strategy as `<name>()`.
</Callout>


# Remote runs (/docs/trader/gui/studio/remote-runs)



Every Run, Sweep and Walk-Forward in the Studio has a **Backend**: where it executes. The toggle sits
on the toolbar's second line. **Local**, the default, runs in-process over the Studio's own store —
`crates/vike-studio/src/remote.rs`'s `Backend` doc calls it byte-identical to the Studio before the
backend existed. **Remote** offloads the run over TCP to a
[vike-datahub](/docs/trader/reference/binaries/vike-datahub) server — the compute-to-data backtest
service, where the engine runs next to the data and only the answer crosses the wire — with an
address field beside it (`host:port`) that starts at `DEFAULT_REMOTE_ADDR`, `127.0.0.1:7878`: the
localhost port an SSH-tunnelled data service serves on, and `vike-cli`'s own default. The choice is a
runtime toggle held on the state struct, not persisted to disk.

## The contract: a drop-in for the local path [#the-contract-a-drop-in-for-the-local-path]

The module header states it. Each `spawn_*_remote` returns the exact same receiver type as its
`vike_studio_core::spawn_*` twin, so `StudioState::poll` folds a remote outcome with zero changes and
the [results pane](/docs/trader/gui/studio/results) renders it unchanged. The wire answer is mapped back
onto the same `BacktestResult`, `StudioSweep` and `WalkForwardReport` the local engine produces, and
every failure — a connect fault, a server-side error, a protocol desync — arrives as an
`Err(RunError)` on that receiver, never a panic.

The strategy and slice go out as DTOs, defined once, in the light `vike-datahub-client` crate (`wire_studio`), and the server — `vike-datahub`
behind its `serve-datafusion` feature — converts wire to engine and runs the same
`vike_studio_core::run::run_slice` the local path runs. A native strategy's parameters ride as TOML
text, the exact text the server parses back with `StrategySpec::native_from_toml_str`, so a local
and a remote native run resolve bit-identical params. Coming back, `to_backtest_result` fills the
rendered fields and leaves the rest at their default; each closed trade is reconstructed losslessly; a sweep's `dsr` or `pbo` the server
could not assess arrives as `NaN`, the sentinel the results pane already handles; the walk-forward
report is a full mirror.

<Callout title="Engine parameters are the defaults, on both backends">
  `run_slice_remote`'s doc: params go out as `None`, and the server resolves every engine field from
  `EngineParams::default()` — matching the local path, which uses the same default. The protocol
  carries an optional cost and cash override; the Studio does not expose one yet.
</Callout>

## Errors render like local ones [#errors-render-like-local-ones]

The server stringifies a run failure kind-first (`"{kind}: {message}"`), and `parse_wire_run_error`
recovers the prefix — `compile`, `data`, `strategy` — and rebuilds the matching `RunError`, so a
remote failure renders identically to the same failure run locally. A connect failure or a protocol-version mismatch becomes a
data error naming the address, shown in the Studio's existing error banner; the mismatch is legible
because `DatahubClient::connect` performs a `Hello`/`Welcome` handshake and, when the versions
disagree, fails naming both.

<Callout type="warn" title="A keyed data service refuses the Studio's dial">
  The Studio dials with `DatahubClient::connect`, the unauthenticated constructor — its doc names the
  Studio's `Backend::Remote` among the callers it keeps working untouched against a key-less server.
  Against a server that requires authentication it fails at the handshake with a message naming
  `VIKE_DATAHUB_OBSERVE_KEY` and `VIKE_DATAHUB_CONTROL_KEY`; the `Run*` verbs sit in the control
  scope, because they compile client-supplied Rhai on the server.
</Callout>

## The store and the backend are two different things [#the-store-and-the-backend-are-two-different-things]

The backend is where compute runs. The store is where the Studio reads history from, and it can be
remote on its own: `StudioState::store` is the trait handle, either a local store or an RPC-backed
`RemoteHistStore` whose reads go over the same protocol — read-only, one fresh connection per read.
The desktop app decides which in `open_studio_store`, on the resolved datahub address: the explicit
`config.datahub_addr` key (see [config.toml](/docs/trader/reference/settings/config)), else the address
the connected backend's `Welcome` advertises. With an address it opens a remote store; without one
there is no local store to open. The binary also sets
`store_is_remote` and seeds the backend after construction. There is no local
engine at all: the Studio is remote-only, and with no address its open fails naming both fixes —
set `config.datahub_addr`, or connect a backend whose daemon advertises a datahub.

<Callout type="warn" title="Connect first, then open the Studio">
  `open_studio_store`'s doc calls this the contract's sharp edge: the store is opened once and kept
  for the session. A Studio opened before any backend connects resolves from the explicit key alone
  and never picks up the advertisement. Every other datahub consumer re-resolves per read.
</Callout>

## The one refusal: tick slices over a remote store [#the-one-refusal-tick-slices-over-a-remote-store]

`remote_store_tick_refusal` is the split-plane rule: with a remote store, a tick slice runs only on
the Remote backend. A local tick replay would need the tick tape — `scan_book_updates`, `scan_depth`
— pulled over the wire, which is exactly what compute-to-data refuses; the RPC store keeps both verbs
as read-only errors. Instead of dispatching, the
Studio shows one line: switch Backend to Remote. The guard sits in front of Run, Sweep and
Walk-Forward alike, and never fires for a local store, a bar slice (its `load_bars` read is a served
verb — small, not the tape), or the Remote backend itself.

The same offload from a terminal is `vike-cli backtest`, `sweep` and `walkforward` —
[Running a backtest](/docs/trader/backtesting/running) covers the verb, and
[Run a sweep on the data service](/docs/trader/guides/sweep-on-the-service) walks one through.


# The research pane (/docs/trader/gui/studio/research-pane)



`crates/vike-studio/src/research.rs`'s header names the pane in one line: the studies a user has
written, the ONE button that runs one, and the runs that came out — the Studio's sibling of the
Sweep pane, dispatching through `crates/vike-studio-core/src/study_dispatch.rs` instead of the
backtest engine. It invents no second mechanism: the dispatch is a worker thread whose result
`StudioState::poll` folds, and the outcome lands in the same centre panel a backtest's does. What a
study *is* belongs to the [research](/docs/trader/research) tree ([studies](/docs/trader/research/studies),
[running a study](/docs/trader/research/running-a-study)); this page is the surface.

## One list for both tiers [#one-list-for-both-tiers]

`list_studies` returns the `rhai` tier and the `rust` tier as rows of one list, differing only in a
`StudyTier` tag, and the only `match` that decides how a study RUNS lives in `run_study_plan`. So
the pane has one list, one Run button and no second surface for either tier. The tier shows as a
**badge** because it is a fact a user acts on, and the hover says which: interpreted, compiled at
run time from the folder, so a shipped binary can run it; or compiled, resolved through a registry
generated at build time, so it runs only on a binary built from a checkout that held it
([Rhai studies](/docs/trader/research/rhai-studies), [Rust studies](/docs/trader/research/rust-studies)).

Scanning is lazy: the first frame the tool is opened reads both listings, a session that never
opens it reads no directory at all, and ⟳ Rescan re-reads `user_data/research/studies` and
`user_data/runs`. Everything a scan could not use renders as a red row rather than an absence —
`crates/vike-studio-core/src/listing.rs`'s rule that a run which vanishes from a list is worse than
one that shows as broken.

## Where it reads from [#where-it-reads-from]

The pane resolves no path. `StudyHost` — the studies root `<project>/user_data/research/studies`,
the runs root `<project>/user_data/runs`, a scratch directory, the producing binary's name and its
commit if it can name one — is set by the binary after construction, for the same reason the
store's remoteness and the backend are: a library resolves no project root.
`crates/vike-desktop/src/main.rs`'s `studio_study_host` derives it from the settings directory the app
already resolved, honouring `VIKE_USER_DATA_DIR` outright, and records `produced_by` as `vike-desktop`
with no commit, which its doc calls the honest answer for a binary that reaches build info only
through its boot crate.

No host is the ordinary state of a binary launched from outside any project, and it is disclosed:
the pane renders `NO_HOST` — "No project folder above this working directory, so there is nowhere
to read studies from and nowhere to put a run. Launch the app from inside a project, or set
VIKE\_SETTINGS\_DIR to name one." — and lists nothing and arms nothing. A project with no studies
reads `NO_STUDIES`, which names the two folders a study can live in.

## Recipe, window, learner [#recipe-window-learner]

A recipe is a `.toml` beside the study's entry file, one named configuration, and neither runner
reads it — the caller does. The **Recipe** picker's index 0 is `(no recipe)`, which runs the study
with no configuration and records that it had none; the rest are the folder's `.toml` files in name
order. Selecting a different study resets the picker, because recipe 2 of one study has nothing to
do with recipe 2 of another. The recipe is read when the plan is built, so a file that will not
parse is refused *before* dispatch, with the file named beside the picker that chose it.

**Window** is the picked data slice's range, or "the whole store (no data slice picked)".
`StudioState::study_window`'s doc is careful that this is not a gate: a study reads whatever series
it likes through its own context verbs, so the window is a fact the run records and the default its
read verbs take — requiring a slice would be an invented coupling, since a backtest replays that
exact series and a study does not.

<Callout type="warn" title="This host supplies no learner">
  The pane states its ceiling where a study would hit it: "This host supplies no learner: a study
  that must FIT refuses with NoLearner. Inference and importance still work." The Studio's ML surface
  is inference only — `crates/vike-studio-core/src/lib.rs`'s header: it fits nothing, because no
  trainer binary ships off Linux — and the plan is built with `learner: None`. A study that fits runs
  under [vike-study](/docs/trader/reference/binaries/vike-study); [training](/docs/trader/research/training)
  and [models](/docs/trader/research/models) cover what a learner is.
</Callout>

▶ Run study is enabled with a study selected and nothing running; it dispatches through
`spawn_study` and leaves a run behind in `user_data/runs`. When the run lands, only the runs list is
re-scanned — no study folder can have changed by running one.

## The runs list holds no numbers [#the-runs-list-holds-no-numbers]

The **Runs** section lists every run of every kind, newest first, each with a `kind` badge — the
manifest's `kind`, the one top-level field a reader may branch on. `kind_color` gives three answers
on purpose: a study run in the accent colour, a backtest run in the success colour, and a kind this
build does not recognise in the warning colour under its own name, because kinds grow in crates
that cannot see each other and "I do not know this one" is an answer a reader needs. Hover shows
who produced it, when it started, and "no report on disk" when the report is missing; a footer
names which runs tree the rows are about ([runs on disk](/docs/trader/backtesting/runs-on-disk)).

`RunRow` carries no metric at all, and a test holds it there over a manifest whose metrics are
populated. The pane's own blurb: "Numbers live in the run, never in this list — a study's Sharpe
and a backtest's are not the same measurement." `crates/vike-studio-core/src/study_run.rs` nests a
study's metrics under `detail.metrics` precisely so a listing that never asked which scorer produced
a number cannot render it in a shared column.

## The result surface [#the-result-surface]

`study_result_ui` is the centre panel for one study run, and it is deliberately not the backtest
[results](/docs/trader/gui/studio/results) pane: that renders an equity curve, a trade list and eleven
event-driven metrics, and a study produces none of them. It shows the run's facts — study, produced
by, started, finished, window, whether a learner was supplied, where it was saved — then a Metrics
table in which a non-finite value renders as IEEE-754's own token through `nonfinite_tag` rather
than as `0.00`, because a `NaN` Sharpe over a fold that never traded is an observation the manifest
keeps; then any artifacts by name and size; and finally `STUDY_METRICS_NOTE` verbatim, the sentence
the library writes into every study run's manifest so that a file read alone still carries the
distinction. A study that recorded nothing says so rather than rendering a gap.


# Results (/docs/trader/gui/studio/results)



`crates/vike-studio/src/results.rs`'s header describes the pane: tabbed rendering over a
`BacktestResult`, with the table-building helpers pure and tested and the tabs drawn as plot lines
and bars plus grids. It sits in the centre panel whenever the last thing asked for was a backtest —
a Run, a Sweep or a Walk-Forward ([the research pane](/docs/trader/gui/studio/research-pane) claims the
panel for a study instead). With a single run present it renders that; with only a sweep, it
renders the sweep's best entry, so Equity and Trades have data even when you never ran a single
backtest. The ★ on the ranked table marks that link.

## The five tabs [#the-five-tabs]

**Equity** plots the equity curve by bar index. **Trades** is a striped grid — `#`, side, entry,
exit, size, pnl, fees — with `long`/`short` coloured by direction and pnl by sign.

**Performance** is `perf_cells`: Total return, Final equity, Sharpe, Sortino, Max drawdown, CAGR,
Calmar, Win rate, Profit factor, SQN, Trades. Annualised figures use `PPY = 252` periods per year,
the convention the pane's comment shares with the tearsheet. Rows where the sign means something at
a glance — the returns and the Sharpe family — read green or red; drawdown and counts stay neutral,
because a drawdown is always a decline. The metric definitions are
[analytics](/docs/trader/analytics/metrics)'.

**Distribution** bins the per-bar returns (`metrics::returns` over the equity curve) into 21 bins
between the minimum and maximum.

<Callout type="warn" title="An empty distribution is a real case, and it once took the frame down">
  A curve shorter than two points yields no returns, and the fold that sizes the bins seeds with
  `(f64::MAX, f64::MIN)`, so every bar centre landed near `1.7e308` — infinite once taken as `f32`.
  That never reached the frame-sanity check: the plot library's own bounds check panicked first,
  inside the render, measured on egui\_plot 0.37 by removing the guard. A run that stops on its first
  bar, or a strategy that never trades, produces exactly that curve. The tab now paints the empty plot
  frame — axes and grid, no bars — and leaves the populated path unchanged; the kill proof lives
  beside the guard in the module's tests.
</Callout>

**Validation** is two grids, then whatever a sweep or walk-forward adds.

## What validation shows [#what-validation-shows]

The first grid, `validation_rows`, is what one run can say: the annualised Sharpe, then the inputs
to the probabilistic Sharpe ratio — observations, skew, kurtosis — and `Prob. Sharpe > 0 (PSR)` as
a percentage. The inputs come from the shared `overfit::sharpe_moments` derivation, which owns the
per-period-Sharpe and non-excess-kurtosis conventions; the pane's doc flags both as footguns and is
explicit that the *displayed* Sharpe is the annualised value, a different quantity that must never
be fed back into the overfitting statistics.

The second grid, `validation_verdict_rows`, needs more than one run:

* **Deflated Sharpe** — from a sweep's trial set, else `—`.
* **PBO** — the probability of backtest overfitting, computed by CSCV across the sweep's per-trial
  returns matrix; `NaN` renders `—` and `overfit_verdict` treats it as "not assessed", its own
  reason row rather than a vote toward low risk. `StudioSweep::pbo`'s doc names the `NaN` cases:
  fewer than two trials, a too-short slice, or non-finite returns.
* **Overfit risk** — `Low`, `Medium` or `High`, from `overfit_verdict`, which combines PBO, the
  deflated Sharpe and, when present, walk-forward consistency into a label with the reasons behind
  it; each reason becomes a `Note` row.
* **Walk-forward consistency** — when a walk-forward report exists.

Under the grids: the ranked **Parameter sweep** table (each grid point's overrides as `k=v`, its
annualised Sharpe coloured by sign, total return, final equity), and the stitched **Walk-forward
OOS equity** curve. The statistics themselves are [overfitting](/docs/trader/analytics/overfitting)'s;
the procedures are [sweeps](/docs/trader/backtesting/sweeps) and
[walk-forward](/docs/trader/backtesting/walk-forward).

## How a sweep is ranked [#how-a-sweep-is-ranked]

`crates/vike-studio-core/src/run.rs` builds a `StudioSweep`: entries ranked best-first by
annualised Sharpe through the harness's one ranking comparator, `cmp_scores_desc`, so a `NaN`
Sharpe — an equity curve poisoned by a blown-up strategy — sorts *last* and can never sit at
`best_index` 0 and feed the deflated Sharpe. `rank_entries_by_sharpe`'s doc records the bug this
replaced: a hand-rolled comparison treated `NaN` as equal to everything, so a degenerate point
placed first by grid order stayed ranked first. Equal Sharpes keep grid order. PBO uses sixteen
CSCV splits, the canonical even count, computed off the UI thread inside the sweep. The Studio's
walk-forward is four anchored splits over one bar series — a tick or multi-symbol slice is refused
with a readable error rather than silently falling back to the first symbol.

## When there is nothing to show [#when-there-is-nothing-to-show]

A failure replaces the tabs with a header naming *which* action failed — "Run failed", "Sweep
failed" or "Walk-forward failed" — and the message in a framed monospace block; the shell's comment
records that a fixed "Run failed" header used to misattribute sweep failures, and that a failed
walk-forward used to be entirely invisible. The Sweep & Validate pane repeats a sweep or
walk-forward failure inline too, for the case where the centre panel is busy showing an older
successful result. A worker thread that dies surfaces the same way, as "run failed (worker
terminated)".


# Saved strategies and workspace (/docs/trader/gui/studio/saved-and-workspace)



The Studio persists two things, and they are not the same kind of thing. The workspace is UI
convenience state the program rewrites at will. The saved-strategy list is the user's work, and the
module that owns it says in its own header that its format is being retired.

## The workspace snapshot [#the-workspace-snapshot]

`crates/vike-studio/src/workspace.rs`'s `StudioWorkspace` holds five fields: which right-hand tool
tab is open, the editor-collapsed and tools-collapsed flags, the template dropdown's index, and the
editor's last source. `StudioState::maybe_persist_workspace` compares the live values against the
last-written snapshot once per frame and writes only on a change, so typing in the editor writes
once per drift rather than once per frame. Loading is best-effort: a missing or corrupt file yields
the defaults rather than a panic, and an empty restored `editor_source` keeps the starter script
rather than blanking the editor.

**Where it lives: `<project>/settings/state/studio_workspace.json`.** The header records the move:
it used to sit at the store root beside the strategy list, and that placement was wrong for the
same reason the pacing file's was — which tab is open describes this user's screen, not the data in
that store, so pointing the Studio at a second store silently forgot the layout. `$VIKE_STATE_ROOT`
names the state directory outright and wins; otherwise it is the project's `settings/state`, the
directory `vike_model::state_path::project_state_dir` reserves for program-written JSON, kept
apart from the TOMLs a human edits ([settings](/docs/trader/concepts/settings)). There is no third
location.

Adoption is a dual read, never a move: `workspace_read_path` falls through to the legacy
store-root file while nothing has been written to the state directory, `workspace_write_path`
always writes the state directory — which is what migrates an existing install on its first save —
and no old file is ever deleted.

<Callout type="warn" title="A symlinked state path falls back silently">
  The shared `vike_model::state_path::write_path` refuses to write through a symlink rather than
  truncate the link's target, and the workspace writer then falls back to the legacy store-root path.
  The save lands somewhere real and never through the link — but, unlike the app-level
  [workspace](/docs/trader/gui/workspace) persister, which propagates the error to the user, nothing here
  says the state directory was skipped: this crate links no logger, so there is nowhere to warn.
</Callout>

A headless capture session that forces a tool tab never writes the workspace at all, so a capture —
or a lingering `VIKE_STUDIO_TAB` in a dev shell — cannot persist the forced state over the real
file.

## The saved-strategy list [#the-saved-strategy-list]

The Saved tool (`crates/vike-studio/src/saved.rs`'s `SavedPane`) is a name box with 💾 Save (also
`Ctrl+S`), a list with Load and ✕ Delete per row, and **Compare all**. The list is
`studio_strategies.json`, pretty JSON, colocated with the store: `StudioState`'s `state_dir` is
the caller-supplied stand-in for the store root, and `vike-desktop` passes its resolved local
history-store root, so a local session keeps the exact old location and a remote session keeps its
strategies at the same stable local path. Every write goes through `StudioState::persist_saved`,
and a write failure is swallowed — the in-memory list stays authoritative for the session.

An entry is either a **Rhai** script or a **Native** registry strategy plus its free-form parameter
rows, stored as text because the [harness registry](/docs/trader/backtesting/harness-registry) has no
parameter spec to type them against. Loading a Rhai entry replaces the editor buffer and
re-baselines the unsaved dot; loading a native entry restores the strategy source instead of
blanking the editor with its empty code, and opens the Strategy tool. `StrategySource`'s doc marks
backward compatibility as load-bearing: files written before native entries existed have no
`source` key, the field defaults to `Rhai`, and reordering the enum so `Native` became the default
would silently reinterpret every legacy script as a registry name.

Compare all backtests every saved strategy over the selected slice on a worker thread — a Rhai
script and a native strategy rank side by side — and `comparison_rows` builds the table:
successful rows by annualised Sharpe descending with `NaN` Sharpes last among them, then every
failed row with its reason inline rather than dropped, which the doc names as the previous
behaviour. The Kind column says what was ranked, the ★ marks the best, and each successful row
carries a sparkline.

## Why the blob is being retired [#why-the-blob-is-being-retired]

`saved.rs`'s header states it: this blob is being retired in favour of files.
`crates/vike-studio-core/src/user_strategies/mod.rs` loads a user's strategies from
`<project>/user_data/strategies/`, one folder per strategy, and argues the blob's two defects. One
corrupt byte loses the library — `load_strategies` answers a parse failure with an empty list, the
right call for a window layout and the wrong one for the only copy of somebody's work. And it was
filed under the wrong owner: inside the history store, re-downloadable market data whose lifecycle
is delete-and-re-ingest. A file can also be opened in an editor, diffed, committed and sent to
somebody. [User strategies](/docs/trader/scripting/user-strategies) is the loader;
[presets](/docs/trader/scripting/presets) is what a `.toml` beside an entry file means.

The migration is `user_strategies/migrate.rs`, covered in full by
[migration](/docs/trader/scripting/migration). From this side: `SavedStrategy::legacy_entry` is the one
place the JSON schema becomes the migration's vocabulary, kept beside the schema because the lower
crate cannot name the type. A Rhai row becomes `strategies/rhai/<name>/<name>.rhai`, verbatim; a
native row carries no code and becomes a preset for its registry strategy,
`strategies/rust/<native>/<entry-name>.toml`, its text rows serialised through the same
`params_from_rows` the run-time path uses, so `2` stays an integer and a bare `BTCUSDT` becomes the
quoted string it would have been at run time. Every row it cannot migrate is named — unnameable,
nameless native, a collision between two names that slug to one stem (case-folded, because `Fast`
and `fast` are one file on Windows), already present, write failed, unserialisable preset. It
writes only where nothing exists, so a second run writes nothing, and it never reads, writes, moves
or deletes `studio_strategies.json` — it does not even take its path. After the migration the JSON
is a read-only fallback a rolled-back build still finds.

<Callout title="The pane still writes the blob">
  `legacy_entry`'s doc says `load_strategies` stays and `save_strategies` is what the migration
  retires — but as of this build the Saved pane's Save and Delete still persist through
  `save_strategies`, so the JSON remains the pane's live store. Which binary runs the migration, and
  when, is stated by neither module.
</Callout>


# The templates gallery (/docs/trader/gui/studio/templates-gallery)



The starters live in `crates/vike-script/src/templates.rs`, and its header says what they are
for: starter Rhai strategies for the Studio, each parameterised via `param()` so they drop straight
into the sweep grid. `templates()` returns three `(name, source)` pairs, and
`every_template_compiles_and_is_parameterized` compiles every one and checks that it exposes at
least one `param()`, so a starter that will not build or cannot be swept cannot ship.

## The three [#the-three]

* **SMA cross** — `fast` (default 5) and `slow` (20); long when the fast average is above the slow
  one, short below, reaching the target through `market(...)` by the delta from `position()`. The
  Studio's default editor script is the same idea with hard-coded constants; this is the sweepable
  form.
* **RSI reversion** — `len` (14), `lo` (30), `hi` (70); buys one unit below `lo` when not already
  long, sells one above `hi` when not already short.
* **Donchian breakout** — `len` (20); a symmetric proxy over `sma`, and the template says so in its
  own comment: `donchian` is not bound to scripts because it is multi-output (upper/mid/lower) and
  the bridge binds single-output indicators only, so `donchian(len)` would be a function-not-found
  at the first call rather than a silent upper-band read. Long when `high()` breaks above the
  average, short when `low()` breaks below.

Every template guards its warm-up with `is_nan()` before acting — the pattern a script over any
indicator needs. [Writing a strategy](/docs/trader/scripting/writing-a-strategy) covers the language and
[the order vocabulary](/docs/trader/scripting/order-vocabulary) the verbs.

## Two ways to load one [#two-ways-to-load-one]

Both live in the Sweep & Validate tool. The **Template** dropdown plus its Load button loads blind:
the selected template's full source replaces the editor buffer. Below it, the **Browse templates**
header opens the gallery — `crates/vike-studio/src/templates_gallery.rs`, whose header states the
difference: richer than the one-line dropdown, because you see the script before loading it. Each
card shows the template's name, the first eight lines of its code in monospace with a trailing `…`
when the script is longer (`template_preview`, which is pure and tested), and a Load button hugging
the right edge so every card's action lines up.

Either route overwrites the editor buffer with the full template code and re-baselines the
[editor](/docs/trader/gui/studio/editor)'s unsaved-changes tracking, so a freshly loaded template is
not marked dirty. `gallery_ui` returns `true` the frame Load is clicked for exactly that purpose,
mirroring the indicators pane's bool-return convention.

The empty results panel offers the same thing as a getting-started action: beside ▶ Run backtest it
shows "Load a template", which loads whichever template the dropdown currently selects.

<Callout title="The dropdown selection is workspace state">
  `template_idx` — the dropdown's position — is one of the five fields the
  [workspace snapshot](/docs/trader/gui/studio/saved-and-workspace) persists, and `StudioState::new_with_qa`
  clamps a restored index against the current `templates()` length, so a value stored by a build
  with more or fewer templates can never index out of bounds.
</Callout>

## Into the sweep grid [#into-the-sweep-grid]

Because each starter declares its knobs with `param()`, "Seed from params" in the same pane fills
the parameter grid from the script's declarations through `vike_script::discover_params` — one row
per parameter, its default as the initial candidate — and ▶ Run Sweep backtests every combination
of the values you type ([results](/docs/trader/gui/studio/results) covers the ranked table). A
discovery failure, such as a script that does not compile, clears the grid rather than raising an
error; Run and Sweep report the compile error when the script is actually executed.

<Callout title="Not the strategy templates">
  These are Rhai scripts for the editor. The per-template pages under the
  [strategies](/docs/trader/strategies) tree describe compiled Rust strategies — a different
  thing. In the Studio a compiled strategy is reached through the Strategy tool's "Native (Rust)"
  switch, whose dropdown lists the backtest [harness registry](/docs/trader/backtesting/harness-registry)'s
  own roster, never through this gallery.
</Callout>


# Basis (/docs/trader/market-making/xemm/basis)



`crates/vike-mm/src/xemm/basis.rs`'s `BasisEwma` is the [cross-exchange maker](/docs/trader/market-making/xemm)'s
estimate of the observed basis between its two venues: an event-time EWMA of `mid_A / mid_B − 1`,
where A is the maker venue and B the reference. Its header opens with the rule the whole file is
built around.

<Callout type="warn" title="Diagnostic and halt band only — never a term in a quote price">
  The obvious use for a basis estimate is to rebase the reference touch before pricing.
  `crates/vike-mm/src/xemm/pricing.rs`'s `passive_clamp` carries the argument against it. Rebasing
  **destroys the hedge identity**: with A 10 bp below B and `edge + fee` also 10 bp, the rebased ask
  lands on `ask_B`, so selling on A and buying back on B is a guaranteed loss net of fees — and every
  such fill *looks* hedged. Flooring the rebase back against the raw quote restores the identity but
  pins the disadvantaged side at a price that can never fill, leaving a one-sided accumulator quoting
  off an estimate whose error between the fill and the hedge is unbounded. The clamp needs no estimate
  at all: venue A's own book is the ground truth about where A trades.
</Callout>

## Two jobs, both honest for a point estimate [#two-jobs-both-honest-for-a-point-estimate]

The header allows the estimator exactly two uses. First, **publish** — `XemmMaker::basis` exposes
the value so an operator can size `min_profitability` against basis **volatility** rather than a
point level; the volatility, not the level, is the real risk between the A-fill and the B-hedge.
Second, `BasisEwma::out_of_band`, the halt band, which catches a decoupled pair, a wrong-instrument
mount and a lying feed with one number, turning "this pair has no two-sided edge" into an
operator-visible halt instead of a silent one-sided accumulation. In `XemmMaker::detect_fault` that
verdict is `HaltReason::BasisOutOfBand`, evaluated last — after the freshness bounds and the
exposure faults, in the order a diagnosis should read.

## Three deliberate disciplines [#three-deliberate-disciplines]

* **Paired observations only.** A fold needs both venues' mids, both sane. Folding one venue's move
  against the other's stale last price would measure feed latency, not basis.
  `XemmMaker::observe_touch` feeds the estimator only once both touches are known and both pass
  `Touch::is_sane`, stamping the fold with the later touch's event time.
* **Event-time half-life, never wall clock**, so the estimate is deterministic under test and
  identical under replay — the same rule the rest of the crate's windows follow.
* **Never fed by own fills.** Own fills are the adversely-selected sample: the maker is filled
  precisely when the basis moved against it, so folding them would bias the estimate toward the side
  already being picked off. The estimator sees market touches only.

## The fold [#the-fold]

`BasisEwma::observe(mid_a, mid_b, ts, halflife_ms, clamp)` folds one paired observation. The raw
observation `mid_a / mid_b − 1` is clamped to `±clamp` when `clamp > 0`, so one garbage touch cannot
move the estimate arbitrarily far — the estimator's job is to detect a persistent regime, and a
single outlier is the opposite of that. The decay weight is `0.5^(dt / halflife)` in event
milliseconds, so one half-life exactly halves the weight of everything before it; the test
`one_halflife_halves_the_previous_weight` pins that bit-for-bit, because the band's calibration
depends on it. A non-positive `dt` — a same-timestamp or out-of-order tick — folds at full weight
rather than being dropped: an out-of-order tick is still a real observation, and dropping it would
make the estimate depend on arrival order. The fold is a no-op when `halflife_ms <= 0`, when either
mid is not finite and strictly positive, or when the ratio comes out non-finite; insane inputs fold
nothing rather than poisoning the estimate.

The estimator is **cold** — `value()` is `None` — until its first paired observation, and disabled
means permanently cold, not merely quiet: with a non-positive half-life nothing downstream can read
a stale or fabricated value out of it. The value is a fraction; `−0.001` means venue A trades 10 bp
below venue B.

`out_of_band(max_bps)` is `true` when the estimate has warmed **and** `|value| · 10_000` exceeds
`max_bps`. A non-positive `max_bps` disables the band, and a cold estimator never trips it — an
absent estimate is not evidence of a wide basis; the freshness bounds on
[guards](/docs/trader/market-making/xemm/guards) cover "I can't see anything". The band is on magnitude,
in both directions.

## The knobs [#the-knobs]

`crates/vike-model/src/strategy/xemm_params.rs`'s `XemmParams` carries three: `max_basis_bps`, the
halt band in basis points of the reference mid; `basis_halflife_ms`, the event-time half-life;
and `basis_clamp`, the per-observation bound as a fraction. `XemmParams::default` sets the half-life
to `60_000` ms and the clamp to `0.05` with the band **off** (`0.0`) — `XemmMaker::with_basis_band`'s
doc notes the estimator still warms and publishes in that state, it just never halts. The TOML keys
under `XemmMaker::from_params` are the same three names.

<Callout title="The pure core is pinned across platforms">
  `crates/vike-mm/src/platform_probe.rs`'s `PINNED_STATEFUL` carries a recorded cross-platform hash
  for `observe` — the fold reaches its `pow` through the `libm` crate rather than the platform — which
  is one of the concrete costs of deleting the stack. The estimator is dormant with the rest of the
  xEMM, but it is not inert in the tree.
</Callout>


# Guards (/docs/trader/market-making/xemm/guards)



Between a maker fill on venue A and the hedge fill on venue B a cross-exchange maker is directionally exposed, on a leg it cannot see through any broker read — a risk a single-venue maker does not carry. `crates/vike-mm/src/xemm/guards.rs`'s module doc says every verdict in it exists because some way of losing sight of that exposure has a specific, nameable shape: the reference feed silently freezes; the maker venue's own feed freezes, so `passive_clamp` is anchored on a touch that no longer exists; both freeze, so neither age bound can fire from a lane that never runs; the hedge does not fill; the pair decouples. Each is a pure function, testable without a runtime or a broker, so the fault path is one readable list rather than a chain of inline conditions.

<Callout type="warn" title="Built, tested, and mounted by nothing">
  `XemmMaker` is reached by no binary — `crates/vike-run/src/xemm.rs`'s `build_live_xemm_core` has no caller, and `crates/vike-strategy/src/registry.rs`'s `strategy_by_name` has no `xemm` arm. Keeping the code rather than deleting it was a deliberate verdict, not an oversight. These guards are design constraints a future mount must not break, not a description of anything running today; see [the xEMM overview](/docs/trader/market-making/xemm).
</Callout>

## The halt vocabulary [#the-halt-vocabulary]

`HaltReason` is public and serialisable, and every variant is an operator-facing fact — a specific thing that is wrong, not a generic error, because the correct response differs:

| reason              | what it names                                                                                                                |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `ReferenceStale`    | the reference venue's touch is older than `max_ref_age_ms`, or has never arrived                                             |
| `OwnTouchStale`     | the maker venue's own touch is older than `max_own_touch_age_ms` — the passive clamp's anchor is gone                        |
| `FeedImpaired`      | neither venue has ticked within `max_emission_gap_ms`, or the maker venue's feed reported a non-`Live` status                |
| `HedgeUnfilled`     | the hedge residual survived its full retry budget — an open, unhedged position the taker venue has refused to close          |
| `NakedHardBand`     | the unhedged exposure breached `naked_hard_band`                                                                             |
| `BasisOutOfBand`    | the observed maker-vs-reference basis breached `max_basis_bps` — a decoupled pair, a wrong-instrument mount, or a lying feed |
| `UnknownFillSymbol` | a fill arrived for a symbol that is neither leg; the maker can no longer know its own inventory, so it fails closed          |

The doc's triage: a stale feed is transient, an out-of-band basis means the mount is probably wrong, and an unfilled hedge means there is a real open position someone has to close by hand.

`Halt` is `Running` or `Halted { reason, since }`. A halt **latches** with the event timestamp it began at, and `crates/vike-mm/src/xemm/mod.rs`'s `enter_halt` keeps the first reason if one is already latched — the first fault is the diagnostic one, and a cascade of consequences would otherwise overwrite it. `resume_after_halt_ms` is event time like every window in the crate; its default `0` means manual resume only, which `maybe_resume`'s doc calls correct for faults that all mean "something I cannot see is wrong". The latch is persisted in `XemmStateV1`, so a halted maker cannot un-halt merely by being restarted — `load_state`'s doc says a restore can only make the maker more cautious, never less. `XemmMaker::halt_reason` is the operator-facing observable.

## Freshness [#freshness]

`stale(last_ts, now, max_age_ms)` is true when the timestamp is absent, or older than `max_age_ms` of event time. Three edges are deliberate and pinned: `max_age_ms <= 0` disables the bound for a **present** timestamp, but an absent one is still stale, because no configuration may declare a never-seen feed fresh; a negative age (an out-of-order or clock-skewed tick) is fresh, since it is evidence the feed is alive and halting on it would fire on healthy feeds; and the bound is inclusive — exactly at it is fresh, one millisecond past is stale.

`detect_fault` consults it three times, freshness first as the most common and most recoverable fault: the reference touch against `max_ref_age_ms`, the own touch against `max_own_touch_age_ms`, then `last_tick_ts` — the last touch from **either** venue — against `max_emission_gap_ms`. That third clock exists because the per-venue ages each catch one dead feed, and when nothing at all is arriving no per-venue lane can fire. A cold start, either touch not yet seen, is deliberately not a fault; `requote` pulls on it anyway. `XemmParams::default` sets both ages to 2 s and the gap to 5 s, and `the_defaults_ship_every_guard_armed` pins that every guard ships armed — the one place this workspace inverts its neutral-default rule, because a strategy signing orders on two venues must not be one forgotten field away from quoting into a frozen feed. Under `with_freshness` any `<= 0` disables that bound, which for the two ages means "quote off a dead feed forever".

Three lanes back the pure check. `on_feed_status` receives the maker venue's status only — `FeedStatus` carries neither venue nor symbol — and any non-`Live` value halts as `FeedImpaired` and pulls at once; the reference venue is covered by `max_ref_age_ms`, which is strictly stronger than a status subscription because it also catches a feed that freezes without ever reporting a disconnect. `on_schedule` is the all-feeds-dead sweep: every other lane fires off a market message, so when both venues go silent none of them run and a stale quote would rest forever; the wall-clock schedule fires regardless and re-runs the whole funnel. `on_trade_tick` carries no touch but advances the clock, which lets a bound fire on a venue printing trades while its quote feed has silently frozen.

## The naked bands [#the-naked-bands]

Both bands read `HedgeLedger::naked` — `maker_pos + hedge_pos`, the exposure actually carried — off the [hedge ledger](/docs/trader/market-making/xemm/hedge), never a broker.

`soft_band_suppression(naked, band)` returns `(suppress_bid, suppress_ask)`. While `|naked| > band` the side that would grow the exposure is withheld and the reducing side keeps quoting, so the maker trades its way back toward flat instead of stopping dead: net long suppresses the bid, net short the ask. The doc calls it the mirror-image of the fill-rate breaker — that one reacts to one-sided flow, this one to the resulting position. A negative band is clamped to `0`, a non-finite exposure suppresses both sides, and exactly at the band holds. In `requote` it is one of three suppression terms, beside the breaker's cooldown and a non-positive size.

`over_hard_band(naked, hard)` is strictly over (`>`), matching `taker_flatten`'s "exactly at the band is not over" convention so the halt and the impulse leg engage on the same inventories — `the_hard_band_matches_taker_flattens_convention` asserts they agree. `hard <= 0` disables the band (there is no meaningful "halt on any exposure"; that is the soft band's job), and a non-finite exposure trips it. On a breach `detect_fault` raises `NakedHardBand`, `requote` pulls both sides, and `drive_flatten` crosses the taker venue for the excess over the **soft** band — the [flatten-the-excess law](/docs/trader/market-making/taker-flatten). The impulse fires at most once per halt (`flatten_fired`, cleared on resume) and only while the ledger owes nothing, since an in-flight hedge is already closing the exposure; at `hedge_ratio == 1.0` the residual and the naked exposure are the same quantity, so the leg is unreachable by construction and exists for the partial-ratio case.

`XemmMaker::new` sets the bands to `qty` (soft) and `3·qty` (hard): one full quote size of unhedged exposure stops growing it, three sizes is a fault. `with_naked_bands` tunes both, and `from_params` keeps the derived pair unless the profile names `naked_band`/`naked_hard_band`.

<Callout type="warn" title="A bare XemmParams::default arms no hard band">
  `XemmParams::default` sets both bands to `0.0`, and its doc reads that as suppress on any exposure and halt on any exposure. The soft half is right; the hard half is not: `over_hard_band` treats `hard <= 0` as disabled, and its test pins `!over_hard_band(1e9, 0.0)`. A maker configured from a bare default through `apply_params` has no hard halt at all; the builder (`new`) or the TOML reader (`from_params`) is what gives you one.
</Callout>

## The remaining verdicts, and what a halt does [#the-remaining-verdicts-and-what-a-halt-does]

`HedgeUnfilled` is `HedgeLedger::attempts_exhausted` — owed, budget spent, and timed out, all three. `BasisOutOfBand` is `BasisEwma::out_of_band`: the estimate has warmed and `|basis| · 10 000 > max_bps`; `max_bps <= 0` (the default) disables it, and a cold estimator never trips, because an absent estimate is not evidence of a wide basis — the freshness bounds cover "I cannot see anything" ([basis](/docs/trader/market-making/xemm/basis)). `UnknownFillSymbol` latches from `on_fill` with no order verb, because the dispatch series of an unattributable fill is unknown and a tagged cancel from the wrong series is a silent no-op; the next maker-venue lane pulls both sides. `detect_fault`'s full order is reference age, own age, emission gap, hedge exhaustion, hard band, basis — freshness, then exposure, then the model.

`requote`'s stage 0 runs `maybe_resume`, then `detect_fault`, and a halted or not-yet-ready maker calls `pull_all` and stops. `pull_all` is two `cancel_tagged`s, never `mass_cancel`, which in the live runtime is scoped to the dispatching series and from a hedge-fill dispatch would cancel nothing on the maker venue — a pull that silently does not pull. A pull is never gated by the [refresh tolerance](/docs/trader/market-making/refresh-tolerance). The one-sided-fill breaker (`record_maker_fill`, maker-leg fills only, off by default) is the symptom guard beside these — see [inventory skew](/docs/trader/market-making/inventory-skew) — and `crates/vike-mm/src/tests/xemm_guards.rs` opens with the poisoned-broker test that pins the one read the maker must never make, and drives the freshness, hard-band and basis verdicts to their halts; `HedgeUnfilled` and `UnknownFillSymbol` are driven in `crates/vike-mm/src/tests/xemm_hedge.rs` instead.


# The hedge ledger (/docs/trader/market-making/xemm/hedge)



Every fill the cross-exchange maker takes on the maker venue creates a directional exposure that only an order on the taker venue can close. `crates/vike-mm/src/xemm/hedge.rs`'s `HedgeLedger` is the one place that exposure is accounted for — the xEMM's **only inventory authority** — and its defining choice is that it is a **target, not a delta**.

<Callout type="warn" title="Built, tested, and mounted by nothing">
  `XemmMaker` is reached by no binary — `crates/vike-run/src/xemm.rs`'s `build_live_xemm_core` has no caller, and `crates/vike-strategy/src/registry.rs`'s `strategy_by_name` has no `xemm` arm — and it has never quoted on a venue. Keeping the code rather than deleting it was a deliberate verdict, not an oversight. Read this page as the design constraints a future mount must not break; see [the xEMM overview](/docs/trader/market-making/xemm).
</Callout>

## Why a delta ledger is wrong [#why-a-delta-ledger-is-wrong]

The obvious ledger adds the owed hedge on a maker fill and subtracts it on a hedge fill. The module doc names its silent, unbounded failure: a hedge whose ack is lost — the ordinary case `hedge_timeout_ms` exists for — is re-fired, and if the original then fills too, a delta ledger has subtracted once and sent twice. The position doubles while the maker believes it is flat.

The ledger instead holds the two legs' **signed** positions — `maker_pos` folded from maker-leg fills, `hedge_pos` from hedge-leg fills, `+` long in both — and derives everything else:

```text
target   = −hedge_qty(maker_pos, hedge_ratio)   // the hedge position we WANT
residual = target − hedge_pos                   // what still has to be sent
naked    = maker_pos + hedge_pos                // the exposure actually carried
```

`crates/vike-mm/src/xemm/pricing.rs`'s `hedge_qty` is `net_filled_base · hedge_ratio`, linear in both. A retry re-sends `residual`, which a late original fill has already shrunk — so **a retry can never double the position, whatever order the acks arrive in**. The in-file test `a_retry_never_doubles_the_position` drives the sequence a delta ledger fails — fire, time out, re-fire, then the original lands — and if the retry then fills too, the residual reports an over-hedge to be unwound rather than "flat". Sign convention: `side` is `+1` buy / `−1` sell, `size` unsigned, and a maker buy of 5 owes a hedge sell of 5.

## Why the broker seam is never read for inventory [#why-the-broker-seam-is-never-read-for-inventory]

`Broker::position(hedge_symbol)` would be the natural source for `hedge_pos`. Two of the three reasons the module doc used to give against it are history — the runtime defects in `declared_views` and `dispatch_applied_fills` are fixed, with `crates/vike-core/tests/wiring/multi_symbol_reads.rs` as the proof. What survives is narrower and still decisive: `HftBroker::position`, the verb this maker's own trait bound gives it, takes no symbol and returns the *dispatching* engine's scalar, so reading a hedge leg through it is wrong by signature; and a broker read answers about **settled** state while this ledger exists for the **in-flight** hedge — no `Broker::position` can see a sent-but-unacked order, and a ledger derived from one would re-fire the full residual and double the position on a late ack. So the fill stream stays the authority, needs zero plumbing, and `crates/vike-mm/src/tests/xemm_guards.rs`'s `the_maker_never_reads_position_price_or_equity_through_the_broker` pins the maker's output bit-identical against a broker whose every read surface is poisoned.

## Residual, dust, and the deliberate naked position [#residual-dust-and-the-deliberate-naked-position]

`HedgeLedger::residual(hedge_ratio, dust)` returns the owed order as `(side, qty)`, or `None` when the hedge is complete within `dust`. Dust forgives a residual smaller than the taker venue's `min_qty`: a sub-minimum order is rejected by the venue, and a rejected hedge is an unhedged position that would be retried forever. The bound is inclusive, so a residual exactly at it settles rather than oscillating; a negative `dust` is clamped to zero; a non-finite residual is treated as settled, there being no order to name. `XemmParams::hedge_dust`'s doc says to set it to the taker venue's `min_qty` ([symbol properties](/docs/trader/concepts/instruments/symbol-properties)); the default is `0.0`.

`naked()` is **not** the residual. With `hedge_ratio < 1.0` a fully executed hedge still leaves a deliberate naked position — `a_partial_ratio_leaves_a_deliberate_residual_exposure` hedges 6 of a 10-unit fill at ratio `0.6` and reports 4 naked — and that is exactly what the [naked bands](/docs/trader/market-making/xemm/guards) measure, so "deliberate" never means "invisible". `hedge_ratio == 0.0` owes nothing and fires no order rather than a zero-size one. `XemmParams::hedge_ratio`'s doc calls `1.0` the only defensible v1 setting, and it is the default.

## In flight, attempts, and exhaustion [#in-flight-attempts-and-exhaustion]

`InFlight { ts }` records the event timestamp a hedge was sent at — the timeout clock. `fire(ts)` sets it and increments `attempts`; `settle()` clears both, so a new maker fill after a completed hedge starts with the full budget rather than inheriting the last cycle's. `timed_out(now, timeout_ms)` is true once a sent hedge has been outstanding for at least `timeout_ms` of event time; `timeout_ms <= 0` disables the timeout, and with it any consumption of the budget past the first send.

`attempts_exhausted` needs all three: something still owed, `attempts >= max_attempts`, **and** the last send timed out — a hedge merely in flight is not a fault. When all three hold, `HaltReason::HedgeUnfilled` is raised, because continuing to quote past that point grows an exposure the taker venue has demonstrably refused to close. `XemmParams::default` times the hedge out at 3 s with 3 attempts. The budget counts **sends**, the first included — `XemmMaker::with_hedge_discipline`'s doc spells `0` as "never hedge at all".

## Where it fires from [#where-it-fires-from]

`crates/vike-mm/src/xemm/mod.rs`'s `drive_hedge` is the target-residual discipline in one place: nothing owed settles the ledger; a hedge in flight and not yet timed out, or a spent budget, sends nothing; otherwise the residual goes out as `Broker::submit_market(hedge_symbol, side, qty)` and the send is recorded. That verb is a hard contract — the only venue-routable one, because the runtime's `resolve_intent_venue` finds a declared leg by symbol and a tagged submit carries `symbol: None`. A tagged verb here would place the hedge on the **maker** venue, doubling the exposure it was sent to close.

`crates/vike-mm/src/xemm/strategy_impl.rs`'s `on_fill` routes by `Fill::symbol`, the only leg discriminator a fill carries, which is why `XemmMaker::new` panics on equal leg symbols. On the maker leg it folds the fill, hedges **first** and re-quotes second — the exposure just created is the urgent thing. On the hedge leg, a dispatch that drains on the taker venue's series, it folds and calls `drive_hedge` only: never a tagged verb, never `requote` or `pull_all`. `on_schedule` calls `drive_hedge` too, so an owed hedge gets its retry even when both feeds are silent. Hedge-leg fills never reach the [one-sided-fill breaker](/docs/trader/market-making/inventory-skew): they are the maker's own mechanical offset, and netting them would cancel every real signal to exactly zero.

<Callout title="A rejected hedge is handled by the clock, not by an event">
  `on_order_event` is deliberately not implemented: how a rejected or externally cancelled hedge leg folds back into `HedgeLedger` and `InFlight` is a hedge-accounting question `strategy_impl.rs`'s module doc says is undesigned, and "no reaction is better than a guessed one". Until then a lost or refused hedge is the in-flight marker aging past `hedge_timeout_ms` and the residual being re-sent — the path the ledger was built to make safe.
</Callout>

## Persistence and observables [#persistence-and-observables]

`XemmStateV1` persists `maker_pos`, `hedge_pos`, `hedge_attempts` and the in-flight timestamp across a restart, because an unhedged position is real money at risk on two venues and a maker that forgets it restarts believing it is flat; `load_state` is fail-open and can only make the maker more cautious ([mounting](/docs/trader/concepts/mounting) covers strategy-state persistence). `XemmMaker::naked_exposure` and `leg_positions` read the owned ledger for the operator. A hot re-tune through `apply_params` never touches it — the ledger is a sibling of the tunable bag, and the two leg symbols live outside that bag as identity, so a re-tune cannot repoint a leg while an unhedged position is open. The test module is `crates/vike-mm/src/tests/xemm_hedge.rs`, whose header calls it the #997 regression surface and the most dangerous code in the crate.


# Cross-exchange market making (/docs/trader/market-making/xemm)



`crates/vike-mm/src/xemm/mod.rs`'s `XemmMaker` is the cross-exchange market maker: rest passively
on venue A, the maker venue, at prices derived from venue B's touch, and hedge every fill on B. Its
pricing arithmetic is a port of an Apache-2.0 cross-exchange strategy; the risk half — the guards,
the hedge ledger and the basis estimator — is Vike Trader's own.

<Callout type="warn" title="Built, tested, and mounted by nothing">
  `crates/vike-run/src/xemm.rs`'s `build_live_xemm_core` has no caller; its paper twin is called only
  from tests; `crates/vike-strategy/src/registry.rs`'s `strategy_by_name` has no `xemm` arm, so a
  profile naming it is told it does not exist; there is no feature gate, flag, CLI verb or GUI
  surface. It has never quoted on a venue. Keeping the code rather than deleting it was a deliberate
  verdict, not an oversight — and registering `"xemm"` in that registry would be the wrong road
  anyway: it would produce a single-leg mount that never hedges. The
  event that flips it to mounted is one mount declaring a leg on a second venue — a non-empty
  `MountSpec::legs`, the shape `xemm_mount_legs` produces.
</Callout>

## What it earns [#what-it-earns]

xEMM earns the **maker spread**: it rests at `reference ± (edge + fee)` and offloads any fill on B,
so it profits from *being filled*, not from a pre-existing price gap. The module doc adds why the
distinction is load-bearing: the cross-venue dislocation this strategy is often mis-explained by
does not survive a four-crossing cost floor on the pairs measured here.

## The pure core [#the-pure-core]

`crates/vike-mm/src/xemm/pricing.rs` is four functions and one value type, no state and no I/O.
`xemm_maker_quotes` turns B's `(bid, ask)` into the pair to rest on A:
`maker_bid = taker_bid · (1 − min_profitability − total_fee)` and
`maker_ask = taker_ask · (1 + min_profitability + total_fee)`, so a fill on A can always be hedged
into B at a profit no smaller than the edge. Both terms only ever add, the spread widens
monotonically in each, and with both at zero the maker quotes collapse onto the taker touch
bit-for-bit. The header calls this **the hedge identity**, living here and nowhere else: every later
stage may move a quote away from the reference touch, never toward it. `hedge_qty` sizes the hedge
as `net_filled_base · hedge_ratio`.

`passive_clamp` holds each side strictly inside A's own touch — `min(raw_bid, a_ask − standoff)`
and `max(raw_ask, a_bid + standoff)`. `min`/`max` can only move a quote away from the reference, so
the edge survives by construction, and the quote can never be marketable on A, which is the
structural substitute for the post-only that **no roster venue supports** — `vike_model::venue_caps`
pins `supports_post_only: false` on all 14 rows. It refuses rather than degrades — no maker touch,
an insane touch, a non-finite price, a non-positive standoff or a crossed result all return `None`,
and the caller **pulls**. `snap_down` and `snap_up` then
put the two prices on A's grid directionally, because the crate's half-to-even `round_to_step`
could round a clamped bid back up through the clamp.

## The one hard problem: a persistent basis [#the-one-hard-problem-a-persistent-basis]

Two venues quoting the "same" instrument sit at systematically different prices — the doc's
measurement is that hyperliquid trades below the CEXes on some instruments in more than 99 % of
minutes. A maker treating B's touch as fair value for A therefore quotes marketable on one side
continuously, paying an unbudgeted taker fee — and paper and backtest book that as a **maker** fill
(`is_maker = kind == Limit` at both fill sites), so the rehearsal looks profitable. The fix is
placement, not a price term. `passive_clamp`'s doc states the consequence so nobody reads it as a bug: on a
pair whose basis exceeds the required edge, one side rests deep and inert while the other sits at
A's touch and fills — the economic truth of the pair. The obvious alternative, rebasing the reference
by an estimated basis, is refuted on the [basis](/docs/trader/market-making/xemm/basis) page.

## Four independent safety layers [#four-independent-safety-layers]

The doc lists them because none alone suffices: the passive clamp, structural and impossible to
mis-tune; the basis halt band, which catches a decoupled pair, a wrong-instrument mount or a lying
feed; the one-sided-fill [breaker](/docs/trader/market-making/inventory-skew), which fires on the
symptom regardless of whether any model is right; and the naked bands — soft suppression of the
growing side, then a hard halt plus a [taker-flatten](/docs/trader/market-making/taker-flatten) impulse
on the excess. The freshness bounds and the halt vocabulary are on
[guards](/docs/trader/market-making/xemm/guards); the inventory authority — a target, not a delta — is
the [hedge ledger](/docs/trader/market-making/xemm/hedge). The maker reads no inventory through the
broker seam anywhere, and a poisoned-broker test pins it.

`XemmMaker::requote` is the one quote funnel: a halted or not-yet-ready maker pulls both sides;
then the hedge identity, the passive clamp against A's own touch — with `min_edge_ticks` floored at
`1.0`, because a sub-tick standoff rounds onto the touch — the directional snap, inventory skew on
the sizes off the owned ledger, per-side suppression, and emission bid-then-ask. The hedge goes
through `Broker::submit_market`,
the only venue-routable verb — a tagged submit carries no symbol and the runtime resolves a leg by
symbol alone — which is why the bound is `HftBroker` and why `XemmMaker::new` panics if the two
symbols are equal.

## Defaults that ship safety on [#defaults-that-ship-safety-on]

`crates/vike-model/src/strategy/xemm_params.rs`'s header declares a knowing inversion of the
workspace's neutral-default rule: xEMM has no existing behaviour to protect, and every guard's
neutral value is unsafe. `XemmParams::default` sets both touch-age bounds to 2 s, the
all-lanes-quiet gap to 5 s, a 3 s hedge timeout with 3 attempts, a 60 s basis half-life with a
`0.05` clamp, `resume_after_halt_ms = 0` (manual resume only) and `qty = 0.0`, so a bare default
quotes nothing. `total_fee` must come from `vike_model::fees::xemm_round_trip_fee`, whose `None` is a refusal a
caller may not default to `0.0`: it refuses every fee **shape** a flat fraction of price cannot
express or would understate, because a silent zero would price a fee-bearing round trip as free;
its `assume_taker_on_maker_leg` defaults to false precisely because the clamp keeps the maker leg
passive. The two symbols are identity, not config, held outside the params bag:
`XemmMaker::apply_params` is one struct copy that can widen the edge or cut size but never repoint
a leg mid-flight.

`crates/vike-run/src/xemm.rs`'s header names the three feeds a live mount would need — the maker venue's L1/L2, the taker venue's
L1 delivered to `on_reference_quote` through `MountLeg::at`, and a periodic `LiveSchedule` sweep,
the one lane that still fires when both venues go silent — and that file's `XemmMountConfig` names
the v1 pair: a hyperliquid maker leg on `BTC` against an okx taker leg on `BTC-USDT-SWAP`.


# backtest (/docs/trader/reference/binaries/backtest)



`backtest` is the standalone run driver: it reads a harness profile, runs the simulator against the
history store and prints a report. It is behind `required-features = ["datafusion-store"]`
(`crates/vike-backtest/Cargo.toml`) because it opens a concrete `DataFusionHist` — a default build
of the crate compiles none of it.

```
usage: backtest --profile PATH [--store DIR] [--json]
       backtest --profile SWEEP.toml [--rank-by sharpe|return|max_dd|equity|multi]
                [--search grid|euler] [--euler-depth N]
                [--optimizer tpe [--trials N] [--seed S]]
       backtest --list
       backtest --seed-demo [--store DIR]
       backtest --fetch VENUE:SYMBOL:INTERVAL (--days N | --from LABEL --to LABEL) [--store DIR]
       backtest --fetch-starter [--store DIR]
       backtest --export VENUE:SYMBOL:INTERVAL --out FILE [--from LABEL --to LABEL] [--store DIR]
```

`--profile` names the harness profile TOML — the data slice, the engine costs and the strategy —
and is required unless `--list`. `--store` picks the hist-store root, falling back to
`$VIKE_HIST_STORE`, then the `<project>/market_data/hist` of a project named outright by
`$VIKE_SETTINGS_DIR`, then `<repo>/market_data/hist` if the checkout that built the binary is still
on the box, then the project the working directory sits in, and finally the per-user data directory
(`…/vike-data`). `--json` prints the report as pretty JSON instead of the human table. `--list`
prints every registered strategy name and exits: no store, no profile needed. `--help` and
`--version` are answered on stdout with exit 0, **before** `vike_log::init`, because answering
either must not create a log directory.

The bin (`crates/vike-backtest/src/bin/backtest.rs`) is a thin shim over
`vike_backtest::backtest_cli::run`. It is the composition root and holds the two things the library
may not: the one `std::env::vars()` sweep, and the ambient clock —
`crates/vike-ops/tests/clock_pin.rs`'s `CLOCK_PIN` keeps `SystemTime::now()` out of the library
tree, so `run` takes the timestamp as a parameter.

<Callout title="A clock set before the epoch answers with a negative second">
  Zero is a real instant, and a failure wearing a valid value is how a manifest starts lying about
  when a run happened. `now_unix_secs` returns the negative offset rather than `unwrap_or(0)`; do not
  "simplify" it.
</Callout>

## Getting data into the store first [#getting-data-into-the-store-first]

Three of the verbs exist so a fresh install has something to run.

`--seed-demo` writes the **synthetic** demo tape into the store and exits — venue `demo`, a
closed-form curve, explicitly *not* market data. It is the slice the shipped
`user_data/profiles/backtest.toml` names, so a fresh install can run that profile immediately, and
it is safe to re-run: a second seed writes nothing.

`--fetch VENUE:SYMBOL:INTERVAL` pulls **real public bars** into the store with no credentials
(`binance` is the only fetchable venue; any other spec is refused by name), bounded by `--days N`
counting back from now or by `--from`/`--to` taking epoch milliseconds or `YYYY-MM-DDTHH`.
Re-fetching the same window writes nothing. `--fetch-starter` downloads the published starter
dataset over plain HTTPS — no venue, no credentials, verified against its published `SHA256SUMS` —
for a box a venue cannot be reached from, a geoblock or a locked-down network. Both need the
`venue-fetch` feature; the release binary and the container image have it.

`--export VENUE:SYMBOL:INTERVAL --out FILE` writes one series from the store to a standalone
Parquet file, optionally bounded by `--from`/`--to`, for any venue the store holds — `demo`
included. It sits behind the same `venue-fetch` feature as the two fetch verbs.

## Sweeps and search [#sweeps-and-search]

A profile carrying a `[sweep]` table (`profile.is_sweep()`) runs `harness::run_sweep` instead of a
single `run_backtest`: the strategy runs once per point in the cartesian parameter grid, and the
result is a ranked `SweepReport` table rather than one `BacktestReport`.

* `--rank-by` picks the ranking metric, default `sharpe`, and is ignored — not an error — on a
  non-sweep profile. `--rank-by multi` ranks by the composite multi-metric objective instead, and
  rows gain a `score` column; the four classic metric names keep the original path and produce
  byte-identical output.
* `--search euler` replaces the exhaustive grid with a bounded successive-halving refinement
  (`harness::run_sweep_euler`): the coarse grid runs once, then the per-axis step is halved up to
  `--euler-depth` times (default 3, capped at 16) around the running best point. Each completed
  halving doubles the effective resolution for a fraction of the backtests an equally fine grid
  would cost — at the cost of being a **local** refinement (it can only descend into the basin the
  coarse grid already found) and of requiring every axis to be numeric and type-homogeneous. The
  stderr budget line compares against the grid matching the depth **actually reached**, so a search
  that ran out of candidates early reports the smaller, honest saving. `--search grid` is the
  default and is completely untouched.
* `--optimizer tpe` is the Bayesian tree-structured-Parzen-estimator ask/tell search
  (`harness::run_tpe`) — the alternative to enumerating the grid, converging in `--trials`
  backtests (default 64) by modelling which regions score well. `--seed` (default 0) makes it fully
  reproducible. It takes precedence over `--search` and reuses `--rank-by` as its objective.

See [sweeps](/docs/trader/backtesting/sweeps), [search](/docs/trader/backtesting/search) and
[objectives](/docs/trader/backtesting/objectives) for what each of those does.

## What a finished run leaves behind [#what-a-finished-run-leaves-behind]

A finished **single** run also persists: a `<run_id>` directory under `<project>/user_data/runs/`
gets `manifest.json` — the common, kind-agnostic manifest documented on
`vike_backtest::runs::RunManifest` — beside `report.json`, the same `BacktestReport` that `--json`
prints. Until this existed the bin saved nothing, so there was no history and nothing a UI could
list.

Persistence is **additive**: the report reaches stdout first, and a persist failure is reported on
stderr without changing the exit code, so saving a run can never become a way to lose one. `--json`
stdout is byte-identical to before.

<Callout type="warn" title="Only the single-run path persists">
  A sweep, a euler refinement and a `--optimizer tpe` run each answer with a `SweepReport` — a
  different document, and a run kind of its own rather than a backtest with extra rows — so they
  print exactly as before and write nothing.
</Callout>

Related: [running a backtest](/docs/trader/backtesting/running),
[run profiles](/docs/trader/backtesting/run-profiles), [runs on disk](/docs/trader/backtesting/runs-on-disk),
[the harness registry](/docs/trader/backtesting/harness-registry),
[the history store](/docs/trader/concepts/hist-store).


# collector_supervisor (/docs/trader/reference/binaries/collector-supervisor)



Every collector in [data providers](/docs/trader/data-providers) is a one-shot process: you invoke it,
it fetches a range, it exits. `collector_supervisor` is the long-running counterpart —
a declared roster of series, a cadence per source, and a per-pass gap heal, running forever.

Its module doc states what was missing before it existed. Gap **detection** already existed
(`vike_data::DataFusionHist`'s `series_gaps` derives a series' missing UTC days from its manifest
`date=` index, with no Parquet scan) and a coverage **dashboard** already existed (the
[Data Manager](/docs/trader/gui/data-manager)). What did not exist was anything that *runs on its own*:
the only in-repo scheduler was store maintenance — compaction and retention, not collection.
`crates/vike-backfill/src/supervisor/mod.rs` is that missing third leg; the binary is
`crates/vike-backfill/src/bin/collector_supervisor.rs`, behind the `venue-backfill` feature.

## It reimplements no collector [#it-reimplements-no-collector]

The first clause of the module's stated contract: every dispatch goes through the **same**
`backfill_*` function the matching one-shot bin calls
(`crates/vike-backfill/src/supervisor/run.rs`), so idempotency, paging and the
still-forming-candle guard are inherited verbatim — a supervised backfill and a hand-run one are
the same code path.

Wired today are the three keyless crypto kline collectors — binance, bybit and okx — the only
library entry points that already share one signature and need no credentials. That is the same
trio the Data Manager's bulk-backfill button offers; the supervisor is the unattended twin of that
button. A collector with a different arity needs a small adapter first, deliberately left out
rather than papered over with a lossy default mapping.

## Why the freshness window is anchored, not rolling [#why-the-freshness-window-is-anchored-not-rolling]

<Callout type="warn" title="The store dedups by batch key, never by row value">
  The commit key is `{venue}:{symbol}:{interval}:{start}-{end}`, and `commit_rows`'s own comment is
  that a batch key already committed is a no-op — *never* dedup by row value. A window whose both
  ends move with the clock mints a brand-new key every pass and re-appends the same bars forever.
  `crates/vike-backfill/src/supervisor/heal.rs` measures it: a 24 h lookback on a 5-minute cadence is
  roughly 288x row amplification.
</Callout>

So `heal.rs`'s `fresh_window` starts at the series' stored **watermark** — `max(now - lookback,
last_ts + step)` — and `lookback_ms` is only the outer bound for a cold or long-stalled series. A
healthy series fetches the sliver since its last stored bar and nothing else; when the watermark is
already at or past "now", no freshness job is planned at all. The planner, not the store, is what
keeps the supervisor from duplicating its own data.

Two more invariants live in the same module. &#x2A;*Heal work rotates.** A gap the venue genuinely has
no data for can never close: the fetch returns zero rows, `commit_rows` returns before recording
the key, and `series_gaps` re-reports the identical hole forever. Taking the oldest N ranges every
pass would re-attempt those same N holes and never reach hole N+1, so `plan_heal_jobs&#x60; walks the
gap set round-robin from a rotating cursor. And **`max_heal_jobs` bounds work, not range count**:
consecutive missing days collapse into one range, so a 300-day hole is a single range spanning
hundreds of paged REST calls. Every range is split into `HEAL_CHUNK_MS` sub-windows — seven days —
*before* the cap applies, which is what keeps a stop prompt.

Order is load-bearing: freshness first, heal after. An always-on collector's primary duty is that
"now" is present; healing 2019 must never delay today's bars.

## Failures, and the two lanes [#failures-and-the-two-lanes]

Nothing inside a pass can end the loop. A `series_gaps` failure degrades that symbol to
freshness-only, a backfill failure is recorded and the next symbol runs, and a status-write failure
is logged and ignored — in the resident loop; under `--once` that write error is propagated and the
run exits 2. Only the failure **count** changes behaviour, through
`crates/vike-backfill/src/supervisor/schedule.rs`'s `effective_interval_ms` — a bounded exponential
backoff of `cadence * 2^failures`, capped at `max_backoff_ms` — plus the optional `is_parked` hard
stop after `max_consecutive_failures`. A recovered source snaps straight back to its cadence.

Only the **freshness** lane feeds that. `crates/vike-backfill/src/supervisor/run.rs` explains why:
a source whose freshness fetch is healthy but whose historical heal window returns 429s must keep
collecting "now" at its configured cadence, or healing 2019 pushes today's bars out to the one-hour
backoff cap — exactly the priority inversion the ordering above exists to prevent. Heal-lane
failures increment a separate `heal_failures` counter that is published and changes no schedule.

The loop runs on the shared `vike_data::worker::Worker` harness — the same one the store's
maintenance scheduler uses: a condvar-interruptible inter-pass sleep, `stop()` as flag-then-join,
and a `Drop` that mirrors it. Sources are visited sequentially and a pass is never re-entered, so a
supervised backfill never races another; racing an unrelated live append is safe because every
store write serialises on the per-series manifest lock.

## Running it [#running-it]

```
collector_supervisor --config FILE.toml [--store DIR] [--status FILE] [--once]
```

`--config` is required and is a TOML roster of `[[source]]` tables — name, collector, symbols,
kind, interval, `cadence_secs`, `lookback_ms`, `heal`, `max_heal_jobs`, `max_backoff_secs`,
`max_consecutive_failures`. It is parsed with `deny_unknown_fields`, so a typo'd key is a hard
error rather than a silently ignored setting. There is deliberately **no** per-source `venue`
override: each collector writes under its own hard-coded venue, so an override would make the gap
lookup and the ingest target disagree.

`--store` resolves through the shared ladder in `crates/vike-backfill/src/cli.rs`'s `store_root`,
with one wrinkle worth knowing: the config's `store =` line is folded into that function's
*explicit* argument before the ladder is entered, so it outranks `$VIKE_HIST_STORE` rather than
sitting below it. Beneath the flag and that line the rungs are `$VIKE_HIST_STORE`, a project named
outright by `$VIKE_SETTINGS_DIR`, the repo-root `<repo>/market_data/hist` on a box that still has
that checkout, the project's own `<project>/market_data/hist`, and finally the per-user data
directory.

`--status` publishes a JSON document carrying
last-run / next-run / heal-queue / last-error per source, rewritten after every pass by
serialise → write `.tmp` → rename, so a reader always sees a complete document. It is deliberately
a plain file rather than a socket: no new transport, no port to secure, and `cat`/`jq` can read it
while the loop runs. A status write failure never stops the resident loop — it is logged and
collecting goes on; under `--once` it is fatal and exits 2.

`--once` runs a single pass and exits, for a cron or timer deployment. The resident mode stops on
EOF on stdin or the word `quit`, finishing the in-flight pass first; nothing is lost either way,
because every store write is already committed and idempotent by the time a pass returns.

Set `VIKE_LOG_FILE_LEVEL` for any long run — see [log volume](/docs/trader/data-providers/log-volume).


# incident (/docs/trader/reference/binaries/incident)



A live node's forensic trail is scattered across stores that overwrite themselves. The write-ahead
command journal is mmap segments that **prune**. The JSON trace log **rolls** daily and can be
size-capped. The resolved run profile is a file somebody can edit between runs. The process
environment is gone the instant the process exits. When something goes wrong at 03:00 the operator
needs a single artifact that pins all of it to the moment of the incident, before any of it rots.

`incident` is that artifact's collector. The binary is
`crates/vike-run/src/bin/incident.rs`; the collection itself is `crates/vike-run/src/incident.rs`'s
`run_incident`. It is feature-free — no venue or native dependencies — so it builds in the default
lane like any ordinary target.

```sh
incident --since 2h
incident --since 30m --out /var/vike/incidents
incident --since 1d --journal-dir data/journal --profile run.toml
```

`--since` is the one required flag and takes a Vike interval — `30s`, `15m`, `2h`, `1d`. A
malformed value is an error, not a zero-length window: an empty bundle would read as "there was no
evidence". `vike-run incident …` also works — one leading `incident` token is accepted and dropped,
a second is not. The bundle's directory path is printed on stdout.

## What it collects [#what-it-collects]

Into `incident-<UTC>/`:

* the **journal segment** files whose last write overlaps the window, gzipped;
* the **trace-log** files from the resolved log directory whose last write overlaps the window,
  gzipped;
* the resolved &#x2A;*`RunProfile`** TOML plus its FNV-1a64 hash, so a later edit to that file is
  detectable;
* the latest &#x2A;*`EngineSnapshot`** and its `state_hash`, taken from the journal's last `Snap`;
* git SHA and build info;
* a **redacted** dump of the process environment.

Selection is `select_overlapping`: a file is in when its last write is at or after `now - since`,
with the subtraction saturating so a huge window cannot overflow.

The archive is per-file gzip in a directory alongside a plain `manifest.json` rather than one
`.tar.gz`. The module doc is explicit that this is a deliberate fallback — a single tarball needs a
`tar` crate the crate cannot compile-check in its current build lane — and that bundling the
directory afterwards is a trivial follow-up.

<Callout title="Safe to run against a live node">
  `incident` is a read-only collector. It opens the journal through
  `vike_core::journal::CommandJournal`'s `read_all` — the lock-free entry point the journal module
  blesses for offline inspection tooling — never the writer. Nothing in the mount path calls it, the
  live core is untouched, and no existing struct gains a field for it.
</Callout>

## Redaction [#redaction]

The environment dump is masked exactly the way the signers' manual `Debug` implementations mask
their secrets (`crates/vike-bridge-core/src/signer.rs`): `redact_secret_value` returns `***`
followed by the last four characters, and nothing else. A value shorter than four characters gets
the bare mask.

Which keys get masked is `is_secret_key`, and its doc states the bias: a generous, case-insensitive
substring match, because over-redaction is safe — it costs an operator a non-secret flag — while a
miss leaks a credential. It covers every credential shape the workspace uses (`*_API_KEY`,
`*_API_SECRET`, `*_API_PASSPHRASE`, `*_PRIVATE_KEY`, the Polymarket `PK` family) plus tokens,
mnemonics, seeds and signatures. Most `VIKE_*` runtime flags carry none of those needles and pass
through verbatim. The ones whose names do are masked: the genuine secrets
(`VIKE_TRADEHUB_CONTROL_KEY`, `VIKE_TELEGRAM_BOT_TOKEN` and their family) as intended, and
`VIKE_ALLOW_WITHDRAW_KEYS` — an ordinary flag whose `_KEYS` suffix trips the `_KEY` needle — as
over-redaction, which is the safe direction. `build_manifest` redacts internally, so the artifact
is safe to share by construction.

## Where the sources come from, and where the bundle lands [#where-the-sources-come-from-and-where-the-bundle-lands]

Every source is resolved the way a live node resolves it, never re-derived:

* **profile** — `--profile`, else `VIKE_RUN_PROFILE`, through
  `vike_core::run_profile`'s `resolve_profile_path`, so this bin cannot silently diverge from the
  resolver the node uses;
* **journal directory** — `--journal-dir`, else `VIKE_JOURNAL_DIR`, else the loaded profile's
  journal sink;
* **log directory** — the same four-layer precedence `vike_log::resolve_log_dir` gives a node
  (`VIKE_LOG_DIR`, then the flag, then the project's own `settings/state/logs`, then `<exe_dir>`).
  Before the project layer existed this resolved to `<exe_dir>/logs` and would now miss every log
  the collector was built to freeze;
* **output** — `--out`, else the project's `settings/state/incidents`, else `<exe_dir>`.

<Callout type="warn" title="The bundle is not scratch">
  The output default is deliberately not a temporary directory. A bundle is frozen post-mortem
  evidence — written precisely so it can be read after the thing that produced it is gone — so an
  owned scratch directory that deletes on drop, or a swept root that prunes to a bounded newest-N,
  would each destroy the only artifact this binary exists to make. It used to default to a fixed name
  under the system temp directory, which failed twice over: inside a container that directory is not
  the host's and does not survive a restart, and on a shared box whoever created it first owned it
  permanently.
</Callout>

File logging is switched off for this process, so the collector never writes into the very log
directory it is about to freeze.

## The parser rules worth knowing [#the-parser-rules-worth-knowing]

A valued flag must be *given* a value, and a token beginning with `--` is a flag, never a value.
That rule closed a real defect: `--out --profile` used to parse cleanly and write the post-mortem
bundle into a directory literally named `--profile`. A collector whose evidence lands somewhere
nobody looks is the same as no collector. It is `--` and not a bare `-`, so a negative number stays
a legal value.

`-h`/`--help` exits **0** to stdout — it used to exit 1, which breaks `set -e` and any wrapper that
checks a status. A `--help` in a *value* slot (`--out --help`) is still refused as a swallow,
because succeeding there would silently discard the `--out` the operator typed. A repeated flag
takes the last value, silently.

See [the command journal](/docs/trader/concepts/journal) for what the segments contain, and
[replay-journal](/docs/trader/reference/binaries/replay-journal) for replaying them deterministically
afterwards.


# Binaries (/docs/trader/reference/binaries)




Every binary target the workspace declares — **46** across 17 crates —
derived from `cargo metadata` at release time (xtask's `docs-bins` verb renders `bins.json`)
and classified here by name. Nothing is unlisted and the list cannot rot: a new `[[bin]]` fails
this page's generator until somebody says what it is. Each entry links to its own page, to the
collector family under [data providers](/docs/trader/data-providers) that documents it, or to where it
is covered elsewhere; the rest are internal harnesses — built and tested, not an operator's tool.

A bin marked "requires" is behind a cargo feature: a default build of its crate does not contain it,
and the [release](/docs/trader/reference) ships only the configurations its workflow names.

### `vike-agent-eval` [#vike-agent-eval]

* `vike-agent-eval` — the evaluation harness that grades the shipped agent surface
* [`vike-agent-run`](/docs/ai/trader/unattended) — one unattended agent session against your own node, read-only by default, leaving a record

### `vike-backend` [#vike-backend]

* [`vike-backend`](/docs/trader/concepts/architecture) — the multicall dispatcher: one binary that answers to every tool name, and depends on them all

### `vike-backfill` [#vike-backfill]

* `aster_backfill` — a collector; see [venue-direct](/docs/trader/data-providers/venue-direct) — requires `venue-backfill`
* `binance_backfill` — a collector; see [venue-direct](/docs/trader/data-providers/venue-direct) — requires `venue-backfill`
* `bybit_backfill` — a collector; see [venue-direct](/docs/trader/data-providers/venue-direct) — requires `venue-backfill`
* [`collector_supervisor`](/docs/trader/reference/binaries/collector-supervisor) — supervises the collectors — requires `venue-backfill`
* `databento_backfill` — a collector; see [databento](/docs/trader/data-providers/databento) — requires `databento`
* `deribit_backfill` — a collector; see [venue-direct](/docs/trader/data-providers/venue-direct) — requires `venue-backfill`
* `dukascopy_backfill` — a collector; see [venue-direct](/docs/trader/data-providers/venue-direct) — requires `venue-backfill`
* `eod_backfill` — a collector; see [eod-and-events](/docs/trader/data-providers/eod-and-events)
* `events_api_backfill` — a collector; see [eod-and-events](/docs/trader/data-providers/eod-and-events) — requires `vike-archive`
* `exec_trade_backfill` — a collector; see [eod-and-events](/docs/trader/data-providers/eod-and-events)
* `funding_rate_backfill` — a collector; see [funding-rates](/docs/trader/data-providers/funding-rates) — requires `venue-backfill`
* `hyperliquid_backfill` — a collector; see [venue-direct](/docs/trader/data-providers/venue-direct) — requires `venue-backfill`
* `hyperliquid_funding_backfill` — a collector; see [funding-rates](/docs/trader/data-providers/funding-rates) — requires `venue-backfill`
* `ibkr_backfill` — a collector; see [ibkr-historical](/docs/trader/data-providers/ibkr-historical) — requires `ibkr`
* `ingest_bench_bars` — a collector; see [store-maintenance](/docs/trader/data-providers/store-maintenance)
* `migrate_to_group` — a collector; see [store-maintenance](/docs/trader/data-providers/store-maintenance)
* `okx_backfill` — a collector; see [venue-direct](/docs/trader/data-providers/venue-direct) — requires `venue-backfill`
* `pmxt_backfill` — a collector; see [polymarket](/docs/trader/data-providers/polymarket)
* `poly_reparse` — a collector; see [polymarket](/docs/trader/data-providers/polymarket) — requires `poly-reparse`
* `tardis_backfill` — a collector; see [tardis](/docs/trader/data-providers/tardis) — requires `tardis`
* `vike_archive_backfill` — a collector; see [vike-data-api](/docs/trader/data-providers/vike-data-api) — requires `vike-archive`
* `vikedata_backfill` — a collector; see [vike-data-api](/docs/trader/data-providers/vike-data-api) — requires `vikedata`

### `vike-backtest` [#vike-backtest]

* [`backtest`](/docs/trader/reference/binaries/backtest) — the standalone backtest runner — requires `datafusion-store`
* `cheap_np_askgate` — a research harness (the cheap-NP study) — requires `datafusion-store`
* `cheap_np_depth` — a research harness (the cheap-NP study) — requires `datafusion-store`
* `cheap_np_run` — a research harness (the cheap-NP study) — requires `datafusion-store`
* `sport_taker_run` — a research harness (the sport-taker study) — requires `strategies`

### `vike-cli` [#vike-cli]

* [`vike-cli`](/docs/trader/reference/cli) — the command-line interface — every verb under reference/cli

### `vike-core` [#vike-core]

* [`replay_journal`](/docs/trader/reference/binaries/replay-journal) — deterministic journal replay
* [`vike_stat`](/docs/trader/reference/binaries/vike-stat) — read-only health counters

### `vike-ctrader` [#vike-ctrader]

* [`ctrader_authorize`](/docs/trader/reference/binaries/venue-setup-tools) — cTrader OAuth authorisation

### `vike-datahub` [#vike-datahub]

* [`vike-datahub`](/docs/trader/reference/binaries/vike-datahub) — the backtest and data service

### `vike-desktop` [#vike-desktop]

* [`vike-desktop`](/docs/trader/reference/binaries/vike-desktop) — the desktop app — one build, no local core

### `vike-dukascopy` [#vike-dukascopy]

* `fake_jforex_bridge` — the test double for the Dukascopy JForex sidecar

### `vike-hyperliquid` [#vike-hyperliquid]

* [`hyperliquid_builder_fee_approve`](/docs/trader/reference/binaries/venue-setup-tools) — Hyperliquid builder-fee approval — requires `builder-fee-approve`

### `vike-ops` [#vike-ops]

* `docs_data` — the docs-data exporter that rendered this site's venue, indicator and strategy tables — requires `docs-data`

### `vike-report` [#vike-report]

* [`tearsheet`](/docs/trader/reference/binaries/tearsheet) — the HTML report generator — requires `journal`

### `vike-run` [#vike-run]

* [`ibkr_mount`](/docs/trader/reference/binaries/mount-bins) — a real IBKR mount, not paper — requires `ibkr`
* [`incident`](/docs/trader/reference/binaries/incident) — the incident tool
* [`polymarket_maker_paper`](/docs/trader/reference/binaries/mount-bins) — a Polymarket paper maker mount — requires `polymarket`

### `vike-studio-core` [#vike-studio-core]

* [`vike-study`](/docs/trader/reference/binaries/vike-study) — the study runner that can fit — requires `study-cli`

### `vike-tradehub` [#vike-tradehub]

* [`vike-tradehub`](/docs/trader/reference/binaries/vike-tradehub) — the unattended live daemon

### `xtask` [#xtask]

* `xtask` — the workspace's build tooling (derives the CI roster; renders bins.json)

## Where this comes from [#where-this-comes-from]

`bins.json`: every target whose kind is exactly `bin` on a workspace member, from
`cargo metadata --format-version 1`, sorted by crate and name (`xtask/src/docs_bins.rs`).
Workspace-excluded crates are not members and appear nowhere: no lane builds them and they ship
nothing.


# Mount binaries (/docs/trader/reference/binaries/mount-bins)



`vike-run` carries two runnable mounts, each behind a `required-features` gate, so a default build
of the crate contains neither. They look alike from the outside and are opposite in the one way
that matters: one of them cannot place a real order, and the other exists to.

## `polymarket_maker_paper` — a live feed, a paper book [#polymarket_maker_paper--a-live-feed-a-paper-book]

Behind the `polymarket` feature. `crates/vike-run/src/bin/polymarket_maker_paper.rs` mounts the
Avellaneda–Stoikov maker on a **real** Polymarket market: the strategy quotes and trades off the
live tick feed, and every fill lands in the paper exchange. No credentials, no signing, no money.

It picks a market three ways — `--auto` (universe selection: the most-liquid tradeable market, no
name needed, with `--min-liquidity` as the floor), `--query` by name through the Gamma catalog, or
`--token-id` for an exact outcome token. The market's `end_date` becomes the A-S `resolution_ts`.
It then builds a `vike_mm::SpreadMaker` and mounts it on the **production** live core through
`vike_core::spawn_core`, with the paper exchange as the `ExecutionClient` and the real
`vike_polymarket::Feeds` as the tick source. The module header states the property that makes this
worth having: it is an identical mount to the offline scripted test, and only the feed differs.

That is enforced by sharing one builder. `vike_run::build_paper_maker_core` puts
`PaperExecutionClient` behind the `ExecutionClient` seam and the maker behind a `StrategyMount` on
`spawn_core`, and it is deliberately feature-free — no venue code — so the live binary and the
offline test use it verbatim, differing only in what feeds the returned handle. Its default options
are documented as today's plain-path values: `RiskLimits::new()` (explicitly *not*
`RiskLimits::default()`, which differs), every other knob off, and the halt sentinel at
process-wide — the **armed** default, because the alternative silently disarms an operator's kill
switch on the shipped paper daemon. See [halt](/docs/trader/concepts/halt) and
[the paper exchange](/docs/trader/concepts/paper-exchange).

It logs position, working quotes, paper fills and realized PnL every few seconds, then flushes the
last synthesised bar and shuts the core down cleanly.

<Callout type="warn" title="Polymarket is geo-blocked from the US">
  The Polymarket CLOB — the Gamma catalog read and the market WS alike — is geo-blocked from the US,
  so this binary must run on, or egress through, an EU host, the same route the catalog and the live
  market smokes use. No API keys are needed: the market channel is public and unauthenticated, and
  the mount is paper, so it never signs or sends an order. A US machine can still compile and run the
  offline test; only the live path needs the route. See
  [Polymarket operations](/docs/trader/venues/polymarket-operations).
</Callout>

Every research knob is opt-in and inert by default, and the defaults are chosen so an unset flag
gives a byte-identical mount: reward-aware quoting (`--reward-weight`, else `POLY_REWARD_WEIGHT`,
else `0.0` — off; see [liquidity rewards](/docs/trader/market-making/liquidity-rewards)); the
cross-symbol underlying anchor (`--underlying`, with `--underlying-weight`, `--window-secs` and
`--atm-blackout-scale`, all inert without it); and the flow-toxicity guard (`--toxicity`, with
`--tox-widen`, `--tox-size-cut`, `--tox-window-secs` and a `--wallet-classes` JSON map — an absent
map means every wallet is unknown, never toxic, guard inert).

One direction of failure is worth knowing: an unparseable `POLY_REWARD_WEIGHT` degrades **silently**
to `0.0`, so a decimal comma turns reward-aware quoting off rather than on, with no diagnostic —
and `0.0` is also what an absent variable means, so the two are indistinguishable.

## `ibkr_mount` — a real mount, not paper [#ibkr_mount--a-real-mount-not-paper]

Behind the `ibkr` feature. `crates/vike-run/src/bin/ibkr_mount.rs` is a headless Interactive
Brokers mount: it loads `IBKR_{DEMO|LIVE}_*` config, connects the chosen backend as a &#x2A;*real
out-of-process `ExecutionClient`**, wires its venue events into a `vike-core` runtime, and drives
place and cancel from stdin.

```
usage: ibkr_mount --env demo|live [--backend socket|cpapi] [--sub SYM@INTERVAL ...]
```

The two backends are the bridge's umbrella feature: `socket` is the vendored blocking client
speaking the TWS wire protocol to a Gateway, `cpapi` is REST and WS to a browser-authenticated
Client Portal Gateway. Both implement one transport seam and share one exec loop and one mapper,
so they can only diverge inside the transport.

<Callout type="warn" title="`--env live` is a live account">
  The parser defaults to **demo**, and its own test calls that the parser's safety property: this
  binary connects a real execution client and drives place and cancel from stdin, so a forgotten or
  mistyped `--env` must never resolve to a live account. `--env` accepts exactly `demo`, `paper` and
  `live` and refuses everything else — including `LIVE` in the wrong case, which is the shape a typo
  actually takes. `--sub` is repeatable and order-preserving; the last `--backend` wins, silently.
</Callout>

The mount pattern mirrors the desktop app's, and the header explains why it has to: the live client
cannot be handed the core's event sender, because the core does not exist until `spawn_core` and
the client is moved into the engine. So the binary builds a standalone event lane, connects the
client against it, spawns the core, and runs a forwarder thread relaying that lane into the core's
sender. Orders go through the core's command lane, never by holding the client.

Market data is separate and optional: `--sub SYM@INTERVAL` subscribes IBKR bars and trades into the
core's data lanes through a `vike_core::CoreLaneSink`, over IBKR's own connection with a distinct
client id, and that connection is opened only when at least one `--sub` was given.

The stuck-order watchdog is armed here at 30 seconds, matching the desktop app's live mount, and
the comment on that field argues it is not a nice-to-have: the bridge's own event mapper ends its
unroutable-reject arm "relying on submit-ack watchdog", and its rejection code table is a
six-code allowlist — so an IB rejection carrying any other code, or an id-less one arriving while
two orders are unacked, emits no terminal at all. Without the timeout an order IBKR had already
refused sat submitted forever. See [the watchdog](/docs/trader/concepts/watchdog) and
[IBKR](/docs/trader/venues/ibkr).

Once up, the binary prints its account and backend and accepts `buy SYM QTY [PX]`,
`sell SYM QTY [PX]`, `cancel COID`, `status` and `quit`; an order with no price is a market order.
On exit it shuts down every subscription pump and joins the core.


# replay-journal (/docs/trader/reference/binaries/replay-journal)



"Send me your journal": `replay_journal` deterministically replays a journal directory and verifies
its determinism fence. The fence verifies **exec-lane determinism** — that re-folding the journaled
exec lane from the first checkpoint reproduces the recorded final order and account state
(`crates/vike-core/src/bin/replay_journal.rs`).

```
replay_journal <journal-dir>
```

Called with no argument it prints `usage: replay_journal <journal-dir>` and exits 2. On success it
prints the source journal's total record count, how many snapshots were verified, the final state
hash, and one line per engine giving its venue, symbol, open-order count, position count and
balance. On failure it prints `REPLAY FAILED` with the error and exits 1. Protocol and result
output stays raw on stdout — the repo's logging rule for tools.

## The mechanism [#the-mechanism]

The bin is a thin wrapper around `vike_core::replay::replay_offline`, and the interesting part is
where the replay starts.

1. **Restore the engine from the journal's first `Snap`** — the earliest full-config checkpoint.
   Restoring from the *latest* would leave nothing to replay on a clean run, because its exit
   snapshot already reflects everything: a worthless fence. Cadence snapshots are taken after the
   fold, so every command before the first snapshot is already folded into it and every command
   after it is re-folded forward, re-deriving the whole post-checkpoint history.
2. **Spawn a real core from that engine** with a pure no-op `ReplayClient` — venue side effects
   suppressed, because the original venue events are already journaled and get re-pumped, and a
   client that *also* emitted events would double the state — a `QueueClock` replaying the tail's
   recorded `now_ms` so timestamp-derived state matches, the base snapshot's client-order-id
   session, and a temp journal configured so only the exit snapshot fires.
3. **Pump every post-base command through the handle in order**, shut down, join.
4. **Fence**: read the replay journal's final snapshot and require its hash to equal the *source*
   journal's last snapshot hash.

<Callout title="Why the fence is a final hash and not a per-record comparison">
  The replay core's temporary sequence numbers differ from the source's, so per-sequence comparison
  is impossible. Final-hash equality is the essential guarantee: re-folding from the first checkpoint
  reproduces the exact final state.
</Callout>

This both gates the journal format — any nondeterminism in the fold surfaces as a mismatch — and is
the substrate the crash-restart path builds on. That second entry point,
`vike_core::replay::restore_from_journal`, shares the same engine but restores from the **latest**
snapshot, re-folds only the (usually empty) crash tail, and returns the reproduced engines and
session with **no** fence: it is a restore, not a proof.

## What replays, and what does not [#what-replays-and-what-does-not]

A mounted strategy reacts to non-journaled bar and tick messages, but its **order flow** does not:
each already-resolved `OrderIntent` is journaled write-ahead as `JournalRecord::StrategySubmit`,
with mint and tag resolution already done, and the tail replays it exactly like a command. Replay
never re-runs the strategy's hooks — the replay core mounts no strategy — so it does not matter
that the triggering ticks are absent; only the strategy's already-decided orders need to reproduce.

[Emulated conditional](/docs/trader/concepts/emulated-orders) **fires** replay the same way: the
decision is journaled write-ahead as `JournalRecord::ConditionalFire` (arm id plus the released
order request) and re-applied through the same submit site, never re-evaluating a trigger, so a
fire can neither double nor vanish. **Disarms** ride an ordinary write-ahead command carrying the
complete arm id. Identity is what makes that sound: the replay core's arm counter is seeded from
the base snapshot's stamped `arm_seq`, so tail arms re-mint the identical ids the live core minted
and a tail disarm finds its arm.

Armed conditionals also survive a restart. The resting books ride every snapshot — each arm's
minted id plus the terms the book held, **including a trailing arm's current ratcheted extreme**,
the one value neither the write-ahead arm command nor the seed record can carry, because it moves
on non-journaled market data. Crash-tail membership is a pure fold of the journal's conditional
records (`fold_conditionals`), never the replay core's own book state: that core pumps no market
data, so a fired arm would linger in it and a trailing arm would be refused for lack of a mark —
the fold gets both right from the records.

<Callout type="warn" title="Two shapes are refused rather than guessed">
  Replay is **single-engine only**: a multi-engine base returns `ReplayError::Unsupported`, because
  per-engine `seed_cash` is not part of `EngineSnapshot` and a faithful multi-engine restore is
  deferred. A watchdog-tick tail is `Unsupported` too — the stuck-order and dead-man wall-clock
  sweeps it carries are not deterministic functions of the journal.
</Callout>

Related: [the command journal](/docs/trader/concepts/journal), [replay](/docs/trader/concepts/journal/replay),
[segments](/docs/trader/concepts/journal/segments), [locking](/docs/trader/concepts/journal/locking),
[replay a recorded session](/docs/trader/guides/replay-a-session),
[the execution core](/docs/trader/concepts/execution-core).


# tearsheet (/docs/trader/reference/binaries/tearsheet)



`tearsheet` reads a **live** command journal and turns its fill stream into the same tearsheet a
backtest produces. It is not a backtest reader: the input is the journal a running paper or live
session wrote, and the output is that session's performance
(`crates/vike-report/src/lib.rs`).

```
usage: tearsheet --journal DIR [--seed CASH] [--name LABEL] [--periods-per-year N] [--json]
                 [--html PATH] [--store DIR [--venue V] [--interval STR]]
```

`--journal DIR` is required, or `$VIKE_JOURNAL_DIR` — the same variable that turns journaling on in
the producing binary, so you point the reader at exactly what you enabled. Without it the tool
exits 2 with the usage line. That printed line omits `--mtm`, which is nonetheless a real flag
whenever `--store` is present (`crates/vike-report/src/tearsheet_cli.rs`'s `run`) — described
below.

## The parity contract [#the-parity-contract]

Every closed-trade round-trip is reconstructed through `vike_model::compute_fill` — the **one**
cost-basis primitive that `vike_exec::Account::fold` and `vike_backtest`'s `SimBroker::apply_fill`
both delegate to — and every performance number is a call into `vike_analytics::metrics`. &#x2A;*No
metric is reimplemented here.** So a live tearsheet and a backtest tearsheet over the same fill
sequence are computed bit-for-bit identically.

<Callout title="The analytics edge is deliberately vike-analytics, not vike-backtest">
  Those modules used to live in `vike-backtest`, so reusing them meant compiling 32,259 lines to
  reach \~3,900: the simulator, the paper exchange and the whole gated harness tree came along, and
  89% of what this crate built it could never call. `vike-analytics` depends on `vike-model` alone,
  so the catalog now arrives without the machine that produced it. The numbers are the same
  functions; only their home changed.
</Callout>

## Flags [#flags]

`--seed` is the account's starting capital, default 10000. It sets the base of the realized-only
equity curve, so it scales `total_return`, `cagr` and `sharpe` — pass the session's real starting
equity for accurate returns. `--name` labels the sheet. `--periods-per-year` is the
Sharpe/Sortino/Calmar/CAGR annualization factor, default 252 (`report::DAILY_PERIODS_PER_YEAR`);
note the equity curve here is realized-per-trade rather than a fixed calendar cadence, so
annualized ratios are approximate.

`--json` prints the `LiveTearsheet` as pretty JSON instead of the human table. `--html PATH`
**additionally** writes the self-contained HTML tearsheet through `crate::render_html` — a metrics
table, inline-SVG equity and underwater-drawdown charts, and a monthly-returns table when
timestamps allow — leaving the terminal output unchanged.

## Store enrichment [#store-enrichment]

`--store DIR` points at a `vike-data` DataFusion + Parquet hist store root, and needs the crate's
`hist` feature. Given both, two enrichments replace the bare realized-only sheet.

First, the equity curve is read from the store's `kind=equity` series
(`crate::equity_curve_from_store`) — a true mark-to-market curve. The equity sampler persists the
cross-venue **account** rollup under `venue="portfolio"`, `symbol="TOTAL"` (per-exchange rows use
`symbol=<exchange>`), and that whole-account curve is what the tearsheet reads; it falls back to
the realized-only curve, with a note on stderr, when no such series exists. Second, each
reconstructed trade's MAE and MFE is back-filled from the store's OHLC bars over the trade window
(`crate::backfill_excursions`).

`--interval` is the bar series interval used for the excursion back-fill, default `1m`. `--venue`
names the trades' venue for those bar lookups — the `Trade` type drops venue — and when omitted it
is derived from the journal's fills if they all share one; otherwise `--venue` is required. The
equity-curve lookup does **not** use it, because that series is the `portfolio`/`TOTAL` rollup
rather than a per-venue one.

<Callout type="warn" title="--store errors without the hist feature">
  Built without `--features hist`, passing `--store` exits 2: the DataFusion backend is not compiled
  in. That is a build question, not a store question, and the message says so rather than reporting a
  missing series.
</Callout>

`--mtm` (which requires `--store`) swaps the equity source: instead of the sampler's `kind=equity`
series, the curve is **reconstructed** from the journal fills marked to market against the store's
`(--venue, --interval)` bars (`crate::mtm_curve_from_store`) — the sampler stays the default. It
additionally renders a "Runtime exposure" section into the `--html` output — turnover, gross and
net exposure, peak margin (`crate::RuntimeStats`). Without `--store` it is a no-op, and on the
default path everything is byte-identical to before the flag existed.

## Where the numbers come from [#where-the-numbers-come-from]

The report side of this crate is a small set of pure steps, each its own module:
`journal_read::fills_from_journal` reads the journal's fill records, `trades::reconstruct_trades`
folds them into closed round-trips through the shared cost-basis primitive, `equity` builds the
curve from samples, the store or the trades themselves, `mtm` adds the positions-over-time fold
marked against store prices, and `html::render_html` renders. Nothing in the `mtm` path is
persisted: the live `kind=equity` sampler stays the primary source.

The bin is a thin shim over `vike_report::tearsheet_cli::run`, which takes both argv **and** the
environment as parameters — taking `VIKE_JOURNAL_DIR` from a caller-supplied map rather than
`std::env::var` is what moves its settings-registry row from `Layer::Binary` to `Layer::Injected`,
the registry's own declared target state.

Related: [the command journal](/docs/trader/concepts/journal),
[reading the journal](/docs/trader/concepts/journal/reading),
[the report](/docs/trader/analytics/report), [metrics](/docs/trader/analytics/metrics),
[excursions](/docs/trader/analytics/excursions), [read a backtest report](/docs/trader/guides/read-a-report).


# Venue setup tools (/docs/trader/reference/binaries/venue-setup-tools)



Two binaries in this workspace are neither daemons nor front ends: they are one-off setup steps a
human runs once against a venue, and then never again. Both are deliberately separate from the
mount path — nothing in the live execution path invokes either.

## `ctrader_authorize` — the OAuth catcher [#ctrader_authorize--the-oauth-catcher]

cTrader's Open API is OAuth2, which normally means copying a `?code=` out of a browser address bar
and pasting it into a shell. `crates/bridges/ctrader/src/bin/ctrader_authorize.rs` removes that
round trip. It starts a plain HTTP server on `http://localhost:5033/`, prints the authorize URL,
blocks for the browser's redirect, exchanges the code for a `vike_ctrader::oauth::Token` **in the
same process**, prints the token redacted, and writes it to
`<project>/settings/state/ctrader_token.json` in the venue's own camelCase wire shape.

Its inputs come from the environment and never from argv: `CTRADER_CLIENT_ID` and
`CTRADER_CLIENT_SECRET` are required; `CTRADER_REDIRECT_URI` defaults to the localhost address
above and `CTRADER_SCOPE` to `trading`. Output is raw `println!` rather than tracing — the
workspace convention for a tool whose stdout is a result.

The file it writes holds a live access **and** refresh token, and the module header records what
changed after that was noticed. It used to be written as `token.json` in the process working
directory with no resolver at all, so a live credential landed wherever the binary happened to be
started from — frequently a world-readable directory on a server. Now the path resolves
`$CTRADER_TOKEN_FILE` → `<project>/settings/state/ctrader_token.json` → `./token.json`, and it is
written owner-only (0600) on unix on **every** rung, including the working-directory fallback. The
token's value is never printed or logged, only a redacted head and tail, and the tool never reads,
moves or deletes a pre-existing `token.json`: a box that has one keeps it, untouched and unread.

<Callout type="warn" title="The JSON file is read by nothing — copy the pair into the credential store">
  Nothing in the tree reads that file. The grant lives in
  `<project>/settings/secrets.env` on `CTRADER_{TIER}_ACCESS_TOKEN` and `_REFRESH_TOKEN`, and nowhere
  else — it is a credential, so it lives where credentials live, and there is deliberately no second
  source of truth to rank against it. `settings/state/ctrader_token.json` is this binary's own output
  record and stays that. **After an authorize run you copy the pair into `secrets.env` yourself**,
  and that hand-copy is now the only manual step in the loop.
</Callout>

Everything after that copy is automatic. A refresh is persisted back through the byte-preserving
upsert that replaces exactly those two keys and leaves every comment, blank line and unrelated key
verbatim — and both keys move together, because cTrader rotates the refresh token on every refresh.
An expired grant self-heals at startup by spending the refresh token once and retrying the
handshake; a healthy daemon refreshes ahead of the lapse on its heartbeat tick. See
[cTrader](/docs/trader/venues/ctrader).

## `hyperliquid_builder_fee_approve` — the builder-fee grant [#hyperliquid_builder_fee_approve--the-builder-fee-grant]

Hyperliquid lets an order carry a builder's code, and separately lets that builder charge a fee.
The fee needs a standing on-chain grant first, and
`crates/bridges/hyperliquid/src/bin/hyperliquid_builder_fee_approve.rs` is the one-time tool that
makes it. It is gated behind the `builder-fee-approve` feature: never built by default, never
invoked from the live exec or mount path.

Its arguments are a builder address and a maximum fee rate, plus an optional `--mainnet`.
`<max_fee_rate>` is Hyperliquid's percentage-string shape, e.g. `"0.01%"`. The private key comes
from `HYPERLIQUID_{DEMO,LIVE}_PRIVATE_KEY` in the credential store — never argv, never logs.
`--mainnet` selects the `LIVE` tier and real funds; its absence selects `DEMO` and testnet.

`crates/bridges/hyperliquid/src/builder_fee.rs` states the two things worth carrying before you run
it. It is a **standing grant**, not a per-order action: run it once per `(account, builder, rate)`
tuple, not on every submit. And **attribution-only mounts never need it at all** — a builder fee of
zero, which is this workspace's default and is resolved at mount time, requires no prior approval,
because Hyperliquid only gates a *nonzero* fee.

<Callout type="warn" title="Master wallet only, and the grant is not live-verified">
  Unlike other user-signed actions, Hyperliquid requires the grant to come from the master account's
  own key: an agent wallet is approved *for* builder-coded orders, it cannot approve a builder's fee
  on the account's behalf. Passing an agent key signs a well-formed but venue-rejected request — or
  worse, silently approves nothing, since the recovered signer address will not match the account.
  The binary therefore refuses to run when `HYPERLIQUID_{tier}_ACCOUNT_ADDRESS` is set, because that
  shape means the loaded key is an agent or API wallet.

  The module also declares itself **unverified live**: the signing path is faithful to the venue's
  own SDK, but it has no golden vector and has not been round-tripped against the venue. Its tests
  prove the wire shape and field order, and that the produced signature recovers the signer's own
  address. They do not prove the venue accepts it, and a real testnet round trip is owed before
  trusting it with a live grant.
</Callout>

See [Hyperliquid](/docs/trader/venues/hyperliquid) for the attribution row itself, and
[environment variables](/docs/trader/reference/environment) for where the credential keys are read.


# vike-datahub (/docs/trader/reference/binaries/vike-datahub)



A headless, **compute-to-data** backtest server. A client sends a small
`vike_backtest::harness::BacktestProfile` config over a TCP socket; the server runs the existing
`vike-backtest` engine right next to the data and returns just the
`vike_backtest::harness::BacktestReport` answer. The heavy history never crosses the wire — only
the profile in and the metrics summary out. The crate owns no engine of its own: it is assembly of
`vike-backtest` for the engine, config and report, and `vike-data` for the store seam
(`crates/vike-datahub/src/lib.rs`).

```
usage: vike-datahub

The headless compute-to-data backtest server. It takes no options: the listen address and the
hist-store root come from the environment.

  -h, --help      print this and exit 0
  -V, --version   print the version and exit 0
```

## Transport and backends [#transport-and-backends]

Blocking `std::net` — `TcpListener`/`TcpStream`, thread-per-connection — with length-prefixed
`serde_json` frames from `vike_datahub_client::proto`. There is no async runtime and no second
HTTP/RPC/WS stack: the workspace `deny.toml` bans one, and this stays inside bare `std::net` plus
`serde_json`. The server holds the store as `Arc<dyn HistStore + Send + Sync>`, so the same `serve`
runs over `DataFusionHist` in production and over the in-memory `MemHistStore` double in tests.

The wire protocol, the thin `DatahubClient` and `RemoteHistStore` (a `HistStore` served over this
protocol) live in the light `vike-datahub-client` crate, which is DataFusion-free so the GUI can
link it without the Arrow/DataFusion tree; it is the one home of the wire schema, and every
consumer — this server included — imports it directly.

<Callout title="A default build does not serve">
  The real `DataFusionHist`-backed server is compiled only under the `serve-datafusion` feature,
  which is what makes the concrete backend nameable. A default build compiles an inert stub `main`
  that prints a rebuild hint and exits, so `cargo build -p vike-datahub` always produces a runnable
  binary — and that build is DataFusion-free. `backfill-serve` additionally compiles the real
  collector table and makes `serve` advertise and answer `Request::Backfill`; it requires
  `serve-datafusion`, because the collectors write a concrete `DataFusionHist`.
</Callout>

`--help` and `--version` are answered in **both** builds, identically, before anything else. This
binary parsed no argv at all once: under the feature it went straight to opening a store and
binding a listener, so `vike-datahub --help` started a server; without it, every invocation printed
the missing-feature message and exited 2. Help is a question about the command line, which both
builds have; the missing backend is a question about running, which is why only the run path still
fails (`crates/vike-datahub/src/datahub_cli.rs`).

## Where it listens [#where-it-listens]

`VIKE_DATAHUB_ADDR` is the listen address, default `127.0.0.1:7878`.

<Callout type="warn" title="A non-loopback bind is refused twice over">
  A non-loopback address is refused at startup unless `VIKE_DATAHUB_ALLOW_PUBLIC_BIND` is set to the
  exact string `1` **and** at least one node key is configured. The opt-in alone used to be enough
  behind a warning; that is the state `crates/vike-datahub/src/datahub_cli.rs`'s header names
  as the one the refusal exists to prevent — the opt-in consents to being reachable, and is not consent to
  serve a store write and a Rhai compiler unauthenticated. The guard did not soften when
  authentication landed: the handshake is plaintext and authenticates the connection, not each frame,
  so an SSH tunnel is still what supplies confidentiality and integrity.
</Callout>

## Authentication — the credential is the switch [#authentication--the-credential-is-the-switch]

Two scoped HMAC node keys live in the credential store
(`<project>/settings/secrets.env`): `VIKE_DATAHUB_OBSERVE_KEY` and `VIKE_DATAHUB_CONTROL_KEY`.
Their **absence** is the switch. With neither set — the default — the server authenticates nothing
and behaves exactly as every build before them did: `Hello` is optional and informs rather than
gates, every verb is served to whoever can reach the socket, and the `Welcome` bytes are identical.
That is the same credential-is-the-gate idiom the venue mounts use, pointed at a server, and it is
why that mode is confined to a loopback bind.

With either key set the handshake becomes mandatory. `Hello` must be the first frame; the `Welcome`
answering it carries a fresh 32-byte per-connection nonce; a `Request::Auth` carrying the HMAC over
that nonce must follow; and every subsequent verb is checked against the authenticated scope. Any
verb before `AuthOk` is refused and the connection closes.

`crates/vike-datahub/src/server.rs`'s `required_scope` is the **one** authority for which verb
needs which scope, and its match is exhaustive — no `_` arm — so a new wire verb cannot be added
unclassified; it fails to compile instead. `Scope::Observe` covers the history and catalog reads
(`LoadBars`, `ScanQuotes`, `ScanTrades`, `PropertiesAsOf`, `ListSeries`, `Inventory`, `SeriesGaps`,
`Coverage`, `ListStrategies`) and `Ping` — a liveness probe is Observe rather than a handshake
frame, because answering one unauthenticated hands out a free oracle for "is this address a
datahub". `Scope::Control` additionally admits the `Backfill` store write and every `Run*`
verb — those compile client-supplied Rhai server-side, so they are not reads whatever they return.

## Connection hygiene [#connection-hygiene]

A read error or clean EOF ends only that connection's loop, never the accept loop; each connection
runs on its own thread, so even a panic inside a handler drops one socket rather than taking down
the server; and every request produces a response, so a client always learns the outcome. Framing
and decoding are split, so a well-framed body that fails to decode into a known `Request` — an
unknown verb from a newer client — is answered with an error and the loop **continues**: one bad
request is a bad request, not a bad connection. Each accepted stream gets a generous
`IDLE_READ_TIMEOUT`, and a timeout on an idle or half-open peer closes the connection rather than
resuming the loop, which would desync the stream.

## The rest of the environment [#the-rest-of-the-environment]

`VIKE_DATAHUB_STORE` names the hist-store root; unset, it falls through the shared precedence
`resolve_store_root_from` documents at its call site — the CWD-relative `market_data/hist` this
line used to name as the last resort is gone, and it was the whole bug (launching from anywhere but
the repo root created an empty store beside the shell). `VIKE_USER_DATA_DIR` is the user-content
root whose `indicators/` this server installs, falling back to the project walk from the working
directory; a client script resolves against the set **this** box installs.

Under `serve-datafusion` the `RunSlice` boundary (`crates/vike-studio-core/src/wire_run.rs`) is
compiled too — it is the only place this crate names `vike-studio-core`, and the parity test drives
the same `run_slice_local` the server arm does, keeping "local" and "over the wire" one
computation. A default build answers `RunSlice` with a clean error instead.

Related: [running a backtest](/docs/trader/backtesting/running),
[the history store](/docs/trader/concepts/hist-store),
[the node protocol](/docs/trader/concepts/node-protocol),
[running a sweep on the data service](/docs/trader/guides/sweep-on-the-service).


# vike-desktop (/docs/trader/reference/binaries/vike-desktop)



The desktop application: a native egui multi-window shell with live charts. Each window has a rich
title toolbar — chart-style menu, symbol dropdown, interval dropdown, LIVE badge, clone, minimize
and maximize icons (`crates/vike-desktop/src/main.rs`).

Market data flows feed threads → core ingest (lossless bar closes, conflated forming bars and
ticks) → the core-owned bar cache → an arc-swap `CoreSnapshot`, which this GUI converts to its
render model once per changed snapshot. &#x2A;*The GUI is a lossy observer; it never touches the core's
state directly.** That is the property every panel inherits, and it is why a slow frame can cost a
picture and never an order.

## One build, no features [#one-build-no-features]

`crates/vike-desktop/Cargo.toml` declares **no `[features]` table**, so there is one program here
and `cargo build -p vike-desktop` is the whole of it. What that build does NOT contain is the
interesting half, and the manifest records each absence as a tombstone rather than a deletion:

* **no trading core.** `vike-mount` (the venue→`ExecutionClient`/`ReconClient` composition root)
  and `vike-run` (`build_node`) stood in the manifest as optional dependencies turned on by a
  `fat` feature. Both are gone with it, so no `make_engine` arm is compiled and this binary mounts
  no venue, signs no order and runs no reconciliation.
* **no DataFusion.** `vike-data` is taken with DEFAULT features — the `HistStore` trait and
  nothing behind it. The manifest's own check is
  `cargo tree -p vike-desktop -i datafusion`, which must report the crate unreachable.
* **no collectors.** `vike-backfill` was enabled by the same `fat` feature; the Data Manager's
  bulk action now takes `backfill_route`'s WIRE arm against a datahub's store instead.
* **one venue crate, unconditionally.** `vike-deribit`, because the options-chain provider
  `vike-app-core` mounts is Deribit's.

It still links the (DataFusion-free) [Studio](/docs/trader/gui/studio) and drives it remote-only.

<Callout title="The ibkr and polymarket features went with fat">
  They gated live venue arms by flipping the matching `vike-mount`/`vike-run` feature. With no
  `vike-mount` dependency there is no arm to gate, so a venue named at this binary is not demoted to
  paper — it is not reachable from here at all. Those gates live in
  [vike-tradehub](/docs/trader/reference/binaries/vike-tradehub) now, which is the one live root.
</Callout>

## `--observe` [#--observe]

`vike-desktop --observe <ADDR>` is the read-only client mode: it connects to a headless
[vike-tradehub](/docs/trader/reference/binaries/vike-tradehub) daemon's observe server instead of
spawning a local trading core — which it could not do in any case. The argv scan lives in the
binary — argv is the binary's own fact — and feeds
`vike_app_core::backend_conn::startup_backend`, which is the ladder that decides which node is
actually dialled. A bare `--observe` is not an error: the app can do nothing else, so the word
alone means "the configured node" and the ladder falls through to the registry. Observe mode is made unmistakable in the OS window title, which reads
`OBSERVING <addr>` — and since the address always resolves, every run now carries that title
rather than the historic `— live` one.

<Callout title="It no longer refuses to start without an address">
  There is no local trading core, so `App::new`'s local-core arm is compiled out — but the observe
  address now always resolves (flag, else the active backend, else the local default), so the arm it
  could have fallen into is unreachable by construction rather than by an early exit. The window
  opens and the status bar says whether it connected, which is the thing a person can act on.
</Callout>

There is no local store engine either, so `open_studio_store`'s no-address arm is an error
naming **both** fixes — set `config.datahub_addr` to a running
[vike-datahub](/docs/trader/reference/binaries/vike-datahub), or connect a backend whose daemon
advertises one — rather than a feature-shaped "rebuild fatter" shrug. See
[observe mode](/docs/trader/gui/observe-mode) for the mode itself.

## Startup order [#startup-order]

`resolve_settings` runs **first** — before the log subscriber, the window, any feed and any core.
Two reasons, in order of weight: the log directory (`config.log_dir`) and both log levels are
themselves settings, so a subscriber built before the load could only ever honour the environment;
and a stale risk-ceiling variable must stop the process before it does anything at all. It logs
nothing, which is why it can run that early; everything it would have said is emitted the instant
the subscriber exists, including the warnings `vike_config` deliberately returns as data — a clamp
nobody is told about is a limit the operator believes they set and does not have. A failure prints
to stderr and exits 2.

The binary performs the process's one `std::env::vars()` sweep and hands it to `vike_boot::boot`,
which owns the startup sequence: refuse removed environment variables, walk once for the settings
directory, load the credentials and refuse an arming credential file, then load the settings and
render the disclosure. The credential loader is passed as a function, so `vike-boot` owns **when**
the store is opened and this binary owns **how**.

<Callout type="warn" title="A credential file may not arm real money">
  `secrets.env` is plaintext and parsed last-wins, so appending one line to it — with no read access
  at all — would otherwise be enough to flip this app's venue mount onto a live venue. `vike-boot`
  runs that refusal the moment the credentials are loaded, before the settings load and long before
  the window, the feeds, the core and every mount (`vike_config::arming`). It does not change which
  sources arm; it makes an arming credential file stop the process rather than run it.
</Callout>

## Where the logic actually lives [#where-the-logic-actually-lives]

`vike-desktop` is deliberately outside the derived CI roster (`xtask/src/ci/tables.rs`'s
`EXCLUDE_FROM_CI`). CI's `app-check` job compiles it once — there is one feature resolution to
compile — runs
`cargo clippy -p vike-desktop --all-targets -- -D warnings`, and runs `cargo nextest run -p vike-desktop` —
but only two things **execute** in the crate: the pure-logic byte-layout pins in
`crates/vike-desktop/src/chart_gpu.rs`, and `main.rs`'s `font_binding_tests`, which installs the fonts
and renders one real frame to assert every named family is bound to a usable face — it exists
because a Linux build that panicked on frame one shipped without it. Everything else, including
the whole of `App::update`, is type-checked and linted and then never run.

That is why the decisions moved down into `vike-app-core`, which rides the normal roster: the
per-frame `CoreSnapshot` fold (`core_sync`), the feed lifecycle, the startup layout, window spawn,
order dispatch, venue routing and the `--observe` reverse bridge (`observe_bridge`, whose
hand-maintained order-status mapping is now pinned by an exhaustive round-trip test — before the
move, a newly added variant silently rendered as terminal `Rejected` in the observer). The size of
the remaining unexecuted half is ratcheted by
`crates/vike-ops/tests/ci_excluded_gui_shell_ratchet.rs`, which fails a PR that grows it. Putting a
new branch in `main.rs` instead of in `vike-app-core` is choosing the unexecuted half.

## Headless capture [#headless-capture]

The app has a QA capture mode driven by environment knobs the binary reads and injects as
`vike_app_core::startup::StartupEnv`. `VIKE_SHOT` being present marks a headless capture and
suppresses the saved-workspace restore, so a capture always renders the deterministic default
windows; `VIKE_SHOT_WIN` selects which single tool window opens instead of the default chart;
`VIKE_STYLE` forces every window to one `ChartStyle` and `VIKE_SCALE` forces every window's
price-scale mode, each ignoring an unparseable or out-of-range value. The recognised
`VIKE_SHOT_WIN` values are deliberately not written down in prose — the test
`each_shot_win_value_opens_exactly_its_own_tool_window_and_no_feed` iterates them, so they live in
something that goes red rather than in something that goes stale.

Related: [the desktop app](/docs/trader/gui), [the chart](/docs/trader/gui/chart),
[connections](/docs/trader/gui/connections), [workspaces](/docs/trader/gui/workspace).


# vike-recorder (/docs/trader/reference/binaries/vike-recorder)



The headless live-tape recorder. A trader with no warehouse behind them still needs to backtest on
markets they have actually watched, so the terminal has to accumulate that tape for them. That is
this binary (`crates/vike-recorder/src/lib.rs`).

```
usage: vike-recorder --profile PATH [--tick-secs N] [--silent-secs N] [--exit-on-silence] [--once]

  --profile PATH    the recorder profile TOML (store root + subscriptions)
  --tick-secs N     how often to re-resolve the desired symbol set (default 30)
  --silent-secs N   warn when a subscribed series has received no rows for N seconds
                    (default 300; 0 disables)
  --exit-on-silence stop with status 3 when a series is silent, so Restart=on-failure can act
  --once            run ONE tick and exit — the dry run
  -h, --help        print this and exit 0
  -V, --version     print the version and exit 0
```

One TOML profile names the store and what to record. Every tick resolves each subscription's
current symbols, publishes their family membership, and drives the venue feed to exactly that set;
rows land in your own DataFusion + Parquet store through `RecorderSink`, **one commit per family**
rather than one per symbol.

## Why it is its own daemon [#why-it-is-its-own-daemon]

Recording needs venue feeds, and those drag the signer, WebSocket and TLS crates into whatever
links them. Keeping them out of [vike-datahub](/docs/trader/reference/binaries/vike-datahub) means a
panic in feed parsing cannot take serving down, and the server's dependency tree — audited on the
same box that signs real orders — stays small. The accepted cost is that datahub cannot report
recorder lag; if that ever matters the fix is an IPC surface, not co-hosting.

Not [vike-desktop](/docs/trader/reference/binaries/vike-desktop) either: a tape that only exists while a desktop
app is open has a hole wherever you closed it. And not
[vike-tradehub](/docs/trader/reference/binaries/vike-tradehub): recording must run whether or not you
are trading, and a trading daemon restart must not punch a hole in the tape.

Everything venue-free — the subscription model, the family membership, the subscription driver and
the daemon tick — is tested without a network, because the driver speaks the
`vike_data::live::DataClient` trait and the runtime drives a `VenueFeed`. The concrete venue is the
**binary's** choice.

## Venue features [#venue-features]

`crates/vike-recorder/src/venues/mod.rs` is the only venue-aware code in the crate, one module per
recordable venue, each behind its own Cargo feature — features rather than plain deps because a
bridge is heavy: enabling `polymarket` pulls the EIP-712 signer stack into the recorder binary, and
a build recording only static-symbol venues should not link one. A venue module implements
`VenueFeed` by *assembling* what the bridge crate already owns, never by reimplementing venue
logic.

<Callout title="A feature-absent build errors instead of recording nothing">
  `build_feed` answers a profile naming a venue this build cannot serve with a startup **error** that
  names the Cargo feature to rebuild with. A recorder that silently skipped an unsupported venue
  would look healthy while recording nothing — the same failure the profile-level config validation
  already exists to prevent.
</Callout>

The `binance` feature records the **trade tape only**: the venue serves no quotes and no lossless
book, and its L2 is the conflating `depth` lane, which `RecorderSink` does not persist
(`crates/vike-recorder/Cargo.toml`'s `binance`).

## Stopping without losing the tape [#stopping-without-losing-the-tape]

One stop flag, many triggers: a control word on stdin (`quit`/`shutdown`/`stop`) raises it, and so
do **SIGTERM and SIGINT** through `vike_ops::stop::install_handlers`, so `systemctl stop`, a bare
`kill` and Ctrl-C all reach the same teardown the typed word does. EOF stops only on a TTY — under
systemd stdin is `/dev/null`, which reads EOF immediately, so treating that as a stop would make
the daemon exit on startup. On Windows there is no POSIX signal, but `install_handlers` bridges the
console control events — Ctrl-C, Ctrl-Break, a window close — onto that same flag; only a recorder
started detached, with no console to deliver them, is left with the stdio word. Until that handler
existed, SIGTERM reached none of the teardown — and **the flush is where the tape was lost**, on
every restart of every box.

The teardown is budgeted end to end, because systemd follows SIGTERM with SIGKILL after
`TimeoutStopSec=` and a teardown that can outrun that budget is killed mid-write instead of
finishing. There are **two** numbers, not one: `FEED_STOP_BUDGET_SECS` for the feed unsubscribe
(measured, warned on, and subtracted from what follows, because a non-`Send` `VenueFeed` cannot
move onto the orchestration thread) plus `SHUTDOWN_DEADLINE_SECS` for the bounded
flush-and-compaction tail, summing to `TOTAL_STOP_BUDGET_SECS`, which is what the shipped unit's
`TimeoutStopSec=` is checked against.

<Callout type="warn" title="Teardown order is load-bearing">
  Unsubscribe every feed **first**, then shut the sink down. The other order leaves feed threads
  pushing rows into a channel whose writer is gone, and those rows are counted as dropped with no
  reporter left to announce them. The sequence is flush-first with the maintenance join last, so what
  a hard cap abandons is a compaction pass — restartable, costs nothing — and never the rows.
</Callout>

## The two watchdogs [#the-two-watchdogs]

The **silence** watchdog catches a feed that is subscribed, connected and receiving nothing, which
raises no error anywhere. It has three possible reactions and only two are on by default: a silent
series is always logged and always alerted (`crate::alerts::watchdog_tick`, in the library so a
test drives it; delivery is log-only until the `[alerting]` profile table names a target).
**Exiting** is opt-in via `--exit-on-silence`, because a venue can be legitimately quiet — an
illiquid market, a closed session, a window between rotations — and letting a quiet venue kill the
daemon recording five healthy ones would be a worse failure, crash-looping under
`Restart=on-failure`. The 300-second default was chosen against the slowest thing a healthy
recorder does — a Polymarket up/down family rotates its tokens every five minutes and a freshly
opened window can be genuinely quiet for a stretch, so a threshold at or below the rotation period
would cry wolf every cycle.
The exit status is `EXIT_SILENT` = 3, distinct from the generic failure 1 so a supervisor can tell
"a series went silent" apart from "the profile was bad".

The **resolve** watchdog is the feed-level twin and is on by default: a venue that has never
resolved a symbol since startup escalates, past the same `--silent-secs` grace, to an error plus a
real alert, while a venue that resolved before and is failing now stays the per-tick warning it
always was. The series watchdog is structurally blind to that state — a venue that resolved nothing
subscribed nothing, so its expected-series set is empty — and a clean install once produced exactly
it while the daemon ran on recording nothing.

`--once` is the dry run and the only reaction that exits on that judgement, with `EXIT_DRY_RUN`.
It exits 0 only if every feed ended that tick with at least one live subscription and no refused
subscribe; otherwise status 4, naming each feed that would record nothing. It is stricter than the
daemon on purpose — it is a commissioning check of your own profile, with you watching.

Related: [record a live feed](/docs/trader/guides/record-a-feed),
[the live data seam](/docs/trader/concepts/live-data-seam),
[the history store](/docs/trader/concepts/hist-store), [log volume](/docs/trader/data-providers/log-volume).


# vike-stat (/docs/trader/reference/binaries/vike-stat)



`vike_stat` maps one file read-only and prints the live core's key health counters. It never
attaches to the trader process, never opens a socket and never asks the core for anything — the
whole interface is a memory-mapped file the core mirrors into. That is the point: a headless
trader on a remote box has no window to look at, and `vike_stat` is how you look at it anyway.
This page is written from `crates/vike-core/src/bin/vike_stat.rs`'s module header and
`crates/vike-core/src/counters.rs`.

## The mirror is opt-in, and off by default [#the-mirror-is-opt-in-and-off-by-default]

The trader writes the file only when `vike_core::CoreConfig`'s `counters_path` is set. `None` is
the default, and its module doc states the consequence exactly: nothing is opened and the publish
path is byte-identical to a build without the feature. Off costs nothing.

On costs almost nothing either, and the reason is where the copy happens.
`crates/vike-core/src/counters.rs` opens with the pinned constraint: the per-message fold — the
`p99 < 10µs` gate — is **not** touched. No runtime atomic moves into the mmap and no per-message
write is added. The file is a *periodic mirror*, copied at the same coalesced cadence the runtime
already publishes a `CoreSnapshot` at (the module doc gives \~16 ms while busy, or on idle). The
only new cost is at that existing rare publish.

If the path is set and cannot be opened, the core fails loudly at startup rather than dropping the
mirror silently — `assemble_core` (`crates/vike-core/src/runtime/mod.rs`) opens it with an
`expect`, on the argument that a trader which believes it is mirroring but is not would mislead
this tool. The desktop app therefore probes the path itself first, so a read-only directory
degrades to *no mirror, with a warning* instead of a panic at launch.

## Finding the file [#finding-the-file]

`vike_stat` takes the path as its one positional argument, or from `$VIKE_COUNTERS_FILE`. The
desktop app resolves the writer's path the same way — `crates/vike-desktop/src/main.rs`'s
`counters_file_path` reads `$VIKE_COUNTERS_FILE` first and falls back to `<exe_dir>/counters.vmc`
— and its doc says why that matters: setting the one variable points the writer and the reader at
the same file with no arguments on either side.

```
usage: vike_stat <counters-file> [--watch] [--interval <secs>]

  --watch            re-read every 1s until interrupted
  --interval <secs>  re-read on a custom period (implies --watch)
```

`-h`/`--help` prints that text to **stdout** and exits 0; the same text alongside an error message
goes to stderr. The split is deliberate and is recorded on `vike_stat`'s `usage` function: printing
it unconditionally to stderr made `vike_stat --help | less` an empty page. A one-shot run whose
read fails exits non-zero so a script can tell "no file / bad file" apart from a healthy read;
under `--watch`, a transient error (the trader not up yet) is printed and the next tick retries.

## What a torn read means [#what-a-torn-read-means]

The writer wraps every mirror in a seqlock: the header's `seq` goes odd before the payload is
written and even after. The reader reads `seq`, the payload, then `seq` again, and accepts the
values only when both reads are equal and even. A clean read can therefore never return a
mid-update mix of counters.

When the retries are exhausted the report comes back with `clean = false` and `vike_stat` prints
`TORN-READ` instead of `clean` on its header line. `CountersReport`'s own field doc is the
authority for reading that: the values *may* be a mid-update mix, but every counter is monotonic,
so each individual value is still a valid point-in-time reading of that counter, off by at most one
update.

The layout is fixed, versioned and cache-line padded — a header slot plus one 128-byte slot per
counter — so an external reader has a stable schema and every field a stable aligned offset.
`vike_core::counters::read` errors on a missing file, a file smaller than one slot, or a bad magic;
a **version** mismatch is surfaced in the report rather than being an error, so a newer file still
prints the counters this reader knows.

## The counters [#the-counters]

`vike_core::counters::COUNTER_NAMES` is the stable wire order — append-only, never reordered or
removed, with the format version bumped on each append (v2 appended `dropped_nonfinite`). Two slots
are reserved tombstones: `exec_db_queue_depth` and `exec_db_errors` are marked RETIRED since the
SQLite exec database was removed and are always 0.

<Callout type="warn" title="One counter has no benign reading">
  `COUNTER_NAMES` singles out `dropped_nonfinite`. The others — conflation drops, rejected commands,
  stranded terminals, a terminal dropped on a live order, a lifecycle event for an unknown client
  order id — all have innocent explanations: a reconnect replay, a shared-account order, an
  out-of-order frame. A money-lane event carrying a non-finite `f64` has none; no venue sends
  `"NaN"`. Nonzero means a venue fault or a compromised feed, and the comment on that row says to
  page on it.
</Callout>

The counters are also carried in-process by `CoreSnapshot` for the GUI. This file is the
out-of-process twin of that, for the case where there is no GUI to read.

For the environment variable itself see [environment variables](/docs/trader/reference/environment); for
the fold whose budget the mirror is designed around, [the latency
gate](/docs/trader/concepts/latency-gate).


# vike-study (/docs/trader/reference/binaries/vike-study)



`vike-study` runs one **compiled** user study over the hist store and leaves a run behind. It is
the study runner that can *fit*: until it existed, nothing in the workspace could fit a compiled
study at all.

```
vike-study --study NAME --recipe FILE --from WHEN --to WHEN --store DIR
           [--lightgbm PATH] [--scratch DIR] [--runs-root DIR]

  --study NAME      the study's folder name under user_data/research/studies/rust/
  --recipe FILE     its .toml recipe; an optional [learner] table carries the GBDT base params
  --from/--to WHEN  YYYY-MM-DD, YYYY-MM-DDTHH, or bare unix SECONDS
  --store DIR       the hist store root the study reads
  --lightgbm PATH   the PINNED trainer. Omitted, the study runs with NO learner and a fitting
                    study refuses BY NAME rather than silently producing nothing
  --scratch DIR     per-fit scratch root (default: <runs-root>/../scratch/vike-study — the
                    project folder, never the system temp directory)
  --runs-root DIR   where the run is minted (default: user_data/runs)
```

The bin (`crates/vike-studio-core/src/bin/vike-study.rs`) is a thin shim over
`vike_studio_core::study_cli::run`, which reads no environment and no `std::env::args()` — argv is
a parameter, which is what lets the `vike` multicall dispatcher own the process's single sweep and
link one copy of the DataFusion closure for every tool.

## The gap it closes [#the-gap-it-closes]

The one caller of `run_study_plan` was the [Studio](/docs/trader/gui/studio), whose ML surface is the
**inference** half only (`crates/vike-studio-core/src/ml.rs`). It supplies no learner, so a study
needing a gradient-boosted classifier per fold answered `StudyError::NoLearner&#x60; on every
invocation — &#x2A;"the documented ceiling of a host with no LightGBM binary"*. That left the whole
compiled tier unrunnable in practice rather than in principle. This binary is the host that
supplies a learner.

`--lightgbm` names the pinned trainer. Omit it and the study runs with **no** learner, and a
fitting study refuses by name rather than silently producing nothing — the distinction between "you
did not give me a trainer" and "there was nothing to find" is the whole point of the refusal.

## Why a feature-gated bin in this crate [#why-a-feature-gated-bin-in-this-crate]

The host must sit strictly above `run_study_plan` (layer 55) and be able to construct a
`DataFusionHist`. [`vike-cli`](/docs/trader/reference/cli) (layer 65) clears the layer bound, but that
crate is deliberately **light**: it reaches history through `vike-datahub-client`, over the wire,
and names no DataFusion at all — the `light-consumers` CI lane compiles it as the
default-features-off consumer precisely to keep that true. Buying a verb with that property would
have charged every `vike-cli` user for it.

A bin beside the function it calls costs nothing instead. `study-cli` is off by default, so the
`studio-standalone` lane's structural check — the default normal-dep tree must carry no DataFusion
crate — is untouched, and `required-features = ["study-cli"]`
(`crates/vike-studio-core/Cargo.toml`) keeps this bin out of every build that has not asked for it.

<Callout type="warn" title="It is not in a default build">
  `vike-study` is a `required-features` bin. A plain `cargo build` of the workspace does not produce
  it, and the release ships only the configurations its workflow names. Build it with the
  `study-cli` feature enabled, or reach it through the `vike` dispatcher built with that feature.
</Callout>

## The `[learner]` table [#the-learner-table]

A study's LightGBM base parameters are a property **of the study** — the non-searched keys its
published results were measured at — while `vike_ml::GbdtLearner` knows nothing about any study and
the host is what constructs it. In the cohort study those keys had no home a host could reach: they
lived in a `#[cfg(test)]&#x60; module whose own doc called itself &#x2A;"their only home"*, so any real run
would have used LightGBM's defaults and quietly fitted a different model than the one every
recorded number came from.

So the **recipe** carries them, under `[learner]`, and this binary reads that table. The recipe is
already the study's own file and already travels with it; the study itself ignores the table (its
reader is lenient, as the strategy tier's is); and nothing study-specific is compiled into this
generic verb. An absent key keeps LightGBM's default, so a partial table is meaningful rather than
an error — a study that fixes two of five says exactly that (`study_cli::learner_params`). An
absent table means `GbdtParams::default()`, which is the right answer for a caller with no opinion
and the wrong one to assume in silence, so **the run prints which of the two it used**.

## Time boundaries [#time-boundaries]

`--from` and `--to` accept `YYYY-MM-DD`, `YYYY-MM-DDTHH`, or bare unix **seconds**, converted to
the epoch milliseconds `TsRange` speaks (`study_cli::boundary_ms`). Seconds are accepted because
every anchor in the cohort study's own record is written that way, and re-deriving one by hand is
how a window silently moves.

`--scratch` defaults to a directory under the runs root's parent — the project folder, never the
system temp directory — so a per-fit scratch tree lands beside everything else the program writes.

Related: [research](/docs/trader/research), [running a study](/docs/trader/research/running-a-study),
[Rust studies](/docs/trader/research/rust-studies), [training](/docs/trader/research/training),
[the fit cache](/docs/trader/research/fit-cache), [runs on disk](/docs/trader/backtesting/runs-on-disk).


# vike-tradehub (/docs/trader/reference/binaries/vike-tradehub)



The headless trading daemon. It runs a strategy on a server with no GUI, controlled by a TOML
**profile** plus newline-JSON `vike_exec::Command`s on stdin, emits a periodic one-line JSON
snapshot summary on stdout, and survives an SSH disconnect — it is a systemd service, detached from
the login session (`crates/vike-tradehub/src/tradehub_cli.rs`; `deploy/vike-tradehub.service` is
the shipped unit).

```
usage: vike-tradehub --config <profile.toml> [--profile <run_profile.toml>]

  --config PATH   the daemon profile TOML (venue / token_id / A-S mount shape) — REQUIRED
  --profile PATH  the operator-budget RunProfile TOML ([risk] ceilings); absent, $VIKE_RUN_PROFILE
  -h, --help      print this and exit 0
  -V, --version   print the version and exit 0
```

The bin is a thin shim over `vike_tradehub::tradehub_cli::run`; it is the composition root and
holds what a library may not — the one `std::env::vars()` sweep and the one `current_dir()`, both
handed to `run` (`crates/vike-tradehub/src/main.rs`).

## Paper is the default; live is a flag [#paper-is-the-default-live-is-a-flag]

By default the daemon mounts the resolved strategy on the **production live core** with the paper
exchange as its `ExecutionClient` — through `vike_run::build_paper_strategy_core_with`, so there is
zero real-money, credential or geo risk and no live feed. The `tradehub_live` flag
(`<project>/settings/flags.toml`, still overridden by `VIKE_TRADEHUB_LIVE`) instead mounts the same
strategy on the real `vike_run::build_node` core, with per-venue credential-gated exec and the
venue's own live feed. Off is byte-identical to the pure-paper daemon.

The live path is defended by five gates and **fails loud, never soft**: the master flag; per-venue
credentials (absent creds keep that venue paper); the venue's own second gate
(`HYPERLIQUID_MAINNET`); `crates/vike-tradehub/src/config.rs`'s `LIVE_WIRED_VENUES`, which
hard-errors on an unwired venue rather than falling back to paper silently; and the profile's
symbol checked against `vike_run::WIRED_MARKETS` by `DaemonProfile::validate_for_live`, because
`make_engine` wires no extra symbols and a foreign symbol on a wired venue would have its orders
and fills dropped at `accepts_symbol`.

<Callout type="warn" title="No policy.toml means an all-paper daemon">
  `policy.venues` is the per-venue arming **ceiling**, read at the top of `vike_mount::make_engine`
  above the credential read, and its default is `paper` for every venue. A box with no `policy.toml`
  mounts all paper, whatever the credential store holds. `vike_mount::venue_arming_migration` warns
  once at startup, naming the file, the `[venues]` key and every venue it refused. See
  [policy.toml](/docs/trader/reference/settings/policy).
</Callout>

## Which strategy is a profile field [#which-strategy-is-a-profile-field]

`[strategy] name = "…"` plus `[strategy.params]` — deliberately the same table
`vike_backtest::harness::BacktestProfile` has — resolves through the shared registry
`vike_strategy::strategy_by_name`, so the profile that was backtested is the profile that trades.
Absent `[strategy]`, the mount is the Avellaneda–Stoikov `vike_mm::SpreadMaker` built from the
profile's own maker fields by `vike_run::build_maker`. A Rhai script mounts **by path**
(`[strategy] rhai = "<path>"`, mutually exclusive with `name`), and the daemon logs the source's
sha256 and path at INFO — the journal's answer to which code traded.

`DaemonProfile::validate` refuses, at profile **load**, a name that is unknown, simulator-only
(`vike_strategy::SIMULATOR_ONLY`), or one that would resolve and then never trade
(`vike_strategy::LIVE_CAPABLE` carries a written reason for every "no"). Four further refusals
cover `[strategy.params]`, each the case the previous one passes: `unknown_params` (a key no reader
reads), `mistyped_params` (a value no reader can take), `misrouted_params` (a key the mount
overrides — including the ones naming which instrument and which venue real orders go to), and
`unarmable_params` (a table that passes all three and still describes no order at all). The mount
then echoes the resolved configuration through `DaemonProfile::effective_params`.

`[[mounts]]` is an array of the single-mount blocks, so strategies sharing a venue account share a
process; each row mounts under a derived controller id
(`DaemonProfile::derived_controller_id`), and two rows deriving one id are refused at load.

## Control surfaces [#control-surfaces]

With `config.tradehub_addr` (or `VIKE_TRADEHUB_ADDR`) set and a `VIKE_TRADEHUB_OBSERVE_KEY` in the
credential store — absent either, `start_observe_server` starts nothing and the daemon keeps
trading headless — the daemon also starts an authenticated node server so a laptop GUI can watch
this node's snapshots — see [observe mode](/docs/trader/gui/observe-mode) and
[the node protocol](/docs/trader/concepts/node-protocol) — and, behind the `tradehub_control` flag plus
a `VIKE_TRADEHUB_CONTROL_KEY`, trade it.
`crates/vike-tradehub/src/server.rs`'s `accept_command` is the **one** acceptance path, shared by
every control surface, so the rate token, the notional cap, the rationale sanitizer, the lowering,
the single-writer lane and the audit record are identical by construction rather than by review. A
remote submit must carry a pre-minted `client_order_id` or it is refused: a remote peer whose id
the runtime minted has no stable handle to cancel or dedup by. The optional rationale is remote
free text landing verbatim in a structured JSON log line, so
`crates/vike-tradehub/src/audit.rs`'s `sanitize_reason` is mandatory at the call site.

<Callout type="warn" title="Reachability is the outer barrier">
  Everything in `server.rs` is authorization — none of it is confidentiality or integrity. The
  handshake is plaintext and authenticates the connection, not each frame. There is deliberately no
  TLS: the listener stays on loopback and an SSH tunnel supplies both properties. Three things hold
  that up, each stating its own reasoning — `bind_exposure` (a non-loopback bind is refused unless
  explicitly opted in), `MAX_CONNECTIONS` and `HANDSHAKE_MAX_FRAME_LEN`.
</Callout>

The publisher (`crates/vike-tradehub/src/publish.rs`) reads only the coalesced arc-swap snapshot
cell, on its own thread, and pushes shared frame bytes into each subscriber's bounded, drop-oldest
mailbox — it must never enter the core fold. The opt-in
[Telegram channel](/docs/trader/guides/telegram-control) is a second remote write surface behind an
off-by-default Cargo feature and four runtime gates; it shares `accept_command` with the TCP path.

## Lifecycle and stop [#lifecycle-and-stop]

`vike_ops::stop::install_handlers` is the **first** statement of `run`, above argv and the settings
load (`crates/vike-tradehub/src/tradehub_cli.rs`'s `run`). The gate behind it is narrower than
that: `crates/vike-ops/tests/graceful_stop_pin.rs`'s
`the_tradehub_handler_is_installed_before_anything_can_place_an_order` checks by position only that
the install precedes every mount call, because between a mount returning and the handler
installing, the maker may already hold resting orders at the venue while SIGTERM still carries the
OS default disposition. One stop flag has many triggers: the
`shutdown`/`quit` word on stdin, Ctrl-D on a TTY, SIGTERM/SIGINT, the Windows console control
events, and on Windows the appearance of `<state>/` plus `vike_ops::stop::STOP_FILE_NAME`. A
non-TTY EOF does **not** stop the daemon — it keeps trading headless. The teardown is bounded by
`vike_ops::shutdown::run_with_deadline` wrapping `vike_core::CoreHandle::shutdown_and_join`.

stdout is **protocol-only** — newline-JSON summaries and acks; every log and diagnostic rides the
`vike_log` file/stderr layer. `resolve_settings` runs before the log subscriber is built, because
the log directory and both log levels are themselves settings; it returns its warnings as data for
`main` to emit once a subscriber exists. A removed environment variable refuses startup outright.

[Reconciliation](/docs/trader/concepts/reconciliation) defaults to `quarantine` here rather than to the
workspace default: under `hybrid` a freshly restarted daemon would auto-apply position drift,
rewriting position size and booking realized PnL at the venue's price before anyone has confirmed
the venue's report is complete. Its health gate is fed by the feeds this mount actually wired
(`recon_feed_statuses_of`): a CEX venue contributes its own status handle and is gated on it, while
every venue that contributes none — hyperliquid and polymarket among them — reads Healthy.
[Alerting](/docs/trader/concepts/alerting) rides the periodic summary tick off-fold, and the rules file
is the gate. `record-feeds` and `materialize` are the crate's two DataFusion arms, both off by
default to keep the daemon DataFusion-free.


# Global flags (/docs/trader/reference/cli/global-flags)



Every `vike-cli` verb drains the same flag iterator. `crates/vike-cli/src/cmd/args.rs` owns only the
mechanics: the two spellings, value resolution with a clean dangling-flag error, bare-boolean
rejection of inline values, the `-h`/`--help` short-circuit, and the one place a parser's `Err`
becomes an exit code and a stream. Each command keeps its own `Args` struct and its own match over
flag names. There is no `clap` — the crate deliberately adds no dependency for this.

The module exists because the same `split_once('=')` / `take_value` loop had been hand-copied across
`backtest`, `sweep` and `walkforward` and re-rolled as closures in `mcp` and `trade`, already
drifting in shape.

## Both spellings resolve [#both-spellings-resolve]

`--flag value` and `--flag=value` are equivalent. `Flags::next_flag` splits on the **first** `=`
only, so an inline value may itself contain `=` (`--script=a=b.rhai` is the script `a=b.rhai`). A
value taken from the next argument is consumed **raw** and never re-split, so `--profile k=v.toml`
is the path `k=v.toml`.

A value-taking flag with nothing after it is a clean error naming the flag:

```
--profile requires a value
```

## A token beginning with `--` is a flag, never a value [#a-token-beginning-with----is-a-flag-never-a-value]

<Callout type="warn" title="This rule is why a mistyped line fails instead of running the wrong thing">
  Without it a valued flag ate whatever followed, including another flag. `vike-cli backtest --script --json` took the literal `--json` as the **script path** and then ran with JSON output off;
  `--profile --addr 1.2.3.4:9` put `--addr` in the profile path and died on the address as an unknown
  argument, naming a token the operator had written correctly. Both errors now name the unfed flag
  **and** the token it would have eaten (`crates/vike-cli/src/cmd/args.rs`'s `is_flag_token`).
</Callout>

The test is `--`, not a bare `-`, and that half is load-bearing: a **negative number is a real
value** in this workspace's parsers, so a `starts_with('-')` test would turn every signed field into
a usage error. `--qty -5` resolves to `-5`. The residual is stated rather than implied — a
single-dash token (`-h`, `-5`) is still accepted as a value.

The rule is applied to the inline `=value` form as well, deliberately: one rule, one sentence, no
per-spelling exception to remember. The cost is that a value which genuinely begins with `--` has no
flag-attached spelling; a path is still reachable as `./--weird`.

## A bare boolean rejects an inline value [#a-bare-boolean-rejects-an-inline-value]

`--json`, `--strict`, `--list-params`, `--yes` and their siblings take no value, and
`args::no_value` refuses one rather than reading it as a silent true:

```
--json takes no value
```

## Help is a success; its text is stdout [#help-is-a-success-its-text-is-stdout]

`-h` and `--help` short-circuit a parser through the `Err` channel — these parsers return `Result`,
so "the user asked for help" has to travel back somehow — carrying the sentinel
`args::HELP_SENTINEL`, spelled once so the parsers and the exit path cannot disagree about it. It is
control flow, never a diagnostic, and must never reach a terminal.

`args::exit_for_parse_error` is **the** one place that decision is made:

| outcome         | stream                                                                     | exit |
| --------------- | -------------------------------------------------------------------------- | ---- |
| `-h` / `--help` | the usage, on **stdout** — help is normal output a user pipes into a pager | 0    |
| a usage error   | `vike-cli <command>: <msg>` and the usage, on **stderr**                   | 1    |

Nothing else is printed on the help path, and the sentinel appears nowhere. Every non-interactive
command used to inline the error arm and route the help short-circuit straight into it, so
`--help` exited **1** and printed `vike-cli backtest: help requested`. Sharing the decision is what
stops the spellings drifting apart again: `config` had already been fixed at its verb level and
**not** at its `show --help` level, in the same file. The shipped-binary gate is
`crates/vike-cli/tests/help_cli.rs`, which asserts the status, the stream and the absence of the
token; see [the dispatcher](/docs/trader/reference/cli).

The [`trade` REPL](/docs/trader/reference/cli/trade/trade) is the one deliberate outlier — it records
`help = true` and prints its verb reference instead of short-circuiting, because its help is a
reference to an interactive grammar rather than a usage line.

## Flags that mean the same thing everywhere [#flags-that-mean-the-same-thing-everywhere]

These are conventions across the verbs rather than shared code, but they are spelled the same way
by every command that has them:

| flag                 | meaning                                                                                                                                                                                                                                                                                            |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--profile <path>`   | a backtest profile `.toml`, read locally and shipped to the server — **verbatim** for [sweep](/docs/trader/reference/cli/sweep) and [walkforward](/docs/trader/reference/cli/walkforward), while [backtest](/docs/trader/reference/cli/research/backtest) rewrites it first if `--preset` or `--script` was given |
| `--addr <host:port>` | the [data service](/docs/trader/reference/binaries/vike-datahub) address, default `127.0.0.1:7878`                                                                                                                                                                                                      |
| `--node <host:port>` | a running [`vike-tradehub`](/docs/trader/reference/binaries/vike-tradehub) node — [trade](/docs/trader/reference/cli/trade/trade), [mcp](/docs/trader/reference/cli/mcp)                                                                                                                                          |
| `--json`             | print the machine view: the server's report verbatim, or the command's own report as one object — including [`data`](/docs/trader/reference/cli/data/data), which describes the fetch or the seed and quotes the engine's report verbatim                                                               |

A verb that *produces* a document prints it on **success only**: a failure is a sentence on stderr
plus a rung on the exit ladder, and stdout carries nothing, so a caller reads the exit code first
and parses second. None of them wraps the answer in an `{"ok": false}` shape that would duplicate
what the code already said. `config check` is the deliberate exception, and for a reason its own page
gives — there the exit code *is* the product, so its report is meant to be read on a failing run too
and is printed either way.

Before any of this is parsed, the dispatcher has already refused a removed environment variable and
resolved this box's settings — see [environment variables](/docs/trader/reference/environment) and
[settings](/docs/trader/concepts/settings).


# vike-cli (/docs/trader/reference/cli)



`vike-cli` is the unified command-line surface over the light client crates: a git/cargo-style
subcommand dispatcher, `vike-cli <command> [args…]`, with argument parsing hand-rolled and no
`clap` dependency (`crates/vike-cli/src/lib.rs`). The dispatcher itself never grows command logic —
it only routes. Each verb is a sibling module under `cmd` exposing a `run(args) -> ExitCode`, and
adding one is a module, an arm in `dispatch`, and a line in `COMMANDS`.

That constant is the single source of truth for both the help text and the "unknown command" hint,
so a new command shows up in help for free. This is what it holds:

```
vike-cli — the unified vike command-line surface

usage: vike-cli <command> [args…]

commands:
  backtest     run a backtest on a remote vike-datahub server and print the report
  sweep        run a parameter-grid search on a remote vike-datahub server and print the ranked grid
  walkforward  run an anchored walk-forward validation on a remote vike-datahub server
  data         get market data into the hist store: fetch real bars, or seed the demo tape
  config       settings provenance (`show`) and a validating pre-flight (`check`) for this box
  mcp          serve the create+backtest tools over stdio MCP (for Claude / an agent)
  trade        interactive REPL to observe + control a running vike-tradehub node (for a human)
  strategy-status ask a running vike-tradehub node what it is running (read-only; --json for machines)
  secrets      inspect the credential store <project>/settings/secrets.env, and set ONE key in it (list | path | template | set)
  init         create <project>/user_data — strategies, profiles, results — with examples
  indicators   print the indicators a Rhai strategy can call, with their parameters

run `vike-cli <command> --help` for a command's own options
run `vike-cli --version` to print this build's version
```

One page each: [backtest](/docs/trader/reference/cli/research/backtest) · [sweep](/docs/trader/reference/cli/sweep) ·
[walkforward](/docs/trader/reference/cli/walkforward) · [data](/docs/trader/reference/cli/data/data) ·
[config](/docs/trader/reference/cli/set-up/config) ·
[mcp](/docs/trader/reference/cli/mcp) · [trade](/docs/trader/reference/cli/trade/trade) ·
[strategy-status](/docs/trader/reference/cli/strategy-status) ·
[secrets](/docs/trader/reference/cli/set-up/secrets) · [init](/docs/trader/reference/cli/set-up/init) ·
[indicators](/docs/trader/reference/cli/research/indicators). The grammar every verb shares is on
[global flags](/docs/trader/reference/cli/global-flags).

## Help exits 0, to stdout [#help-exits-0-to-stdout]

A top-level `--help`, `-h` or `help` prints the command list and succeeds; `--version` or `-V`
prints the version and succeeds; an unknown command prints its error to stderr, then the help, and
fails. Invoking the binary with no subcommand prints help and exits non-zero — there was nothing to
do.

<Callout type="warn" title="A non-zero --help breaks every wrapper that checks a status">
  `--help` short-circuits each parser through the `Err` channel carrying an internal sentinel, and
  four commands used to read that as a usage error: exit 1, with `help requested` printed to stderr as
  though it were a diagnostic. `crates/vike-cli/src/cmd/args.rs`'s `exit_for_parse_error` is now the
  one place that decision is made, and `crates/vike-cli/tests/help_cli.rs` runs the **real binary**
  and asserts the three properties a user sees — the status, the stream, and that no internal token
  leaks. A unit test of the parser cannot see any of them.
</Callout>

`--version` prints `<name> <version> (<build identity>)` through `vike_buildinfo::version_line` —
the shape every `--version` on the box already prints, with this build's provenance appended so a
packaging script or a bug report can answer &#x2A;which commit is this?*. Both spellings are accepted;
never `-v`, which is verbosity everywhere else. Until they were added, both fell into the
unknown-command arm and exited 1.

## What happens before any verb runs [#what-happens-before-any-verb-runs]

`run` calls `resolve_policy` first, which runs the workspace's one startup sequence
(`vike_boot::boot`): it refuses a removed environment variable, resolves `<project>/settings`
**once**, and loads it. The environment read lives at the entry point, per the rule that only
binaries read the process environment — see [environment variables](/docs/trader/reference/environment)
and [startup preflight](/docs/trader/concepts/startup-preflight). The check runs for every subcommand,
including read-only ones: a variable that is stale is stale regardless of which verb was typed.

The loader's non-fatal resolutions are **surfaced, never swallowed** — this dispatcher used to drop
them, so a preference clamped to a policy ceiling took effect with no output at all. They print to
**stderr**, never stdout, because `vike-cli mcp`'s stdout is a protocol.

The same sweep yields the settings directory (`secrets`, `trade`, `config` take it as a parameter,
so the directory they print is provably the one every other surface reads) and its sibling
`<project>/user_data`, which reaches `init` alone — the one subcommand that writes to the project,
and it writes only under `user_data/`. `indicators` takes nothing from the dispatcher and opens no
file of its own: its built-in roster is a property of the build, never of the environment or a
credential. The listing is still not a pure function of the build — a user's own indicators are read
out of the process state installed below, so two boxes running one binary print different listings
when one of them has written one.

## The credential read is lazy, and scoped [#the-credential-read-is-lazy-and-scoped]

`node_keyring` opens `<project>/settings/secrets.env` **only** for the node-facing arms — `trade`,
`mcp` and the read-only `strategy-status`. A backtest command has no business opening the file that
holds every venue key on the box, and `config` and `secrets` reach that store through their own
readers rather than this keyring. A store that exists but cannot be read is reported on stderr and
treated as empty rather than fatal.

## The identity is negative [#the-identity-is-negative]

The crate is **DataFusion-free and transport-free**, and that is the test every dependency is argued
against edge by edge — `crates/vike-cli/Cargo.toml` carries the argument on the rows themselves,
describing the crate as "the unified, DataFusion-free command-line surface" and marking it
DataFusion-free by construction. `vike-secrets` — a crate with zero dependencies — is linked
instead of `vike-bridge-core` for the credential store, and `vike-ops` and `vike-bridge-core` are
both taken `default-features = false`; restoring their default `full` features would drag the venue
transport and signing stack into a laptop binary. The heavy work happens on the
[data service](/docs/trader/reference/binaries/vike-datahub) instead.

`<project>/user_data/indicators/*.rhai` are loaded and installed process-wide before any subcommand
runs, so a script run by any verb can call them. Every rejected file is reported on stderr and a bad
one never fails the command — aborting would let one half-edited indicator block every invocation,
including the `init` that scaffolds the examples.


# vike-cli mcp (/docs/trader/reference/cli/mcp)



`vike-cli mcp` serves the vike agent surface as MCP tools over stdio, so an agent can run the full
loop: author a Rhai strategy, discover its knobs, see the host-bound indicator set, run a backtest —
and, against a running [`vike-tradehub`](/docs/trader/reference/binaries/vike-tradehub) node, read live
state and place orders through a mandatory preview gate (`crates/vike-cli/src/cmd/mcp.rs`).

```
usage: vike-cli mcp [--addr 127.0.0.1:7878] [--node <host:port>] \
                    [--profile full|read-only|offline] [--deny-tool NAME]... \
                    [--trace | --trace-dir <dir>]
```

| flag                 | meaning                                                                                                                                                   |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--addr <host:port>` | the [data service](/docs/trader/reference/binaries/vike-datahub) the run tools ship profiles to; default `127.0.0.1:7878`                                      |
| `--node <host:port>` | a running vike-tradehub node, for the live read and write tools. Omit it and the create-and-backtest tools still work                                     |
| `--profile <ring>`   | which tools this server serves at all: `full` (default, every tool), `read-only` (no order-write tools) or `offline` (only the tools that open no socket) |
| `--deny-tool <name>` | withhold one tool by name, repeatable; subtracts from whatever the profile allows                                                                         |
| `--trace`            | append one JSONL record per tool call under `<project>/settings/state/agent`. Off unless asked for                                                        |
| `--trace-dir <dir>`  | the same record, written exactly there                                                                                                                    |
| `-h`, `--help`       | print the usage to stdout and exit 0                                                                                                                      |

An unknown `--profile` value or an unknown `--deny-tool` name is a usage error naming the valid set,
never a silent fallback — `Profile::parse` in `crates/vike-cli/src/cmd/mcp.rs` has no `_ => Full`
arm, and `parse_config` validates a deny name against the served roster before it accepts it. Both
refusals are the same rule: a typo in an MCP client's launch config must not serve more than the
operator asked for, and must not leave them believing a tool was withheld when nothing was.

Client setup — the config block an agent needs, and where it goes — is on
[connect an agent](/docs/trader/guides/connect-an-agent) and
[connect Claude to the Studio](/docs/trader/gui/studio/connect-claude). Each tool's schema, a runnable
call and its captured response are under [the MCP tools](/docs/ai/trader/tools).

## Transport [#transport]

MCP's stdio transport is JSON-RPC 2.0 framed as newline-delimited JSON — one message per line, no
embedded newlines. It is hand-rolled with `serde_json`, the same "no async, no new transport stack,
stdio-JSON" convention the workspace's other sidecars use; a full MCP SDK would drag in a second
async stack the workspace rejects. Requests carrying an `id` get exactly one response; notifications
get none. `initialize` echoes the client's requested protocol version when it declares one and
otherwise answers `2024-11-05`, declares three capabilities — `tools`, `resources` and `prompts` —
and carries an `instructions` string beside them (below). `ping`, `tools/list`, `resources/list`
and `prompts/list` are answered directly;
`tools/call`, `resources/read` and `prompts/get` route into a handler; an unrecognised method
returns `-32601`, and a malformed line is answered with a `-32700` parse error rather than killing
the connection.

<Callout type="warn" title="stdout is a protocol">
  Diagnostics, warnings and the settings loader's resolutions all go to **stderr**. One stray
  `println!` corrupts the JSON-RPC stream. This is also why the dispatcher's warning surfacing is
  stderr-only, and why the settings library returns its resolutions as data rather than logging them.
</Callout>

## What `initialize` tells the model [#what-initialize-tells-the-model]

MCP's `instructions` field is free text the client puts in front of the model as guidance about the
server, and this server sends one (`instructions` in `crates/vike-cli/src/cmd/mcp.rs`, assembled
from named constants — so it is fixed text for a given build and profile, not something a session
accumulates).

It exists because of a fact no tool description can carry. A description describes *its* tool;
"there is no tool for this, and the binary that does it is `vike-recorder`" is a fact about the
**absence** of a tool, and there is no tool to hang it on. A model-in-the-loop evaluation on
2026-09-06 measured the consequence four times over: the agent refused correctly, said the
capability was a separate step, and could not name the step — so the operator was told *no* and
nothing else. So the text says three things unconditionally:

* **This server is one surface of a larger system**, which is the fact that makes the rest worth
  its place in every session's context window.
* **One line per capability that lives outside it**, each naming the command an operator types:
  `vike-recorder` for a live tape, [`vike-cli data fetch`](/docs/trader/reference/cli/data/data) or
  `vike-cli data seed-demo` for bars in the history store, `vike-cli backtest --local` for a
  backtest with no data service running, and [`vike-cli secrets list` /
  `vike-cli secrets path`](/docs/trader/reference/cli/set-up/secrets) for which venue keys this box holds and
  where they are read from. None is a tool, and the text says so outright.
* **Two rules about answering**: invent no tool name, and never report an operator-side command as
  something you ran.

Two further sentences ride on the scope, and each is present only because some profile drops it:
one names `list_series` as how you confirm a tape or a fetch arrived, and one says an order write
without the `preview_token` this server issued for that exact command returns a preview and sends
nothing. Those two identifiers are the whole of what the text shares with `tools/list` — it
restates no schema, no argument table and no procedure, because the roster carries the first at
length and pages like this one carry the rest.

<Callout type="warn" title="It is advice, not capability, and it is scoped like the roster">
  Nothing an agent may **call** changes because of this text. What changes is what it can say when it
  cannot call anything, which is the whole point.

  And it is scoped by the same `ToolAccess` as `tools/list`: a `read-only` session's text carries no
  preview-gate sentence, and an `offline` one also drops the sentence naming `list_series`, because
  prose pointing at a withheld tool is advertising a withheld tool
  (`the_instructions_are_scoped_by_the_same_access_the_roster_is`). The operator-side commands survive
  every profile and must: a profile scopes this server's tools, not the operator's terminal.
</Callout>

The credential line names `secrets list` and `secrets path` and **no writer** — a deliberate fence
rather than an omission, held by `the_mcp_surface_advertises_no_credential_writer`, which now reads
this text as well as the tool roster. The same test requires the text to state outright that no
tool here reads, writes or arms a credential: the store's path with no such sentence beside it
reads as an invitation, and an omission is what a model fills in with a guess.

## The tools [#the-tools]

**Offline, read-only** — pure script work, no server: `validate_strategy` (compile *is* validation),
`discover_params`, `list_templates`, `list_indicators`.

**Remote data service, read-only** — a backtest mutates nothing: `run_backtest`, `run_sweep`,
`run_walk_forward`, `list_strategies`, `list_series`.

**Live node, read-only**: `node_snapshot` — orders, positions, per-venue equity, recent events.
Needs `--node` and `VIKE_TRADEHUB_OBSERVE_KEY`.

**Live order-write**, annotated `destructiveHint`: `submit_order`, `cancel_order`, `modify`,
`flatten`, `market_exit`, `mass_cancel`, `set_trading_state`. Needs `--node` and
`VIKE_TRADEHUB_CONTROL_KEY`.

`list_indicators` deliberately names no roster in its description: that text ships in every session's
`tools/list` whether the tool is called or not, and it used to splice the bound-name list in — 13
characters when the host bound three names, kilobytes now that it binds the catalog. Pass `category`
for one family or `name` for one indicator — the host-bound BUILT-IN set, which the human
[`indicators` verb](/docs/trader/reference/cli/research/indicators) prints too; an indicator installed from
`user_data/indicators` shows up in that verb's listing and in no answer this tool gives.

## Serving fewer of them: `--profile` and `--deny-tool` [#serving-fewer-of-them---profile-and---deny-tool]

The preview gate below makes a write take two calls. `--profile` is the other question — whether
this server offers the write tools *at all* — and it is answered at startup, by the operator, in the
MCP client's launch command. Under `read-only` the seven order-write tools are &#x2A;*absent from
`tools/list`** as well as refused by `tools/call`; under `offline` every network-touching tool goes
too, leaving the four authoring tools.

| profile     | serves | what it is for                                                                                                      |
| ----------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| `full`      | all 17 | the default — an absent flag is the surface that shipped before the flag existed                                    |
| `read-only` | 10     | an agent that may read the node, run backtests and author scripts, and cannot place an order                        |
| `offline`   | 4      | script authoring with no socket at all: `validate_strategy`, `discover_params`, `list_templates`, `list_indicators` |

Neither ring is a roster somebody typed, which is what stops it drifting from the gate it mirrors.
`ToolAccess::new` in `crates/vike-cli/src/cmd/mcp.rs` makes **one** pass over the tool registry and
produces two complements — `tools/list` renders one and `Server::call_tool` refuses the other — so
an advertised tool cannot be refused and a withheld one cannot be routed. `read-only` is the
negation of `is_write_tool`, the same `WRITE_TOOLS` roster the preview gate itself routes on, so an
eighth write verb joins the ring the moment it joins that array. `offline` is the tool's own
`openWorldHint` annotation read back off the spec it advertises, and a tool that declares nothing is
withheld rather than admitted — the safe direction for a ring whose whole promise is negative.

`--deny-tool NAME` subtracts one tool from whatever the profile allows, and feeds the same set; it
is repeatable. `--profile read-only --deny-tool run_sweep` is an agent that may backtest but not
spend the data service's time on a grid.

Three consequences worth knowing before you scope a session:

* **The resources are scoped by the same predicate.** A resource is a second way *in* to a tool's
  implementation — `vike://node/snapshot` routes into `node_snapshot` — so serving one while its
  tool is withheld would hand back exactly the answer the profile refused, through a URI. Neither
  resource is a write, so `read-only` withholds neither; `offline` withholds both, because both
  reach a tool that opens a socket.
* **The prompts are re-worded, not withheld.** A prompt executes nothing, and a sheet that vanishes
  teaches an agent less than one saying the tools are not served here. So a session with no admitted
  write opens every prompt with a banner saying so, and the two-call instructions are rendered from
  the *admitted* write set rather than from the roster — when none is admitted there is no gate to
  teach and none is printed.
* **The `initialize` instructions lose clauses under the same predicate** — not re-worded, dropped:
  a session with no write tool is sent no preview-gate sentence, and one with no `list_series` is
  sent no sentence naming it (see [above](#what-initialize-tells-the-model)). Free text that reaches
  the model is a place a withheld tool can be advertised just as surely as a roster entry is.

A refusal names the profile, lists the tools that *are* served, and says that only the operator can
widen it by restarting the server — an agent told merely "not available" spends its next turns
hunting for the switch that turns it on.

## The preview gate [#the-preview-gate]

A write executes only when the call carries **both** `confirm: true` **and** a `preview_token`
this server issued for that exact command. A call missing either half previews instead: it returns
the resolved command, a client-side guardrail check, the node's own dry-run verdict when there is a
node to ask, a note, and a token. `Server::call_tool` is the one gate, and it fails closed in every
direction — but not equally loudly. A missing `confirm`, a `confirm` that is not the JSON boolean
(the *string* `"true"` is not), or a missing token all come back as an ordinary preview; an unknown,
expired or mismatched token comes back as a tool error saying which. Nothing sends.

The token is minted by `PendingPreviews::issue`, **fires once** (`PendingPreviews::take` removes it
before the command runs), **expires after 60 seconds** (`PREVIEW_WINDOW`), is **bound to the command
it previewed** (`same_intent`, which ignores only the minted client order id) and lives in process
memory, so it dies with the stdio session. It is not a secret and does not need to be — on a stdio
server the only party who can send a request already holds both ends of the pipe. What it proves is
that a preview happened *for this command*: a sequence, not an authorization. The full rules, field
by field, are on [the live-node tools page](/docs/ai/trader/trading).

<Callout type="warn" title="confirm: true on its own is not an error — it is a preview">
  A confirming call with no `preview_token` does **not** fail. It returns a fresh preview with
  `will_execute: false` and a new token, and sends nothing. An agent that reads `isError: false` as
  "the order went in", without reading `will_execute`, believes it placed an order that does not
  exist. The **node's** own control limits and the core risk gate are the enforcing backstop
  regardless: the client preview is UX, the node gate is truth. See
  [the control boundary](/docs/trader/concepts/control-boundary).
</Callout>

Every `submit_order` carries a client order id. It stays an optional argument, but the node refuses
a remote submit with an empty one, so when the agent omits it this server **mints** one — the same
generator and wire form the live core uses — before the preview renders. The agent does not have to
carry that id back: what a confirming call executes is the **stored** command, not the one it
rebuilt, so the id that reaches the venue is the one the preview displayed and the node dry-ran.
`client_order_id` in the accepted response is always the authoritative one.

Each write tool reports **its own** command's outcome, by awaiting the ticket the send returned
under a two-second deadline. It used to poll a handle-wide error field that **latches**, so every
tool call after the first refusal returned that same refusal — including commands the node had
executed. An agent reading that would reasonably retry and place the order twice.

Every write tool also takes an optional &#x2A;*`reason`**: why this command is being issued. It rides
beside the command, is echoed in the preview, and lands in the node's audit trail, sanitized
server-side — control characters stripped, capped at 512 characters. It never reaches the order, the
core fold, the journal, or a venue.

## The agent transcript: `--trace` [#the-agent-transcript---trace]

The node records one audit line per **accepted** control command. Nothing recorded what the *agent*
attempted — the tools it called, the arguments it called them with, and above all what was
**refused**, which never reaches the node's trail at all because it was refused before a byte left
this process. `--trace` is that record: one appended JSON Lines entry per `tools/call`, written by
`crates/vike-cli/src/cmd/mcp_trace.rs`.

Each entry carries the tool, whether it is a write, the profile the server is running under, the
arguments, the verdict, and — for a gated write — the preview token's identity. The verdict is one
of four words, and `refused` is the one the file exists for: `ok` (the tool ran and answered),
`preview` (a write tool returned its mandatory preview and sent nothing), `refused` (a gate said no
— the profile, or the token binding — and nothing was attempted) and `error` (the tool was admitted
and failed). `preview` is kept apart from `ok` deliberately: "the agent called `submit_order`" and
"an order left this process" are different facts.

It is a **sibling** of the change journal rather than a fifth record kind in it — a per-event stream
does not belong in a per-change ledger — so `--trace` writes monthly files under
`<project>/settings/state/agent/`, beside `.../state/changes/`, pruned to the newest 24 at startup.
`--trace-dir <dir>` names a directory outright instead. A `--trace` that can resolve no project
refuses to start rather than serving silently with no record: an operator who typed the flag must
not find out after the incident that there was nothing to read.

<Callout title="Off by default, and no secret and no token bytes are written">
  Absent flags mean nothing is written and no directory is created. When it is on, argument values are
  redacted through the workspace's one credential-name authority (`vike_config::is_secret_key`)
  applied in two positions: every object key, so an `_API_KEY`/`_SECRET`/`_TOKEN`-suffixed name never
  has its value recorded, and every credential-shaped SHOUTING\_CASE identifier appearing inside a string value, so a
  `reason` mentioning `BINANCE_LIVE_API_SECRET=…` has the whole value replaced. The shouting-case
  precondition is what keeps that a rule rather than a nuisance: the shapes match the bare word
  `TOKEN`, so applied to prose they would erase every `reason` that mentions one. The `preview_token`
  argument is redacted by that first rule; what the record carries instead is a field of its own
  holding the token's **identity** — `pv-3`, the per-session counter — and whether this call minted it
  or presented it. That is a sequence rather than an authorization, which is why there is nothing
  there to withhold. The residual is stated rather than implied: a high-entropy string
  with no name anywhere near it is not detectable, and is recorded (capped). This module reads no
  credential store and no environment — the arguments are its only input.
</Callout>

An oversized record **degrades** rather than being refused: the arguments are dropped, a marker says
so, and the row survives. That is the deliberate inversion of the change journal's rule, and it
follows from what each record is for — for a ledger of changes a truncated line is worse than a
missing one, while for a record of attempts the missing line *is* the failure. A trace that cannot
be written is reported on **stderr**, never stdout, for the reason the callout at the top of this
page gives.

## Node keys [#node-keys]

The two HMAC keys are resolved once by the dispatcher: **process environment first, then the
credential store** the daemon itself reads (`<project>/settings/secrets.env`). Values are trimmed,
because the server trims — a client that did not would sign with a trailing newline and get an
opaque auth denial rather than a useful message. Absent from both, the trade tools return a clean
error naming both places and the create-and-backtest tools keep working. Which keys exist on this
box is answered by [`vike-cli secrets`](/docs/trader/reference/cli/set-up/secrets); which venue may arm at all is
[`policy.toml`](/docs/trader/reference/settings/policy).

## One vocabulary, two surfaces [#one-vocabulary-two-surfaces]

The write verbs resolve through the same construction site, the same client-order-id mint and the
same guardrail as the human [`trade` REPL](/docs/trader/reference/cli/trade/trade). Both used to build wire
commands independently and had already drifted — the REPL supported `modify` and `mass-cancel` while
the agent surface did not, and each carried its own copy of the guardrail. A new write verb is now
visibly missing from whichever surface forgets to expose it, rather than silently absent from one.


# Node status (/docs/trader/reference/cli/strategy-status)



<Callout type="warn" title="`strategy-status` is retired — the command is `vike-cli trade status`">
  There is **no alias and no named refusal**. The binary does not know the word `strategy-status`, so
  typing it is an unknown-verb error that names no replacement — unlike `sweep`, `walkforward` and
  `study`, which are refused *by name* with their successor printed. If you arrived here from a
  bookmark, the command you want is `vike-cli trade status --node HOST:PORT`.

  Ruling 17 folded the verb into the `trade` surface, which already holds an Observe connection to the
  node, and merged the REPL's old `state` read into it at the same time. `state` is gone — from the
  REPL and from `vike-cli trade` alike — because it was a READ and a WRITE on one word: `state`
  printed the mode, `state halted` **halted the daemon**, and the only thing between them was a second
  token. `halt` and `resume` are their own verbs now, named for what they do, and this one read
  answers both former questions. Most of what the old page described survived the move; the frame
  changed and the output gained the trading mode.
</Callout>

`trade status` is the shell-level answer to &#x2A;what is that daemon actually doing?* — the trading mode
and the mounted-strategy registry, in one output. It is read-only: it authenticates under the
observe scope and there is no spelling of it that writes.

The wire verb existed before the command did. Until this module the only way to ask a running node
what it was running from a shell was to compile a throwaway probe — the gap the I10 rehearsal found,
and the problem this command was built to solve.

## Two reads, because no single wire verb answers both [#two-reads-because-no-single-wire-verb-answers-both]

The registry comes from `vike_tradehub_client::strategy_status` (`Request::StrategyStatus`) and the
mode from `vike_tradehub_client::snapshot_once` (`Request::Snapshot`). Each is its own short-lived
`vike_tradehub_client::Scope::Observe` connection, registry first, mode second —
`crates/vike-cli/src/cmd/trade_status.rs`'s `run` performs them in that fixed order. Neither frame
carries the other's fields, and merging them would mean a `NODE_PROTO_VERSION` bump, which breaks
the handshake against every running node, to save one round trip on a command a human types.

**The registry read decides the exit code. It does not decide what is printed.** Both halves are
rendered as an answer *or a reason there is not one*, never as an absence:

* the mode read failed after the registry answered → the registry still prints, and the mode line
  (or, under `--json`, a `trading_state_error` key) says why it is missing;
* the registry read failed on a node that *answered* — one too old for the verb, or one refusing it
  — → the mode read is attempted anyway and printed, because `Request::Snapshot` is a base verb of
  the protocol that every node has always served. `crates/vike-cli/src/cmd/trade_status.rs`'s
  `mode_read_worth_attempting` carries the two kinds it deliberately does not retry under.

The exit stays the registry's, so a wrapper cannot read a partial answer as a whole one.

<Callout type="warn" title="Why the mode half is worth two connections">
  Until 2026-09-10 a registry failure returned before the mode read ran, so `trade status` against a
  node too old for the `strategy-verbs` capability printed no trading mode at all — the operator asked
  a halted node what it was doing and was told only to upgrade it. "Is this node halted" must not be a
  question you can ask and get silence to.
</Callout>

## Usage [#usage]

```sh
vike-cli trade status --node 10.0.0.5:9200
```

```sh
vike-cli trade status --node 10.0.0.5:9200 --json
```

| flag               | meaning                                                                    |
| ------------------ | -------------------------------------------------------------------------- |
| `--node HOST:PORT` | the node's observe address. **Required** — there is no default node to ask |
| `--json`           | the node's answer as JSON instead of the table                             |
| `-h`, `--help`     | the usage text, on stdout, exit `0`                                        |

Both spellings of the valued flag parse — `--node 10.0.0.5:9200` and `--node=10.0.0.5:9200` — and a
token beginning `--` is a flag, never a value, so a dangling `--node` is a named usage error rather
than an address of `--json`. That rule is `crates/vike-cli/src/cmd/args.rs`'s `is_flag_token`,
spelled once for every subcommand because without it a valued flag ate whatever followed it,
including another flag. `--json` is a bare boolean and rejects an inline value (`--json=1` →
`--json takes no value`). An unknown argument is rejected by name. See
[global flags](/docs/trader/reference/cli/global-flags).

A **bare word is a usage error, never a write**: `trade status halted` is rejected as an unknown
argument, because the grammar takes flags only. That is the whole of ruling 17 expressed in the
parser — nothing that changes the daemon's mode may be spelled by adding a word to something that
does not. `crates/vike-cli/src/cmd/trade_status.rs`'s `parse` is where it is enforced, and
`a_bare_mode_word_is_a_usage_error_and_never_a_write` pins it for `halted`, `reducing`, `active` and
`state` alike.

## One credential, and it is the observe one [#one-credential-and-it-is-the-observe-one]

Both wire verbs are read-only, so the node answers them under either scope, and both client
functions always connect under `Scope::Observe`. The command therefore needs exactly one key:
`VIKE_TRADEHUB_OBSERVE_KEY`, resolved by the dispatcher the same way `trade` and `mcp` resolve
theirs — &#x2A;*the process environment first, then `<project>/settings/node.env`**, the same node-key
store the daemon itself reads. `crates/vike-cli/src/cmd/nodekeys.rs`'s `resolve` argues that
precedence: an `export` is ephemeral, narrow and deliberate, while the store is the box's standing
configuration.

That same function **trims** whichever value it picks, because the server's
`vike_tradehub_client::auth::from_vars` trims too, and the agreement is load-bearing rather than
tidiness: an untrimmed client signs with `secret\n` against a server verifying `secret`, and the
mismatch comes back as an opaque auth refusal instead of *your key file has a trailing space*.

A box whose pair is still in the older `<project>/settings/secrets.env` keeps authenticating — the
fallback is a migration, not a deprecation that breaks a running deployment — and is told once, on
stderr, which file it read and which file the pair belongs in now. `vike-cli backend setup` writes
the new one. Nothing about the migration reaches stdout, which `--json` makes a document.

<Callout type="warn" title="A control key cannot stand in for an observe key">
  The node verifies each scope against its own key, so "has any key" would be the wrong question here.
  `crates/vike-cli/src/cmd/trade_status.rs`'s `run` asks for the observe half specifically, and the
  absent-key message is the observe-specific `NodeKeyring::observe_absent_message` — it names the
  variable, both places it was looked for, and the store path a key would go in. No connection is
  attempted without a key, so nothing about the address is reported.
</Callout>

## Output [#output]

Human form: the trading mode, a daemon identity line, the daemon's effective-params line, a blank
line, then one aligned row per mount. Column widths come from the data, headers included, so a long
strategy name cannot shear the params column. The mode cell is uppercase exactly when it matters —
`LIVE` shouts, `paper` is the quiet default. The rendering is pure and pinned on a two-mount
fixture, one paper row and one live:

```text
trading state: Active
node hub-a — paper — build vike-tradehub 0.1.0 (abc1234, clean)
params: spread=0.01 size=20

  STRATEGY      MODE   PARAMS
  spread_maker  paper  venue=polymarket symbol=TOK-A spread=0.01
  np            LIVE   venue=polymarket symbol=TOK-B edge=0.02
```

The mode is first because an operator asking what a node is doing reads the kill switch before the
roster, not after it. `trading state:` is `Active`, `Reducing` or `Halted`, and when the core sits
in safe state a second line follows it:

```text
  FAULT (core halted safe-state): fold panic in engine 0
```

That block is `crates/vike-cli/src/cmd/trade_status.rs`'s `mode_lines`, which sits in this command's
own module rather than in `crate::cmd::trade`, because three surfaces render it — this verb, the
REPL's `status`, and the REPL's `snapshot` — and they may not word a kill switch differently. Before
ruling 17 there were two spellings of it and they already disagreed.

### `--json` [#--json]

The payload the node sent is nested **verbatim** under `strategy_status`, with the mode fields
beside it. The nesting is the point: a machine consumer gets the wire schema, which cannot drift
from the node's, rather than a second hand-maintained shape. The two mode keys have no wire struct
of their own to be verbatim about. The document is **pretty-printed** —
`crates/vike-cli/src/cmd/trade_status.rs`'s `json_body` ends in `serde_json::to_string_pretty` — so
it spans lines: read it with a parser, not with a line filter.

| key                     | present when                               | value                                                                                                   |
| ----------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `trading_state`         | the mode read answered                     | `"Active"`, `"Reducing"` or `"Halted"`                                                                  |
| `fault`                 | the mode read answered                     | the safe-state fault string, or `null`                                                                  |
| `trading_state_error`   | the mode read failed, or was not attempted | the reason, as a string                                                                                 |
| `strategy_status`       | the registry read answered                 | the `vike_tradehub_client::wire::WireStrategyStatus` payload — `identity`, `effective_params`, `mounts` |
| `strategy_status_error` | the registry read failed                   | the reason, as a string                                                                                 |

**A half that could not be read is a key, never an omission.** No mode is invented — `trading_state`
and `fault` are genuinely absent when the read failed — and `trading_state_error` is what stops the
document reading as *this node has no mode*. The earlier shape dropped the mode keys in silence, on
the argument that a consumer requiring `trading_state` would fail loudly; that holds for a strict
typed deserializer and for nothing else. `jq .trading_state` answers `null` for an absent key exactly
as it does for a null one, `serde_json::Value` indexing returns null for both, and a human sees a
document with one fewer line.

A mode read that was **made** and failed puts its reason on stderr as well, in both output modes,
because a `--json` stdout is a document a script parses, not a transcript anyone reads. A mode read
that was never **attempted** gets no line of its own: `crates/vike-cli/src/cmd/trade_status.rs`'s
`run` guards that stderr line on a read that actually happened, and the reason it was skipped — the
registry failure — is already on stderr immediately above, where repeating it would bury it. The
JSON key is there either way.

## The three registry failures, and what each one tells you [#the-three-registry-failures-and-what-each-one-tells-you]

`crates/vike-cli/src/cmd/trade_status.rs`'s `failure_lines` is pure, so each wording is pinned by a
unit test rather than needing a downgraded daemon to reproduce.

| condition                         | what is printed on stderr                                                                                                                                                                                                                                        |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `io::ErrorKind::Unsupported`      | the feature-negotiation refusal: the node's `Welcome` advertised no `strategy-verbs` capability. The client's own sentence names the missing capability and says nothing was sent; the added line is the action — upgrade that node's `vike-tradehub` and re-run |
| `io::ErrorKind::PermissionDenied` | the observe handshake itself was refused. Points at the key, not the verb, and names `vike-cli secrets path` as the way to see which store this side read it from                                                                                                |
| anything else                     | an honest transport-shaped report naming the address                                                                                                                                                                                                             |

There is no fourth arm, and one case is worth naming because the exit table below does separate it:
`io::ErrorKind::InvalidData` — the node answered and refused the verb, which is what a publisher
with no identity block sends — lands in that last row and prints the same `cannot query` line as an
unreachable socket. Where it *is* singled out is the rung
(`crates/vike-cli/src/cmd/trade_status.rs`'s `failure_exit`) and the retry
(`crates/vike-cli/src/cmd/trade_status.rs`'s `mode_read_worth_attempting`), never the wording. Do
not go hunting a distinct InvalidData message on a live box.

Every one of those lines names the verb as the operator typed it, from a single constant, so a
message can never point back at the retired top-level spelling.

The old-node refusal is **client-side**: the verb is feature-negotiated through
`crates/vike-tradehub-client/src/proto.rs`'s `FEATURE_STRATEGY_VERBS`, and against a node that does
not advertise it the client sends nothing after the handshake. An older node's serde cannot decode
the frame, so sending would produce an opaque decode error at the node instead of a diagnosis here.
The end-to-end test scripts exactly that node and asserts the connection carried no frame at all.

## Exit codes [#exit-codes]

The rule is **did the node answer**. Everything a reachable box can tell you is a permanent
configuration fact, and a wrapper that retries one of those retries it forever; only a socket that
never got an answer is worth backing off and trying again.
`crates/vike-cli/src/cmd/trade_status.rs`'s `failure_exit` decides the rung over the same
`ErrorKind` match that decides the words, so the two cannot come to disagree about which failure is
which.

| outcome                                                                                                                                                   | exit                                                                |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| the registry read answered                                                                                                                                | `0` — including when the mode read failed; that half is best-effort |
| the node answered and refused: too old (`Unsupported`), observe key rejected (`PermissionDenied`), node-side error or unexpected response (`InvalidData`) | `1`                                                                 |
| no answer came back: connection refused, unroutable, timed out, aborted                                                                                   | `3`, the connect rung                                               |
| no observe key resolved anywhere                                                                                                                          | `1`                                                                 |
| usage error — an unknown argument, a bare word, a missing `--node`, `--json=1`                                                                            | `2`, the usage rung, on stderr                                      |
| `-h` / `--help`                                                                                                                                           | `0`, on **stdout**                                                  |

Those last two rows are decided in one place for the whole binary —
`crates/vike-cli/src/cmd/args.rs`'s `exit_for_parse_error`, which turns the help short-circuit into a
success on stdout and puts everything the parser rejected on the usage rung rather than the
run-failure one — and `crates/vike-cli/tests/help_cli.rs` runs the real binary to assert the status,
the stream, and that no internal token leaks. The rungs themselves are
`crates/vike-cli/src/exit.rs`'s `Exit`, and the split is what a wrapper branches on: a `2` is yours
to fix, a `3` is worth waiting on, a `1` means it ran and failed. A misspelled flag and a node that
answered and refused are deliberately **not** the same rung.

## What is covered [#what-is-covered]

The grammar, every renderer and both halves of the failure mapping — the words and the rung — are
pure and unit-tested in the module itself. The connections are
`crates/vike-cli/tests/trade_status_cli.rs`, which drives the shipped binary against a real loopback
node with no credentials, no venue and no external network:

* `trade_status_renders_the_mode_the_node_identity_and_mount_rows` — both wire reads, the mode above
  an identity line and one row per mount, and nothing on stderr on the happy path;
* `trade_status_json_nests_the_wire_payload_beside_the_mode` — the machine surface parses and
  carries the node's own field names;
* `an_identity_less_node_is_an_honest_error` — the server-error path exits `1`, never `3`, and the
  mode still comes back;
* `an_old_node_is_refused_client_side_but_still_answers_the_mode` — a scripted node lacking
  `strategy-verbs`: an actionable message, no frame sent on that connection, and the mode asked for
  and printed on a second one;
* `a_failed_mode_read_is_a_json_key_and_a_stderr_line` — the other direction, a node that answers the
  registry and refuses the snapshot;
* `with_no_observe_key_anywhere_the_message_names_both_sources` and
  `legacy_keys_still_authenticate_and_say_so` — the absent-key message, and the `secrets.env` box
  that must keep working and must be told where the pair belongs now.

## See also [#see-also]

* [`vike-cli trade`](/docs/trader/reference/cli/trade/trade) — the surface this verb lives in. `halt` and
  `resume` are the verbs that change the mode, and they authenticate with the CONTROL key
  (`VIKE_TRADEHUB_CONTROL_KEY`), not this read's observe one. `halt` and
  `resume` are the verbs that change the mode
* [The node protocol](/docs/trader/concepts/node-protocol) — the keys, the frames, the handshake
* [`vike-cli secrets`](/docs/trader/reference/cli/set-up/secrets) — where the key was read from
* [`vike-tradehub`](/docs/trader/reference/binaries/vike-tradehub) — the daemon on the other end


# vike-cli surface (/docs/trader/reference/cli/surface)



`vike-cli surface` writes this binary's own command-surface data as JSON. It runs anywhere `vike-cli` runs — a developer's prompt or a release workflow against a bare checkout — because it reads no settings, opens no credential store, and dials no daemon. The table it prints is compiled into the binary, so the answer is a property of the build, not of the environment it runs in.

## What it writes [#what-it-writes]

The verb is a thin writer over `crates/vike-cli/src/surface.rs`'s `rendered_files`. The table and its rendering live entirely in that module; `crates/vike-cli/src/cmd/surface.rs`'s `run` only decides where the bytes land (stdout, a directory, or nowhere but a name list), so a release workflow and a developer at a prompt reach identical output.

`rendered_files` returns one asset today: `cli.json`, named by `crates/vike-cli/src/surface.rs`'s `CLI_JSON` constant. The docs site fetches published assets like this one from the public mirror's latest release and renders committed MDX from them at prebuild — the Rust-side obligation is to produce the asset, never to decide how a page looks.

`crates/vike-cli/src/surface.rs`'s `PLANE` constant is `"backtest"`. Everything `cli.json` describes today — sub-verbs, flags, rosters, refusals — is the `vike-cli backtest` plane. It says nothing about `trade`, `mcp`, `datahub`, or any other verb; there is no second plane wired in yet.

<Callout type="warn" title="The schema version is a declaration, not a gate">
  `crates/vike-cli/src/surface.rs`'s `SCHEMA_VERSION` is not checked against `cli.json` specifically — the docs site's own asset-freshness check reads only `stats.json`'s version field, so a `cli.json` declaring a version the site can't read is rendered anyway. What actually protects the site is that its fetch is all-or-nothing: every published asset is fetched together, and any one of them failing to fetch or parse demotes every asset — `cli.json` included — to the last committed snapshot, silently. A malformed `cli.json` costs the site a release's worth of freshness for being malformed, not for its version number.
</Callout>

## Usage [#usage]

```
vike-cli surface [--out DIR] [--list]
```

With neither flag, every asset prints to stdout, one after another. `--list` and `--out` are read in that order inside `crates/vike-cli/src/cmd/surface.rs`'s `run`: if both are given, `--list` wins outright and nothing is written to disk.

| flag           | takes a value                   | effect                                                                                                                              |
| -------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `--out DIR`    | yes, `--out DIR` or `--out=DIR` | creates `DIR` if it doesn't exist, writes each asset into it under its own name, and reports each write to stderr as `wrote <path>` |
| `--list`       | no (`--list=1` is refused)      | prints each asset's name, one per line, and writes nothing                                                                          |
| `-h`, `--help` | no                              | prints the usage line above to stdout and exits 0                                                                                   |

Print the current surface to stdout:

```sh
vike-cli surface
```

List the published asset names without writing anything:

```sh
vike-cli surface --list
```

Write the assets to a directory, for a release workflow or a local docs-site checkout to pick up:

```sh
vike-cli surface --out dist
```

That last form creates `dist/` if needed, writes `dist/cli.json`, and logs `wrote dist/cli.json` to stderr.

An unrecognized flag is refused by name (`crates/vike-cli/src/cmd/surface.rs`'s `parse`), the same shape every other verb's flag loop uses.

## Why a subcommand, not `--help --json` [#why-a-subcommand-not---help---json]

Help already has a channel: it travels back through the `Err` path as `crates/vike-cli/src/cmd/args.rs`'s `HELP_SENTINEL`, and `exit_for_parse_error` turns that sentinel back into the static usage text on stdout at exit 0. That path carries no payload — it can print one fixed string, never a document. Making `--help` emit JSON would need a second sentinel, and any reply that isn't byte-equal to a sentinel falls through to the ordinary `eprintln!` usage-error arm — so a near-miss between the two sentinels would silently read as a usage error instead of as JSON, which is a failure `exit_for_parse_error`'s own doc already records having happened. A separate subcommand has no sentinel to collide with: it returns its data through the normal exit path instead of hijacking the help path.

## Why not a second binary [#why-not-a-second-binary]

`crates/vike-cli/Cargo.toml` declares no `[[bin]]` section — there is exactly one binary in this crate. `crates/vike-ops/tests/packaging_gate.rs` polices that manifest, but against a different property: that its release-asset template cannot drift from what actually ships, not a one-binary invariant. An `xtask`-style side binary would face the same objection from the other direction: either shape joins the release matrix for the sake of producing one JSON file. Folding the writer into the existing binary as a subcommand means the release workflow's own `vike-cli` build is the thing that renders `cli.json`, with nothing extra to build, sign, or ship.

## Related [#related]

[backtest](/docs/trader/reference/cli/research/backtest)


# Parameter search (/docs/trader/reference/cli/sweep)



<Callout type="warn" title="`vike-cli sweep` is retired — the command is `vike-cli backtest run`">
  A search is a backtest run many times and ranked, so it stopped being a verb of its own. The old
  spelling is **refused by name and prints its replacement**: `crates/vike-cli/src/lib.rs`'s
  `RETIRED_COMMANDS` carries the row and the sentence, so it is not the unknown-command shrug a
  genuinely non-existent verb gets. (`crates/vike-cli/src/cmd/backtest.rs`'s `LIST_PARAMS_RETIRED` is
  the same doctrine one level in, for the `--list-params` mode flag.)

  **What to type instead:** put a non-empty `[paramscan]` table in the profile and run
  `vike-cli backtest run --profile search.toml`. `--optimizer`, `--trials`, `--seed`, `--euler-depth`
  and `--rank-by` steer it; they do not decide that a search happens.

  The profile TABLE was renamed with the verb, and `[sweep]` is kept as a **permanent** serde alias —
  so no committed profile breaks. Writing **both** spellings in one file is a duplicate-field error.
</Callout>

`vike-cli backtest run` ships a profile's TOML **verbatim** to a compute daemon next to the data and
prints what comes back. What that profile SAYS decides what runs: a non-empty `[paramscan]` table
makes it a parameter search — the grid is expanded and the results ranked on the far side — and
everything else is one backtest. The predicate is
`crates/vike-backtest/src/harness/profile.rs`'s `is_paramscan` (present **and** non-empty), and the
engine and the compute server both branch on it.
`crates/vike-cli/src/cmd/backtest.rs`'s `declares_a_paramscan_grid` is this side's own presence
check over the same key — a separate function because `vike-cli` links no `vike-backtest`,
deliberately — so all three answer the same question the same way.

```
vike-cli backtest run --profile search.toml
vike-cli backtest run --profile search.toml --rank-by sharpe --addr 127.0.0.1:7880
vike-cli backtest run --profile search.toml --optimizer tpe --trials 128 --seed 7
vike-cli backtest run --local --profile search.toml --optimizer euler --euler-depth 3
```

## `[paramscan]` is the name; `[sweep]` keeps loading forever [#paramscan-is-the-name-sweep-keeps-loading-forever]

This is the pairing a reader most easily gets wrong, so it is stated as one rule:

* **`[paramscan]` is the name to write.** It replaced `[sweep]` when the verb moved.
* **`[sweep]` still loads, permanently.** `crates/vike-backtest/src/harness/profile.rs`'s
  `paramscan` field carries `#[serde(alias = "sweep")]`, and its doc argues why that alias has no
  end date: `BacktestProfile` is `deny_unknown_fields`, so removing the alias would make every
  profile ever written fail to load with "unknown field". It is not a deprecation.
  `both_the_new_section_and_the_legacy_one_load_and_parse_identically` pins that both spellings
  produce the identical parsed grid.
* **Writing both in one file is refused.** serde reports a duplicate field, and that is the correct
  answer rather than a gap — two grids in one profile has no meaning, and a silent winner is exactly
  the different-answer defect the rename exists to end
  (`writing_both_spellings_in_one_profile_is_refused`).
* **What kept the old spelling is what a PEER matches literally** — the Rust names moved with
  the section (`is_paramscan`, `expand_paramscan`, `run_paramscan`, `declares_a_paramscan_grid`),
  and `PROFILE_TOP_LEVEL_KEYS` carries its own correction of the narrower claim. What still says
  `sweep`: the wire tags (`#[serde(rename = "RunSweep")]` and its siblings), the `"sweep"` field
  key, the capability strings `run_sweep_profile`/`run_sweep`, the MCP tool name `run_sweep`, and
  the alias above. `crates/vike-cli/src/cmd/backtest.rs`'s `declares_a_paramscan_grid` carries that
  list and the reason: an identifier may move, a string another process compares against may not.

So: rename the section when you edit a profile, or leave it alone. Never add the new name beside the
old one.

```toml
# search.toml — everything a single-run profile has, plus the grid
name = "sma-cross-search"

[data]
venue = "binance"
symbols = ["BTCUSDT"]
kind = "bar"
interval = "1h"
from = "2026-01-01T00"
to = "2026-02-01T00"

[engine]
cash = 100000.0
fee_rate = 0.001

[strategy]
name = "sma_cross"

[strategy.params]
fast = 10
slow = 20

[paramscan]
fast = [5, 10, 20]
slow = [20, 40]
```

`[data]` and `[engine]` are there because they are **required**: neither field of
`crates/vike-backtest/src/harness/profile.rs`'s `BacktestProfile` carries `#[serde(default)]`, so a
profile without them fails to load with a missing-field error before anything runs.

## The grid grammar [#the-grid-grammar]

`crates/vike-backtest/src/harness/sweep.rs`'s `expand_paramscan` turns that table into the cartesian
product of single-run profiles:

* Each **key** names a `strategy.params` field the point overrides.
* Each **value** must be a **non-empty TOML array** — that is one axis of the grid.
  `sweep_axis_array` is the one reader every optimizer lane shares, so a non-array or an empty array
  is refused with the same sentence whichever method runs.
* The order is **deterministic**: axes sorted by key, values in their array order.
* Each expanded point clears the grid section, so every point is itself a plain, runnable
  single-backtest profile (`ParamscanPoint`).
* An absent or empty table expands to exactly one point with no overrides — the non-search path,
  unchanged.

The profile above is 3 × 2 = 6 points.

`--param` cannot build a grid. A range-looking value is refused by
`crates/vike-cli/src/cmd/backtest.rs`'s `parse_run_args`, which tells you to declare a `[paramscan]`
table instead — a `--param` that wrote a grid would silently reroute the request and change the
response document with nothing in the output saying so.

## The flags that steer a search [#the-flags-that-steer-a-search]

| flag                                                | meaning                                                                                                                                                                                                                                                                                         |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--profile <path>`                                  | the profile, as a BASE the other flags override. Optional: a grid can also be built with no file at all, since `--set paramscan.fast='[5, 10, 20]'` lands a non-empty table on the text that crosses the wire. A command line carrying neither a file nor anything to build one from is refused |
| `--rank-by <metric>`                                | `sharpe` · `return` · `max_dd` · `equity` · `multi`. Absent = whichever side runs applies its own default, annualized Sharpe                                                                                                                                                                    |
| `--optimizer <method>`                              | `grid` · `euler` · `tpe` · `genetic`. Absent is forwarded as absent — this side substitutes no default                                                                                                                                                                                          |
| `--euler-depth <n>` · `--trials <n>` · `--seed <n>` | the per-method knobs, forwarded **verbatim**                                                                                                                                                                                                                                                    |
| `--addr <host:port>`                                | the compute daemon; default `127.0.0.1:7880`                                                                                                                                                                                                                                                    |
| `--local`                                           | run on this machine by driving the standalone engine instead of dialling a server                                                                                                                                                                                                               |
| `--json`                                            | print the server's JSON verbatim                                                                                                                                                                                                                                                                |
| `--show-effective`                                  | print the resolved profile with each override's origin and stop, exit 0, dialling nothing                                                                                                                                                                                                       |
| `-h`, `--help`                                      | print the usage to stdout and exit 0                                                                                                                                                                                                                                                            |

That `--set` route is not an accident of the parser:
`crates/vike-cli/src/cmd/backtest.rs`'s `PROFILE_TOP_LEVEL_KEYS` names **both** `paramscan` and
`sweep` precisely so a key the engine accepts cannot be a CLI usage error, and a bracketed value is
typed as a TOML array by `parse_scalar`.

`--rank-by` and `--optimizer` are validated **locally** against their rosters
(`crates/vike-cli/src/cmd/backtest.rs`'s `RANK_METRICS` and `OPTIMIZERS`, through `one_of`), so a
typo is a usage error instead of a wasted round trip. That is a **spelling** check and never a second
implementation: what a metric or a method MEANS is computed by `vike_backtest::harness`, on whichever
side runs. The three method knobs are not parsed here at all —
`crates/vike-cli/src/cmd/backtest.rs`'s `wire_search` says why: `vike_backtest::harness::search_select`
is the one authority for what `--trials abc` means and for the sentence that refuses it, this crate
cannot call it, and forwarding the token is what keeps that sentence single on both routes.

**`--rank-by` names how to ORDER results, not what work to do.** A valid value is therefore *ignored*
— not an error — on a profile with no grid. `--optimizer` is the opposite: it says what work to do,
so `crates/vike-cli/src/cmd/backtest.rs`'s `route_of` sends a gridless profile to the search verb
anyway, where the side that runs refuses it by name. `search_requested` is the predicate, and it
deliberately excludes `--rank-by`.

<Callout type="warn" title="One guard did NOT come across, and the difference is worth knowing">
  `sweep` refused a profile with no grid before doing anything, because it PROMISED a grid.
  `backtest run` promises nothing of the kind — the profile decides — so the same input is now one
  backtest, on both routes, at exit 0. That is the correct answer rather than a lost check, and
  `crates/vike-cli/src/cmd/backtest.rs`'s module doc keeps the dropped guard beside its reason. What
  is still covered is the case that asks for work which cannot happen: `--optimizer` on a gridless
  profile, routed to the search verb by `route_of` and refused on whichever side runs.
</Callout>

## The whole TOML crosses the wire, and that is still the point [#the-whole-toml-crosses-the-wire-and-that-is-still-the-point]

The profile text is shipped as written; the SERVER parses and validates it with
`crates/vike-backtest/src/harness/profile.rs`'s `from_toml_str`. There is one profile parser in the
workspace and one date parser, and a search therefore honours the whole profile — `[engine].fee`,
`[engine.impact]`, `[engine.resolution]`, `[risk]`, `snap_to_properties`, a tick slice, a
cross-venue `[[data.series]]` slice — under the same costs as the same profile's single backtest.
Ranking and every printed statistic are the server's own `BacktestReport` numbers; nothing is
recomputed client-side, per the rule that no metric is reimplemented outside `vike-backtest`.

<Callout type="warn" title="A search once ran under different costs than the same profile's backtest">
  That rule is load-bearing rather than tidiness, and the list above is the bill. This command used to
  re-parse the profile into `WireSpec`/`WireSlice`/`WireSweep` DTOs — a SECOND profile parser and a
  SECOND date parser in the workspace — and that mapping could carry none of those keys: a profile
  that declared a fee, an impact model, a resolution, a `[risk]` table, a tick slice or a cross-venue
  series ran here with them and ran on the server without them, silently. It also shipped a local
  re-implementation of Sharpe, max drawdown and total return, which went with it.
</Callout>

`--preset` and `--script` are **client-side rewrites of the profile text**, applied before anything
is sent, so they are resolved against YOUR filesystem rather than the server's. Both behave
identically under `--local`: `crates/vike-cli/src/cmd/backtest.rs`'s `execute_local` stages the
rewritten text and hands the engine that, so a local run is a byte-identical rehearsal of a remote
one. Routing runs on the rewritten text too, so a grid that arrives through a preset routes as a
search.

To see exactly what would be sent, without sending it:

```
vike-cli backtest run --profile search.toml --preset fast.toml --show-effective
vike-cli backtest run --profile search.toml --write-profile resolved.toml
```

`--write-profile` writes the built profile and then runs. It refuses an existing path — this is the
one file the verb writes, and clobbering a committed profile from a flag typo is unrecoverable.

## The output [#the-output]

One row per grid point, in the order the **server** ranked them, rendered by
`crates/vike-cli/src/cmd/backtest.rs`'s `print_paramscan`. Every number is read straight out of that
row's report.

```
parameter search — 6 point(s), ranked server-side by sharpe
rank  overrides                             final_equity     return    sharpe    max_dd   trades
```

The `overrides` column renders each row's pairs as `k=v, k=v`, printed through the values' own
`Display` so nothing is re-typed on the way — they are TOML scalars serialized into JSON by then,
so it is serde\_json's (`fmt_overrides`). A method that has a budget — euler, tpe
— prints its own cost line BETWEEN those two lines, above the column header; the exhaustive grid
carries none and prints none.

A point that failed **never fails the whole search**: it comes back as that row's error and the row
still prints, so you can see which point failed and why.

```
   7  fast=5, slow=40                     FAILED: <the server's message>
```

An empty grid prints `(the search returned no grid points)`.

`--json` prints the server's document verbatim. There are **three** documents, one per route — a
single report, a ranked search report, a walk-forward report — and which one arrived is decided by
the route, not by a flag.

```
vike-cli backtest run --profile search.toml --json
```

## Where it runs, and what it costs [#where-it-runs-and-what-it-costs]

**The address is a three-rung ladder**, folded by `crates/vike-cli/src/cmd/backtest.rs`'s
`resolve_addr`: `--addr` → `settings/config.toml`'s `backtest_addr` → the workspace constant
`DEFAULT_BACKTEST_ADDR`, `127.0.0.1:7880`. A blank value is treated as absent rather than dialled.
That function's own doc names the digits — `7880` the **compute** daemon (`vike-backend backtest --addr`), `7878` the data server — and the module doc above it adds that the daemon binds localhost
only, so reach a remote one over a tunnel:

```
ssh -L 7880:localhost:7880 <host>
```

**Auth scope is `Control`, not `Observe`.** Every profile-running verb is grouped with the write and
destructive ones because each one compiles client-supplied Rhai on the server. With no keys the dial
is unauthenticated, which is what a key-less server has always answered.

**A daemon too old to honour a search selector is refused locally, and nothing is sent.** It would
otherwise decode the frame, drop the selector, run the exhaustive grid and report success — a silent
downgrade. The client checks the handshake's feature list first and fails on the ordinary failure
rung, naming the capability.

**Parallelism multiplies memory, so it is bounded.** Every point re-materializes its own data slice,
so peak RSS is `threads × slice`, not `1 × slice`. The points run on a bounded pool of
`crates/vike-backtest/src/harness/sweep.rs`'s `sweep_threads` workers — `min(4, cores)` by default,
raised with `VIKE_SWEEP_THREADS` on the box that RUNS the search — and `VIKE_SWEEP_SEQUENTIAL=1` pins
that process back to one at a time. Both produce byte-identical reports: the collect preserves input
order and the ranking sort is stable, so scheduling cannot change the answer (`ParamscanExec`).

## `--local` [#--local]

`--local` drives the standalone `backtest` engine on this machine instead of dialling anything —
spawned, never linked, because this crate's identity is being DataFusion-free. `--store DIR` names
the hist-store root and `--engine PATH` names the binary outright; both are refused without
`--local`, where they would describe the wrong machine. `--addr` beside `--local` is refused for the
mirror-image reason.

Since the wire carries a method selector, `--optimizer`, `--euler-depth`, `--trials`, `--seed` and
`--rank-by multi` all work on **both** routes, and a knob refused under the wrong method is refused
with the same sentence whichever one ran.

A release attaches that engine beside `vike-cli` on **Linux only**, so on Windows this arm needs an
engine you built or fetched yourself; the missing-engine message says so.
`crates/vike-cli/src/cmd/engine.rs`'s `locate` is what looks for it, and that module's doc is the
authority on the asymmetry and on the search order —
[the standalone `backtest` binary](/docs/trader/reference/binaries/backtest) is its reference page.

## Composing with a walk-forward [#composing-with-a-walk-forward]

`[walkforward]` is a sibling table, and the two axes do not compete: the grid says WHAT is computed,
`[walkforward]` says HOW it is validated. A profile declaring both is carried by the walk-forward
wire verb, and nothing on this side refuses the pair — `crates/vike-cli/src/cmd/backtest.rs`'s
`route_of` is the whole map.

**Whether each window re-searches the grid is a key in the profile, not the pairing itself.**
`crates/vike-backtest/src/harness/profile.rs`'s `window_search` reads `[walkforward].search`:
absent or `"none"` is the no-search CONTROL — every window trades the profile's own
`[strategy.params]`, grid or no grid — while `"sweep"` scores the grid on each window's training
half and carries only the winner onto its validation half. `"grid"` was a synonym for one release
and is now refused by name telling you to write `"sweep"`, and `"sweep"` with no grid is refused at
load by `BacktestProfile::validate`, because every window would "select" the one parameter set it
already has. So the composing profile says:

```toml
[walkforward]
n_splits = 5
search = "sweep"
```

⚠ &#x2A;*Declared residual, and it is on the far side.** Ruling 4 deletes that key — the presence of the
two sections becomes the statement — and until it lands, a profile declaring both tables and
omitting `search` routes correctly from here and runs UNSEARCHED there, at exit 0, with nothing in
the report saying so. `route_of`'s own doc carries it.

Two consequences for this page's flags. `--rank-by` and `--optimizer` are **refused by name** on a
walk-forward profile rather than dropped, because the wire verb that carries it takes the profile
TOML and nothing else — a window's ranking is `[walkforward].rank_by`, in the profile
(`refuse_a_walkforward_flag`). And `--local` cannot run one at all: the standalone engine has one
profile path, branching on the grid and nothing else, so there is nothing to spawn
(`WALKFORWARD_HAS_NO_LOCAL_ARM`).

## Exit codes [#exit-codes]

| code | when                                                                                    |
| ---- | --------------------------------------------------------------------------------------- |
| `0`  | the server returned a report                                                            |
| `2`  | a bad command line — an unknown flag, a `--rank-by`/`--optimizer` typo, a mode conflict |
| `3`  | the daemon could not be reached                                                         |
| `1`  | everything else — an unreadable profile or preset, a server-side error response         |

The failure message goes to **stderr** on every rung.

## Related [#related]

[`backtest`](/docs/trader/reference/cli/research/backtest) is this verb's own reference page — the profile-building
flags, the single-run output, the stored-run sub-verbs. [search](/docs/trader/backtesting/search) and
[sweeps](/docs/trader/backtesting/sweeps) are the difference between an exhaustive grid, a halving
schedule and a TPE run; [running a search on the data service](/docs/trader/guides/sweep-on-the-service) is
the end-to-end walkthrough including the tunnel.
[walkforward](/docs/trader/reference/cli/walkforward) is the anchored out-of-sample validation you run over
a search's winner, and [validation](/docs/trader/analytics/validation) is why. The Studio's own wire verb —
still spelled `RunSweep`, like every other peer-visible string — is untouched and still serves the
GUI, which holds a picker's spec and slice rather than a profile file, and its wire verb is DTO-shaped — see
[remote runs](/docs/trader/gui/studio/remote-runs).


# Walk-forward (/docs/trader/reference/cli/walkforward)



<Callout type="warn" title="This verb moved — it is `vike-cli backtest run` now">
  Walking forward is how a run is **validated**, not a different kind of run, so it stopped being a
  verb of its own. Put a `[walkforward]` table in the profile and run `vike-cli backtest run` with
  the same file: `n_splits` is the window count and `mode`/`rank_by` shape it.

  ```text
  was:  vike-cli walkforward     --profile wf.toml
  now:  vike-cli backtest run    --profile wf.toml
  ```

  The old spelling is refused **by name** with that pairing printed — `vike-cli` carries it in
  `crates/vike-cli/src/lib.rs`'s `RETIRED_COMMANDS`, so a pasted old command tells you what to type
  rather than reading as a typo.

  ⚠ &#x2A;*There is no `--local`.** The standalone engine has no walk-forward driver to spawn, so unlike a
  plain `backtest run` this one has only the remote route.
</Callout>

The anchored out-of-sample sibling of [`backtest`](/docs/trader/reference/cli/research/backtest). Ship a profile's
TOML **verbatim** to a remote [`vike-datahub`](/docs/trader/reference/binaries/vike-datahub) server, run
the walk-forward there — the existing `vike_backtest::harness::run_walkforward`, next to the data —
and print the stitched out-of-sample result, with no DataFusion in this side's build graph
(`crates/vike-cli/src/cmd/walkforward.rs`).

```
usage: vike-cli walkforward --profile <run.toml> [--addr 127.0.0.1:7878] [--json]
```

| flag                 | meaning                                                                                                                                                 |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--profile <path>`   | **required.** A backtest profile `.toml`, shipped verbatim. Its `[walkforward]` table supplies `n_splits`, the number of anchored out-of-sample windows |
| `--addr <host:port>` | the data service address; default `127.0.0.1:7878`                                                                                                      |
| `--json`             | print the server's `WalkForwardReport` JSON                                                                                                             |
| `-h`, `--help`       | print the usage to stdout and exit 0                                                                                                                    |

`[walkforward]` is a first-class profile section like `[sweep]`, so **one file describes the whole
run** — see [run profiles](/docs/trader/backtesting/run-profiles). A profile with no `[walkforward]`
table comes back as a clean server-side error. Reach a remote server over
`ssh -L 7878:localhost:7878 <host>`.

## Bar mode, one series [#bar-mode-one-series]

<Callout type="warn" title="A tick or multi-symbol profile is a clean error, never a silent fallback">
  Server-side this is **bar** mode over **one** series: the splitter divides a single bar series by
  index. A tick profile or a multi-symbol profile is refused outright rather than quietly running on
  the first symbol it finds — which would produce a plausible report about a different experiment than
  the one the profile describes.
</Callout>

## Why the profile crosses the wire whole [#why-the-profile-crosses-the-wire-whole]

Like the [`sweep`](/docs/trader/reference/cli/sweep) sibling, this replaced a client-side profile→DTO
mapping whose `WireSlice`/`WireEngineParams` pair could not carry `[engine].fee` and the rest of the
`[engine]` surface. The server now parses the profile with the one `BacktestProfile::from_toml_str`
parser, so the walk-forward honours the whole `[engine]` — the [cost model](/docs/trader/backtesting/cost-model)
and [market impact](/docs/trader/backtesting/market-impact) a run was configured with are the ones it
actually ran under. The Studio's DTO-shaped `RunWalkforward` wire verb is untouched and still serves
the GUI ([remote runs](/docs/trader/gui/studio/remote-runs)).

## The output [#the-output]

One row per out-of-sample window, then the summary line. Every number is the server's own — nothing
is recomputed on this side.

```
walk-forward: 2 out-of-sample window(s)
window  test_range             oos_return
     1  [0, 60)                    +5.00%
     2  [60, 120)                  -2.00%

oos_return = +2.90%   oos_sharpe = 0.810   wf_consistency = 50.0%
```

`test_range` is the window's half-open bar index range as the server reported it. The three summary
scalars are the stitched out-of-sample return, its Sharpe, and the walk-forward consistency — the
fraction of windows that came back positive. What each one is for, and the trap of reading a single
number off a small number of windows, is on [walk-forward](/docs/trader/backtesting/walk-forward) and
[validation](/docs/trader/analytics/validation).

A degenerate report renders rather than breaking: a numeric field that is absent or `null` — which
is `serde_json`'s encoding of a non-finite `f64` — reads as `0.0`, so a run with no windows still
prints a table instead of failing at the printer.

Under `--json` the bytes are the server's own `WalkForwardReport`, including the `oos_equity_curve`
the human table does not draw.

## Related [#related]

The usual order is a [sweep](/docs/trader/reference/cli/sweep) to pick a parameter point, then this verb
over the winner; [overfitting](/docs/trader/analytics/overfitting) is why the second step is not
optional. [Running a backtest](/docs/trader/backtesting/running) covers running the same profile as a
single in-sample run first.


# alerts.json (/docs/trader/reference/settings/alerts)



`alerts.json` is not a settings file. It is program-written state, and it sits beside the four
[settings TOMLs](/docs/trader/reference/settings) rather than among them: it holds a rule set an editor
writes, it is loaded by a path its caller supplies, and its **absence is the off switch**.
`crates/vike-alerting/src/persist.rs` owns the file conventions and
`crates/vike-alerting/src/rule.rs` owns the model.

## Where it lives [#where-it-lives]

`vike-tradehub`'s `alerts_path` resolves it: `$VIKE_ALERTS` when set and non-blank, else
`<state_dir>/alerts.json`, where the state directory is `$VIKE_STATE_ROOT` if set and
`<project>/settings/state` otherwise. A blank override falls *through* rather than resolving to the
empty string — an empty systemd `Environment=VIKE_ALERTS=` line would otherwise point the loader at
the working directory. The answer is `None` when there is no override and no state directory
resolves, and the mount says so rather than reading somewhere else.

The environment read happens in the binary, deliberately: `persist.rs`'s header records that this
module reads no environment variable and resolves no path, that every entry point takes the file as
a `&Path`, and that `ALERTS_FILE` — the basename, `"alerts.json"` — is the single thing the library
states, so the caller composing the directory does not re-spell it. `load_path` reads and parses;
`save_path` writes it back pretty-printed.

<Callout title="A missing or corrupt file is never an error">
  `load_path` returns `None` when the file is absent, and on an unparseable file it logs a warning and
  returns `None` too. A bad file must never brick startup — the same never-brick discipline the
  workspace loader follows. Both cases mean *no rules configured*, which is the off state.
</Callout>

## The schema [#the-schema]

`AlertRuleSet` is the persisted container: a `version` (`#[serde(default)]`, so a file predating the
field loads as `CURRENT_VERSION`, which is `1`) and a `rules` vector. An empty set is the default and
the off state — nothing is evaluated and nothing is delivered, byte-identical to a build without the
alerting engine.

Each `AlertRule` carries:

* **`id`** — a stable unique id. It is the per-rule evaluation-state key, the cooldown and
  once key, and the delivery correlation id, so keep it stable across edits of a rule.
* **`name`** — a human label; it becomes the delivered message's title, falling back to the `id`
  when empty.
* **`enabled`** — defaults to `true`. A disabled rule is persisted but never evaluated,
  byte-identical to its absence.
* **`trigger`** — the condition, a `RuleTrigger`.
* **`targets`** — an `AlertTargets`; absent means the default, which is `in_process: true` and no
  webhooks.
* **`cooldown_ms`** — the minimum milliseconds between re-fires of the same rule, `0` for none. For a
  latched trigger it is redundant, since the latch already prevents a re-fire until re-arm; it is
  the primary rate limit for discrete-event triggers.
* **`once`** — fire at most once per process session, regardless of cooldown.

Forward compatibility is a discipline rather than a migration path: every field *added over time*
is `#[serde(default)]`, with `skip_serializing_if` where an absent key is the common case, so an
older `alerts.json` still loads and a rule that uses none of a field's feature writes no key for it.
`id` and `trigger` are the two that carry no default and are required on load — a rule with no
identity or no condition is not a rule.

`RuleTrigger` variants include `Price` (a published mark for a venue and symbol crossing a level,
edge-triggered), `Indicator` (a streaming-indicator output crossing a threshold — the rule stores
only the registry key, the output index and the parameter overrides, so it round-trips without a bar
dependency), `Fill`, `OrderRejected`, `Drawdown`, `ReconAlert`, `Feed`, `FillRateBreaker`,
`PolymarketResolution` and `SeriesStale`.

Two carry warnings in their own docs. &#x2A;*`Drawdown`** tracks the daemon's own equity curve —
configured capital plus realized and unrealized P\&L — drawing down from its running session peak,
latched so it fires once on breach and re-arms only after recovery; it is deliberately *not&#x2A; the
cross-venue equity total, because that includes each live venue's wallet, which a third party can
move, and it tracks the same quantity the core's own liquidate-only latch does so the two cannot
disagree. &#x2A;*`SeriesStale`** is the writer-stopped-writing condition and is deliberately not `Feed`:
feed health is venue-scoped and reports a transport transition, while this one is series-scoped and
reports an absence — the socket is established, the subscription returned `Ok`, no error is raised
and no row is lost, because there are no rows. Its `series_prefix` is a prefix match rather than an
equality test, because on a venue whose symbols rotate the series an operator wants to watch does
not exist yet when the rule is written.

## What a headless node can actually fire [#what-a-headless-node-can-actually-fire]

`crates/vike-tradehub/src/alerts.rs` is the headless mount, and its header is candid about the gap.
The engine accepts four inputs and the daemon has a real source for exactly one of them today, and
the module fabricates none of the others:

* **Fed** — `on_snapshot`, from the daemon's periodic summary tick. Usable triggers: `Price`,
  `Drawdown` and `ReconAlert`.
* **Unfed** — `on_event` (`Fill`, `OrderRejected`): the daemon has no typed event stream off-fold.
* **Unfed** — `on_indicator` (`Indicator`): a headless daemon computes no streaming indicators.
* **Unfed** — `on_signal` (`Feed`, `FillRateBreaker`, `PolymarketResolution`, `SeriesStale`).
  `SeriesStale` is the one whose producer exists and is simply somewhere else —
  `crates/vike-recorder/src/alerts.rs` raises it, and the daemon depends on no recorder crate.

Rules of an unfed kind still load and are still counted; they simply never fire there.

The mount is strictly off-fold: it consumes already-published state and never enters the core fold,
adding one `AlertEngine::on_snapshot` call per summary tick on a thread the core never waits on.
The **rules file is the gate**, not a second flag: `maybe_mount` returns `None` when there is no
file, when the file has zero rules, and when every rule in it is disabled — and `None` means no
engine, no sink constructed and no webhook target resolved.

## Delivery [#delivery]

`crates/vike-alerting/src/delivery.rs` defines the seam: a sink is a fire-and-forget consumer, the
engine broadcasts each fired alert to every registered sink, and each sink **self-filters** on the
alert's `AlertTargets`, so routing lives in the alert rather than in the dispatcher. Two sinks ship
in the crate — an in-memory buffer a future GUI would drain for toasts, which nothing mounts today,
and a Telegram or generic webhook POST over the workspace's existing HTTP and TLS stack, with the
blocking POST behind an injected transport so the seam never touches the network in CI. The daemon
always adds a log sink, because its stdout is protocol-only; no configured webhook target therefore
still leaves a real headless notification surface.

<Callout type="warn" title="A webhook secret never reaches Debug or a log line">
  A bot token or a webhook URL is redacted by a manual `Debug` impl, and a failed delivery logs the
  target **name** and a coarse error category only — never the endpoint URL, which for Telegram embeds
  the token, and never the raw transport error, which can echo the request target. Webhook
  configuration is built from a caller-supplied credential map, so nothing in the library can load a
  token its caller did not hand it.
</Callout>

[Alerting](/docs/trader/concepts/alerting) covers the rule model, the evaluator and the delivery seam as
a concept; [`vike-tradehub`](/docs/trader/reference/binaries/vike-tradehub) covers the daemon that mounts
them.


# config.toml (/docs/trader/reference/settings/config)



`crates/vike-config/src/config.rs` is the authority for this file. The distinguishing question its
header asks is &#x2A;would a second machine running the same strategy need a different value?* Store
roots, log directories and listen addresses all answer yes, which is why they carry the full
`defaults → file → env → CLI` chain: a container overrides a path with an environment variable, an
operator overrides a port with a flag for one run, and neither is a risk decision. Contrast
[`preferences.toml`](/docs/trader/reference/settings/preferences), whose values would be the same on the
second machine, and [`policy.toml`](/docs/trader/reference/settings/policy), which stops at the file layer
on purpose.

Every key is optional, and an omitted path key does not mean *no directory* — it means the reading
binary falls back to its own default, which is not the same for every binary.
`settings/config.example.toml` says so explicitly and points at `vike-cli config show`'s DEFAULT
column as the authority per key.

## The keys [#the-keys]

| key                      | environment variable          | absent means                                      | hot-appliable |
| ------------------------ | ----------------------------- | ------------------------------------------------- | ------------- |
| `store_root`             | `VIKE_HIST_STORE`             | the caller's own fallback                         | no            |
| `log_dir`                | `VIKE_LOG_DIR`                | `vike-log`'s own fallback                         | no            |
| `journal_dir`            | `VIKE_JOURNAL_DIR`            | —                                                 | no            |
| `state_dir`              | `VIKE_STATE_DIR`              | the project rung, then `<exe_dir>/strategy-state` | no            |
| `datahub_addr`           | `VIKE_DATAHUB_ADDR`           | the backend's advertisement, else the local store | no            |
| `tradehub_addr`          | `VIKE_TRADEHUB_ADDR`          | no control server                                 | no            |
| `datahub_advertise_addr` | `VIKE_DATAHUB_ADVERTISE_ADDR` | advertise nothing                                 | no            |

The hot column comes from `crates/vike-tradehub/src/hot_reload.rs`, whose classification table has
one row per key and whose `the_hot_set_is_exactly_the_two_log_levels` test pins the hot set to two
`preferences` keys — so **every `config.toml` key is restart-required**. That is always the safe
answer: the write is on disk, the next boot loads it, and the operator restarts and loses nothing.

**`store_root`** is the root of the DataFusion and Parquet history and tick store — see the
[history store](/docs/trader/concepts/hist-store). The field doc records why this key exists at all:
`VIKE_HIST_STORE` had five rows in `vike_ops::settings::SETTINGS`, because `vike-desktop`,
`vike-backtest`, `vike-backfill`, `vike-datahub` and `vike-studio` each read it with a *different*
fallback chain. One field with one default is the fix, and the divergent fallbacks become the
callers' business rather than the variable's. `vike-desktop`'s row moved first: its `studio_store_root`
takes `Config::store_root` and passes it to the same `vike_model::store_path::resolve_store_root`
precedence it always used.

**`log_dir`** is where the rolling JSON trace log is written; absent, `vike-log`'s own fallback
applies. The example file flags the neighbouring trap in bold: this is not the size knob. The file
layer defaults to `trace` and ignores `RUST_LOG` entirely, so the volume is turned down with
`preferences.log_file_level`.

**`journal_dir`** is the live core's memory-mapped write-ahead command journal directory; the
example file records that omitting it disables the journal.

<Callout type="warn" title="journal_dir is the one key here whose file layer is still inert">
  `vike_config::CONSUMPTION` carries it as a written admission that nothing reads the field:
  `VIKE_JOURNAL_DIR` is read by `crates/vike-core/src/run_profile.rs`'s `journal_config_from_env`,
  which resolves three variables at once — `VIKE_RUN_PROFILE`, `VIKE_JOURNAL_DIR` and
  `VIKE_JOURNAL_SNAPSHOT_EVERY` — and is called from `vike-desktop`, `vike-tradehub` and `vike-run`, so
  the whole family has to move together and the WAL directory stays an environment variable for now.
  Setting the key in `config.toml` configures nothing today; set the variable instead.
  `vike-cli config show`'s READ column prints `NO` for it and the `--json` view carries that reason.
  Every other key on this page is read from the file.
</Callout>

<Callout type="warn" title="state_dir is not the state root">
  `Config::state_dir` is the directory for program-written strategy state, and — as the example file
  puts it — it is `vike-desktop`'s strategy-state **sidecar** directory, not the state root that
  `vike-tradehub`, `vike-ops` and `vike-studio` resolve. That root is `<project>/settings/state/` and
  is not configurable from this file. The two have collided by name before;
  `vike_model::state_path`'s module doc records it. Setting this key on a headless box does nothing,
  because only the GUI reads it. Absent, it resolves the project rung
  `<project>/settings/state/strategy-state` and falls back to `<exe_dir>/strategy-state` only when no
  project sits above the working directory — `crates/vike-desktop/src/main.rs`'s `state_dir_path` is the
  resolver, and it takes that project rung off the boot's own walk rather than re-walking.
</Callout>

## Three addresses, three jobs [#three-addresses-three-jobs]

The `datahub_advertise_addr` field doc enumerates them, because two of the three are easy to
confuse:

* **`tradehub_addr`** — where the *daemon listens*. This is `vike-tradehub`'s bind address on the
  daemon's own box, and absent is the safe default: no control server at all, so the daemon trades
  headless with no network surface. The example file notes that setting it opens a socket, that
  observe is available to a peer holding an observe key, and that writes additionally need
  `flags.tradehub_control` — see [flags](/docs/trader/reference/settings/flags) and the
  [node protocol](/docs/trader/concepts/node-protocol).
* **`datahub_addr`** — where *this machine's client dials* a `vike-datahub` data server, usually
  over an SSH tunnel. Presence **is** the branch: set, and `vike-desktop`'s Studio takes its history
  from that server over RPC through a DataFusion-free `RemoteHistStore`, with the Studio's run
  backend also defaulting to remote at the same address; unset — the default — and a connected
  backend's advertisement fills in, with the local store at `store_root`'s resolution only when
  neither answers (the desktop has no local engine, so that arm is an error naming
  both fixes instead). This field lost its old always-set default for exactly that reason. An
  explicit value here always wins over any advertisement.
* **`datahub_advertise_addr`** — where the daemon *tells clients* to dial the datahub it fronts. Set
  it, and every `Welcome.features` the node server sends carries `datahub=<value>`, so a connected
  client with no `datahub_addr` of its own adopts it and one configured address reaches both planes.
  Absent advertises nothing. It is **advertisement, never proxying**: history and backtest traffic
  still dials the datahub directly, and nothing routes through the process holding live orders. Its
  value must be valid *from the client's side of the wire* — with the tunnel-only posture both
  servers ship with, that is the client-local tunnel mouth, not the daemon's private interface.

The `vike-datahub` server binary does not read this file at all: its own listen address is its own
`VIKE_DATAHUB_ADDR` environment read, defaulting to `DEFAULT_DATAHUB_ADDR`, which is
`127.0.0.1:7878`. `datahub_advertise_addr` is consumed on the daemon's box, by `vike-tradehub`'s
`start_observe_server`.

## Editing it [#editing-it]

`vike-cli config show --filter config` prints which layer actually won on this box; the
[config verb](/docs/trader/reference/cli/set-up/config) covers the flags. A write through
`vike_config::set_setting` preserves the file's comments and the formatting of every untouched line,
validates the resulting text through the loader before a byte lands on disk, and renames atomically
— so a crash mid-write leaves the old file intact rather than a truncated one.


# flags.toml (/docs/trader/reference/settings/flags)



`crates/vike-config/src/flags.rs` is the authority for this file. A flag is a thing an operator
turns on for a run: enable reconciliation, mount live execution, open a control surface, start a
recorder. Unlike a ceiling, *settable from the environment* is the right property here — that is how
a systemd unit, a container and a one-off shell all express intent, and the blast radius of a wrong
value is a feature that is on or off, not a risk limit that is wrong.

**Every flag defaults to `false`.** That is not tidiness: each one gates a live order path, a remote
write surface, a settlement poller or extra I/O, and the safe reading of an absent configuration is
*do the smaller thing*. Two shapes need the sentence read carefully and say so in their own docs —
`poly_redeem_halt` is a kill **switch**, where `false` means *not halted*, safe only because the
poller it halts is itself off by default; and `preflight_skip` and `allow_withdraw_keys` are safety
**overrides**, where `false` is the guarded state.

<Callout type="warn" title="A truthy typo is an error, not a silent false">
  The variables these mirror are read elsewhere as the exact string `"1"`, and anything else is
  silently false — so `VIKE_RECONCILE=true` is a run that reconciles nothing and looks completely
  normal. This crate's parser accepts `"1"` and `"0"` and rejects everything else by name and value.
  The one exception is `poly_redeem_halt`, whose live read is presence-based: the variable existing
  halts redemption whatever its value, empty included. Narrowing a kill switch to `"1"` would silently
  stop `POLY_REDEEM_HALT=` and `POLY_REDEEM_HALT=0` from halting anything, and a kill switch that
  fails to fire is the worst regression on the list.
</Callout>

## Owner, review date, disposition [#owner-review-date-disposition]

`FLAG_REGISTRY` carries a `FlagMeta` row per field: the field name — identical to the `flags.toml`
key, which `crates/vike-config/tests/flag_registry.rs` proves rather than assumes — the environment
variable, an owner, an ISO `YYYY-MM-DD` review date, and the `Disposition` that review is expected
to reach. The point is stated flatly in the module header: &#x2A;a flag with no owner is a flag nobody
will ever delete.* Every row names the same handle today, because the repository has one maintainer
and inventing team names would be fiction; the field exists so ownership can diverge later without a
schema change.

`Disposition` has three values.

* **`Keep`** — genuinely a per-run operator decision: a real-money arm, a kill switch, a safety
  override.
* **`Graduate`** — not really a per-run decision but how this deployment is set up, usually with
  non-boolean siblings — `*_CADENCE_MS`, `*_INTERVAL_MS`, a policy name — already sitting in
  [`config.toml`](/docs/trader/reference/settings/config).
* **`Retire`** — delete it, with the behaviour it gates becoming unconditional or dropped: the flag
  exists because something was unproven, and once it is proven, an option nobody should turn off is
  a branch nobody tests.

`flag_registry.rs` fails when a field has no row, when a row has no field, when an owner is blank,
when a date is malformed, and — because it drives every row through the real environment and file
layers — when a row's variable is wired to the wrong field. It deliberately does **not** fail once a
review date has passed: that would turn the calendar into a merge blocker on unrelated PRs, and a
settings crate must not be able to stop a trading fix from shipping.

## The flags, by group [#the-flags-by-group]

Every row below is `field` / `VARIABLE` / review date / disposition, from `FLAG_REGISTRY`.

**Reconciliation.** `reconcile` / `VIKE_RECONCILE` / 2026-11-01 / Graduate — the master gate; off
means no `ReconDriver`, no thread. `reconcile_generate_missing` /
`VIKE_RECONCILE_GENERATE_MISSING` / 2027-02-01 / Graduate. `reconcile_balance` /
`VIKE_RECONCILE_BALANCE` / 2027-02-01 / Graduate. The rest of the `VIKE_RECONCILE_*` family is
config, not flags — cadences, lookbacks and the policy name. See
[reconciliation](/docs/trader/concepts/reconciliation).

**Order emulation.** `oco_cancel_sibling_on_dead_exit` /
`VIKE_OCO_CANCEL_SIBLING_ON_DEAD_EXIT` / 2026-11-01 / Retire — *a bracket that half-survives its own
exit is a bug, not a preference*.

**The headless daemon.** `tradehub_live` / `VIKE_TRADEHUB_LIVE` / 2026-11-01 / Keep — the field doc
calls it the single largest blast radius on the list, and a real-money arm must stay a deliberate
per-run decision. `tradehub_control` / `VIKE_TRADEHUB_CONTROL` / 2026-11-01 / Graduate — the
authenticated control scope; off, a Control-scope peer is refused at the handshake however good its
key. `tradehub_allow_public_bind` / `VIKE_TRADEHUB_ALLOW_PUBLIC_BIND` / 2026-11-01 / Keep — a safety
override: that surface's handshake is plaintext and authenticates the connection rather than each
frame, so its confidentiality comes entirely from being unreachable, and the daemon refuses a
non-loopback bind while logging the SSH-tunnel alternative. It is a separate flag rather than an
inference from the address because the mistake it catches *is* typing an address, and no address can
be its own consent. `telegram_control` / `VIKE_TELEGRAM_CONTROL` / 2026-11-01 / Keep — sits under a
Cargo feature as well, so a default build does not compile the module at all. `tradehub_record` /
`VIKE_TRADEHUB_RECORD` / 2027-02-01 / Graduate. `cancel_orders_on_shutdown` /
`VIKE_CANCEL_ORDERS_ON_SHUTDOWN` / 2026-11-01 / Keep.

<Callout type="warn" title="cancel_orders_on_shutdown cancels; it never flattens">
  Off is what has always happened and stays byte-identical: teardown detaches and exits, and your
  quotes stay resting at the venue with nothing left running to manage them. That really is what an
  operator restarting for a deploy usually wants, which is why the safer-*sounding* value is not the
  default. Positions survive either way. And it can only run on a path that reaches teardown at all —
  `vike_ops::stop::install_handlers` registers SIGTERM/SIGINT onto the daemon's stop flag before
  anything else in `main`, so `systemctl stop` does run the teardown and does honour the flag. What
  bypasses it is a failed handler install (reported as an error at startup), a platform with neither
  signals nor a Windows console, or a SIGKILL after the unit's stop deadline.
</Callout>

**Polymarket.** `poly_exec` / `POLY_EXEC` / 2026-11-01 / Graduate — mounts the live execution
client, and inseparably starts the user-WS fill pump, because on that venue every post-acceptance
terminal arrives only on the user channel. `poly_reconcile` / `POLY_RECONCILE` / 2026-11-01 /
Graduate — meaningful only alongside `poly_exec`: reconciling a paper engine against live venue
state makes the two sides different accounts, and under the `hybrid` policy `PositionDrift`
auto-applies, folding the live account's position into the paper engine's books. Run
recon-without-exec under `quarantine`. Then `poly_presubmit_register` / `POLY_PRESUBMIT_REGISTER` /
Retire, `poly_heartbeat` / `POLY_HEARTBEAT` / Retire, `poly_rate_gate` / `POLY_RATE_GATE` / Retire,
`poly_chain_watch` / `POLY_CHAIN_WATCH` / Retire (all 2026-11-01), `poly_chain_proxy` /
`POLY_CHAIN_PROXY` / 2027-02-01 / Graduate, `poly_auto_redeem` / `POLY_AUTO_REDEEM` / 2026-11-01 /
Keep, `poly_redeem_halt` / `POLY_REDEEM_HALT` / 2027-02-01 / Keep, and `pm_resolve` /
`VIKE_PM_RESOLVE` / 2027-02-01 / Keep.

**Per-venue behaviour.** `hl_outcome` / `VIKE_HL_OUTCOME` / 2027-02-01 / Keep. `bybit_fast_exec` /
`VIKE_BYBIT_FAST_EXEC` / 2026-11-01 / Retire. `binance_trade_lite_fill` /
`VIKE_BINANCE_TRADE_LITE_FILL` / 2026-11-01 / Retire. `hyperliquid_hip3` / `HYPERLIQUID_HIP3` /
2027-02-01 / Graduate.

**Recorders.** `record_properties` / `VIKE_RECORD_PROPERTIES`, `record_chains` /
`VIKE_RECORD_CHAINS`, `record_dvol` / `VIKE_RECORD_DVOL` — all 2027-02-01 / Graduate.

**Safety overrides.** `allow_withdraw_keys` / `VIKE_ALLOW_WITHDRAW_KEYS` / 2027-02-01 / Keep — the
default refusal exists because a key that can move funds off the venue has no business signing
orders. `preflight_skip` / `VIKE_PREFLIGHT_SKIP` / 2027-02-01 / Keep — skips the checks that catch a
misconfigured mount before it trades; see [startup preflight](/docs/trader/concepts/startup-preflight).

## Check the READ column before you set one [#check-the-read-column-before-you-set-one]

<Callout type="warn" title="Most of these are still read by a library, not by this file">
  `vike_config::CONSUMPTION` carries one row per key naming the file and the read that consumes it, or
  a written admission that nothing does, and `crates/vike-config/tests/settings_are_consumed.rs` opens
  each claimed consumer and looks. Many flags are still read by a venue adapter or a recorder through
  its own environment read, so setting them here does nothing yet — `vike-cli config show`'s READ
  column says `NO` for exactly those and the `--json` view carries each one's reason. Moving one is
  not a line change: it means threading the value from a composition root through
  `vike_run::NodeConfig` and `vike_mount::make_engine` into the adapter, and a flag living in two
  places that disagree would be worse than the state the program is fixing, so the file layer and the
  environment read flip together, per flag.
</Callout>

Six boolean-ish things in the tree are deliberately **not** fields here, each named in the module
header so the omission is on the record: the two computed per-venue families keyed by venue rather
than by a fixed name, the default-on master of one of them, the Polymarket proxy trio with its fuzzy
grammar, the sweep sequential switch that belongs with
[preferences](/docs/trader/reference/settings/preferences), the presence-based GUI and screenshot
harness, and the test-only self-skip gates.


# Settings files (/docs/trader/reference/settings)



Every setting the typed settings model reads from a file lives in `<project>/settings/`, in four
TOML files. `crates/vike-config/src/lib.rs` is the typed model and the layered loader, and its
header states the split the four files exist to draw: **by authority, not by subsystem** — one type
per level of who may change a value and from where.

One other file carries settings-shaped values, and no live mount starts without it: a **run
profile**, named by `--profile` or `VIKE_RUN_PROFILE` and conventionally kept in
`<project>/user_data/profiles/` — a sibling of `settings/`, never inside it. Its `[risk]` table
deserializes into `crates/vike-exec/src/risk_profile.rs`'s `ProfileRisk` and is threaded verbatim
into every venue mount through `vike_run::NodeConfig::risk_profile`, whose neighbouring `policy`
field spells the split: a run profile is per-run and operator-owned, a policy per-machine and
admin-owned. `crates/vike-mount/src/arming.rs`'s `require_live_risk_budget` refuses a live mount
whose `max_notional_per_order` and `max_total_exposure` no profile supplied — today the `[risk]`
table is the only source that reaches the risk gate, so the same-named notional ceiling in the
table below is a second enforcement point at the order surfaces rather than a substitute for it.

| file                                                         | type          | holds                                                                                                     | who writes it | overridable by |
| ------------------------------------------------------------ | ------------- | --------------------------------------------------------------------------------------------------------- | ------------- | -------------- |
| [`policy.toml`](/docs/trader/reference/settings/policy)           | `Policy`      | hard ceilings — leverage, order notional, market-slippage band, halt admission, per-venue arming          | org/admin     | **file only**  |
| [`config.toml`](/docs/trader/reference/settings/config)           | `Config`      | deployment — store paths, log dir, listen addresses                                                       | deployment    | file, env, CLI |
| [`preferences.toml`](/docs/trader/reference/settings/preferences) | `Preferences` | taste and tuning — log levels, chart style, and a sweep-thread bound only `VIKE_SWEEP_THREADS` sets today | user          | file, env, CLI |
| [`flags.toml`](/docs/trader/reference/settings/flags)             | `Flags`       | toggles — reconcile, poly exec, control surfaces, recorders                                               | operator      | file, env, CLI |

One precedence order applies to all of them, written out in `crates/vike-config/src/layers.rs`:
code defaults → `<project>/settings/*.toml` → env → CLI. Nothing runs after that layer today —
`crates/vike-config/src/lib.rs`'s header records that there is currently no
policy-bounds-preference clamp, the mechanism still being the taxonomy's spine but having no
instance since the `rate_utilization` tombstone. What differs per type is not the order but *which
layers exist*, and `layers.rs` says that table is enforced by the type system rather than by a
comment.

## The one type with fewer layers [#the-one-type-with-fewer-layers]

`Policy` implements neither `EnvOverride` nor `CliOverride`, and has no `from_env`, `apply_env` or
`apply_cli` inherent method either — so `settings.policy.apply_env(&env)` is a compile error, not a
review comment. Both traits are sealed behind a crate-private supertrait, so a downstream crate
cannot bolt an impl on from outside. The argument in that module's header is short: *a ceiling you
can override with an environment variable is not a ceiling*, and the failure mode is silent — a
stale systemd unit or an inherited shell raises the limit with no file changed, no diff, no review,
and a run that looks completely normal.

<Callout type="warn" title="There is no fifth override layer">
  A `<project>/vike.toml` override layer sat between the settings directory and the environment and
  is **removed**. `crates/vike-config/src/removed.rs` explains why a present one is a startup refusal
  rather than something ignored: the file was genuinely wired for the hour between the change that
  wired it and the change that removed the layer, so an operator may have one on disk that took
  effect. Ignoring it would make their belief silently false. `REMOVED_PROJECT_FILE` and
  `removed_project_file_message` own the message, and a path that cannot be probed refuses too —
  saying so, rather than claiming the file is there.
</Callout>

## What the loader refuses to be quiet about [#what-the-loader-refuses-to-be-quiet-about]

Unknown keys are rejected **by name**: every file struct carries `deny_unknown_fields`, because a
typo'd setting that silently does nothing is worse than an error. The crate header states the one
limit of that mechanism — it governs a struct's field names, and serde treats a map's keys as data.
`Policy::venues` and `PolicyPatch::accounts` — the `[accounts]` table — are the model's maps, so
both have their venue ids checked by hand against `vike_model::VENUES` in `Policy::apply`, an
unknown one refused with the roster in the message, and an account label checked against
`vike_model::account_keys::AccountLabel::parse`.

Every failure names the file and the key. `crates/vike-config/src/error.rs` sets the bar
explicitly: `"invalid config"` is useless to the person holding the file, while
`"policy.toml: market_slippage = 0.9 exceeds the allowed maximum 0.05"` names the file to open, the
value rejected and the bound it broke. Env and CLI failures name the variable or flag instead,
because there is no file to open.

A **missing file is not an error**. A layer with no file contributes nothing and the layer below
stands; only a file that exists and cannot be read or parsed fails the load.

## Nothing here resolves a directory [#nothing-here-resolves-a-directory]

The loader is a pure function of its arguments: the settings directory is a parameter, and so is
the env map. `crates/vike-config/src/load.rs` states that this crate never walks, never expands
`~` and never reads a platform variable — `vike_model::state_path::project_settings_dir_from` owns
the walk and the **binary** performs it. That is the workspace rule that libraries take
configuration as parameters and only binaries touch the process environment.

## Finding out what actually applied [#finding-out-what-actually-applied]

`vike-cli config show` prints every setting, its effective value and the layer that set it — see
the [config verb](/docs/trader/reference/cli/set-up/config). Provenance is *measured, never inferred*:
`crates/vike-config/src/provenance.rs` decides an origin by key **presence in a parsed layer**, not
by diffing effective values against defaults, because a `policy.toml` that sets `max_leverage = 1.0`
— the same number as the code default — is a file that was read and did configure that key. The
precedence header the command prints is rendered from the `PRECEDENCE` table itself, so it cannot
name a layer no binary applies.

A daemon does not wait to be asked. `crates/vike-config/src/boot.rs` renders the settings
directory, one line per file (present or absent, with its key count), the resolved settings, and
the credential store's presence — every `policy.*` row always, plus every row some layer actually
configured. Its header carries the incident that motivated it: on one production box the
project-root walk answered with an unrelated directory, so the daemon loaded no policy, no config
and no credentials, and every venue silently dropped to paper with no error.

## Editing, and when an edit takes effect [#editing-and-when-an-edit-takes-effect]

`crates/vike-config/src/write.rs` is the write half: it sets one key in one file, preserving the
operator's comments and the formatting of every untouched line, validates the would-be text
through the same parse-and-apply the loader runs *before* a byte lands on disk, and writes
atomically. `crates/vike-tradehub/src/hot_reload.rs` classifies each key as hot-safe or
restart-required, exhaustively against `vike_config::provenance::setting_keys`, and its
`the_hot_set_is_exactly_the_two_log_levels` test pins the hot set to
`preferences.log_level` and `preferences.log_file_level&#x60;. **`policy.toml` is never hot by
construction** — `classify` answers restart-required for that file before the table is consulted.

Two more pages sit beside these four: the alert rule file
[`alerts.json`](/docs/trader/reference/settings/alerts), which is program-written state rather than a
settings file, and the [environment variable reference](/docs/trader/reference/environment).


# policy.toml (/docs/trader/reference/settings/policy)



`crates/vike-config/src/policy.rs` is the authority for this file. `Policy` answers *what is this
deployment never allowed to exceed*, which makes it the one settings type whose value must be
harder to change than the rest — so it carries fewer layers than the others, and that reduction is
the entire reason it exists as its own struct. It implements neither `EnvOverride` nor
`CliOverride` and has no `apply_env`, so `policy.apply_env(&env)` fails to compile.
`settings/policy.example.toml` ships every line commented out, so the file as shipped configures
nothing.

## The keys [#the-keys]

**`max_leverage`** — the maximum leverage any strategy on this machine may request, `>= 1.0`.
Defaults to `DEFAULT_MAX_LEVERAGE`, which is `1.0`, meaning no leverage at all: a ceiling's default
must be the conservative end, so a deployment that ships no `policy.toml` gets the safest reading.
It was `[risk] max_leverage` in a run-profile TOML, where `vike_exec::ProfileRisk::max_leverage`
converts it to `RiskLimits::im_requirement` as `1.0 / max_leverage`.

**`max_notional_per_order`** — the maximum notional of any single order, in quote currency; absent
means uncapped. Its field doc calls this the clearest case the whole taxonomy exists for. It
replaces two environment variables, `VIKE_MAX_ORDER_NOTIONAL` (read by `vike-desktop` and `vike-cli`)
and `VIKE_TRADEHUB_MAX_ORDER_NOTIONAL`, both of which are now refused at startup by
`vike_config::refuse_removed_env` rather than ignored — see the
[environment reference](/docs/trader/reference/environment). The example file records where it bites: the
ceiling is enforced at the node, and `vike-cli trade`'s preview guardrail only advises, saying so on
the line.

**`market_slippage`** — the aggression band for an **emulated** market order, as a fraction
(`0.002` = 0.2 %). Absent means each venue keeps its own historical literal, byte-identically. Only
venues with no native market order consult it, and hyperliquid is the only one on the roster; such
an adapter prices a market intent as an `Ioc` limit at `mid * (1 ± band)` and a tripped stop-market
at `trigger * (1 ± band)`. The band is therefore the worst price the order is allowed to reach — not
a prediction and not a fee. Hyperliquid's compiled-in value was `0.05`: 5 % on every market order and
every protective stop exit, which never binds on a deep BTC book and binds completely on a thin alt.
Accepted values lie in `MIN_MARKET_SLIPPAGE ..= MAX_MARKET_SLIPPAGE`, both imported from
`vike_model::market_slippage` rather than redefined here, and a value outside the range is rejected
rather than clamped.

**`halt_admit`** — how much evidence the halt file sentinel demands before letting a submit out:
`"admit"` (the default) or `"verify"`, over `vike_model::HaltAdmit`. It is policy-class because it
governs what a kill switch lets through, and because its two values differ only under an engaged
halt — during an incident, the worst possible moment to discover that the environment overrode your
file.

<Callout type="warn" title="verify is weaker than the word suggests">
  The field doc is explicit: only a **live cTrader mount** implements `verify`, and it refuses only
  what a positive report from the venue's own position book proves opens risk. Every absence — never
  fetched, fetch failed, socket dropped since, an answer that could not be read in full or was for
  another account, or simply no position reported in that symbol — still admits, because *halting
  cannot trap you* outranks *halting is airtight*. Every other venue degrades to `"admit"` and says so
  once, at mount, naming the reason; a cTrader venue that fell back to paper says that too, because
  the paper client holds no book either. `crates/vike-exec/src/halt.rs` is the single authority. There
  is deliberately no third value — a `"refuse"` mode was the behaviour until 2026-08-06 and was
  removed because it disarmed the panic button in exactly the situations that halt on their own.
</Callout>

See [halt](/docs/trader/concepts/halt) for what an engaged halt lets out.

**`link_deadman_grace_ms`** — how long a venue's market-data link may be reported `Disconnected` by
its own bridge before the daemon cancels **that venue's** resting orders and, per `deadman_action`,
engages the halt. **It is the one key in this file whose absent state is armed**, at
`DEFAULT_LINK_DEADMAN_GRACE_MS` — 120 000 ms — and `0` is the only off, which needs no warning
because writing it is a decision. Legal values are `0`, or `MIN_LINK_DEADMAN_GRACE_MS` (30 000 ms)
through `MAX_LINK_DEADMAN_GRACE_MS` (3 600 000 ms); the floor is the slowest measured ordinary
reconnect among the lanes that report a dead link, and a value outside the range is rejected by
name rather than clamped. It may carry an armed default because it reads what the bridge discloses
instead of counting ticks: a market that merely closed is disclosed `Stale`, which never counts.
Where it arms is not settable here — that is a property of the venue's adapter and of the lanes the
mount subscribed. On a default live mount that is **binance, bybit, okx and aster**, plus polymarket
behind its feature; every FX and equities venue stays off deliberately, because a close is not an
outage. The daemon prints one line per mounted venue at startup saying which, and why not.

**`deadman_timeout_ms`** — the other switch, on the opposite convention: how long the whole core's
ingest may be silent before it cancels **every** resting order. Absent is **off**, with one warning
at mount naming the key; `0` is off as a recorded decision and is the only spelling that silences
that warning; a written value arms it, legal from 1 000 ms to one day. It shipped armed at 60 s for
a single morning and was made opt-in the same day, because silence is also what a closed market
looks like — it halted every FX and equities mount at every session close, and the one-day maximum
could not be raised past an FX weekend. Arm it on a 24/7 mount only.

**`deadman_action`** — what a trip does, shared by both switches because *what does a trip do* is
one question: `"cancel_all_and_halt"` (the default — pull the book and engage the halt, in-process
on every engine plus the sentinel file) or `"cancel_all"` (pull the book, leave the trading state
alone). An unknown spelling is refused at load naming the legal two, and the key is inert while the
switch it would act for is not constructed.
[The dead-man's switches](/docs/trader/concepts/dead-mans-switch) carries the mechanism, the per-venue
reading and the startup lines that say which of the two, if either, is armed on your box.

## `[venues]` — per-venue arming [#venues--per-venue-arming]

One key per roster venue, `paper` / `demo` / `live`, defaulting to `paper` everywhere.
`crates/vike-config/src/venue_mode.rs` states the property that makes this safe to introduce into a
deployment already trading real money: &#x2A;*it is a ceiling, not a selector.** The effective tier is
`min(mode, whatever the existing mechanisms decide)` — never `max` — so `venues.bybit = "live"` does
not put bybit live; it declines to stop bybit going live if its credentials, its `{VENUE}_MAINNET`
flag and its mount arm already say so. `VenueMode` derives `Ord` over variants declared in ascending
risk order and `VenueMode::cap` is the one spelling of the fold, so an author reaching for `max` has
to delete a method and write their own.

It is enforced. The fold sits at `crates/vike-mount/src/lib.rs`'s `make_engine_for_account` —
`make_engine_with_legs` is a one-line delegation to it — **above** the credential read, so a `paper`
venue returns the paper client without loading a credential, fetching an instrument grid or opening
a socket. `crates/vike-config/tests/policy_is_consumed.rs`'s `venues` row names
`crates/vike-mount/src/arming.rs`'s `account_ceiling`, the per-account spelling of that fold, and
opens that file to check it is still there. [Risk and arming](/docs/trader/concepts/risk-and-arming)
puts it in order against the other gates.

<Callout type="warn" title="The first start on a box with credentials and no [venues] table">
  Every venue drops to paper. That is the correct ceiling and a silent one, so it is not silent:
  `vike_mount::venue_arming_migration` warns once, names this file and this key, lists the venues
  whose credentials would have armed, and prints the block that restores them. It warns rather than
  refusing because a venue connection is a capability, and a daemon that will not start cannot flatten
  a position either. `VenuePolicy::is_declared` is the fact it self-silences on — writing the table at
  all, even with every venue at `paper`, is a stated decision and is not the same as leaving it out.
</Callout>

Every roster venue gets a row, including ones this build cannot mount. `ibkr`, `polymarket` and
`fxcm` sit behind Cargo features declared far above `vike-config`, which cannot see them; a ceiling
for an unmountable venue caps at paper anyway; and a `policy.toml` must stay portable across boxes
whose features differ, so refusing `ibkr = "demo"` on a build without the feature would hard-fail a
reviewed file for a line that is correct. An unknown venue id is refused by name at load with the
whole roster in the message, because `[venues]` keys are data to serde and `deny_unknown_fields`
cannot see them.

## `[accounts]` — per-account ceilings [#accounts--per-account-ceilings]

A venue you hold more than one account on addresses each by a label appended to that venue's
credential keys behind a double underscore. `Policy`'s hand-written `Serialize` emits `accounts` as
a sixth field — a **projection** of `VenuePolicy`'s per-account ceilings, not a second copy of them:
`VenuePolicy` is `#[serde(transparent)]` over its flat map and so cannot carry a second serialized
field, and a table nothing serializes gets no provenance row, no `vike-cli config show` cell and no
example line, which is the declared-but-undisclosed shape this crate exists to refuse. The default
account inherits its venue's `[venues]` line; a labelled account must be named here to be armed, and
the venue's own line still caps it. [Accounts](/docs/trader/concepts/accounts) has the credential-key
grammar.

`crates/vike-config/src/venue_accounts.rs` carries the shared-book rule, with a correction worth
reading before assuming otherwise: two active accounts of one venue that resolve to the **same
effective trading book** are reported — loudly, by name — and both are mounted anyway. The symbol is
not part of the rule; long on account A and short on account B is an ordinary spread. The hazard
that is real is one book reached by two engines, and `vike_mount::make_engine_accounts` emits one
warning per pair naming the venue, both labels and the shared book.

## Two tombstones, and the gate they left behind [#two-tombstones-and-the-gate-they-left-behind]

`max_total_exposure` was declared here, validated by `Policy::apply`, accepted by `PolicyPatch`'s
`deny_unknown_fields`, and consumed by no code path in the workspace — an operator who set it got
validation, no complaint, and no cap. `rate.max_utilization` was the second: it clamped a preference
that was itself read by nothing. Both now refuse their key by name, and
`crates/vike-config/tests/policy_is_consumed.rs` is the standing gate — every field of this struct
must name a file that genuinely reads it, or carry a written admission that nothing does, and a
claimed consumer inside `vike-config` itself is rejected as self-consumption. See the
[settings gates](/docs/trader/developer/settings-gates).

Nothing in this file is hot-appliable. `crates/vike-tradehub/src/hot_reload.rs`'s `classify` answers
restart-required for the policy file *before* its table is consulted, so no future row can make a
risk ceiling hot-appliable; a policy edit lands on disk and takes effect on the next boot.


# preferences.toml (/docs/trader/reference/settings/preferences)



`crates/vike-config/src/preferences.rs` is the authority for this file. Its header draws two lines.
Against [`config.toml`](/docs/trader/reference/settings/config): &#x2A;would a second machine need a different
value?* — a log level or a chart style would not, they express what the operator likes. Against
[`policy.toml`](/docs/trader/reference/settings/policy) the line is sharper: &#x2A;*policy sets the bound, a
preference sets the value inside it.** `settings/preferences.example.toml` states the consequence
plainly — nothing here is a risk control. A preference may be wrong and cost you a readable screen;
it can never place a larger order.

Every key carries the full chain: environment variable, then this file, then the default — with one
reservation: `vike_config::CONSUMPTION` still marks `preferences.sweep_threads` unconsumed, because
`crates/vike-backtest/src/harness/sweep.rs`'s `sweep_threads` reads `VIKE_SWEEP_THREADS` itself and
none of its callers load settings, so only the variable bites for that one key today.

| key              | environment variable        | default                                    | hot-appliable |
| ---------------- | --------------------------- | ------------------------------------------ | ------------- |
| `log_level`      | `RUST_LOG`, then `VIKE_LOG` | `DEFAULT_LOG_LEVEL` = `info`               | yes           |
| `log_file_level` | `VIKE_LOG_FILE_LEVEL`       | `DEFAULT_LOG_FILE_LEVEL` = `trace`         | yes           |
| `chart_style`    | `VIKE_STYLE`                | absent — the GUI's own default             | no            |
| `sweep_threads`  | `VIKE_SWEEP_THREADS`        | absent — `min(4, available_parallelism())` | no            |

**`log_level`** is the console filter, in standard `tracing` directive syntax (`info`, `warn`, or a
targeted `info,vike_exec=debug`). `RUST_LOG` is checked first, matching `vike_log::init`, and
`VIKE_LOG` is the Vike-flavoured alias.

**`log_file_level`** is the JSON log **file**'s own level, and it is independent of `log_level`,
which filters the console only.

<Callout type="warn" title="This is the disk knob, and the surprise is that RUST_LOG does not touch it">
  The file layer defaults to `trace` and captures the `log`-to-`tracing` bridge, so a chatty
  dependency writes at `trace` no matter how quiet the terminal looks. The example file carries the
  measurements: one hour of `pmxt_backfill` wrote **6.4 GB**, and one long range wrote **341 GB** and
  nearly filled the disk hosting a live trading node. Set this to `warn` for any long backfill or
  replay run — `off` silences the file entirely — and still watch the size of `config.log_dir`. The
  shipped systemd units all set it to `warn`. The default is kept at `trace` in
  `DEFAULT_LOG_FILE_LEVEL` deliberately, so that introducing this file changed nothing; the field
  exists so a deployment can finally turn it down in a file instead of an environment variable.
</Callout>

**`chart_style`** is the style `vike-desktop` opens new chart windows with. Absent means the GUI's own
default. It is read only by `vike-desktop`, so it does nothing on a headless daemon or a recorder box.

**`sweep_threads`** bounds the rayon pool a parameter sweep installs. Absent falls back to
`vike-backtest`'s own `min(4, available_parallelism())`, and the example file notes it must not be
zero. It is the one key here the file cannot yet set: `sweep_threads` reads `VIKE_SWEEP_THREADS`
itself and none of its callers load settings, so today only the variable bites.

## The two hot keys [#the-two-hot-keys]

`crates/vike-tradehub/src/hot_reload.rs` classifies every `config`, `preferences` and `flags` key as
hot-safe or restart-required, exhaustively against `vike_config::provenance::setting_keys`, and its
`the_hot_set_is_exactly_the_two_log_levels` test pins the hot set to exactly `preferences.log_level`
and `preferences.log_file_level` — a pin, so growing the set is a deliberate diff on that line plus
a reasoned table row rather than a drive-by. Every hot row must carry a written reason, checked for
length the way `vike_config::consumed`'s gate checks its own; the module calls this the
power-granting class carrying its own justification.

A hot write does not apply on the server's connection thread. The accepted write enqueues an apply
job and blocks, bounded by `HOT_APPLY_DEADLINE`, while the daemon's existing periodic summary tick —
the same off-fold thread that prints the stdout summary and drives alerting — drains the queue and
executes the apply. One thread owns every runtime mutation, so two concurrent writes cannot race an
apply and nothing new touches the core fold. `Response::SettingsWritten.restart_required` is `false`
only when the tick confirmed the apply executed inside the deadline; a timeout, a failed apply, a
daemon without the seam wired and a restart-class key all answer `true`, which is always safe. The
one residual the module declares: an apply that lands *after* the deadline was already reported as
restart-required — conservative, never false the other way.

## The `rate_utilization` tombstone [#the-rate_utilization-tombstone]

The field is gone and the key is now refused by name rather than ignored, and the story is worth
keeping because the example was wrong in the one way that matters. `rate_utilization` claimed to
replace the compiled-in `vike_model::rate_limits::DEFAULT_UTILIZATION`, and
`policy.rate.max_utilization` clamped it at the end of the load with a warning naming both halves.
&#x2A;*Nothing read the result.** Every pacer takes its target fraction from
`vike_binance::family::klines::KlineSpec::utilization`, and every construction site of that field
fills it with the constant. So an operator could set the preference, watch it validate, watch
`vike-cli config show` attribute it to their file, watch the policy ceiling clamp it, read a warning
about the clamp, and change nothing at all. There was also a `--rate-utilization` CLI override that
no binary parsed.

Both halves are tombstones now. The concept did not leave the product, only this file:
`vike_model::rate_limits` owns the number and its bounds, and — the part a single float in this
struct could never express — per-venue overrides through `vike_model::RateLimitConfig`. A pacing
knob that cannot say *40 % on binance, 20 % on aster* is the wrong shape. The field also
deliberately never got a `VIKE_RATE_UTILIZATION` environment name, for a reason that still holds for
any future one: a program whose end state is &#x2A;no crate calls `env::var` except `vike-config`* should
not open by minting a new environment variable.

With that field gone there is **no policy-bounds-preference clamp left in the loader**.
`crates/vike-config/src/lib.rs`'s header says so outright, and `crates/vike-config/src/load.rs`'s
layered load now ends at the CLI layer, carrying a comment where the clamp call used to sit. The
mechanism is not repudiated, only uninstanced — *policy sets the bound, a preference sets the value
inside it* is still the spine of the split, and the first real bound/value pair brings the pass
back, ideally with the gate that would have caught this one. `vike-cli config show --filter
preferences` prints which layer won for each key — see the
[config verb](/docs/trader/reference/cli/set-up/config).


# Buy & hold (buy_hold) (/docs/trader/strategies/templates/buy-hold)




**Buy & hold** buys once at the first bar and holds — the baseline every other template is measured against. It is one of the portable strategies — the names
`vike_strategy::strategy_by_name` resolves for a live mount as well as a backtest — so a run
profile or a daemon names it as `buy_hold` under `[strategy]`, and the keys below arrive
through `[strategy.params]`. The [registry page](/docs/trader/strategies/the-registry) explains the
roster; the [simulator-only](/docs/trader/strategies/simulator-only) page lists the names a backtest can
still resolve that a daemon cannot.

## Parameters [#parameters]

Each key is listed with the TOML type its reader insists on — read off the strategy's own
`from_params` by the registry's gate, never chosen (`vike_strategy::registry::PARAM_KEYS`). A
key of the wrong type is a silent no-op, which is why the type is stated.

| Key      | TOML type |
| -------- | --------- |
| `size`   | number    |
| `symbol` | string    |

## Live mount [#live-mount]

Mountable on the live core today: the registry's `LIVE_CAPABLE` row carries no blocker, so a daemon that names this strategy will trade it.

## Where this comes from [#where-this-comes-from]

The roster is `vike_strategy::registry::PORTABLE_STRATEGIES`; its parameter table and live
verdict are that registry's `PARAM_KEYS` and `LIVE_CAPABLE` rows, held exhaustive against each
other by the registry's own tests and exported as `templates.json` at every release. The glosses
on this page are the one hand-written part; every table is rendered.


# DCA accumulate (dca_accumulate) (/docs/trader/strategies/templates/dca-accumulate)




**DCA accumulate** accumulates a position in fixed-size steps on a schedule, the dollar-cost-averaging shape. It is one of the portable strategies — the names
`vike_strategy::strategy_by_name` resolves for a live mount as well as a backtest — so a run
profile or a daemon names it as `dca_accumulate` under `[strategy]`, and the keys below arrive
through `[strategy.params]`. The [registry page](/docs/trader/strategies/the-registry) explains the
roster; the [simulator-only](/docs/trader/strategies/simulator-only) page lists the names a backtest can
still resolve that a daemon cannot.

## Parameters [#parameters]

Each key is listed with the TOML type its reader insists on — read off the strategy's own
`from_params` by the registry's gate, never chosen (`vike_strategy::registry::PARAM_KEYS`). A
key of the wrong type is a silent no-op, which is why the type is stated.

| Key            | TOML type                                     |
| -------------- | --------------------------------------------- |
| `side`         | string or integer                             |
| `anchor`       | string                                        |
| `anchor_price` | number                                        |
| `step`         | number                                        |
| `rungs`        | integer (a whole number — `4.0` sets nothing) |
| `size`         | number                                        |
| `tp`           | number                                        |
| `symbol`       | string                                        |

## Live mount [#live-mount]

Mountable on the live core today: the registry's `LIVE_CAPABLE` row carries no blocker, so a daemon that names this strategy will trade it.

## Where this comes from [#where-this-comes-from]

The roster is `vike_strategy::registry::PORTABLE_STRATEGIES`; its parameter table and live
verdict are that registry's `PARAM_KEYS` and `LIVE_CAPABLE` rows, held exhaustive against each
other by the registry's own tests and exported as `templates.json` at every release. The glosses
on this page are the one hand-written part; every table is rendered.


# Funding capture (funding_capture) (/docs/trader/strategies/templates/funding-capture)




**Funding capture** takes and unwinds a perpetual position around the funding timestamp to capture the payment. It is one of the portable strategies — the names
`vike_strategy::strategy_by_name` resolves for a live mount as well as a backtest — so a run
profile or a daemon names it as `funding_capture` under `[strategy]`, and the keys below arrive
through `[strategy.params]`. The [registry page](/docs/trader/strategies/the-registry) explains the
roster; the [simulator-only](/docs/trader/strategies/simulator-only) page lists the names a backtest can
still resolve that a daemon cannot.

## Parameters [#parameters]

Each key is listed with the TOML type its reader insists on — read off the strategy's own
`from_params` by the registry's gate, never chosen (`vike_strategy::registry::PARAM_KEYS`). A
key of the wrong type is a silent no-op, which is why the type is stated.

| Key         | TOML type |
| ----------- | --------- |
| `threshold` | number    |
| `qty`       | number    |
| `symbol`    | string    |

## Live mount [#live-mount]

**Resolves but would not trade live.** The registry's `LIVE_CAPABLE` row names the missing input: reads `Bar::funding`, which every live kline lane leaves `None` (`vike_bridge_core::klines::kline_to_bar`) — it would mount and never see a funding rate

## Where this comes from [#where-this-comes-from]

The roster is `vike_strategy::registry::PORTABLE_STRATEGIES`; its parameter table and live
verdict are that registry's `PARAM_KEYS` and `LIVE_CAPABLE` rows, held exhaustive against each
other by the registry's own tests and exported as `templates.json` at every release. The glosses
on this page are the one hand-written part; every table is rendered.


# Funding carry (funding_carry) (/docs/trader/strategies/templates/funding-carry)




**Funding carry** holds a hedged spot/perpetual position to collect the funding rate. It is one of the portable strategies — the names
`vike_strategy::strategy_by_name` resolves for a live mount as well as a backtest — so a run
profile or a daemon names it as `funding_carry` under `[strategy]`, and the keys below arrive
through `[strategy.params]`. The [registry page](/docs/trader/strategies/the-registry) explains the
roster; the [simulator-only](/docs/trader/strategies/simulator-only) page lists the names a backtest can
still resolve that a daemon cannot.

## Parameters [#parameters]

Each key is listed with the TOML type its reader insists on — read off the strategy's own
`from_params` by the registry's gate, never chosen (`vike_strategy::registry::PARAM_KEYS`). A
key of the wrong type is a silent no-op, which is why the type is stated.

| Key               | TOML type                                     |
| ----------------- | --------------------------------------------- |
| `symbol`          | string                                        |
| `qty`             | number                                        |
| `tp`              | number                                        |
| `sl`              | number                                        |
| `time_limit_ms`   | integer (a whole number — `4.0` sets nothing) |
| `trailing`        | number                                        |
| `hold_periods`    | number                                        |
| `entry_threshold` | number                                        |
| `venue`           | string                                        |
| `cooldown_ms`     | integer (a whole number — `4.0` sets nothing) |
| `venues`          | table                                         |

## Live mount [#live-mount]

**Resolves but would not trade live.** The registry's `LIVE_CAPABLE` row names the missing input: TWO-LEG and cross-venue: needs one declared mount leg per carry venue, and no mount surface declares legs today (`vike_run::MountSpec`'s `legs` is empty on every spec, and the paper builder asserts it) — plus the same missing live funding series as `funding_capture`

## Where this comes from [#where-this-comes-from]

The roster is `vike_strategy::registry::PORTABLE_STRATEGIES`; its parameter table and live
verdict are that registry's `PARAM_KEYS` and `LIVE_CAPABLE` rows, held exhaustive against each
other by the registry's own tests and exported as `templates.json` at every release. The glosses
on this page are the one hand-written part; every table is rendered.


# Grid (grid) (/docs/trader/strategies/templates/grid)




**Grid** rests a ladder of rungs around an anchor price and trades the oscillation between them. It is one of the portable strategies — the names
`vike_strategy::strategy_by_name` resolves for a live mount as well as a backtest — so a run
profile or a daemon names it as `grid` under `[strategy]`, and the keys below arrive
through `[strategy.params]`. The [registry page](/docs/trader/strategies/the-registry) explains the
roster; the [simulator-only](/docs/trader/strategies/simulator-only) page lists the names a backtest can
still resolve that a daemon cannot.

## Parameters [#parameters]

Each key is listed with the TOML type its reader insists on — read off the strategy's own
`from_params` by the registry's gate, never chosen (`vike_strategy::registry::PARAM_KEYS`). A
key of the wrong type is a silent no-op, which is why the type is stated.

| Key            | TOML type                                     |
| -------------- | --------------------------------------------- |
| `anchor`       | string                                        |
| `anchor_price` | number                                        |
| `step`         | number                                        |
| `rungs`        | integer (a whole number — `4.0` sets nothing) |
| `size`         | number                                        |
| `band`         | number                                        |
| `bounded01`    | bool                                          |
| `tick`         | number                                        |
| `symbol`       | string                                        |

## Live mount [#live-mount]

Mountable on the live core today: the registry's `LIVE_CAPABLE` row carries no blocker, so a daemon that names this strategy will trade it.

## Where this comes from [#where-this-comes-from]

The roster is `vike_strategy::registry::PORTABLE_STRATEGIES`; its parameter table and live
verdict are that registry's `PARAM_KEYS` and `LIVE_CAPABLE` rows, held exhaustive against each
other by the registry's own tests and exported as `templates.json` at every release. The glosses
on this page are the one hand-written part; every table is rendered.


# Guéant maker (gueant_maker) (/docs/trader/strategies/templates/gueant-maker)




**Guéant maker** quotes with the Guéant–Lehalle–Fernandez-Tapia optimal-quote model from `vike-mm`, skewing for inventory. It is one of the portable strategies — the names
`vike_strategy::strategy_by_name` resolves for a live mount as well as a backtest — so a run
profile or a daemon names it as `gueant_maker` under `[strategy]`, and the keys below arrive
through `[strategy.params]`. The [registry page](/docs/trader/strategies/the-registry) explains the
roster; the [simulator-only](/docs/trader/strategies/simulator-only) page lists the names a backtest can
still resolve that a daemon cannot.

## Parameters [#parameters]

Each key is listed with the TOML type its reader insists on — read off the strategy's own
`from_params` by the registry's gate, never chosen (`vike_strategy::registry::PARAM_KEYS`). A
key of the wrong type is a silent no-op, which is why the type is stated.

The registry does not enumerate this template's keys: the `spread_maker` bag, forced to `SpreadModel::Gueant`

## Live mount [#live-mount]

Mountable on the live core today: the registry's `LIVE_CAPABLE` row carries no blocker, so a daemon that names this strategy will trade it.

## Where this comes from [#where-this-comes-from]

The roster is `vike_strategy::registry::PORTABLE_STRATEGIES`; its parameter table and live
verdict are that registry's `PARAM_KEYS` and `LIVE_CAPABLE` rows, held exhaustive against each
other by the registry's own tests and exported as `templates.json` at every release. The glosses
on this page are the one hand-written part; every table is rendered.


# Momentum (momentum) (/docs/trader/strategies/templates/momentum)




**Momentum** follows a momentum signal through the controller seam, going with the recent direction. It is one of the portable strategies — the names
`vike_strategy::strategy_by_name` resolves for a live mount as well as a backtest — so a run
profile or a daemon names it as `momentum` under `[strategy]`, and the keys below arrive
through `[strategy.params]`. The [registry page](/docs/trader/strategies/the-registry) explains the
roster; the [simulator-only](/docs/trader/strategies/simulator-only) page lists the names a backtest can
still resolve that a daemon cannot.

## Parameters [#parameters]

Each key is listed with the TOML type its reader insists on — read off the strategy's own
`from_params` by the registry's gate, never chosen (`vike_strategy::registry::PARAM_KEYS`). A
key of the wrong type is a silent no-op, which is why the type is stated.

| Key             | TOML type                                     |
| --------------- | --------------------------------------------- |
| `qty`           | number                                        |
| `threshold`     | number                                        |
| `tp`            | number                                        |
| `sl`            | number                                        |
| `time_limit_ms` | integer (a whole number — `4.0` sets nothing) |
| `trailing`      | number                                        |
| `venue`         | string                                        |
| `cooldown_ms`   | integer (a whole number — `4.0` sets nothing) |
| `venues`        | table                                         |

## Live mount [#live-mount]

Mountable on the live core today: the registry's `LIVE_CAPABLE` row carries no blocker, so a daemon that names this strategy will trade it.

## Where this comes from [#where-this-comes-from]

The roster is `vike_strategy::registry::PORTABLE_STRATEGIES`; its parameter table and live
verdict are that registry's `PARAM_KEYS` and `LIVE_CAPABLE` rows, held exhaustive against each
other by the registry's own tests and exported as `templates.json` at every release. The glosses
on this page are the one hand-written part; every table is rendered.


# Pairs z-score (pairs_zscore) (/docs/trader/strategies/templates/pairs-zscore)




**Pairs z-score** trades the rolling z-score of a two-leg spread — long the cheap leg, short the rich one. It is one of the portable strategies — the names
`vike_strategy::strategy_by_name` resolves for a live mount as well as a backtest — so a run
profile or a daemon names it as `pairs_zscore` under `[strategy]`, and the keys below arrive
through `[strategy.params]`. The [registry page](/docs/trader/strategies/the-registry) explains the
roster; the [simulator-only](/docs/trader/strategies/simulator-only) page lists the names a backtest can
still resolve that a daemon cannot.

## Parameters [#parameters]

Each key is listed with the TOML type its reader insists on — read off the strategy's own
`from_params` by the registry's gate, never chosen (`vike_strategy::registry::PARAM_KEYS`). A
key of the wrong type is a silent no-op, which is why the type is stated.

| Key               | TOML type |
| ----------------- | --------- |
| `symbol_a`        | string    |
| `symbol_b`        | string    |
| `period`          | number    |
| `entry_z`         | number    |
| `exit_z`          | number    |
| `beta`            | number    |
| `notional`        | number    |
| `taker_fee`       | number    |
| `half_spread_bps` | number    |
| `hold_intervals`  | number    |
| `funding_a`       | number    |
| `funding_b`       | number    |
| `max_half_life`   | number    |

## Live mount [#live-mount]

**Resolves but would not trade live.** The registry's `LIVE_CAPABLE` row names the missing input: TWO-LEG: needs `symbol_a` + `symbol_b` as declared mount legs admitted into the venue engine's `extra_symbols`; a mount declares no legs today, so the second leg's bars never arrive and its orders would be dropped at `ExecutionEngine::accepts_symbol`

## Where this comes from [#where-this-comes-from]

The roster is `vike_strategy::registry::PORTABLE_STRATEGIES`; its parameter table and live
verdict are that registry's `PARAM_KEYS` and `LIVE_CAPABLE` rows, held exhaustive against each
other by the registry's own tests and exported as `templates.json` at every release. The glosses
on this page are the one hand-written part; every table is rendered.


# Spread maker (spread_maker) (/docs/trader/strategies/templates/spread-maker)




**Spread maker** quotes both sides of the book around mid at a configured spread — the simplest market-making template, backed by `vike-mm`. It is one of the portable strategies — the names
`vike_strategy::strategy_by_name` resolves for a live mount as well as a backtest — so a run
profile or a daemon names it as `spread_maker` under `[strategy]`, and the keys below arrive
through `[strategy.params]`. The [registry page](/docs/trader/strategies/the-registry) explains the
roster; the [simulator-only](/docs/trader/strategies/simulator-only) page lists the names a backtest can
still resolve that a daemon cannot.

## Parameters [#parameters]

Each key is listed with the TOML type its reader insists on — read off the strategy's own
`from_params` by the registry's gate, never chosen (`vike_strategy::registry::PARAM_KEYS`). A
key of the wrong type is a silent no-op, which is why the type is stated.

The registry does not enumerate this template's keys: the \~60-key A-S/GLFT bag is documented on `vike_mm::SpreadMaker::from_params`, in another crate; a hand copy here would rot. The live consumer refuses this table entirely and builds the maker from the profile's own maker fields

## Live mount [#live-mount]

Mountable on the live core today: the registry's `LIVE_CAPABLE` row carries no blocker, so a daemon that names this strategy will trade it.

## Where this comes from [#where-this-comes-from]

The roster is `vike_strategy::registry::PORTABLE_STRATEGIES`; its parameter table and live
verdict are that registry's `PARAM_KEYS` and `LIVE_CAPABLE` rows, held exhaustive against each
other by the registry's own tests and exported as `templates.json` at every release. The glosses
on this page are the one hand-written part; every table is rendered.


# Trailing scalper (trailing_scalper) (/docs/trader/strategies/templates/trailing-scalper)




**Trailing scalper** enters on a trigger and rides a trailing stop, taking small moves repeatedly. It is one of the portable strategies — the names
`vike_strategy::strategy_by_name` resolves for a live mount as well as a backtest — so a run
profile or a daemon names it as `trailing_scalper` under `[strategy]`, and the keys below arrive
through `[strategy.params]`. The [registry page](/docs/trader/strategies/the-registry) explains the
roster; the [simulator-only](/docs/trader/strategies/simulator-only) page lists the names a backtest can
still resolve that a daemon cannot.

## Parameters [#parameters]

Each key is listed with the TOML type its reader insists on — read off the strategy's own
`from_params` by the registry's gate, never chosen (`vike_strategy::registry::PARAM_KEYS`). A
key of the wrong type is a silent no-op, which is why the type is stated.

| Key                            | TOML type                                     |
| ------------------------------ | --------------------------------------------- |
| `qty`                          | number                                        |
| `half_spread`                  | number                                        |
| `exit_delay_ms`                | integer (a whole number — `4.0` sets nothing) |
| `profit_target`                | number                                        |
| `entry_open_delay_ms`          | integer (a whole number — `4.0` sets nothing) |
| `entry_cutoff_before_close_ms` | integer (a whole number — `4.0` sets nothing) |
| `market_open_ms`               | integer (a whole number — `4.0` sets nothing) |
| `market_close_ms`              | integer (a whole number — `4.0` sets nothing) |

## Live mount [#live-mount]

**Resolves but would not trade live.** The registry's `LIVE_CAPABLE` row names the missing input: NAKED SHORT on its own venue: from flat it rests a SELL leg documented as the single-token synthetic of `buy Down` (see its module doc), an equivalence that holds in the simulator — where a signed position may go negative for free — and NOT on the Polymarket CLOB it was written for, which requires the ERC-1155 outcome balance to sell. Live from flat that leg cannot rest, so the strategy degrades to a one-sided buyer while the backtest fills both sides; nothing in the mount path converts a sell into the Down-buy it is priced as

## Where this comes from [#where-this-comes-from]

The roster is `vike_strategy::registry::PORTABLE_STRATEGIES`; its parameter table and live
verdict are that registry's `PARAM_KEYS` and `LIVE_CAPABLE` rows, held exhaustive against each
other by the registry's own tests and exported as `templates.json` at every release. The glosses
on this page are the one hand-written part; every table is rendered.


# vike-cli data (/docs/trader/reference/cli/data/data)



`data` puts bars into the hist store the backtest engine reads. It is **not a collector**: every
byte of the work is done by the standalone `backtest` engine, which has carried `--fetch` and
`--seed-demo` since long before this verb existed. What was missing was discoverability —
`vike-cli init` ends by telling a new user to run `backtest --seed-demo`, which is a different binary
with a different name, and somebody who installed "the vike CLI" has no reason to expect that the
tool which runs a backtest is not the tool which fetches the data for one. So this is a route
(`crates/vike-cli/src/cmd/data.rs`), and `crate::cmd::engine` is the one place that knows where the
engine lives and what its exit codes mean.

It could not be anything else. Fetching writes a hist store, which needs DataFusion, and this
crate's whole identity is being DataFusion-free — see [the dispatcher](/docs/trader/reference/cli).

```
usage: vike-cli data fetch <SPEC> (--days N | --from LABEL --to LABEL) [--store DIR] [--json]
       vike-cli data seed-demo [--store DIR] [--json]
```

## Subcommands [#subcommands]

| subcommand   | what it writes                                                                                                                                                                                                             |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fetch SPEC` | **real** public bars, over a window. `SPEC` is `VENUE:SYMBOL:INTERVAL`, e.g. `binance:BTCUSDT:1h`. No credentials — this is public market data                                                                             |
| `seed-demo`  | the **synthetic** demo tape: venue `demo`, a closed-form curve, not market data. It is the slice the shipped `user_data/profiles/backtest.toml` names, so a fresh install can run that profile immediately. Safe to re-run |

## Flags [#flags]

| flag                          | meaning                                                                                                     |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `--days N`                    | `fetch`: a window counting back from now                                                                    |
| `--from LABEL` / `--to LABEL` | `fetch`: an explicit window — epoch-ms, or `YYYY-MM-DDTHH`. The two go together                             |
| `--store DIR`                 | the hist-store root to write into                                                                           |
| `--engine PATH`               | the standalone engine to run, instead of searching `<project>/bin`, this executable's directory, and `PATH` |
| `--json`                      | one JSON object on stdout describing the run                                                                |
| `-h`, `--help`                | the usage, on stdout, exit 0                                                                                |

A window is required on `fetch` and refused on `seed-demo`. Mixing the two window forms is an error
rather than a precedence rule: `--days 30 --from 2026-01-01T00` has two readable meanings and no
obviously right one, and whichever a rule picked would silently discard half of what was typed. The
same reasoning refuses `--days` on `seed-demo` instead of ignoring it — the demo tape is a fixed
synthetic span, and a quietly-ignored `--days 30` leaves an operator believing they seeded a month.

What is validated here is the spec's **shape** — three non-empty `:`-separated parts — and the
window. The venue and the interval are not: which venues a build can reach is a property of the
engine's own feature set and its collectors, and a roster copied into this crate would be a second
list to keep in step, refusing a venue the engine supports or accepting one it does not with equal
confidence. The engine's own error names what it can do.

## `--json` [#--json]

Both subcommands take it, because both write to a store and *what was written and where* is exactly
the question a caller driving this verb has. The document is `report_json`'s, and it carries the
request, the engine and the engine's own report:

| field         | what it holds                                                                                         |
| ------------- | ----------------------------------------------------------------------------------------------------- |
| `subcommand`  | `fetch` or `seed-demo`                                                                                |
| `store`       | what `--store` **named**, or `null` when the flag was absent — not a resolved path                    |
| `series`      | the spec split into `venue` / `symbol` / `interval`, plus the `spec` as typed; `null` for `seed-demo` |
| `window`      | `{days}` or `{from,to}`; `null` for `seed-demo`                                                       |
| `engine`      | the engine binary this process actually ran                                                           |
| `engine_argv` | the argv it ran with                                                                                  |
| `report`      | the engine's own stdout, line by line, **verbatim**                                                   |

Two of those are honest about a limit rather than convenient. `store` is `null` rather than a path
when no `--store` was given, because with the flag absent the **engine** resolves the root, in a
different process, and this side would be guessing. And `report` is left as lines: `backtest --fetch`
prints `N bars returned … M rows written` and `--seed-demo` prints a line per slice, and neither has
a machine mode of its own — so fielding those counts would mean re-implementing another crate's
output format in a crate that cannot see it change, which would start reporting a *wrong* count
rather than failing the day a word moves.

Under `--json` the engine's report moves to **stderr** and stdout carries the document and nothing
else. The lines are not lost: they are echoed to stderr as they arrive and appear again in `report`.

<Callout type="warn" title="A failure emits no document — read the exit code">
  The document is printed on **success only**, which is the shape every sibling in this crate already
  has ([`secrets list`](/docs/trader/reference/cli/set-up/secrets), `init`,
  [`backtest`](/docs/trader/reference/cli/research/backtest)): a failure is a sentence on stderr plus a rung on the
  [exit ladder](/docs/trader/reference/cli), and stdout carries nothing at all. It is deliberately not an
  `{"ok": false}` document — matching every sibling beats being cleverer than them in one, and a
  caller already has to read the exit code, which is the field such a document would duplicate.

  The rung is the **same** one the human path gives. A `--json` that folded the child's status
  differently would tell a wrapper to retry, or not to, on the strength of an output format; both paths
  call the one `fold_status` in `crates/vike-cli/src/cmd/engine.rs`. A bad command line is `2`, an
  engine that ran and failed is `1`, and an engine that could not be started at all is `3` — the rung a
  wrapper may back off and retry on.
</Callout>

## Where the engine comes from [#where-the-engine-comes-from]

`--engine PATH` wins and is **not probed for existence**: a named path that is not there must fail
with the name the operator typed, never by falling through to a different engine they did not ask
for. Otherwise `engine::locate` looks in `<project>/bin` (the directory
`vike_model::state_path::PROJECT_BIN_DIR` names), then beside this executable, then leaves the bare
name for `PATH` to resolve. A spawn failure is one message either way, so the two `--json` and human
paths cannot describe the same failure differently.

## Examples [#examples]

```sh
vike-cli data seed-demo                                   # the synthetic tape, no network
vike-cli data fetch binance:BTCUSDT:1h --days 180          # real public bars
vike-cli data fetch okx:BTC-USDT:1h --from 2026-01-01T00 --to 2026-02-01T00 --json
```

* [The `backtest` binary](/docs/trader/reference/binaries/backtest) — what `--fetch` and `--seed-demo`
  belong to, and the store precedence they use.
* [Running a backtest](/docs/trader/backtesting/running) — what to do with the data once it is there.


# vike-cli datahub (/docs/trader/reference/cli/data/datahub)



`vike-cli datahub setup` mints the pair of node keys a `vike-datahub` server authenticates with — CSPRNG bytes, one key scoped to observe and one to control — and writes them into the project's node-key store. Run it **on the datahub server's own box**. There is no argv form, no stdin form, and no `--from-env` form: no key value ever reaches or leaves this command in any shape, and what it prints is each key's ID, not the key itself.

## Usage [#usage]

```
vike-cli datahub setup [--rotate]
```

`setup` is the only subcommand. Nothing else parses — no subcommand at all, or any spelling but `setup`/`-h`/`--help`/`help`, is a clean parse error (`crates/vike-cli/src/cmd/datahub.rs`'s `parse`).

Mint a fresh pair:

```
vike-cli datahub setup
```

This refuses if either key already exists in the store. A key already written is a key some client is already signing with, so replacing it is a decision, not an idempotent re-run — the same refusal `backend setup` makes for its own pair (`crates/vike-cli/src/cmd/datahub.rs`'s `run_setup`).

Replace keys already in the store:

```
vike-cli datahub setup --rotate
```

<Callout type="warn" title="Rotating breaks every client holding the old pair">
  `--rotate` replaces both keys unconditionally, with no overlap window. Every client still holding the old pair stops working the moment the server restarts and loads the new ones (`crates/vike-cli/src/cmd/datahub.rs`'s `USAGE`).
</Callout>

`--rotate` takes no inline value: `--rotate=maybe` is a parse error rather than a silently-ignored value, because dropping it quietly is how a command line whose author meant something by `=maybe` leaves them believing they rotated when they did not (`crates/vike-cli/src/cmd/datahub.rs`'s `parse`).

A successful run prints the store's path, each key's name and ID, and the restart line:

```
minted into <path>:
  <key name>  id <id>
  <key name>  id <id>

restart the server so it loads them:
  sudo systemctl restart vike-datahub
```

It will then log `AUTHENTICATION REQUIRED` with both key IDs at next start — compare those against the two this command printed to confirm a client and the server hold the same pair (`crates/vike-cli/src/cmd/datahub.rs`'s `run_setup`).

## Why this is a separate verb, not a mode of `backend` [#why-this-is-a-separate-verb-not-a-mode-of-backend]

`backend` means a `vike-tradehub` node, and a datahub is not one: it speaks a different protocol, serves different verbs, and its control scope compiles client-supplied Rhai rather than placing orders. `vike-datahub` authenticates with the same two-key HMAC handshake `vike-tradehub` does, but until this verb existed nothing in the tree could generate a datahub's pair — `backend setup` mints the tradehub pair and validates names against a table that did not carry the datahub's, and `secrets set` refuses both datahub key names by design. The datahub deployed to prod2 on 2026-09-08 had its keys made with `openssl` at a shell, for exactly that reason (`crates/vike-cli/src/cmd/datahub.rs`'s module doc).

<Callout type="warn" title="Folding this into `backend setup --datahub` was considered and rejected">
  A flag would have to disable most of what `backend setup` does — the bind address, the control flag, the restart line — none of which apply to a datahub. A separate verb costs one word and keeps each command's help true to what it actually runs (`crates/vike-cli/src/cmd/datahub.rs`'s module doc).
</Callout>

## What it deliberately does not write [#what-it-deliberately-does-not-write]

This verb writes nothing but the key store itself. `backend setup` also sets `config.tradehub_addr` and, under `--control`, `flags.tradehub_control` — there is no equivalent pair to set here. The datahub server's bind address is not a value this command owns: it arrives as `VIKE_DATAHUB_ADDR`, an `Environment=` line `deploy/vike-datahub.service` sets. `config.datahub_addr` is a *client's* dial address, not the server's bind, so setting it from this command would move nothing on the datahub's own box (`crates/vike-cli/src/cmd/datahub.rs`'s `USAGE`).

An absent key store is refused rather than created — this command mints keys into a store that already exists; it does not stand one up (`crates/vike-cli/src/cmd/datahub.rs`'s module doc).

## Related [#related]

* [backend](/docs/trader/reference/cli/set-up/backend) — the equivalent mint for a `vike-tradehub` node's keys; its own doc is why the two verbs stay separate.
* [secrets](/docs/trader/reference/cli/set-up/secrets) — `secrets path` prints where this box's store lives; `secrets set` refuses both datahub key names outright.


# Data (/docs/trader/reference/cli/data)



| Verb                                          | What it owns                                                                                 |
| --------------------------------------------- | -------------------------------------------------------------------------------------------- |
| [data](/docs/trader/reference/cli/data/data)       | The hist store: fetch real bars or seed the demo tape, list what it holds, report coverage   |
| [datahub](/docs/trader/reference/cli/data/datahub) | Mints the node key pair a `vike-datahub` server authenticates with, on that server's own box |


# vike-cli backtest --profile (/docs/trader/reference/cli/research/backtest-profile)




A profile is the whole run as one TOML file: the data slice, the engine, the strategy, and — when
you want them — a parameter grid and a walk-forward protocol. It is the only form a run takes that
you can commit, diff, review and hand to a machine that is not yours.

**You never have to write one by hand.** Build a command line you like, then `--write-profile` it
and keep the file it hands back:

```sh
# The shape: get a run right on the command line, then freeze it
vike-cli backtest run --venue binance --symbols BTCUSDT --interval 1h \
    --from 2026-01-01T00 --to 2026-02-01T00 --strategy buy_hold \
    --cash 10000 --fee-rate 0.001 --write-profile profiles/btc_1h.toml

# ...and from then on the profile IS the run
vike-cli backtest run --profile profiles/btc_1h.toml
vike-cli backtest run --profile profiles/btc_1h.toml --set engine.slippage=0.0005
vike-cli backtest run --profile profiles/btc_1h.toml --show-effective
```

<Callout type="error" title="The schema is CLOSED, so a typo is a hard failure rather than a silent default">
  Every table below refuses an undeclared key. That is the property worth knowing before you edit a
  profile by hand: a misspelt key does not fall back to its default and it does not warn — the load
  fails and names it. The same closure is what makes `--set` safe to paste, and it is why
  `--show-effective` is worth running once after any hand edit: it prints what actually resolved,
  which is the only way to tell a key you set from a key you thought you set.
</Callout>

## The shape [#the-shape]

A profile is 11 possible tables, 5 of them at the top level, and
113 keys across all of them. 11 keys are **required** and the
rest have a default — so the shortest profile that loads is much smaller than this page:

```toml
[data]
from = "2026-01-01T00"
interval = "1h"
kind = "bar"
symbols = ["BTCUSDT", "ETHUSDT"]
to = "2026-02-01T00"
venue = "binance"
max_gap = "1d"
on_gap = "warn"
universe = "strict"

[engine]
cash = 10000
decide = "sequential"
fee_rate = 0.001
slippage = 0.0005

[strategy]
name = "buy_hold"
```

Every value above is one the CLI itself advertises as parsing, placed at the key that flag writes —
the example is joined from the two exported tables rather than typed here, so it cannot drift from
either.

**The required keys, in full:** `data.kind`, `data.from`, `data.to`, `engine.cash`, `strategy.name`, `data.series.venue`, `data.series.symbol`, `engine.impact.model`, `engine.fee.kind`, `engine.resolution.kind`, `engine.sizer.kind`. Each of the
optional tables is required ONCE YOU DECLARE IT: `[risk]`, `[walkforward]`, `[data.series]`, `[engine.impact]`, `[engine.fee]`, `[engine.resolution]`, `[engine.sizer]` may all be absent, and a table that is present must satisfy its own required
keys.

## Walk-forward windows [#walk-forward-windows]

A `[walkforward]` table turns a single run into a sequence of train/validate windows, and it must
declare **exactly one window form**. There are two, and they are not two spellings of one idea:

```toml
# form (a) — a SPLIT COUNT. The window length is whatever the range divided by N happens to be,
# so it moves when the range moves.
[walkforward]
n_splits = 6

# form (b) — DURATIONS. The window length is what you wrote, whatever the range does.
[walkforward]
train = "12mo"   test = "3mo"   step = "3mo"
train = "5000bars"   test = "1000bars"   # calendar and bar suffixes mix freely

# purge and embargo are legal on the DURATION form only — the gap has to be measured in the same
# units as the windows, and a split count has no length to measure against.
[walkforward]
train = "12mo"   test = "3mo"
purge   = "8h"   # bars dropped BETWEEN train and test
embargo = "1d"   # the minimum gap AFTER a validation window
```

<Callout type="warn" title="A step shorter than test is refused — by the RUNNER, not at load">
  `step` is how far each window advances, and an absent `step` **is** `test`, which tiles the windows
  edge to edge: each window starts where the last one ended. A **larger** `step` is legal and leaves a
  gap — the same separation `embargo` produces deliberately. A **shorter** one is refused by name,
  because the walk folds every window's out-of-sample curve onto ONE running equity, so overlapping
  windows would compound the same bars more than once and report a return and a Sharpe roughly the
  overlap factor too high, with nothing in the report showing it.

  Two things worth knowing about WHERE that refusal lives. It is the walk-forward runner's, not the
  profile loader's, so it fires when the walk starts rather than when the file parses. And it compares
  **resolved bar counts** against `data.interval`, both floored — so a `step` shorter than `test` in
  wall-clock but flooring to the same number of bars passes.
</Callout>

<Callout type="info" title="Tiling is not the same as judging every bar">
  Edge-to-edge windows mean no bar inside the walked region is validated twice and none is skipped
  between windows. They do not mean every bar is judged: the leading `train` bars (plus any `purge`
  gap) sit before the first validation window, and a trailing remainder shorter than `test` is
  dropped rather than shortened. Those bars are never validated at all, and no field in the report
  says how many they were.
</Callout>

<Callout type="info" title="purge is a gap; embargo DROPS WINDOWS — and it is not López de Prado's embargo">
  `purge` is the gap between a training half and the validation window that follows it, so a label or
  feature computed over a lookahead cannot straddle the boundary. A strategy whose features look back
  further than `purge` still leaks: the knob is a length you have to match to your own feature window,
  not a switch.

  ⚠ &#x2A;*`embargo` does something different from what its name promises.** It is a minimum gap required
  between one validation window's END and the next window's START, and a window that falls inside that
  gap is **dropped from the window list** — not shifted, and **no bars are held out of any training
  half**. So it borrows the word without the semantics: the form that removes post-validation bars
  from a later window's TRAIN side is a named reopener in the decision record, not what this key does.
  Read it as "thin the windows until they are this far apart". Both keys are legal on the duration
  form only, and both round UP to a whole number of bars.
</Callout>

| key        | takes     | when absent | what it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ---------- | --------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `n_splits` | `integer` | *absent*    | Number of out-of-sample windows — window form (a), the one that existed first.                                                                                                                                                                                                                                                                                                                                                                                                   |
| `train`    | `string`  | *absent*    | Window form (b)/(c) — the TRAIN window's length, as a `vike_model::time::parse_span` duration (`"12mo"`, `"90d"`, `"5000bars"`). Mutually exclusive with `Self::n_splits`; requires `Self::test`.                                                                                                                                                                                                                                                                                |
| `test`     | `string`  | *absent*    | Window form (b)/(c) — the VALIDATION window's length. Required with `Self::train`.                                                                                                                                                                                                                                                                                                                                                                                               |
| `step`     | `string`  | *absent*    | How far each window advances. Absent ⇒ equal to `Self::test`, which tiles the validation windows edge to edge.                                                                                                                                                                                                                                                                                                                                                                   |
| `purge`    | `string`  | *absent*    | Bars dropped BETWEEN train and test, so `test_start - train_end == purge` exactly.                                                                                                                                                                                                                                                                                                                                                                                               |
| `embargo`  | `string`  | *absent*    | The minimum gap AFTER a validation window before the next one may start. A window whose `test_start` falls inside the zone is DROPPED, not moved — moving it would make `Self::step` mean something other than what was written. Same duration-form-only rule as `Self::purge`, and the same ROUNDS-UP rule.                                                                                                                                                                     |
| `search`   | `string`  | *absent*    | Which search each window runs on its OWN training half — the knob that chooses between the two walk-forward protocols. Absent or `"none"` is the CONTROL (`WindowSearch::None`): every window trades the profile's own `strategy.params`, which is the fixed-parameter walk this section has always described. `"sweep"` — named for the table it expands — scores this profile's `sweep` grid on each window's train half and carries only the winner onto its validation half. |
| `mode`     | `string`  | *absent*    | The TRAIN-window shape (`WalkMode`): absent or `"anchored"` is the expanding window every split trains from bar 0; `"rolling"` trains on the ONE chunk immediately preceding the window. Case-insensitive and trimmed (`Self::walk_mode`), unknown values refused at load.                                                                                                                                                                                                       |
| `rank_by`  | `string`  | *absent*    | How a window SCORES its candidates when `Self::search` runs one: any of the four `RankMetric` names the sweep's own `--rank-by` takes (`"sharpe"` \| `"return"` \| `"max_dd"` \| `"equity"`, case-insensitive), defaulting to `RankMetric::default`. Consulted only when a search actually runs — the control scores nothing.                                                                                                                                                    |

**What it refuses, verbatim.** These are the sentences the binary prints, not a paraphrase of them
— which is why they carry the accepted set for the three string knobs above and the default each
one takes when absent:

| refused                                                                                                                                                                                                                                                                                                                                                                                                                                                  | raised by                       |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| \[walkforward] declares no window form — set n\_splits = N, or a train/test pair (e.g. train = "12mo", test = "3mo")                                                                                                                                                                                                                                                                                                                                     | `WalkforwardCfg::window_form`   |
| data.detail\_interval is unavailable to a \[walkforward] profile: the walk hands each window a sliced coarse series while nothing slices the detail tape, so every window's last step would fill against bars from AFTER the window ended. That is look-ahead, not merely waste. Run the profile without \[walkforward], or without the detail tape.                                                                                                     | `BacktestProfile::refusals`     |
| profile has no \[walkforward] table — a walk-forward needs a window form, e.g. `[walkforward] n_splits = 4` or `[walkforward] train = "12mo" test = "3mo"`                                                                                                                                                                                                                                                                                               | `walkforward_preflight`         |
| the \[walkforward] window form yields NO windows over the \{} bar(s) of \{symbol} in this range — a walk that evaluates nothing must not return a report that looks like one                                                                                                                                                                                                                                                                             | `walkforward_preflight`         |
| the duration window form needs BOTH walkforward.train and walkforward.test (step defaults to test) — a half-declared window has no shape                                                                                                                                                                                                                                                                                                                 | `WalkforwardCfg::window_form`   |
| unknown walkforward.mode \{other:?} (want anchored \| rolling; absent = anchored)                                                                                                                                                                                                                                                                                                                                                                        | `WalkforwardCfg::walk_mode`     |
| unknown walkforward.rank\_by \{raw:?} (want sharpe \| return \| max\_dd \| equity; absent = sharpe)                                                                                                                                                                                                                                                                                                                                                      | `WalkforwardCfg::rank_metric`   |
| unknown walkforward.search \{other:?} (want none \| sweep; absent = none, the no-search control)                                                                                                                                                                                                                                                                                                                                                         | `WalkforwardCfg::window_search` |
| walkforward.n\_splits and walkforward.train/test/step are two PROTOCOLS, not two spellings — a split count is defined BY the range and moves when the range moves, a duration does not. Set exactly one.                                                                                                                                                                                                                                                 | `WalkforwardCfg::window_form`   |
| walkforward.n\_splits must be >= 1, got 0                                                                                                                                                                                                                                                                                                                                                                                                                | `BacktestProfile::refusals`     |
| walkforward.n\_splits must be >= 1, got 0                                                                                                                                                                                                                                                                                                                                                                                                                | `resolve_windows`               |
| walkforward.purge / walkforward.embargo need the DURATION window form (train/test) — the split-count walk stays gap-free (decision 0046 — the bar mode walk forward has no purge). Replace n\_splits with a train/test pair, or drop the key.                                                                                                                                                                                                            | `WalkforwardCfg::window_form`   |
| walkforward.search = "grid" was renamed to "sweep" — one name for one knob, and it is the table it expands (\[sweep]). Write search = "sweep".                                                                                                                                                                                                                                                                                                           | `WalkforwardCfg::window_search` |
| walkforward.search = "sweep" needs a \[sweep] table to search — this profile has none, so every window would 'select' the one parameter set it already has. Add the grid, or drop the key for the no-search control.                                                                                                                                                                                                                                     | `BacktestProfile::refusals`     |
| walkforward.step resolves to \{step} bar(s) and walkforward.test to \{test} — a step shorter than the validation window makes consecutive windows OVERLAP, and the stitched out-of-sample curve would compound the same bars more than once, reporting a return and a Sharpe roughly the overlap factor too high. Set step >= test: equal tiles the windows edge to edge (that is also what an absent step means), and larger leaves a gap between them. | `resolve_windows`               |
| walkforward.\{key} is a duration, so it needs a bar interval to convert against — data.interval \{interval:?} is not one (want e.g. "1m", "1h", "1d"), or spell the window with the `bars` suffix                                                                                                                                                                                                                                                        | `to_bars`                       |
| walkforward.\{key} is shorter than one \{interval} bar — it would resolve to zero bars and change nothing; widen it or use the `bars` suffix                                                                                                                                                                                                                                                                                                             | `to_bars`                       |
| walkforward.\{key}: \{e}                                                                                                                                                                                                                                                                                                                                                                                                                                 | `span_field`                    |

## Position sizing [#position-sizing]

`[engine.sizer]` decides how big each entry is, and it is the knob most worth setting explicitly:
left alone, a strategy's own requested size passes straight through, so the size that reaches the
book is whatever the strategy happened to ask for rather than a share of the account you chose.

Each `kind` reads one knob of its own, and two of them **wrap another sizer** instead of sizing
anything themselves — which is what lets a budget and a throttle compose:

```toml
# the common case: every entry targets 2% of current equity as notional
[engine.sizer]
kind = "pct_equity"   pct = 0.02

# a chain: the same 2%-of-equity sizer, scaled down while the account is in drawdown
[engine.sizer]
kind = "drawdown_throttle"   sensitivity = 2.0   floor = 0.25

[engine.sizer.base]
kind = "pct_equity"   pct = 0.02
```

<Callout type="error" title="max_risk_pct with no stop sizes to ZERO — and a zero-size entry is dropped in silence">
  `max_risk_pct` sizes each entry so that hitting its stop costs exactly `pct` of equity:
  `qty = pct × equity / (|entry − stop| × multiplier)`. It needs the stop to arrive **on the entry
  call**, and only the plain market and limit entries carry one — the stop, trailing and close verbs
  all pass none.

  When no stop arrives it returns **zero**, the submit guards drop the order without pushing it, and
  **nothing is refused at load**. So a profile pairing this sizer with a strategy that enters through
  those verbs trades NOTHING, reports a flat curve, and raises no error anywhere. If you set this
  sizer, check the first few fills exist before you believe the result. (`pct_volatility` is the
  sibling that degrades instead: with no ATR it falls back to sizing on equity.)
</Callout>

**The kinds, and the knob each one requires.** Derived from the arms of the sizer's own
constructor, so a kind cannot appear here without being buildable and cannot be buildable without
appearing here:

| kind                | requires               | wraps a base sizer                          |
| ------------------- | ---------------------- | ------------------------------------------- |
| `pass_through`      | — *nothing*            | no — a base is refused                      |
| `fixed_dollar`      | `amount`               | no — a base is refused                      |
| `fixed_shares`      | `shares`               | no — a base is refused                      |
| `pct_equity`        | `pct`                  | no — a base is refused                      |
| `pct_volatility`    | `pct`                  | no — a base is refused                      |
| `max_risk_pct`      | `pct`                  | no — a base is refused                      |
| `portfolio_heat`    | `max_heat`             | **yes** — `[engine.sizer.base]` is required |
| `drawdown_throttle` | `sensitivity`, `floor` | **yes** — `[engine.sizer.base]` is required |

| key           | takes    | when absent  | what it does                                                                                                                                                                                                                                                                                                                                                                 |
| ------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kind`        | `string` | **required** | One of `"pass_through"` \| `"fixed_dollar"` \| `"fixed_shares"` \| `"pct_equity"` \| `"pct_volatility"` \| `"max_risk_pct"` \| `"portfolio_heat"` \| `"drawdown_throttle"` — every concrete `vike_analytics::sizing::PositionSizer` this crate ships and nothing else (`Self::build`).                                                                                       |
| `amount`      | `number` | *absent*     | `crate::sizing::FixedDollarSizer::amount` — fixed cash notional per entry. Required for `"fixed_dollar"`.                                                                                                                                                                                                                                                                    |
| `shares`      | `number` | *absent*     | `crate::sizing::FixedSharesSizer::shares` — fixed share/contract count per entry. Required for `"fixed_shares"`.                                                                                                                                                                                                                                                             |
| `pct`         | `number` | *absent*     | The knob `"pct_equity"` / `"pct_volatility"` / `"max_risk_pct"` each read as their own fraction of equity (target notional, ATR-risk budget, and stop-risk budget respectively — see `vike_analytics::sizing`'s doc on each). Required for those three kinds.                                                                                                                |
| `max_heat`    | `number` | *absent*     | `crate::sizing::PortfolioHeatSizer::max_heat` — total open-risk cap as a fraction of equity. Required for `"portfolio_heat"`.                                                                                                                                                                                                                                                |
| `sensitivity` | `number` | *absent*     | `crate::sizing::DrawdownThrottleSizer::sensitivity`. Required for `"drawdown_throttle"`.                                                                                                                                                                                                                                                                                     |
| `floor`       | `number` | *absent*     | `crate::sizing::DrawdownThrottleSizer::floor`. Required for `"drawdown_throttle"`.                                                                                                                                                                                                                                                                                           |
| `base`        | `table`  | *absent*     | The wrapped sizer for `"portfolio_heat"` / `"drawdown_throttle"` — required for those two kinds (`Self::build` refuses their absence), and REFUSED under every other kind, which reads it nowhere: a base under a scalar kind would run one sizer while the profile read as a chain. Boxed because `SizerCfg` nests itself — see `MAX_SIZER_DEPTH` for the bound on how far. |

| refused                                                                                                                                                                                                                                        | raised by                  |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| engine.sizer nesting is \{depth} levels deep (\[engine.sizer\{}]) — MAX\_SIZER\_DEPTH is \{MAX\_SIZER\_DEPTH}; flatten the base chain (no composition of the two wrapping kinds needs to nest this deep)                                       | `SizerCfg::build_at_depth` |
| engine.sizer.kind = "drawdown\_throttle" wraps a base sizer — add an \[engine.sizer.base] table naming it                                                                                                                                      | `SizerCfg::need`           |
| engine.sizer.kind = "portfolio\_heat" wraps a base sizer — add an \[engine.sizer.base] table naming it                                                                                                                                         | `SizerCfg::need`           |
| engine.sizer.kind = \{kind:?} does not wrap a base sizer, but \[engine.sizer\{}.base] is set — only "portfolio\_heat" and "drawdown\_throttle" read it, so the chain would run \{kind:?} alone. Remove the base table, or name a wrapping kind | `SizerCfg::need`           |
| engine.sizer.\{field} is required when engine.sizer.kind = \{kind:?}                                                                                                                                                                           | `SizerCfg::need`           |
| unknown engine.sizer.kind \{other:?} (want pass\_through \| fixed\_dollar \| fixed\_shares \| pct\_equity \| pct\_volatility \| max\_risk\_pct \| portfolio\_heat \| drawdown\_throttle)                                                       | `SizerCfg::need`           |

## What `--set` reaches [#what---set-reaches]

`--set <dotted key>=<value>` writes straight into the profile before it is sent, so it reaches any
**scalar leaf** under any table the schema declares — not only the keys that have a flag of their
own. Only the FIRST path segment is checked here; a wrong deeper key is refused by the far side,
because the schema is closed.

Three limits are worth knowing before you reach for it. There is **no array-index grammar**, so the
keys of `[[data.series]]` cannot be set per element — that table needs a file. A leaf that names a
whole TABLE is **refused rather than replaced**, so set its leaves instead; an inline-table
replacement has no `--set` spelling. And the closed schema does not reach the two untyped subtrees:
a typo under `strategy.params.*` or `paramscan.*` is a **silent no-op** that neither side catches.

```sh
# costs and fills
vike-cli backtest run --profile p.toml --set engine.fee_rate=0.001 --set engine.slippage=0.0002

# money you actually have — OFF unless you turn it on
vike-cli backtest run --profile p.toml --set engine.cash_gate=true --set engine.maint_margin=0.005

# the volume-participation cap, and position shape
vike-cli backtest run --profile p.toml --set engine.volume_limit=0.05 --set engine.max_open_positions=10

# a nested table is reached by its dotted path, like any other key
vike-cli backtest run --profile p.toml --set engine.sizer.kind=pct_equity --set engine.sizer.pct=0.02
```

<Callout type="error" title="A default run is frictionless — know what is off">
  Cash admission (`engine.cash_gate` → `false`), the margin and liquidation watchdog
  (`engine.maint_margin` → `0.0`, which short-circuits the check entirely) and the
  volume-participation cap (`engine.volume_limit` → absent, uncapped) are all **off** unless you turn
  them on. So a default run can spend money it does not have and fill more size than the event's own
  volume, and it will report the result without complaint. Turn them on before you believe a number,
  and confirm with `--show-effective`.

  ⚠ `engine.liq_buffer` is **not** in that group, and reading it as one is a mistake worth avoiding:
  it defaults to `0.10`, a deliberate cushion rather than zero. It only sits idle in a default run
  because the watchdog `maint_margin` gates is off — arm that and the buffer is already at 10%.
</Callout>

<Callout type="warn" title="Some engine behaviours no key reaches — and the list is not gated">
  Several engine behaviours are implemented and reachable from no profile key at all: the per-symbol
  sessions table (`session_gate` exposes the gate alone), the point-in-time membership mask that
  keeps a delisted instrument out of a replay, the interpolated order-latency model (the latency keys
  reach the constant model only), the funding-rate source seam, per-symbol sub-bar series, the
  stale-print fill deferral and option-expiry settlement.

  ⚠ &#x2A;*Do not treat that as a complete list.** Nothing checks this direction — the gate on the Rust
  side asserts every profile KEY reaches the engine, never that every engine field has a key — so the
  set is derived by diffing the two types and it can grow without anything noticing. If your run
  depends on one of these, the dependency is currently unexpressable in a profile, and a clean load is
  not evidence it was honoured.
</Callout>

**Every table it reaches, and how many keys each one has.** A nested table is reached by its
dotted path; the count is the file's, not this page's:

| table                 | keys | absent is legal    | reached as                              |
| --------------------- | ---- | ------------------ | --------------------------------------- |
| *the root*            | 7    | — *always present* | `--set <key>=<value>`                   |
| `[data]`              | 14   | no — **required**  | `--set data.<key>=<value>`              |
| `[engine]`            | 35   | no — **required**  | `--set engine.<key>=<value>`            |
| `[strategy]`          | 2    | no — **required**  | `--set strategy.<key>=<value>`          |
| `[risk]`              | 11   | yes                | `--set risk.<key>=<value>`              |
| `[walkforward]`       | 9    | yes                | `--set walkforward.<key>=<value>`       |
| `[data.series]`       | 3    | yes                | `--set data.series.<key>=<value>`       |
| `[engine.impact]`     | 5    | yes                | `--set engine.impact.<key>=<value>`     |
| `[engine.fee]`        | 14   | yes                | `--set engine.fee.<key>=<value>`        |
| `[engine.resolution]` | 5    | yes                | `--set engine.resolution.<key>=<value>` |
| `[engine.sizer]`      | 8    | yes                | `--set engine.sizer.<key>=<value>`      |

## Every key, table by table [#every-key-table-by-table]

The whole schema, in the order the types declare it. Nothing above needs this section to be read —
it is here so a question about one key always has an answer.

### The root table [#the-root-table]

the profile's own keys · refuses an undeclared key · read from `BacktestProfile`

| key           | takes            | when absent  | what it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------- | ---------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | `string`         | *absent*     | Free-form label (logs/report titles only — not used for lookup).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `data`        | `table`          | **required** | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `engine`      | `table`          | **required** | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `strategy`    | `table`          | **required** | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `risk`        | `table`          | *absent*     | Optional pre-trade `RiskGate` limits (runprofile-wiring-step2). The SAME `risk` schema AND the SAME compile-checked converter (`vike_exec::ProfileRisk::to_risk_limits`) `vike-core`'s `RunProfile` uses for paper/live — so a limit proven here (via `BacktestProfile::validate` + a real `SimBroker` denial) carries unchanged into paper and live, rather than being re-derived by a parallel converter that could drift. Absent (the default) ⇒ `crate::EngineParams::risk_limits` stays `None` ⇒ byte-identical to every profile written before this field existed: `engine` today has no `leverage` knob either, so `risk` is the ONLY way a harness profile arms the gate at all (`crate::engine::SimBroker::build_risk_gate`'s `(None, None) => None` arm). |
| `paramscan`   | `any TOML value` | *absent*     | Optional PARAMETER-SEARCH grid: each key is a `strategy.params` field name, each value an array of TOML values to cross-product over (expansion lives in `super::sweep::expand_paramscan`). Absent or empty means "not a parameter search".                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `walkforward` | `table`          | *absent*     | Optional anchored WALK-FORWARD config — the `paramscan` sibling: present means this profile can ALSO be run through `super::walkforward::run_walkforward` over `walkforward.n_splits` out-of-sample windows. Absent (the default) is byte-identical to every profile written before this field existed, and `run_backtest`/`run_paramscan` ignore the section entirely — exactly as they ignore a `sweep` table they were not asked to expand.                                                                                                                                                                                                                                                                                                                      |

### `[data]` [#data]

a table · **required** · refuses an undeclared key · read from `DataCfg`

**Choosing the slice.**

```sh
# Name the slice with the sugar flags — one venue, its symbols, the bar interval
vike-cli backtest run --profile p.toml --venue binance --interval 1h   # the single-venue form; two venues need [[data.series]], which --set cannot reach
vike-cli backtest run --profile p.toml --symbol BTCUSDT,ETHUSDT   # one comma list becomes ONE data.symbols array, in argv order
vike-cli backtest run --profile p.toml --from 2026-01-01T00 --to 2026-02-01T00   # YYYY-MM-DDTHH is UTC, and from must be <= to
vike-cli backtest run --profile p.toml --from 1767225600000 --to 1769904000000   # bare epoch-ms works here because the sugar keeps it a STRING

# The same keys, spelled the way the profile spells them
vike-cli backtest run --profile p.toml --set data.venue=bybit --set data.interval=4h   # the universal channel, but it skips --interval's own grammar check
vike-cli backtest run --profile p.toml --set data.to=2026-03-01T00   # a punctuated date stays a string; --set data.from=1767225600000 types an INTEGER and is refused far-side

# Bars or recorded ticks
vike-cli backtest run --profile p.toml --kind bar --interval 1h   # bar|tick is exact and case-sensitive; engine.timeframes must be COARSER than this interval
vike-cli backtest run --profile p.toml --kind tick   # the bar-only engine keys (timeframes, cash_gate, attach_funding) are then refused

# Read the slice back before spending any compute
vike-cli backtest run --profile p.toml --venue bybit --from 2026-02-01T00 --to 2026-03-01T00 --show-effective   # prints the resolved profile with each override's origin, then exits 0 — no daemon, no engine, no store
vike-cli backtest run --venue binance --symbol BTCUSDT --interval 1h --from 2026-01-01T00 --to 2026-02-01T00 --show-effective   # --profile is optional, so this reads back a slice built from flags alone
vike-cli backtest run --profile p.toml --from 2026-02-01T00 --to 2026-03-01T00 --write-profile feb.toml --show-effective   # freeze the shifted slice to a new file (it refuses an existing path) and stop before the run
```

| key                     | takes             | when absent  | what it does                                                                                                                                                                                                                                                                                                                                          |
| ----------------------- | ----------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data.venue`            | `string`          | *absent*     | Single-venue form: the one venue every entry of `Self::symbols` lives under. Mutually exclusive with `Self::series`.                                                                                                                                                                                                                                  |
| `data.symbols`          | `array of string` | `[]`         | Single-venue form: the symbols to load under `Self::venue`. Mutually exclusive with `Self::series`.                                                                                                                                                                                                                                                   |
| `data.series`           | `array of tables` | `[]`         | Cross-venue form (`[data.series]`): one entry per series, each naming its own `venue`, `symbol` and (tick mode only) lane `kind`. Mutually exclusive with `Self::venue`/`Self::symbols`.                                                                                                                                                              |
| `data.kind`             | `"bar" \| "tick"` | **required** | —                                                                                                                                                                                                                                                                                                                                                     |
| `data.interval`         | `string`          | `1d`         | —                                                                                                                                                                                                                                                                                                                                                     |
| `data.from`             | `string`          | **required** | Bare epoch-ms integer (as a string) or `YYYY-MM-DDTHH` UTC — see `BacktestProfile::range`.                                                                                                                                                                                                                                                            |
| `data.to`               | `string`          | **required** | Same format as `from`.                                                                                                                                                                                                                                                                                                                                |
| `data.warmup`           | `string`          | *absent*     | How much history the strategy's indicators need before the run's FIRST tradeable event — a bar/event count (`"200bars"`) or, in bar mode, a duration (`"7d"`) the base `Self::interval` divides into one. Absent (the default) is byte-identical to every profile written before this key existed: the gate stays exactly `Strategy::warmup()`.       |
| `data.detail_interval`  | `string`          | *absent*     | Opt-in INTRABAR DETAIL TAPE: a per-symbol series FINER than `Self::interval`, loaded over the same range and bucketed into each coarse step, against which every order is resolved while the strategy keeps deciding on the coarse timeframe. Absent (the default) is byte-identical to every profile written before this key existed. BAR MODE ONLY. |
| `data.explain`          | `true / false`    | `false`      | PLAN-THEN-APPLY: resolve this profile's whole data slice, report what the store holds for it, and EXIT without computing. Absent (the default) is byte-identical to every profile written before this key existed.                                                                                                                                    |
| `data.require_coverage` | `true / false`    | `false`      | ARM THE COVERAGE GATE: refuse (or warn on) a run whose window the store does not cover. Absent (the default) is byte-identical to every profile written before this key existed — the run loads whatever is there and says nothing.                                                                                                                   |
| `data.max_gap`          | `string`          | *absent*     | How much of the window `Self::require_coverage` tolerates missing in ONE span, as a fixed duration (`"1d"`, `"4h"`, `"900000"` ms). Absent = ZERO tolerance: any missing span at all is a finding.                                                                                                                                                    |
| `data.on_gap`           | `string`          | *absent*     | What `Self::require_coverage` DOES about a finding: `"refuse"` (the default — nothing runs), `"warn"` (the findings are logged and the run proceeds unchanged), or `"run"` (the gate is inert).                                                                                                                                                       |
| `data.universe`         | `string`          | *absent*     | POINT-IN-TIME UNIVERSE MEMBERSHIP — the survivorship defence. `"declared"` (the default, byte-identical: the symbol list is taken verbatim), `"covered"` (a member whose tape does not span the window is NAMED and the run proceeds), or `"strict"` (that run is REFUSED).                                                                           |

**What `[data]` refuses**, verbatim from the code that refuses it:

| refused                                                                                                                                                                                                                                                                                                                                                                                           | raised by                              |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| data.detail\_interval and engine.cash\_gate are mutually exclusive: cash\_gate routes the whole bar step through the gated fill lane and UNCONDITIONALLY disables the granular sub-bar lane, so the detail tape would be loaded, scanned and then ignored while every order was reported as resolved against it. Set one.                                                                         | `BacktestProfile::refusals`            |
| data.detail\_interval and engine.decide = "simultaneous" are mutually exclusive: the simultaneous mode implies the shared-cash admission phase, which routes the whole bar step through fill\_step\_gated and disables the granular sub-bar lane — the detail tape would be loaded, paid for and ignored                                                                                          | `BacktestProfile::refusals`            |
| data.detail\_interval is unavailable to a \[walkforward] profile: the walk hands each window a sliced coarse series while nothing slices the detail tape, so every window's last step would fill against bars from AFTER the window ended. That is look-ahead, not merely waste. Run the profile without \[walkforward], or without the detail tape.                                              | `BacktestProfile::refusals`            |
| data.detail\_interval \{raw:?} (\{ms}ms) must be strictly FINER than data.interval \{:?} (\{base}ms) — at this resolution each coarse step buckets at most one sub-bar, which resolves no stop-versus-target ambiguity while paying for a second whole store scan. This is the inverse of the engine.timeframes rule, where a synthesised series must be COARSER than the base                    | `DataCfg::detail_interval_ms`          |
| data.detail\_interval \{raw:?} is bar-mode only: the intrabar detail tape is bucketed into COARSE BAR steps and consulted by StrategyEngine::run's bar fill phase, and run\_ticks never reads those buckets — a tick replay already resolves every order against the tape it is replaying                                                                                                         | `DataCfg::detail_interval_ms`          |
| data.detail\_interval \{raw:?} is not a valid interval (want a count then one of s/m/h/d, e.g. "1m") — it is handed straight to the hist store as a series interval, so it must name a series the store can hold                                                                                                                                                                                  | `DataCfg::detail_interval_ms`          |
| data.detail\_interval \{raw:?} resolves to \{ms}ms — a zero-length window makes every sub-bar boundary the same instant                                                                                                                                                                                                                                                                           | `DataCfg::detail_interval_ms`          |
| data.from (\{start}) must be \<= data.to (\{end})                                                                                                                                                                                                                                                                                                                                                 | `BacktestProfile::refusals`            |
| data.interval \{:?} is not a valid interval, so data.detail\_interval \{raw:?} cannot be checked as finer than it                                                                                                                                                                                                                                                                                 | `DataCfg::detail_interval_ms`          |
| data.interval \{:?} is not a valid interval, so engine.timeframes cannot be checked against it                                                                                                                                                                                                                                                                                                    | `BacktestProfile::refusals`            |
| data.interval \{:?} is not a valid interval, so the duration data.warmup \{raw:?} cannot be converted to a step count                                                                                                                                                                                                                                                                             | `DataCfg::warmup_steps`                |
| data.interval \{:?} resolves to \{base}ms, so the duration data.warmup \{raw:?} names no number of steps                                                                                                                                                                                                                                                                                          | `DataCfg::warmup_steps`                |
| data.max\_gap is set without data.require\_coverage = true, so the gate whose tolerance it names is not armed and this key is read by nothing. Arm the gate, or remove the tolerance                                                                                                                                                                                                              | `BacktestProfile::refusals`            |
| data.max\_gap \{raw:?} is a BAR COUNT, and a gap in this store is a wall-clock span in epoch-ms: converting \{n} bars to a duration needs an interval, and a tick profile has none. Write the tolerance as fixed time — "4h", "1d"                                                                                                                                                                | `DataCfg::max_gap_ms`                  |
| data.max\_gap \{raw:?} is a CALENDAR span, and a calendar month is not a fixed number of milliseconds (one month from 31 January is 28 days, from 31 March 30) — so the tolerance would depend on where data.from happens to sit, and two runs naming the same tolerance would accept different amounts. Write it in fixed time — "30d"                                                           | `DataCfg::max_gap_ms`                  |
| data.max\_gap \{raw:?} resolves to \{ms}ms — a non-positive tolerance is what an ABSENT data.max\_gap already means (tolerate nothing), so this spelling can only mislead. Remove the key, or name a real duration                                                                                                                                                                                | `DataCfg::max_gap_ms`                  |
| data.max\_gap: \{e}                                                                                                                                                                                                                                                                                                                                                                               | `DataCfg::max_gap_ms`                  |
| data.on\_gap is set without data.require\_coverage = true, so the gate it configures is not armed and this key is read by nothing — while it reads as though a run over an uncovered window would be stopped. Arm the gate, or remove the disposition                                                                                                                                             | `BacktestProfile::refusals`            |
| data.on\_gap \{raw:?} is not one of \{roster}. It says what data.require\_coverage DOES about a window the store does not cover: `refuse` stops the run (the default, because a gate that only warns is invisible on every run nobody reads), `warn` logs the findings and runs unchanged, `run` leaves the gate inert while keeping the file's statement of what this run is supposed to require | `DataCfg::on_gap`                      |
| data.series\[\{:?}].kind = \{:?} is tick-mode only: a bar series has no quote/trade/book lanes to filter                                                                                                                                                                                                                                                                                          | `BacktestProfile::validate_data_slice` |
| data.symbols must not be empty                                                                                                                                                                                                                                                                                                                                                                    | `BacktestProfile::validate_data_slice` |
| data.symbols must not be empty (or use the cross-venue \[\[data.series]] form)                                                                                                                                                                                                                                                                                                                    | `BacktestProfile::validate_data_slice` |
| data.universe \{raw:?} is not one of \{roster}. It is the POINT-IN-TIME membership rule: `declared` takes the symbol list verbatim (the default), `covered` names every member whose tape does not span the window and runs anyway, `strict` refuses that run. None of the three ever drops a member — a universe a run narrowed silently would not be the one the profile names                  | `DataCfg::universe_mode`               |
| data.venue is required alongside data.symbols                                                                                                                                                                                                                                                                                                                                                     | `BacktestProfile::validate_data_slice` |
| data.venue/data.symbols and \[\[data.series]] are two ways to name the SAME slice — set exactly one (the \[\[data.series]] form is the cross-venue one)                                                                                                                                                                                                                                           | `BacktestProfile::validate_data_slice` |
| data.warmup \{raw:?} is a CALENDAR span, and a calendar month is not a fixed number of steps (one month from 31 January is 28 days, from 31 March 30) — so its length would depend on where data.from happens to sit, which is the irreproducibility this key exists to remove. Write it in bars ("200bars") or in fixed time ("90d")                                                             | `DataCfg::warmup_steps`                |
| data.warmup \{raw:?} is a DURATION, which is bar-mode only: a tick tape has no fixed cadence to divide it by, so no number of ticks corresponds to it. The engine gates run\_ticks on an EVENT index, so write the requirement as a count — e.g. "200bars" means 200 ticks here                                                                                                                   | `DataCfg::warmup_steps`                |
| data.warmup: \{e}                                                                                                                                                                                                                                                                                                                                                                                 | `DataCfg::warmup_steps`                |
| engine.fee.kind = "venue" needs engine.fee.venue — it is not inferred from \[data]. EngineParams::fee\_schedule is ONE schedule for the whole run, so a cross-venue slice has no single answer to infer, and naming the venue is the operator asserting which venue's book this run is costed at.                                                                                                 | `FeeCfg::validate_shape`               |
| engine.resolution: \{} window slug(s) in data.series have no binary winning\_index (first: \{names:?}). A window with no payout would end the run marked at its last traded price — remove it from the slice or supply its resolution.                                                                                                                                                            | `ResolutionCfg::build`                 |
| engine.snap\_to\_properties is single-venue only: the point-in-time instrument grid is looked up under one default\_venue, so a cross-venue \[\[data.series]] slice would snap every series to the first series' venue                                                                                                                                                                            | `BacktestProfile::validate_data_slice` |
| engine.timeframes \{tf:?} (\{ms}ms) must be coarser than data.interval \{:?} (\{base}ms) — a finer window cannot be synthesised from the base stream and would return the base bars re-labelled                                                                                                                                                                                                   | `BacktestProfile::refusals`            |
| unknown engine.decide \{other:?} (want sequential \| simultaneous; absent = sequential, the per-symbol walk in the order data.symbols lists them)                                                                                                                                                                                                                                                 | `EngineCfg::decide_mode`               |
| walk-forward is bar-mode only: the splitter divides ONE bar series by index, which a tick replay does not produce — set data.kind = "bar"                                                                                                                                                                                                                                                         | `walkforward_preflight`                |
| walkforward.\{key} is a duration, so it needs a bar interval to convert against — data.interval \{interval:?} is not one (want e.g. "1m", "1h", "1d"), or spell the window with the `bars` suffix                                                                                                                                                                                                 | `to_bars`                              |

### `[engine]` [#engine]

a table · **required** · refuses an undeclared key · read from `EngineCfg`

**Costs and fills.**

```sh
# Cost per fill — nothing in this group is mode-gated, so it applies in bar mode too
vike-cli backtest run --profile p.toml --fee 0.001 --slippage 0.0005   # sugar for engine.fee_rate + engine.slippage
vike-cli backtest run --profile p.toml --set engine.fee_rate=0.0004 --set engine.slippage=0.0002   # the taker rate you measured, 2bp of slip
vike-cli backtest run --profile p.toml --set engine.fee.kind=probability_scaled --set engine.fee.taker_rate=0.02   # the [engine.fee] model INSTEAD: a non-zero engine.fee_rate beside it is refused
vike-cli backtest run --profile p.toml --set engine.fee.maker_rebate_share=0.5   # credit half the maker rebate back

# Stop the tick lane filling your whole size at the quote
vike-cli backtest run --profile p.toml --kind tick --set engine.fill_model=l2book --set engine.slippage=0.0   # l2book rests what the book cannot cover, so the walk IS the slippage
vike-cli backtest run --profile p.toml --kind tick --set engine.fill_model=l2book --fee 0.0004   # tick-only per its doc, yet profile.json carries NO refusal row — a bar run accepts it and nothing changes

# Make a passive maker earn its fills — queue position first, then reaction time
vike-cli backtest run --profile p.toml --kind tick --set engine.queue_model=risk_adverse   # the conservative bound: the front shrinks only on hard evidence
vike-cli backtest run --profile p.toml --kind tick --set engine.queue_model=prob_power:2   # probabilistic, f(x)=x^2; prob_log is the third spelling
vike-cli backtest run --profile p.toml --kind tick --set engine.queue_model=prob_log --set engine.queue_seed_depth=500.0   # size-ahead fallback where neither book nor quote shows a depth
vike-cli backtest run --profile p.toml --kind tick --set engine.queue_model=risk_adverse --set engine.queue_min_hold_ms=2000   # refuse a fabricated sub-2s maker round-trip
vike-cli backtest run --profile p.toml --kind tick --set engine.order_latency_ms=50 --set engine.fill_latency_ms=50   # entry leg + response leg; tick-only too, and likewise unrefused in bar mode

# Confirm the stack before you spend an engine run
vike-cli backtest run --profile p.toml --kind tick --set engine.queue_model=prob_power:2 --show-effective   # prints each override's origin and STOPS — no engine, exit 0
vike-cli backtest run --profile p.toml --kind bar --set engine.queue_model=prob_power:2   # the ONE knob here bar mode refuses outright; the others just go quiet
```

**The money gates — every one of these is off until you set it.**

```sh
# Admit a fill only when the shared cash pool can fund it — OFF by default, so a run can overspend
vike-cli backtest run --profile p.toml --kind bar --set engine.cash_gate=true              # bar mode only: the tick lane never consults it
vike-cli backtest run --profile p.toml --kind bar --set engine.cash_gate=true --cash 25000 # size the pool it admits against; must be > 0

# Arm the liquidation watchdog — maint_margin defaults to 0, and 0 means the watchdog never fires
vike-cli backtest run --profile p.toml --set engine.maint_margin=0.005                     # 0.5% of adverse notional, a perp-like maintenance rate
vike-cli backtest run --profile p.toml --set engine.maint_margin=0.005 --set engine.liq_buffer=0.02   # cushion tighter than the 0.10 default
vike-cli backtest run --profile p.toml --set engine.maint_margin=0.005 --set engine.liq_buffer=0.0    # no cushion at all — the harshest honest run

# Bound one fill by what the market printed, and the position by margin — both uncapped by default
vike-cli backtest run --profile p.toml --set engine.volume_limit=0.1                       # at most 10% of the EVENT's own volume per fill; must be in (0, 1]
vike-cli backtest run --profile p.toml --set engine.volume_limit=1.0                       # the loosest value that is still a cap: all of one print, never more
vike-cli backtest run --profile p.toml --set engine.leverage=3.0                           # a 1/L margin requirement — only on a profile with NO [risk] table
vike-cli backtest run --profile p.toml --set engine.leverage=3.0 --set engine.clamp_to_leverage=true  # clamp an oversized order down instead of rejecting it

# Read back what this command line set, with each origin — no engine, no store, exit 0
vike-cli backtest run --profile p.toml --kind bar --set engine.cash_gate=true --set engine.maint_margin=0.005 --set engine.volume_limit=0.1 --show-effective
vike-cli backtest run --profile p.toml --set engine.liq_buffer=0.02 --show-effective       # the only way to SEE liq_buffer: unset, its 0.10 default lives where this side cannot read it
```

| key                              | takes             | when absent  | what it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| -------------------------------- | ----------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `engine.cash`                    | `number`          | **required** | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `engine.fee_rate`                | `number`          | `0`          | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `engine.slippage`                | `number`          | `0`          | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `engine.snap_to_properties`      | `true / false`    | `false`      | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `engine.attach_funding`          | `true / false`    | `false`      | Opt-in: window-join the stored market `funding` series onto the replayed bars' `Bar.funding` at each funding-event timestamp, for perp funding accrual + funding-reading strategies. The market funding-rate backfill (#761) writes a `(venue, symbol, "funding")` bar series whose each `Bar.funding = Some(rate)` sits at a funding-event ts; with this on, `crate::harness::window_join_funding` attaches each rate to the ONE price bar whose window contains the event (NEVER forward-filled onto every bar — that would make the `SimBroker` bar-loop accrual charge every bar instead of once per 8h/1h interval). Both consumers then work: the accrual (`engine.rs`, charges when `Bar.funding.is_some()`) and a funding-reading strategy's signal (`FundingCarryController` remembers the last rate in its funding book).                                                                                                                                                                                                                                                                                                |
| `engine.feed_latency`            | `true / false`    | `false`      | Opt-in feed-latency replay (see `crate::TickReplayConfig::feed_latency`): deliver ticks to the strategy in recorded ARRIVAL (`local_ts`) order instead of venue order, while order matching stays on venue `ts`. Absent (the default `false`) = today's venue-ordered replay, byte-identical. TICK MODE ONLY — a bar has no `local_ts`, so a profile that sets this with `data.kind = "bar"` is rejected by `BacktestProfile::validate` rather than silently ignored (the mirror of the bar-only `attach_funding` rule).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `engine.order_latency_ms`        | `integer`         | `0`          | Opt-in ORDER latency (see `crate::latency`): a fixed entry-leg delay in MILLISECONDS on every strategy order action (place / modify / cancel). The maker's quotes, re-prices and pulls only reach the matching engine `order_latency_ms` after it decides them, so it cannot react within one tick — the missing clock skew that otherwise lets a maker enter and exit in the same instant. `0` (the default) = zero latency, byte-identical. TICK MODE ONLY (only `run_ticks` arms the latency gate; the bar lane and vector kernel never consult it).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `engine.fill_latency_ms`         | `integer`         | `0`          | Opt-in FILL-notification latency (the response leg, see `crate::latency`): a fixed delay in MILLISECONDS before the strategy LEARNS of a fill. The fill books at the real time (equity/PnL are exact), but the strategy-visible shadow position (`vike_model::HftBroker::position`) does not advance until `fill_latency_ms` later — so a maker that polls its inventory cannot react (place its exit) inside that gap. Models the "time to realise you're filled" half of a real round-trip reaction. `0` (the default) = off, byte-identical. TICK MODE ONLY.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `engine.fill_model`              | `string`          | *absent*     | Opt-in tick-lane fill-model override: `"l2book"` (the ONE accepted value; case-insensitive, like `Self::queue_model`) selects the depth-capped `crate::engine::FillModelKind::L2Book` (a resting order fills only up to the DISPLAYED book depth; when the within-limit depth cannot cover its size it RESTS rather than filling size the market never showed), vs the default L1 spread-crossing `Tick` model (fills the full size at the quote). Absent ⇒ `Tick`, byte-identical. Any OTHER value is a fail-fast `HarnessError::Validation` at load (`EngineCfg::fill_model_kind`, the mirror of the `Self::queue_model` rule) — a typo like `"l2_book"` must not silently select the optimistic `Tick` model and undo the depth-cap realism knob. TICK MODE ONLY. Pair with `slippage = 0.0` (the book walk IS the slippage).                                                                                                                                                                                                                                                                                                   |
| `engine.seed_bar_interval_ms`    | `integer`         | *absent*     | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `engine.impact`                  | `table`           | *absent*     | Opt-in market-impact slippage on top of the flat `slippage` (see `crate::impact`). Absent (the default) = the frozen flat-slippage cost, byte-identical.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `engine.emulator_release_stops`  | `true / false`    | `false`      | Stop-verb release timing (see `crate::EngineParams::emulator_release_stops`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `engine.fee`                     | `table`           | *absent*     | Opt-in fee SCHEDULE (port backlog G7) — the shapes a flat `Self::fee_rate` cannot express. Absent (the default) = the flat `fee_rate` path, byte-identical. Setting BOTH is a validation error: two cost models would be configured and only one could win.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `engine.resolution`              | `table`           | *absent*     | Opt-in binary-resolution settlement (port backlog G6): builds the `crate::EngineParams::resolution` source + `resolution_end_ts` the engine has always consumed. Absent (the default) = no settlement source, byte-identical.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `engine.queue_model`             | `string`          | *absent*     | Opt-in QUEUE-POSITION fill model for the tick lane (see `crate::queue_model`): a resting limit — INCLUDING a tagged MAKER quote — no longer fills the instant price touches it, but only once a taker TRADE has consumed the size AHEAD of it in the FIFO queue (seeded from the replayed L2 book's size at that price, or the last L1 quote, or `Self::queue_seed_depth`). This is the realistic passive-maker fill: a quote earns the spread only when flow actually hits it, with partial fills on the trade's excess over the front. Absent (the default) = the frozen simple-crossing fill (`fill_tagged`), byte-identical. TICK MODE ONLY — the queue lane is consulted exclusively by `run_ticks`, so a bar-mode profile setting it is rejected by `BacktestProfile::validate` (the mirror of the `feed_latency` rule). Values (case-insensitive): `"risk_adverse"` (the conservative bound — front shrinks only on hard evidence), `"prob_power"` / `"prob_power:N"` (probabilistic, `f(x)=x^N`, default `N=1`), `"prob_log"`. For a real maker backtest feed the TRADE tape (and, for true size-ahead seeding, the BOOK). |
| `engine.queue_seed_depth`        | `number`          | *absent*     | Fallback front-of-queue depth (in size units) seeded when neither the replayed L2 book nor an L1 quote gives a size at a resting order's price — see `crate::queue_model`. Only consulted when `Self::queue_model` is set. Absent ⇒ `0.0` (a quote with no observed size-ahead fills on the first at-price trade).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `engine.queue_min_hold_ms`       | `integer`         | *absent*     | Minimum-hold floor in MS for the queued lane (`crate::EngineParams::queue_min_hold_ms`): a position-reducing (closing) fill is deferred until this long after the position opened, so the backtest can't fabricate a sub-second maker round-trip. Only consulted when `Self::queue_model` is set. Absent ⇒ `0` (off). Calibrate from real MM flip times (Polymarket BTC-5m ≈ 2s p10).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `engine.equity_sample_every`     | `integer`         | *absent*     | Equity-curve density for the tick lane (see `crate::EquitySampling`) — the SWEEP knob for a very long tape. The curve is two `Vec`s grown 16 bytes per priced tick, so a 100M-tick replay carries 1.6 GB of samples per run whether or not anything reads them.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `engine.timeframes`              | `array of string` | `[]`         | Higher timeframes synthesised from the base bar stream, look-ahead safe: a coarse bar becomes visible only once its window has fully elapsed. Each entry is an `vike_model::time::interval_ms` spelling (`"4h"`, `"1d"`). Absent (the default) registers nothing, which is byte-identical to before this key existed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `engine.cash_gate`               | `true / false`    | `false`      | Admit a fill only when the shared cash pool can fund it. Default `false`, which is what every profile written before this key did.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `engine.decide`                  | `string`          | *absent*     | WHEN a multi-symbol step is decided — `"sequential"` (absent = the default, byte-identical to every profile written before this key) or `"simultaneous"`. Resolved by `decide_mode`, which owns the unknown-spelling refusal; the ARGUMENT is in `crate::DecideMode`, and this doc deliberately does not restate it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `engine.maint_margin`            | `number`          | `0`          | Maintenance-margin RATE (a fraction of adverse notional), folded as `\|size\| · adverse · multiplier · maint_margin` by the liquidation watchdog.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `engine.liq_buffer`              | `number`          | `0.10`       | Equity cushion held above the maintenance requirement before the watchdog liquidates. ⚠ Defaults to `0.10` to match `EngineParams::default()` — a bare `#serde(default)` would give `0.0` and silently change every profile that omits the key.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `engine.venue_style_liquidation` | `true / false`    | `false`      | Opt-in stress knob. ⚠ `true` selects the retired TOTAL-WIPE liquidation model — once `eq_adv \<= maint_margin * notional_adv` at the intrabar adverse marks, it force-closes the WHOLE account (bar mode, `StrategyEngine::check_liquidation`) / the triggering symbol in full (tick mode, `StrategyEngine::check_liquidation_tick`). `false` (the default) runs the shared LEAN law (`vike_model::cross_liquidation_plan`) instead: PARTIAL, losers-first liquidation with the `liq_buffer` grace line — the opposite of a total wipe. Despite its name, `true` is the CRUDER model, not the gentler one.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `engine.volume_limit`            | `number`          | *absent*     | Participation cap: the fraction of the EVENT's own volume any one fill may take. `None` (the default) means uncapped, which is what every profile did before this key — and which lets a backtest "trade" more than the market traded.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `engine.max_open_positions`      | `integer`         | `0`          | Ceiling on concurrently open positions. ⚠ `0` is the engine's UNLIMITED, not "none" — it is the default, and it is what every profile written before this key did.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `engine.max_open_long`           | `integer`         | `0`          | Ceiling on concurrently open LONG positions. ⚠ `0` means unlimited, as above.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `engine.max_open_short`          | `integer`         | `0`          | Ceiling on concurrently open SHORT positions. ⚠ `0` means unlimited, as above.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `engine.multiplier`              | `number`          | `1.0`        | Contract multiplier applied to every symbol without its own row in `Self::multipliers`. ⚠ Defaults to `1.0`, matching `EngineParams::default()` — a bare `#serde(default)` would give `0.0` and zero every position's notional.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `engine.multipliers`             | `table of number` | `{}`         | Per-symbol contract multipliers, e.g. `ES = 50.0`. A `BTreeMap` rather than a `HashMap` because the engine takes an ordered `Vec` and a run must not depend on hash order.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `engine.leverage`                | `number`          | *absent*     | The run's own leverage. ⚠ Distinct from `risk max_leverage`, which reaches the same gate through `ProfileRisk::im_requirement` but is a CEILING — this is what the run uses, that is what it may not exceed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `engine.clamp_to_leverage`       | `true / false`    | `false`      | Clamp an order down to what `Self::leverage` allows instead of rejecting it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `engine.settlement_period_ms`    | `integer`         | *absent*     | Variation-settlement cadence in milliseconds — how often open-position profit is realised into cash instead of accruing. `None` (the default) never settles, which is what every profile did before this key.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `engine.session_gate`            | `true / false`    | `false`      | Defer an order that falls outside its symbol's trading session instead of filling it. Deferrals are already counted and already reach the report as `BacktestResult::session_deferrals`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `engine.sizer`                   | `table`           | *absent*     | How a strategy's requested size becomes an order size (`vike_analytics::sizing::PositionSizer`, the WealthLab PosSizer port). `None` (the default) passes the request through unchanged (`crate::sizing::PassThroughSizer`) — what every profile did before this key existed (`StrategyEngine::new` installs it whenever `EngineParams::sizer` is `None`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

**What `[engine]` refuses**, verbatim from the code that refuses it:

| refused                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | raised by                              |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| data.detail\_interval and engine.cash\_gate are mutually exclusive: cash\_gate routes the whole bar step through the gated fill lane and UNCONDITIONALLY disables the granular sub-bar lane, so the detail tape would be loaded, scanned and then ignored while every order was reported as resolved against it. Set one.                                                                                                                                                                                                                                                                                                                                                                         | `BacktestProfile::refusals`            |
| data.detail\_interval and engine.decide = "simultaneous" are mutually exclusive: the simultaneous mode implies the shared-cash admission phase, which routes the whole bar step through fill\_step\_gated and disables the granular sub-bar lane — the detail tape would be loaded, paid for and ignored                                                                                                                                                                                                                                                                                                                                                                                          | `BacktestProfile::refusals`            |
| data.detail\_interval \{raw:?} (\{ms}ms) must be strictly FINER than data.interval \{:?} (\{base}ms) — at this resolution each coarse step buckets at most one sub-bar, which resolves no stop-versus-target ambiguity while paying for a second whole store scan. This is the inverse of the engine.timeframes rule, where a synthesised series must be COARSER than the base                                                                                                                                                                                                                                                                                                                    | `DataCfg::detail_interval_ms`          |
| data.interval \{:?} is not a valid interval, so engine.timeframes cannot be checked against it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `BacktestProfile::refusals`            |
| engine.attach\_funding is bar-mode only: the per-interval funding accrual runs in the bar loop; the tick lane carries no funding fold to feed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `BacktestProfile::refusals`            |
| engine.cash must be > 0, got \{}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `BacktestProfile::refusals`            |
| engine.cash\_gate is bar-mode only: the shared-cash admission phase is StrategyEngine::run's own bar step (fill\_step\_gated), and run\_ticks never consults it — a tick profile setting it would change nothing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `BacktestProfile::refusals`            |
| engine.clamp\_to\_leverage is unavailable to a profile carrying \[risk]: SimBroker::build\_risk\_gate returns None on clamp\_to\_leverage BEFORE it reads risk\_limits, so the clamp disarms the pre-trade gate entirely and EVERY \[risk] limit — not just max\_leverage — is discarded. Drop clamp\_to\_leverage to keep \[risk]'s gate, or remove \[risk] and clamp against engine.leverage alone                                                                                                                                                                                                                                                                                              | `BacktestProfile::refusals`            |
| engine.clamp\_to\_leverage needs engine.leverage: there is nothing to clamp to                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `BacktestProfile::refusals`            |
| engine.decide = "simultaneous" is bar-mode only: the cross-sectional allocator it orders is StrategyEngine::fill\_step\_gated, reached only from StrategyEngine::run — run\_ticks consults neither it nor cash\_gate, so a tick profile setting it would change nothing                                                                                                                                                                                                                                                                                                                                                                                                                           | `BacktestProfile::refusals`            |
| engine.decide = "simultaneous" is not built for a run with a pre-trade risk gate: remove \[risk] and engine.leverage, or keep engine.decide unset. With a gate armed, SimBroker::gate\_order folds the pending set as it ACCUMULATES during the on\_bar fan-out, so the symbol judged first faces the whole step budget and later ones face the remainder — the DECISION is still taken in symbol-list order and no fill-phase ranking can repair it. Closing it needs a step-boundary budget snapshot, which does not exist                                                                                                                                                                      | `BacktestProfile::refusals`            |
| engine.equity\_sample\_every is tick-mode only: the bar lane records one equity sample per BAR (bounded by the bar count), so there is nothing to thin                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `BacktestProfile::refusals`            |
| engine.fee and a non-zero engine.fee\_rate (\{}) are two different cost models — set exactly one                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `BacktestProfile::refusals`            |
| engine.fee.kind = "per\_share\_with\_floor" needs BOTH per\_share and min. The floor is the whole reason this shape exists — a per-share fee with no minimum is a flat rate wearing a different name, and it is the configuration that makes a small-size high-frequency run backtest as viable and then lose to the broker minimum live. Write min = 0.0 to assert there is genuinely no floor.                                                                                                                                                                                                                                                                                                  | `FeeCfg::validate_shape`               |
| engine.fee.kind = "per\_share\_with\_floor" needs engine.multiplier = 1.0 (the default) and no engine.multipliers row other than 1.0: the fee path scales the schedule's answer by the contract multiplier, so a per-ORDER minimum would be charged per CONTRACT. This shape models an equities book. Drop the multiplier, or price a multiplied contract with percent\_maker\_taker.                                                                                                                                                                                                                                                                                                             | `BacktestProfile::refusals`            |
| engine.fee.kind = "percent\_maker\_taker" needs at least one of maker\_bps / taker\_bps — a table naming neither describes no cost, which is what kind = "free" says on purpose. A genuinely zero-fee side is written as the explicit 0.0, so the zero is an assertion rather than an omission.                                                                                                                                                                                                                                                                                                                                                                                                   | `FeeCfg::validate_shape`               |
| engine.fee.kind = "percent\_of\_underlying" needs BOTH bps and premium\_cap\_pct — the cap is half the rule it models (min(bps x underlying, cap x premium)), and it is the half that binds for a cheap deep-OTM option.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `FeeCfg::validate_shape`               |
| engine.fee.kind = "venue" needs engine.fee.venue — it is not inferred from \[data]. EngineParams::fee\_schedule is ONE schedule for the whole run, so a cross-venue slice has no single answer to infer, and naming the venue is the operator asserting which venue's book this run is costed at.                                                                                                                                                                                                                                                                                                                                                                                                 | `FeeCfg::validate_shape`               |
| engine.fee.kind = "venue" resolves ONE schedule for the whole run, and this run's \{venue:?} series straddle \{} fee lanes (\{}) — a venue prices its lanes completely differently (crates/vike-model/src/fees.rs's fee\_schedule\_for carries the measurement per lane), so one row would misprice the other lane. Split the run per lane, or set engine.fee.symbol to name the lane this run is costed at.                                                                                                                                                                                                                                                                                      | `FeeCfg::fee_lane_for`                 |
| engine.fee.pm\_curve is polymarket-only, and this table names venue \{:?} — vike\_model::fee\_schedule\_for\_with\_pm\_curve delegates to fee\_schedule\_for for every other venue, so the flag would configure nothing while the run was read as curve-priced. Drop it.                                                                                                                                                                                                                                                                                                                                                                                                                          | `FeeCfg::validate_shape`               |
| engine.fee.premium\_cap\_pct must be > 0, got \{} — a zero cap is not "no cap". FeeSchedule::commission on this shape is min(bps x premium, cap x premium), so a zero cap zeroes the whole commission and the run pays no fee at all while the profile reads as fee-modelled. crates/vike-model/src/fees.rs's fee\_schedule\_for carries the real Deribit cap in its "deribit" arm.                                                                                                                                                                                                                                                                                                               | `FeeCfg::validate_shape`               |
| engine.fee.venue = \{venue:?} names a venue this run does not load, so there is no symbol to resolve its fee LANE from — and answering with the bare-venue row would charge a perp run at the venue's SPOT schedule, the mispricing the lane key exists to end. This run's series are on: \{}. Name a venue the slice trades, or set engine.fee.symbol outright.                                                                                                                                                                                                                                                                                                                                  | `FeeCfg::fee_lane_for`                 |
| engine.fee.\{key} is a knob of kind \{owner:?}, and this table declares kind \{kind:?} — nothing would read it. A COST knob that configures nothing is worse than an absent one: the operator reads the profile as priced at what they wrote and the run prices at something else. Set the kind this knob belongs to, or drop the knob.                                                                                                                                                                                                                                                                                                                                                           | `FeeCfg::validate_shape`               |
| engine.fee.\{name} must be finite and >= 0, got \{v}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `FeeCfg::validate_shape`               |
| engine.feed\_latency is tick-mode only: it re-orders recorded ticks by their machine receive stamp (local\_ts), which a bar series does not carry                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `BacktestProfile::refusals`            |
| engine.impact.exec\_time must be > 0, got \{}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `ImpactCfg::build`                     |
| engine.impact.window must be >= 3 (two returns), got \{}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `ImpactCfg::build`                     |
| engine.impact.\{name} must be > 0 and finite, got \{v}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `ImpactCfg::build`                     |
| engine.leverage and \[risk] are two different margin sources for the same gate — set exactly one. With clamp\_to\_leverage off (the default) there are three configurations and \[risk] wins all of them: SimBroker::build\_risk\_gate's (Some(l), \_) arm takes risk\_limits unconditionally, so a \[risk] that sets max\_leverage answers with ITS number, a \[risk] that does not sets no margin requirement at all, and either way engine.leverage's 1/L im\_requirement is silently discarded. (With clamp\_to\_leverage on, neither reaches a gate — that combination is refused separately.) Set risk.max\_leverage instead, or remove \[risk] to use engine.leverage's 1/L margin mapping | `BacktestProfile::refusals`            |
| engine.leverage must be > 0, got \{l} — omit the key for unlevered                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `BacktestProfile::refusals`            |
| engine.liq\_buffer must be >= 0, got \{}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `BacktestProfile::refusals`            |
| engine.maint\_margin must be >= 0, got \{} — 0 means the liquidation watchdog is off, and a negative rate has no meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `BacktestProfile::refusals`            |
| engine.multiplier must be > 0, got \{} — it scales every position's notional, so zero makes every trade worth nothing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `BacktestProfile::refusals`            |
| engine.multipliers.\{sym} must be > 0, got \{m}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `BacktestProfile::refusals`            |
| engine.multipliers.\{sym} names a symbol this run does not load — the engine matches a multiplier row by EXACT symbol name and otherwise falls back to the global engine.multiplier, so this row would change nothing. The data slice is: \{}                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `BacktestProfile::refusals`            |
| engine.queue\_model is tick-mode only: the FIFO queue lane runs in the tick/book replay path, which a bar series does not drive                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `BacktestProfile::refusals`            |
| engine.resolution.window\_secs must be > 0, got \{}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `ResolutionCfg::validate_shape`        |
| engine.resolution.winners\[\{slug:?}] = \{wi} is not a binary outcome index (0 or 1). Non-binary and unresolved (-1) values are real on-chain facts and are never coerced to "both sides lose" — drop the window from the run instead.                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `ResolutionCfg::validate_shape`        |
| engine.resolution: \{} window slug(s) in data.series have no binary winning\_index (first: \{names:?}). A window with no payout would end the run marked at its last traded price — remove it from the slice or supply its resolution.                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `ResolutionCfg::build`                 |
| engine.settlement\_period\_ms must be > 0, got \{ms} — omit the key to never settle                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `BacktestProfile::refusals`            |
| engine.sizer nesting is \{depth} levels deep (\[engine.sizer\{}]) — MAX\_SIZER\_DEPTH is \{MAX\_SIZER\_DEPTH}; flatten the base chain (no composition of the two wrapping kinds needs to nest this deep)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `SizerCfg::build_at_depth`             |
| engine.sizer.kind = "drawdown\_throttle" wraps a base sizer — add an \[engine.sizer.base] table naming it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `SizerCfg::need`                       |
| engine.sizer.kind = "portfolio\_heat" wraps a base sizer — add an \[engine.sizer.base] table naming it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `SizerCfg::need`                       |
| engine.sizer.kind = \{kind:?} does not wrap a base sizer, but \[engine.sizer\{}.base] is set — only "portfolio\_heat" and "drawdown\_throttle" read it, so the chain would run \{kind:?} alone. Remove the base table, or name a wrapping kind                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `SizerCfg::need`                       |
| engine.sizer.\{field} is required when engine.sizer.kind = \{kind:?}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `SizerCfg::need`                       |
| engine.snap\_to\_properties is single-venue only: the point-in-time instrument grid is looked up under one default\_venue, so a cross-venue \[\[data.series]] slice would snap every series to the first series' venue                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `BacktestProfile::validate_data_slice` |
| engine.timeframes is bar-mode only: the coarse series are resampled from the base BAR stream, and a tick profile has none                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `BacktestProfile::refusals`            |
| engine.timeframes \{tf:?} (\{ms}ms) must be coarser than data.interval \{:?} (\{base}ms) — a finer window cannot be synthesised from the base stream and would return the base bars re-labelled                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `BacktestProfile::refusals`            |
| engine.timeframes \{tf:?} is not a valid interval (want a count then one of s/m/h/d, e.g. "4h")                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `BacktestProfile::refusals`            |
| engine.timeframes \{tf:?} resolves to \{ms}ms — a zero-length window makes every boundary the same instant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `BacktestProfile::refusals`            |
| engine.volume\_limit must be in (0, 1], got \{v} — it is the fraction of the EVENT's own volume one fill may take (a bar's volume in bar mode, ONE PRINT's in tick mode), so 1.0 is all of it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `BacktestProfile::refusals`            |
| unknown engine.decide \{other:?} (want sequential \| simultaneous; absent = sequential, the per-symbol walk in the order data.symbols lists them)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `EngineCfg::decide_mode`               |
| unknown engine.fee.kind \{kind:?} (known: \{}; a single flat fraction of notional may also stay on engine.fee\_rate, which is the same shape as percent\_maker\_taker charged to both sides)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `FeeCfg::validate_shape`               |
| unknown engine.fee.kind \{other:?} (known: \{})                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `FeeCfg::build_for`                    |
| unknown engine.impact.model \{other:?} (known: "almgren\_chriss")                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `ImpactCfg::build`                     |
| unknown engine.resolution.kind \{:?} (known: "binary\_outcome")                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `ResolutionCfg::validate_shape`        |
| unknown engine.sizer.kind \{other:?} (want pass\_through \| fixed\_dollar \| fixed\_shares \| pct\_equity \| pct\_volatility \| max\_risk\_pct \| portfolio\_heat \| drawdown\_throttle)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `SizerCfg::need`                       |

### `[strategy]` [#strategy]

a table · **required** · refuses an undeclared key · read from `StrategyCfg`

**Naming a strategy and passing its knobs.**

```sh
# Name the strategy and fill [strategy.params] — --param takes ONE FLAT scalar, so a table knob needs the file
vike-cli backtest run --profile p.toml --strategy momentum --param qty=0.25           # --strategy is sugar for strategy.name
vike-cli backtest run --profile p.toml --set strategy.name=momentum --param tp=0.01   # the un-sugared spelling of that same key
vike-cli backtest run --profile p.toml --strategy grid --param rungs=4                # rungs is Integer: `rungs=4.0` sets nothing, silently
vike-cli backtest run --profile p.toml --strategy momentum --param threshold=0.002    # a knob name is checked by NOBODY — a typo is a no-op

# The script form: --script fills strategy.params.src and implies strategy.name = "rhai"
vike-cli backtest run --profile p.toml --script s.rhai                                # the file's SOURCE TEXT is injected, not its path
vike-cli backtest run --profile p.toml --script s.rhai --param qty=2                  # every numeric param but `src` overrides a param() default

# Prove what [strategy] resolved to before spending a run
vike-cli backtest run --profile p.toml --strategy momentum --param qty=0.25 --show-effective    # resolved TOML + each override's origin, exit 0
vike-cli backtest run --profile p.toml --strategy momentum --param qty=0.25 --write-profile momentum-qty.toml   # ...the same document, then it runs
```

**Before you type a name, ask what exists.** `backtest strategies` prints the roster and
`backtest params --strategy <name>` prints each declared key with the TOML type its reader takes —
both documented where they live, on [the command surface](/docs/trader/reference/cli/research/backtest).
Those four lines used to be repeated here, and a command line that lives in two places is one that
can drift between them.

| key               | takes            | when absent  | what it does |
| ----------------- | ---------------- | ------------ | ------------ |
| `strategy.name`   | `string`         | **required** | —            |
| `strategy.params` | `any TOML value` | `{}`         | —            |

**What `[strategy]` refuses**, verbatim from the code that refuses it:

| refused                         | raised by                    |
| ------------------------------- | ---------------------------- |
| strategy.params must be a table | `require_overridable_params` |
| strategy.params must be a table | `profile_with_overrides`     |

### `[risk]` [#risk]

a table · optional · refuses an undeclared key · read from `ProfileRisk`

| key                                | takes          | when absent  | what it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ---------------------------------- | -------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `risk.tick_size`                   | `number`       | **required** | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `risk.lot_size`                    | `number`       | **required** | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `risk.min_notional`                | `number`       | **required** | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `risk.min_qty`                     | `number`       | **required** | per-order minimum quantity floor (venue lot-size grid); checked on the lot-rounded qty.                                                                                                                                                                                                                                                                                                                                                                                                              |
| `risk.max_notional_per_order`      | `number`       | **required** | `risk max_notional_per_order` — the per-order notional cap the pre-trade gate evaluates on **EVERY order this engine admits**, whatever its origin (strategy-emitted, control-socket-originated, reconcile-originated). It lands verbatim in `RiskLimits::max_notional_per_order` and is denied as `over-max-notional`.                                                                                                                                                                              |
| `risk.max_total_exposure`          | `number`       | **required** | `risk max_total_exposure` — cap on **ONE SYMBOL's** projected open notional at **ONE VENUE**, in the account's quote currency. Despite the name it is NOT an account-wide, cross-symbol or cross-venue total: it lands verbatim in `RiskLimits::max_total_exposure`, whose doc is the authority on the scope, on why the name is kept, and on the test that pins it. Size it for a SINGLE instrument — an operator who sizes it for a whole book of N symbols gets an N× weaker cap than they wrote. |
| `risk.max_orders_per_window`       | `integer`      | **required** | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `risk.window_ms`                   | `integer`      | `0`          | throttle window (ms); only active when `max_orders_per_window` is set                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `risk.max_leverage`                | `number`       | **required** | THE leverage knob (>= 1.0), e.g. `10.0` ⇒ 10x. Arms the pre-trade buying-power check by converting to `RiskLimits::im_requirement` (`1.0 / max_leverage`) — see `ProfileRisk::im_requirement` and the module doc's "One leverage concept, one name". Omitted ⇒ the buying-power lane stays off here (a live mount then applies its own conservative 1× rescue).                                                                                                                                      |
| `risk.block_reduce_only_overshoot` | `true / false` | `false`      | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `risk.required_free_bp_pct`        | `number`       | `0`          | LEAN free-buying-power haircut on equity, `[0.0, 1.0)`                                                                                                                                                                                                                                                                                                                                                                                                                                               |

**What `[risk]` refuses**, verbatim from the code that refuses it:

| refused                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | raised by                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| engine.clamp\_to\_leverage is unavailable to a profile carrying \[risk]: SimBroker::build\_risk\_gate returns None on clamp\_to\_leverage BEFORE it reads risk\_limits, so the clamp disarms the pre-trade gate entirely and EVERY \[risk] limit — not just max\_leverage — is discarded. Drop clamp\_to\_leverage to keep \[risk]'s gate, or remove \[risk] and clamp against engine.leverage alone                                                                                                                                                                                                                                                                                              | `BacktestProfile::refusals` |
| engine.decide = "simultaneous" is not built for a run with a pre-trade risk gate: remove \[risk] and engine.leverage, or keep engine.decide unset. With a gate armed, SimBroker::gate\_order folds the pending set as it ACCUMULATES during the on\_bar fan-out, so the symbol judged first faces the whole step budget and later ones face the remainder — the DECISION is still taken in symbol-list order and no fill-phase ranking can repair it. Closing it needs a step-boundary budget snapshot, which does not exist                                                                                                                                                                      | `BacktestProfile::refusals` |
| engine.leverage and \[risk] are two different margin sources for the same gate — set exactly one. With clamp\_to\_leverage off (the default) there are three configurations and \[risk] wins all of them: SimBroker::build\_risk\_gate's (Some(l), \_) arm takes risk\_limits unconditionally, so a \[risk] that sets max\_leverage answers with ITS number, a \[risk] that does not sets no margin requirement at all, and either way engine.leverage's 1/L im\_requirement is silently discarded. (With clamp\_to\_leverage on, neither reaches a gate — that combination is refused separately.) Set risk.max\_leverage instead, or remove \[risk] to use engine.leverage's 1/L margin mapping | `BacktestProfile::refusals` |
| risk.max\_orders\_per\_window is a wall-clock order-rate throttle — meaningless in backtest sim time (a replayed month can execute in under a second, which would spuriously rate-limit every order; SimBroker::build\_risk\_gate always disarms this field for the identical reason on the live-parity gate it mounts). Remove it from `[risk]` — every other risk.\* limit is honored                                                                                                                                                                                                                                                                                                           | `BacktestProfile::refusals` |

### `[walkforward]` [#walkforward]

a table · optional · refuses an undeclared key · read from `WalkforwardCfg`

**Declaring a window form, and what gets refused.**

```sh
# Slice the range you already load into N out-of-sample windows
vike-cli backtest run --profile wf.toml --set walkforward.n_splits=6 --addr 127.0.0.1:7880   # --local is REFUSED on a [walkforward] profile, so every line here dials the compute daemon
vike-cli backtest run --profile wf.toml --set walkforward.n_splits=6 --from 2024-01-01T00 --to 2026-01-01T00   # a split count is defined BY the range: widen it and every window grows
vike-cli backtest run --profile wf.toml --set walkforward.n_splits=6 --set walkforward.mode=rolling   # train on the one chunk before each window instead of from bar 0
vike-cli backtest run --profile wf.toml --set walkforward.n_splits=6 --show-effective   # confirm what resolved: prints the profile and STOPS, no dial, no engine

# Fixed-length windows instead — the form whose windows keep their length when the range moves
vike-cli backtest run --profile wf.toml --set walkforward.train=12mo --set walkforward.test=3mo   # step defaults to test, which tiles the validation windows edge to edge
vike-cli backtest run --profile wf.toml --set walkforward.train=12mo --set walkforward.test=3mo --set walkforward.step=1mo   # overlap them: a fresh window every month
vike-cli backtest run --profile wf.toml --set walkforward.train=90d --set walkforward.test=30d --set walkforward.purge=2d   # drop 2d between the halves, so test_start - train_end == 2d exactly
vike-cli backtest run --profile wf.toml --set walkforward.train=90d --set walkforward.test=30d --set walkforward.embargo=2d   # a window whose test_start lands in the zone is DROPPED, not moved

# Let each window choose its parameters on its own training half, and say how it chooses
vike-cli backtest run --profile wf.toml --set walkforward.search=sweep   # scores this profile's own [sweep] grid per window; absent (or "none") is the fixed-parameter control
vike-cli backtest run --profile wf.toml --set walkforward.search=sweep --set walkforward.rank_by=max_dd   # a window's ranking is this key — the --rank-by FLAG is refused on a walk-forward profile

# Refused at load, and worth pasting once to read the message
vike-cli backtest run --profile wf.toml --set walkforward.n_splits=6 --set walkforward.purge=2d
  # walkforward.purge / walkforward.embargo need the DURATION window form (train/test) — the split-count
  # walk stays gap-free (decision 0046). Replace n_splits
  # with a train/test pair, or drop the key.
vike-cli backtest run --profile wf.toml --set walkforward.train=12mo --set walkforward.test=3mo --set walkforward.n_splits=6
  # walkforward.n_splits and walkforward.train/test/step are two PROTOCOLS, not two spellings — a split
  # count is defined BY the range and moves when the range moves, a duration does not. Set exactly one.
```

| key                    | takes     | when absent | what it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ---------------------- | --------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `walkforward.n_splits` | `integer` | *absent*    | Number of out-of-sample windows — window form (a), the one that existed first.                                                                                                                                                                                                                                                                                                                                                                                                   |
| `walkforward.train`    | `string`  | *absent*    | Window form (b)/(c) — the TRAIN window's length, as a `vike_model::time::parse_span` duration (`"12mo"`, `"90d"`, `"5000bars"`). Mutually exclusive with `Self::n_splits`; requires `Self::test`.                                                                                                                                                                                                                                                                                |
| `walkforward.test`     | `string`  | *absent*    | Window form (b)/(c) — the VALIDATION window's length. Required with `Self::train`.                                                                                                                                                                                                                                                                                                                                                                                               |
| `walkforward.step`     | `string`  | *absent*    | How far each window advances. Absent ⇒ equal to `Self::test`, which tiles the validation windows edge to edge.                                                                                                                                                                                                                                                                                                                                                                   |
| `walkforward.purge`    | `string`  | *absent*    | Bars dropped BETWEEN train and test, so `test_start - train_end == purge` exactly.                                                                                                                                                                                                                                                                                                                                                                                               |
| `walkforward.embargo`  | `string`  | *absent*    | The minimum gap AFTER a validation window before the next one may start. A window whose `test_start` falls inside the zone is DROPPED, not moved — moving it would make `Self::step` mean something other than what was written. Same duration-form-only rule as `Self::purge`, and the same ROUNDS-UP rule.                                                                                                                                                                     |
| `walkforward.search`   | `string`  | *absent*    | Which search each window runs on its OWN training half — the knob that chooses between the two walk-forward protocols. Absent or `"none"` is the CONTROL (`WindowSearch::None`): every window trades the profile's own `strategy.params`, which is the fixed-parameter walk this section has always described. `"sweep"` — named for the table it expands — scores this profile's `sweep` grid on each window's train half and carries only the winner onto its validation half. |
| `walkforward.mode`     | `string`  | *absent*    | The TRAIN-window shape (`WalkMode`): absent or `"anchored"` is the expanding window every split trains from bar 0; `"rolling"` trains on the ONE chunk immediately preceding the window. Case-insensitive and trimmed (`Self::walk_mode`), unknown values refused at load.                                                                                                                                                                                                       |
| `walkforward.rank_by`  | `string`  | *absent*    | How a window SCORES its candidates when `Self::search` runs one: any of the four `RankMetric` names the sweep's own `--rank-by` takes (`"sharpe"` \| `"return"` \| `"max_dd"` \| `"equity"`, case-insensitive), defaulting to `RankMetric::default`. Consulted only when a search actually runs — the control scores nothing.                                                                                                                                                    |

**What `[walkforward]` refuses**, verbatim from the code that refuses it:

| refused                                                                                                                                                                                                                                                                                                                                                                                                                                                  | raised by                       |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| \[walkforward] declares no window form — set n\_splits = N, or a train/test pair (e.g. train = "12mo", test = "3mo")                                                                                                                                                                                                                                                                                                                                     | `WalkforwardCfg::window_form`   |
| data.detail\_interval is unavailable to a \[walkforward] profile: the walk hands each window a sliced coarse series while nothing slices the detail tape, so every window's last step would fill against bars from AFTER the window ended. That is look-ahead, not merely waste. Run the profile without \[walkforward], or without the detail tape.                                                                                                     | `BacktestProfile::refusals`     |
| profile has no \[walkforward] table — a walk-forward needs a window form, e.g. `[walkforward] n_splits = 4` or `[walkforward] train = "12mo" test = "3mo"`                                                                                                                                                                                                                                                                                               | `walkforward_preflight`         |
| the \[walkforward] window form yields NO windows over the \{} bar(s) of \{symbol} in this range — a walk that evaluates nothing must not return a report that looks like one                                                                                                                                                                                                                                                                             | `walkforward_preflight`         |
| the duration window form needs BOTH walkforward.train and walkforward.test (step defaults to test) — a half-declared window has no shape                                                                                                                                                                                                                                                                                                                 | `WalkforwardCfg::window_form`   |
| unknown walkforward.mode \{other:?} (want anchored \| rolling; absent = anchored)                                                                                                                                                                                                                                                                                                                                                                        | `WalkforwardCfg::walk_mode`     |
| unknown walkforward.rank\_by \{raw:?} (want sharpe \| return \| max\_dd \| equity; absent = sharpe)                                                                                                                                                                                                                                                                                                                                                      | `WalkforwardCfg::rank_metric`   |
| unknown walkforward.search \{other:?} (want none \| sweep; absent = none, the no-search control)                                                                                                                                                                                                                                                                                                                                                         | `WalkforwardCfg::window_search` |
| walkforward.n\_splits and walkforward.train/test/step are two PROTOCOLS, not two spellings — a split count is defined BY the range and moves when the range moves, a duration does not. Set exactly one.                                                                                                                                                                                                                                                 | `WalkforwardCfg::window_form`   |
| walkforward.n\_splits must be >= 1, got 0                                                                                                                                                                                                                                                                                                                                                                                                                | `BacktestProfile::refusals`     |
| walkforward.n\_splits must be >= 1, got 0                                                                                                                                                                                                                                                                                                                                                                                                                | `resolve_windows`               |
| walkforward.purge / walkforward.embargo need the DURATION window form (train/test) — the split-count walk stays gap-free (decision 0046 — the bar mode walk forward has no purge). Replace n\_splits with a train/test pair, or drop the key.                                                                                                                                                                                                            | `WalkforwardCfg::window_form`   |
| walkforward.search = "grid" was renamed to "sweep" — one name for one knob, and it is the table it expands (\[sweep]). Write search = "sweep".                                                                                                                                                                                                                                                                                                           | `WalkforwardCfg::window_search` |
| walkforward.search = "sweep" needs a \[sweep] table to search — this profile has none, so every window would 'select' the one parameter set it already has. Add the grid, or drop the key for the no-search control.                                                                                                                                                                                                                                     | `BacktestProfile::refusals`     |
| walkforward.step resolves to \{step} bar(s) and walkforward.test to \{test} — a step shorter than the validation window makes consecutive windows OVERLAP, and the stitched out-of-sample curve would compound the same bars more than once, reporting a return and a Sharpe roughly the overlap factor too high. Set step >= test: equal tiles the windows edge to edge (that is also what an absent step means), and larger leaves a gap between them. | `resolve_windows`               |

### `[data.series]` [#dataseries]

an ARRAY of tables · optional · refuses an undeclared key · read from `SeriesRef`

| key                  | takes                                    | when absent    | what it does |
| -------------------- | ---------------------------------------- | -------------- | ------------ |
| `data.series.venue`  | `string`                                 | **required**   | —            |
| `data.series.symbol` | `string`                                 | **required**   | —            |
| `data.series.kind`   | `"tick" \| "quote" \| "trade" \| "book"` | *type default* | —            |

**What `[data.series]` refuses**, verbatim from the code that refuses it:

| refused                                                                                                                                                                                                                | raised by                              |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| data.symbols must not be empty (or use the cross-venue \[\[data.series]] form)                                                                                                                                         | `BacktestProfile::validate_data_slice` |
| data.venue/data.symbols and \[\[data.series]] are two ways to name the SAME slice — set exactly one (the \[\[data.series]] form is the cross-venue one)                                                                | `BacktestProfile::validate_data_slice` |
| engine.snap\_to\_properties is single-venue only: the point-in-time instrument grid is looked up under one default\_venue, so a cross-venue \[\[data.series]] slice would snap every series to the first series' venue | `BacktestProfile::validate_data_slice` |

### `[engine.impact]` [#engineimpact]

a table · optional · refuses an undeclared key · read from `ImpactCfg`

| key                       | takes     | when absent  | what it does                                                                                                                                                                                                                                                                                                                                   |
| ------------------------- | --------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `engine.impact.model`     | `string`  | **required** | which model — currently only `"almgren_chriss"`                                                                                                                                                                                                                                                                                                |
| `engine.impact.exec_time` | `number`  | `1.0`        | Execution horizon, in whatever period this run's context is measured over — bar-periods in bar mode, TRADE PRINTS in tick mode (see `crate::impact::AlmgrenChriss::exec_time` and `crate::impact::TickWindow`). The default `1.0` means "worked inside one period".                                                                            |
| `engine.impact.window`    | `integer` | `21`         | Rolling sigma/volume lookback — in BARS in bar mode, in TRADE PRINTS in tick mode. The default is one trading month of daily bars; on a liquid tape it is a fraction of a second, so a tick profile should set it rather than inherit it. Lengthening it averages away sampling noise; it does NOT change the UNIT the context is measured in. |
| `engine.impact.gamma`     | `number`  | `0.314`      | Permanent-impact coefficient, defaulting to the published `crate::impact::AC_GAMMA`.                                                                                                                                                                                                                                                           |
| `engine.impact.eta`       | `number`  | `0.142`      | Temporary-impact coefficient, defaulting to the published `crate::impact::AC_ETA`. The twin of `Self::gamma` for the half a book walk already pays — so it moves the bar and L1-tick lanes and is inert on an L2 fill that walked a book. Same rationale, same fence around the exponents.                                                     |

**What `[engine.impact]` refuses**, verbatim from the code that refuses it:

| refused                                                           | raised by          |
| ----------------------------------------------------------------- | ------------------ |
| engine.impact.exec\_time must be > 0, got \{}                     | `ImpactCfg::build` |
| engine.impact.window must be >= 3 (two returns), got \{}          | `ImpactCfg::build` |
| unknown engine.impact.model \{other:?} (known: "almgren\_chriss") | `ImpactCfg::build` |

### `[engine.fee]` [#enginefee]

a table · optional · refuses an undeclared key · read from `FeeCfg`

| key                             | takes          | when absent  | what it does                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------- | -------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `engine.fee.kind`               | `string`       | **required** | Which `vike_model::FeeSchedule` shape this table describes: `"probability_scaled"` \| `"per_share_with_floor"` \| `"percent_of_underlying"` \| `"percent_maker_taker"` \| `"venue"` \| `"free"`.                                                                                                                                                                                                                       |
| `engine.fee.taker_rate`         | `number`       | `0`          | `probability_scaled`: the TAKER fraction of the `p(1−p)`-scaled share count.                                                                                                                                                                                                                                                                                                                                           |
| `engine.fee.maker_rate`         | `number`       | `0`          | `probability_scaled`: the MAKER fraction, before any rebate.                                                                                                                                                                                                                                                                                                                                                           |
| `engine.fee.maker_rebate_share` | `number`       | `0`          | `probability_scaled`: the maker's rebate as a share of the EQUIVALENT TAKER fee, so a zero `maker_rate` with a positive share is a NEGATIVE maker commission (a rebate — the sign convention on `vike_model::FeeSchedule`).                                                                                                                                                                                            |
| `engine.fee.per_share`          | `number`       | *absent*     | `per_share_with_floor`: the per-SHARE fee. REQUIRED by that kind.                                                                                                                                                                                                                                                                                                                                                      |
| `engine.fee.min`                | `number`       | *absent*     | `per_share_with_floor`: the per-order MINIMUM. REQUIRED by that kind, and required deliberately — an absent floor defaults to no floor, which is the flat-rate behaviour the whole shape exists to escape. Write `min = 0.0` to assert there is genuinely none.                                                                                                                                                        |
| `engine.fee.max_pct`            | `number`       | *absent*     | `per_share_with_floor`: the maximum fraction of trade value the fee may reach. Optional — absent is `0.0`, which `FeeSchedule::commission` treats as NO ceiling (it caps only on a positive notional bound), so omitting it charges the uncapped per-share-or-floor figure. That default is safe in the direction that matters: it can only over-charge.                                                               |
| `engine.fee.bps`                | `number`       | *absent*     | `percent_of_underlying`: basis points of the UNDERLYING notional. REQUIRED by that kind.                                                                                                                                                                                                                                                                                                                               |
| `engine.fee.premium_cap_pct`    | `number`       | *absent*     | `percent_of_underlying`: the cap, as a fraction of the PREMIUM notional (Deribit's real rule caps the underlying term at 12.5 % of the premium). REQUIRED, and a non-positive value is REFUSED rather than read as "no cap": `FeeSchedule::commission` on this shape is `min(bps × premium, cap × premium)`, so a zero cap makes the whole commission zero — the silent free backtest, wearing a configured fee model. |
| `engine.fee.maker_bps`          | `number`       | *absent*     | `percent_maker_taker`: maker basis points of quote-notional. At least one of this and `Self::taker_bps` is required; the other defaults to `0.0`.                                                                                                                                                                                                                                                                      |
| `engine.fee.taker_bps`          | `number`       | *absent*     | `percent_maker_taker`: taker basis points of quote-notional. See `Self::maker_bps`.                                                                                                                                                                                                                                                                                                                                    |
| `engine.fee.venue`              | `string`       | *absent*     | `venue`: which venue's published schedule to cost the run at. REQUIRED by that kind, and it is not inferred from `data` — `EngineParams::fee_schedule` is ONE schedule for the whole run, so on a cross-venue `[data.series]` slice there is no single right answer to infer and naming it is the operator asserting which venue's book this run is priced at.                                                         |
| `engine.fee.symbol`             | `string`       | *absent*     | `venue`: which SYMBOL selects the venue's fee LANE. Absent (the normal case) resolves from the run's own series on `Self::venue`, which is what keeps the `.P` suffix from being typed twice — see `FeeCfg::build_for` for the two ways that resolution refuses.                                                                                                                                                       |
| `engine.fee.pm_curve`           | `true / false` | *absent*     | `venue`, polymarket only: take the verified 2026 V2 fee regime (`vike_model::POLYMARKET_V2_FEE_CURVE`, via `vike_model::fee_schedule_for_with_pm_curve`) instead of the registry's `Free`.                                                                                                                                                                                                                             |

**What `[engine.fee]` refuses**, verbatim from the code that refuses it:

| refused                                                                                                                                                                                                                                                                                                                                                                                                      | raised by                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------- |
| engine.fee.kind = "per\_share\_with\_floor" needs BOTH per\_share and min. The floor is the whole reason this shape exists — a per-share fee with no minimum is a flat rate wearing a different name, and it is the configuration that makes a small-size high-frequency run backtest as viable and then lose to the broker minimum live. Write min = 0.0 to assert there is genuinely no floor.             | `FeeCfg::validate_shape`    |
| engine.fee.kind = "per\_share\_with\_floor" needs engine.multiplier = 1.0 (the default) and no engine.multipliers row other than 1.0: the fee path scales the schedule's answer by the contract multiplier, so a per-ORDER minimum would be charged per CONTRACT. This shape models an equities book. Drop the multiplier, or price a multiplied contract with percent\_maker\_taker.                        | `BacktestProfile::refusals` |
| engine.fee.kind = "percent\_maker\_taker" needs at least one of maker\_bps / taker\_bps — a table naming neither describes no cost, which is what kind = "free" says on purpose. A genuinely zero-fee side is written as the explicit 0.0, so the zero is an assertion rather than an omission.                                                                                                              | `FeeCfg::validate_shape`    |
| engine.fee.kind = "percent\_of\_underlying" needs BOTH bps and premium\_cap\_pct — the cap is half the rule it models (min(bps x underlying, cap x premium)), and it is the half that binds for a cheap deep-OTM option.                                                                                                                                                                                     | `FeeCfg::validate_shape`    |
| engine.fee.kind = "venue" needs engine.fee.venue — it is not inferred from \[data]. EngineParams::fee\_schedule is ONE schedule for the whole run, so a cross-venue slice has no single answer to infer, and naming the venue is the operator asserting which venue's book this run is costed at.                                                                                                            | `FeeCfg::validate_shape`    |
| engine.fee.kind = "venue" resolves ONE schedule for the whole run, and this run's \{venue:?} series straddle \{} fee lanes (\{}) — a venue prices its lanes completely differently (crates/vike-model/src/fees.rs's fee\_schedule\_for carries the measurement per lane), so one row would misprice the other lane. Split the run per lane, or set engine.fee.symbol to name the lane this run is costed at. | `FeeCfg::fee_lane_for`      |
| engine.fee.pm\_curve is polymarket-only, and this table names venue \{:?} — vike\_model::fee\_schedule\_for\_with\_pm\_curve delegates to fee\_schedule\_for for every other venue, so the flag would configure nothing while the run was read as curve-priced. Drop it.                                                                                                                                     | `FeeCfg::validate_shape`    |
| engine.fee.premium\_cap\_pct must be > 0, got \{} — a zero cap is not "no cap". FeeSchedule::commission on this shape is min(bps x premium, cap x premium), so a zero cap zeroes the whole commission and the run pays no fee at all while the profile reads as fee-modelled. crates/vike-model/src/fees.rs's fee\_schedule\_for carries the real Deribit cap in its "deribit" arm.                          | `FeeCfg::validate_shape`    |
| engine.fee.venue = \{venue:?} names a venue this run does not load, so there is no symbol to resolve its fee LANE from — and answering with the bare-venue row would charge a perp run at the venue's SPOT schedule, the mispricing the lane key exists to end. This run's series are on: \{}. Name a venue the slice trades, or set engine.fee.symbol outright.                                             | `FeeCfg::fee_lane_for`      |
| unknown engine.fee.kind \{kind:?} (known: \{}; a single flat fraction of notional may also stay on engine.fee\_rate, which is the same shape as percent\_maker\_taker charged to both sides)                                                                                                                                                                                                                 | `FeeCfg::validate_shape`    |
| unknown engine.fee.kind \{other:?} (known: \{})                                                                                                                                                                                                                                                                                                                                                              | `FeeCfg::build_for`         |

### `[engine.resolution]` [#engineresolution]

a table · optional · refuses an undeclared key · read from `ResolutionCfg`

| key                             | takes              | when absent  | what it does                                                                                                                                                                                                                                                                                                         |
| ------------------------------- | ------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `engine.resolution.kind`        | `string`           | **required** | currently only `"binary_outcome"`                                                                                                                                                                                                                                                                                    |
| `engine.resolution.window_secs` | `integer`          | `300`        | Seconds from a window's open (`sts`) to its resolution. Defaults to `vike_model::fair::UPDOWN_WINDOW_SECS` (300). NOTE the symbol GRAMMAR is independent of this: `TokenId::parse` pins `sts` to a multiple of `UPDOWN_WINDOW_SECS`, so a different `window_secs` moves the payout TIME without redefining the grid. |
| `engine.resolution.path`        | `string`           | *absent*     | Optional `slug,winning_index` CSV. Relative paths resolve against the profile file's own directory (`BacktestProfile::base_dir`), not the CWD.                                                                                                                                                                       |
| `engine.resolution.winners`     | `table of integer` | `{}`         | Optional inline `slug = winning_index` table. Merged over `path`'s rows.                                                                                                                                                                                                                                             |
| `engine.resolution.end_ts`      | `string`           | *absent*     | Explicit override for `crate::EngineParams::resolution_end_ts` (epoch-ms or `YYYY-MM-DDTHH`). Absent = the LATEST resolution among the run's own series (`max(sts) + window_secs`), which is what pins the end-of-run sweep to the window rather than to the `RESOLUTION_PROBE_SENTINEL`.                            |

**What `[engine.resolution]` refuses**, verbatim from the code that refuses it:

| refused                                                                                                                                                                                                                                | raised by                       |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| engine.resolution.window\_secs must be > 0, got \{}                                                                                                                                                                                    | `ResolutionCfg::validate_shape` |
| engine.resolution.winners\[\{slug:?}] = \{wi} is not a binary outcome index (0 or 1). Non-binary and unresolved (-1) values are real on-chain facts and are never coerced to "both sides lose" — drop the window from the run instead. | `ResolutionCfg::validate_shape` |
| unknown engine.resolution.kind \{:?} (known: "binary\_outcome")                                                                                                                                                                        | `ResolutionCfg::validate_shape` |

### `[engine.sizer]` [#enginesizer]

a table · optional · refuses an undeclared key · read from `SizerCfg`

**Sizing an entry, and composing two sizers.**

```sh
# The three kinds whose knob is theirs alone — the kind plus its one required key, one line each
vike-cli backtest run --profile p.toml --set engine.sizer.kind=pass_through                                 # the implicit default written down: the strategy's request goes through untouched
vike-cli backtest run --profile p.toml --set engine.sizer.kind=fixed_dollar --set engine.sizer.amount=2500  # the same cash per entry whatever the price
vike-cli backtest run --profile p.toml --set engine.sizer.kind=fixed_shares --set engine.sizer.shares=1     # one contract per entry — the size-blind control run

# The three that all read `pct` — one key, three meanings, so the KIND is the thing you are choosing
vike-cli backtest run --profile p.toml --set engine.sizer.kind=pct_equity --set engine.sizer.pct=0.02       # 2% of equity as target NOTIONAL
vike-cli backtest run --profile p.toml --set engine.sizer.kind=pct_volatility --set engine.sizer.pct=0.02   # 2% of equity as an ATR-risk budget: a volatile symbol gets fewer units
vike-cli backtest run --profile p.toml --set engine.sizer.kind=max_risk_pct --set engine.sizer.pct=0.01     # 1% of equity risked to the STOP, so stop distance decides the size

# The two wrapping kinds need a base, and a base is a NESTED table — --set has no grammar for one, so write it
cat > chain.toml <<'TOML'
[engine.sizer]
kind = "portfolio_heat"   # a wrapper: caps TOTAL open risk, sizes nothing on its own
max_heat = 0.06           # 6% of equity across every open position

[engine.sizer.base]       # required under both wrapping kinds, REFUSED under the other six
kind = "pct_equity"       # a base takes the same field set as [engine.sizer] — it nests itself
pct = 0.02
TOML
vike-cli backtest run --profile chain.toml --show-effective   # confirm it resolved as a CHAIN, not as one sizer
vike-cli backtest run --profile chain.toml --set engine.sizer.kind=drawdown_throttle --set engine.sizer.sensitivity=1.5 --set engine.sizer.floor=0.25 --show-effective   # the other wrapper over the same written base: its own two knobs ARE flat leaves, so they flag

# Keep the sizer a report was produced by, then replay exactly it
vike-cli backtest run --profile p.toml --set engine.sizer.kind=max_risk_pct --set engine.sizer.pct=0.01 --write-profile run-01.toml   # refuses an existing path, so every run keeps its own
vike-cli backtest run --profile run-01.toml --local --store /data --json   # the same sizer, on this box, as machine-readable report
```

| key                        | takes    | when absent  | what it does                                                                                                                                                                                                                                                                                                                                                                 |
| -------------------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `engine.sizer.kind`        | `string` | **required** | One of `"pass_through"` \| `"fixed_dollar"` \| `"fixed_shares"` \| `"pct_equity"` \| `"pct_volatility"` \| `"max_risk_pct"` \| `"portfolio_heat"` \| `"drawdown_throttle"` — every concrete `vike_analytics::sizing::PositionSizer` this crate ships and nothing else (`Self::build`).                                                                                       |
| `engine.sizer.amount`      | `number` | *absent*     | `crate::sizing::FixedDollarSizer::amount` — fixed cash notional per entry. Required for `"fixed_dollar"`.                                                                                                                                                                                                                                                                    |
| `engine.sizer.shares`      | `number` | *absent*     | `crate::sizing::FixedSharesSizer::shares` — fixed share/contract count per entry. Required for `"fixed_shares"`.                                                                                                                                                                                                                                                             |
| `engine.sizer.pct`         | `number` | *absent*     | The knob `"pct_equity"` / `"pct_volatility"` / `"max_risk_pct"` each read as their own fraction of equity (target notional, ATR-risk budget, and stop-risk budget respectively — see `vike_analytics::sizing`'s doc on each). Required for those three kinds.                                                                                                                |
| `engine.sizer.max_heat`    | `number` | *absent*     | `crate::sizing::PortfolioHeatSizer::max_heat` — total open-risk cap as a fraction of equity. Required for `"portfolio_heat"`.                                                                                                                                                                                                                                                |
| `engine.sizer.sensitivity` | `number` | *absent*     | `crate::sizing::DrawdownThrottleSizer::sensitivity`. Required for `"drawdown_throttle"`.                                                                                                                                                                                                                                                                                     |
| `engine.sizer.floor`       | `number` | *absent*     | `crate::sizing::DrawdownThrottleSizer::floor`. Required for `"drawdown_throttle"`.                                                                                                                                                                                                                                                                                           |
| `engine.sizer.base`        | `table`  | *absent*     | The wrapped sizer for `"portfolio_heat"` / `"drawdown_throttle"` — required for those two kinds (`Self::build` refuses their absence), and REFUSED under every other kind, which reads it nowhere: a base under a scalar kind would run one sizer while the profile read as a chain. Boxed because `SizerCfg` nests itself — see `MAX_SIZER_DEPTH` for the bound on how far. |

**What `[engine.sizer]` refuses**, verbatim from the code that refuses it:

| refused                                                                                                                                                                                                                                        | raised by        |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| engine.sizer.kind = "drawdown\_throttle" wraps a base sizer — add an \[engine.sizer.base] table naming it                                                                                                                                      | `SizerCfg::need` |
| engine.sizer.kind = "portfolio\_heat" wraps a base sizer — add an \[engine.sizer.base] table naming it                                                                                                                                         | `SizerCfg::need` |
| engine.sizer.kind = \{kind:?} does not wrap a base sizer, but \[engine.sizer\{}.base] is set — only "portfolio\_heat" and "drawdown\_throttle" read it, so the chain would run \{kind:?} alone. Remove the base table, or name a wrapping kind | `SizerCfg::need` |
| engine.sizer.\{field} is required when engine.sizer.kind = \{kind:?}                                                                                                                                                                           | `SizerCfg::need` |
| unknown engine.sizer.kind \{other:?} (want pass\_through \| fixed\_dollar \| fixed\_shares \| pct\_equity \| pct\_volatility \| max\_risk\_pct \| portfolio\_heat \| drawdown\_throttle)                                                       | `SizerCfg::need` |

## What else the profile refuses [#what-else-the-profile-refuses]

117 refusals in all, 23 of them shown beside the tables above.
The remaining 93 are the ones that judge a profile as a WHOLE — a knob that needs a
mode it was not given, a value outside its range, a table that contradicts another. Each is printed
verbatim, with the symbol that raises it; a `format!` hole stays as its template rather than being
filled in with an invented value.

| refused                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | raised by                              |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| data.detail\_interval and engine.cash\_gate are mutually exclusive: cash\_gate routes the whole bar step through the gated fill lane and UNCONDITIONALLY disables the granular sub-bar lane, so the detail tape would be loaded, scanned and then ignored while every order was reported as resolved against it. Set one.                                                                                                                                                                                                                                                                                                                                                                         | `BacktestProfile::refusals`            |
| data.detail\_interval and engine.decide = "simultaneous" are mutually exclusive: the simultaneous mode implies the shared-cash admission phase, which routes the whole bar step through fill\_step\_gated and disables the granular sub-bar lane — the detail tape would be loaded, paid for and ignored                                                                                                                                                                                                                                                                                                                                                                                          | `BacktestProfile::refusals`            |
| data.detail\_interval \{raw:?} (\{ms}ms) must be strictly FINER than data.interval \{:?} (\{base}ms) — at this resolution each coarse step buckets at most one sub-bar, which resolves no stop-versus-target ambiguity while paying for a second whole store scan. This is the inverse of the engine.timeframes rule, where a synthesised series must be COARSER than the base                                                                                                                                                                                                                                                                                                                    | `DataCfg::detail_interval_ms`          |
| data.detail\_interval \{raw:?} is bar-mode only: the intrabar detail tape is bucketed into COARSE BAR steps and consulted by StrategyEngine::run's bar fill phase, and run\_ticks never reads those buckets — a tick replay already resolves every order against the tape it is replaying                                                                                                                                                                                                                                                                                                                                                                                                         | `DataCfg::detail_interval_ms`          |
| data.detail\_interval \{raw:?} is not a valid interval (want a count then one of s/m/h/d, e.g. "1m") — it is handed straight to the hist store as a series interval, so it must name a series the store can hold                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `DataCfg::detail_interval_ms`          |
| data.detail\_interval \{raw:?} resolves to \{ms}ms — a zero-length window makes every sub-bar boundary the same instant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `DataCfg::detail_interval_ms`          |
| data.from (\{start}) must be \<= data.to (\{end})                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `BacktestProfile::refusals`            |
| data.interval \{:?} is not a valid interval, so data.detail\_interval \{raw:?} cannot be checked as finer than it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `DataCfg::detail_interval_ms`          |
| data.interval \{:?} is not a valid interval, so engine.timeframes cannot be checked against it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `BacktestProfile::refusals`            |
| data.interval \{:?} is not a valid interval, so the duration data.warmup \{raw:?} cannot be converted to a step count                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `DataCfg::warmup_steps`                |
| data.interval \{:?} resolves to \{base}ms, so the duration data.warmup \{raw:?} names no number of steps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `DataCfg::warmup_steps`                |
| data.max\_gap is set without data.require\_coverage = true, so the gate whose tolerance it names is not armed and this key is read by nothing. Arm the gate, or remove the tolerance                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `BacktestProfile::refusals`            |
| data.max\_gap \{raw:?} is a BAR COUNT, and a gap in this store is a wall-clock span in epoch-ms: converting \{n} bars to a duration needs an interval, and a tick profile has none. Write the tolerance as fixed time — "4h", "1d"                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `DataCfg::max_gap_ms`                  |
| data.max\_gap \{raw:?} is a CALENDAR span, and a calendar month is not a fixed number of milliseconds (one month from 31 January is 28 days, from 31 March 30) — so the tolerance would depend on where data.from happens to sit, and two runs naming the same tolerance would accept different amounts. Write it in fixed time — "30d"                                                                                                                                                                                                                                                                                                                                                           | `DataCfg::max_gap_ms`                  |
| data.max\_gap \{raw:?} resolves to \{ms}ms — a non-positive tolerance is what an ABSENT data.max\_gap already means (tolerate nothing), so this spelling can only mislead. Remove the key, or name a real duration                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `DataCfg::max_gap_ms`                  |
| data.max\_gap: \{e}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `DataCfg::max_gap_ms`                  |
| data.on\_gap is set without data.require\_coverage = true, so the gate it configures is not armed and this key is read by nothing — while it reads as though a run over an uncovered window would be stopped. Arm the gate, or remove the disposition                                                                                                                                                                                                                                                                                                                                                                                                                                             | `BacktestProfile::refusals`            |
| data.on\_gap \{raw:?} is not one of \{roster}. It says what data.require\_coverage DOES about a window the store does not cover: `refuse` stops the run (the default, because a gate that only warns is invisible on every run nobody reads), `warn` logs the findings and runs unchanged, `run` leaves the gate inert while keeping the file's statement of what this run is supposed to require                                                                                                                                                                                                                                                                                                 | `DataCfg::on_gap`                      |
| data.series\[\{:?}].kind = \{:?} is tick-mode only: a bar series has no quote/trade/book lanes to filter                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `BacktestProfile::validate_data_slice` |
| data.symbols must not be empty                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `BacktestProfile::validate_data_slice` |
| data.symbols must not be empty (or use the cross-venue \[\[data.series]] form)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `BacktestProfile::validate_data_slice` |
| data.universe \{raw:?} is not one of \{roster}. It is the POINT-IN-TIME membership rule: `declared` takes the symbol list verbatim (the default), `covered` names every member whose tape does not span the window and runs anyway, `strict` refuses that run. None of the three ever drops a member — a universe a run narrowed silently would not be the one the profile names                                                                                                                                                                                                                                                                                                                  | `DataCfg::universe_mode`               |
| data.venue is required alongside data.symbols                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `BacktestProfile::validate_data_slice` |
| data.venue/data.symbols and \[\[data.series]] are two ways to name the SAME slice — set exactly one (the \[\[data.series]] form is the cross-venue one)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `BacktestProfile::validate_data_slice` |
| data.warmup \{raw:?} is a CALENDAR span, and a calendar month is not a fixed number of steps (one month from 31 January is 28 days, from 31 March 30) — so its length would depend on where data.from happens to sit, which is the irreproducibility this key exists to remove. Write it in bars ("200bars") or in fixed time ("90d")                                                                                                                                                                                                                                                                                                                                                             | `DataCfg::warmup_steps`                |
| data.warmup \{raw:?} is a DURATION, which is bar-mode only: a tick tape has no fixed cadence to divide it by, so no number of ticks corresponds to it. The engine gates run\_ticks on an EVENT index, so write the requirement as a count — e.g. "200bars" means 200 ticks here                                                                                                                                                                                                                                                                                                                                                                                                                   | `DataCfg::warmup_steps`                |
| data.warmup: \{e}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `DataCfg::warmup_steps`                |
| duplicate symbol \{:?} in the data slice — the engine routes ticks to a symbol slot BY NAME, so two series cannot share one symbol                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `BacktestProfile::validate_data_slice` |
| engine.attach\_funding is bar-mode only: the per-interval funding accrual runs in the bar loop; the tick lane carries no funding fold to feed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `BacktestProfile::refusals`            |
| engine.cash must be > 0, got \{}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `BacktestProfile::refusals`            |
| engine.cash\_gate is bar-mode only: the shared-cash admission phase is StrategyEngine::run's own bar step (fill\_step\_gated), and run\_ticks never consults it — a tick profile setting it would change nothing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `BacktestProfile::refusals`            |
| engine.clamp\_to\_leverage is unavailable to a profile carrying \[risk]: SimBroker::build\_risk\_gate returns None on clamp\_to\_leverage BEFORE it reads risk\_limits, so the clamp disarms the pre-trade gate entirely and EVERY \[risk] limit — not just max\_leverage — is discarded. Drop clamp\_to\_leverage to keep \[risk]'s gate, or remove \[risk] and clamp against engine.leverage alone                                                                                                                                                                                                                                                                                              | `BacktestProfile::refusals`            |
| engine.clamp\_to\_leverage needs engine.leverage: there is nothing to clamp to                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `BacktestProfile::refusals`            |
| engine.decide = "simultaneous" is bar-mode only: the cross-sectional allocator it orders is StrategyEngine::fill\_step\_gated, reached only from StrategyEngine::run — run\_ticks consults neither it nor cash\_gate, so a tick profile setting it would change nothing                                                                                                                                                                                                                                                                                                                                                                                                                           | `BacktestProfile::refusals`            |
| engine.decide = "simultaneous" is not built for a run with a pre-trade risk gate: remove \[risk] and engine.leverage, or keep engine.decide unset. With a gate armed, SimBroker::gate\_order folds the pending set as it ACCUMULATES during the on\_bar fan-out, so the symbol judged first faces the whole step budget and later ones face the remainder — the DECISION is still taken in symbol-list order and no fill-phase ranking can repair it. Closing it needs a step-boundary budget snapshot, which does not exist                                                                                                                                                                      | `BacktestProfile::refusals`            |
| engine.equity\_sample\_every is tick-mode only: the bar lane records one equity sample per BAR (bounded by the bar count), so there is nothing to thin                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `BacktestProfile::refusals`            |
| engine.fee and a non-zero engine.fee\_rate (\{}) are two different cost models — set exactly one                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `BacktestProfile::refusals`            |
| engine.fee.kind = "per\_share\_with\_floor" needs BOTH per\_share and min. The floor is the whole reason this shape exists — a per-share fee with no minimum is a flat rate wearing a different name, and it is the configuration that makes a small-size high-frequency run backtest as viable and then lose to the broker minimum live. Write min = 0.0 to assert there is genuinely no floor.                                                                                                                                                                                                                                                                                                  | `FeeCfg::validate_shape`               |
| engine.fee.kind = "per\_share\_with\_floor" needs engine.multiplier = 1.0 (the default) and no engine.multipliers row other than 1.0: the fee path scales the schedule's answer by the contract multiplier, so a per-ORDER minimum would be charged per CONTRACT. This shape models an equities book. Drop the multiplier, or price a multiplied contract with percent\_maker\_taker.                                                                                                                                                                                                                                                                                                             | `BacktestProfile::refusals`            |
| engine.fee.kind = "percent\_maker\_taker" needs at least one of maker\_bps / taker\_bps — a table naming neither describes no cost, which is what kind = "free" says on purpose. A genuinely zero-fee side is written as the explicit 0.0, so the zero is an assertion rather than an omission.                                                                                                                                                                                                                                                                                                                                                                                                   | `FeeCfg::validate_shape`               |
| engine.fee.kind = "percent\_of\_underlying" needs BOTH bps and premium\_cap\_pct — the cap is half the rule it models (min(bps x underlying, cap x premium)), and it is the half that binds for a cheap deep-OTM option.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `FeeCfg::validate_shape`               |
| engine.fee.kind = "venue" needs engine.fee.venue — it is not inferred from \[data]. EngineParams::fee\_schedule is ONE schedule for the whole run, so a cross-venue slice has no single answer to infer, and naming the venue is the operator asserting which venue's book this run is costed at.                                                                                                                                                                                                                                                                                                                                                                                                 | `FeeCfg::validate_shape`               |
| engine.fee.kind = "venue" resolves ONE schedule for the whole run, and this run's \{venue:?} series straddle \{} fee lanes (\{}) — a venue prices its lanes completely differently (crates/vike-model/src/fees.rs's fee\_schedule\_for carries the measurement per lane), so one row would misprice the other lane. Split the run per lane, or set engine.fee.symbol to name the lane this run is costed at.                                                                                                                                                                                                                                                                                      | `FeeCfg::fee_lane_for`                 |
| engine.fee.pm\_curve is polymarket-only, and this table names venue \{:?} — vike\_model::fee\_schedule\_for\_with\_pm\_curve delegates to fee\_schedule\_for for every other venue, so the flag would configure nothing while the run was read as curve-priced. Drop it.                                                                                                                                                                                                                                                                                                                                                                                                                          | `FeeCfg::validate_shape`               |
| engine.fee.premium\_cap\_pct must be > 0, got \{} — a zero cap is not "no cap". FeeSchedule::commission on this shape is min(bps x premium, cap x premium), so a zero cap zeroes the whole commission and the run pays no fee at all while the profile reads as fee-modelled. crates/vike-model/src/fees.rs's fee\_schedule\_for carries the real Deribit cap in its "deribit" arm.                                                                                                                                                                                                                                                                                                               | `FeeCfg::validate_shape`               |
| engine.fee.venue = \{venue:?} names a venue this run does not load, so there is no symbol to resolve its fee LANE from — and answering with the bare-venue row would charge a perp run at the venue's SPOT schedule, the mispricing the lane key exists to end. This run's series are on: \{}. Name a venue the slice trades, or set engine.fee.symbol outright.                                                                                                                                                                                                                                                                                                                                  | `FeeCfg::fee_lane_for`                 |
| engine.fee.\{key} is a knob of kind \{owner:?}, and this table declares kind \{kind:?} — nothing would read it. A COST knob that configures nothing is worse than an absent one: the operator reads the profile as priced at what they wrote and the run prices at something else. Set the kind this knob belongs to, or drop the knob.                                                                                                                                                                                                                                                                                                                                                           | `FeeCfg::validate_shape`               |
| engine.fee.\{name} must be finite and >= 0, got \{v}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `FeeCfg::validate_shape`               |
| engine.feed\_latency is tick-mode only: it re-orders recorded ticks by their machine receive stamp (local\_ts), which a bar series does not carry                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `BacktestProfile::refusals`            |
| engine.impact.exec\_time must be > 0, got \{}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `ImpactCfg::build`                     |
| engine.impact.window must be >= 3 (two returns), got \{}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `ImpactCfg::build`                     |
| engine.impact.\{name} must be > 0 and finite, got \{v}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `ImpactCfg::build`                     |
| engine.leverage and \[risk] are two different margin sources for the same gate — set exactly one. With clamp\_to\_leverage off (the default) there are three configurations and \[risk] wins all of them: SimBroker::build\_risk\_gate's (Some(l), \_) arm takes risk\_limits unconditionally, so a \[risk] that sets max\_leverage answers with ITS number, a \[risk] that does not sets no margin requirement at all, and either way engine.leverage's 1/L im\_requirement is silently discarded. (With clamp\_to\_leverage on, neither reaches a gate — that combination is refused separately.) Set risk.max\_leverage instead, or remove \[risk] to use engine.leverage's 1/L margin mapping | `BacktestProfile::refusals`            |
| engine.leverage must be > 0, got \{l} — omit the key for unlevered                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `BacktestProfile::refusals`            |
| engine.liq\_buffer must be >= 0, got \{}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `BacktestProfile::refusals`            |
| engine.maint\_margin must be >= 0, got \{} — 0 means the liquidation watchdog is off, and a negative rate has no meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `BacktestProfile::refusals`            |
| engine.multiplier must be > 0, got \{} — it scales every position's notional, so zero makes every trade worth nothing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `BacktestProfile::refusals`            |
| engine.multipliers.\{sym} must be > 0, got \{m}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `BacktestProfile::refusals`            |
| engine.multipliers.\{sym} names a symbol this run does not load — the engine matches a multiplier row by EXACT symbol name and otherwise falls back to the global engine.multiplier, so this row would change nothing. The data slice is: \{}                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `BacktestProfile::refusals`            |
| engine.queue\_model is tick-mode only: the FIFO queue lane runs in the tick/book replay path, which a bar series does not drive                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `BacktestProfile::refusals`            |
| engine.resolution.window\_secs must be > 0, got \{}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `ResolutionCfg::validate_shape`        |
| engine.resolution.winners\[\{slug:?}] = \{wi} is not a binary outcome index (0 or 1). Non-binary and unresolved (-1) values are real on-chain facts and are never coerced to "both sides lose" — drop the window from the run instead.                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `ResolutionCfg::validate_shape`        |
| engine.resolution: \{} window slug(s) in data.series have no binary winning\_index (first: \{names:?}). A window with no payout would end the run marked at its last traded price — remove it from the slice or supply its resolution.                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `ResolutionCfg::build`                 |
| engine.settlement\_period\_ms must be > 0, got \{ms} — omit the key to never settle                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `BacktestProfile::refusals`            |
| engine.snap\_to\_properties is single-venue only: the point-in-time instrument grid is looked up under one default\_venue, so a cross-venue \[\[data.series]] slice would snap every series to the first series' venue                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `BacktestProfile::validate_data_slice` |
| engine.timeframes is bar-mode only: the coarse series are resampled from the base BAR stream, and a tick profile has none                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `BacktestProfile::refusals`            |
| engine.timeframes \{tf:?} (\{ms}ms) must be coarser than data.interval \{:?} (\{base}ms) — a finer window cannot be synthesised from the base stream and would return the base bars re-labelled                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `BacktestProfile::refusals`            |
| engine.timeframes \{tf:?} is not a valid interval (want a count then one of s/m/h/d, e.g. "4h")                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `BacktestProfile::refusals`            |
| engine.timeframes \{tf:?} resolves to \{ms}ms — a zero-length window makes every boundary the same instant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `BacktestProfile::refusals`            |
| engine.volume\_limit must be in (0, 1], got \{v} — it is the fraction of the EVENT's own volume one fill may take (a bar's volume in bar mode, ONE PRINT's in tick mode), so 1.0 is all of it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `BacktestProfile::refusals`            |
| euler search supports at most \{MAX\_AXES} sweep axes, got \{} — the 3^d refinement neighbourhood stops being cheaper than the grid past that; use the \{} optimizer (--optimizer \{})                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `numeric_axes`                         |
| queue\_model "prob\_power:\{tail}": \{tail:?} is not a number                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `EngineCfg::queue_model_kind`          |
| rhai compile error: \{e}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `strategy_by_name`                     |
| rhai strategy requires a `src` param (the inline Rhai script source)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `strategy_by_name`                     |
| risk.max\_orders\_per\_window is a wall-clock order-rate throttle — meaningless in backtest sim time (a replayed month can execute in under a second, which would spuriously rate-limit every order; SimBroker::build\_risk\_gate always disarms this field for the identical reason on the live-parity gate it mounts). Remove it from `[risk]` — every other risk.\* limit is honored                                                                                                                                                                                                                                                                                                           | `BacktestProfile::refusals`            |
| strategy.params must be a table                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `require_overridable_params`           |
| strategy.params must be a table                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `profile_with_overrides`               |
| sweep.\{key} mixes integer and float values; \{search} search must render every coordinate as one TOML type, which would change what the strategy receives — make the axis all-integer or all-float, or use the \{grid} optimizer (--optimizer \{grid})                                                                                                                                                                                                                                                                                                                                                                                                                                           | `numeric_sweep_axes`                   |
| sweep.\{key} must be a non-empty array                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `sweep_axis_array`                     |
| sweep.\{key} must be an array of values to sweep over, got \{value:?}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `sweep_axis_array`                     |
| unknown engine.decide \{other:?} (want sequential \| simultaneous; absent = sequential, the per-symbol walk in the order data.symbols lists them)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `EngineCfg::decide_mode`               |
| unknown engine.fee.kind \{kind:?} (known: \{}; a single flat fraction of notional may also stay on engine.fee\_rate, which is the same shape as percent\_maker\_taker charged to both sides)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `FeeCfg::validate_shape`               |
| unknown engine.fee.kind \{other:?} (known: \{})                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `FeeCfg::build_for`                    |
| unknown engine.impact.model \{other:?} (known: "almgren\_chriss")                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `ImpactCfg::build`                     |
| unknown engine.resolution.kind \{:?} (known: "binary\_outcome")                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `ResolutionCfg::validate_shape`        |
| unknown fill\_model \{other:?} (want l2book; absent = the default Tick model)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `EngineCfg::fill_model_kind`           |
| unknown queue\_model \{other:?} (want risk\_adverse \| prob\_power\[:n] \| prob\_log)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `EngineCfg::queue_model_kind`          |
| unknown strategy \{n:?} (known: \{}; user: \{})                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `strategy_by_name`                     |
| walk-forward is bar-mode only: the splitter divides ONE bar series by index, which a tick replay does not produce — set data.kind = "bar"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `walkforward_preflight`                |
| walk-forward optimization needs a \[sweep] table to search — this profile has none, so every window would 'select' the one parameter set it already has. Add the grid, or run the fixed-parameter walk instead.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `run_walkforward_optimized_with`       |
| walk-forward runs over ONE bar series — this profile resolves \{}; name a single symbol                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `walkforward_preflight`                |
| \{search} search needs a \[sweep] table (a single-point profile has nothing to search)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `numeric_sweep_axes`                   |
| \{search} search needs numeric sweep axes, but sweep.\{key} contains \{v:?} — use the \{grid} optimizer (--optimizer \{grid}) for non-numeric axes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `numeric_sweep_axes`                   |

## Where this came from [#where-this-came-from]

Every table, key, default, accepted set and refusal above is rendered from `profile.json`, which
the Rust workspace DERIVES from the types that declare the schema rather than from a table somebody
maintains beside them. The sources it was read from:

| file                                          | owns               |
| --------------------------------------------- | ------------------ |
| `crates/vike-backtest/src/harness/profile.rs` | the profile schema |
| `crates/vike-backtest/src/hist_replay.rs`     | \[\[data.series]]  |

### Related [#related]

* [`vike-cli backtest`](/docs/trader/reference/cli/research/backtest) — the command surface: every flag,
  its default and every refusal, rendered from the CLI's own exported table.
* [Run profiles](/docs/trader/backtesting/run-profiles) — the same file from the harness's side: how a
  slice is resolved, which knobs are bar-only or tick-only, and where a relative path resolves
  from.
* [Walk-forward](/docs/trader/backtesting/walk-forward) and [sweeps](/docs/trader/backtesting/sweeps) — what
  the two optional tables are FOR, rather than what they accept.


# vike-cli backtest (/docs/trader/reference/cli/research/backtest)




Compute a strategy over history and judge what came back. One executor, six verbs that read and
compare what it left behind, two that tell you what you can tune.

**Every run is saved and addressable afterwards**, so reporting, comparison and CI gating never
re-run anything.

## Start here [#start-here]

### What each sub-verb is for [#what-each-sub-verb-is-for]

```
vike-cli backtest run          compute a backtest — or a search, or a walk-forward
                  ls           list what past runs left behind
                  show         re-render ONE stored run, or export a document raw
                  path         print one absolute path, so $(…) works
                  tag          label a run, or give it a MARK a comparison can name
                  diff         what differed in the INPUTS beside the OUTPUTS
                  gate         judge a run against a mark → an EXIT CODE
                  params       the tunable knobs a strategy declares (offline)
                  strategies   the roster the compute SERVER can run
```

`run` is the only one that computes, and the only one that takes `--addr` — so it is the only one
that needs a server at all.

`ls`, `show`, `path`, `tag`, `diff` and `gate` read the run directory and nothing else, which is why
they work on runs made months ago, on another machine, by somebody else. `params` is local too, and
the CLI says so in its own refusal: &#x2A;reads the script or the strategy roster on this machine and
lists its knobs — no server, no store, no engine.*

### Why this verb exists [#why-this-verb-exists]

The heavy history never crosses the wire. You ship a profile — a small TOML document — to the
machine that already holds the data, and get back a compact report. That is the whole trade: compute
goes to the data, not the other way round.

It is also why `--preset` is read **locally** and merged into the profile before anything is sent.
A preset is a file on your disk; the server has no view of it, and giving it one would mean a
`user_data/` directory on the far side with all the questions that raises.

### What it looks like in use [#what-it-looks-like-in-use]

```sh
# a complete backtest, no file anywhere
vike-cli backtest run --venue binance --symbol BTCUSDT --interval 1h \
    --from 2025-01-01 --to 2026-01-01 \
    --strategy momentum --param threshold=60 --param tp=900 \
    --cash 100000 --fee 0.001 --slippage 0.0002

# the same command, saved so it can be committed and reviewed
vike-cli backtest run … --write-profile profiles/momentum_btc.toml

# a search — the profile's [paramscan] table is what makes it one
vike-cli backtest run --profile profiles/momentum_btc.toml \
    --optimizer tpe --trials 400 --seed 7 --rank-by sharpe

# afterwards — no engine, no store, no socket
vike-cli backtest show <id> --metrics
vike-cli backtest diff <id> baseline/momentum
vike-cli backtest gate <id> --against baseline/momentum --fail-if 'sharpe:-5%'
```

### The grammar [#the-grammar]

**A sub-verb is required.** There is no bare `vike-cli backtest` — running it without one is an error, not a default action. 12 exist: `run`, `ls`, `show`, `path`, `tag`, `diff`, `gate`, `params`, `strategies`, `templates`, `script-api`, `script-check`.

A flag takes its value in either form — `--flag value`, `--flag=value` — and an `=` form splits on the FIRST `=` only, so a value may contain more. `--help` writes to **stdout** and exits **0**, so it is pipeable and does not read as a failure in a script.

### How much surface each sub-verb has [#how-much-surface-each-sub-verb-has]

Flags each sub-verb accepts, of 54 that ship.

| sub-verb                | flags accepted |
| ----------------------- | -------------- |
| `backtest run`          | 33             |
| `backtest ls`           | 7              |
| `backtest show`         | 9              |
| `backtest path`         | 2              |
| `backtest tag`          | 5              |
| `backtest diff`         | 6              |
| `backtest gate`         | 4              |
| `backtest params`       | 4              |
| `backtest strategies`   | 3              |
| `backtest templates`    | 2              |
| `backtest script-api`   | 1              |
| `backtest script-check` | 2              |

## The sub-verbs, one at a time [#the-sub-verbs-one-at-a-time]

Each one: the line you type, commands to copy, then every flag it accepts. A flag accepted by
several sub-verbs appears under each.

### `backtest run` [#backtest-run]

`vike-cli backtest run [--profile <run.toml>] [overrides]`

Builds ONE profile TOML — from `--profile` if you name one, otherwise from an empty table — applies
the flags on the line as overrides, and computes it. The default route is **remote**: the profile
text is shipped to a compute daemon, so a line with no daemon up dies on the connect rung rather
than quietly running here. `--local` spawns the standalone engine on this machine instead, and the
two cannot be combined.

```sh
# A complete run with no file anywhere — every flag here is sugar for a profile key
vike-cli backtest run --venue binance --symbol BTCUSDT --interval 1h \
    --from 2025-01-01 --to 2026-01-01 \
    --strategy momentum --param threshold=60 --param tp=900 \
    --cash 100000 --fee 0.001 --slippage 0.0002

# Shorter, while you are still deciding whether the idea works at all
vike-cli backtest run --venue binance --symbol BTCUSDT --interval 1d \
    --from 2025-01-01 --to 2026-01-01 --strategy buy_hold --cash 10000
vike-cli backtest run --venue binance --symbol ETHUSDT --interval 4h \
    --from 2025-06-01 --to 2026-01-01 --strategy momentum --cash 10000

# Several symbols — --symbol is the ONE flag that folds instead of last-wins
vike-cli backtest run --strategy buy_hold --symbol BTCUSDT,ETHUSDT \
    --venue binance --interval 1h --kind bar \
    --from 2026-01-01T00 --to 2026-02-01T00 --cash 10000
vike-cli backtest run --profile run.toml --symbol BTCUSDT,ETHUSDT --symbol SOLUSDT

# Ticks instead of bars
vike-cli backtest run --venue binance --symbol BTCUSDT --kind tick \
    --from 2026-01-01 --to 2026-01-02 --strategy momentum --cash 10000

# Read it back before you spend a run — --show-effective PRINTS, then STOPS
vike-cli backtest run --profile profiles/momentum_btc.toml --show-effective
vike-cli backtest run --profile run.toml --fee 0.001 --slippage 0.0005 \
    --set engine.fee_rate=0.001 --param size=1.5 --show-effective
vike-cli backtest run --venue binance --symbol BTCUSDT --strategy momentum \
    --cash 10000 --show-effective

# Keep the command you liked — --write-profile writes, and then RUNS
vike-cli backtest run --profile profiles/momentum_btc.toml \
    --write-profile profiles/momentum_btc.toml
vike-cli backtest run --venue binance --symbol BTCUSDT --interval 1h \
    --from 2025-01-01 --to 2026-01-01 --strategy momentum --cash 100000 \
    --write-profile profiles/first-try.toml

# Change one knob against a profile you trust
vike-cli backtest run --profile profiles/momentum_btc.toml --fee 0.002
vike-cli backtest run --profile profiles/momentum_btc.toml --cash 250000
vike-cli backtest run --profile profiles/momentum_btc.toml --param threshold=75

# Reach an engine knob that has no flag of its own
vike-cli backtest run --profile p.toml \
    --set engine.cash_gate=true \
    --set engine.maint_margin=0.005 \
    --set engine.volume_limit=0.05
vike-cli backtest run --profile p.toml --set engine.sizer.kind=pct_equity \
    --set engine.sizer.pct=0.02
vike-cli backtest run --profile p.toml --set name=btc-trend-1h-fees-on

# Layer a preset and a script — the preset merges FIRST, the script overwrites src
vike-cli backtest run --preset fast.toml --script s.rhai --write-profile out.toml
vike-cli backtest run --profile p.toml --script strategies/momentum.rhai
vike-cli backtest run --profile p.toml --preset presets/tight-stops.toml

# Search a [paramscan] grid — each method owns its own knobs
vike-cli backtest run --profile run.toml --optimizer grid --rank-by sharpe
vike-cli backtest run --profile run.toml --optimizer grid --rank-by max_dd
vike-cli backtest run --profile run.toml --optimizer tpe --trials 400 --seed 7
vike-cli backtest run --profile run.toml --optimizer tpe --trials 8 --seed 1
vike-cli backtest run --profile run.toml --optimizer euler --euler-depth 2
vike-cli backtest run --profile run.toml --optimizer euler --euler-depth 0
vike-cli backtest run --profile run.toml --optimizer genetic --seed 1
vike-cli backtest run --profile run.toml --optimizer tpe --trials 200 --seed 7 \
    --rank-by multi

# Run the engine on THIS machine instead of shipping the profile
vike-cli backtest run --profile run.toml --local --store /data --engine /opt/backtest
vike-cli backtest run --profile p.toml --local --store ~/vike/store
vike-cli backtest run --profile run.toml --local --json

# Dial a specific daemon, or take the report JSON verbatim
vike-cli backtest run --profile run.toml --addr 127.0.0.1:7880
vike-cli backtest run --profile run.toml --addr 127.0.0.1:7881 --json
vike-cli backtest run --profile run.toml --json

# A preset plus a script, frozen to a profile you can commit
vike-cli backtest run --preset fast.toml --script s.rhai \
    --write-profile out.toml
```

<Callout type="error" title="--local and --addr are one choice, not two">
  Writing both is refused: `--addr` names a
  remote daemon, so it cannot be combined with running the engine here. That choice then decides two
  more flags — `--store` and `--engine` apply to `--local` ONLY, and typing either on the remote arm
  is refused rather than ignored, because a remote run reads the **server's** store. And one shape has
  no local answer at all: a profile declaring a `[walkforward]` table cannot run under `--local`,
  because the standalone engine has one profile path that branches on `[paramscan]` and nothing else.
</Callout>

<Callout type="error" title="A search knob belongs to ONE method">
  `--trials` is tpe's, `--euler-depth` is euler's, `--seed`
  is tpe's and genetic's. A knob typed under the wrong method is refused on both routes — including
  under the `grid` you get by writing no `--optimizer` at all. These used to be discarded in silence,
  which is the whole reason the refusal exists. `genetic` additionally REFUSES an absent `--seed`,
  deliberately: a genetic search reports one sample of a distribution, and a seed nobody typed is a
  constant the result silently depends on.
</Callout>

<Callout type="warn" title="--param cannot be validated, on either side">
  `[strategy.params]` is an untyped TOML value,
  so a typo'd knob name is a silent no-op — the run proceeds with the default you meant to change.
  `backtest params --strategy <name>` is how you get the real list. `--set` is checked only on its
  FIRST dotted segment (against `name, data, engine, strategy, risk, paramscan, sweep, walkforward`);
  everything after it is the far side's unknown-field refusal.
</Callout>

<Callout type="warn" title="Three values have no default anywhere, and --cash is one of them">
  Omit it and the far side
  refuses by name, because a starting balance is a modelling input with no defensible default. `--from`
  and `--to` are the other two. Meanwhile `--fee` and `--slippage` default to `0.0` and the
  participation cap, cash gate and margin model are all **off** unless you turn them on with `--set` —
  so a default run can spend money it does not have. `--show-effective` is how you check before you
  believe a number.
</Callout>

| flag                         | sample                  | scope    | what it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ---------------------------- | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--addr host:port`           | `127.0.0.1:7880`        | `remote` | The COMPUTE daemon to dial (vike-backend backtest --addr, NOT the datahub). Refused beside --local; unwritten, it falls through config.backtest\_addr to 127.0.0.1:7880.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `--cash N`                   | `10000`                 | any      | A `run`-only sugar flag (SUGAR row `engine.cash`, Shape::Scalar) included here because it has THREE different answers across this plane. ACCEPTED on `run`. On `params` it is on `PARAMS_REFUSED` and gets the run-flag sentence. On every other reading sub-verb it is not a known token at all and falls into the generic unknown-option arm.                                                                                                                                                                                                                                                                                                                                                  |
| `--decide mode`              | `sequential`            | any      | WHEN a multi-symbol step is decided. `simultaneous` makes the run's answer a property of the instrument SET rather than of the order data.symbols was typed in, and IMPLIES engine.cash\_gate. Sugar for `--set engine.decide=…`, reaching the same key through the same applier.                                                                                                                                                                                                                                                                                                                                                                                                                |
| `--engine PATH`              | `/opt/backtest`         | `local`  | Name the standalone engine outright instead of searching for it. Local-arm only; never probed for existence.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `--euler-depth N`            | `2`                     | any      | euler's successive-halving depth. Forwarded as a token; range-checked (0..=16) by the engine, never clamped silently.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `--fee RATE`                 | `0.001`                 | any      | Sugar for engine.fee\_rate through parse\_scalar; a non-numeric value becomes a TOML string and is refused far-side, not here.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `--from DATE`                | `2026-01-01T00`         | any      | Sugar for data.from. Shape::Str is REQUIRED not a preference: a bare epoch-ms stays a string, so --from 0 works while --set data.from=0 is a far-side type error.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `--interval 1h`              | `1h`                    | any      | Sugar for data.interval, plus the ONE grammar check inside the match body: the trimmed value must parse through vike\_model::time::interval\_ms.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `--json`                     | —                       | any      | Print a machine-readable document instead of the human rendering. On `run` that is the server's report JSON verbatim (and on --local it is forwarded to the spawned engine); each reading verb emits its own — `gate`'s carries the verdict, one object per criterion, and `available_keys` when a criterion went unevaluated. ⚠ ACCEPTED on `path` and read nowhere: that verb prints one line so `$(…)` works and has no document form, so the flag is inert there rather than refused. On `script-check` the document is the VERDICT (`ok`, `error`, `script`, `params`) and the rung is beside it; on `templates` it is the starter roster, one starter, or the path a starter was saved to. |
| `--kind bar\|tick`           | `bar`                   | any      | Sugar for data.kind, plus the second in-match special case: the trimmed value goes through one\_of against DATA\_KINDS. It is the key implied\_defaults always supplies.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `--local`                    | —                       | any      | Run on THIS machine by spawning the standalone backtest engine instead of shipping the profile to a compute daemon.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `--optimizer method`         | `grid`                  | any      | The parameter-search METHOD (grid, euler, tpe, genetic). Spelling-checked locally against the protocol roster; meaning resolved by the engine or the compute server.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `--param k=v`                | `size=1.5`              | any      | Sugar for --set strategy.params.\<k>=\<v>, value typed by parse\_scalar. NO schema validation is possible on either side: StrategyCfg::params is an untyped toml::Value, so a typo is a silent no-op.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `--preset <p.toml>`          | `fast.toml`             | any      | A flat preset TOML merged into \[strategy.params], applied BEFORE --script. Repeating it silently LAST-WINS.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `--profile <run.toml>`       | `run.toml`              | any      | Optional BASE profile file; flags override it. Repeating it silently LAST-WINS (plain Option assignment, no test pins it).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--rank-by METRIC`           | `sharpe`                | any      | Which metric orders a parameter search's rows (sharpe, return, max\_dd, equity, multi). A VALID value is IGNORED, not an error, on a profile with no grid.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--script <s.rhai>`          | `s.rhai`                | any      | Injects the .rhai file's source into strategy.params.src (overwriting any existing src) and implies strategy.name=rhai. On the `params` sub-verb the same spelling names the script whose knobs are listed, and on `script-check` the script to COMPILE — three owners, one meaning: a .rhai file on this machine.                                                                                                                                                                                                                                                                                                                                                                               |
| `--seed u64`                 | `1`                     | any      | Reproducibility seed for the two stochastic searchers. tpe defaults it to 0; genetic REFUSES an absent one.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `--set key=value`            | `engine.fee_rate=0.001` | any      | Repeatable universal channel; value typed by parse\_scalar. ONLY the FIRST segment is checked (against PROFILE\_TOP\_LEVEL\_KEYS) — the rest is the far side's deny\_unknown\_fields, on exit rung 1.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `--show-effective`           | —                       | any      | Prints the resolved profile with each override's origin as TOML COMMENTS and STOPS — exit 0, no dial, no engine, no store. Rejects an inline value.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `--slippage RATE`            | `0.0005`                | any      | Sugar for engine.slippage through parse\_scalar; same typing rule as --fee and --cash.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `--store DIR`                | `/data`                 | `local`  | The hist-store root the LOCAL engine reads. Local-arm only: a remote run reads the SERVER's store.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `--strategy NAME`            | `buy_hold`              | any      | Sugar for strategy.name, forwarded UNVALIDATED (the roster lives in vike-backtest and includes user strategies this crate cannot see). On the `params` sub-verb the same spelling names the roster entry whose knobs are listed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `--symbol SYM[,SYM]`         | `BTCUSDT,ETHUSDT`       | any      | The ONE row that does not push per occurrence: every occurrence comma-splits and accumulates, and a SINGLE data.symbols array Override is pushed after the loop, in argv order.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `--to DATE`                  | `2026-02-01T00`         | any      | Sugar for data.to; same Shape::Str string-preservation rule as --from. No CLI-side date validation of any kind.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `--trials N`                 | `8`                     | any      | tpe's trial budget. Forwarded as the token you typed; the engine or the server parses and refuses it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `--venue NAME`               | `binance`               | any      | Sugar for data.venue, value trimmed and written as a TOML string. No roster check here — a venue name is forwarded unvalidated.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `--write-profile <out.toml>` | `out.toml`              | any      | Writes the fully-resolved profile (after --preset and --script rewrites) and then RUNS. Refuses an existing path outright. Repeating it silently LAST-WINS.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `--explain-data`             | —                       | any      | Print exactly what the run WILL read — every series, the resolved range, the store root and the rung that chose it, with row counts — and stop without computing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `--require-coverage`         | —                       | any      | Refuse a run whose window the store does not cover, naming the missing spans per series. The failure it ends: a window with a complete trade tape and no book runs to completion and REPORTS FILLS.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `--max-gap SPAN`             | `1d`                    | any      | How large an interior hole `--require-coverage` tolerates. A PER-SPAN tolerance, not a total: a shortfall that is the whole series ignores it under every value.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `--on-gap DISPOSITION`       | `warn`                  | any      | What an armed coverage gate DOES about an uncovered window: refuse stops the run, warn logs the findings and runs unchanged, run leaves the verdict in the document only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `--universe MODE`            | `strict`                | any      | What to do about a member whose tape does not span the window: declared takes the list verbatim, covered names the short members and runs anyway, strict refuses. NONE of the three drops a member.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

**Which knob belongs to which search method** — `--euler-depth => euler`, `--trials => tpe`, `--seed => tpe, genetic`.

**Parses, then refuses:** `--list-params` reach this sub-verb and are turned down by name — see [Accepted nowhere yet](#accepted-nowhere-yet) for what each one is waiting on.

### `backtest ls` [#backtest-ls]

`vike-cli backtest ls [--where EXPR] [--sort FIELD[:dir]] [--cols a,b,c] [--limit N] [--out FILE]`

Lists runs already on disk. It takes no `--addr` and no selector, so there is no remote form and
nothing is recomputed. A bare `ls` prints four manifest fields and opens no `report.json` at all —
the moment you name a metric in `--cols`, `--sort` or `--where`, every run's report is read.

```sh
# Start here — the flag list, then the default table
vike-cli backtest ls --help             # or -h: the USAGE block on stdout, exit 0
vike-cli backtest ls                    # the DEFAULT_COLS four; no report.json opened

# Choose the columns — a metric column opens every report.json
vike-cli backtest ls --cols run_id,kind,started_at,report   # that default, spelled out
vike-cli backtest ls --cols run_id,kind,sharpe
vike-cli backtest ls --cols run_id,kind,sharpe,max_drawdown
vike-cli backtest ls --cols run_id,started_at,config.name

# Narrow, order, truncate — QUOTE the expression, > and < are the shell's
vike-cli backtest ls --where 'sharpe>1.2' --sort sharpe --limit 20
vike-cli backtest ls --where 'kind=backtest,sharpe>1'       # comma is AND
vike-cli backtest ls --where 'kind=search' --sort sharpe:desc --limit 10
vike-cli backtest ls --where 'config.name~momentum' --sort started_at:desc
vike-cli backtest ls --where 'sharpe<0' --cols run_id,config.name,sharpe

# The worst runs, not the best — ascending is how you find what broke
vike-cli backtest ls --sort sharpe:asc --limit 10 --cols run_id,config.name,sharpe
vike-cli backtest ls --sort max_drawdown:desc --limit 10 \
    --cols run_id,config.name,max_drawdown

# What ran today, and what it was called
vike-cli backtest ls --sort started_at:desc --limit 20 \
    --cols run_id,kind,started_at,config.name
vike-cli backtest ls --where 'kind=walkforward' --sort started_at:desc --limit 5

# Write the rendered table to a file — an existing path is OVERWRITTEN
vike-cli backtest ls --sort sharpe:desc --limit 20 --out runs.txt
vike-cli backtest ls --where 'sharpe>1' --sort sharpe:desc --limit 50 --out shortlist.txt

# A leaderboard in one line: filter, order, pick the columns, cap the rows
vike-cli backtest ls --where 'kind=backtest,sharpe>1' --sort sharpe:desc \
    --cols run_id,kind,sharpe --limit 20
```

**`--where` — the grammar, in full.** One predicate in place of a wall of typed min/max flags, and
its field vocabulary is shared with `--sort` and `--cols`, so the three can never disagree about a
name:

```text
EXPR := TERM (',' TERM)*        # comma is AND. There is no OR and no grouping.
TERM := FIELD OP VALUE
OP   := '>=' | '<=' | '!=' | '~' | '=' | '>' | '<'      # two-character operators match FIRST
```

<Callout type="info" title="How a comparison is decided — and what a missing field does">
  A comparison is **numeric when both sides parse as a number**, and a case-insensitive string
  comparison otherwise; `~` is always a substring test. &#x2A;*A missing field fails every operator except
  `!=`** — a null is not less than anything, and letting `sharpe>1` admit a run that computed no
  Sharpe would put an empty row at the top of your leaderboard. So a filter on a metric silently
  narrows the table to runs that HAVE it, which is usually what you want and is worth knowing when a
  count surprises you.
</Callout>

<Callout type="warn" title="Quote the --where expression">
  `>` and `<` belong to the shell. Unquoted,
  `--where kind=backtest,sharpe>1` never reaches the CLI intact: the shell takes `>1` as a redirection
  and creates a file called `1`, handing `ls` a term with its operator stripped off. It refuses rather
  than filtering on something you did not write — but single-quote the whole expression and the
  problem does not arise.
</Callout>

<Callout type="warn" title="A misspelled --cols name is a column of dashes, not a refusal">
  The field vocabulary has an
  open tail: the manifest fields resolve first, `detail.<dotted.path>` reaches into the manifest
  detail, and &#x2A;*any other name is read as a top-level key of `report.json`** — which is a legal
  request for a key that may simply be absent. So `--cols` cannot tell a typo from a missing key, and
  renders `-`. The same typo in `--sort` *is* refused, because it has every row in hand and can see
  that none carries the key. A quiet column of dashes is a typo; an empty table is an empty store.
</Callout>

<Callout type="info" title="--where has no OR and no grouping">
  The grammar is `FIELD OP VALUE` joined by commas, and the
  comma means AND. Operators are `>=` `<=` `!=` `~` `=` `>` `<`, with the two-character ones matched
  first. A `|` anywhere is refused with the advice to run `ls` twice for a disjunction. `--limit` is
  parsed at render time rather than in the flag loop, so a negative or non-integer value still lands
  as a usage refusal rather than a silent zero.
</Callout>

<Callout type="warn" title="--sort's typo check sees rows --where already removed">
  The "no run carries that field"
  check runs over the UNFILTERED scan, so a field only your excluded runs carry passes the check and
  then sorts every surviving row into the missing-key bucket at the end. An empty store is excused
  before that check runs, deliberately — otherwise a fresh project would exit 2 accusing you of a typo
  you had not made.
</Callout>

| flag                        | sample                   | scope | what it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| --------------------------- | ------------------------ | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--cols a,b,c`              | `run_id,kind,sharpe`     | any   | `ls` only. Split on ',', each element trimmed, EMPTY elements dropped — so `--cols 'a,,b'` is two columns, not three, and `--cols ,` is refused as no column names. An unknown column name is NOT refused: it renders as a column of '-'.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--help`                    | —                        | any   | `-h` or `--help`, matched inside the shared reading flag loop. Also FALLS THROUGH — no refusal array names it. It short-circuits through the Err channel with `args::HELP_SENTINEL` ("help requested"), which `args::exit_for_parse_error` turns back into the USAGE on stdout and exit 0.                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `--json`                    | —                        | any   | Print a machine-readable document instead of the human rendering. On `run` that is the server's report JSON verbatim (and on --local it is forwarded to the spawned engine); each reading verb emits its own — `gate`'s carries the verdict, one object per criterion, and `available_keys` when a criterion went unevaluated. ⚠ ACCEPTED on `path` and read nowhere: that verb prints one line so `$(…)` works and has no document form, so the flag is inert there rather than refused. On `script-check` the document is the VERDICT (`ok`, `error`, `script`, `params`) and the rung is beside it; on `templates` it is the starter roster, one starter, or the path a starter was saved to.                |
| `--limit N`                 | `20`                     | any   | `ls` only. Parsed as `usize` at RENDER time (not in the flag loop), then `runs.truncate(n)`. A negative or non-integer value is a usage refusal.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `--out FILE`                | `runs.txt`               | any   | A DOUBLE-OWNED FLAG. Owners: `ls` (writes the table or the --json document) and `show` (writes the rendered run, or the raw --export document). Refused on every other reading sub-verb by a NAMED rule, not by a roster: `gate` and `diff` are deliberately excluded because their single clean stream is what `>` already handles. The write itself is `std::fs::write(file, format!("\{text}\\n"))` — note the appended newline — and an existing path is OVERWRITTEN (no refusal). ⚠ That last property is why `templates` does NOT reuse this flag even though it is the one reading verb that creates a file: --write-strategy refuses an existing path, and one flag may not carry two clobber policies. |
| `--sort FIELD[:asc\|:desc]` | `sharpe:desc`            | any   | `ls` only. Direction defaults by TYPE of the surviving rows: numeric descends, text ascends; runs missing the key sort LAST in both directions. The typo check runs over the UNFILTERED scan, and an EMPTY store is excused before the fold (otherwise `all(Missing)` would be vacuously true and a fresh project would exit 2 accusing a typo).                                                                                                                                                                                                                                                                                                                                                                |
| `--where EXPR`              | `kind=backtest,sharpe>1` | any   | `ls` only. Grammar: EXPR := TERM ("," TERM)\* ; TERM := FIELD OP VALUE ; OP := >= \| \<= \| != \| \~ \| = \| > \| \< (two-character operators tried FIRST). Comma is AND; there is no OR and no grouping. FIELD resolves through the same `ls::field_of` vocabulary `--sort`/`--cols` use.                                                                                                                                                                                                                                                                                                                                                                                                                      |

**The columns a bare `ls` prints** — `run_id`, `kind`, `started_at`, `report`.

**The operators `--where` accepts** — `>=`, `<=`, `!=`, `~`, `=`, `>`, `<`.

**The field names `--cols`, `--sort` and `--where` share** — `run_id`, `kind`, `produced_by`, `started_at`, `finished_at`, `git_sha`, `config.path`, `config.name`, `report`, `detail.<dotted.path>`, `<any other name> = a TOP-LEVEL key of report.json`.

**Parses, then refuses:** `--attribution`, `--breakdown`, `--drawdowns` reach this sub-verb and are turned down by name — see [Accepted nowhere yet](#accepted-nowhere-yet) for what each one is waiting on.

### `backtest show` [#backtest-show]

`vike-cli backtest show <selector> [--metrics|--trades|--config] [--export trades|equity] [--out FILE]`

Re-renders one run that is already on disk: it opens the directory a selector names and prints it,
with no server, no engine and no store lookup in the path. The rule that catches people is that the
three section flags **narrow** — a bare `show` prints metrics, trades and config, and naming one of
them *hides* the other two.

```sh
# Name the run — five selector forms, all accepted here
vike-cli backtest show 1789213143-8821-01   # the full run id
vike-cli backtest show 1789213              # a unique id PREFIX is enough
vike-cli backtest show @last                # the newest run, any kind
vike-cli backtest show @last:search         # the newest run of ONE kind
vike-cli backtest show @baseline/momentum   # a mark set by `backtest tag --as`

# Narrow to a section — naming one HIDES the others, it does not add one
vike-cli backtest show @last --metrics            # report.json's metrics, alone
vike-cli backtest show @last --trades             # the stored trade ledger, alone
vike-cli backtest show @last --config             # profile path + resolved config.toml
vike-cli backtest show @last --metrics --config   # two sections; trades is now hidden

# Audit what actually produced a number — was the cost model even on?
vike-cli backtest show @baseline/momentum --config
vike-cli backtest show 1789213 --config
vike-cli backtest show @last:search --config

# Export the raw stored document instead of a rendering
vike-cli backtest show @last --export trades      # trades.json, pretty-printed
vike-cli backtest show @last --export equity      # series.json: the equity curve
vike-cli backtest show @last --export=equity      # same value, --flag=value form

# Send it to a file — with --export, the EXPORT is what lands there
vike-cli backtest show @last --out run.txt
vike-cli backtest show @last --metrics --out metrics.txt
vike-cli backtest show @last --export equity --out equity.json
vike-cli backtest show @last --export trades --out trades.json
vike-cli backtest show --help

# Write the rendering to a file instead of the terminal
vike-cli backtest show @last --out runs.txt
vike-cli backtest show @last --export equity --out runs.txt   # the equity series, redirected
```

<Callout type="warn" title="The section flags narrow, and they do nothing under --export">
  `show` computes
  *all = not metrics and not trades and not config*, so naming any one of them turns the other two
  off. Under `--export` they shape nothing at all: the export replaces the rendering outright. Each
  takes no value, so `--metrics=1` is refused rather than read as truthy.
</Callout>

<Callout type="info" title="--export fills is refused by name, and that is a data fact rather than a missing feature">
  Fills are not stored at any size: a backtest computes them, consumes them into `report.json`'s
  scalars and drops them. Only the trade LEDGER and the equity curve survive, which is why `trades`
  and `equity` are the whole set. A comma list such as `trades,equity` is refused too — one export is
  one document and `--out` is one file, so run `show` twice.
</Callout>

<Callout type="info" title="Four renderers parse and then refuse, and two of them are missing DATA rather than a renderer">
  `--html` needs a tearsheet renderer nothing in this tree has built. `--drawdowns` needs only the
  table — the equity curve it would read is already in `series.json`, and `--export equity` hands you
  that curve today. `--breakdown` needs per-bar returns, and the stored curve is DECIMATED once a run
  passes the sample cap, so a period breakdown computed off it would disagree with `report.json`'s own
  numbers. `--attribution` needs a per-source attribution the engine does not compute at all.
</Callout>

<Callout type="info" title="A run flag here is a bare unknown option, not a sentence">
  The sugar flags belong to
  `backtest run`; on `show` they are not known tokens at all, so `--cash` gets `unknown option
  '--cash'` and exit 2 with nothing telling you where the flag actually lives. `params` is the one
  reading sub-verb that holds a named roster of them and answers with the full sentence instead.
</Callout>

| flag                      | sample     | scope   | what it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------- | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--config`                | —          | any     | `show` only. Renders the run's RunConfig (the profile path as the operator spelled it, plus its name) and the resolved config.toml when the producer wrote one — saying so when it is absent.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `--export trades\|equity` | `trades`   | any     | `show` only. REPLACES the rendering entirely with the raw stored document (pretty-printed JSON), and composes with `--out` and with nothing else. The value is trimmed. A COMMA LIST is refused by name. `fills` is refused by NAME with its own sentence rather than by refusing the flag.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `--help`                  | —          | any     | `-h` or `--help`, matched inside the shared reading flag loop. Also FALLS THROUGH — no refusal array names it. It short-circuits through the Err channel with `args::HELP_SENTINEL` ("help requested"), which `args::exit_for_parse_error` turns back into the USAGE on stdout and exit 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `--html`                  | —          | `local` | `show` only: this run's whole tearsheet as one standalone HTML page, to --out or stdout. ⚠ It was a member of the unbuilt\_renderers roster until the vike-report edge landed, refused with a sentence blaming a missing renderer — `vike_report::render_html` was never missing and `LiveTearsheet::from_report` names show\.rs by path as the caller it was built for; what was missing was the dependency. The metrics table carries report.json through value by value, but the charts, their captions and the monthly-returns table are FOLDED from series.json as stored, so on a decimated run the drawn low can read shallower than the max\_drawdown printed above it. That asymmetry is why this ships where --breakdown stays refused: a picture of a sample is visibly one, while a recomputed period table would quietly disagree with report.json's own numbers. |
| `--json`                  | —          | any     | Print a machine-readable document instead of the human rendering. On `run` that is the server's report JSON verbatim (and on --local it is forwarded to the spawned engine); each reading verb emits its own — `gate`'s carries the verdict, one object per criterion, and `available_keys` when a criterion went unevaluated. ⚠ ACCEPTED on `path` and read nowhere: that verb prints one line so `$(…)` works and has no document form, so the flag is inert there rather than refused. On `script-check` the document is the VERDICT (`ok`, `error`, `script`, `params`) and the rung is beside it; on `templates` it is the starter roster, one starter, or the path a starter was saved to.                                                                                                                                                                               |
| `--metrics`               | —          | any     | `show` only. Renders the report.json metrics section. Has no effect under `--json` (`show_json` takes only `a.trades`) and none under `--export` (the export replaces the rendering entirely).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `--metrics-list`          | —          | any     | `show` only, and the ONE flag on this verb that is not about a run: it prints the METRIC CATALOG (every id with where it is stored and what it measures, plus the declared-absent rows) and stops. Takes no selector and reads no runs directory. Composes with --out; refused beside --metrics/--trades/--config/--export and beside --json.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `--out FILE`              | `runs.txt` | any     | A DOUBLE-OWNED FLAG. Owners: `ls` (writes the table or the --json document) and `show` (writes the rendered run, or the raw --export document). Refused on every other reading sub-verb by a NAMED rule, not by a roster: `gate` and `diff` are deliberately excluded because their single clean stream is what `>` already handles. The write itself is `std::fs::write(file, format!("\{text}\\n"))` — note the appended newline — and an existing path is OVERWRITTEN (no refusal). ⚠ That last property is why `templates` does NOT reuse this flag even though it is the one reading verb that creates a file: --write-strategy refuses an existing path, and one flag may not carry two clobber policies.                                                                                                                                                                |
| `--trades`                | —          | any     | THE OTHER DOUBLE-OWNED FLAG. Owners: `show` (renders trades.json as a section) and `diff` (adds a third diff section over both runs' trades.json). Deliberately kept OUT of both the `show_only` and `diff_only` rosters and refused on the remaining six by its own named rule with its own sentence.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

**The ways to name a run** — `<run-id>`, `<unique-prefix>`, `@last`, `@last:<kind>`, `@<mark>`.

**The forms the REFUSAL lists when you name none** — `<run-id>`, `<unique-prefix>`, `@last`, `@last:<kind>`.

⚠ HAND-WRITTEN, and it DISAGREES with FORMS. This four-name list is a literal inside a format! template in another crate-module; nothing derives it from FORMS and no test compares the two.

**What `--export` can take** — `trades`, `equity`.

⚠ `fills` is recognised and **refused**: --export fills is not available — fills are not stored at ANY size. A backtest computes them, consumes them into report.json's scalars and drops them; only the trade LEDGER and the equity curve survive. `--export trades` and `--export equity` both work today.

**Parses, then refuses:** `--attribution`, `--breakdown`, `--drawdowns` reach this sub-verb and are turned down by name — see [Accepted nowhere yet](#accepted-nowhere-yet) for what each one is waiting on.

### `backtest path` [#backtest-path]

`vike-cli backtest path <selector> [FILE]`

Prints ONE absolute line — the stored run's directory, or a file inside it — so it composes with
`$(…)`, `cd` and `jq` with no parsing at all. It takes a selector positionally and an optional FILE
after it, and the rule people get wrong is that FILE is **sugar over an open set**: `report` and
`manifest` are spelled out, everything else is joined to the directory verbatim.

```sh
# One absolute line — the run's directory, or one file inside it
vike-cli backtest path @last                 # the newest run's directory
vike-cli backtest path @last report          # sugar for report.json in that dir
vike-cli backtest path @last manifest.json   # the other spelled-out name
vike-cli backtest path @last series.json     # any other name joins VERBATIM
vike-cli backtest path @last trades.json

# Naming the run — the five selector forms this verb takes
vike-cli backtest path 1789213143-8821-01    # the full run id
vike-cli backtest path 1789213               # a unique short prefix
vike-cli backtest path @last:search          # newest run of that kind
vike-cli backtest path @baseline/momentum report

# Which is the point of it — the line drops straight into another tool
jq .metrics.sharpe "$(vike-cli backtest path @last report)"
jq -r '.metrics | to_entries[] | "\(.key)\t\(.value)"' "$(vike-cli backtest path @last report)"
cd "$(vike-cli backtest path @last)"
ls -la "$(vike-cli backtest path @last)"

# Compare two runs with tools that know nothing about vike
diff <(jq -S .metrics "$(vike-cli backtest path @baseline/momentum report)") \
     <(jq -S .metrics "$(vike-cli backtest path @last report)")

# Copy a run's artefacts somewhere else
cp "$(vike-cli backtest path @last report)" ./report-under-review.json
cp -r "$(vike-cli backtest path @baseline/momentum)" ./baseline-snapshot

# The only flag this verb has
vike-cli backtest path --help
```

<Callout type="warn" title="FILE is sugar over an open set, not a vocabulary">
  `report` → `report.json` and `manifest` →
  `manifest.json` are the only two spellings this verb knows; every other name is joined to the
  directory exactly as typed. So `path @last sereis.json` prints a path happily — the typo surfaces
  only when something tries to open it. The upside is that a run artefact added next month needs no
  change here.
</Callout>

<Callout type="info" title="It prints a path; it does not promise the file exists">
  The run directory is resolved and the
  name is appended, with no `stat` in the way. That is what makes it safe inside `$(…)` — a probe
  would make the line's success depend on the artefact rather than on the run — but it means the
  consumer is what reports a missing file, in its own words.
</Callout>

<Callout type="info" title="Every other flag of the plane is refused here, by name">
  `path` takes `--help` and nothing else,
  so a pasted `--cols` or `--metrics` answers with the sub-verb that owns it rather than with
  `unknown option`. There is no `--out`: the whole output is one line the shell can already redirect.
</Callout>

| flag     | sample | scope | what it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| -------- | ------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--help` | —      | any   | `-h` or `--help`, matched inside the shared reading flag loop. Also FALLS THROUGH — no refusal array names it. It short-circuits through the Err channel with `args::HELP_SENTINEL` ("help requested"), which `args::exit_for_parse_error` turns back into the USAGE on stdout and exit 0.                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--json` | —      | any   | Print a machine-readable document instead of the human rendering. On `run` that is the server's report JSON verbatim (and on --local it is forwarded to the spawned engine); each reading verb emits its own — `gate`'s carries the verdict, one object per criterion, and `available_keys` when a criterion went unevaluated. ⚠ ACCEPTED on `path` and read nowhere: that verb prints one line so `$(…)` works and has no document form, so the flag is inert there rather than refused. On `script-check` the document is the VERDICT (`ok`, `error`, `script`, `params`) and the rung is beside it; on `templates` it is the starter roster, one starter, or the path a starter was saved to. |

**The ways to name a run** — `<run-id>`, `<unique-prefix>`, `@last`, `@last:<kind>`, `@<mark>`.

**File names spelled out — anything else joins verbatim** — `manifest`, `manifest.json`, `report`, `report.json`.

**Parses, then refuses:** `--attribution`, `--breakdown`, `--drawdowns` reach this sub-verb and are turned down by name — see [Accepted nowhere yet](#accepted-nowhere-yet) for what each one is waiting on.

### `backtest tag` [#backtest-tag]

`vike-cli backtest tag <selector> [--add TAG] [--as NAME] [--note TEXT]`

The one writing verb in this plane: it takes a stored run and puts labels, a note or a mark onto it.
Nothing happens by default — with no flags it writes nothing — and the three flags write to **two
different places on disk**, which is why a mark survives things a label does not.

```sh
# Label a run so you can find it again — --add is the ONE repeatable flag here
vike-cli backtest tag @last --add ci                # one label
vike-cli backtest tag @last --add ci --add fee-fix  # two labels, one write
vike-cli backtest tag 1789213 --add ci              # a unique short prefix names the run
vike-cli backtest tag @last:search --add grid-sweep

# Give a run a MARK — the stable name a gate can be pointed at
vike-cli backtest tag @last --as baseline/momentum   # gate --against @baseline/momentum
vike-cli backtest tag 1789213143-8821-01 --as prod   # the mark outlives the run id
vike-cli backtest tag @last --as baseline/btc-1h
vike-cli backtest tag @last --as candidate

# Say why, and let the reason travel with the mark
vike-cli backtest tag @last --note 'fee model fix'
vike-cli backtest tag @last --as baseline/momentum --note 'pre-refactor reference'
vike-cli backtest tag @last --note 'cash_gate on for the first time'

# Move a baseline you have accepted — re-pointing is the whole operation
vike-cli backtest tag @last --as baseline/momentum --note 'accepted: fee model fix'

# All three in one write
vike-cli backtest tag @last:search --add ci --as baseline/momentum \
    --note 'fee model fix'
vike-cli backtest tag @last --add release --as prod --note 'shipped 2026-02-01'
vike-cli backtest tag --help

# One command that marks a run AND records why
vike-cli backtest tag @last --as baseline/momentum --note 'fee model fix'
```

<Callout type="info" title="Three writes, three homes — and none of them happen by default">
  `--add` pushes labels into the
  run's own `meta.json` sidecar. `--as` writes a MARK into a file that is a *sibling* of the runs root,
  not inside the run — which is exactly why a mark can outlive the run directory and why `gate --against @baseline/<name>` keeps working after the id is forgotten. `--note` is APPENDED, never
  replacing what is there.
</Callout>

<Callout type="info" title="With --as, the note is deliberately written twice">
  The same text goes into the run's sidecar
  *and* into the mark. That is not a bug to tidy: the reason has to travel with the pointer, because
  the pointer is what a pipeline names six months later.
</Callout>

<Callout type="warn" title="A mark name becomes a file path on every platform this ships to">
  So it is validated at parse
  time rather than at write time. Keep to the `baseline/momentum` shape — a name with an empty
  segment, leading or trailing whitespace, or a path escape is refused before anything is written.
</Callout>

<Callout type="warn" title="--add is the only repeatable flag in the whole reading loop">
  Every other value-taking flag
  here silently last-wins, so writing `--as` twice keeps the second and writing `--note` twice keeps
  the second — while `--add ci --add fee-fix` genuinely means two labels.
</Callout>

| flag          | sample              | scope | what it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------- | ------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--add TAG`   | `ci`                | any   | `tag` only, and THE ONLY REPEATABLE FLAG IN THE READING FLAG LOOP — `--add ci --add fee-fix` is two labels, pushed onto `ReadArgs::add`. Writes into the run's own META\_FILE (meta.json) sidecar via `vike_model::runs::add_tags`.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `--as NAME`   | `baseline/momentum` | any   | `tag` only. Sets a MARK — the stable second operand `gate --against` takes — in a file that is a SIBLING of the runs root (`vike_model::state_path::MARKS_SUBDIR`). Validated at PARSE time by `vike_model::runs::valid_mark_name`, whose message is prefixed with `--as `.                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `--help`      | —                   | any   | `-h` or `--help`, matched inside the shared reading flag loop. Also FALLS THROUGH — no refusal array names it. It short-circuits through the Err channel with `args::HELP_SENTINEL` ("help requested"), which `args::exit_for_parse_error` turns back into the USAGE on stdout and exit 0.                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--json`      | —                   | any   | Print a machine-readable document instead of the human rendering. On `run` that is the server's report JSON verbatim (and on --local it is forwarded to the spawned engine); each reading verb emits its own — `gate`'s carries the verdict, one object per criterion, and `available_keys` when a criterion went unevaluated. ⚠ ACCEPTED on `path` and read nowhere: that verb prints one line so `$(…)` works and has no document form, so the flag is inert there rather than refused. On `script-check` the document is the VERDICT (`ok`, `error`, `script`, `params`) and the rung is beside it; on `templates` it is the starter roster, one starter, or the path a starter was saved to. |
| `--note TEXT` | `fee model fix`     | any   | `tag` only. APPENDED, never replacing. ⚠ When `--as` is also given the SAME note is written TWICE on disk — into the run's sidecar and into the mark — deliberately, so the reason travels with the pointer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

**The ways to name a run** — `<run-id>`, `<unique-prefix>`, `@last`, `@last:<kind>`, `@<mark>`.

**Parses, then refuses:** `--attribution`, `--breakdown`, `--drawdowns` reach this sub-verb and are turned down by name — see [Accepted nowhere yet](#accepted-nowhere-yet) for what each one is waiting on.

### `backtest diff` [#backtest-diff]

`vike-cli backtest diff <run-a> <run-b> [--all|--changed-only] [--trades] [--md]`

Sets two stored runs side by side and reports the leaves that differ — **inputs beside outputs**,
which is the question a metrics table cannot answer: a fee change and a signal change look identical
in the numbers. Both selectors are required, and either can be any of the five forms.

```sh
# Name two stored runs — full id, unique prefix, @last, @last:<kind> or @<mark>
vike-cli backtest diff 1789213143-8821-01 1789213    # full id vs a unique prefix
vike-cli backtest diff @last @baseline/momentum      # newest run vs a tagged mark
vike-cli backtest diff @last:search @last            # @last:<kind> narrows by kind
vike-cli backtest diff @candidate @baseline/momentum # a mark on both sides

# Did the number move because the strategy changed, or because the inputs did?
vike-cli backtest diff @baseline/momentum @last --changed-only
vike-cli backtest diff @baseline/momentum @last --all

# Choose what the comparison holds
vike-cli backtest diff @last @baseline/momentum --all           # unchanged leaves too
vike-cli backtest diff @last @baseline/momentum --trades        # a third section
vike-cli backtest diff @last @baseline/momentum --trades --all

# Render it for a pull request — --md is this verb's answer to --json
vike-cli backtest diff @last @baseline/momentum --md
vike-cli backtest diff @last @baseline/momentum --md --trades --all
vike-cli backtest diff @last @baseline/momentum --md > diff.md

# In CI, beside the gate: the gate decides, this says what to look at
vike-cli backtest diff @last @baseline/momentum --md --changed-only
vike-cli backtest diff @last:search @baseline/momentum --md --changed-only
vike-cli backtest diff --help

# Narrow the comparison to what actually moved
vike-cli backtest diff @last @baseline/momentum --changed-only   # only the leaves that differ
```

<Callout type="warn" title="--changed-only changes nothing — it is accepted and then ignored">
  The parser sets it and
  nothing in `run_diff` reads it, because changed-only is already the default. It exists purely so an
  explicit script is not refused for saying what the verb was going to do anyway. `--all` is the flag
  that actually moves anything, by adding the unchanged leaves back.
</Callout>

<Callout type="info" title="There is no --json here, and --out is refused">
  This verb prints one clean stream, so the
  shell's `>` already does the job — which is the stated reason `--out` is excluded from `diff` and
  `gate` while `ls` and `show` own it. Use `--md` for a table a pull request can render.
</Callout>

<Callout type="info" title="--trades is shared with show, and means something different in each">
  On `show&#x60; it renders
  the stored trade ledger as a section; here it adds a THIRD comparison section over both runs'
  ledgers. It is deliberately kept out of both sub-verbs' exclusive rosters so that the other six can
  refuse it by name — &#x2A;"it names the stored trade ledger, which `show` renders and `diff` compares"* —
  rather than answering `unknown option`.
</Callout>

| flag             | sample | scope | what it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ---------------- | ------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--all`          | —      | any   | `diff` only. Shows UNCHANGED leaves too — the negation of the default. Read by `run_diff` as `show_all` and passed to all three renderers (human/md/json).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--changed-only` | —      | any   | `diff` only, and a deliberate NO-OP: `ReadArgs::changed_only` is set by the parser and read by NOTHING in run\_diff. It is accepted purely so an explicit script is not refused.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `--help`         | —      | any   | `-h` or `--help`, matched inside the shared reading flag loop. Also FALLS THROUGH — no refusal array names it. It short-circuits through the Err channel with `args::HELP_SENTINEL` ("help requested"), which `args::exit_for_parse_error` turns back into the USAGE on stdout and exit 0.                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--json`         | —      | any   | Print a machine-readable document instead of the human rendering. On `run` that is the server's report JSON verbatim (and on --local it is forwarded to the spawned engine); each reading verb emits its own — `gate`'s carries the verdict, one object per criterion, and `available_keys` when a criterion went unevaluated. ⚠ ACCEPTED on `path` and read nowhere: that verb prints one line so `$(…)` works and has no document form, so the flag is inert there rather than refused. On `script-check` the document is the VERDICT (`ok`, `error`, `script`, `params`) and the rung is beside it; on `templates` it is the starter roster, one starter, or the path a starter was saved to. |
| `--md`           | —      | any   | `diff` only. Renders the same rows as a Markdown table. ⚠ `--json` WINS over it — run\_diff tests `a.json` first, so `--json --md` emits JSON.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `--trades`       | —      | any   | THE OTHER DOUBLE-OWNED FLAG. Owners: `show` (renders trades.json as a section) and `diff` (adds a third diff section over both runs' trades.json). Deliberately kept OUT of both the `show_only` and `diff_only` rosters and refused on the remaining six by its own named rule with its own sentence.                                                                                                                                                                                                                                                                                                                                                                                           |

**The ways to name a run** — `<run-id>`, `<unique-prefix>`, `@last`, `@last:<kind>`, `@<mark>`.

**Parses, then refuses:** `--attribution`, `--breakdown`, `--drawdowns` reach this sub-verb and are turned down by name — see [Accepted nowhere yet](#accepted-nowhere-yet) for what each one is waiting on.

### `backtest gate` [#backtest-gate]

`vike-cli backtest gate <selector> --against <selector> --fail-if EXPR`

Compares one stored run against a baseline and turns the comparison into an **exit code**. It needs
three things and refuses without any of them — a run selector, `--against` naming the baseline, and
`--fail-if` carrying the criteria — because every criterion is measured *relative* to that baseline
and this grammar has no absolute form.

```sh
# The shape: a stored run, a baseline, and the criteria that judge them
vike-cli backtest gate @last --against @baseline/momentum \
    --fail-if 'sharpe:-5%'                  # exit 0 clean, exit 6 Breach
vike-cli backtest gate 1789213143-8821-01 --against @baseline/momentum \
    --fail-if 'sharpe:-5%,max_dd:+10%'      # ONE comma list — a 2nd --fail-if replaces

# Several criteria, one comma list — name each metric once
vike-cli backtest gate @last --against @baseline/momentum \
    --fail-if 'sharpe:-5%,max_dd:+10%,return:-10%'
vike-cli backtest gate @last --against @baseline/momentum --fail-if 'equity:-2%'
vike-cli backtest gate @last --against @baseline/momentum --fail-if 'max_dd:+5%'

# Naming the two runs — any selector form works on either side
vike-cli backtest gate @last:search --against @baseline/momentum \
    --fail-if 'sharpe:-5%'                  # @last:<kind> — the last run of that kind
vike-cli backtest gate 1789213 --against 1789213143-8821-01 \
    --fail-if 'max_dd:+10%'                 # a unique prefix, judged against a full id
vike-cli backtest gate @baseline/candidate --against @baseline/momentum \
    --fail-if 'sharpe:-5%'                  # a mark on both sides

# Either value form works — the split is on the FIRST '=' only
vike-cli backtest gate @last --against=@baseline/momentum --fail-if='sharpe:-5%'
vike-cli backtest gate --help               # USAGE on stdout, exit 0
```

**Defend a result in CI.** Set the baseline once by hand; everything after is the pipeline.

```sh
# once, on the run you want to defend
vike-cli backtest tag @last --as baseline/momentum --note 'pre-refactor reference'

# on every change
vike-cli backtest run --profile profiles/momentum_btc.toml --json
vike-cli backtest gate @last --against @baseline/momentum --fail-if 'sharpe:-5%'

# gate a search instead of a single run — @last:search needs no id
vike-cli backtest run --profile profiles/grid.toml --optimizer tpe --trials 200 --seed 7
vike-cli backtest gate @last:search --against @baseline/momentum \
    --fail-if 'sharpe:-5%,max_dd:+10%'

# accepted the new number? re-point the mark — nothing is copied
vike-cli backtest tag @last --as baseline/momentum --note 'accepted: fee model fix'
```

**The whole CI step, branching on the CODE rather than on "non-zero".** That is what makes the gate
a gate: three of the codes below mean a BROKEN GATE rather than a failing strategy, and a step that
fails the build on all of them teaches the team to ignore it.

```sh
# the run, with its report kept as an artifact — `--json` is `run`'s flag, not `gate`'s
set -u
vike-cli backtest run --profile profiles/momentum_btc.toml --json > run.json

# the verdict IS the exit code; the criteria it judged are on stdout
vike-cli backtest gate @last --against @baseline/momentum \
    --fail-if 'sharpe:-5%,max_dd:+10%' | tee verdict.txt
rc=${PIPESTATUS[0]}

case "$rc" in
  0) echo "within tolerance" ;;
  6) echo "REGRESSION — the verdict names every criterion:"; cat verdict.txt; exit 1 ;;
  7) echo "NOTHING WAS EVALUATED — an empty slice, or no coverage for the window."
     echo "A DATA problem, not a strategy regression. Do not fail the build on it."; exit 0 ;;
  3) echo "compute daemon unreachable — retry"; exit 75 ;;   # EX_TEMPFAIL
  *) echo "the gate itself failed (rc=$rc)"; exit 1 ;;
esac

# a reviewable comment, from the same two stored runs — `--md` is `diff`'s flag
vike-cli backtest diff @last @baseline/momentum --md >> "$GITHUB_STEP_SUMMARY"
```

<Callout type="warn" title="gate has no --json, so capture its stdout — and read the status past the pipe">
  `--json` is accepted on `run` alone. A pipeline expecting a machine-readable verdict FILE from
  `gate` is written against a flag that does not exist, and will be refused by name. Pipe stdout
  instead, and take `${PIPESTATUS[0]}`: a plain `$?` after a pipe is `tee`'s status, which is 0 even
  on a breach — a gate that can only pass.
</Callout>

<Callout type="error" title="Three required inputs, all refused before any run is opened">
  Omit the baseline and the refusal
  hands you the recipe rather than a complaint: make one with `backtest tag <run> --as
  baseline/<name>`, then point `--against @baseline/<name>` at it. Omit the criteria and you are told
  the shape — a METRIC, a colon, a SIGN saying which direction is bad, the tolerance, and an optional
  `%`. A blank or whitespace `--against` counts as absent, not as an empty baseline.
</Callout>

**`--fail-if` — the grammar, in full.** Get this wrong and the merge gate is decoration, so it is
worth the two minutes:

```text
EXPR      := CRITERION (',' CRITERION)*
CRITERION := METRIC ':' SIGN NUMBER ['%']
SIGN      := '+' | '-'

--fail-if 'sharpe:-5%'                  # fail if Sharpe falls more than 5% below baseline
--fail-if 'sharpe:-5%,max_dd:+10%'      # both — one flag, one comma list
--fail-if 'sharpe:-0.2'                 # no '%' — an ABSOLUTE amount, in the metric's own units
```

The sign says which direction is BAD and the number is the TOLERANCE, never a threshold. There is
no absolute-threshold form and no `OR`.

<Callout type="error" title="The sign is not optional, and it is not the direction of the change">
  `-` fails on a FALL and
  `+` fails on a RISE; the number is the MAGNITUDE. So `sharpe:-5%` means &#x2A;fail if Sharpe drops more
  than 5%*, and `sharpe:--5%` is refused outright — the tolerance cannot be negative, because the
  direction is the sign's job. `%&#x60; makes the tolerance a share of the baseline's absolute value;
  without it, it is an absolute amount. There is no absolute-threshold form at all: for &#x2A;"Sharpe must
  exceed 1.2"*, pipe `backtest show <run> --json` through `jq` instead.
</Callout>

<Callout type="warn" title="A metric is resolved against the report, not against a roster — so a typo is not an error">
  Three aliases resolve first, case-sensitively: `max_dd → max_drawdown`, `return → total_return`,
  `equity → final_equity`. Every other name is kept verbatim and used as a key of `report.json`, which
  means the metric set is **open** — any key the report has, or gains later, is accepted. The
  consequence worth knowing: a misspelled metric does not fail the parse. When neither side carries a
  finite number under that key the criterion comes back *Unevaluated*, which is not a pass you can
  trust. Two criteria resolving to the same key are refused, alias pairs included
  (`max_dd:+5%,max_drawdown:+10%`), because a silently-dropped criterion is a gate checking something
  other than what it was handed.
</Callout>

<Callout type="error" title="Only exit 6 means &#x22;regression&#x22;">
  The ladder is `0 Ok, 1 Failed, 2 Usage, 3 Connect, 4 Refused,
  5 Venue, 6 Breach, 7 Empty`. A breach is 6; a run or baseline that will not resolve is 1 or 7; a
  malformed flag is 2. **A CI step branching on "non-zero" therefore reports a deleted mark, an empty
  store and a typo'd expression as a failing strategy** — branch on 6 specifically and treat the rest
  as a broken gate, not as a result.
</Callout>

| flag               | sample                   | scope | what it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------ | ------------------------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--against <mark>` | `@baseline/momentum`     | any   | `gate` only, and REQUIRED. A blank/whitespace value counts as absent. It is the baseline every criterion is relative to; a baseline that will not resolve is `Exit::Failed`/`Exit::Empty`, never `Exit::Breach`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `--fail-if EXPR`   | `sharpe:-5%,max_dd:+10%` | any   | `gate` only, and REQUIRED. Grammar: EXPR := CRITERION (',' CRITERION)\* ; CRITERION := METRIC ':' SIGN NUMBER \['%'] ; SIGN := '+' \| '-'. The sign says which direction is BAD and is REQUIRED; '%' makes the tolerance a share of \|baseline\|. RELATIVE only — there is no absolute form. Parsed TWICE: once by `refuse_an_ungateable_line` (before any directory is opened) and again in `run_gate`.                                                                                                                                                                                                                                                                                         |
| `--help`           | —                        | any   | `-h` or `--help`, matched inside the shared reading flag loop. Also FALLS THROUGH — no refusal array names it. It short-circuits through the Err channel with `args::HELP_SENTINEL` ("help requested"), which `args::exit_for_parse_error` turns back into the USAGE on stdout and exit 0.                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--json`           | —                        | any   | Print a machine-readable document instead of the human rendering. On `run` that is the server's report JSON verbatim (and on --local it is forwarded to the spawned engine); each reading verb emits its own — `gate`'s carries the verdict, one object per criterion, and `available_keys` when a criterion went unevaluated. ⚠ ACCEPTED on `path` and read nowhere: that verb prints one line so `$(…)` works and has no document form, so the flag is inert there rather than refused. On `script-check` the document is the VERDICT (`ok`, `error`, `script`, `params`) and the rung is beside it; on `templates` it is the starter roster, one starter, or the path a starter was saved to. |

**The ways to name a run** — `<run-id>`, `<unique-prefix>`, `@last`, `@last:<kind>`, `@<mark>`.

⚠ OPEN — there is NO metric roster. parse\_one resolves a metric against METRIC\_ALIASES and otherwise keeps the spelling verbatim as the JSON key, so ANY key of report.json (and any key it gains later) is accepted. An unknown metric is NOT a parse error.

**Aliases those metrics also answer to** — `max_dd -> max_drawdown`, `return -> total_return`, `equity -> final_equity`.

**Parses, then refuses:** `--attribution`, `--breakdown`, `--drawdowns` reach this sub-verb and are turned down by name — see [Accepted nowhere yet](#accepted-nowhere-yet) for what each one is waiting on.

### `backtest params` [#backtest-params]

`vike-cli backtest params (--strategy NAME | --script <s.rhai>)`

Lists the tunable knobs a strategy declares, from exactly one source — a registry name or a `.rhai`
file. It is **offline**: it reads the script or the strategy roster on this machine and lists its
knobs, with no server, no store and no engine. Worth running before you write a profile, because a
typo'd knob name in `[strategy.params]` is a silent no-op rather than a refusal.

```sh
# A built-in strategy: name it, get its knobs
vike-cli backtest params --strategy buy_hold
vike-cli backtest params --strategy momentum
vike-cli backtest params --strategy spread_maker
vike-cli backtest params --strategy=buy_hold      # --flag=value is the same flag

# A .rhai script: the knobs the file itself declares — it is read and COMPILED
vike-cli backtest params --script s.rhai
vike-cli backtest params --script strategies/momentum.rhai

# The usage text
vike-cli backtest params --help
```

<Callout type="error" title="One source, named exactly once">
  `--strategy` and `--script` answer the same question from two
  places, so naming both is the refusal — give one. Unlike on `run`, `--strategy` here **is** checked:
  a name no roster carries is turned down with the roster printed, because this verb's whole product
  is the knob list and there is no far side to decide it later.
</Callout>

<Callout type="warn" title="[strategy.params] is untyped, which is why this verb matters">
  The table is an untyped TOML
  value on both sides of the wire, so no schema validation is possible anywhere: a misspelled knob is
  accepted, ignored, and the strategy runs with the default you meant to change. The names this prints
  are the only ones `--param` actually reaches.
</Callout>

<Callout type="info" title="23 run flags are refused here by name, and two are not">
  `--strategy` and `--script` belong
  to both verbs. Every other sugar flag — `--profile`, `--preset`, `--set`, `--venue`, `--cash` and
  the rest — is refused with a sentence saying this verb reads the script or the roster and lists its
  knobs, rather than with a bare `unknown option`. That named refusal is deliberate: these are the
  flags somebody would most plausibly try here.
</Callout>

| flag                | sample     | scope | what it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------- | ---------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--help`            | —          | any   | `-h` or `--help`, matched inside the shared reading flag loop. Also FALLS THROUGH — no refusal array names it. It short-circuits through the Err channel with `args::HELP_SENTINEL` ("help requested"), which `args::exit_for_parse_error` turns back into the USAGE on stdout and exit 0.                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--json`            | —          | any   | Print a machine-readable document instead of the human rendering. On `run` that is the server's report JSON verbatim (and on --local it is forwarded to the spawned engine); each reading verb emits its own — `gate`'s carries the verdict, one object per criterion, and `available_keys` when a criterion went unevaluated. ⚠ ACCEPTED on `path` and read nowhere: that verb prints one line so `$(…)` works and has no document form, so the flag is inert there rather than refused. On `script-check` the document is the VERDICT (`ok`, `error`, `script`, `params`) and the rung is beside it; on `templates` it is the starter roster, one starter, or the path a starter was saved to. |
| `--script <s.rhai>` | `s.rhai`   | any   | Injects the .rhai file's source into strategy.params.src (overwriting any existing src) and implies strategy.name=rhai. On the `params` sub-verb the same spelling names the script whose knobs are listed, and on `script-check` the script to COMPILE — three owners, one meaning: a .rhai file on this machine.                                                                                                                                                                                                                                                                                                                                                                               |
| `--strategy NAME`   | `buy_hold` | any   | Sugar for strategy.name, forwarded UNVALIDATED (the roster lives in vike-backtest and includes user strategies this crate cannot see). On the `params` sub-verb the same spelling names the roster entry whose knobs are listed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

**2 flags of this plane are refused here by name** — each answers with a sentence naming the sub-verb that owns it, never a bare `unknown option`. They are listed in full under [Refusals](#refusals).

**The strategies `--strategy` knows here** — `buy_hold`, `grid`, `dca_accumulate`, `spread_maker`, `gueant_maker`, `trailing_scalper`, `momentum`, `funding_carry`, `funding_capture`, `pairs_zscore`, `rotation_top_k`, `bracket_per_symbol`, `gated_weights`, `caps_sizers_mask`, `tick_pair_mse`, `cheap_catch_updown_fair_value`, `sport_copy_follower`, `rhai`.

**Parses, then refuses:** `--attribution`, `--breakdown`, `--drawdowns` reach this sub-verb and are turned down by name — see [Accepted nowhere yet](#accepted-nowhere-yet) for what each one is waiting on.

### `backtest strategies` [#backtest-strategies]

`vike-cli backtest strategies`

Prints the roster of built-in strategies to stdout, one per line, and takes no flag but `--help`.
That is the whole surface — there is deliberately no filter, no format and no output flag, because
plain lines are what the shell already knows how to narrow.

```sh
# Print the roster — plain lines, so the shell does the rest
vike-cli backtest strategies                   # the built-in names, nothing else
vike-cli backtest strategies > strategies.txt  # the shell redirects; there is no --out
vike-cli backtest strategies | grep -i maker
vike-cli backtest strategies | grep -i funding
vike-cli backtest strategies | wc -l           # how many there are

# Confirm a name before you spell it in a profile
vike-cli backtest strategies | grep -x buy_hold
vike-cli backtest strategies | grep -x momentum
vike-cli backtest strategies | grep -x rhai    # the name implied when --script is given

# The workflow this verb starts — read the knobs next with `params --strategy <name>`
vike-cli backtest strategies | grep -i momentum
vike-cli backtest strategies | grep -iE 'maker|carry'

# Read the usage instead of the roster
vike-cli backtest strategies --help            # the USAGE, on stdout, exit 0
vike-cli backtest strategies --help | head -20 # stdout, so head and a pager both work
```

<Callout type="warn" title="Confirming a name here is worth the extra command">
  `run` will not do it for you:
  `--strategy` is forwarded **unvalidated** — the roster lives in the engine and includes user
  strategies this binary cannot see — so a bad name is decided far-side, after the profile has already
  been shipped. On `params` the same spelling *is* checked. That asymmetry is why this verb exists.
</Callout>

<Callout type="warn" title="The list is this binary's, not the engine's">
  It prints what is compiled in here; a compute
  server can carry user strategies this roster has never heard of, and those names work on `run`
  despite being absent from this output. An empty or missing name here is not proof the far side will
  refuse it — and a name that *is* here is not proof a given server has it.
</Callout>

<Callout type="info" title="--help is the entire flag surface">
  Every other flag of the plane is refused by name, the three
  unbuilt renderers included, so a pasted line from another sub-verb tells you where the flag actually
  lives rather than answering `unknown option`. (It was four until `--html` shipped.)
</Callout>

| flag               | sample           | scope    | what it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------ | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--addr host:port` | `127.0.0.1:7880` | `remote` | The COMPUTE daemon to dial (vike-backend backtest --addr, NOT the datahub). Refused beside --local; unwritten, it falls through config.backtest\_addr to 127.0.0.1:7880.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `--help`           | —                | any      | `-h` or `--help`, matched inside the shared reading flag loop. Also FALLS THROUGH — no refusal array names it. It short-circuits through the Err channel with `args::HELP_SENTINEL` ("help requested"), which `args::exit_for_parse_error` turns back into the USAGE on stdout and exit 0.                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--json`           | —                | any      | Print a machine-readable document instead of the human rendering. On `run` that is the server's report JSON verbatim (and on --local it is forwarded to the spawned engine); each reading verb emits its own — `gate`'s carries the verdict, one object per criterion, and `available_keys` when a criterion went unevaluated. ⚠ ACCEPTED on `path` and read nowhere: that verb prints one line so `$(…)` works and has no document form, so the flag is inert there rather than refused. On `script-check` the document is the VERDICT (`ok`, `error`, `script`, `params`) and the rung is beside it; on `templates` it is the starter roster, one starter, or the path a starter was saved to. |

**Parses, then refuses:** `--attribution`, `--breakdown`, `--drawdowns` reach this sub-verb and are turned down by name — see [Accepted nowhere yet](#accepted-nowhere-yet) for what each one is waiting on.

### `backtest templates` [#backtest-templates]

`vike-cli backtest templates [ID] [--write-strategy <s.rhai>]`

The starter Rhai strategies this binary **ships** — listed, printed, or saved to a new file. It is
OFFLINE in the strongest sense available here: the answer comes from consts compiled into this
binary, so there is no server, no store, no engine and no run directory. The positional is the
selector and it is optional — absent lists the roster, present prints that one, and a second
positional is a usage error rather than a filter.

```sh
# The roster — no argument, so it lists
vike-cli backtest templates
vike-cli backtest templates --json          # the same roster, as a document

# One template, printed to stdout
vike-cli backtest templates sma-cross
vike-cli backtest templates sma-cross --json

# Start a strategy FROM one — the file is created, never overwritten
vike-cli backtest templates sma-cross --write-strategy strategies/my-cross.rhai
vike-cli backtest templates sma-cross --write-strategy s.rhai

# Confirm a selector before you save with it
vike-cli backtest templates | grep -i cross
vike-cli backtest templates | wc -l         # how many ship

# The usage text
vike-cli backtest templates --help
```

<Callout type="warn" title="--write-strategy creates; it will not overwrite">
  This is the one member of the authoring family that writes a file, and it refuses an existing path
  rather than replacing it. That is deliberate: the argument is a path you are about to edit, and a
  silent overwrite of a strategy somebody has already changed is the one mistake this verb could make
  that no diff would show. Point it at a new name, or move the old file first.
</Callout>

<Callout type="info" title="Printing a template is not compiling it">
  The roster and the printed body are consts. Nothing is parsed on the way out, so a template that
  prints is not thereby a template that compiles in your tree. `script-check` is the verb that answers
  that, and it is the natural next command after a `--write-strategy` — as `params` is for reading
  back the knobs the saved file declares.
</Callout>

<Callout type="warn" title="Two neighbouring flags are refused here by name">
  `--script` belongs to `script-check` and `--out` to the reading verbs; typing either here is refused
  with a message that names the sub-verb that owns it rather than `unknown option`. The selector is a
  POSITIONAL, so there is no `--template` either.
</Callout>

| flag                        | sample   | scope | what it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| --------------------------- | -------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--json`                    | —        | any   | Print a machine-readable document instead of the human rendering. On `run` that is the server's report JSON verbatim (and on --local it is forwarded to the spawned engine); each reading verb emits its own — `gate`'s carries the verdict, one object per criterion, and `available_keys` when a criterion went unevaluated. ⚠ ACCEPTED on `path` and read nowhere: that verb prints one line so `$(…)` works and has no document form, so the flag is inert there rather than refused. On `script-check` the document is the VERDICT (`ok`, `error`, `script`, `params`) and the rung is beside it; on `templates` it is the starter roster, one starter, or the path a starter was saved to. |
| `--write-strategy <s.rhai>` | `s.rhai` | any   | `templates` only. Saves the named starter to a file that does NOT exist yet — a `--write-profile`-shaped rule, and the reason this is not `--out`: that flag overwrites, and the file this one writes is a strategy somebody then edits, so clobbering it from a flag typo is unrecoverable. It needs a starter id: given alone it is a usage refusal rather than a roster listing, because a listing plus exit 0 reads exactly like a write that happened.                                                                                                                                                                                                                                      |

**Parses, then refuses:** `--attribution`, `--breakdown`, `--drawdowns` reach this sub-verb and are turned down by name — see [Accepted nowhere yet](#accepted-nowhere-yet) for what each one is waiting on.

### `backtest script-api` [#backtest-script-api]

`vike-cli backtest script-api`

Everything an authored Rhai strategy may **call**: the reads, the order verbs, the `param()` knob,
the indicator spellings, and the hooks to put them in. It takes no positional and no input file — it
describes the HOST, not a script — and it is OFFLINE: the answer is derived from the host's own
registration compiled into this binary, so it needs no server, no store and no engine.

```sh
# The whole callable surface
vike-cli backtest script-api
vike-cli backtest script-api --json         # the same surface, as a document

# Settle a spelling before you type it into a strategy
vike-cli backtest script-api | grep -i rsi
vike-cli backtest script-api | grep -i atr
vike-cli backtest script-api | grep -iE 'buy|sell|close'

# Which hooks exist to put the calls in
vike-cli backtest script-api | grep -i hook

# Keep the surface beside the script you are writing
vike-cli backtest script-api --json > api.json

# The usage text
vike-cli backtest script-api --help
```

<Callout type="info" title="Derived from the registration, not from a list">
  The roster is read off the host's own registration rather than a hand-kept list, which is what makes
  this the place to settle a spelling. A name this output does not carry is a name the interpreter has
  not been given — and a misspelled indicator does not fail loudly at authoring time, it errors on
  every bar until the strategy switches itself off.
</Callout>

<Callout type="warn" title="This describes the host, so it cannot see your script">
  There is deliberately no `--script` here. What a particular file DECLARES is `params`' answer and
  whether it COMPILES is `script-check`'s; this verb answers only what the host makes available to any
  script at all. The three are separate for that reason rather than by accident.
</Callout>

| flag     | sample | scope | what it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| -------- | ------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--json` | —      | any   | Print a machine-readable document instead of the human rendering. On `run` that is the server's report JSON verbatim (and on --local it is forwarded to the spawned engine); each reading verb emits its own — `gate`'s carries the verdict, one object per criterion, and `available_keys` when a criterion went unevaluated. ⚠ ACCEPTED on `path` and read nowhere: that verb prints one line so `$(…)` works and has no document form, so the flag is inert there rather than refused. On `script-check` the document is the VERDICT (`ok`, `error`, `script`, `params`) and the rung is beside it; on `templates` it is the starter roster, one starter, or the path a starter was saved to. |

**Parses, then refuses:** `--attribution`, `--breakdown`, `--drawdowns` reach this sub-verb and are turned down by name — see [Accepted nowhere yet](#accepted-nowhere-yet) for what each one is waiting on.

### `backtest script-check` [#backtest-script-check]

`vike-cli backtest script-check --script <s.rhai>`

Compiles one Rhai script offline and answers **twice** — the diagnostic on stdout and a verdict in
the exit code. It is built for a save hook or a pre-commit, which is why the number matters as much
as the text: no server, no store, no engine, and nothing written anywhere.

```sh
# Compile one file
vike-cli backtest script-check --script s.rhai
vike-cli backtest script-check --script strategies/my-cross.rhai
vike-cli backtest script-check --script=s.rhai       # --flag=value is the same flag

# The document form, for a hook that reports rather than prints
vike-cli backtest script-check --script s.rhai --json

# In a save hook: the exit code is the verdict, the text is the reason
vike-cli backtest script-check --script s.rhai || echo 'blocked: it does not compile'

# The usage text
vike-cli backtest script-check --help
```

A script that compiles prints `ok: <path> compiles (N param() knob(s))` and exits **0**. One that
does not prints `error: <path> does not compile`, then the compiler's own diagnostic in full, and
exits **1** — the diagnostic is on stdout either way, so a hook can capture it without merging
streams.

<Callout type="warn" title="Three outcomes, and only two are about your script">
  Exit **0** and exit **1** are verdicts: the file was read and compiled, or read and rejected. Exit
  **2** is not — it means the command line was wrong, and the case you will actually hit is omitting
  `--script`, which is refused with a sentence naming the flag. A wrapper that treats every non-zero
  as "the strategy is broken" reports a typo in its own invocation as a failing strategy.
</Callout>

<Callout type="warn" title="An unreadable file is not a verdict either">
  A path that cannot be opened fails with `cannot read script <path>` rather than a compile
  diagnostic, because nothing was compiled and there is nothing to diagnose. Check the path exists
  first — a hook that reads a missing file as a broken script blocks a commit for a reason that is not
  in the commit.
</Callout>

<Callout type="info" title="Compiling is not the same as declaring">
  This verb answers whether the interpreter accepts the file. What knobs it DECLARES is `params`'
  answer, and the two disagree usefully: a script can compile cleanly and still declare nothing, which
  is what a missing `param()` looks like from the outside. `templates --write-strategy` is where a
  file worth checking usually comes from.
</Callout>

| flag                | sample   | scope | what it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------- | -------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--json`            | —        | any   | Print a machine-readable document instead of the human rendering. On `run` that is the server's report JSON verbatim (and on --local it is forwarded to the spawned engine); each reading verb emits its own — `gate`'s carries the verdict, one object per criterion, and `available_keys` when a criterion went unevaluated. ⚠ ACCEPTED on `path` and read nowhere: that verb prints one line so `$(…)` works and has no document form, so the flag is inert there rather than refused. On `script-check` the document is the VERDICT (`ok`, `error`, `script`, `params`) and the rung is beside it; on `templates` it is the starter roster, one starter, or the path a starter was saved to. |
| `--script <s.rhai>` | `s.rhai` | any   | Injects the .rhai file's source into strategy.params.src (overwriting any existing src) and implies strategy.name=rhai. On the `params` sub-verb the same spelling names the script whose knobs are listed, and on `script-check` the script to COMPILE — three owners, one meaning: a .rhai file on this machine.                                                                                                                                                                                                                                                                                                                                                                               |

**Parses, then refuses:** `--attribution`, `--breakdown`, `--drawdowns` reach this sub-verb and are turned down by name — see [Accepted nowhere yet](#accepted-nowhere-yet) for what each one is waiting on.

## Running it somewhere else [#running-it-somewhere-else]

### Reaching a daemon that is not on this machine [#reaching-a-daemon-that-is-not-on-this-machine]

The compute daemon binds **loopback only** by default, and that is a refusal rather than a
preference: the control handshake is plaintext, so a non-loopback bind is refused outright unless
`VIKE_DATAHUB_ALLOW_PUBLIC_BIND=1` is set on the daemon's own box, and even then it requires a node
key. Setting the variable on your side does nothing.

So the sanctioned way to reach a remote daemon is a tunnel, not a wider bind:

```sh
ssh -N -L 7880:127.0.0.1:7880 user@the-box   # in another shell, or -f to background
vike-cli backtest run --profile p.toml       # --addr now needs no change
```

⚠ &#x2A;*Set a file log level before any long run.** The JSON file log defaults to `trace` and is *not*
affected by console log settings. One hour of a chatty batch job has measured 6.4 GB, and a long
range once wrote enough to nearly fill the disk of a box hosting live trading. Export
`VIKE_LOG_FILE_LEVEL=warn` — or `off` — for any long search or walk-forward.

## The profile [#the-profile]

You never have to write one by hand: build a command line you like, then `--write-profile` it.
Two optional tables change what *kind* of run it is — a non-empty `[paramscan]` makes it a search,
a `[walkforward]` table makes it a walk-forward, and a profile declaring both composes.

**Every table, key, default, accepted value and refusal has its own generated page:
[`backtest --profile`](/docs/trader/reference/cli/research/backtest-profile).** It is rendered from the Rust
types that declare the schema — walk-forward's nine keys and its two window forms, the eight sizer
kinds and the knob each requires, and the sixty-odd refusals verbatim — so it cannot fall behind
them. This page stays the COMMAND surface; two properties of the file are worth carrying here,
because they change how you use the flags above.

**`--set <dotted key>=<value>` reaches every key of every table**, not just the ones with a flag of
their own, and the schema is **closed** — an undeclared field is a hard load error, so **a typo is
refused, never a silent no-op**. That is what makes the flag safe to paste from anywhere.

⚠ &#x2A;*A default run is frictionless — know what is off.** Cash admission (`engine.cash_gate`), margin
and liquidation (`engine.maint_margin`, `engine.liq_buffer`), and the volume-participation cap
(`engine.volume_limit`) are all **off** unless you turn them on. So a default run can spend money it
does not have and fill size the market could not absorb. Turn them on before you believe a number,
and use `--show-effective` to confirm what actually resolved.

## The whole surface [#the-whole-surface]

Everything the exported surface carries, in full. Nothing above needs this section to be read —
it is here so a question about one flag always has an answer.

### Defaults, and who decides them [#defaults-and-who-decides-them]

22 flags carry a default. Where it is decided differs — a FAR SIDE value cannot be shown before you run.

### implied by the parser when the flag is absent [#implied-by-the-parser-when-the-flag-is-absent]

| flag         | default                                                                                                                                                                       | conditional on       | why                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--addr`     | `127.0.0.1:7880`                                                                                                                                                              | —                    | `resolve_addr(cli, configured)` folds three rungs and falls through to `vike_config::DEFAULT_BACKTEST_ADDR`. The FLAG layer performs no host:port check at all (a blank value is treated as absent, and dialling anything else produces a connect-rung failure); the file and env layers do check, via `vike_config`'s `check_addr` / `check_env_addr`.                                |
| `--cols`     | `run_id,kind,started_at,report`                                                                                                                                               | —                    | `ls::DEFAULT_COLS` — manifest-only, so a bare `ls` opens no report.json at all.                                                                                                                                                                                                                                                                                                        |
| `--engine`   | `<project>/bin/backtest[EXE] → <exe_dir>/backtest[EXE] → <project>/bin/vike[EXE] with lead arg backtest → <exe_dir>/vike[EXE] with lead arg backtest → bare backtest on PATH` | —                    | `crate::cmd::engine`'s `locate(explicit, project_root)`: an explicit path short-circuits the whole ladder and is deliberately NOT probed for existence (a named path that is not there must fail with the name the operator typed), and is never treated as a multicall. Otherwise the four-rung standalone-then-multicall search runs, with bare `backtest` on PATH as the last word. |
| `--kind`     | `bar`                                                                                                                                                                         | —                    | no --kind and no profile said otherwise                                                                                                                                                                                                                                                                                                                                                |
| `--strategy` | `rhai`                                                                                                                                                                        | `--script`           | implied\_defaults pushes strategy.name = "rhai" ONLY when a script was named. With no --script the CLI supplies nothing and StrategyCfg::name carries no serde default, so the far side decides.                                                                                                                                                                                       |
| `--on-gap`   | `refuse`                                                                                                                                                                      | `--require-coverage` | An armed gate with no stated disposition refuses. The other way round — arming a gate that then runs anyway — is the shape that reads as checked while checking nothing.                                                                                                                                                                                                               |
| `--universe` | `declared`                                                                                                                                                                    | —                    | Unwritten, the symbol list is taken verbatim — byte-identical to every profile written before this key existed.                                                                                                                                                                                                                                                                        |

### the profile schema — the Rust type its field deserialises into [#the-profile-schema--the-rust-type-its-field-deserialises-into]

| flag         | default | conditional on | why                                                                                                                                                                                                                       |
| ------------ | ------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--fee`      | `0.0`   | —              | `EngineCfg::fee_rate` is `#[serde(default)] f64` in crates/vike-backtest/src/harness/profile.rs, so an absent value is 0.0. The CLI supplies nothing.                                                                     |
| `--interval` | `1d`    | —              | `DataCfg::interval` is `#[serde(default = "default_interval")]` and crates/vike-backtest/src/harness/profile.rs's default\_interval returns "1d". The CLI supplies nothing.                                               |
| `--slippage` | `0.0`   | —              | `EngineCfg::slippage` is `#[serde(default)] f64` in crates/vike-backtest/src/harness/profile.rs. The CLI supplies nothing.                                                                                                |
| `--symbol`   | `[]`    | —              | `DataCfg::symbols` is `#[serde(default)] Vec\<String>` in crates/vike-backtest/src/harness/profile.rs; empty is the schema default and the CLI supplies nothing.                                                          |
| `--venue`    | `None`  | —              | `DataCfg::venue` is `#[serde(default)] Option\<String>` in crates/vike-backtest/src/harness/profile.rs, so an absent venue is None (the cross-venue \[\[data.series]] form is the alternative). The CLI supplies nothing. |

### **the server**, not this CLI — the value is decided where the work runs [#the-server-not-this-cli--the-value-is-decided-where-the-work-runs]

| flag            | default                                                      | conditional on | why                                                                                                                                                                                                                                                                                                                                                                   |
| --------------- | ------------------------------------------------------------ | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--cash`        | —                                                            | —              | NO default is supplied by either side. `implied_defaults`'s doc states it outright: a starting balance is a modelling input with no defensible default, so an omitted `--cash` is a FAR-SIDE missing-field refusal naming `engine.cash`.                                                                                                                              |
| `--decide`      | `sequential`                                                 | —              | This crate substitutes NO default — an absent --decide writes no `engine.decide` key at all, and `decide_mode` resolves an absent key to `DecideMode::Sequential`, byte-identical to every profile written before the key existed. It is NOT an `implied_defaults` row for that reason: there is nothing the schema failed to write down.                             |
| `--euler-depth` | `3`                                                          | —              | CONFIRMED forwarded verbatim (same three sites as --trials). Default applied only under euler, by `search_select`'s `parse_euler_depth` → `EulerConfig::DEFAULT_MAX_DEPTH` = 3; the hard cap is `EulerConfig::MAX_DEPTH_CAP` = 16 and 0 is legal (coarse-grid-only).                                                                                                  |
| `--from`        | —                                                            | —              | `DataCfg::from` carries NO serde default in crates/vike-backtest/src/harness/profile.rs, so an absent value is a far-side missing-field refusal. The CLI implies nothing.                                                                                                                                                                                             |
| `--optimizer`   | `grid`                                                       | —              | This crate substitutes NO default — an absent --optimizer is forwarded as `None` on BOTH routes and the side that RUNS resolves it against `vike_datahub_client::DEFAULT_SEARCH_METHOD` ("grid"). `DEFAULT_OPTIMIZER` in vike-cli is `#[cfg(test)]`-gated and exists only to build sample argv in that file's own tests.                                              |
| `--rank-by`     | `sharpe`                                                     | —              | The CLI forwards `None` when unwritten; `search_select`'s `resolve_rank` maps `None` to `RankChoice::Metric(RankMetric::default())`, and `RankMetric`'s `#[default]` variant is `Sharpe`. Deliberately NOT part of `Args::search_requested`, so it never routes a run to the search verb by itself.                                                                   |
| `--seed`        | `0 under tpe; NO default under genetic (absence is refused)` | —              | CONFIRMED forwarded verbatim (same three sites). `search_select`'s `parse_seed` returns `Option\<u64>` and substitutes nothing; the tpe arm applies `.unwrap_or(0)` and the genetic arm calls `require_seed`, which refuses an absent seed outright.                                                                                                                  |
| `--store`       | —                                                            | —              | Unwritten, no `--store` is pushed into the child argv at all and the engine resolves its own hist-store root (`crates/vike-backtest/src/backtest_cli.rs`'s `store_root`, which also consults the caller-supplied vars). This side substitutes nothing and validates nothing about the path.                                                                           |
| `--to`          | —                                                            | —              | `DataCfg::to` carries NO serde default in crates/vike-backtest/src/harness/profile.rs. The CLI implies nothing.                                                                                                                                                                                                                                                       |
| `--trials`      | `64`                                                         | —              | CONFIRMED forwarded verbatim: `parse_run_args` stores the raw String, `execute_local` pushes `("--trials", &args.trials)` into the child argv unchanged, and `Args::wire_search` clones it into `WireSearch.trials` as a String. The default is applied only when tpe is the resolved method, by `search_select`'s `parse_trials` → `TpeConfig::DEFAULT_TRIALS` = 64. |

### Accepted nowhere yet [#accepted-nowhere-yet]

4 flags are declared and accepted by **no** sub-verb.

| flag            | refusal reaches                                                                                                | what it will do                                                                                                                                                                                                                                                                                                                                                     |
| --------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--attribution` | `ls`, `show`, `path`, `tag`, `diff`, `gate`, `params`, `strategies`, `templates`, `script-api`, `script-check` | Refused by name on any reading sub-verb: the engine computes no per-source attribution at all, so this is missing DATA rather than a missing renderer.                                                                                                                                                                                                              |
| `--breakdown`   | `ls`, `show`, `path`, `tag`, `diff`, `gate`, `params`, `strategies`, `templates`, `script-api`, `script-check` | Refused by name on any reading sub-verb, and UNCONDITIONALLY: a period breakdown needs per-bar returns, and the reason it is refused — a curve DECIMATED past the sample cap — holds only for a large run, while this guard sees argv alone and no run. `vike-cli report \<run> --breakdown day\|month` evaluates that condition per run, off the same series.json. |
| `--drawdowns`   | `ls`, `show`, `path`, `tag`, `diff`, `gate`, `params`, `strategies`, `templates`, `script-api`, `script-check` | Refused by name on any reading sub-verb, and what is missing is the WIRING rather than the renderer: `vike_analytics::periods::drawdown_table_text` is linked into this binary and nothing calls it, while the equity curve it reads is in the run record and `--export equity` hands it over today.                                                                |
| `--list-params` | `run`                                                                                                          | RETIRED. A knob discovery is now `backtest params`, not a mode flag on a run — decision 11 gives every action inside this plane exactly one spelling. Both parse levels answer this spelling with its replacement.                                                                                                                                                  |

### Refusals [#refusals]

150 refusals across 50 flags, verbatim. A name in braces is substituted at runtime.

### Given a value it will not take (130) [#given-a-value-it-will-not-take-130]

| flag                 | when                                                                                                                                                                                                                                                                                                                                                                        | message                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--add`              | ls, show, path, diff, gate, params, strategies, templates, script-api, script-check                                                                                                                                                                                                                                                                                         | --add does not apply to `backtest \{sub}` — that flag WRITES a label, a note or a mark onto a stored run, which is what `tag` does                                                                                                                                                                                                                                                                                                                                                                             |
| `--addr`             | the daemon is not reachable (exit 3, the CONNECT rung; `\{addr}` is the resolved address and `\{e}` the transport error)                                                                                                                                                                                                                                                    | cannot connect to the backtest daemon at \{addr}: \{e} (start it with `vike-backend backtest --addr`)                                                                                                                                                                                                                                                                                                                                                                                                          |
| `--against`          | ls, show, path, tag, diff, params, strategies, templates, script-api, script-check                                                                                                                                                                                                                                                                                          | --against does not apply to `backtest \{sub}` — that flag names the BASELINE or the criteria a verdict is computed from, and `gate` is the verb whose product is that verdict                                                                                                                                                                                                                                                                                                                                  |
| `--all`              | ls, show, path, tag, gate, params, strategies, templates, script-api, script-check                                                                                                                                                                                                                                                                                          | --all does not apply to `backtest \{sub}` — that flag shapes a two-run COMPARISON, which is what `diff` renders                                                                                                                                                                                                                                                                                                                                                                                                |
| `--all`              | (any reading sub-verb, with a value)                                                                                                                                                                                                                                                                                                                                        | --all takes no value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `--as`               | tag, empty name                                                                                                                                                                                                                                                                                                                                                             | --as a mark name is required (for example `baseline/momentum`, or `prod`)                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `--as`               | tag, leading/trailing whitespace                                                                                                                                                                                                                                                                                                                                            | --as '\{name}': a mark name may not begin or end with whitespace                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `--as`               | tag, more than 3 '/'-separated parts                                                                                                                                                                                                                                                                                                                                        | --as '\{name}': a mark name may have at most 3 '/'-separated parts — a mark is a label, not a directory tree                                                                                                                                                                                                                                                                                                                                                                                                   |
| `--as`               | tag, an empty part                                                                                                                                                                                                                                                                                                                                                          | --as '\{name}': an empty part — a mark name may not start or end with '/' and may not contain '//'                                                                                                                                                                                                                                                                                                                                                                                                             |
| `--as`               | tag, a part starting with '.'                                                                                                                                                                                                                                                                                                                                               | --as '\{name}': the part '\{segment}' starts with '.' — that is a traversal ('..'), or a dot-entry every directory scan in this workspace skips, so the mark would be written and then be invisible                                                                                                                                                                                                                                                                                                            |
| `--as`               | tag, a disallowed character                                                                                                                                                                                                                                                                                                                                                 | --as '\{name}': the part '\{segment}' contains '\{bad}' — a mark name takes ASCII letters, digits, '.', '\_', '-' and '/' only, because it becomes a file path on every platform this ships to                                                                                                                                                                                                                                                                                                                 |
| `--as`               | ls, show, path, diff, gate, params, strategies, templates, script-api, script-check                                                                                                                                                                                                                                                                                         | --as does not apply to `backtest \{sub}` — that flag WRITES a label, a note or a mark onto a stored run, which is what `tag` does                                                                                                                                                                                                                                                                                                                                                                              |
| `--cash`             | ls, show, path, tag, diff, gate, strategies, templates, script-api, script-check                                                                                                                                                                                                                                                                                            | unknown option '--cash'                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `--changed-only`     | ls, show, path, tag, gate, params, strategies, templates, script-api, script-check                                                                                                                                                                                                                                                                                          | --changed-only does not apply to `backtest \{sub}` — that flag shapes a two-run COMPARISON, which is what `diff` renders                                                                                                                                                                                                                                                                                                                                                                                       |
| `--changed-only`     | (any reading sub-verb, with a value)                                                                                                                                                                                                                                                                                                                                        | --changed-only takes no value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `--cols`             | ls, when every element is empty after trimming                                                                                                                                                                                                                                                                                                                              | --cols was given no column names                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `--cols`             | show, path, tag, diff, gate, params, strategies, templates, script-api, script-check                                                                                                                                                                                                                                                                                        | --cols does not apply to `backtest \{sub}` — that flag narrows, orders or shapes a LISTING, and `ls` is the listing                                                                                                                                                                                                                                                                                                                                                                                            |
| `--config`           | ls, path, tag, diff, gate, params, strategies, templates, script-api, script-check                                                                                                                                                                                                                                                                                          | --config does not apply to `backtest \{sub}` — that flag selects a SECTION of one stored run, which is what `show` renders                                                                                                                                                                                                                                                                                                                                                                                     |
| `--config`           | (any reading sub-verb, with a value)                                                                                                                                                                                                                                                                                                                                        | --config takes no value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `--decide`           | an unknown spelling (the ENGINE or the compute server, after a spawn or a dial — this side forwards the value verbatim)                                                                                                                                                                                                                                                     | unknown engine.decide \{other:?} (want sequential \| simultaneous; absent = sequential, the per-symbol walk in the order data.symbols lists them)                                                                                                                                                                                                                                                                                                                                                              |
| `--decide`           | `simultaneous` on a tick profile (the far side, BacktestProfile::refusals)                                                                                                                                                                                                                                                                                                  | engine.decide = "simultaneous" is bar-mode only: the cross-sectional …                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `--engine`           | ⚠ typed WITHOUT --local, i.e. on the remote arm (CLI, exit 2). Same one-line template as --store.                                                                                                                                                                                                                                                                           | --engine applies to --local only — a remote run reads the SERVER's store                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--engine`           | the named program cannot be spawned (CONNECT rung; `\{}` is the engine display form, `\{e}` the io::Error, `MISSING_HINT` a constant in crates/vike-cli/src/cmd/engine.rs that this area did not transcribe)                                                                                                                                                                | cannot run the backtest engine (\{engine}): \{e} \{MISSING\_HINT}                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `--euler-depth`      | --euler-depth under any method but euler (from METHOD\_KNOBS, both routes)                                                                                                                                                                                                                                                                                                  | --euler-depth is a euler flag, but this run selected the "grid" optimizer. It was silently discarded before; it is refused now, because a knob that configures a search you did not select cannot do what it says                                                                                                                                                                                                                                                                                              |
| `--euler-depth`      | a value past the cap, under euler (`\{d}` is the parsed value, the second hole is EulerConfig::MAX\_DEPTH\_CAP)                                                                                                                                                                                                                                                             | --euler-depth 99 is past the cap of 16 — it was silently clamped before, which made the budget line report a depth you did not ask for                                                                                                                                                                                                                                                                                                                                                                         |
| `--euler-depth`      | a non-integer value, under euler                                                                                                                                                                                                                                                                                                                                            | invalid --euler-depth "abc" (expected an integer)                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `--export`           | value `fills` (Usage, rung 2) — refused at EXECUTION time in `export_document`, not at parse time                                                                                                                                                                                                                                                                           | --export fills is not available — fills are not stored at ANY size. A backtest computes them, consumes them into report.json's scalars and drops them; only the trade LEDGER and the equity curve survive. `--export trades` and `--export equity` both work today.                                                                                                                                                                                                                                            |
| `--export`           | any value containing a comma, e.g. `trades,equity` (Usage, rung 2). Template: "--export '\{value}': one value at a time. …" where \{value} is the trimmed spec as typed                                                                                                                                                                                                     | --export 'trades,equity': one value at a time. Each export is a single document and `--out` names a single file, so a list would either be truncated to its first value or written as two documents nothing can parse. Run `show` once per value.                                                                                                                                                                                                                                                              |
| `--export`           | any other unrecognised value (Usage, rung 2). Template: "--export '\{other}' is not a value this verb knows — §6.2's set is trades, equity and fills, of which \{list} are stored (fills are not: see `--export fills`)" where \{other} is the trimmed value and \{list} is `EXPORTABLE.join(" and ")` = "trades and equity"                                                | --export 'nonsense' is not a value this verb knows — §6.2's set is trades, equity and fills, of which trades and equity are stored (fills are not: see `--export fills`)                                                                                                                                                                                                                                                                                                                                       |
| `--export`           | `--export trades` on a run whose producer wrote no trades.json (Failed, rung 1). Template holes: \{run\_id} = the run's directory name, \{file} = `vike_model::runs::TRADES_FILE` = "trades.json"                                                                                                                                                                           | a-1-0 wrote no trades.json — this producer keeps no trade ledger (a study, or a run minted before the run artifact existed)                                                                                                                                                                                                                                                                                                                                                                                    |
| `--export`           | `--export equity` on a run whose producer wrote no series.json (Failed, rung 1). Template holes: \{run\_id} = the run's directory name, \{file} = `vike_model::runs::SERIES_FILE` = "series.json"                                                                                                                                                                           | a-1-0 wrote no series.json — this producer keeps no equity curve                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `--export`           | any other RunReadError on either value (Failed, rung 1)                                                                                                                                                                                                                                                                                                                     | \<the `RunReadError`'s own Display, passed through verbatim by `CliError::failed(other.to_string())`>                                                                                                                                                                                                                                                                                                                                                                                                          |
| `--export`           | used on any sub-verb other than `show` (Usage, rung 2), by `refuse_foreign_read_flags`'s `show_only` roster. Template: "\{flag} does not apply to `backtest \{sub}` — \{why}"                                                                                                                                                                                               | --export does not apply to `backtest ls` — that flag selects a SECTION of one stored run, which is what `show` renders                                                                                                                                                                                                                                                                                                                                                                                         |
| `--fail-if`          | the whole expression is empty or whitespace                                                                                                                                                                                                                                                                                                                                 | --fail-if takes at least one criterion, e.g. `sharpe:-5%,max_dd:+10%` — METRIC, a colon, a SIGN saying which direction is bad, the tolerance, and an optional `%`                                                                                                                                                                                                                                                                                                                                              |
| `--fail-if`          | a term between two commas is empty                                                                                                                                                                                                                                                                                                                                          | --fail-if: an empty criterion — terms are joined by a single comma, e.g. `sharpe:-5%,max_dd:+10%`                                                                                                                                                                                                                                                                                                                                                                                                              |
| `--fail-if`          | the colon is missing (format! template; \{term} is the trimmed term)                                                                                                                                                                                                                                                                                                        | --fail-if `\{term}`: a criterion is METRIC:SIGN NUMBER\[%], e.g. `sharpe:-5%` — the colon is missing                                                                                                                                                                                                                                                                                                                                                                                                           |
| `--fail-if`          | the metric before the colon is empty (\{term} = the trimmed term)                                                                                                                                                                                                                                                                                                           | --fail-if `\{term}`: the metric before the colon is empty                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `--fail-if`          | no leading + or - on the tolerance (\{term} = the trimmed term, \{metric} = the trimmed metric)                                                                                                                                                                                                                                                                             | --fail-if `\{term}`: the tolerance needs a SIGN saying which direction is bad — `-` fails on a FALL (`\{metric}:-5%`), `+` fails on a RISE (`\{metric}:+5%`). Without one this gate would check a side of the number you did not choose.                                                                                                                                                                                                                                                                       |
| `--fail-if`          | the magnitude does not parse as f64 (\{term} = the trimmed term, \{number} = the text after the sign with any trailing % stripped, NOT trimmed)                                                                                                                                                                                                                             | --fail-if `\{term}`: `\{number}` is not a number — the tolerance is the MAGNITUDE                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `--fail-if`          | the magnitude parses but is not finite, e.g. `sharpe:+inf` (\{term}, \{number} as above)                                                                                                                                                                                                                                                                                    | --fail-if `\{term}`: `\{number}` is not a finite tolerance                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `--fail-if`          | the magnitude is negative, e.g. `sharpe:--5%` (\{term} = the trimmed term, \{metric} = the trimmed metric)                                                                                                                                                                                                                                                                  | --fail-if `\{term}`: the tolerance is negative — the DIRECTION is the sign's job and the number is the magnitude, so `\{metric}:-5%` is what `\{term}` was probably meant to be                                                                                                                                                                                                                                                                                                                                |
| `--fail-if`          | two criteria resolve to the SAME report key — including an alias pair such as `max_dd:+5%,max_drawdown:+10%` (\{prev} and \{c} are the two criteria re-rendered by Criterion's Display, \{key} is the resolved JSON key)                                                                                                                                                    | `\{prev}` and `\{c}` both judge `\{key}` — name each metric once; a silently-dropped criterion is a gate checking something other than what it was given                                                                                                                                                                                                                                                                                                                                                       |
| `--help`             | `--version` / `-V` typed inside the backtest plane                                                                                                                                                                                                                                                                                                                          | unknown argument: --version                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `--html`             | --html --json                                                                                                                                                                                                                                                                                                                                                               | --html and --json are two SERIALIZATIONS of the same run, and this verb writes one document: --html is the rendered tearsheet a human opens, --json is the machine shape (`\{run_id, dir, manifest, report}`). Run it twice, or take the JSON and render it elsewhere — every number in the HTML comes from the same report.json --json prints.                                                                                                                                                                |
| `--interval`         | vike\_model::time::interval\_ms returns None — fewer than 2 chars, a non-digit count, or an unknown trailing unit. NOTE: a ZERO count (`0m`) DOES parse and is NOT refused here.                                                                                                                                                                                            | --interval \{v:?} is not a valid interval — a digit count and one unit of s\|m\|h\|d (e.g. 30s, 5m, 1h, 1d)                                                                                                                                                                                                                                                                                                                                                                                                    |
| `--json`             | an inline value (`--json=1`)                                                                                                                                                                                                                                                                                                                                                | --json takes no value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `--kind`             | a value outside DATA\_KINDS (exact, case-sensitive)                                                                                                                                                                                                                                                                                                                         | --kind must be bar\|tick, got \{value:?}                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--limit`            | ls, non-usize value                                                                                                                                                                                                                                                                                                                                                         | --limit '\{n}' is not a whole number of rows                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `--limit`            | show, path, tag, diff, gate, params, strategies, templates, script-api, script-check                                                                                                                                                                                                                                                                                        | --limit does not apply to `backtest \{sub}` — that flag narrows, orders or shapes a LISTING, and `ls` is the listing                                                                                                                                                                                                                                                                                                                                                                                           |
| `--local`            | --local on a profile that declares a \[walkforward] table (CLI, exit 2). One real newline before `Drop --local`.                                                                                                                                                                                                                                                            | --local cannot run a walk-forward: this profile declares a \[walkforward] table, and the standalone engine has ONE profile path — it branches on the \[paramscan] grid and nothing else, so neither walk-forward driver is reachable from any binary and there is nothing local to spawn. Drop --local to run it on the compute daemon, or drop the \[walkforward] table to backtest this profile here.                                                                                                        |
| `--local`            | an inline value (`--local=1`)                                                                                                                                                                                                                                                                                                                                               | --local takes no value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `--local`            | --local when the profile had to be STAGED and there is no project above the working directory (exit 1). `\{}` is filled by one of the two sentences below.                                                                                                                                                                                                                  | --local runs the engine on this machine from a profile FILE, and there is no project above the working directory to stage one in. \{staging reason} Run inside your project (or set $VIKE\_SETTINGS\_DIR), pass an already-merged profile to --profile, or write one first with --write-profile \<path>                                                                                                                                                                                                        |
| `--md`               | ls, show, path, tag, gate, params, strategies, templates, script-api, script-check                                                                                                                                                                                                                                                                                          | --md does not apply to `backtest \{sub}` — that flag shapes a two-run COMPARISON, which is what `diff` renders                                                                                                                                                                                                                                                                                                                                                                                                 |
| `--md`               | (any reading sub-verb, with a value)                                                                                                                                                                                                                                                                                                                                        | --md takes no value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `--metrics`          | ls, path, tag, diff, gate, params, strategies, templates, script-api, script-check                                                                                                                                                                                                                                                                                          | --metrics does not apply to `backtest \{sub}` — that flag selects a SECTION of one stored run, which is what `show` renders                                                                                                                                                                                                                                                                                                                                                                                    |
| `--metrics`          | (any reading sub-verb, with a value)                                                                                                                                                                                                                                                                                                                                        | --metrics takes no value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--metrics-list`     | ls, path, tag, diff, gate, params, strategies, templates, script-api, script-check — a NAMED rule rather than a `show_only` roster row, because that roster's sentence ("selects a SECTION of one stored run") is FALSE of a listing                                                                                                                                        | --metrics-list does not apply to `backtest \{sub}` — it prints the METRIC CATALOG (every id this tree can measure, with what each one means), which is `show`'s answer to "what can I ask for" beside its --metrics. It names no run and reads no runs directory: `backtest show --metrics-list`                                                                                                                                                                                                               |
| `--metrics-list`     | (any reading sub-verb, with a value)                                                                                                                                                                                                                                                                                                                                        | --metrics-list takes no value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `--note`             | ls, show, path, diff, gate, params, strategies, templates, script-api, script-check                                                                                                                                                                                                                                                                                         | --note does not apply to `backtest \{sub}` — that flag WRITES a label, a note or a mark onto a stored run, which is what `tag` does                                                                                                                                                                                                                                                                                                                                                                            |
| `--optimizer`        | a value outside the roster, in any case (CLI, before any dial or spawn; exit 2) — the ENGINE and the compute server answer with this same sentence, rendered from the same roster by the same function, so there is no longer a second wording to reach                                                                                                                     | invalid --optimizer "bogus" (expected grid\|euler\|tpe\|genetic)                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `--optimizer`        | typed on a profile that declares a \[walkforward] table (CLI, exit 2)                                                                                                                                                                                                                                                                                                       | --optimizer configures nothing on a walk-forward run: the wire verb it goes over carries the profile TOML and nothing else. A window's ranking is \[walkforward].rank\_by, in the profile, read by the one parser that runs it — and what each window searches is that same \[walkforward] table's business, never a flag on this side.                                                                                                                                                                        |
| `--optimizer`        | --optimizer genetic with no --seed (engine/server, via search\_select::require\_seed)                                                                                                                                                                                                                                                                                       | --optimizer genetic requires --seed \<u64>. It is not defaulted, deliberately: a genetic search reports ONE sample of a distribution, and a seed nobody typed is a constant the result silently depends on — write `--seed 7` (any u64) and the run is reproducible from your own shell history                                                                                                                                                                                                                |
| `--optimizer`        | --local, on a profile with no \[paramscan] table (the spawned engine, exit 2; `\{asked}` is the space-joined subset of --optimizer --euler-depth --trials --seed --keep-trials --resume that argv actually carried, `\{profile_path:?}` the Debug-quoted profile path)                                                                                                      | backtest: \{asked} names a parameter SEARCH, but \{profile\_path:?} has no \[paramscan] table — there is nothing to search. Add one, or drop the search flags                                                                                                                                                                                                                                                                                                                                                  |
| `--optimizer`        | remote, on a profile with no \[paramscan] table (compute server Response::Error; the literal contains a real newline before `fast = …`)                                                                                                                                                                                                                                     | profile has no \[paramscan] table — a parameter search needs a grid, e.g. `[paramscan] fast = [5, 10, 15]`                                                                                                                                                                                                                                                                                                                                                                                                     |
| `--optimizer`        | any non-grid method against a daemon that does not advertise `search_method` — refused locally, NOTHING sent (`\{:?}` renders the daemon's advertised feature list)                                                                                                                                                                                                         | backtest daemon does not advertise `search_method` (advertised: \{features:?}) — nothing was sent. A search METHOD (--optimizer/--euler-depth/--trials/--seed) and --rank-by multi need a newer `vike-backend backtest --addr`; this verb is capability-negotiated, not version-gated. An older daemon would DROP the field, run the exhaustive grid and report success, which is the silent downgrade this refusal exists to prevent — upgrade the daemon, or drop the flag to search the grid on the server. |
| `--out`              | path, tag, diff, gate, params, strategies, script-api, script-check                                                                                                                                                                                                                                                                                                         | --out names a FILE to write a rendered document to, and `backtest \{sub}` prints a line the shell can already redirect                                                                                                                                                                                                                                                                                                                                                                                         |
| `--out`              | templates — the same rule with a POINTER appended, because an operator typing it there is trying to save a starter and a bare `>` would clobber the strategy they are editing                                                                                                                                                                                               | --out names a FILE to write a rendered document to, and `backtest templates` prints a line the shell can already redirect — a starter is SAVED with --write-strategy, which refuses an existing path rather than overwriting one                                                                                                                                                                                                                                                                               |
| `--out`              | ls or show, when the file cannot be written                                                                                                                                                                                                                                                                                                                                 | cannot write \{file}: \{io\_error}                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `--param`            | the value carries no `=`                                                                                                                                                                                                                                                                                                                                                    | --param takes k=v, got \{pair:?} (e.g. --param size=1.5)                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--param`            | the key is empty or whitespace (refused HERE so the message names --param rather than the --set grammar)                                                                                                                                                                                                                                                                    | --param takes k=v with a non-empty key, got \{pair:?} (e.g. --param size=1.5)                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `--param`            | the key contains a `.`                                                                                                                                                                                                                                                                                                                                                      | --param \{key}: \[strategy.params] is a FLAT knob table — use --set strategy.params.\{key}=… if you really mean a nested key                                                                                                                                                                                                                                                                                                                                                                                   |
| `--param`            | the value looks like a search axis — it starts with `[`, or it is three colon-separated parts that all parse as f64                                                                                                                                                                                                                                                         | --param \{key}=\{raw}: a RANGE declares a search axis, which this command cannot build yet — declare it as a \[paramscan] table in a --profile, or pass a single value. (--set strategy.params.\{key}=\{raw} sets it as a literal value if that is what you meant.)                                                                                                                                                                                                                                            |
| `--preset`           | the preset wraps its knobs in a \[params] table (exactly one key, and it is a table named `params`) — the message is prefixed `preset \{preset_path}: ` by execute                                                                                                                                                                                                          | it wraps its knobs in a \[params] table, so the strategy would receive one parameter called 'params' that nothing reads and every knob would keep its default. A preset IS the params table: delete the \[params] header and leave the keys at the top level                                                                                                                                                                                                                                                   |
| `--preset`           | the preset defines `src`                                                                                                                                                                                                                                                                                                                                                    | it defines 'src', which is the strategy's SOURCE rather than one of its knobs — that is what `--script` is for. Delete the 'src' key                                                                                                                                                                                                                                                                                                                                                                           |
| `--preset`           | the preset is not valid TOML                                                                                                                                                                                                                                                                                                                                                | not valid TOML: \{e}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `--preset`           | the preset is TOML but not a table                                                                                                                                                                                                                                                                                                                                          | a preset must be a table of parameters                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `--preset`           | the file cannot be read                                                                                                                                                                                                                                                                                                                                                     | cannot read preset \{preset\_path}: \{e}                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--profile`          | a trailing --profile with nothing after it                                                                                                                                                                                                                                                                                                                                  | \{flag} requires a value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--profile`          | the next token starts with `--`                                                                                                                                                                                                                                                                                                                                             | \{flag} requires a value, but the next argument is another flag (\{found})                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `--profile`          | the file cannot be read (in execute, exit rung 1)                                                                                                                                                                                                                                                                                                                           | cannot read profile \{path}: \{e}                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `--profile`          | the file is not valid TOML (in build\_profile\_toml, lifted onto the USAGE rung by CliError::usage)                                                                                                                                                                                                                                                                         | profile is not valid TOML: \{e}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `--rank-by`          | a value outside the roster, in any case (CLI, exit 2, before any dial or spawn) — ⚠ this row used to carry TWO messages, because the CLI refused with `--rank-by must be …, got "bogus"` while the engine and the server refused the same value with the sentence below; both sides render it from one roster through one function now, so the pair collapsed into this row | invalid --rank-by "bogus" (expected sharpe\|return\|max\_dd\|equity\|multi)                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `--rank-by`          | typed on a profile that declares a \[walkforward] table (CLI, exit 2) — that wire verb carries the profile TOML and nothing else                                                                                                                                                                                                                                            | --rank-by configures nothing on a walk-forward run: the wire verb it goes over carries the profile TOML and nothing else. A window's ranking is \[walkforward].rank\_by, in the profile, read by the one parser that runs it — and what each window searches is that same \[walkforward] table's business, never a flag on this side.                                                                                                                                                                          |
| `--rank-by`          | --rank-by multi against a daemon that does not advertise `search_method` — refused locally, nothing sent                                                                                                                                                                                                                                                                    | backtest daemon does not advertise `search_method` (advertised: \{features:?}) — nothing was sent. A search METHOD (--optimizer/--euler-depth/--trials/--seed) and --rank-by multi need a newer `vike-backend backtest --addr`; this verb is capability-negotiated, not version-gated. An older daemon would DROP the field, run the exhaustive grid and report success, which is the silent downgrade this refusal exists to prevent — upgrade the daemon, or drop the flag to search the grid on the server. |
| `--script`           | params, given together with --strategy                                                                                                                                                                                                                                                                                                                                      | --script and --strategy name two different sources for the same question — give exactly one                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `--script`           | params, unreadable file                                                                                                                                                                                                                                                                                                                                                     | cannot read script \{path}: \{io\_error}                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--script`           | params, script that will not compile                                                                                                                                                                                                                                                                                                                                        | rhai compile error: \{err}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `--script`           | script-check, given a file that does not compile (exit rung 1; the diagnostic is the PRODUCT and goes to stdout, not through this refusal)                                                                                                                                                                                                                                  | error: \{path} does not compile\n\{rhai compile error}                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `--script`           | ls, show, path, tag, diff, gate, strategies, templates, script-api                                                                                                                                                                                                                                                                                                          | --script does not apply to `backtest \{sub}` — it names a .rhai FILE, whose knobs `params` lists and which `script-check` compiles                                                                                                                                                                                                                                                                                                                                                                             |
| `--seed`             | --seed under grid or euler (METHOD\_KNOBS row owners are \["tpe", "genetic"], joined with " or ")                                                                                                                                                                                                                                                                           | --seed is a tpe or genetic flag, but this run selected the "grid" optimizer. It was silently discarded before; it is refused now, because a knob that configures a search you did not select cannot do what it says                                                                                                                                                                                                                                                                                            |
| `--seed`             | a non-u64 value                                                                                                                                                                                                                                                                                                                                                             | invalid --seed "abc" (expected a u64)                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `--seed`             | --optimizer genetic with no --seed                                                                                                                                                                                                                                                                                                                                          | --optimizer genetic requires --seed \<u64>. It is not defaulted, deliberately: a genetic search reports ONE sample of a distribution, and a seed nobody typed is a constant the result silently depends on — write `--seed 7` (any u64) and the run is reproducible from your own shell history                                                                                                                                                                                                                |
| `--set`              | the value carries no `=` (split\_once, first `=` only — the VALUE may contain further `=`)                                                                                                                                                                                                                                                                                  | --set takes key=value, got \{pair:?} (e.g. --set engine.fee\_rate=0.001)                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--set`              | the first dotted segment is not in PROFILE\_TOP\_LEVEL\_KEYS — including the EMPTY head produced by a leading dot or an empty key. The trailing hole is PROFILE\_TOP\_LEVEL\_KEYS.join(", ").                                                                                                                                                                               | --set \{key}: a profile has no `\{head}` table — the top-level keys are \{PROFILE\_TOP\_LEVEL\_KEYS.join(", ")}                                                                                                                                                                                                                                                                                                                                                                                                |
| `--set`              | any segment is empty after the head check passed (e.g. `--set name.=1`) — raised by set\_profile\_key inside build\_profile\_toml, lifted onto the USAGE rung                                                                                                                                                                                                               | --set key \{dotted\_key:?} has an empty segment — a key is spelled `table.key` (or `table.sub.key`), with no leading, trailing or doubled dot                                                                                                                                                                                                                                                                                                                                                                  |
| `--set`              | the path runs THROUGH a plain value; `\{}` is `segs[..=i].join(".")`, the blocking prefix                                                                                                                                                                                                                                                                                   | `\{segs[..=i].join(".")}` is a plain value in the profile, so `\{dotted_key}` cannot nest under it                                                                                                                                                                                                                                                                                                                                                                                                             |
| `--set`              | the leaf names a whole table                                                                                                                                                                                                                                                                                                                                                | `\{dotted_key}` names a whole table in the profile, not a single value — set its leaves instead (`\{dotted_key}.\<key>`)                                                                                                                                                                                                                                                                                                                                                                                       |
| `--set`              | the profile root is not a TOML table                                                                                                                                                                                                                                                                                                                                        | profile root is not a TOML table                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `--show-effective`   | an inline value (`--show-effective=1`)                                                                                                                                                                                                                                                                                                                                      | \{flag} takes no value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `--sort`             | ls, with a direction suffix that is not asc/desc                                                                                                                                                                                                                                                                                                                            | --sort direction '\{other}' is not one of: asc \| desc                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `--sort`             | ls, when the store is non-empty and NO run carries the field                                                                                                                                                                                                                                                                                                                | --sort '\{key}': no run carries that field. Manifest fields are run\_id, kind, produced\_by, started\_at, finished\_at, git\_sha, config.path, config.name, report and detail.\<path>; any other name is read as a top-level key of report.json.                                                                                                                                                                                                                                                               |
| `--sort`             | show, path, tag, diff, gate, params, strategies, templates, script-api, script-check                                                                                                                                                                                                                                                                                        | --sort does not apply to `backtest \{sub}` — that flag narrows, orders or shapes a LISTING, and `ls` is the listing                                                                                                                                                                                                                                                                                                                                                                                            |
| `--store`            | ⚠ typed WITHOUT --local, i.e. on the remote arm (CLI, exit 2). One line, no continuations.                                                                                                                                                                                                                                                                                  | --store applies to --local only — a remote run reads the SERVER's store                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `--strategy`         | params, given together with --script                                                                                                                                                                                                                                                                                                                                        | --script and --strategy name two different sources for the same question — give exactly one                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `--strategy`         | params, a name no roster carries                                                                                                                                                                                                                                                                                                                                            | no built-in strategy named '\{name}'. The roster is: \{roster joined by ", " — PORTABLE\_STRATEGIES, then SIMULATOR\_ONLY names, then SCRIPT\_ONLY names}                                                                                                                                                                                                                                                                                                                                                      |
| `--strategy`         | ls, show, path, tag, diff, gate, strategies, templates, script-api, script-check                                                                                                                                                                                                                                                                                            | --strategy does not apply to `backtest \{sub}` — that flag names the built-in strategy whose keys `params` lists                                                                                                                                                                                                                                                                                                                                                                                               |
| `--symbol`           | any empty element after trimming — a leading, trailing or doubled comma, or an empty value. The flag name in the message is HARD-CODED `--symbol` even though the arm is generic over Shape::StrList (it is the only StrList row).                                                                                                                                          | --symbol takes SYM\[,SYM…] with no empty element, got \{raw:?}                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `--trades`           | ls, path, tag, gate, params, strategies, templates, script-api, script-check                                                                                                                                                                                                                                                                                                | --trades does not apply to `backtest \{sub}` — it names the stored trade ledger, which `show` renders and `diff` compares                                                                                                                                                                                                                                                                                                                                                                                      |
| `--trades`           | (any reading sub-verb, with a value)                                                                                                                                                                                                                                                                                                                                        | --trades takes no value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `--trials`           | ⚠ --trials under --optimizer euler (and under grid, i.e. under no --optimizer at all) — refused from `METHOD_KNOBS` by `refuse_unowned_knob`, on BOTH routes. `\{method:?}` is the Debug of the method TOKEN, so it renders quoted.                                                                                                                                         | --trials is a tpe flag, but this run selected the "euler" optimizer. It was silently discarded before; it is refused now, because a knob that configures a search you did not select cannot do what it says                                                                                                                                                                                                                                                                                                    |
| `--trials`           | --trials with no --optimizer written at all (name falls back to DEFAULT\_SEARCH\_METHOD)                                                                                                                                                                                                                                                                                    | --trials is a tpe flag, but this run selected the "grid" optimizer. It was silently discarded before; it is refused now, because a knob that configures a search you did not select cannot do what it says                                                                                                                                                                                                                                                                                                     |
| `--trials`           | a value that is not a positive integer, under tpe (engine/server)                                                                                                                                                                                                                                                                                                           | invalid --trials "abc" (expected a positive integer)                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `--trials`           | against a daemon that does not advertise `search_method` — refused locally, nothing sent                                                                                                                                                                                                                                                                                    | backtest daemon does not advertise `search_method` (advertised: \{features:?}) — nothing was sent. A search METHOD (--optimizer/--euler-depth/--trials/--seed) and --rank-by multi need a newer `vike-backend backtest --addr`; this verb is capability-negotiated, not version-gated. An older daemon would DROP the field, run the exhaustive grid and report success, which is the silent downgrade this refusal exists to prevent — upgrade the daemon, or drop the flag to search the grid on the server. |
| `--venue`            | a missing or flag-shaped value                                                                                                                                                                                                                                                                                                                                              | \{flag} requires a value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--where`            | the expression contains a '\|' anywhere (\{expr} = the whole raw expression, untrimmed)                                                                                                                                                                                                                                                                                     | --where '\{expr}': this grammar has no OR — terms are joined by a comma, which means AND (`kind=backtest,sharpe>1`). Run `ls` twice for a disjunction.                                                                                                                                                                                                                                                                                                                                                         |
| `--where`            | a term between two commas is empty (\{expr} = the whole raw expression; OP\_HELP is the literal '>= \| \<= \| != \| \~ \| = \| > \| \<')                                                                                                                                                                                                                                    | --where '\{expr}': an empty term — terms are joined by a single comma (FIELD OP VALUE, with OP one of: >= \| \<= \| != \| \~ \| = \| > \| \<)                                                                                                                                                                                                                                                                                                                                                                  |
| `--where`            | a term contains none of the seven operators (\{term} = the TRIMMED term, not the whole expression)                                                                                                                                                                                                                                                                          | --where '\{term}': no operator — a term is FIELD OP VALUE, with OP one of: >= \| \<= \| != \| \~ \| = \| > \| \<                                                                                                                                                                                                                                                                                                                                                                                               |
| `--where`            | the text before the operator is empty, e.g. '>1' (\{term} = the trimmed term, \{op} = the matched operator)                                                                                                                                                                                                                                                                 | --where '\{term}': no field before '\{op}' — a term is FIELD OP VALUE, with OP one of: >= \| \<= \| != \| \~ \| = \| > \| \<                                                                                                                                                                                                                                                                                                                                                                                   |
| `--write-profile`    | the path already exists (USAGE rung, exit 2)                                                                                                                                                                                                                                                                                                                                | --write-profile \{path} already exists, and this command will not overwrite a profile — delete it, or name a different path                                                                                                                                                                                                                                                                                                                                                                                    |
| `--write-profile`    | the write fails (exit rung 1)                                                                                                                                                                                                                                                                                                                                               | cannot write the profile to \{path}: \{e}                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `--write-strategy`   | the path already exists (USAGE rung, exit 2)                                                                                                                                                                                                                                                                                                                                | --write-strategy \{path} already exists, and this command will not overwrite a strategy — delete it, or name a different path                                                                                                                                                                                                                                                                                                                                                                                  |
| `--write-strategy`   | given with no starter id (USAGE rung, exit 2; `\{roster}` is the derived id list)                                                                                                                                                                                                                                                                                           | --write-strategy \{path} needs a starter to write — name one: `vike-cli backtest templates \<id> --write-strategy \{path}`. The ids are: \{roster}                                                                                                                                                                                                                                                                                                                                                             |
| `--write-strategy`   | the write fails (exit rung 1)                                                                                                                                                                                                                                                                                                                                               | cannot write the strategy to \{path}: \{io\_error}                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `--write-strategy`   | ls, show, path, tag, diff, gate, params, strategies, script-api, script-check                                                                                                                                                                                                                                                                                               | --write-strategy does not apply to `backtest \{sub}` — that flag SAVES a shipped starter to a new file, and `templates` is the verb that emits one                                                                                                                                                                                                                                                                                                                                                             |
| `--write-strategy`   | run — a DIFFERENT answer, because `run` has its own parser and this token is not in it                                                                                                                                                                                                                                                                                      | unknown argument: --write-strategy                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `--explain-data`     | an inline value (`--explain-data=1`)                                                                                                                                                                                                                                                                                                                                        | \{flag} takes no value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `--require-coverage` | an inline value (`--require-coverage=1`)                                                                                                                                                                                                                                                                                                                                    | \{flag} takes no value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `--max-gap`          | a blank value                                                                                                                                                                                                                                                                                                                                                               | --max-gap requires a duration, e.g. --max-gap 1d (or 4h, 900000)                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `--on-gap`           | a value outside the roster                                                                                                                                                                                                                                                                                                                                                  | --on-gap \{value} is not one of refuse \| warn \| run                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `--universe`         | a value outside the roster                                                                                                                                                                                                                                                                                                                                                  | --universe \{value} is not one of declared \| covered \| strict                                                                                                                                                                                                                                                                                                                                                                                                                                                |

### Combined with a flag it contradicts (7) [#combined-with-a-flag-it-contradicts-7]

| flag             | when                                                                                                                                                                                                                                                                                            | message                                                                                                                                                                                                                                                                                                                                         |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--addr`         | --addr combined with --local (CLI, exit 2)                                                                                                                                                                                                                                                      | --addr names a remote backtest daemon, so it cannot be combined with --local drop one: --local runs the engine on this machine, --addr ships the profile to a server                                                                                                                                                                            |
| `--decide`       | `simultaneous` beside an armed \[risk] table or engine.leverage (the far side, BacktestProfile::refusals) — a DECLARED GAP rather than a preference: with a pre-trade gate armed the symbol judged first faces the whole step budget, and the fix is a step-boundary snapshot that is not built | engine.decide = "simultaneous" is not built for a run with a pre-trade risk gate: remove \[risk] and engine.leverage, or keep engine.decide …                                                                                                                                                                                                   |
| `--html`         | beside any other document or section flag on `show`                                                                                                                                                                                                                                             | --html and \{flag} ask for two different documents: --html renders this run's whole tearsheet as one HTML page, and \{flag} selects or exports part of it. Which one wins would be a guess, so neither does — run `backtest show \<run> --html --out sheet.html`, then `backtest show \<run> \{flag}`.                                          |
| `--local`        | --local combined with --addr (CLI, exit 2). The literal carries a real newline; the line continuations strip their own leading whitespace, so the second line begins at `drop one:`.                                                                                                            | --addr names a remote backtest daemon, so it cannot be combined with --local drop one: --local runs the engine on this machine, --addr ships the profile to a server                                                                                                                                                                            |
| `--metrics`      | show, beside --metrics-list                                                                                                                                                                                                                                                                     | --metrics-list and --metrics ask for two different documents: the first lists what this tree CAN measure (the catalog, with no run involved at all), the second renders part of one stored run. Which of the two wins would be a guess, so neither does — run `backtest show --metrics-list` on its own, then `backtest show \<run> --metrics`. |
| `--metrics-list` | show, beside --metrics \| --trades \| --config \| --export (`\{flag}` is whichever was given)                                                                                                                                                                                                   | --metrics-list and \{flag} ask for two different documents: the first lists what this tree CAN measure (the catalog, with no run involved at all), the second renders part of one stored run. Which of the two wins would be a guess, so neither does — run `backtest show --metrics-list` on its own, then `backtest show \<run> \{flag}`.     |
| `--metrics-list` | show, beside --json                                                                                                                                                                                                                                                                             | --metrics-list has no --json rendering: it is an aligned table for a human, and nothing in this tree serializes the metric catalog. For the machine-readable answer use the published surface asset — `vike-cli surface --out DIR` writes cli.json, whose `rosters` carry the metric ids. `backtest show --metrics-list` prints the table.      |

### Written without a value (10) [#written-without-a-value-10]

| flag               | when                                                                                            | message                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------ | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--addr`           | written with no value                                                                           | --addr requires a value                                                                                                                                                                                                                                                                                                                                                           |
| `--against`        | gate, absent or blank                                                                           | `backtest gate` needs `--against \<run\|mark>` — every criterion is RELATIVE to a baseline, so there is nothing to judge without one. Make a stable baseline with `vike-cli backtest tag \<run> --as baseline/\<name>`, then gate `--against @baseline/\<name>`. (For an ABSOLUTE threshold this grammar cannot spell, pipe `vike-cli backtest show \<run> --json` through `jq`.) |
| `--engine`         | written with no value                                                                           | --engine requires a value                                                                                                                                                                                                                                                                                                                                                         |
| `--euler-depth`    | written with no value, on the engine's argv path                                                | --euler-depth was written with no value (expected an integer). A trailing `--euler-depth` read as ABSENT before, which silently ran the default instead of refusing — write `--euler-depth \<value>`                                                                                                                                                                              |
| `--optimizer`      | written with no value (trailing `--optimizer`, or `--optimizer` followed by another `--` token) | --optimizer requires a value, but the next argument is another flag (--json)                                                                                                                                                                                                                                                                                                      |
| `--out`            | (any reading sub-verb, no value)                                                                | --out requires a value                                                                                                                                                                                                                                                                                                                                                            |
| `--seed`           | written with no value, on the engine's argv path                                                | --seed was written with no value (expected a u64). A trailing `--seed` read as ABSENT before, which silently ran the default instead of refusing — write `--seed \<value>`                                                                                                                                                                                                        |
| `--store`          | written with no value                                                                           | --store requires a value                                                                                                                                                                                                                                                                                                                                                          |
| `--trials`         | written with no value, on the engine's argv path (`required_value`)                             | --trials was written with no value (expected a positive integer). A trailing `--trials` read as ABSENT before, which silently ran the default instead of refusing — write `--trials \<value>`                                                                                                                                                                                     |
| `--write-strategy` | written with no value                                                                           | --write-strategy requires a value                                                                                                                                                                                                                                                                                                                                                 |

### Used on a sub-verb that does not take it (3) [#used-on-a-sub-verb-that-does-not-take-it-3]

| flag       | when   | message                                                                                                                                                                                        |
| ---------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--cash`   | params | --cash does not apply to `params`, which reads the script or the strategy roster on this machine and lists its knobs — no server, no store, no engine. It belongs to `vike-cli backtest run`   |
| `--cash`   | run    | (ACCEPTED — no refusal. It pushes an Override with key `engine.cash`, value `parse_scalar(raw)`, origin `Origin::Sugar("--cash")`.)                                                            |
| `--decide` | params | --decide does not apply to `params`, which reads the script or the strategy roster on this machine and lists its knobs — no server, no store, no engine. It belongs to `vike-cli backtest run` |

### Accepted values [#accepted-values]

Where a flag takes one of a closed set, this is the set.

| flag                | accepts                                                                                                                                                                                      |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--kind`            | `bar`, `tick`                                                                                                                                                                                |
| `--cols`, `--where` | `run_id`, `kind`, `produced_by`, `started_at`, `finished_at`, `git_sha`, `config.path`, `config.name`, `report`, `detail.<dotted.path>`, `<any other name> = a TOP-LEVEL key of report.json` |
| `--optimizer`       | `grid`, `euler`, `tpe`, `genetic`                                                                                                                                                            |
| `--set`             | `name`, `data`, `engine`, `strategy`, `risk`, `paramscan`, `sweep`, `walkforward`                                                                                                            |
| `--rank-by`         | `sharpe`, `return`, `max_dd`, `equity`                                                                                                                                                       |
| `--against`         | `<run-id>`, `<unique-prefix>`, `@last`, `@last:<kind>`, `@<mark>`                                                                                                                            |
| `--export`          | `trades`, `equity`                                                                                                                                                                           |
| `--sort`            | `asc`, `desc`                                                                                                                                                                                |
| `--on-gap`          | `refuse`, `warn`, `run`                                                                                                                                                                      |
| `--universe`        | `declared`, `covered`, `strict`                                                                                                                                                              |

⚠ `--rank-by` — `multi` is recognised and **refused**: ⚠ NOT refused by today's engine-side `--rank-by` parser. Both routes resolve through crates/vike-backtest/src/harness/search\_select.rs's `resolve_rank`, whose FIRST arm is `Some(s) if s.eq_ignore_ascii_case("multi")` — the engine binary reaches it via `parse_search_flags` and the compute server via `run_paramscan_profile`, so `--rank-by multi` is accepted on `--local` and on `--addr` alike (crates/vike-cli/tests/search\_walkforward\_cli.rs's `every_search_knob_now_reaches_the_dial` drives `["--rank-by", "multi"]` to a CONNECT failure, exit 3, proving it was not a usage error). It IS refused by the FOUR-ARM parser crates/vike-backtest/src/harness/sweep.rs's `RankMetric::from_str_ci`, which returns None for it — and that parser is what a daemon predating the `search_method` capability uses, and what crates/vike-backtest/src/harness/profile.rs's `WalkforwardCfg::rank_metric` uses for the PROFILE key `[walkforward].rank_by`. Verbatim from that profile-key path: `unknown walkforward.rank_by "multi" (want sharpe \| return \| max_dd \| equity; absent = sharpe)`. Against an old daemon the CLI never gets that far — crates/vike-datahub-client/src/client.rs's `run_paramscan_profile` pre-refuses `rank_by == "multi"` locally under FEATURE\_SEARCH\_METHOD, without sending.

⚠ `--export` — `fills` is recognised and **refused**: --export fills is not available — fills are not stored at ANY size. A backtest computes them, consumes them into report.json's scalars and drops them; only the trade LEDGER and the equity curve survive. `--export trades` and `--export equity` both work today.

⚠ `--kind` — HAND-WRITTEN COPY of the two spellings `DataKind` accepts, for the same reason as the roster above — this crate links no engine crate. Checked through the shared one\_of helper, which is a SPELLING check and never a second implementation of what the value MEANS. The comparison is `roster.contains(&value)` on the already-trimmed string, so it is case-SENSITIVE.

⚠ `--set` — HAND-WRITTEN COPY, deliberately. crates/vike-cli/Cargo.toml states this crate links no vike-backtest and no engine crate, so `BacktestProfile` is not nameable here at all and nothing can derive it. It is the FIRST-SEGMENT roster only — a full key roster would be \~90 engine.\* names against a schema that grew sixteen fields in one PR. `base_dir` is deliberately absent (it is `#[serde(skip)]`, not a TOML key). BOTH `paramscan` and `sweep` are members: owner ruling R2 renamed the section and the loader keeps `sweep` as a PERMANENT serde alias, so an omitted alias row would make `--set sweep.fast=…` a CLI usage error against a key the engine accepts. Gated from the test tree (where the dev-dependency reaches) by crates/vike-cli/tests/backtest\_flags\_schema.rs's every\_cli\_top\_level\_key\_is\_one\_the\_profile\_declares.

⚠ `--on-gap` — HAND-WRITTEN COPY of `vike_backtest::data_plan::OnGap::NAMES`, for the reason `data_kinds` and `profile_top_level_keys` above give: this crate links no engine crate, so that function is not nameable here and nothing can derive it. ⚠ This row claimed `derived_from: crates/vike-backtest/src/harness/profile.rs's DataCfg::on_gap` and that was a false claim of derivation — the field's own doc reserves `Some` for a path the members come FROM, and these are a literal. What IS gated is the direction this crate can reach: the\_data\_rosters\_are\_exactly\_what\_the\_cli\_validator\_accepts holds these members equal to crates/vike-cli/src/cmd/data.rs's `ON_GAP_VALUES`, in order, by rendering the refusal that prints it — so the published roster and the validator an operator actually meets cannot differ. RESIDUAL, declared rather than assumed away: nothing compares either of them to the ENGINE, so a FOURTH disposition added to `DataCfg::on_gap` leaves `--on-gap \<new>` a local usage error against a value the profile loader accepts. The engine-side leg belongs in crates/vike-cli/tests/backtest\_flags\_schema.rs, where the vike-backtest dev-dependency already reaches and `every_cli_top_level_key_is_one_the_profile_declares` is the pattern.

⚠ `--universe` — HAND-WRITTEN COPY of `vike_backtest::data_plan::UniverseMode::NAMES`, on `gap_dispositions`' terms exactly — including the false derivation claim this row also carried, and the same declared RESIDUAL on the engine-side direction. Gated as far as this crate reaches by the\_data\_rosters\_are\_exactly\_what\_the\_cli\_validator\_accepts.

A further 16 closed sets back the parser itself rather than any one flag.

## Exit codes, and where this came from [#exit-codes-and-where-this-came-from]

### The ladder [#the-ladder]

Every verb answers on this ladder, so a script branches on the number rather than on the text.

| code | name    |
| ---- | ------- |
| `0`  | Ok      |
| `1`  | Failed  |
| `2`  | Usage   |
| `3`  | Connect |
| `4`  | Refused |
| `5`  | Venue   |
| `6`  | Breach  |
| `7`  | Empty   |

Read out of crates/vike-cli/src/exit.rs's `Exit` (`#[repr(u8)]`; the discriminants ARE the exit codes, converted by `impl From\<Exit> for ExitCode`)

### Where each of these was read from [#where-each-of-these-was-read-from]

54 flags, each with the source it was rendered from — a path and the symbol inside it,
never a line number.

| flag                 | read from                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--add`              | crates/vike-cli/src/cmd/backtest.rs's `parse_read` (the `"--add"` arm calls `a.add.push`, with the ⚠ comment naming it the only repeatable one); crates/vike-cli/src/cmd/runs/tag.rs's `run_tag`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `--addr`             | crates/vike-cli/src/cmd/backtest.rs's `resolve_addr`, `Args::addr` and `execute`; crates/vike-config/src/config.rs's `DEFAULT_BACKTEST_ADDR`, `Config::backtest_addr`, `BACKTEST_ADDR_ENV` and `check_env_addr`; crates/vike-cli/src/lib.rs's `Resolved::backtest_addr`                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--against`          | crates/vike-cli/src/cmd/runs/gate.rs's `refuse_an_ungateable_line` and `run_gate`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `--all`              | crates/vike-cli/src/cmd/runs/diff.rs's `run_diff` (`let show_all = a.all;`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `--as`               | crates/vike-cli/src/cmd/runs/tag.rs's `refuse_a_tag_that_writes_nothing` (the `valid_mark_name(name).map_err(\|why\| format!("--as \{why}"))` call) and `run_tag`; crates/vike-model/src/runs.rs's `valid_mark_name`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `--cash`             | crates/vike-cli/src/cmd/backtest.rs's `SUGAR` (the `Sugar \{ flag: "--cash", key: "engine.cash", shape: Shape::Scalar }` row), `PARAMS_REFUSED`, `refuse_a_run_flag_on_params`, and `parse_read`'s final `other if other.starts_with("--")` arm; `implied_defaults`'s ⚠ paragraph                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `--changed-only`     | crates/vike-cli/src/cmd/backtest.rs's `ReadArgs::changed_only` (its doc: "the DEFAULT, accepted so a script that says what it means is not refused"); crates/vike-cli/src/cmd/runs/diff.rs's `run_diff` never reads the field                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `--cols`             | crates/vike-cli/src/cmd/runs/ls.rs's `run_ls` (the `a.cols` split) and `DEFAULT_COLS`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `--config`           | crates/vike-cli/src/cmd/runs/show\.rs's `show_text` (the `config \|\| all` branch) and that module's doc `⚠ --config says what is NOT recorded`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `--decide`           | crates/vike-cli/src/cmd/backtest.rs's `SUGAR` (the `engine.decide` row) and `parse_run_args` (the `Shape::Str` arm, whose ⚠ argues why this value is not checked here); crates/vike-backtest/src/harness/profile.rs's `EngineCfg::decide` and `decide_mode`; crates/vike-backtest/src/engine/sim\_broker.rs's `DecideMode`                                                                                                                                                                                                                                                                                                                                                                                    |
| `--engine`           | crates/vike-cli/src/cmd/backtest.rs's `Args::engine`, `parse_run_args`'s remote-arm refusal loop and `execute_local`; crates/vike-cli/src/cmd/engine.rs's `locate`, `ENGINE_BIN` and `cannot_spawn`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `--euler-depth`      | crates/vike-cli/src/cmd/backtest.rs's `Args::euler_depth` and `parse_run_args`'s `"--euler-depth"` arm; crates/vike-backtest/src/harness/search\_select.rs's `parse_euler_depth`; crates/vike-backtest/src/search.rs's `EulerConfig::DEFAULT_MAX_DEPTH` and `EulerConfig::MAX_DEPTH_CAP`                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `--export`           | crates/vike-cli/src/cmd/runs/show\.rs's `export_document` and `EXPORTABLE`; `run_show`'s `match &a.export`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `--fail-if`          | crates/vike-cli/src/cmd/runs/gate.rs's `refuse_an_ungateable_line`; crates/vike-cli/src/cmd/runs/failif.rs's `parse_fail_if` and that module's grammar block                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `--fee`              | crates/vike-cli/src/cmd/backtest.rs's SUGAR (row `--fee` -> `engine.fee_rate`, Shape::Scalar); crates/vike-cli/src/cmd/backtest.rs's parse\_scalar                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `--from`             | crates/vike-cli/src/cmd/backtest.rs's SUGAR and its Shape::Str doc; pinned by crates/vike-cli/src/cmd/backtest.rs's a\_bare\_epoch\_ms\_date\_stays\_a\_string\_through\_the\_sugar\_flag                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `--help`             | crates/vike-cli/src/cmd/backtest.rs's `parse_read` (the `"-h" \| "--help"` arm calls `args::help_requested`); crates/vike-cli/src/cmd/args.rs's `HELP_SENTINEL` and `exit_for_parse_error`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `--html`             | `crates/vike-cli/src/cmd/runs/show.rs`'s `html_document` and `refuse_a_second_document`; the parser arm in `crates/vike-cli/src/cmd/backtest.rs`'s `parse_read`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `--interval`         | crates/vike-cli/src/cmd/backtest.rs's parse\_run\_args (the `s.flag == "--interval"` special case inside the Shape::Str arm); crates/vike-model/src/time.rs's interval\_ms                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `--json`             | crates/vike-cli/src/cmd/backtest.rs's `Args::json`, `parse_run_args`'s `"--json"` arm, `parse_read`'s `"--json"` arm, `ReadArgs::json`, `execute`, `execute_local` and `execute_read`; crates/vike-cli/src/cmd/runs/gate.rs's `run_gate`                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `--kind`             | crates/vike-cli/src/cmd/backtest.rs's parse\_run\_args (the `s.flag == "--kind"` special case calls one\_of with DATA\_KINDS); crates/vike-cli/src/cmd/backtest.rs's implied\_defaults                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `--limit`            | crates/vike-cli/src/cmd/runs/ls.rs's `run_ls` (the `a.limit` parse + `truncate`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `--local`            | crates/vike-cli/src/cmd/backtest.rs's `Args::local`, `parse_run_args`'s `"--local"` arm, `execute` and `execute_local`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `--md`               | crates/vike-cli/src/cmd/runs/diff.rs's `run_diff` (the `if a.json \{ … } else if a.md \{ … }` ladder)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `--metrics`          | crates/vike-cli/src/cmd/runs/show\.rs's `show_text` and `run_show`; crates/vike-cli/src/cmd/backtest.rs's `refuse_foreign_read_flags` (`show_only`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `--metrics-list`     | crates/vike-cli/src/cmd/runs/show\.rs's `run_show` (the `a.metrics_list` short-circuit), `refuse_a_listing_beside_a_run_rendering` and `run_rendering_flags_given`; crates/vike-cli/src/cmd/backtest.rs's `parse_read` (the `"--metrics-list"` arm) and `ReadArgs::metrics_list`; crates/vike-analytics/src/metric\_catalog.rs's `metric_list_text`, `METRICS` and `ABSENT`                                                                                                                                                                                                                                                                                                                                   |
| `--note`             | crates/vike-cli/src/cmd/runs/tag.rs's `run_tag` (passes `a.note` to both `add_tags` and `write_mark`) and that function's ⚠ doc                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `--optimizer`        | crates/vike-cli/src/cmd/backtest.rs's `parse_run_args` (the `"--optimizer"` arm, which calls `accept_value`); crates/vike-datahub-client/src/flag\_vocab.rs's `accept_value` and its `--optimizer` row, whose `values` IS the protocol const; crates/vike-cli/src/cmd/backtest.rs's `DEFAULT_OPTIMIZER` (cfg(test)); crates/vike-datahub-client/src/proto.rs's `SEARCH_METHODS` and `DEFAULT_SEARCH_METHOD`; crates/vike-backtest/src/harness/search\_select.rs's `resolve`. ⚠ This row cited a local `OPTIMIZERS` const and `one_of` until the client adopted the shared vocabulary; that const was already `= SEARCH_METHODS`, so its MEMBERS never drifted — its MATCH RULE did, which is the field below. |
| `--out`              | crates/vike-cli/src/cmd/backtest.rs's `refuse_foreign_read_flags` (the `!matches!(a.sub, ReadSub::Ls \| ReadSub::Show) && a.out.is_some()` rule); crates/vike-cli/src/cmd/runs/ls.rs's `run_ls`; crates/vike-cli/src/cmd/runs/show\.rs's `run_show`                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `--param`            | crates/vike-cli/src/cmd/backtest.rs's parse\_run\_args (the `"--param"` arm); crates/vike-cli/src/cmd/backtest.rs's looks\_like\_a\_search\_axis                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `--preset`           | crates/vike-cli/src/cmd/backtest.rs's merge\_preset\_params; crates/vike-cli/src/cmd/backtest.rs's parse\_run\_args (the `"--preset"` arm)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `--profile`          | crates/vike-cli/src/cmd/backtest.rs's parse\_run\_args (the `"--profile"` arm assigns `profile_path = Some(flags.value(&flag, inline)?)`); crates/vike-cli/src/cmd/backtest.rs's execute reads it into `base` and hands it to build\_profile\_toml                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `--rank-by`          | crates/vike-cli/src/cmd/backtest.rs's `Args::rank_by`, `Args::search_requested` and `parse_run_args`'s `"--rank-by"` arm (which calls `accept_value`); crates/vike-datahub-client/src/flag\_vocab.rs's `RANK_METRICS` and `accept_value`; crates/vike-backtest/src/harness/search\_select.rs's `resolve_rank`; crates/vike-backtest/src/harness/sweep.rs's `RankMetric`                                                                                                                                                                                                                                                                                                                                       |
| `--script`           | crates/vike-cli/src/cmd/backtest.rs's inject\_script\_src and its SRC\_KEY; crates/vike-cli/src/cmd/backtest.rs's implied\_defaults and the named `--script` rule in `refuse_foreign_read_flags`; crates/vike-cli/src/cmd/strategies.rs's `run_script_check`                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `--seed`             | crates/vike-cli/src/cmd/backtest.rs's `Args::seed` and `parse_run_args`'s `"--seed"` arm; crates/vike-backtest/src/harness/search\_select.rs's `parse_seed`, `require_seed` and `resolve`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `--set`              | crates/vike-cli/src/cmd/backtest.rs's parse\_run\_args (the `"--set"` arm computes `let head = key.split('.').next().unwrap_or("")` and tests `PROFILE_TOP_LEVEL_KEYS.contains(&head)`); crates/vike-cli/src/cmd/backtest.rs's set\_profile\_key                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `--show-effective`   | crates/vike-cli/src/cmd/backtest.rs's execute (`if args.show_effective \{ print!(...); return Ok(()); }`); crates/vike-cli/src/cmd/backtest.rs's render\_effective                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `--slippage`         | crates/vike-cli/src/cmd/backtest.rs's SUGAR (row `--slippage` -> `engine.slippage`, Shape::Scalar)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `--sort`             | crates/vike-cli/src/cmd/runs/ls.rs's `sort_rows`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `--store`            | crates/vike-cli/src/cmd/backtest.rs's `Args::store`, `parse_run_args`'s remote-arm refusal loop and `execute_local`; crates/vike-backtest/src/backtest\_cli.rs's `store_root`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `--strategy`         | crates/vike-cli/src/cmd/backtest.rs's SUGAR (row `--strategy` -> `strategy.name`); pinned by crates/vike-cli/src/cmd/backtest.rs's a\_strategy\_name\_is\_forwarded\_unvalidated; the conditional default is crates/vike-cli/src/cmd/backtest.rs's implied\_defaults                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `--symbol`           | crates/vike-cli/src/cmd/backtest.rs's parse\_run\_args (the Shape::StrList arm accumulates into `symbols`; the post-loop block pushes one Override with Origin::Sugar("--symbol")); pinned by crates/vike-cli/src/cmd/backtest.rs's symbol\_is\_repeatable\_and\_comma\_splitting\_and\_yields\_one\_override                                                                                                                                                                                                                                                                                                                                                                                                 |
| `--to`               | crates/vike-cli/src/cmd/backtest.rs's SUGAR (row `--to` -> `data.to`, Shape::Str)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `--trades`           | crates/vike-cli/src/cmd/backtest.rs's `refuse_foreign_read_flags` (the `!matches!(a.sub, ReadSub::Show \| ReadSub::Diff) && a.trades` rule, and the ⚠ comment above `show_only` saying why it is not in that array); crates/vike-cli/src/cmd/runs/show\.rs's `show_text`; crates/vike-cli/src/cmd/runs/diff.rs's `run_diff`                                                                                                                                                                                                                                                                                                                                                                                   |
| `--trials`           | crates/vike-cli/src/cmd/backtest.rs's `Args::trials` and `parse_run_args`'s `"--trials"` arm; crates/vike-cli/src/cmd/backtest.rs's `execute_local`; crates/vike-backtest/src/harness/search\_select.rs's `parse_trials` and `METHOD_KNOBS`; crates/vike-backtest/src/harness/tpe.rs's `DEFAULT_TRIALS`                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--venue`            | crates/vike-cli/src/cmd/backtest.rs's SUGAR (row `--venue` -> `data.venue`, Shape::Str); crates/vike-backtest/src/harness/profile.rs's DataCfg                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `--where`            | crates/vike-cli/src/cmd/backtest.rs's `refuse_foreign_read_flags` (`ls_only`); crates/vike-cli/src/cmd/runs/where\_expr.rs's `OPS` and `filter`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `--write-profile`    | crates/vike-cli/src/cmd/backtest.rs's execute (the `args.write_profile` block sits BELOW both client-side rewrites and above the show\_effective return)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `--write-strategy`   | crates/vike-cli/src/cmd/strategies.rs's `run_templates`; crates/vike-cli/src/cmd/backtest.rs's `ReadArgs::write_strategy` and the `templates_only` roster in `refuse_foreign_read_flags`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `--explain-data`     | crates/vike-backtest/src/data\_plan.rs's `plan_data` and `explain_lines`; crates/vike-cli/src/cmd/data.rs's `explain_data_override`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `--require-coverage` | crates/vike-backtest/src/data\_plan.rs's `enforce` and `coverage_verdict`; crates/vike-data/src/coverage.rs's `window_shortfall`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `--max-gap`          | crates/vike-backtest/src/data\_plan.rs's `CoverageGate`; crates/vike-cli/src/cmd/data.rs's `max_gap_override`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `--on-gap`           | crates/vike-backtest/src/data\_plan.rs's `CoverageVerdict`; crates/vike-backtest/src/harness/profile.rs's `DataCfg::on_gap`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `--universe`         | crates/vike-backtest/src/data\_plan.rs's `universe_verdict` and `UniverseMode`; crates/vike-backtest/src/harness/profile.rs's `DataCfg::universe`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

### Related [#related]

[Parameter search](/docs/trader/reference/cli/sweep) and [walk-forward](/docs/trader/reference/cli/walkforward) are not sub-verbs of `backtest` — both are `backtest run` with a different profile table — and moved off this page's bar entry for that reason. They cover the `[paramscan]` and `[walkforward]` tables named above in full.

***



# Research (/docs/trader/reference/cli/research)



| Verb                                                    | What it owns                                                                    |
| ------------------------------------------------------- | ------------------------------------------------------------------------------- |
| [indicators](/docs/trader/reference/cli/research/indicators) | Every indicator function a Rhai strategy can call, with parameters and defaults |
| [backtest](/docs/trader/reference/cli/research/backtest)     | Compute a strategy over history and judge what came back — the one executor     |
| [research](/docs/trader/reference/cli/research/research)     | Investigate a signal and fit a **model** — the plane before a strategy exists   |


# vike-cli indicators (/docs/trader/reference/cli/research/indicators)



`indicators` prints the indicator functions a Rhai strategy can **call**, grouped by category, each
with its parameters and the defaults you get by leaving them out. It is offline: no store, no
settings, no credential.

It exists as a command rather than a sentence in a README because the claim cannot be written down.
The scaffolded `user_data/strategies/rhai/README.md` tells you the host binds the whole
`vike-indicators` catalog; on a release install there is no source tree to check that against, and a
roster written into prose is wrong the first time an indicator is added. So the roster is printed off
the same derived list the host binds from.

## Flags [#flags]

| flag              | meaning                                                        |
| ----------------- | -------------------------------------------------------------- |
| `--name NAME`     | just this one — or, if it is not callable, **why** not         |
| `--category NAME` | only this category, matched case-insensitively; built-ins only |
| `--json`          | machine-readable rows instead of the grouped listing           |
| `-h`, `--help`    | the usage text, on stdout, exit 0                              |

`--name` and `--category` ask different questions and are mutually exclusive — passing both is a
usage error rather than one of them being silently ignored. An unknown `--category` is an error that
names the categories this build has, because an empty answer to a typo is indistinguishable from
"this build binds nothing in that family".

## It prints the bound set, never the registry [#it-prints-the-bound-set-never-the-registry]

Every row is a name `vike_script::RHAI_INDICATORS` carries — what
`crates/vike-script/src/engine.rs`'s `register_indicators` actually registers — joined onto its
`vike_indicators::registry()` metadata for the label, the parameters and the output lines.
`crates/vike-cli/src/cmd/indicators.rs`'s `bound_metas` is that filter, and it also admits an
indicator reachable **only** through a per-line accessor: `bollinger`'s bare name is refused because
line 0 is the upper band, but `bollinger_mid(20)` is callable, and a roster omitting it would say a
band indicator is unreachable when it is not.

<Callout type="warn" title="A name this command does not print is not callable — and it still compiles">
  Rhai resolves a function name when the line **runs**. A script naming an unbound indicator therefore
  compiles, raises on every bar, and self-disables after the consecutive-error cap — mounted, and
  silently never trading. That is why `--name` on a missing name **exits non-zero** and separates the
  two ways a name can miss: "not in the registry at all" versus "a real indicator this host does not
  bind", the second carrying the host's own reason from `vike_script::unbound_reason` rather than a
  paraphrase. An exit 0 would make *not callable* indistinguishable from a successful lookup to
  anything scripting this command.
</Callout>

## The call form is the whole point of a row [#the-call-form-is-the-whole-point-of-a-row]

Each row prints `name(param=default, …)` with every parameter spelled out. The host registers one
form per argument count, from zero up to the full list, so a row is simultaneously the widest call
and the answer to *what do the ones I leave out become*. Rows are grouped by category in
first-appearance order, so the registry's curated grouping survives, and a row names its output line
only when that differs from the indicator's own name. The footer counts what was printed — the only
number this feature states, and it is stated nowhere in prose.

## Your own indicators [#your-own-indicators]

`user_data/indicators/*.rhai` are callable from the same script by the same spelling, and they are
listed in their own block under `your own (user_data/indicators)`. Listing only the built-ins told an
author their own indicator did not exist — the same *a name this command does not print is not
callable* reading, pointed at the one indicator they are surest about.

The block is derived from `vike_script::installed_user_indicators`, joined to
`installed_user_indicator_params` for the knobs and to `installed_user_bare_call` and
`installed_user_line_accessors` for the spellings that resolve. It reads **process state, not a
directory**: the dispatcher already did the I/O, and a listing that re-scanned the folder could print
an indicator this process never installed and therefore cannot call.

```text
your own (user_data/indicators)
  my_ema(period=20, scale=1.5)
  my_flag()
  my_bands_mid(width=2)          -> mid
```

The bare name is printed only when it **binds**. A file declaring `fn outputs()` whose line 0 is not
its namesake has no bare name — the same refusal `bollinger` carries — and printing one anyway would
print a call that raises on every bar. The line accessors are printed instead, so the block always
names a way in. A file declaring no `param()` renders `name()`, with the empty parentheses, because a
bare `name` would read as a value rather than a call.

`--category` never matches one of yours, and that is the honest answer rather than a gap: a user
indicator has no category, so no category can contain one. `--name` does resolve one, and searches
them **first**.

## `--json` [#--json]

Both keys are always emitted, `indicators` and `user_indicators`, including as empty arrays — a
consumer that has to test for a key before reading it is one `--name` away from a crash. A built-in
row carries `name`, `pretty`, `category`, `params`, `outputs`, `accessors` and `bare_call`. A user row
carries `name`, `params`, `accessors`, `bare_call` and `source`, and deliberately no `category`,
`pretty` or `outputs` — spelling those as empty would tell a consumer the fields exist and happen to
be blank.

<Callout type="warn" title="One declared residual">
  `--name` matches the file's or indicator's own name, not a per-line accessor. `--name bollinger_mid`
  reads "no indicator named", which is wrong about a spelling this command's own `--json` output
  carries. It is narrower for a user indicator, whose block names every accessor one screen away.
</Callout>

## See also [#see-also]

* [The indicator catalog](/docs/trader/indicators) — every built-in, by category
* [Writing an indicator](/docs/trader/scripting/writing-an-indicator) and [loading indicators](/docs/trader/scripting/loading-indicators)
* [`vike-cli init`](/docs/trader/reference/cli/set-up/init) — what ships in `user_data/indicators`
* [The scripting cheatsheet](/docs/trader/scripting/cheatsheet) — every host function in one page


# vike-cli research (/docs/trader/reference/cli/research/research)



`vike-cli research` is a plane, not a single command. It groups the tools that investigate a signal and fit a model — the step *before* a strategy exists to backtest. `backtest` computes a strategy's PnL over history; `research` produces the model a strategy will later be built on. Today the plane has exactly one subcommand, `study`. It runs from wherever the CLI is invoked, but the work itself happens on the compute daemon: `study` asks that daemon to run a compiled study next to the hist store the daemon holds, over the same daemon address `backtest` resolves.

The top level names planes this way on purpose — `backtest` (compute a strategy over history), `research` (investigate a signal, fit a model), `data` (market history), `trade` (live) — and a study belongs to none of the other three: it drives a LightGBM child process per fold and produces a fitted **model**, not a PnL curve. `research` is the area; `study` is one unit of work inside it, compiled from `<project>/user_data/research/studies/rust/<name>/` into a registry by `crates/vike-user-research`'s `build.rs`.

## Usage [#usage]

```text
vike-cli research <subcommand> [options]
```

One subcommand exists today:

```text
vike-cli research study --study NAME --recipe FILE --from WHEN --to WHEN [--addr host:port]
```

`--study NAME` names the entry in the compiled study registry. `--recipe FILE` is a recipe, not a profile — `study` takes its own parameter-file shape, deliberately distinct from `backtest`'s strategy profiles. `--from WHEN` and `--to WHEN` bound the range of history the study runs over. `--addr host:port` overrides the resolved daemon address for that one call.

```sh
vike-cli research study --study btc-momentum --recipe recipes/btc-momentum.toml --from 2026-01-01 --to 2026-06-01
```

Typing `-h`, `--help`, or `help` in the subcommand slot prints help instead of erroring — the same generic help arm every other verb uses. Leaving the subcommand off, or putting a flag where it belongs, prints the plane's usage; there is no bare `vike-cli research` and no default subcommand.

### The daemon address [#the-daemon-address]

`research study` dials the same compute daemon `backtest` does, through the same address ladder. The `configured_addr` argument threaded into `research`'s `run` is `config.backtest_addr`, resolved once by the CLI's composition root — the middle rung of that ladder — the ladder's own order is not re-derived here, and `research.rs`'s own doc says so directly: `resolve_addr` is `crate::cmd::backtest`'s, and this file does not repeat it. See [backtest](/docs/trader/reference/cli/research/backtest) for the full ladder. `run` also receives `keys: Option<&NodeKeys>` — the daemon-auth credential — threaded straight through to `study`'s own entry point unchanged.

<Callout type="warn" title="No daemon serves this yet">
  `research`'s own usage text says so directly:

  ```text
  study    ask the backend to run a compiled study over the hist store IT holds. ⚠ No backend
           serves this yet — it refuses and names `vike-backend study`, which does
  ```

  On every box today, `vike-cli research study` reaches a compute daemon that has not mounted a study runner and refuses by name. `vike-backend study` and the standalone `vike-study` binary — a different program, and a separate decision — are what actually runs a study; this CLI does not rename or wrap either one, and every failure `research study` can produce names that one working invocation instead.
</Callout>

## study flags [#study-flags]

| flag               | meaning                                                    |
| ------------------ | ---------------------------------------------------------- |
| `--study NAME`     | the compiled study's name in the research registry         |
| `--recipe FILE`    | the study's own recipe file (not a strategy profile)       |
| `--from WHEN`      | start of the history range the study runs over             |
| `--to WHEN`        | end of the history range the study runs over               |
| `--addr host:port` | override the resolved compute-daemon address for this call |

<Callout type="warn" title="More of `study`'s grammar lives past this router">
  `research` hands every argument after `study` straight to `study`'s own parser without re-parsing it. That parser's grammar is disjoint from every other verb in the CLI, and it owns three refusals of its own beyond the flags above: `--store` and `--lightgbm`, which name paths on the *backend's* box rather than this one, and `--json`, which has nothing to format yet. Their exact wording belongs to `study`, not to this page.
</Callout>

## Related [#related]

* [backtest](/docs/trader/reference/cli/research/backtest) — computes a strategy's PnL over history, once a study has produced a model; dials the same compute daemon through the same address ladder.
* [data](/docs/trader/reference/cli/data/data) — the market-history plane.
* [trade](/docs/trader/reference/cli/trade/trade) — the live plane; its one-shot verbs are the precedent, inside this CLI, for a sub-verb owning its own argument parser — the shape `study` uses here.


# vike-cli backend (/docs/trader/reference/cli/set-up/backend)



`vike-cli backend` stands a `vike-tradehub` node's authentication up on the machine running it, and attaches a separate client machine to a node that is already running. It has two halves, and each runs on a different box — getting that right is the one thing to know before typing anything else:

* **`backend setup`** runs on the **daemon's box** — the machine actually running `vike-tradehub`. It mints two keys, writes them into that box's own store, and never prints a key value.
* **`backend connect`*&#x2A;, &#x2A;*`backend status`*&#x2A;, and &#x2A;*`backend disconnect`** run on the **client's box** — a laptop, a container, anywhere that wants to reach the daemon. They raise or close an SSH tunnel, take the two keys `setup` minted, and prove the connection with a real round trip against the node.

"Node" means the running `vike-tradehub` daemon: one process holding the live core, its venue mounts, and its authenticated socket. It is not Node.js and it is not rented compute — the word survives in the protocol (`--node`, the `node.env` file) even though the verb itself was renamed from `vike-cli node` to `vike-cli backend`, because "node" read as something else to people arriving from outside this codebase.

No subcommand here can print, log, or journal a key value, on any path. What reaches the screen instead is each key's `key_id` — a derived, non-reversible fingerprint (`crates/vike-cli/src/cmd/node/mod.rs`'s `key_id`) that is safe to paste anywhere. Comparing the two ids `setup` printed on the daemon's box against the two `connect` or `status` print on the client's box is this design's whole answer to "did I just attach to the right node."

## Usage [#usage]

```text
vike-cli backend setup       [--addr HOST:PORT] [--control] [--rotate]
vike-cli backend connect HOST [--port N] [--manual] [--no-tunnel] [--replace]
vike-cli backend status
vike-cli backend disconnect  [--port N]
```

A flag scoped to the other box is refused by name rather than silently dropped — `--control` on `connect`, or `--manual` on `status`, fails immediately and says which box the flag belongs on (`crates/vike-cli/src/cmd/node/mod.rs`'s `check_flag_scope`). That matters most for `--control`: silently accepted on the wrong box, it would leave an operator believing the daemon's write channel was armed when nothing armed it.

### `setup` — on the daemon's box [#setup--on-the-daemons-box]

Mints both node keys from the OS CSPRNG (32 bytes each, hex-encoded), writes them into this box's store, sets the bind address, and prints each key's id plus a restart line. Run it once, on the machine actually running `vike-tradehub`:

```sh
vike-cli backend setup
```

<Callout type="warn" title="Nothing here accepts a key, on any path">
  `setup` mints both keys itself — there is no argv form, no stdin form, and no `--from-env` form to refuse, because there is no operator-supplied value to accept. The one path on which a human ever touches key material is `connect --manual`, and only there.
</Callout>

The default bind address is `127.0.0.1:7879`. To bind somewhere else and arm the write channel in one step:

```sh
vike-cli backend setup --control --addr 0.0.0.0:9100
```

<Callout type="warn" title="--control is never the default and never inferred">
  `flags.tradehub_control` is written only when `--control` is passed. A box with fresh keys and no `--control` mints the control key but never writes `flags.tradehub_control`, so nothing on the daemon side has been told to trust it — run `setup --control` once you mean to arm the write channel (`crates/vike-cli/src/cmd/node/setup.rs`'s `CONTROL_FLAG_KEY`).
</Callout>

Running `setup` again on a box that already has keys refuses rather than reissuing them:

```
$ vike-cli backend setup
OBSERVE_KEY and CONTROL_KEY already in .../settings/node.env, and `setup` will not silently
replace a key some client is signing with.
⚠ Re-run with --rotate to replace BOTH keys. Every client already holding the old ones — a
laptop's vike-cli, a vike-app --observe, a thin container — stops working the moment the daemon
restarts, and its symptom is an auth denial that reads like a revoked credential.
Nothing was written.
```

Pass `--rotate` once you mean it:

```sh
vike-cli backend setup --rotate
```

<Callout type="warn" title="A rotation detaches every other client">
  `--rotate` replaces both keys and preserves every other line already in the store (`crates/vike-cli/tests/node_cli.rs`'s `rotate_replaces_both_keys_and_preserves_the_rest_of_the_store`), but every client still holding the old pair fails its next handshake with an auth denial that reads like a revoked credential rather than like a rotation. Re-run `backend connect` on each of them afterward.
</Callout>

Every successful `setup` — first run or rotation — ends the same way, because the daemon reads both keys once at start and never re-reads them (`crates/vike-cli/src/cmd/node/setup.rs`'s `report`):

```sh
sudo systemctl restart vike-tradehub          # a systemd deployment
docker restart vike-tradehub                  # the container
```

### `connect HOST` — on the client's box [#connect-host--on-the-clients-box]

Raises an SSH tunnel to `HOST` (`-N -f` under the hood, so a taken port or an unreachable host fails synchronously rather than sitting there forwarding nothing), optionally takes the two keys, records the dial address, and finishes with a live round trip against the node.

On a first attachment, pipe both keys in:

```sh
printf '%s\n%s\n' "$OBSERVE" "$CONTROL" | vike-cli backend connect my-node --manual
```

<Callout type="warn" title="Keys never go on the command line">
  `--manual` reads two lines from stdin — observe, then control — and is the only way a key value reaches this command. A second positional after `HOST` is refused (`crates/vike-cli/tests/node_cli.rs`'s `a_key_never_goes_on_the_command_line`): argv lands in shell history and in `ps` output for every other user on the box. A blank second line means observe-only — a client that can watch the node and place nothing.
</Callout>

Without `--manual`, `connect` writes nothing to the store: it raises the tunnel, records the dial address, and verifies with whatever keys this box already resolves (the process environment first, then the store). That is the ordinary second and later run:

```sh
vike-cli backend connect my-node
```

A client already inside the trust boundary can skip the tunnel and dial the daemon directly:

```sh
vike-cli backend connect my-node --no-tunnel
```

A successful run ends with the round trip (`crates/vike-cli/src/cmd/node/connect.rs`'s `verify`):

```
verified: node my-node — LIVE — build 0.1.24
  reached at 127.0.0.1:7879, 3 mount(s)
  observe key id 4f2a…
⚠ compare those ids with the ones `vike-cli backend setup` printed on the daemon's box. They
match, or you are talking to a different node.
```

<Callout type="warn" title="A local key that disagrees with the incoming one is a refusal, not a silent switch">
  If this box already holds a different value for a key name than the one `--manual` was just given, `connect` refuses and prints both key ids rather than detaching whatever the old key reached (`crates/vike-cli/src/cmd/node/connect.rs`'s `replace_refusal`). Pass `--replace` once you mean to point this client at a different node.
</Callout>

### `status` — on the client's box [#status--on-the-clients-box]

Reports the dial address, which keys resolved and from where, and whether the node answers right now — it prints the configuration half even when the round trip fails, so a bad address or a missing key is diagnosable from the same command that would otherwise just hang:

```sh
vike-cli backend status
```

```
dial address: 127.0.0.1:7879   (config.node_addr)
OBSERVE_KEY                4f2a…   read plane, from the store
CONTROL_KEY                9b1c…   write plane, from the process environment
⚠ a write key resolved here; whether the NODE admits orders is flags.tradehub_control on the
daemon's box, which this side cannot read.
```

On a box that has never attached, it names exactly what is missing rather than printing an empty table or dialling nothing (`crates/vike-cli/tests/node_cli.rs`'s `status_on_an_unattached_box_names_what_is_missing`):

```
$ vike-cli backend status
dial address: NONE — config.node_addr is unset, so every node verb still needs --node
OBSERVE_KEY                absent          read plane
CONTROL_KEY                absent          write plane
vike-cli backend: no config.node_addr on this box, so there is no node to ask. `vike-cli backend
connect <host>` records one; `--node HOST:PORT` still names one per command.
```

### `disconnect` — on the client's box [#disconnect--on-the-clients-box]

Closes the tunnel `connect` raised:

```sh
vike-cli backend disconnect
```

It matches the recorded forward spec, not a process id — `ssh -f` has already forked and exited by the time `connect` returns, so there is no child handle to hold onto (`crates/vike-cli/src/cmd/node/connect.rs`'s `run_disconnect`). Running it with no recorded tunnel succeeds and says so, rather than failing on a state you already have:

```
no tunnel recorded by `vike-cli backend connect` on this box — nothing to close. (A tunnel
raised by hand is not recorded here; close it where you raised it.)
```

`--port N` closes a forward on that port even when nothing was recorded for it (it still checks the recorded port first, then falls back to a plain `-L N:localhost:N` match with no host filter):

```sh
vike-cli backend disconnect --port 9200
```

<Callout type="warn" title="disconnect is not automated on Windows">
  `pkill -f` has no equivalent this workspace can reach without a Win32 call its lint policy forbids, so on Windows `disconnect` refuses and prints the exact command to run by hand instead:

  ```powershell
  Get-CimInstance Win32_Process -Filter "Name='ssh.exe'" |
    Where-Object CommandLine -like '*7879:localhost:7879*' |
    ForEach-Object { Stop-Process -Id $_.ProcessId }
  ```
</Callout>

## Flags [#flags]

| Flag               | Subcommand              | Meaning                                                                                                |
| ------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------ |
| `--addr HOST:PORT` | `setup`                 | Address the daemon binds (default `127.0.0.1:7879`)                                                    |
| `--control`        | `setup`                 | Also set `flags.tradehub_control = true`, admitting order commands from a peer holding the control key |
| `--rotate`         | `setup`                 | Replace keys already in the store                                                                      |
| `--port N`         | `connect`, `disconnect` | Node port to forward, dial, or close (default `7879`)                                                  |
| `--manual`         | `connect`               | Read both keys from stdin, one per line: observe, then control                                         |
| `--no-tunnel`      | `connect`               | This client is already inside the trust boundary — dial `HOST` directly, raise no forward              |
| `--replace`        | `connect`               | Overwrite a local key that differs from the incoming one                                               |
| `-h`, `--help`     | all                     | Print usage                                                                                            |

## The store [#the-store]

`setup` and `connect --manual` write into `<project>/settings/node.env` — the two node key names, kept apart from the much larger venue credential store so a reader of one need not open the other. Neither verb creates that file: an absent store is refused, naming the command that makes one (`crates/vike-cli/src/cmd/node/mod.rs`'s `open_store`):

```sh
install -m600 /dev/null <project>/settings/node.env
```

If this box already has node keys under the old, shared credential file, they are still read from there — the refusal above is only about where the *next write* lands, not about losing keys that already exist.

`$VIKE_SETTINGS_DIR` names the settings directory outright, for a run against a project other than the one the working directory sits under.

## Related [#related]

* [secrets](/docs/trader/reference/cli/set-up/secrets) — the venue credential store `backend`'s writes are kept apart from. Its own missing-store refusal points at `install -m600 /dev/null <path>`, never at `secrets path` or `secrets template` — those read a different file shaped for a different roster.
* [mcp](/docs/trader/reference/cli/mcp) — advertises no tool that can reach either of `backend`'s credential writers


# vike-cli config (/docs/trader/reference/cli/set-up/config)



`config` has two verbs. They read the **same** directory through the **same** loader and differ in
what they produce.

```
usage: vike-cli config <verb> [options]

verbs:
  show    every setting, its effective value, and WHERE that value came from
  check   validate this box's settings tree + credential store; the EXIT CODE is the product

run `vike-cli config <verb> --help` for a verb's own options
```

`show`'s product is a table; its exit code says only whether the loader refused, so nothing there
can be put in front of a daemon. `check`'s product is the **exit code**, which is what the shipped
`deploy/*.service` units put in an `ExecStartPre=` (`crates/vike-cli/src/cmd/config.rs`,
`crates/vike-cli/src/cmd/config_check.rs`).

## `config show` — provenance [#config-show--provenance]

```
usage: vike-cli config show [--json] [--filter <substr>] [--changed-only] [--section files|env|all]
```

| flag                | meaning                                                                                                                                                                                                                                                                                     |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--section`         | which half to print. `files` = the settings TOMLs; `env` = the environment-variable registry; `all` (default) = both. The env half is several hundred rows, and the question that motivated the files half — &#x2A;did my `policy.toml` get read?* — should not require scrolling past them |
| `--filter <substr>` | case-insensitive substring match on the setting name or key, or on the reading crate or file, so `--filter reconcile`, `--filter bridges/okx` and `--filter policy` all work                                                                                                                |
| `--changed-only`    | only rows something actually configured — the "what have I set?" view                                                                                                                                                                                                                       |
| `--json`            | one object carrying the settings directory, the per-file status, both row sets and the loader's warnings                                                                                                                                                                                    |

**The files half** covers `<project>/settings/{policy,config,preferences,flags}.toml`, and its
provenance is exact: an origin is decided by key **presence** in a parsed layer, so a `policy.toml`
that sets a key to the same number as the code default still reports `policy.toml`. That half is why
the command exists in this shape — a risk ceiling can only be set in a file, and until this existed
**nothing anywhere printed whether that file had been read**. A typo'd filename, or a directory
resolved from the wrong project, produced a silently uncapped node. See
[settings](/docs/trader/reference/settings) and [policy](/docs/trader/reference/settings/policy).

**The env half** is the registry of every environment variable the workspace reads. Precedence
there is **process env > the credential store > documented default**, and the printed `source` is
the store that *won*, not the highest store that merely holds a key. Presence wins, not
non-emptiness: an exported `NAME=` overrides the store with an empty string and is reported honestly.

<Callout type="warn" title="`source` is what the stores support; `READS` is what the reader does">
  Most consumers read exactly one store, so a `source` word alone would assert a provenance the tool
  cannot verify. Each row therefore prints `READS`: `env` for a direct `env::var`, `caller-map` for a
  map the caller supplies, `unknown` for a computed name. A row whose value came only from the
  credential store while its reader calls `env::var` is named in a warning under the table — a real
  case that used to print a flat, confident `dotenv`. The `Layer` column is **not** that signal: it
  records where a read lives, not which store it consults.
</Callout>

Every row in the files half also carries &#x2A;*`READ`**, and the cell names the *binary* where one can
be derived. Attributing a value to a file and printing its origin asserts the value is in force;
when nothing reads it, that assertion is positive confirmation of something false. A clean install
found five keys in exactly that state, and a later one on a headless box found three more reporting
`READ: yes` whose only reader is the GUI, which will never run there. A `NO` is followed by what
reads the key's environment variable instead; `policy.*` keys are exempt, having their own gate.

<Callout type="warn" title="The default env table discloses which venues and tiers this box holds credentials for">
  The registry declares the whole `{VENUE}_{TIER}_API_*` grid, so the table **names** every one of
  those keys and marks each `<set>` or `<unset>`. No **value** can leak: redaction happens inside the
  resolver rather than in either printer, so `--json` cannot leak what the tables hide, and a
  secret-shaped row prints `<set>`/`<unset>` while still reporting its true source. `--changed-only` is
  the wrong instinct here and reads like the right one — it keeps precisely the rows something set, so
  on this table it prints exactly that list. &#x2A;*The narrow view for a paste is `--filter`.**
</Callout>

Store keys matching no registry row print as a complement under the env table — credential-shaped
ones counted and never named, everything else named outright — because a typo'd variable used to
look exactly like one that was never set.

## `config check` — the pre-flight [#config-check--the-pre-flight]

```
usage: vike-cli config check [--json] [--strict]

  --json      the same report as one JSON object
  --strict    promote every WARNING to a failure. For an operator asking `is this box fully
              configured?`, NOT for a systemd ExecStartPre= — it refuses a paper deployment
              over an absent-but-legitimate configuration

exit 0 = nothing is broken; exit 1 = something the operator believes is configured is not
```

The three levels are not severities anyone tuned. Each row is an argument, decided by the same rule
[startup preflight](/docs/trader/concepts/startup-preflight) applies: **refuse** when a silent difference
would leave the operator believing a protection is armed when it is not; **degrade** when
"unconfigured" is a legitimate state the operator may have chosen.

| finding                                                  | level                                                        |
| -------------------------------------------------------- | ------------------------------------------------------------ |
| a removed environment variable is set                    | fail — the operator asked for a ceiling and does not have it |
| a settings file fails to load                            | fail — the same refusal a daemon performs                    |
| the credential store exists and cannot be read           | **warn, or fail when this box is armed for live**            |
| `VIKE_SETTINGS_DIR` names a path that is not a directory | fail — set-but-unhonoured                                    |
| no settings directory at all                             | warn — the ordinary state of a fresh clone and of CI         |
| the credential store is **absent**                       | **ok** — absent credentials *are* the live gate              |
| the store is readable beyond its owner                   | warn — a finding is never a refusal                          |
| a pre-one-store `<project>/.env` beside an absent store  | warn                                                         |

The absent-store row is what makes the verb installable at all: every shipped unit is a paper
deployment with an empty store, so failing there would make a correct fresh install unstartable.

The one arming-aware row reads two independent sources and **never the credential store** — the
store is the thing that could not be read. One is the venue-scoped arming table over the process
environment; the other is the resolved `flags.tradehub_live`, which is node-scoped and so speaks for
the switchless venues that pick their tier from a credential prefix inside the unreadable file. A
settings tree that did not load yields an **undetermined** verdict, which refuses: answering "not
armed" from a missing signal is the bug this row exists to catch. See
[risk and arming](/docs/trader/concepts/risk-and-arming).

Output is `OK`/`WARN`/`FAIL` per finding, then `N error(s), M warning(s).`, followed by a verdict
sentence when anything failed or warned. On failure one line also goes to **stderr**, so
`journalctl -p err` catches an `ExecStartPre=` refusal without anyone reading the whole report; the
report stays on stdout whatever the verdict.

<Callout type="warn" title="On one shipped layout --strict calls a correct install an error">
  A recorder needs no credentials, so its runbook creates a `<project>/.env` and no `secrets.env`.
  Absent store plus a `<project>/.env` is exactly the pair the legacy-store warning fires on — a
  pre-one-store leftover and a systemd `EnvironmentFile` are the same file to anything that does not
  read it. So `--strict` there exits 1 with a single `credential store` warning. That is audit mode
  being literal; the units run the **default** disposition.
</Callout>

Both verbs answer `--help` on stdout with exit 0, at the verb level and at the `show`/`check` level
alike — see [global flags](/docs/trader/reference/cli/global-flags). For the credential store itself,
[`vike-cli secrets`](/docs/trader/reference/cli/set-up/secrets) is the surface that names keys.


# Set up (/docs/trader/reference/cli/set-up)



Four verbs, none of which compute anything. Each owns one part of the state every other verb reads:
a project layout, a settings tree, a credential store, and a running node's own key pair.

| Verb                                            | What it owns                                                                             |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------- |
| [init](/docs/trader/reference/cli/set-up/init)       | Scaffolds `<project>/user_data` — strategies, profiles, results — with runnable examples |
| [config](/docs/trader/reference/cli/set-up/config)   | This box's settings: provenance, a validating pre-flight, a journalled one-key write     |
| [secrets](/docs/trader/reference/cli/set-up/secrets) | The venue credential store — key **names**, never values                                 |
| [backend](/docs/trader/reference/cli/set-up/backend) | Stands a `vike-tradehub` node's keys up on its own box, and attaches a client box to it  |


# vike-cli init (/docs/trader/reference/cli/set-up/init)



`init` creates `<project>/user_data` — the half of the project a program must never author — fills
every folder with runnable examples, and prints the map. Printing the map is not a flourish: the
answer to &#x2A;what is all this?* arrives before you open a file manager, rather than after you go
looking for a README.

## Flags [#flags]

| flag           | meaning                                                     |
| -------------- | ----------------------------------------------------------- |
| `--dir PATH`   | scaffold here instead of the resolved `<project>/user_data` |
| `--reset`      | restore the shipped examples that are missing or edited     |
| `--dry-run`    | print what would change, write nothing                      |
| `-h`, `--help` | the usage text, on stdout, exit 0                           |

`--reset` and `--dry-run` are bare booleans and reject an inline value (`--reset=yes` is a usage
error). `--dir` takes both forms.

## Re-running is the ordinary case [#re-running-is-the-ordinary-case]

A new version ships new examples, so the **default writes only what is absent**. A file you edited is
never touched, never diffed and never backed up, because the command has no business having an
opinion about it. Each shipped file is reported as one of three actions — `Created` (was absent),
`Restored` (existed, differed, and `--reset` was given), or `Kept` (identical, or edited and
protected) — so the output is a record of what the command *did*, never a claim about what it
intended. An existing file that cannot be read is treated as *different* rather than as a failure:
the question being asked is "does this match the sample?", and a file that cannot be read is not the
sample.

<Callout type="warn" title="--reset is narrow, and cannot reach a strategy you wrote">
  `--reset` overwrites the entries in `crates/vike-cli/src/cmd/init/mod.rs`'s `files` table and nothing
  else — that table is simultaneously the shipped set and the exhaustive list of what `--reset` can
  possibly destroy. A strategy you authored is not in it, so no combination of flags here deletes your
  work. What `--reset` *can* destroy is edits to a shipped example, which is exactly what it is for.
  `--dry-run` performs every comparison and writes nothing, so its report is the report the real run
  would produce.
</Callout>

## Where it writes [#where-it-writes]

`--dir` wins; otherwise the directory the dispatcher already resolved (`VIKE_USER_DATA_DIR`, else the
project walk). **With neither, this is an error, not a fallback to the working directory** —
scattering a `user_data/` tree into whatever directory somebody happened to be standing in is not a
recoverable mistake, and `--dir` says what they meant in one word.

The command writes only under the resolved `user_data/`. It creates no file in `settings/` and reads
no credential; `crates/vike-model/src/state_path.rs`'s `PROJECT_USER_DATA_DIR` argues the split, and
the point of it is that a tool inviting people to drop files somewhere never operates in the
directory holding live venue keys.

## The map [#the-map]

```text
user_data/               your work — nothing here is ever overwritten once you have edited it
  strategies/rhai/       interpreted strategies: edit, save, backtest. No toolchain needed.
  strategies/rust/       compiled strategies. SOURCE CHECKOUT ONLY — a release binary cannot build them.
  indicators/            your own indicators, one <name>.rhai each. Callable from any strategy.
  profiles/              run profiles: which data, which costs, which strategy
  backtest_results/      saved reports. One sample ships, so the notebooks work before your first run.
  notebooks/             analysis over the results above
  logs/                  compile.log — every strategy load, pass and fail. Look here first.
```

Every folder arrives populated, deliberately: a feature nobody can see is a feature nobody uses, and
an empty `strategies/rhai/` reads as setup somebody abandoned. `logs/` is the one exception — it ships
a README and no sample, because a sample log would be fiction. The Rhai folder ships three strategies
chosen one per **shape** (`sma_cross`, `rsi_meanrev`, `ema_trend`) rather than one per indicator,
since the host binds the whole catalog and three files could not sample it; each comes with its own
preset TOMLs. `indicators/` ships `donchian_high.rhai` and `streak.rhai`, `strategies/rust/` a
`my_experiment` template, `profiles/` the backtest, sweep and walk-forward profiles, and
`backtest_results/` one sample report so the notebook works before your first run.

## What it prints next [#what-it-prints-next]

The report ends with the sequence a new user actually needs, because `init` writes strategies and
profiles and writes **no market data** — the shipped profile names a slice an empty store does not
hold, which would otherwise be a run that completes with no trades and no explanation. So the report
names `backtest --seed-demo` for the synthetic demo tape, then `--fetch-starter` for a published
dataset that needs no venue, then `--fetch binance:BTCUSDT:1h --days 180` straight from the venue.
The store is not seeded from this command on purpose: writing a history store needs DataFusion, and
this binary is DataFusion-free by construction.

<Callout title="Your indicators are installed before any verb runs">
  `crates/vike-cli/src/lib.rs`'s `install_user_indicators` loads `user_data/indicators/*.rhai` and
  installs them process-wide before dispatch, so a script run by any subcommand can call them. Every
  rejected file is reported on **stderr** and a bad one never fails the command — one half-edited
  indicator blocking every invocation, including the `init` that scaffolds the examples, would be
  worse than the report.
</Callout>

## See also [#see-also]

* [Writing a strategy](/docs/trader/scripting/writing-a-strategy) and [writing an indicator](/docs/trader/scripting/writing-an-indicator)
* [Loading indicators](/docs/trader/scripting/loading-indicators) — how the directory is scanned
* [`vike-cli indicators`](/docs/trader/reference/cli/research/indicators) — what a script can actually call
* [The `backtest` binary](/docs/trader/reference/binaries/backtest) — what `--seed-demo` and `--fetch` belong to


# vike-cli secrets (/docs/trader/reference/cli/set-up/secrets)



There is one credential store, `<project>/settings/secrets.env`, and `secrets` is how you look at it
without opening it in an editor. Three subcommands read; **one writes, and only in one shape**: `set`
upserts a single named key into a store that already exists. There is deliberately no `rotate`, no
`delete`, no `--out` on `template` and no way to create a store from here: it is the user's only copy
of live venue credentials, so creating, moving or rewriting it is their decision, made with an
editor. `path` prints the location so they can.

## Subcommands and flags [#subcommands-and-flags]

| invocation         | what it does                                                                                                                                                                                                                                                                                                       |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `secrets list`     | the key **names** in the store — never a value — plus the accounts those names resolve to                                                                                                                                                                                                                          |
| `secrets path`     | the store's path, whether it is there, and whether its mode exposes it                                                                                                                                                                                                                                             |
| `secrets template` | an **empty** credential grid on stdout — per roster venue, the `SIM`/`DEMO`/`LIVE` × `_API_KEY`/`_API_SECRET`/`_API_PASSPHRASE` rows plus that venue's attribution keys. Not every name the workspace reads: the legacy `MAINNET` tier and the bespoke shapes are absent by design, and the emitted header says so |
| `secrets set KEY`  | upsert **one** credential into the project's **existing** store, the value read from **stdin** (one line) — see [`set`](#set--the-one-writer-and-the-shape-it-is-held-to)                                                                                                                                          |
| `--from-env NAME`  | `set` only: take the value from the environment variable `NAME` instead of stdin, verbatim                                                                                                                                                                                                                         |
| `--file PATH`      | inspect this store instead of the project's (`list`, `path`). &#x2A;*Refused on `set`**: a write never takes an operator-supplied destination                                                                                                                                                                      |
| `--venue ID`       | `template` only: emit one roster venue's rows. Passing it to `list` or `path` is a named usage error rather than a silently ignored flag                                                                                                                                                                           |
| `-h`, `--help`     | the usage text, on stdout, exit 0                                                                                                                                                                                                                                                                                  |

## Which file, exactly [#which-file-exactly]

`path` answers the question an operator must be able to settle without reading source: &#x2A;which file
are my keys actually coming from?* The settings directory is found by walking up from the working
directory, and `VIKE_SETTINGS_DIR` names it outright, so the answer depends on where you are
standing. Both inspecting subcommands take the **same resolved directory the dispatcher hands every
other subcommand**, so this output cannot drift from what a daemon loads.

```text
store:  /srv/vike-tradehub/settings/secrets.env (present)
```

<Callout type="warn" title="Absent has three answers, not two">
  `Path::exists` maps every error to `false`, so a project root this process cannot search once
  reported the store as *absent* and then printed the fresh-install advice for what was really a
  permissions problem. `crates/vike-cli/src/cmd/secrets.rs`'s `Presence` uses `Path::try_exists`
  instead: `Ok(false)` is `NotFound` and nothing else. **Present**, **absent**, and **could not be
  determined** each print different words — the third shares no word with the other two, because an
  operator greps this line. An undetermined answer is a finding, not a refusal: it prints the path,
  says what was not established, and still exits 0, since `path` is what you run when something is
  already broken.
</Callout>

When the store is genuinely absent, `path` prints the three commands that create one — `mkdir -p`,
`$EDITOR`, and `chmod 600 … # it is plaintext credentials` — and, if a pre-one-store `.env` is
sitting beside it, `vike_secrets::legacy_store_warning` says so rather than letting *nothing here
reads any other location* stand unqualified.

## Permissions are reported, never enforced [#permissions-are-reported-never-enforced]

Both subcommands warn about an over-permissive mode. `list` always did, because it opens the store
and `vike_secrets::resolve` hands the finding back with the credentials; `path` never did, because it
opens nothing — so the command documented as the safe first one was the one that stayed silent about
a world-writable credential file. Measured on a clean install at modes 600, 640, 644, 664 and 666,
`path` printed **zero** warnings at every one while `list` warned from 640 up. `path` now asks the
same question through `vike_secrets::permission_warning`, which `lstat`s the file and follows a
symlink only far enough to `readlink` and `stat` it — never its contents. A finding is never a
refusal, so no exit code changes.

## `list` — names, and the accounts behind them [#list--names-and-the-accounts-behind-them]

The header names the file before the keys, because *where did these come from* is the question the
list itself cannot answer. Then the key names, then the accounts, derived from those same names
through `vike_model::account_keys::accounts_in_store`. That second block exists because two spellings
look identical to a reader and are not:

```text
HYPERLIQUID_LIVE_API_KEY__ALT     an account named ALT
HYPERLIQUID_LIVE_API_KEY_ALT      one underscore, and NOT an account
```

The grammar splits at a **double** underscore (`vike_model::account_keys::ACCOUNT_SEPARATOR`), so the
single-underscore spelling leaves the whole string as one base name belonging to the default account
— a credential that is silently inert. An account row is proof the labelled key was understood. The
row renders as `venue/TIER label`, with the unlabelled account shown as `(default)` rather than
`AccountLabel`'s own `DEFAULT`, which is the one spelling `AccountLabel::parse` refuses.

<Callout type="warn" title="This is a store disclosure and says nothing about arming">
  An account listed here is an account whose credentials exist. Whether it mounts is a separate,
  policy question, answered one level below the venue ceiling: `vike_config::VenuePolicy::account`
  resolves an account's mode as the lower of the venue's own line and that account's line in
  `policy.toml`'s `[accounts]` table, and `vike_mount::accounts_to_mount` mounts a labelled account
  only when the answer lands above `paper`.

  A labelled account with no line of its own therefore resolves `paper`: the venue line was written
  when the venue had one account, and reading it as consent for a second is the silent escalation the
  ceiling exists to prevent. Names the grammar recognises as no credential contribute no row, and that
  is a classification rather than a gap: attribution codes, the `POLY_*` L2 trio, Dukascopy's numbered
  sub-account, Aster's `TESTNET` tier.
</Callout>

## `template` — a shape, and a shape is safe to paste [#template--a-shape-and-a-shape-is-safe-to-paste]

Every name is derived from the venue roster (`vike_model::venues::VENUES`) crossed with the current
tiers and suffixes in `vike_model::credential_keys`, so a venue added to the roster appears the same
day; an unknown `--venue` is an error naming the roster rather than an empty emission. The header
states the rule people miss: **arming is not a credential question alone** — `policy.venues.<venue>`
is a ceiling consulted before the credential is read, and it defaults to `paper` for every venue.

The header's *other* ⚠ block states what the grid cannot contain, and that gap is structural rather
than an oversight: a venue whose credentials have a **bespoke** shape is derivable from no central
table, so its keys live only in that bridge's own `crates/bridges/<venue>/src/config.rs` and are
written by hand — the FX brokers' login/password pair, the on-chain venues' `_PRIVATE_KEY`, the
`POLY_*` trio. The pre-rename `MAINNET` tier is omitted for a different reason: the loader still
reads it, so it stays in the registry's grid, but teaching a spelling we are retiring to somebody
writing their first store would be its own kind of wrong. `vike_model::credential_keys::starter_keys`
draws both lines; `lookup_keys` — which this command never calls — is what answers *every name a
computed lookup in this workspace can ask for*.

Output goes to **stdout** and there is no `--out` flag, on purpose: the moment this command owns a
path it can truncate a live store. Redirecting it yourself is your own keystroke against your own
path.

## `set` — the one writer, and the shape it is held to [#set--the-one-writer-and-the-shape-it-is-held-to]

```sh
printf %s "$SECRET" | vike-cli secrets set BINANCE_DEMO_API_KEY      # the value on stdin, one line
vike-cli secrets set BINANCE_LIVE_API_KEY --from-env BINANCE_KEY      # the value from $BINANCE_KEY
```

The CLI stayed read-only for a long time on four arguments — the store is the user's only copy, a
writer invites scripts to regenerate the file wholesale, a value in a shell history is a leak, and
nothing on the agent surface may ever write a credential — and the writer that finally exists is the
one shape those arguments allow. `crates/vike-cli/src/cmd/secrets.rs`'s `run_set` is the code, and
the order it does things in is the argument:

1. **The key is validated first**, before anything is read or asked of stdin, against the key grid
   `vike_model::credential_keys::key_owner` can read — so a refused key never consumed the secret
   you piped on its way to the error. An unknown name is refused **by name**, with the nearest real
   names beside it: the store is a flat file, so a hand-typed `BINANCE_LIVE_API_KEY_` would otherwise
   be written as happily as the real one and the venue would stay on paper with no error anywhere.
   The one exception is a labelled second-account key such as `HYPERLIQUID_LIVE_API_KEY__ALT` — read,
   listed, and not settable from here, because the grid is a fixed enumeration and a label is not.
   Its refusal offers **nothing to copy**: the nearest name is the default account's live key, and
   writing this value there would overwrite the credential that account signs with.
2. **The store must already exist.** `set` upserts into the project's store — the same file
   `path` prints, under the same `VIKE_SETTINGS_DIR` — and **creates none**: with no store the
   command refuses and prints the two lines that make one (`template` redirected, then `chmod 600`).
   A store that is there and cannot be read is an error, never "not configured", the same
   distinction `list` draws. A permissive mode is reported on stderr and the write proceeds.
3. **The value is taken last**, from stdin or from the named variable, and **never from the command
   line**: a second positional — and, deliberately, any unrecognised token, a mistyped flag included
   — is refused with a message that quotes nothing you typed, because the token *is* the secret and
   an error echoing it would put it into the scrollback this refusal exists to keep it out of. Stdin
   is trimmed of the newline a shell or editor adds; a `--from-env` value is taken verbatim, so a
   credential with real leading or trailing whitespace survives, quoted. Both refuse **empty** (an
   empty value arms nothing, and reporting success for it is the failure class this project deletes
   settings keys over) and both refuse **more than one line**: a multi-line value written verbatim
   became a truncated credential plus a second `KEY=VALUE` the store never validated — an injection,
   not an untidiness — so `--from-env` names the variable and stops.
4. **The write is a second call site of the one upsert**, `vike_secrets::save_credentials`: the
   named key is replaced in place or appended, every other line, comment and blank stays
   byte-identical, the store's mode and a symlinked store's link are preserved, and the result
   lands atomically. There is no second writer to drift from the GUI's.
5. **The write is recorded** in the change journal, as the CLI actor, by key name and store —
   never by value — and a journal failure does not fail the call: the credential is on disk, and
   an error path for a write that succeeded is worse than a missing ledger line.

What it prints on success is one line, `KEY replaced in PATH` or `KEY appended in PATH`, and nothing
else. `vike-cli secrets list` afterwards shows the name; no invocation of this command ever shows a
value.

**The agent surface has no counterpart.** `vike-cli mcp` advertises no tool that writes a credential,
and a test holds the tool roster to that — an agent that needs a key armed is told to ask the
operator, who runs the line above.

## See also [#see-also]

* [`policy.toml`](/docs/trader/reference/settings/policy) — the arming ceiling consulted first
* [Accounts](/docs/trader/concepts/accounts) — the key grammar and the per-account arming rows
* [Risk and arming](/docs/trader/concepts/risk-and-arming) — ceiling, then credential, then risk gate
* [Environment variables](/docs/trader/reference/environment) — including `VIKE_SETTINGS_DIR`


# Trade (/docs/trader/reference/cli/trade)



| Verb                                         | What it owns                                                                       |
| -------------------------------------------- | ---------------------------------------------------------------------------------- |
| [trade](/docs/trader/reference/cli/trade/trade)   | Observe and control a running node: status, halt, resume, and the interactive REPL |
| [report](/docs/trader/reference/cli/trade/report) | A tearsheet over the node's own live journal — read-only, observe scope only       |


# vike-cli report (/docs/trader/reference/cli/trade/report)



`report` asks a running `vike-tradehub` node for a tearsheet over the live journal that node itself writes. It is read-only: the client always connects under the observe scope, and the call can neither place nor change anything. The journal itself never crosses the wire — the node renders the tearsheet and returns the answer as JSON.

It renders through the same `vike_report::LiveTearsheet` / `crates/vike-report/src/tearsheet_cli.rs` machinery report.rs's own doc names — pointed here at a live journal rather than a stored run, which is what puts the fills a running daemon is writing right now, on its own box, into the answer. It exists because that journal lives on the daemon's box — without this verb, getting a tearsheet over your own live trading meant opening an SSH session onto the production server.

Ruling 16 states the rule this verb closes a hole in: &#x2A;*`vike-cli <X>` asks the backend to do X; `vike-backend <X>` does X here.** Measuring the two command rosters against that rule found `report` served on the backend with no client half at all — `report` is the fix.

<Callout type="warn" title="Every invocation refuses today">
  No `vike-tradehub` build advertises the `tearsheet` capability yet — the daemon-side renderer is a follow-up. So a `report` call that reaches a node always ends in a client-side capability refusal: nothing is sent to the node beyond the handshake, and stdout stays empty. This is deliberate — a capability advertised before its server-side renderer existed would turn a clean refusal into an opaque server error.
</Callout>

## Usage [#usage]

```
vike-cli report --node <host:port> [--seed CASH] [--periods-per-year N] [--json]
```

```
vike-cli report --node prod2:9200 --seed 25000 --json
```

There is one form — no subcommands. `--node` is the only required flag; there is no default node to fall back to, the same shape `trade status` uses and for the same reason.

## Flags [#flags]

| flag                   | required | meaning                                                                                              |
| ---------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `--node HOST:PORT`     | yes      | the node's observe address                                                                           |
| `--seed CASH`          | no       | the account's starting capital, which scales the return ratios; omitted means the node's own default |
| `--periods-per-year N` | no       | the Sharpe/Sortino/Calmar/CAGR annualization factor; omitted means the node's own default            |
| `--json`               | no       | the tearsheet JSON verbatim, unformatted, instead of pretty-printed                                  |
| `-h`, `--help`         | no       | print usage and exit                                                                                 |

<Callout type="warn" title="A non-finite --seed or --periods-per-year is refused">
  Both flags reach the node as an optional number on the wire. `serde_json` writes a NaN or an infinite value as `null`, and the node would then silently apply its own default while you believed you had set one — so `nan`, `inf`, and `-inf` are refused by flag name before anything is sent, the same as a value that fails to parse at all.
</Callout>

## Key resolution [#key-resolution]

The observe key resolves the same way every node key does: `VIKE_TRADEHUB_OBSERVE_KEY` in the process environment first, then `<project>/settings/node.env` — the same store the daemon itself reads. A control key cannot substitute here: the node verifies each scope against its own key, and `report` presents only the observe half. If no observe key resolves at all, the command exits before dialing the node and prints the keyring's own "no observe key" message instead.

## Output [#output]

The node answers with the `LiveTearsheet` JSON document. `--json` prints that body verbatim; without the flag, the same document is pretty-printed. A body that fails to parse as JSON is reported as an error rather than echoed — a script reading stdout on a garbled body would otherwise see a success exit code.

## The refusal, in full [#the-refusal-in-full]

A `report` call against a reachable node today prints three lines to stderr and exits 1 (stdout stays empty):

```
vike-cli report: this node does not advertise the "tearsheet" capability — Tearsheet refused client-side, nothing was sent
the node at prod2:9200 runs a vike-tradehub build with no server-side renderer for this verb. Until it has one, run the same renderer ON that box:
  vike-backend report --journal <the node's journal directory> --seed 25000 --json
```

That third line is not a generic hint — it carries only the flags the failing invocation actually supplied (dropping `--seed` in translation would rescale every return ratio in the answer without saying so). The journal directory itself is never guessed; it is the node's own `config.journal_dir` or `VIKE_JOURNAL_DIR`, a fact this side of the wire cannot see, so the placeholder stays a placeholder.

If the observe key itself does not verify, the two lines differ and point at the credential instead of the verb:

```
vike-cli report: the node at prod2:9200 refused the observe handshake: auth denied: bad mac
the presented VIKE_TRADEHUB_OBSERVE_KEY does not match that node's — `vike-cli secrets path` names the store this side read it from
```

## Exit codes [#exit-codes]

| outcome                                              | exit | retryable                            |
| ---------------------------------------------------- | ---- | ------------------------------------ |
| node reachable, capability missing (today's outcome) | 1    | no — a permanent build fact          |
| node reachable, observe key does not verify          | 1    | no — fix the key, not the retry loop |
| node unreachable (refused, timed out, aborted)       | 3    | yes                                  |

A node that answered at all — even to refuse — exits on the permanent rung (1); only a socket that never got an answer exits on the retry rung (3). A wrapper that retried a permanent refusal would loop forever against a node that can never serve the call.

## Related [#related]

* [backend](/docs/trader/reference/cli/set-up/backend) — `vike-backend report` is the renderer this verb's refusal points at today, run on the box holding the journal.
* [trade](/docs/trader/reference/cli/trade/trade) — `trade status` resolves its node key the same way and shares the same permanent-vs-retry exit rung rule.
* [secrets](/docs/trader/reference/cli/set-up/secrets) — `vike-cli secrets path` names the store an observe-key mismatch was read from.


# vike-cli trade (/docs/trader/reference/cli/trade/trade)



`vike-cli trade` is the human, terminal-driven sibling of
[the MCP tools](/docs/trader/reference/cli/mcp): a person types short verbs and they are dispatched to a
running [`vike-tradehub`](/docs/trader/reference/binaries/vike-tradehub) node's authenticated **observe**
(read) and **control** (write) servers over the light wire crate
(`crates/vike-cli/src/cmd/trade.rs`).

```
usage: vike-cli trade --node <host:port> [--yes]
```

| flag                 | meaning                                            |
| -------------------- | -------------------------------------------------- |
| `--node <host:port>` | **required.** The node to attach to                |
| `--yes`, `-y`        | skip the per-write `confirm? [y/N]` prompt         |
| `-h`, `--help`       | print the usage and the verb reference, and exit 0 |

## The two halves, each gated on a key [#the-two-halves-each-gated-on-a-key]

Reads need `VIKE_TRADEHUB_OBSERVE_KEY` and give a handle subscribed to the node's pushed snapshot
stream. Writes need `VIKE_TRADEHUB_CONTROL_KEY`. With neither, the command exits with an error that
**names both places it looked**, the credential store's path included. Both keys are resolved once
by the dispatcher — process environment first, then `<project>/settings/secrets.env`, the same store
the daemon loads them from — and the connection line prints which source answered, without echoing
the key.

<Callout type="warn" title="Writes disabled is three different problems, and it used to report only one">
  With the node's control flag off and a perfectly good key in the store, a write used to print
  `no VIKE_TRADEHUB_CONTROL_KEY — nothing was sent`. The key was fine: the node had refused the
  **scope**, and had said so once, at connect time, before scrolling away. The three cases are now
  distinguished at connect and carried forward — **no key resolved**, the node **refused** the control
  scope (turn its `tradehub_control` on and restart it), or the connection could not be **opened** at
  all. Every message still ends in "nothing was sent", the one fact all three share.
</Callout>

## The verbs [#the-verbs]

```
commands:
  WRITE (preview + confirm):
    submit <venue> <symbol> <buy|sell> <qty> [@<price>|@market] [--reduce-only] [--coid <id>]
    buy|sell <venue> <symbol> <qty> [@<price>|@market] [--reduce-only] [--coid <id>]
      (a client_order_id is MINTED per order and shown in the preview; --coid pins one)
      <id> is 1..=32 alphanumeric characters, A-Z a-z 0-9
    cancel <coid>                (fire-and-forget: the node cannot confirm a match)
    modify <coid> [--qty Q] [--price P]
    flatten <venue> <symbol>
    mass-cancel [venue] [symbol]
    market-exit [venue]          (panic: cancel all + flatten all)
    state <active|reducing|halted>
  any WRITE line may end with:
    --reason <text to end of line>   recorded in the node's audit trail
  READ:
    orders [symbol]
    positions [venue]
    equity
    recent [N]
    state                        (show current)
    snapshot
  meta:  help    quit|exit  (or Ctrl-D)
```

The help screen states the client-order-id charset because a rejection is the wrong place to learn a
constraint — and because `cancel`, which takes the same field, only *warns*: a cancel that matches
nothing still reports as accepted, so a mistyped id is silent unless something says so up front.

Ctrl-C cancels the current line; Ctrl-D quits. Line history persists under the settings directory's
`state/` sub-directory, best-effort; with no project above the working directory it is simply not
persisted.

## Every write previews first [#every-write-previews-first]

The resolved command is printed, together with a client-side guardrail check, and then
`confirm? [y/N]` — skipped with `--yes`. Only on `y` is anything sent. The guardrail is advisory and
reads two caps: `max_notional_per_order` from this box's
[`policy.toml`](/docs/trader/reference/settings/policy), and `VIKE_MAX_ORDER_QTY`, a local typo-catcher
with no policy field and no enforcing counterpart anywhere. A market order with no price cannot be
sized client-side, so only the notional half is skipped — `guardrail_check` still measures the
quantity against its cap.

<Callout type="warn" title="The node is the enforcing gate; this preview is UX">
  The node's server-side control limits and the core risk gate are the backstop regardless — see
  [the control boundary](/docs/trader/concepts/control-boundary) and
  [risk and arming](/docs/trader/concepts/risk-and-arming). The notional cap moved out of the environment
  deliberately: a ceiling any exported variable can raise is not a ceiling.
</Callout>

Every order carries a client order id **this side minted**, from the session's generator, filled in
before the preview prints — so the id shown is the id sent and the id you type back at `cancel`. The
generator is session-scoped: an 8-hex prefix from OS entropy per process, then a counter, so two
REPLs open side by side, or one restarted while an order still rests at the venue, cannot collide. A
duplicate id is idempotent at the node, which would silently book nothing the second time.
`submit … --coid <id>` pins one explicitly.

After sending, the REPL waits up to two seconds for the node's verdict on **that** command and
reports accepted, refused, or unknown. It is a deadline, not a sleep — the answer returns the instant
the reply lands.

<Callout type="warn" title="Read a command's outcome from its own ticket, never a shared side-channel">
  This used to poll a handle-wide error field that **latches**: after one refusal every later write in
  the session printed that same refusal, including commands the node accepted and ran. An operator who
  fat-fingered an order, got a correct refusal, then typed `market-exit` was told the panic button was
  rejected when it had executed.
</Callout>

## `--reason` [#--reason]

Any write line may end with `--reason <text to end of line>` — an operator rationale recorded in the
node's audit trail beside the command, so an incident review reads *why*, not just *what*. It is
split off the line before the verb grammar sees it, shown in the preview, and sent beside the
command; it never becomes part of the order. No quoting is needed (one optional layer of surrounding
quotes is stripped), and the node sanitizes it before recording — control characters stripped, capped
at 512 characters.

## Related [#related]

[`strategy-status`](/docs/trader/reference/cli/strategy-status) asks the same node what it is running,
read-only. [Stop, liquidate, restart](/docs/trader/guides/stop-liquidate-restart) and
[triage a stuck order](/docs/trader/guides/triage-a-stuck-order) are the two procedures this REPL exists
for. The wire it speaks is [the node protocol](/docs/trader/concepts/node-protocol).