Terminus

End of All Trades

Ruthless backtesting lab for long-only spot strategies. Where strategies prove themselves, or die.

Why  ·  Features  ·  Install  ·  Quickstart  ·  Presets  ·  CLI  ·  Strategies  ·  Execution  ·  ML  ·  Env  ·  Hub  ·  Structure  ·  API  ·  Roadmap  ·  Contributing

pip install terminus-lab

💡 Why Terminus

Most backtesting tools make it easy to overfit. Terminus makes it hard to cheat.

• Walk-forward required. Frozen parameters tested year by year. At most 2 losing years tolerated, each no worse than -10%.
• Bear years count. 2022 was -64% on BTC. Your strategy survives that or it doesn't ship.
• Multi-pair generalization. Works on one pair? That's a curve fit. Terminus requires success across at least 5 pairs.
• Realistic execution. Tiered slippage by market cap, maker/taker fees, cooldowns, max-hold timeouts.
• Halal-first. Spot-only, no leverage, no shorts, no interest. Cash is a valid position.
• Content-hashed cache. Every sim keyed by SHA-256(pair + tf + config + dates + slippage + fee). Same inputs = instant hit.

✨ Key Features

30 Strategy Families

Each family also has a +BTCreg variant that gates entries on the BTC regime classifier, effectively doubling the config space to 60.

6 Exit Methods

All 6 are implemented in the simulator. The default sweep uses the 3 marked above; trail-based methods can be enabled with --exit-methods.

Exit-check fidelity (exit_check)

The single biggest backtest trap is an exit model that doesn't match how the live engine samples price — it can invert your conclusions. simulate_fast(..., exit_check=...) (and run_full_sweep(..., exit_check=...)) makes the fidelity explicit:

path mode is modelled worst-case: a bar's low is tested against the stop carried from prior bars before that same bar's high can ratchet the trail (a real stop can't use a bar's own high to dodge its own low), and a stop never fills above the bar's own high (gap-through fills at the worse gapped price, not the untouched level). Pick the mode that matches your live closer — mismatching it is how a losing strategy backtests as a winner.

📦 Installation

From PyPI (recommended)

pip install terminus-lab

With ML support

pip install terminus-lab[ml]

This adds LightGBM and scikit-learn — everything needed for both the screener and regime classifier.

From source (development)

git clone https://github.com/Stronex-Labs/terminus.git
cd terminus
pip install -e ".[dev,ml]"

Requirements

• Python 3.10+ (tested on 3.10, 3.11, 3.12, 3.13)
• Core deps: numpy, pandas, pandas-ta, httpx
• ML deps (optional): lightgbm, scikit-learn, joblib
• Storage: ~2 GB for full 21-pair 8-year Parquet cache
• RAM: 4 GB minimum, 8 GB recommended for full sweeps

Verify installation

terminus --help

🚀 Quickstart

# 1. Fetch 8 years of data (21 pairs, 8 timeframes)
terminus fetch

# 2. Run the full parameter sweep
terminus sweep

# 3. Walk-forward the top candidates year-by-year
terminus walk-forward --top 15

# 4. Generate the survivor report
terminus report --min-calmar 1.5 --min-bear-return -5

# 5. Build a portfolio from survivors
terminus portfolio

Minimal quick-run (single pair)

terminus fetch --pairs BTCUSDT --tfs 4h,1d --days 2920
terminus sweep --pairs BTCUSDT --tfs 4h,1d
terminus walk-forward --pairs BTCUSDT --top 5
terminus report

Example Output

=== TOP 15 SURVIVORS by ANNUALIZED return ===
 Rank  Pair       TF    Family                   Yrs   TotalRet   AnnRet   Calmar   Bear22
 ----- ---------- ----  -----------------------  ----  --------   ------   ------   ------
   1   TIAUSDT    2h    Ichi-bull+BTCreg          3/3    +90.7%    +24.0%    2.77     -
   2   XRPUSDT    2h    Ichi-bull+BTCreg          6/6   +213.5%    +21.0%    5.68    +0.0%
   3   LTCUSDT    12h   Ichi-bull+BTCreg          3/3    +70.1%    +19.4%    4.28    +0.0%
   4   BNBUSDT    1h    ROC10+BTCreg              5/5   +133.2%    +18.4%    4.93    +0.0%
   5   SOLUSDT    4h    ATR-brk                   5/5   +130.6%    +18.2%    7.86   +13.2%

🎯 Sweep Presets

Common sweep configurations for different use cases:

Full discovery (default)

terminus sweep

Runs all 21 pairs, all 8 timeframes, fixed_tp_stop exit method. ~10,000+ configs tested. Takes 30-60 minutes on a modern machine.

Extended exit methods

terminus sweep --exit-methods fixed_tp_stop,atr_trail,chandelier_trail,breakeven_after_1r,scale_out_half_at_1r

All exit methods enabled. 5x the configs. Multi-hour run.

Regime-gated only

terminus sweep --pairs BTCUSDT,ETHUSDT,SOLUSDT --tfs 4h,1d

Focus on majors with fewer timeframes for faster iteration.

No regime filter

terminus sweep --no-regime

Skips the +BTCreg variants. Half the config space, useful for pairs with limited BTC correlation.

Labeled runs

terminus sweep --label "q2-2026-majors"
terminus walk-forward --label "q2-2026-wf"

Label manifests for organization and comparison between runs.

🖥 CLI Reference

terminus fetch

Download and cache Binance klines as Parquet files.

terminus fetch [OPTIONS]

terminus sweep

Run full parameter sweep across all strategy families.

terminus sweep [OPTIONS]

terminus walk-forward

Calendar-year walk-forward validation of top candidates.

terminus walk-forward [OPTIONS]

terminus report

Filter survivors and print ranked report.

terminus report [OPTIONS]

terminus portfolio

Build a correlation-capped portfolio from survivors.

terminus portfolio [OPTIONS]

terminus contribute

Upload sim results to the community hub.

terminus contribute [OPTIONS]

terminus ml regime

Train the LightGBM regime classifier on BTC daily data.

terminus ml regime [OPTIONS]

terminus ml train

Train LightGBM screener from sweep results.

terminus ml train [OPTIONS]

Global flags

⚙ Execution Model

Terminus models realistic execution, not idealized fills:

Majors: BTC, ETH, SOL, XRP, BNB   |   Mid-caps: top 20-50 by market cap   |   Small-caps: everything else

Entry fills at next bar's open. Stops fill at stop price with adverse slippage. TPs fill at limit price with favorable slippage. Timeouts fill at close with slippage.

🧠 ML Module

Dependencies: Install with pip install terminus-lab[ml] to get LightGBM and scikit-learn. All ML features (screener + regime classifier) are covered by this single extra.

terminus ml train
terminus ml train --calmar-threshold 2.0 --no-funding

terminus ml regime
terminus ml regime --days 3650 --output ./models/regime_v2

🔧 Environment Variables

🖥 Recommended Setup

Hardware

Data coverage

For robust walk-forward results, use at least 4 years of data (--days 1460). The default 8 years (--days 2920) ensures coverage of both bull (2021) and bear (2022) regimes.

Default pairs (21)

BTCUSDT  ETHUSDT  SOLUSDT  XRPUSDT  BNBUSDT  TRXUSDT  DOGEUSDT
ADAUSDT  AVAXUSDT LINKUSDT MATICUSDT DOTUSDT  LTCUSDT  ATOMUSDT
NEARUSDT SUIUSDT  APTUSDT  ARBUSDT  OPUSDT   TIAUSDT  INJUSDT

Default timeframes (8)

15m  30m  1h  2h  4h  6h  12h  1d

🌐 Community Hub

Leaderboard: terminus-hub.shatla-tech.workers.dev

After every terminus sweep and terminus walk-forward, Terminus automatically contributes your survivors to the community hub. Sims are stored locally first; remote send retries on the next run if the network was down.

• Results are deduplicated by content hash
• Contributor count increments when multiple users discover the same strategy
• Rare pairs get coverage from users who care about them

# Opt out
export TERMINUS_TELEMETRY=0

# Force-upload everything
terminus contribute --all

# Enable sharing explicitly
terminus contribute --enable

🧪 Survivor Filters

A strategy must pass all of these to be promoted:

All thresholds are configurable via CLI flags (e.g. --min-calmar, --min-bear-return).

📁 Project Structure

terminus/
├── cli.py              # Entry point — all subcommands
├── fetch.py            # Async Binance kline fetcher (Parquet cache)
├── simulate.py         # Vectorized trade simulator, 6 exit methods
├── sweep.py            # Parallel parameter sweep engine
├── walk_forward.py     # Frozen / anchored modes
├── filter.py           # Survivor filtering + report
├── portfolio.py        # Greedy correlation-capped portfolio builder
├── registry.py         # Strategy family x parameter grid permutations
├── rules.py            # Vectorized entry signal rules (VRule)
├── indicators.py       # Two-layer indicator precompute (30+ indicators)
├── store.py            # SQLite research DB, content-hashed caching
├── telemetry.py        # Local telemetry + community hub submission
├── funding.py          # Funding rate data
├── sentiment.py        # Fear & Greed index
├── risk/
│   ├── factor_model.py # Risk factor analytics
│   ├── metrics.py      # Sharpe, Calmar, max drawdown, etc.
│   └── rademacher.py   # Rademacher-adjusted Sharpe (multiple-testing deflation)
└── ml/
    ├── regime.py       # LightGBM 3-class regime classifier
    ├── optim.py        # Walk-forward-aware random optimizer
    ├── features.py     # Feature engineering
    ├── dataset.py      # Dataset builder from sweep results
    └── train.py        # LightGBM screener training

🔌 API & Plugins

Status: Planned for v0.5+

REST API (planned)

A local HTTP server for programmatic access to sweep results, walk-forward data, and portfolio state. Will serve the web dashboard and expose JSON endpoints.

Plugin system (planned)

Extensibility for:

• Custom data sources (beyond Binance)
• Custom exit methods
• Custom strategy families
• Custom portfolio construction algorithms
• Result exporters (CSV, Notion, Telegram)

Currently, new strategies are added by editing terminus/registry.py and terminus/rules.py directly. Plugin architecture will formalize this in v1.0.

🏛 Philosophy

🗺 Roadmap

🤝 Contributing

PRs welcome for:

• New strategy families (numpy-vectorized signals)
• Alternative data fetchers (Kraken, Coinbase, OKX, Bybit spot)
• Portfolio construction methods
• New walk-forward modes
• Exit method variants
• ML feature engineering

See CONTRIBUTING.md.

⚠ Disclaimer

Terminus is a research tool. It is not financial advice.

• Past backtest performance does not guarantee future results
• Walk-forward validation reduces but does not eliminate overfitting risk
• Always paper-trade validated strategies before risking real capital
• The authors are not financial advisors and bear no responsibility for trading decisions made using this software
• Crypto markets are volatile; you can lose your entire investment
• This tool is provided "as-is" without warranty of any kind

License

MIT. Use it, fork it, ship it. If you find something useful, open a PR. The community sim database grows stronger with every contributor.

_{Built by Stronex Labs}