Echolon

📖 English · 简体中文

An LLM-agent-native backtest framework for futures research. Ships an MCP server, 22 in-package skills, 32 catalogued error codes, and typed Pydantic configs — agents call structured tools instead of guessing API shapes from prose docs. End-to-end on SHFE daily futures.

Production engine inside Qorka, DolphinQuant's AI-native strategy generation product. Exercised by real money on SHFE every trading day.

Quickstart

Three commands cover the natural newcomer arc:

pip install echolon
mkdir -p ~/echolon-playground && cd ~/echolon-playground
echolon hello                  # 30-second demo

echolon hello downloads ~2y of aluminum data, scaffolds the momentum_breakout template, writes .echolon-workspace.json, and runs the backtest. Open ./echolon-hello/strategy/baseline/entry.py, tweak a parameter, then re-run with echolon backtest single ./echolon-hello/strategy/baseline/ to see how the Sharpe shifts.

Three templates ship in-package — minimal, momentum_breakout, rsi_mean_reversion. echolon examples --list shows them; pass --template <name> to echolon init / echolon hello to start from one.

If pip install fails on Linux ARM64 / Alpine / FreeBSD, run echolon doctor — it diagnoses ta-lib's C library, the only dependency that may need source-building outside the standard prebuilt-wheel platforms (Linux x86_64, macOS x86_64+arm64, Windows x86_64; Python 3.11–3.12).

Drive it from your agent

pip install echolon                                # 1. install
claude mcp add -s user echolon -- echolon-mcp      # 2. register MCP server (user-wide)
# 3. restart Claude Code to load mcp__echolon__* tools

Then ask:

"Build a trend-following strategy on copper, backtest 2018–2024."

Behind the scenes the agent calls list_skills → picks patterns and quick_start → load_template("momentum_breakout") → list_indicators(has_lookback=True) → edits entry.py and exit.py → loops validate_strategy_full(strategy_dir) until everything passes → runs the backtest. If anything breaks, it parses [CODE-NNN] from the traceback and calls get_error_doc(code). There's no point where it has to guess.

For Claude Code: -s user makes the registration apply across all your projects (drop it for current-project-only); -- separates the registration name from the launch command. After running once, claude mcp list should show echolon as a connected stdio server. The agent's orientation guide is llms.txt — also dropped at the workspace root by echolon init / hello so an agent walking into the project finds it without needing the package.

What's in scope today

Done end-to-end (production-grade, exercised daily):

• SHFE daily futures research — data ingestion, 214-indicator catalog, Backtrader execution, Optuna TPE optimization (single + multi-objective), walk-forward analysis with deployment-readiness scoring, KMeans-based robust trial selection.

• Agent surface — 23 MCP tools, 22 skills, 32 error codes, 3 working templates.

Not yet (open an issue if you want to drive a slice forward):

• SHFE intraday backtesting — data pipeline ready, engine plumbing being firmed up.

• Live trading via MiniQMT — clean public release in progress.

• Crypto perpetuals (CCXT adapter scaffolded), CME futures, equities.

• Optuna alternatives (no grid, no random, no Bayesian-budget search), distributed orchestration, Python ≤ 3.10.

• Pre-1.0 — public API may change between minor versions. Breaking changes documented in CHANGELOG.md.

Bring your own data

If you already have raw SHFE XLS files (downloaded from shfe.com.cn), run SHFEFileDayExtractor directly instead of using akshare. For other formats (broker CSV, tushare, custom DB), three files must end up under {workspace}/workspace/data/market_data/SHFE/{instrument}/:

Plus under {workspace}/data/SHFE/{instrument_code}/ (note the SHORT code, e.g. al not aluminum):

Echolon does not auto-derive main_contract.csv from raw OHLCV — it's a USER input that encodes your roll convention (rules based on volume, open interest, or days to expiry). For SHFE via akshare, echolon init derives it for you; otherwise produce it yourself and drop it in place.

Project info

Apache 2.0 — see LICENSE. Use freely, commercially or otherwise. Active development, v0.1.2 beta. Built and maintained by DolphinQuant — the same team running Qorka on SHFE. Issues and pull requests welcome at github.com/dolphinquant/echolon.

@software{echolon,
  title = {Echolon: AI-native quantitative trading engine},
  author = {DolphinQuant},
  year = {2026},
  url = {https://github.com/dolphinquant/echolon},
}