Atabet-Trader

Event-driven algorithmic trading engine for backtest, simulation, and live trading.

Features

• Same strategy code for backtesting, simulation, and live trading
• Supports equity and futures
• Gateways: Backtest, Futu (securities / futures / crypto), Interactive Brokers (IB), QMT (Big QMT via Redis bridge) (CQG source is retained but disabled for public use)
• Plugins: analysis, live monitor (Dash, or a MonitorSink callback for Atabet Terminal), Telegram bot, SQLite, ClickHouse
• Token-based license checking via the Quant Intelligence license (com.atabet.chat)
• N-minute bars (5Min / 15Min / …) via shared 1Min→N-min aggregation (atabet_trader.core.bar_aggregate) for historical requests and backtest when only K_1M CSV data is available
• Daily backtest via TIME_STEP = 86_400_000 + K_1D/{code}/ohlcv.csv (Yahoo sample equities: AAPL / MSFT / GOOGL). A backtest that records 0 bars (header-only result.csv) raises instead of looking like success — see samples/AGENT_INVARIANTS.md.
• Stock backtest CSVs are stored raw; corporate-action factors live in {kline}/adj_factor/{code}/adj_factor.csv and are applied at load (ADJ_METHOD=qfq by default). Each vendor uses its own formula (Futu A/B, Tushare daily factor/last, Yahoo CRSP, Bloomberg DPDF). Refresh the factor file without re-downloading bars.

Authentication

Engine requires a valid authentication token. Install auth support with pip install atabet-trader[auth] (requires atabet-token for licensing-server session support).

Token types

import os
import socket
from atabet_trader.core.engine import Engine

engine = Engine(
    gateways={gateway_name: gateway},
    token=os.environ["ATABET_TRADER_TOKEN"],
    licensing_server_url=os.environ.get(
        "LICENSING_SERVER_URL", "http://39.101.65.167:5001"
    ),
    device_name=os.environ.get(
        "ATABET_DEVICE_NAME",
        os.environ.get("ATABET_CLIENT_ID", socket.gethostname()),
    ),
)

# Dev HMAC token (offline / local testing)
engine = Engine(
    gateways={gateway_name: gateway},
    token=dev_token,
    validation_method="original",
)

When Quant Intelligence runs a script it sets ATABET_DEVICE_NAME and ATABET_SESSION_TOKEN. Engine uses those, so a backtest on that computer shares the app's seat instead of opening another. Basic is one seat online. Pro is three. A new install past the cap takes the oldest seat.

Licenses must be issued with application_id: "com.atabet.chat". BacktestGateway runs on a Basic license (plan: basic). Any other gateway requires plan: professional. A token with no plan claim is a legacy license and can still open simulate and live gateways. Call engine.close() (also invoked from engine.stop()) to free a licensing session slot via POST /logout.

Environment preparations

Quant Intelligence users: create the combined stack with ../atabet-quant-intelligence/environment.yml (atabet_env) instead of a trader-only env.

conda env create -f environment.yml
conda activate atabet_trader_env
pip install -e ".[auth,dev]"

Optional extras:

pip install -e ".[futu,ib,qmt,monitor,telegram,clickhouse]"
# or
pip install -e ".[all]"

Configuration

At the working directory (or on PYTHONPATH), create atabet_trader_config.py. Use atabet_trader_config_sample.py as a template.

DATA_PATH = {
    "kline": "sample_data/k_line",
}
ACTIVATED_PLUGINS = ["analysis"]

Backtest data (CSV-on-disk only) — illustrated cookbook: samples/LLM_DATA_PATH_GUIDE.md.

{DATA_PATH["kline"]}/K_1M/{security.code}/YYYY-MM-DD.csv   # TIME_STEP=60000
{DATA_PATH["kline"]}/K_1D/{security.code}/ohlcv.csv        # TIME_STEP=86400000
{DATA_PATH["kline"]}/adj_factor/{security.code}/adj_factor.csv  # stocks; load-time QFQ/HFQ
# DATA_PATH["kline"] = parent of K_1M / K_1D (not the symbol folder)
# Do not add "adj_factor" as a DATA_PATH key

CSV header: time_key,open,high,low,close,volume (time column first; no extra broker export columns). Native K_5M / K_15M are used when present; otherwise aggregatable TIME_STEP values build N-min bars from K_1M.

Repo sample equities under K_1D/ (AAPL / MSFT / GOOGL) were downloaded via the atabet-data Yahoo channel. General channel download (yahoo / futu / qmt / blpapi / tushare, daily or 1-min where the channel allows, ticker aliases): samples/download_atabet_data_kline.py (see also atabet-data samples/LLM_TRADER_HANDOFF_GUIDE.md).

cd samples
export ATABET_DATA_TOKEN='...'   # for download_atabet_data_kline.py
# Tushare also needs: export TUSHARE_TOKEN='...'
python download_atabet_data_kline.py --source yahoo --freq 1D \
  --tickers "AAPL,TSLA,700 HK,600519 CH" \
  --start 2023-01-01 --end 2025-12-31 --out /tmp/my_kline
# Multi-year 1-minute: --source futu --freq 1M  (Yahoo/QMT/Bloomberg cannot do this)
# Futu stocks: raw klines + get_rehab factor file; optional --verify-adj
python download_atabet_data_kline.py --source futu --freq 1D \
  --tickers "AAPL,700 HK" --start 2020-01-01 --end 2020-12-31 \
  --out /tmp/my_kline --verify-adj
# Bloomberg daily (Terminal + xbbg): raw PX (adjust='-') + DVD_HIST_ALL / splits
# ADJ_METHOD=qfq at load. Live check vs adjust='all': DPDF cash (P-D)/P + split 1/N
# plus EQY_DVD_ADJUST_FACT multiply for spinoffs Bloomberg still applies.
# method='hfq' is a no-op (no BDH backward adjust). Do not persist adjust='all'.
python download_atabet_data_kline.py --source blpapi --freq 1D \
  --tickers "AAPL,700 HK,600519 CH" --start 2020-01-01 --end 2020-12-31 \
  --out /tmp/my_kline
# Tushare daily A-shares: raw pro.daily + adj_factor series (needs TUSHARE_TOKEN)
python download_atabet_data_kline.py --source tushare --freq 1D \
  --tickers "600519 CH,000001.SZ" --start 2023-01-01 --end 2025-12-31 \
  --out /tmp/my_kline
python prepare_backtest_data.py --out /tmp/my_kline --code FUT.GC
python prepare_backtest_data.py --validate /tmp/my_kline --code FUT.GC
python prepare_backtest_data.py --validate ../sample_data/k_line --code AAPL --freq K_1D
python download_yahoo_k1d.py   # optional daily Yahoo shortcut (no Atabet token)

LLM / onboarding docs under samples/:

Quick start (backtest)

from datetime import datetime
from atabet_trader.core.constants import TradeMode, Exchange
from atabet_trader.core.event_engine import BarEventEngineRecorder, BarEventEngine
from atabet_trader.core.security import Stock
from atabet_trader.core.engine import Engine
from atabet_trader.core.strategy import BaseStrategy
from atabet_trader.gateways import BacktestGateway

class MyStrategy(BaseStrategy):
    def init_strategy(self):
        pass

    def on_bar(self, cur_data):
        print(cur_data)

stock_list = [
    Stock(code="HK.01157", lot_size=100, security_name="example", exchange=Exchange.SEHK),
]
gateway_name = "Backtest"
gateway = BacktestGateway(
    securities=stock_list,
    start=datetime(2021, 3, 15, 9, 30, 0, 0),
    end=datetime(2021, 3, 17, 16, 0, 0, 0),
    gateway_name=gateway_name,
)
gateway.SHORT_INTEREST_RATE = 0.0
gateway.set_trade_mode(TradeMode.BACKTEST)

engine = Engine(gateways={gateway_name: gateway}, token=your_token)
# ... init strategy, recorder, BarEventEngine, then event_engine.run()

Full runnable demo:

export ATABET_TRADER_TOKEN='...'
cd samples
python main_demo.py

Simulation / live trading

Replace the backtest gateway with FutuGateway, FutuFuturesGateway, FutuCryptoGateway, IbGateway, or QmtGateway and set TradeMode.SIMULATE or TradeMode.LIVETRADE. Install the matching optional extra first. List currently importable gateways with from atabet_trader.gateways import list_available_gateways.

Big QMT (QmtGateway): MiniQMT / external xtquant is being phased out; Big QMT has no XtQuantServer, so trading runs through a Redis bridge. Deploy atabet_trader/gateways/qmt/agent/atabet_qmt_bridge.py inside the Big QMT built-in strategy environment (see agent README), keep the QMT client logged in, and point GATEWAYS["Qmt"] at Redis (redis_host / redis_port / redis_password / redis_db). The same bridge is shared with atabet-data (source='qmt') — do not run a second strategy on the same key prefix. Historical bars (req_historical_bars for native 1Day / 1Min, plus aggregatable N-min such as 5Min / 15Min built from 1Min via bar_aggregate) use bridge op get_market_data_ex → Big QMT ContextInfo.get_market_data_ex. Financial datasets use get_raw_financial_data / get_divid_factors / get_instrumentdetail. QMT reads local history only — use 数据管理 → 补充数据 for each symbol/period you need; short lookbacks usually mean missing local data, not an RPC failure. Optional config: hist_rpc_timeout (default 30s), hist_max_count, hist_fill_data / hist_subscribe (default False). Install pip install -e ".[qmt]". Keep allow_orders=False (and agent ALLOW_ORDERS=False) until python samples/qmt_bridge_smoke.py succeeds. Strategy hosts may be macOS/Linux; Big QMT itself remains Windows.

Engine.start() is safe to call more than once (the persist thread starts at most once). BarEventEngine.run() also calls start(), which is how Atabet Terminal switches the same strategy folder from Backtest to Simulate/Live.

Interactive Brokers (IbGateway): install the official ibapi Python client from interactivebrokers.github.io and match the API build to your TWS/Gateway (e.g. API 10.48 with TWS 1048). The ib extra expects the ibapi package; it is not reliably available on PyPI from IB. Configure GATEWAYS["Ib"] in atabet_trader_config.py (host, port paper TWS 7497, clientid, broker_account). US cash names like US.VOO (or bare VOO) map to SMART / STK / USD. Weekend paper uses BTC.USD (Currency + Exchange.PAXOS → CRYPTO); those market orders are cashQty-only. Close other live TWS/IBKR sessions on the same account — competing sessions block market/historical data (IB errors 10197 / 162). Crypto spot (e.g. BTC.USD) maps to IB CRYPTO on PAXOS and needs a PAXOS crypto market-data subscription (AGGTRADES); without it you get IB error 162/354. CME crypto futures (e.g. MBT) may have market data but still require Virtual Asset trading permission to place orders. IbGateway disables ibapi 10.48 protobuf encoding for place/cancel (classic socket) because protobuf placeOrder can fail silently.

Important: live mode can send real orders. Use simulation first and review risk controls. Futu crypto (FutuCryptoGateway) supports live trading only (no paper trading).

Live monitoring and Telegram

Enable plugins in atabet_trader_config.py:

ACTIVATED_PLUGINS = ["analysis", "monitor", "telegram"]
TELEGRAM_TOKEN = ""       # prefer env / secret store
TELEGRAM_CHAT_ID = 1

Monitor UI (when enabled): http://127.0.0.1:8050

Atabet Terminal is the product monitor: pass BarEventEngine(..., monitor_sink=sink) and the engine will not pickle or start Dash. Headless scripts that activate "monitor" without a sink keep this Dash path. See samples/LLM_PLUGINS_GUIDE.md.

Packaging

Protected wheels are built with Cython (sources stripped; __init__.pyc kept for importability). samples/ remain plain Python in the distribution.

python setup.py bdist_wheel
# or via cibuildwheel in CI

Test

pip install -e ".[auth,dev]"
DEV_MODE=1 pytest tests/ -v

Integration / broker scripts live under tests/manual_*.py and are not run in default CI. Licensing-server integration tests are marked @pytest.mark.integration.

Note: Analysis / recorder / historical-data helpers avoid pandas in-place column writes (df[col]=…, .T then mutate). They use DataFrame rebuilds and .assign so Cython-built extensions stay compatible with pandas ≥3 Copy-on-Write.

GitHub Actions

• Test workflow: every push and pull request (pytest with .[auth,dev])
• Build wheels (build-wheels.yml): runs when the tip commit message contains [build ci], [pub pypi], or [pub test.pypi] (case variants allowed), or via workflow_dispatch (build only — no publish).
• Publish: tip commit must include [pub pypi] (PyPI) or [pub test.pypi] (TestPyPI). Each OS job uploads its own wheelhouse/ directly, so a full Actions artifact quota does not block the release. Linux uses gh-action-pypi-publish; Windows and macOS use the same trusted publisher via twine, because that action only runs on Linux. Requires Trusted Publishing on PyPI for workflow build-wheels.yml (no GitHub Environment), or an API token wired into the publish step. Artifacts, when saved, are kept for 1 day.

Project structure

atabet-trader/
├── atabet_trader/          # library package
│   ├── core/                # Engine, Strategy, event loop, types
│   ├── gateways/            # Backtest, Futu, IB, QMT (+ disabled CQG)
│   │   └── qmt/agent/       # Big QMT Redis bridge
│   └── plugins/             # analysis, monitor, telegram, sqlite3, …
├── samples/                 # demos + LLM_* guides (plain .py in wheels)
├── sample_data/             # offline bar CSVs for demos/tests
├── tests/                   # pytest + manual broker scripts
├── atabet_trader_config_sample.py
├── pyproject.toml
├── environment.yml
├── setup.py
└── build_wheel.py

See samples/LLM_PROJECT_STRUCTURE.md for the config import contract (atabet_trader_config on CWD / PYTHONPATH).

License

Proprietary — ATABET LIMITED. Contact: info@atabet.com