Your first backtest
The engine is the bin/algo executable. It has five commands:
algo run execute or verify a run
algo cache inspect or clear the bar-series cache
algo report re-render or recombine saved performance results
algo export convert saved results into one .algorun export file
algo version print the build identifierRun bin/algo for the command synopsis and bin/algo run -h for the complete single-run option list. Options use Go’s flag syntax, so --name value and --name=value are equivalent. The rest of this chapter starts with one run and then introduces the option groups you will use most often; the final Reference chapter is the exhaustive list.
Your first command
Now run it. The engine needs a strategy and what to ask for. Here that is the continuous E-mini S&P 500 future as daily bars:
bin/algo run \
--strategy bin/hello \
--symbol fut:XCME:ES --bar-interval 1dThis command needs two things installed: the adapters (make install, see Installing) and a marketfeed archive that holds ES, at /usr/local/marketfeed or $MARKETFEED_DIR (see The marketfeed adapter). With only this repository, run the bundled Databento sample instead (Naming the adapter).
You get your strategy’s log lines, then the run report, then the run’s data notes. On a terminal the run ends with its plates: its results by strategy and symbol, its equity curve and its monthly returns. The full report below is what --plate full prints there, and what a pipe or a file always gets:
[hello] INFO: hello: fut:XCME:ES closed at 1704.8500000000001
[hello] INFO: hello: fut:XCME:ES closed at 1716.6000000000001
[hello] INFO: hello: fut:XCME:ES closed at 1712.6000000000001
...
[hello] INFO: hello: fut:XCME:ES closed at 7353
[hello] INFO: hello: fut:XCME:ES closed at 7350.5
Algolang run run-fut-xcme-es-1d
adapter: marketfeed (stdio-pb-v1), inferred from /usr/local/algolang/adapters
strategy: hello ("Hello") via stdio-pb-v1
lifetime: v2 (default)
instance: 1 (fut:XCME:ES@1d), 0 orders
request: fut:XCME:ES@1d BARS
window: 1970-01-01T00:00:00Z < ts_close <= 2100-01-01T00:00:00Z
fills: bar path (none)
data: 4,231 records, 730,977 bytes in 433.8 ms (9,752 rec/s, 1.6 MiB/s)
bars: 4,229 main after replicate (+ 0 warmup), 4,229 loop, 0 orders
simulator: resolution=bar bracket_ambiguity=conservative limit_fill=conservative slippage_ticks=0
0 fills, commission 0.00, realized PnL 0.00
equity 100000.00 (capital 100000.00, return +0.0000%)
margin report: max initial 0.00 USD, 0 margin calls
margin sources: registry-seed (67 symbols, ESH11 to ESZ26)
phases: spawn+init 5.8 ms | fetch 433.8 ms | validate+replicate 0.0 ms | loop 105.8 ms (39,977 bars/s) | other 1,617.1 ms | total 2,162.6 ms
calls: instrument_info 69 in 1,514.6 ms | composite_bars 1 in 309.9 ms | roll_schedule 2 in 123.9 ms | statistics 67 in 27.8 ms | total 1,976.2 ms
performance: net profit +0.00 (+0.00%) | closed equity 100000.00
max drawdown 0.00 (0.00%) | sharpe n/a | cagr +0.00%
trades 0 closed | win rate n/a | profit factor n/a
BENCH adapter=marketfeed data_protocol=stdio-pb-v1 strategy=hello ...
Data notes 3 notes
run end fut:XCME:ES@1d clamped from 2100-01-01T00:00:00Z to 2026-11-07T00:00:00Z, where the feed's newest bar ends
provisional tail fut:XCME:ES@1d the trading contract's roll span is not final
cache disabled: end 2100-01-01T00:00:00Z not historical; pass an explicit --date-to
What just happened: the command named no data adapter, so the engine first asked each adapter in the adapter directory, /usr/local/algolang/adapters, whether it could serve fut:XCME:ES as daily bars (Finding the adapter). The file adapters wanted a Path, ibkr wanted a gateway, and marketfeed found ES in its archive. So the engine started marketfeed, and the report’s adapter line says where it came from. The adapter served the continuous series: each front contract in turn, rolled on the feed’s schedule and Panama-adjusted at every roll, which is why the early closes print with floating-point noise. Aggregating the bars is the adapter’s job, never the engine’s. The engine then started bin/hello, negotiated a protocol, and fed it the bars one at a time. Each bar triggered your OnBar, whose ctx.Logf line came back over the wire and was printed on stderr with the [hello] INFO: prefix. With no --date-from or --date-to the run asks for 1970 to 2100 and gets the whole archive, and the run’s data notes follow from that. The end is clamped to the newest bar, the newest span of the roll schedule is still provisional, and the bar cache stays off because the range reaches the future. A real backtest names its window with --date-from and --date-to. When the data ran out, the engine shut both processes down and printed the report. Your twenty-line program just ran a complete, simulated backtest over nearly sixteen years of S&P 500 futures.
Reading a command from left to right
The first run can be read as a sentence:
| Part | Meaning |
|---|---|
algo run | Execute a run rather than inspect the cache or version. |
(no --adapter) | Find the market-data source: ask each adapter in the adapter directory and start the one that can serve the request (Finding the adapter). |
--strategy ... | Start this executable as the strategy. |
--symbol fut:XCME:ES | Request one instrument. A bare futures root is its continuous series (The strategy’s view of continuous futures). --symbol is a compatibility alias; prefer --symbols. |
--bar-interval 1d | Request daily time bars, the default (the flag can be left out). |
--session rth | Serve 1d/1w series from a trading-day container (eth, rth, or session, the symbol’s declared alias; empty = plain bars cut at the exchange’s local midnight), or 1d series from a custom window custom:HHMM-HHMM. With an intraday interval (whole seconds, 1s up to but excluding 24h), eth, rth, session or utc-day instead selects an intraday grid: bars restart at each window open and the last bar is cut at the close. Refused with --replicate. On the continuous path (a bare root or a :cont composite in the run grammar) a trading-day container at 1d/1w reads the feed’s session composite (GLE-324; eth when none is given, see --continuous-clock) and an intraday grid reads the feed’s grid composite (Continuous symbols on a grid, GLE-443); the run symbol itself carries no @ session suffix (the session is the run’s). A 1d trading-day container carries the intra-bar path at a named --path-interval (A session bar’s path, GLE-1331) on a dated contract, an equity or a continuous symbol (GLE-1332), while a bare --include-path, a 1w container and a custom window refuse it; a grid series accepts it on any of them, a continuous symbol walking the path of the contract it holds (Path resolution). With --config, overrides every run’s session. “Daily” is three different bars: epoch daily (--bar-interval 1d, no session) buckets on the exchange’s local midnight (ES: Chicago midnight, GLE-1344) and splits every CME session across two calendar days; eth is the full exchange trading day (ES: 17:00 CT the prior evening → 16:00 CT), keyed by trade date with settlement facts on Bar.Session; rth is the regular session only. For trading semantics the session dailies are the real thing; epoch daily is the simple clock-time bucketing. |
The smallest modern spelling therefore uses --symbols:
bin/algo run \
--strategy bin/hello \
--symbols fut:XCME:ES \
--bar-interval 1dNaming the adapter
--adapter names the data source and skips discovery. Here it runs the Databento adapter on the trade sample bundled with this repository, which needs no install and no archive, only make build. It asks for MSFT as 1-minute bars built from the sample’s trades:
bin/algo run \
--adapter bin/databento-adapter \
--adapter-inputs Path=testdata/xnas-sample/xnas-itch-20220610.trades.csv \
--strategy bin/hello \
--symbol MSFT --bar-interval 1m[hello] INFO: hello: MSFT closed at 261.06
[hello] INFO: hello: MSFT closed at 261.64
[hello] INFO: hello: MSFT closed at 260.91
...
[hello] INFO: hello: MSFT closed at 261.03
Algolang run run-MSFT-1m
adapter: databento-adapter (stdio-dbn-v1)
strategy: hello ("Hello") via stdio-pb-v1
lifetime: v2 (default)
instance: 1 (MSFT@1m), 0 orders
request: MSFT@1m BARS
window: 1970-01-01T00:00:00Z < ts_close <= 2100-01-01T00:00:00Z
fills: tick path
coverage: MSFT: finest supportable granularity: tick (limited by
databento-adapter, 2022-06-10T12:30:01Z..2022-06-10T12:52:21Z)
data: 1,023 records, 49,335 bytes in 18.1 ms (56,420 rec/s, 2.6 MiB/s)
bars: 23 main after replicate (+ 0 warmup), 23 loop, 0 orders
simulator: resolution=tick bracket_ambiguity=conservative limit_fill=conservative slippage_ticks=0
0 fills, commission 0.00, realized PnL 0.00
equity 100000.00 (capital 100000.00, return +0.0000%)
phases: spawn+init 300.0 ms | fetch 18.1 ms | validate+replicate 0.0 ms | loop 2.3 ms (9,798 bars/s) | other 22.9 ms | total 343.4 ms
calls: bars 1 in 15.7 ms | trades 1 in 2.4 ms | instrument_info 7 in 1.9 ms | coverage 1 in 0.6 ms | total 20.6 ms
performance: net profit +0.00 (+0.00%) | closed equity 100000.00
max drawdown 0.00 (0.00%) | sharpe n/a | cagr n/a
trades 0 closed | win rate n/a | profit factor n/a
BENCH adapter=databento-adapter data_protocol=stdio-dbn-v1 strategy=hello ...
| Part | Meaning |
|---|---|
--adapter ... | Start this executable as the market-data source: a path, or the name of an installed adapter (--adapter databento). |
--adapter-inputs Path=... | Configure that adapter. Input names belong to the adapter, not to the engine. |
The adapter read the 1,000 sample trades and constructed 23 one-minute bars from them. Once the adapters are installed, --adapter-inputs Path=... without --adapter finds the same adapter: only databento and file-csv take a Path, and only databento reads this file.
The CSV behind Path= is Databento’s own format, not one Algolang invented. testdata/xnas-sample/ is a Databento batch download kept exactly as delivered: 1,000 MSFT trades from the XNAS.ITCH dataset on 10 June 2022, requested in Databento’s CSV encoding, with the manifest.json, metadata.json and condition.json files Databento ships alongside every batch job. The filename follows Databento’s naming too (dataset, date, schema). The adapter is named for where the data comes from, not for a connection: bin/databento-adapter replays a trades file you have already downloaded, never calls the Databento API, and needs no API key. Nor does it require CSV. It also reads DBN, Databento’s native binary encoding, and tells the two apart from the file’s contents, so Path=testdata/msft-trades.dbn (written by make testdata) serves the same trades. The examples use the CSV only because it is the one sample committed to the repository; the DBN file exists only once you have run make testdata.
Keeping the results
The hello strategy places no orders, so its report has nothing to measure. Run the bundled SMA-crossover demo on the same sample instead, and keep its results:
bin/algo run \
--adapter bin/databento-adapter \
--adapter-inputs Path=testdata/xnas-sample/xnas-itch-20220610.trades.csv \
--strategy bin/smacross \
--symbol MSFT --bar-interval 1m \
--results-dir resultsThe run report now ends with a performance: block — net profit, drawdown, trade counts and the rest — and --results-dir writes the same figures to disk:
results/
index.json
run-MSFT-1m/
equity.csv
report.html
result.json
trades.csv
Open results/run-MSFT-1m/report.html in a browser (open on macOS, xdg-open on Linux) for the interactive report: the equity and drawdown chart, the trade statistics and the trade list. One session of one-minute bars makes a thin report; The performance report walks through a full one, and bin/algo report results prints the figures again later without running anything.
To keep the whole run in one file, its bars included, add --export msft.algorun, with --results-dir or without it. The file is the export AlgoChart opens, written as the run goes.
The option groups
Most single-run options answer one of six questions:
| Question | Principal options |
|---|---|
| What data source? | --adapter (optional: Finding the adapter), --adapter-inputs, --data-protocol |
| What strategy? | --strategy, --inputs, --strategy-protocol |
| What series? | --symbols, --bar-interval, --bar-kind, --threshold and expectation-bar settings |
| What time window? | --date-from, --date-to (a date or an RFC 3339 timestamp) |
| How should execution be modelled? | --initial-capital, commission flags, --slippage-ticks, --simulation-resolution, --limit-fill, --bracket-ambiguity, --lifetime |
| Where should reusable or auditable output go? | --cache, --cache-dir, --results-dir, --export, --fills-json, --lifecycle-json, --run-id |
--mode backtest is the default and uses the simulator. --mode live selects the IBKR venue path and requires venue and ledger options; that path is currently limited to deterministic emulator-driven, single-series runs. Treat the live flags in the Reference chapter as an integration surface, not a promise of a general real-time trading workflow in this build.
For repeated runs, portfolios, parameter sweeps, or mixed timeframes, stop growing the command line and use --config. Always preview a config before executing it:
bin/algo run --config runs.json --verify
bin/algo run --config runs.jsonConfig mode intentionally excludes most single-run flags. Only the documented global overrides may accompany --config; this keeps a saved experiment from being silently changed by an unrelated command-line value. The three fill flags (--simulation-resolution, --bracket-ambiguity, --limit-fill) may accompany it too, as defaults for the runs that do not set the key (Fill settings per run).