Extend mt5-httpapi with backtest endpoints on top of v4 config

[Marinski]

Summary

This PR extends mt5-httpapi with an opt-in backtest mode for MT5 terminals.

The current project already runs real MT5 terminals inside a Windows VM and exposes them over HTTP for live trading and market data access. This PR adds a second execution mode focused on isolated tester runs, while keeping the same terminal/account routing model, Docker deployment model, and MT5-on-Windows runtime model.

A terminal configured with mode: backtest exposes tester-oriented endpoints instead of the normal live-trading surface.

This is intended as an extension of the core codebase, not as a separate wrapper around it.

Motivation

mt5-httpapi is already a strong base for remote MT5 automation because it gives each terminal a stable HTTP surface behind:

• /<broker>/<account>/...

That same architecture is also a good fit for remote backtesting.

The missing piece was an API mode that can:

• prepare a terminal for tester use
• accept backtest jobs over HTTP
• run MT5 in tester mode
• expose status/results through a polling API
• keep multiple terminals isolated by broker/account path and configuration

This PR adds that capability directly to the project.

What this PR adds

1. Per-terminal execution mode

A terminal entry in config/config.yaml can now declare a mode.

Example:

terminals:
  - broker: roboforex
    account: main
    port: 6542
    utc_offset: "3h"
    mode: live

  - broker: roboforex
    account: demo
    port: 6543
    utc_offset: "3h"
    mode: backtest

Behavior:

• mode: live keeps the normal trading/data API surface
• mode: backtest exposes backtest-oriented endpoints only

This makes the feature opt-in and terminal-scoped. A single installation can run both live and backtest terminals side by side.

2. Backtest HTTP endpoints

Backtest terminals expose:

• GET /ping
• GET /error
• POST /terminal/first-login
• POST /backtest
• GET /backtest/<job_id>

This keeps the public surface narrow and explicit for tester workers.

POST /backtest

Submits a backtest job and returns 202 Accepted with a job payload.

Accepted inputs:

• ini — required MT5 tester INI as UTF-8 text
• expert — optional uploaded .ex5
• expert_name — optional filename resolved from assets/experts/
• set — optional uploaded .set
• set_name — optional filename resolved from assets/sets/

Rules:

• either expert or expert_name must be provided
• set / set_name are optional
• if both upload and name are provided for the same file type, uploaded file wins

GET /backtest/<job_id>

Returns job state and job result.

Status lifecycle:

• queued
• running
• completed
• failed

The response includes job metadata, log/report/debug paths, and final result data when complete.

3. MT5 tester execution flow

The backtest handler performs the following steps:

• loads account credentials from config/config.yaml
• parses and validates the submitted tester INI
• injects terminal login credentials into the run
• normalizes report output to Reports\...
• stages EA / set / normalized INI artifacts
• launches MT5 in portable tester mode
• persists job state for polling
• returns diagnostics or report output on completion

This makes MT5 tester execution available over HTTP using the same Windows VM runtime as the rest of the project.

4. First-login endpoint for backtest terminals

Backtest terminals also expose:

• POST /terminal/first-login

This gives backtest terminals an API-triggered initialization/login path before tester jobs run.

That is useful for terminals that need to be prepared through HTTP instead of only through manual VM interaction.

5. Optional reusable host-managed backtest assets

This PR adds an optional asset model for repeated isolated testing.

Reusable files can live in:

• assets/experts/
• assets/sets/

Those folders are mounted into the VM shared path and can be referenced in POST /backtest using:

• expert_name
• set_name

This keeps reusable EA/set binaries outside runtime-generated data/ and avoids re-uploading the same files on every request.

Upload-based submission still works exactly as before for the new backtest API.

6. Integration with the current upstream configuration model

This PR uses the current single-file YAML configuration model centered on:

• config/config.yaml

Related runtime and helper paths were updated so the new backtest functionality fits the current project structure and startup flow.

API behavior

Live terminals

Terminals in mode: live keep the current API shape, including:

• /terminal
• /account
• /symbols
• /orders
• /positions
• /history

No change in intent there.

Backtest terminals

Terminals in mode: backtest expose only the backtest-oriented surface listed above.

This separation was intentional so a tester terminal is not also presented as a live-trading terminal.

Example requests

Submit a backtest with uploaded files

curl -X POST \
  -H "Authorization: Bearer $MT5_API_TOKEN" \
  -F 'ini=@tests/fixtures/backtest.ini;type=text/plain' \
  -F 'expert=@dist/MyStrategy.ex5;type=application/octet-stream' \
  -F 'set=@dist/MyStrategy.set;type=application/octet-stream' \
  http://localhost:8888/roboforex/demo/backtest

Submit a backtest with host-managed reusable assets

curl -X POST \
  -H "Authorization: Bearer $MT5_API_TOKEN" \
  -F 'ini=@tests/fixtures/backtest.ini;type=text/plain' \
  -F 'expert_name=MyStrategy.ex5' \
  -F 'set_name=MyStrategy.set' \
  http://localhost:8888/roboforex/demo/backtest

Poll job status

curl \
  -H "Authorization: Bearer $MT5_API_TOKEN" \
  http://localhost:8888/roboforex/demo/backtest/<job_id>

Example queued response

{
  "jobId": "4e3a7f5a1b0d4f6b8c9d2e1f3a4b5c6d",
  "status": "queued",
  "broker": "roboforex",
  "account": "demo",
  "submittedAt": "2026-05-08T12:34:56Z",
  "reportName": "backtest-report.htm",
  "reportPath": "C:\\...\\Reports\\backtest-report.htm",
  "logPath": "C:\\...\\logs\\backtest-roboforex-demo-<job>.log",
  "statusUrl": "/backtest/4e3a7f5a1b0d4f6b8c9d2e1f3a4b5c6d",
  "pollAfterSeconds": 1200,
  "queuePosition": 0,
  "resultStatusCode": null
}

Configuration changes

config/config.yaml

New terminal field:

• mode

Accepted values:

• live
• backtest

Host-managed assets

Optional folders:

• assets/experts/
• assets/sets/

These are mounted into the VM and used only when the caller chooses expert_name / set_name.

Documentation updates included in this PR

This PR updates project documentation to reflect the new merged-state behavior, including:

• backtest mode in the main README
• mode: backtest configuration
• backtest endpoint docs
• host-managed asset docs
• updated setup/skill references
• compose example updates for the new asset mount

Compatibility

This PR is intentionally additive.

• live mode remains available
• terminal routing remains /<broker>/<account>/...
• multi-terminal architecture remains unchanged
• Docker/Windows VM deployment model remains unchanged
• backtest functionality is opt-in per terminal
• host-managed assets are optional

Validation

Validated during development with:

• python3 -m py_compile mt5api/config.py mt5api/handlers/backtest.py
• bash -n run.sh
• docker compose -f docker-compose.yml config -q
• docker compose -f docker-compose.yml.example config -q

In addition, startup/config behavior was verified manually via run.sh, including config sync and installer handling.

Review notes

This PR is broader than a small endpoint patch because the feature crosses several layers of the project:

• API route surface
• MT5 execution flow
• startup/runtime scripts
• compose setup
• documentation

The core idea, though, is narrow:

• extend the existing codebase so a terminal can be explicitly configured either for live HTTP trading or for HTTP-driven MT5 tester execution

If the full PR is too broad for merge as one unit, the backtest mode pieces can also be reviewed as a basis for follow-up splitting or selective integration.