Configuration

File overview

File	Purpose	Tracked in git
`.env`	Secrets and external service credentials	No
`config.json`	Runtime trading behavior, risk profile, filters	Yes
`ml_config.json`	Feature list, model paths, labeling, training params	Yes

The onboarding wizard and weekly_optimize.py manage config.json automatically. You should rarely need to edit it by hand.

config.json

Risk & position sizing
Risk profile
Circuit breakers
SL/TP
Confidence threshold

The most important section. Controls how much capital is risked per trade.

"dynamic_position_sizing": {
  "enabled": true,
  "risk_percent": 3.0,
  "min_lot": 0.01,
  "max_lot": 100,
  "max_risk_per_trade_pct": 10.0
}

Field	Description
`risk_percent`	Base capital at risk per trade, as % of equity
`min_lot`	Floor lot size (never goes below this)
`max_risk_per_trade_pct`	Hard cap — actual risk never exceeds this % of equity regardless of lot

The equity-aware SL cap formula:

hard_cap_pips = (max_risk_per_trade_pct × equity) / (lot × pip_value)
pip_value = trade_tick_value / trade_tick_size  (auto-read from broker symbol info)

At equity 500 USC: cap = 50 pts. At 2418 USC: cap = 242 pts. Scales automatically as your account grows.

Set once during onboarding. Controls drawdown limits and hard halt.

"risk_profile": {
  "id": 3,
  "name": "Balanced",
  "max_total_dd_pct": 45.0,
  "max_weekly_dd_pct": 20.0,
  "hard_halt_pct": 45.0,
  "starting_balance_usd": 500
}

#	Name	Risk/trade	Total halt	Best for
1	Steady Income	0.5–1.0%	20%	Capital preservation
2	Conservative	1.0–1.5%	30%	Low-stress compounding
3	Balanced	1.5–2.0%	45%	Most users
4	Growth	2.0–3.0%	55%	Active traders
5	Aggressive	3.0–4.0%	65%	High risk tolerance

When the hard halt fires, trading.py calls sys.exit(99) and stops. It does not restart automatically. Update starting_balance_usd before restarting.

At 1:500 leverage, even Profile 5 halts well before the broker’s margin call threshold. At

500 starting balance on RoboForex, Profile 5 halts at ~

175 USD loss — far above the broker’s margin call point.

Safety gates that pause or stop trading.

"max_consecutive_losses": 7,
"max_weekly_drawdown_pct": 25.0,
"max_total_drawdown_pct": 55.0,
"loss_cooldown_minutes": 0,
"min_atr": 15

Field	Default	Effect
`max_consecutive_losses`	7	Pauses trading after N losses in a row
`max_weekly_drawdown_pct`	25.0	Pauses trading for the week when weekly loss exceeds this
`max_total_drawdown_pct`	55.0	Fires hard halt — `sys.exit(99)`
`min_atr`	15	Skips trades when ATR is below this (low volatility filter)
`loss_cooldown_minutes`	0	Minutes to wait after a loss before next trade (0 = disabled)

The dynamic SL/TP model overrides fixed pips at runtime. These values are fallbacks.

"sl_pips": 200,
"tp_pips": 300,
"atr_period": 14,
"atr_multiplier": 1.5

The sltp_model section in config.json controls the LightGBM regression parameters:

"sltp_model": {
  "enabled": true,
  "sl_multiplier": 1.0,
  "tp_multiplier": 1.2,
  "sl_min_atr": 0.5,
  "tp_min_atr": 0.8
}

tp_multiplier must be greater than sl_multiplier. The Phase 16 fix corrected a bug where tp < sl caused inverted risk/reward.

The signal model outputs a confidence score per bar. Only trades above the threshold pass through.

"confidence_threshold": 0.633

Higher threshold = fewer trades, higher precision. The optimizer sweeps this parameter during the weekly run. Typical range: 0.55–0.70 depending on risk profile.

ml_config.json

Feature list (62 features)

The feature list is the contract between training and inference. Never reorder, add, or remove features without retraining all 4 models and updating this file.Key groups:

Bollinger Bands: bb_upper, bb_lower, bb_width, range_position
Trend: price_vs_ema200, trend_strength, macd_signal, ema_crossover
Momentum: rsi_14, rsi_divergence, momentum_5, momentum_10
Volatility: atr_14, volatility_20, high_low_ratio
Volume: volume_ratio, volume_trend
Session/news (protected): is_london_session, is_ny_session, is_asian_session, is_news_near, news_minutes_away, news_count_today, is_news_risk_window
Account state: drawdown_pct, equity_ratio, win_rate_recent, consecutive_losses
Market regime (Phase 17.2): volatility_regime, w1_ema_bias, w1_rsi_norm

Protected features (never drop based on SHAP):

is_news_near, news_minutes_away, news_count_today, is_news_risk_window
is_london_session, is_ny_session, is_asian_session

Model paths

"ensemble_paths": {
  "rf": "models/rf_signal.pkl",
  "xgb": "models/xgb_signal.pkl",
  "lgb": "models/lgb_signal.pkl",
  "rf_onnx": "models/rf_signal.onnx",
  "xgb_onnx": "models/xgb_signal.onnx",
  "lgb_onnx": "models/lgb_signal.onnx"
}

Inference priority: calibrated pkl → ONNX → raw pkl. After every retrain, calibrate_models() runs automatically and writes *_calibrated.pkl files.

Risk model features

The risk model uses 7 equity-state features:

"risk_model": {
  "features": [
    "drawdown_pct", "equity_ratio", "win_rate_recent",
    "consecutive_losses", "volatility_20", "atr_14", "hour"
  ]
}

These must stay in sync across ml/risk_trainer.py, ml/risk_predictor.py, and ml_config.json. The model outputs a multiplier in [0.10, 1.25] applied to the base risk percentage.

Broker configuration

The active trading pair is set in config.json:

{
  "symbol": "BTCUSD",
  "symbols": ["BTCUSD"],
  "symbol_configs": {
    "BTCUSD": { "lot": 0.01, "sl_pips": 200, "tp_pips": 300 }
  }
}

All broker-specific parameters (pip_value, contract_size, tick_size, digits, etc.) are read automatically from the MT5 API at startup via GET /symbols/{symbol}. The system adapts to any broker or suffix — BTCUSD, BTCUSDc, BTCUSDm, etc. account_type (cent / standard) is also auto-detected from account.currency at startup: USC → cent, anything else → standard. No manual config needed.

To switch brokers: update symbol in config.json and API_URL in .env. The broker UTC offset is detected automatically from the live tick timestamp. Use GET /time on the MT5 API to inspect the detected offset.

Overview

Setup

System

File overview

config.json

ml_config.json

Broker configuration

​File overview

​config.json

​ml_config.json

​Broker configuration

File overview

config.json

ml_config.json

Broker configuration