SuperAPI AI Directory

@2004/tqx-quant

General & other

View repository

Updated 10-16 06:14

About this skill

TQX Quant — Factor Analysis & Strategy Backtest

TQX (https://www.tqx.trade) is a HK/US stock quant platform. This skill drives it through the official tqx-cli pip package. Everything below was verified end-to-end against the live service.

Setup

pip install tqx-cli
tqx-cli login --email "$TQX_EMAIL" --password "$TQX_PASSWORD"

Credentials come from env vars (collect via secure input, never chat). Token is cached in ~/.tqx/config.yaml.

⚠️ Token expiry gotcha (verified): both accessToken AND refresh_token can expire together. Do NOT only match one specific error string — re-login on ANY response containing LOGIN_REQUIRED, 均已失效, or Please log in to continue. A strict matcher silently fails and every later call returns auth errors.

CLI command map

factor_create / factor_run / factor_result / factor_list / factor_delete
strategy_create / strategy_run / strategy_result / strategy_list / strategy_delete
backtest_result   # per-backtest detail: summary/account/position/profit/trade/log sections
workflow_list / workflow_stop / balance

Add --json for machine-readable output.

1. Factor analysis (cross-sectional IC/IR)

tqx-cli --json factor_create --market us --name "5d momentum" \
  --formula "close/ref(close,5)-1" \
  --start-date 20250101 --end-date 20250701 --group-number 2
tqx-cli --json factor_run <factor_id>          # waits and returns results

Result parsing gotcha: the result JSON has TWO formats depending on backend version — legacy nodes[].result_json and current root-level factor_analysis. Handle both. Key metrics: IC mean, IR, t-stat, annualized group returns, Sharpe.

2. Strategy backtest (panda_backtest engine)

tqx-cli --json strategy_create --market us --name "AAPL SMA cross" \
  --code "$(cat strategy.py)" \
  --start-date 20250101 --end-date 20250701 \
  --start-capital 1000000 --commission-rate 0.0003 --slippage 0.001 --frequency 1d
tqx-cli --json strategy_run <strategy_id>

Strategy code contract (ALL verified the hard way)

from panda_backtest.api.stock_us_api import *   # US market — MANDATORY
# HK market: from panda_backtest.api.stock_hk_api import *

def initialize(context):
    # Account ID is per-user — discover it once, do NOT hardcode.
    # The '8888' from CN-market docs does NOT exist for HK/US backtests.
    context.account = list(context.stock_account_dict.keys())[0]
    context.symbol = 'AAPL.US'   # symbol format: TICKER.US / 00700.HK
    context.prices = []
    context.holding = False

def handle_data(context, bar_dict):
    bar = bar_dict[context.symbol]
    # bar CAN be None on some days — unguarded access kills the run (error 10070)
    if bar is None or getattr(bar, 'close', None) is None or bar.close <= 0:
        return
    context.prices.append(bar.close)
    if len(context.prices) < 20:
        return
    s = sum(context.prices[-5:]) / 5
    l = sum(context.prices[-20:]) / 20
    if s > l and not context.holding:
        order_shares(context.account, context.symbol, 500)   # 3 args: account, symbol, qty
        context.holding = True
    elif s < l and context.holding:
        order_shares(context.account, context.symbol, -500)
        context.holding = False

Hard rules learned from real failures:

Symptom Root cause Fix
禁止使用危险函数 dir() Security filter blocks introspection Never use dir()/eval()/exec; to inspect context, raise Exception(str(...)) and read the error_detail in run logs
访问了不存在的键 on order Wrong account ID (e.g. '8888') Use list(context.stock_account_dict.keys())[0]
order_shares() missing 1 required positional argument Called with 2 args Signature is order_shares(account, symbol, quantity)
股票X不属于当前股票回测市场 Wrong symbol suffix US = TICKER.US, HK = XXXXX.HK; .O/.N/bare tickers are rejected
Backtest SUCCESS but 0 trades, 标的不在当前回测数据集内 Date range beyond ingested market data (recent months may not be loaded even though the benchmark series exists) Shift the window earlier (e.g. use last year's range); verify trades>0 in the trade section before trusting metrics
frequency rejected Only 1d and 1M are valid —

Reading results

strategy_run/strategy_result returns run status + node outputs. For full detail, extract the backtest id from run logs (BacktestNodeIdentifier: line) or node output, then:

tqx-cli --json backtest_result <backtest_id> --section summary   # profit, alpha, beta, sharpe, IR
tqx-cli --json backtest_result <backtest_id> --section trade     # ⚠️ always check trades executed
tqx-cli --json backtest_result <backtest_id> --section log       # per-order rejection reasons

A run can report SUCCESS with zero trades (orders silently rejected day by day). Always confirm the trade section is non-empty before reporting performance numbers.

Debugging failed runs

Error details are NOT in the top-level status — fetch run logs and read error_detail, which includes the exact strategy line number and exception message:

from tqx_cli.config import load_config
from tqx_cli.auth import require_login
from tqx_cli.workflow import get_run_logs
cfg = load_config(); token, uid, _ = require_login(cfg, cfg.get("_config_path"))
for l in get_run_logs(cfg, token, uid, run_id).get("logs") or []:
    if l.get("error_detail"): print(l["error_detail"])

Cost & pacing

Backtests are billed in TQX compute credits (tqx-cli balance). A 6-month daily-frequency single-stock backtest takes ~2 minutes wall time. Poll strategy_result every 3s; don't fire concurrent runs of the same workflow.