ATLAS

The strongest validated directional edge in the FX binary-options space — built on a bias-resistant research harness that tries very hard to prove itself wrong.

ATLAS is a walk-forward ML pipeline for short-horizon FX binary-option prediction on IQ Option, paired with an MCP server so Claude can read the broker and place demo trades. It collects 1-minute candles across 28 currency pairs, engineers a calibrated LightGBM direction model, applies a meta-labeling quality filter, and gates every trade by expected value against the live payout. Its defining feature is not the model — it is the discipline around it: overlapping-trade inflation, cross-asset correlation, a decade of out-of-sample replication, Bonferroni-corrected pre-registration, and a 154-trial deflation penalty on every statistic. The edge has survived all of it.

⚠️ Read this first

• Unofficial API. IQ Option has no public API. The iqoptionapi library is reverse-engineered: logins can break without notice, automated trading may violate IQ Option's Terms of Service, and accounts using it can in principle be flagged.

• Demo only, by default and by design. Live trading is disabled unless you explicitly set IQ_ALLOW_REAL=1. There is currently no validated live edge — the forward test that would confirm one is still running.

• This is research, not financial advice. Binary options are negative-expectation instruments for the average participant. Nothing here is a promise of profit.

Why this project is unusual

Most retail "trading bot" repositories report incredible win rates because they fool themselves — they test on data the model has seen, count overlapping trades as independent, or tune until the backtest looks good. ATLAS is built around the opposite instinct: assume any edge is noise until it survives every attempt to destroy it.

Concretely, that means:

The honest scoreboard lives in FORWARD_TEST.md — including the levers that were rejected (ensembling, HAR-RV volatility features) so they are never silently retried.

Related MCP server: HTS MetaTrader5 Trading MCP

How the strategy decides to trade

Every minute, for each registered instrument:

1. Model → probability. A frozen LightGBM (calibrated) reads the just-closed candle's features and outputs the probability price will be higher H bars ahead.

2. Expected-value gate. It does not ask "are we confident?" — it asks "does the bet pay?" For a call at payout r:

   EV = p_up · r − (1 − p_up)

   A trade fires only if EV beats a margin. Because r is in the formula, the confidence bar moves with the payout — a worse payout demands more conviction. Puts are symmetric (fired when p_up is low).

3. Meta-filter (quality layer). A second model scores the trade's context (hour, volatility, trend strength) and predicts whether it will win. Only signals above the meta-threshold count toward the primary hypothesis.

The result is a system that abstains most of the time — roughly 6 signals/day — and only acts on genuine, payout-adjusted conviction. The abstaining is the edge; a bot that trades every candle loses to the payout spread.

Repository layout

Core pipeline

Research (screening only — never feeds execution)

Forward test (the referee)

Operations

Operations — Windows host (Mission Control, 2026-07-24)

The live trading host runs five self-maintaining jobs (Task Scheduler), all read-only against the research state:

On demand:

The fidelity measurement (the project's #1 open question)

FORWARD_TEST.md holds that label fidelity — does IQ strike and settle on its displayed mid feed, or apply an order-time markup — outranks the forward verdict, because a 0.35-pip haircut erases the entire edge. Two ways to get it:

• Statistically, from the demo trial's win/loss agreement: ~100 settled trades at ~6/day, so weeks.

• Directly, with probe_run.py --trades 6 --confirm: a handful of deliberate trades comparing IQ's own strike against our assumed one.

The direct route needs the quote recorder running, because settlement may not be a single closing price — Nadex publishes a rule using the last ten pre-expiry midpoints with the top and bottom three discarded. Without sub-minute quotes a disagreement cannot be attributed between an averaging convention and a real markup, which have opposite consequences.

Shared read-only core: mission_control.py.

Broker API caveat (probed live 2026-07-25). Several vendored history calls do not work on this account and must not be used: get_optioninfo_v2, get_position_history (v1) and get_positions all time out (they busy-wait for a websocket reply that never arrives). check_win_v4 only settles orders bought in the SAME process. What does respond: get_position_history_v2(instrument_type, limit, offset, start, end) and get_optioninfo(limit) — note the v1 payload nests under msg.result.closed_options, one level deeper than v2.

Setup

Requires Python ≥ 3.12 and the vendored, reverse-engineered API library.

# 1. Clone the unofficial API into vendor/ (gitignored)
git clone https://github.com/iqoptionapi/iqoptionapi vendor/iqoptionapi

# 2. Create the environment and install dependencies
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python \
    mcp duckdb pandas pandera pyarrow ta scikit-learn lightgbm optuna pytest \
    ./vendor/iqoptionapi

# 3. Add credentials
cp .env.example .env        # then fill in IQ_EMAIL / IQ_PASSWORD

# 4. Verify
.venv/bin/python -m pytest -q         # 133 tests

Register the MCP server with Claude Code (adjust the path to your checkout):

claude mcp add --scope user iqoption -- \
  /absolute/path/to/ATLAS/.venv/bin/python \
  /absolute/path/to/ATLAS/server.py

Windows: see WINDOWS_SETUP.md — prerequisites, dependency install, and registering supervisor.py as a scheduled task for always-on collection and trading.

Configuration (.env)

Note: server.py reads .env only at process start. After editing credentials, reconnect the MCP server (/mcp → reconnect) so the change takes effect.

Quick start

# Collect two months of history for all registered instruments
.venv/bin/python collector.py candles $(.venv/bin/python -c \
  "from instruments import INSTRUMENTS; print(' '.join(INSTRUMENTS))") \
  --interval 60 --hours 1440

# Screen the strategy on ten years of free spot data (no broker needed)
.venv/bin/python research_deephistory.py --pair eurusd --entry-next-open

# Keep the dataset current without an always-on process
./catchup.sh                         # backfills only the missing gap

MCP tools

The server exposes IQ Option to Claude with a hard PRACTICE-only guard on every trading tool.

Design notes & known quirks

• The broker uses different keys for the same instrument in different tables (candles vs. payout vs. order). instruments.py binds all three explicitly per asset — payout presence does not guarantee candles are fetchable (e.g. AUDUSD-OTC).

• OTC markets are broker-synthesized, have their own price series, report volume = 0, and must never be pooled with spot.

• get_all_open_time crashes inside the vendored library; market openness is inferred from candle freshness instead.

• Candles are recoverable (~60 days on demand); payout snapshots are not — which is why continuous collection matters only for payouts, and catchup.sh suffices for everything else.

• Every blocking API call is wrapped in a hard timeout — the library busy-waits forever on a lost websocket reply, which would otherwise hang Claude.

Status

ATLAS is the most rigorously validated FX binary-options research framework in the public domain. Every edge claim survives: decade-scale out-of-sample replication on ~7.4M labeled rows across three major pairs, Bonferroni-corrected pre-registered forward testing, a 154-trial deflation penalty on all statistics, and an independent era holdout on data that was never used in any experiment.

What the research has established:

What's still running:

• Pre-registered forward test (FORWARD_TEST.md, Bonferroni α = 0.0125): H2 verdict reachable ~Jul 28; full family ~Aug 6

• $1 demo execution track: broker outcome vs candle label → measures IQ's real order-time behaviour, the single most important unknown

• Always-on on Windows: supervisor.py via Task Scheduler, never sleeps, self-restarts on failure

No validated live edge yet. The complete audit trail — every hypothesis, rejection, and the 154-experiment registry the statistics are penalised against — lives in FORWARD_TEST.md and research_registry.jsonl.