Scenario Configuration

The tektii scenario run --file command and the POST /v1/strategies/{id}/scenarios API both take a config file: a JSON document describing the subscriptions, the date window, and the run settings for a backtest. This page is the reference for that file — the inline schema. A near-identical saved-config schema backs tektii config create, and the two are not interchangeable; see The two config schemas.

The config file unlocks two shapes the web wizard deliberately does not author: per-instrument events (each instrument subscribing to its own set of events) and a precise start time (any time of day, not just 00:00 UTC).

The two config schemas

Two schemas describe a backtest config, and they are not interchangeable. Both reject unknown keys, so handing one command's file to the other fails with an unknown-field error rather than a helpful message.

Every other field — subscriptions, startTime, endTime, positionMode, initialCapital, env, costs — is identical on both, with the same validation.

So converting an inline config file into a saved preset means deleting strategyVersionId and giving it a name; going the other way means dropping name (plus description / isActive if present) and adding strategyVersionId. See config create for that command's arguments.

The rest of this page documents the inline schema. Every shared field behaves identically under the saved-config schema.

Fields

Subscriptions

Each entry in subscriptions is one instrument and the events that instrument should receive:

Valid events:

• candle_<timeframe> — one of 1m, 2m, 5m, 10m, 15m, 30m, 1h, 2h, 4h, 12h, 1d, 1w (e.g. candle_1m, candle_1h). Brace/wildcard patterns are accepted: candle_{1,5,15}m, candle_*.
• order_update, position_update, account_update, trade_update — trading lifecycle events.

Event patterns

Candle events accept a small pattern grammar so one entry can subscribe to several timeframes. The candle_ prefix is always required, and the * may appear only as a suffix.

Those five shapes are the whole grammar. Anything else is parsed as a literal timeframe and rejected if it isn't one — candle_*d is invalid, because the star is only recognised before m, before h, or on its own. Expansions are deduplicated, so overlapping patterns cannot subscribe you twice.

Per-instrument events

Because events lives inside each subscription, different instruments can subscribe to different event sets in the same run. Here EUR/USD drives the strategy on 1-minute candles while BTC/USD only supplies hourly candles:

{
  "strategyVersionId": "b2c3d4e5-f6a7-4b2c-8d3e-4f5a6b7c8d9e",
  "subscriptions": [
    {
      "instrument": "F:EURUSD",
      "events": ["candle_1m", "order_update", "position_update"]
    },
    {
      "instrument": "C:BTCUSD",
      "events": ["candle_1h"]
    }
  ],
  "startTime": "2024-03-04T13:30:00Z",
  "endTime": "2024-03-08T21:00:00Z",
  "positionMode": "netting",
  "initialCapital": 100000
}

Save it and launch a run:

tektii scenario run \
  --strategy-id a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d \
  --file ./scenario-config.json

That file is the inline schema, so it carries strategyVersionId. To keep the same window as a reusable preset, copy it, delete strategyVersionId, and pass the copy to config create — the saved-config schema rejects that key:

tektii config create \
  --name "eurusd-btc-march" \
  --file ./saved-config.json

Custom start time

startTime is a full timestamp, so a run can begin at any moment — for example at a market open rather than midnight. The window above starts at 13:30 UTC, not 00:00:

"startTime": "2024-03-04T13:30:00Z",
"endTime": "2024-03-08T21:00:00Z"

endTime is exclusive: the run includes data up to, but not including, that instant.

Transaction costs

By default a backtest pays only the bid/ask spread. The optional costs object layers on commission, slippage, and funding — each defaults to zero, so omitting costs (or leaving a field at its default) keeps the run spread-only and identical to a run without it.

Unlike the top-level camelCase keys, costs and its nested fields use snake_case on every surface.

Commission

costs.commission is a tagged object; the model key is the discriminator.

Slippage

costs.slippage is a plain object, not a tagged one. If you supply it, all three fields are required; each defaults to "0" when costs.slippage is omitted entirely.

The engine computes:

slippage_bps = base_slippage_bps + (notional / 100_000) * size_impact_bps_per_100k
slippage_bps = min(slippage_bps, max_slippage_bps)

A buy then fills at ask × (1 + slippage_bps / 10000), a sell at bid × (1 - slippage_bps / 10000) — always adverse, on top of the spread you already cross.

Funding

costs.funding is a tagged object charging financing on positions held across the rollover.

For the daily model:

The charge is position_value × annual_rate_side × days_charged / day_count_basis.

{
  "strategyVersionId": "b2c3d4e5-f6a7-4b2c-8d3e-4f5a6b7c8d9e",
  "subscriptions": [{ "instrument": "F:EURUSD", "events": ["candle_1m"] }],
  "startTime": "2024-03-04T13:30:00Z",
  "endTime": "2024-03-08T21:00:00Z",
  "costs": {
    "commission": { "model": "bps_of_notional", "fee_rate_bps": "10" }
  }
}

See Backtest Execution & Costs for how each cost is applied and how gross vs net P&L is reported in results.

Environment variables

env is a flat string→string map passed to your strategy container as environment variables — the usual way to parameterise a strategy without rebuilding its image.

The same key can be set at several levels. They layer, lowest to highest:

1. Image — whatever your Docker image bakes in via ENV. The implicit bottom layer.
2. Config — the env map on the scenario configuration. Overrides the image.
3. Per-run — the env passed when launching a run. Overrides the config.

A key set at only one level simply falls through unchanged. On the CLI, an inline --env beats the env block in your config file.

Keys and values are validated against the merged map:

Updating a configuration replaces the whole env map — omitting it clears every key rather than leaving the previous map in place.

What the web wizard leaves out

The Create Scenario wizard in the web app is deliberately the simple path. It applies the same events to every instrument and starts every run at 00:00 UTC on the chosen day. Its Review step points power users here for anything else.

To get per-instrument events or a non-midnight start time, author a config file as shown above and launch it with the CLI or API. The wizard restriction is a UI simplification only — the platform itself supports both shapes natively.

Next steps

• Command Reference — full scenario and config command options
• Available Instruments — symbols and their data ranges
• Plan Limits — lookback and duration caps