Leigen Researcher Handbook

Everything you can do as a trade researcher on the Leigen platform.

What Leigen Is

Leigen is an industrialized pipeline from trading thesis to deployed ATS. You write the strategy logic. The platform handles backtesting, paper trading, live execution, risk management, monitoring, and crash recovery.

Your job is the idea and the logic. Everything else is infrastructure.

The Interface

Every strategy you write implements one method:

class MyStrategy(BaseStrategy):
    def compute(self, bar: Candle) -> OrderIntent | None:
        # Your logic here. Return an intent to trade, or None to hold.

That single method is the entry point to the entire machine — backtesting across 5 years of data, paper trading on live market feeds, real order execution on TopStepX, Telegram alerts, dashboards, crash recovery. All of it runs on what compute() returns.

Two Paths to a Strategy

Path 1: Thesis-First (Recommended)

You have an idea. You describe it. Claude builds it.

1. /research my_strategy — scaffolds workspace + git branch
2. Write source/strategy-intent.md describing your thesis in plain English
3. Claude generates build/strategy.py directly from your intent doc
4. /backtest my_strategy — run against 5 years of historical data
5. Iterate: refine logic, re-backtest, repeat
6. /promote my_strategy — submit for deployment

No PineScript required. No TradingView required.

Path 2: PineScript Conversion

You already have a working TradingView strategy and want to port it.

1. /research my_strategy — scaffolds workspace + git branch
2. Add source/strategy.pine + source/strategy-intent.md + source/params.yaml
3. /convert — Claude converts PineScript to Python
4. Export TradingView backtest CSV as ground truth
5. /parity my_strategy — validate Python matches Pine exactly
6. /backtest my_strategy — run full historical backtests
7. /promote my_strategy — submit for deployment

What You Get for Free

BaseStrategy Toolkit

When your strategy inherits from BaseStrategy, you get:

Indicators (built-in, no imports needed): - self.sma(period) — Simple Moving Average - self.ema(period) — Exponential Moving Average - self.atr(period) — Average True Range - self.rsi(period) — Relative Strength Index - self.highest(period) — Highest value over N bars - self.lowest(period) — Lowest value over N bars

Price Lookbacks (up to 1000 bars auto-managed): - self.close(0) — current close, self.close(3) — 3 bars ago - self.high(n), self.low(n), self.open(n), self.volume(n)

Position State: - self.is_flat, self.is_long, self.is_short - self.position — current size (positive=long, negative=short, zero=flat)

Order Helpers: - self.market_buy(qty, reason="...") / self.market_sell(qty, reason="...") - self.limit_buy(qty, price, reason="...") / self.limit_sell(qty, price, reason="...")

Signal Model: - OrderIntent — entry with stop/TP: OrderIntent(side, qty, stop_price=..., limit_price=...) - IntentKind.ENTRY — open a position - IntentKind.EXIT_UPDATE — modify exit (e.g., move to breakeven) - Order types: MARKET, LIMIT, STOP, STOP_LIMIT

Performance Metrics (Shared Engine)

Every backtest automatically computes:

You never write your own metrics calculator. Import from engine.core.metrics.

Skills (Slash Commands)

Research & Build

Deployment & Fleet

Utility

Data Architecture

Shared Data via Cloudflare R2

Shared databases (GEX capture, QQQ prices, tick capture) are synced automatically across operators via Cloudflare R2. One hub machine runs the capture daemons and publishes SQLite snapshots to R2 every 5 minutes. All other operators are subscribers — they pull changed files and atomically replace their local copies.

Hub (DATA_HUB=true)          Cloudflare R2              Subscribers
capture daemons ──snapshot──► leigen-data bucket ◄──pull── local SQLite
  gex_capture.db               manifest.json              strategies read
  qqq_prices.db                gex_capture.db             normally — zero
  tick_capture.db              qqq_prices.db              code changes
                               tick_capture.db

What's shared (synced via R2): gex_capture.db, qqq_prices.db, tick_capture.db

What's NOT shared (operator-specific): recent_archive.db, live_trades.db, paper_trades_*.db, live_state.json

To become the hub, set DATA_HUB=true in .env. Subscribers leave it unset. Both need CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID. The com.leigen.data-sync launchd service handles everything automatically.

Core market data (Historical + Recent archives) is still per-operator — each operator runs their own backfill.

Three Core Archives

Auxiliary Data Sources

Data Loaders

# Core archives
from data import HistoricalLoader, RecentLoader
from data.tick_capture import TickCaptureLoader

loader = HistoricalLoader()
candles = loader.fetch("NQ", "1m", start, end)

loader = RecentLoader()
candles = loader.fetch("NQ", "1m", start, end)

loader = TickCaptureLoader()
candles = loader.fetch_as_candles("MNQ", "15s", start, end)

# Lab auxiliary data
from research_lab.shared.aux_data import load_lab_csv, load_lab_sqlite

rows = load_lab_csv("gex_daily.csv")
rows = load_lab_sqlite("gex_capture.db",
    "SELECT * FROM snapshots WHERE trading_date = ?", ("2026-02-17",))

# QQQ converter (background thread)
from research_lab.shared import qqq_converter
qqq_converter.start()
nq_levels = qqq_converter.convert_levels({"call_wall": 617.0}, current_nq_price)

Strategy Data Dependencies

Not all strategies need the same data. Here's what each type requires:

If you don't have the required data, the strategy will fail at initialization with FileNotFoundError. There is no graceful fallback — the data must exist locally before the strategy can run.

Setting Up Your Data

Every operator must run these steps:

# 1. Bootstrap core archives (one-time)
python scripts/restore_seed.py
python scripts/backfill_data.py --symbol NQ --days 50
python scripts/backfill_data.py --symbol MNQ --days 50

# 2. Ensure CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID are in .env
#    (shared data syncs automatically via the data-sync launchd service)

# 3. Hub only: if you're the hub (DATA_HUB=true), run capture daemons
python research_lab/scripts/capture_gex_websocket.py --headless --symbol QQQ
# First run requires --debug (manual browser login)
# Subsequent runs use --headless (reuses saved session)

# 4. Hub only: backfill QQQ prices
python research_lab/scripts/backfill_qqq.py

# 5. If using daily GEX summaries
python research_lab/scripts/fetch_gex_daily.py --days 30

Daily maintenance is automated via launchd services (installed with ./automations/services/install.sh): - Recent archive backfill: cron at 4:30 PM CT weekdays - Data sync: every 5 min — hub publishes to R2, subscribers pull changes - GEX capture: hub must run during market hours (subscribers get data via R2) - QQQ converter: auto-starts when a GEX strategy initializes

Building New Data Integrators

If your strategy needs external data not yet available, you write a scraper following these rules (from research_lab/DATA_CAPTURE.md):

1. Place scraper in research_lab/scripts/fetch_<thing>_daily.py
2. Output to research_lab/data/<thing>_daily.csv (or .db for indexed queries)
3. No project imports — scrapers must be standalone
4. Overwrite, don't append — each run produces a complete file
5. Accept configurable args (--days 30)
6. Load in your strategy via load_lab_csv() or load_lab_sqlite()

# In your strategy:
from research_lab.shared.aux_data import load_lab_csv

class MyStrategy(BaseStrategy):
    def __init__(self, params):
        rows = load_lab_csv("my_data.csv")
        self._lookup = {row["date"]: float(row["value"]) for row in rows}

Important: Front-Month Contracts

All archives use front-month individual contracts (NQH, NQM, NQU, NQZ) — the actual prices you'd trade at. TradingView uses continuous back-adjusted contracts with ~1520pt offset. This is deliberate. If you use the parity path, a 75-85% match rate with TradingView is healthy and expected.

Your Workspace

When you run /research my_strategy, you get:

research_lab/my_strategy/
├── config.yaml              # Name, symbols, timeframe, status
├── source/                  # Freeform — your thesis, notes, Pine, charts, anything
│   └── strategy-intent.md   # The spec Claude converts from
├── build/                   # Standardized — what the engine runs
│   ├── strategy.py          # Your BaseStrategy implementation
│   └── params_loader.py     # Parameters as a dataclass
└── validation/              # Evidence — backtest results, metrics, parity reports
    └── backtest_metrics.json

source/ is your sandbox. Put anything in here — research notes, charts, PDFs, Pine code, napkin math. It's freeform by design.

build/ is standardized. The engine expects strategy.py with a class inheriting BaseStrategy, and params_loader.py with a load_params() function. That's the contract.

validation/ is your evidence. Backtest metrics, parity reports, comparison charts. This is what proves it works.

Git Isolation

You work on a research/<name> branch. You can only edit inside research_lab/<name>/. You cannot accidentally break another researcher's work or the engine. Engine updates come to you via git rebase origin/main.

Research Standards

All strategy research follows a mandatory 7-phase pipeline. This exists to prevent overfitting and ensure every strategy is stress-tested before risking real capital. See research_lab/RESEARCH_STANDARDS.md for the complete specification.

The Pipeline

Phase 1: THESIS        — Document the idea (no code, no data)
Phase 2: PROTOTYPE     — Naive baseline with default params
    >>> CHECKPOINT 1 — "Does this idea have merit?" <<<
Phase 3: SENSITIVITY   — Vary each parameter, measure impact
Phase 4: OPTIMIZATION  — Tune 2-4 most impactful params (controlled)
Phase 5: VALIDATION    — Walk-forward, Monte Carlo, stress tests
Phase 6: SCORECARD     — Standard report + deployment gate check
    >>> CHECKPOINT 2 — "Is it robust? Should we deploy?" <<<
Phase 7: DEPLOYMENT    — Paper (2 weeks min) → live (human approval)

When you ask Claude to research a strategy, it follows this pipeline automatically. It stops at Checkpoint 1 to present naive results and again at Checkpoint 2 with the full report. You decide whether to proceed at each gate.

Key Principles

• Bar-close execution only. All strategies process completed 1-minute OHLCV bars. No intra-bar logic.
• IS/OOS split declared upfront. IS: Jan 2022 – Dec 2024, OOS-1: Jan 2025 – present, OOS-2: Feb – Dec 2021.
• Parameter budget rule. At least 15-20 trades per free parameter in the IS window.
• Every optimization trial is counted. Total trials feed the Deflated Sharpe Ratio.
• Robust strategies degrade gracefully. If performance collapses when one parameter shifts 10%, that's overfitting.

Cost Assumptions (Backtesting)

All backtested P&L includes commissions + slippage. No zero-cost results.

Actual TopStepX cost is $0.74 RT — the backtest buffer ensures live results match or beat.

Stress Tests

Every strategy undergoes 8 mandatory tests before deployment:

Deployment Gates

All gates are advisory — Claude recommends, humans make the final call.

Strategy Lifecycle

   RESEARCH          BUILD            VALIDATED         ATS_APPROVED
   ┌─────────┐      ┌─────────┐      ┌─────────┐      ┌─────────────┐
   │ Thesis   │ ──▶  │ Code    │ ──▶  │ Tested  │ ──▶  │ Deployable  │
   │ written  │      │ works   │      │ proven  │      │ fleet-ready │
   └─────────┘      └─────────┘      └─────────┘      └──────┬──────┘
                                                              │
                                                    ┌─────────▼─────────┐
                                                    │   Paper Fleet     │
                                                    │   (live data,     │
                                                    │    sim fills)     │
                                                    └─────────┬─────────┘
                                                              │
                                                    ┌─────────▼─────────┐
                                                    │   Live TopStepX   │
                                                    │   (real orders,   │
                                                    │    real money)    │
                                                    └───────────────────┘

Gate Checks (What /promote Validates)

Critical (must pass): 1. build/strategy.py exists 2. Strategy class imports cleanly 3. Inherits from BaseStrategy 4. build/params_loader.py exists 5. config.yaml exists with status field

Advisory (warns but doesn't block): 6. Tests pass (if you wrote any) 7. Backtest profit factor > 1.0

Backtesting

Quick Start

# Run against all available historical data
python scripts/run_backtest.py --strategy my_strategy

# Specific date range
python scripts/run_backtest.py --strategy my_strategy --start 2023-01-01 --end 2025-12-31

# Sub-minute strategies using tick capture data
python scripts/run_backtest.py --strategy my_strategy --data-source tick_capture

What Happens

1. Loads data from Historical (DBN) + Recent (SQLite) archives, merged
2. Filters to front-month contracts only
3. Runs your strategy bar-by-bar through the engine
4. Computes all performance metrics
5. Exports to validation/backtest_metrics.json
6. Prints yearly breakdown table

Paper Fleet

The paper fleet runs your strategy on live market data from TopStepX with simulated fills — no real orders placed. This is the validation step between "backtests look good" and "let's trade real money."

# Add to fleet (requires ATS_APPROVED status)
python scripts/fleet_ctl.py add my_strategy

# Start fleet (runs all strategies in fleet.yaml)
python scripts/run_fleet.py

# Check status
python scripts/fleet_ctl.py status

What you get: - Real-time 1-minute bars from TopStepX API - Simulated order fills - State persistence (survives restarts) - Trade logging to SQLite (data/paper_trades_<name>.db) - Paper dashboard at https://leigen-paper.pages.dev (auto-updates every 60s)

Risk controls active in paper mode: - Position limits (max_position in fleet.yaml) - Daily loss limit (max_daily_loss) - Session hours (session_start / session_end)

Live Trading

When paper results are satisfactory, one command takes you live:

python scripts/fleet_ctl.py promote my_strategy

What Changes

Risk Controls (Live)

• Position limits — max contracts per strategy
• Daily loss kill switch — auto-stops if daily loss exceeds threshold
• Session hours — only trades during configured window
• Halt dates — skip specific dates (FOMC, holidays) via halt_dates.txt
• Emergency kill — python scripts/run_live.py --kill (instant halt, no trades until --unkill)
• Demote — fleet_ctl.py demote <name> pulls strategy back to paper

Monitoring

Telegram Alerts

When TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID are configured, you receive: - Session start/stop — strategy came online or went offline - Trade entry — side, price, stop, target - Trade exit — result, exit signal, P&L - Risk rejection — signal blocked by risk manager (and why) - Order failure — order submitted but failed - Disconnect/reconnect — WebSocket connection issues - Kill switch — emergency shutdown activated

Dashboards

All dashboards show: aggregate summary, strategy cards with position/P&L, equity curves (Chart.js), trade history tables, live pulse indicator.

What You Write vs. What the Platform Handles

You Write

• strategy-intent.md — your thesis, in plain English
• strategy.py — your compute() method (with Claude's help)
• params_loader.py — your parameters as a dataclass
• Data scrapers (if your strategy needs external data not yet available)

The Platform Handles

• Bar delivery and history management
• Order execution and fill tracking
• Stop loss, take profit, breakeven management
• Position state and P&L calculation
• Risk controls (position limits, daily loss, session hours)
• Crash recovery and state persistence
• Real-time market data (polling + WebSocket)
• Trade logging (SQLite)
• Performance metrics (equity curves, drawdown)
• Backtesting across 5 years of historical data
• Stress test suite (walk-forward, Monte Carlo, slippage, entry delay, regime)
• Paper fleet orchestration (multiple strategies, shared connections)
• Live deployment (launchd auto-start, auto-restart)
• Telegram notifications (7 event types)
• Dashboard generation and Cloudflare deployment
• Scheduled monitoring (health check, watchdog, EOD summary)
• Git workflow isolation (can't break other researchers)
• Gate checks before deployment
• Data backfill (daily cron job)

Quick Reference: Common Workflows

"I have a thesis, test it fast"

/research my_idea
# Describe thesis in source/strategy-intent.md
# Claude builds strategy.py
/backtest my_idea
# Read metrics, iterate

"My strategy needs external data"

# Write a scraper: research_lab/scripts/fetch_my_data.py
# Output to: research_lab/data/my_data.csv
# Load in strategy via:
from research_lab.shared.aux_data import load_lab_csv
rows = load_lab_csv("my_data.csv")

"Backtest looks good, try it on live data"

# Update config.yaml status to ATS_APPROVED
/deploy add my_idea
# Run paper fleet
python scripts/run_fleet.py
# Watch paper dashboard

"Paper results hold up, go live"

/deploy promote my_idea
# Monitor via Telegram + live dashboard
# Sleep well (or don't)

"Something's wrong, pull it back"

/deploy demote my_idea          # Back to paper
python scripts/run_live.py --kill  # Emergency stop everything

"Check on everything"

/strategy-status    # All strategies and their states
/deploy status      # What's running where
/data-status        # Data archive health

Existing Strategies

Production Ready (ATS_APPROVED)

In Development (BUILD)

Early Research (RESEARCH)

Rules

1. Your workspace is your sandbox. Only edit inside research_lab/<name>/.
2. Engine is locked. Never modify engine/core/ — request changes via PR if needed.
3. Rebase, don't merge. Stay current with git fetch origin && git rebase origin/main.
4. Never expose credentials. .env is gitignored. Don't commit API keys.
5. One live strategy per account. Promoting replaces the current live strategy.
6. Document your work. Run /savegame at the end of sessions.
7. Shared data syncs via R2. GEX, QQQ, and tick capture databases sync from the hub. Core archives (Historical + Recent) are still per-operator.
8. Follow the pipeline. 7-phase research process. No shortcuts to deployment.