tqx

TQX Quant — ファクター分析と戦略バックテスト

TQX（https://www.tqx.trade）は香港株・米国株のクオンツプラットフォームです。このスキルは公式の tqx-cli pip パッケージを通じて TQX を操作します。

公式 TQX スキル（信頼できる情報源 — まずこれらを読んでください）

TQX は 2 つの公式スキルを公開しています。raw URL を直接取得してください（リポジトリの UI は JS の SPA であり、/-/git/raw/ の URL だけがコンテンツを返します）:

1. tqx-research — ファクター分析、戦略バックテスト、ワークフロー管理（Python の tqx-cli、メールアドレス/パスワードでログイン）:

• メイン: https://cnb.cool/liangyunzhijing/clis/-/git/raw/main/skills/tqx-research/SKILL.md
• リファレンス（コードを生成する前に読んでください — API を推測してはいけません）:
  • コマンド: .../skills/tqx-research/references/commands.md
  • 戦略テンプレート: .../skills/tqx-research/references/strategy_templates.md
  • 米国株 API: .../skills/tqx-research/references/stock_us_api.md
  • 香港株 API: .../skills/tqx-research/references/stock_hk_api.md
  • tqx_data: .../skills/tqx-research/references/tqx_data_usage.md （... は https://cnb.cool/liangyunzhijing/clis/-/git/raw/main に置き換えてください）

2. tqx-trading — 口座/ポジション/注文/約定の照会 + 認可された注文の発注（TypeScript の @tqx-ai/[email protected]、API キー認証、バージョンを固定してください）:

• メイン: https://cnb.cool/liangyunzhijing/clis/-/git/raw/main/skills/tqx-trading/SKILL.md
• OpenAPI: https://www.tqx.trade/openapi/v1/openapi.json（インタラクティブ: /openapi/v1/scalar）

ルーティングルール: リサーチ/バックテスト/ファクターの作業 → tqx-research（tqx-cli、Python）。実際の口座状態と注文の執行 → tqx-trading（tqx、TS CLI）。これらは異なる CLI と異なる認証（メールログインと TQX_API_KEY）を使用します — 混在させないでください。以下のこのスキルは、公式ドキュメントがカバーしていない内容を補足します: 検証済みのオンボーディング、障害モードの表、エージェント自動化のパターンです。

ユーザーオンボーディング（初回セットアップ、約 3 分）

1. 登録 — https://www.tqx.trade で登録します（メールアドレスでサインアップ）。PAPER（シミュレーション）口座が自動的にプロビジョニングされます — 以下のすべてのワークフローはこの口座で安全に実行できます。ペーパーとライブは同一の API です: tqx trading account は "mode": "PAPER" または "mode": "LIVE" を報告し、すべてのコマンド（positions、orders place|modify|cancel、trades）は両方で同一です。実際の資金への切り替えは TQX 側の口座レベルの変更であり、異なるコードパスではありません — まさにそのため、以下の注文サイズの上限と人間による承認ルールが重要になります。

   トレーディングコンペティション: TQX はエージェント向けのトレーディングコンペティションを開催しています — エントリーとルールは https://luma.com/dawwrdxk?tk=adzfZA にあります。コンペティション用の口座は同じダッシュボード（https://www.tqx.trade/hk/competition-manage?catalog=2）から作成され、ここでトレーディング CLI 用の TQX_API_KEY も発行されます。

2. 認証情報を安全に収集する: エージェントは TQX_EMAIL と TQX_PASSWORD に対して request_env_input を使用しなければなりません — チャットで認証情報を尋ねてはいけません。

3. インストール + ログイン + 検証:

pip install tqx-cli
tqx-cli login --email "$TQX_EMAIL" --password "$TQX_PASSWORD"
tqx-cli --json balance        # non-error response = onboarding complete

トークンは ~/.tqx/config.yaml にキャッシュされます。

4. 最初のクイックウィン（推奨デモ）: 以下の §1 の「5日モメンタム」ファクター分析を実行します — 約 1〜2 分で完了し、すぐに示せる IC/IR/シャープレシオの数値が得られます。

⚠️ トークン失効の落とし穴: accessToken と refresh_token の両方が同時に失効する可能性があります。特定の 1 つのエラー文字列だけにマッチさせないでください — LOGIN_REQUIRED、均已失效、または Please log in to continue を含むあらゆるレスポンスで再ログインしてください。厳密なマッチャーはサイレントに失敗し、以降のすべての呼び出しが認証エラーを返します。

CLI コマンドマップ

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

機械可読な出力には --json を追加してください。

1. ファクター分析（クロスセクショナル 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

結果パースの落とし穴: 結果の JSON にはバックエンドのバージョンに応じて 2 つの形式があります — レガシーの nodes[].result_json と、現在のルートレベルの factor_analysis です。両方を処理してください。主要な指標: IC 平均、IR、t 値、年率換算したグループリターン、シャープレシオ。

2. 戦略バックテスト（panda_backtest エンジン）

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>

ストラテジーコードの契約

from panda_backtest.api.api import *            # common trading API — MANDATORY
from panda_backtest.api.stock_us_api import *   # US market data API — MANDATORY
# HK market: from panda_backtest.api.stock_hk_api import *
import tqx_data

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.NB'   # symbol format: US = TICKER.NB (NOT .US!), HK = 00700.HK
    context.closes = []

def handle_data(context, data):
    account = context.stock_account_dict.get(context.account)
    if account is None:
        return
    bar = data.get(context.symbol)
    # bar CAN be None — with a WRONG suffix it is None EVERY day (silent 0-trade run)
    if bar is None or getattr(bar, 'close', None) is None or float(bar.close) <= 0:
        return
    price = float(bar.close)
    context.closes.append(price)
    if len(context.closes) < 20:
        return
    fast = sum(context.closes[-5:]) / 5
    slow = sum(context.closes[-20:]) / 20
    position = account.positions.get(context.symbol)
    quantity = 0 if position is None else position.quantity
    sellable = 0 if position is None else position.sellable
    if fast > slow and quantity == 0:
        buy_qty = int(account.cash * 0.9 // price)
        if buy_qty > 0:
            order_shares(context.account, context.symbol, buy_qty, style=MarketOrderStyle)
            print(f"BUY {buy_qty} @ {price:.2f}")   # print() = strategy log; SRLog is FORBIDDEN
    elif fast < slow and quantity > 0 and sellable > 0:
        order_shares(context.account, context.symbol, -sellable, style=MarketOrderStyle)
        print(f"SELL {sellable} @ {price:.2f}")

参照実行: このコードをそのまま AAPL.NB、20250101～20251231 で実行すると、18 件の実際の約定が生成されます（backtest_result <backtest_id> --section trade --all-pages で確認してください）。

実際の失敗から学んだ厳守すべきルール:

症状	根本原因	修正方法
禁止使用危险函数 dir()	セキュリティフィルターがイントロスペクションをブロックする	dir()/eval()/exec を決して使わないこと。コンテキストを調査するには、raise Exception(str(...)) を実行し、実行ログの error_detail を読んでください
注文時に 访问了不存在的键	誤った口座 ID（例: '8888'）	list(context.stock_account_dict.keys())[0] を使用してください
order_shares() missing 1 required positional argument	2 引数で呼び出した	シグネチャは order_shares(account, symbol, quantity) です
股票X不属于当前股票回测市场	誤った銘柄のサフィックス	米国 = TICKER.NB（.US ではない！）、香港 = XXXXX.HK。.O/.N/サフィックスなしのティッカーは拒否されます
バックテストは SUCCESS だが取引 0 件、ログ行 0 件、利益 = 0.0	銘柄のサフィックスが .US（またはその他の誤ったサフィックス）→ すべてのバーが None を返す → 防御的ガードがすべての日を黙ってスキップする	米国株には TICKER.NB を使用してください。必ず backtest_result <id> --section trade で検証してください — SUCCESS ≠ 約定が実行されたという意味ではありません
実行が即座に FAILED（約 0.3 秒、ノード失敗）	SRLog はストラテジーコードでは有効な API ではありません	ストラテジーのログ出力には素の print() を使用してください（--section log で表示されます）
実行ステータスが FAILED だが失敗ノードがない（すべてのノードが success/pending）	一時的な TQX キュー/スケジューラーのエラーであり、あなたのコードの問題ではありません	同じワークフローを一度再送信してください — 通常は約 30 秒で成功します。ノードが実際に失敗した場合にのみストラテジーコードをデバッグしてください
バックテストは SUCCESS だが取引 0 件、标的不在当前回测数据集内	日付範囲が取り込み済みの市場データを超えている（ベンチマーク系列が存在していても、直近数か月が読み込まれていないことがあります）	ウィンドウを以前にずらしてください（例: 昨年の範囲を使用）。メトリクスを信頼する前に、trade セクションで trades>0 を確認してください
frequency が拒否される	有効なのは 1d と 1M のみです	—

結果の読み取り

strategy_run/strategy_result は実行ステータスとノードの出力を返します。詳細をすべて取得するには、実行ログ（BacktestNodeIdentifier: の行）またはノード出力からバックテスト ID を抽出し、次を実行します:

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

実行が SUCCESS と報告されても取引が 0 件のことがあります（注文が日ごとに黙って拒否される）。パフォーマンス数値を報告する前に、必ず trade セクションが空でないことを確認してください。

日次エクイティカーブ（--section profit）

profit セクションは日次の NAV 系列です — 取引日ごとに 1 行で、gmt_create（YYYYMMDD）、strategy_profit（累積ストラテジーリターン、小数）、csi_stock（累積ベンチマークリターン、小数）を含みます。

# ⚠️ --all-pages does NOT work for the profit section: it silently returns only page 1 (100 rows).
tqx-cli --json backtest_result <backtest_id> --section profit --page-size 1000
# -> pagination {total: 252, page: 1, page_size: 1000, total_pages: 1}   ✅ full year in one call

対処すべきもう 2 つの挙動（参照: AAPL.NB、2025 年通年 = 252 行）:

• 行はソートされずに返されます — プロットする前に必ず gmt_create の昇順でソートしてください。API の順序を前提にしてはいけません。
• 値はパーセントではなく小数（-0.1174 = −11.74%）で、すでに累積値なので、そのままプロットしてください。再度複利計算しないでください。
• 最後の行は summary セクションのトータルリターンと一致する必要があります — これを正確性のチェックとして使用してください。

再取得する代わりに、系列をローカルにキャッシュしてください（実行ごとに 1 ファイル）: 呼び出しには約 2～4 秒かかり、実行が完了するとデータは不変です。

失敗した実行のデバッグ

エラーの詳細はトップレベルのステータスにはありません — 実行ログを取得し、error_detail を読んでください。これにはストラテジーの正確な行番号と例外メッセージが含まれます:

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"])

コストとペース配分

バックテストは TQX コンピュートクレジットで課金されます（tqx-cli balance）。日次頻度の単一銘柄の 6 か月バックテストは、実時間で約 2 分かかります。strategy_result を 3 秒ごとにポーリングしてください。同じワークフローの実行を同時に複数起動しないでください。

3. テンプレート（コピー＆ペーストの出発点）

T1 — モメンタムファクター（クロスセクション、全市場）

tqx-cli --json factor_create --market us --name "5d momentum" \
  --formula "close/ref(close,5)-1" \
  --start-date 20250101 --end-date 20250701 --group-number 5

その他の検証済みの数式: 平均回帰 -(close/ref(close,5)-1)、出来高急増 volume/mean(volume,20)。 ファクターモードは全市場クロスセクション専用です（--market hk|us）— 単一銘柄を対象にすることはできません。単一銘柄の質問にはストラテジーバックテスト（T2）を使用してください。

T2 — 単一銘柄のバックテスト (AAPL の SMA クロス)

§2 のストラテジーコード契約をそのまま使用してください — それがテンプレートです。変更するのは context.symbol とシグナルロジックのみです。None バーのガードと動的なアカウント検出は維持してください。

T3 — エージェント駆動の自動取引ループ

10 ラウンドのライブラン (~21 分、エンドツーエンド) で検証済みのパターン:

loop every N minutes:
  1. fetch live positions + account state
  2. compute signal (factor value or strategy rule)
  3. decide: buy / sell / hold  ← agent reasoning step
  4. place order (paper account, small fixed qty during development)
  5. journal the decision: {ts, reasoning, tool_calls, params, result, position_delta}

自動化に関する厳格なルール:

• デフォルトでは PAPER アカウント。 ライブ取引は同一のコマンドサーフェスを使用するため、コード内でライブ注文を止めるものは何もありません — 止められるのはあなたのゲーティングだけです。ループをライブアカウントに向ける前にユーザーの明示的な承認を必須とし、注文サイズのハードキャップを設け、常に --idempotencyKey を渡してリトライが二重約定を起こさないようにしてください。
• すべての判断をジャーナルに記録する (JSONL で十分です) — ユーザーは各取引がなぜ行われたかを監査できなければなりません。
• あらゆる認証系のエラー文字列で再ログインする (上記のトークンの落とし穴を参照); ループ途中のトークン失効は自己修復すべきであり、ループを停止させてはいけません。
• バックテスト系の呼び出しの前に毎回コンピュート残高を確認する ことで、サイレントな残高超過を回避してください。

T4 — Studio: すぐに実行できるコンパニオン UI (templates/studio/)

完全でテスト済みの Web ワークベンチがこのスキルに同梱されています — ダッシュボードをゼロから作らないでください。templates/studio/ をユーザーのワークスペースにコピーし、起動して、適応させてください。

ファイル:

ファイル	役割
server.py	標準ライブラリの HTTP バックエンド (ポート 8090、pip 依存なし)。tqx-cli をプロキシし、トークン失効時に自動再ログインし、すべての /api/* ルートを提供します
index.html	単一ファイルのフロントエンド: ファクター分析、バックテストの送信/履歴、ポジション、エージェントの判断タイムライン
agent.py	エージェント取引ループ (proxied_post 経由の LLM + ツール呼び出し)、JSONL 判断ジャーナル
backtests.py / strategies.py / journal.py	ディスク永続化モジュール (下記のデータ仕様を参照)

UI の言語: テンプレートは英語のみで提供されます。実行時に見かける中国語は TQX API 自体に由来するものです (メトリクスのキー名、エラー文字列) — これらは照合対象であるため、翻訳しないでください。

実行: studio ディレクトリから python3 server.py を実行し (バックグラウンド)、その上で preview(action="serve") を実行します。認証情報は TQX_EMAIL / TQX_PASSWORD 環境変数から取得します (セキュア入力で収集してください — ハードコードは決してしないでください)。

デザイン仕様 (リスタイル時も維持):

• ミニマリストなクオンツテックの美学: ダークファースト、等幅の数字、高密度なテーブル、装飾的なグラフィックなし。明るいテーマやサイバーパンク系のテーマは避けてください。
• 履歴の行はロード可能でなければなりません: 履歴レコードの「Load」をクリックすると、上部の結果エリアにその完全な結果が再表示されます (ファクター実行 → loadBt 経由でファクターメトリクス/チャート; ストラテジー実行 → loadStgBt 経由で専用のストラテジー結果カード: ベンチマークに対するリターン、年率、シャープレシオ、最大ドローダウン、取引回数、パラメータ + コードリンク)。行を一覧表示するだけでロードバックできない履歴テーブルは不完全です。
• UI が公開するのは高頻度のパラメータ (フォーミュラ、市場、日付範囲、グループ、リバランス、方向) + アカウントスイッチャー + NAV 曲線 + 判断タイムラインのみです。複雑なものすべて (カスタムストラテジーコード、銘柄プール、手数料/スリッページ) は会話レイヤーに留めます — エージェントは完全な CLI サーフェスを持っており、UI がそれを重複させてはいけません。
• 金額: ゴールド/キャッシュの値は単一の専用フォーマッターで整形してください。競合する 2 つのフォーマッターは一貫しない出力を生みます。すべてのカードでダークモードのコントラストを確認してください。

永続化とパス (なぜ 2 つのディレクトリなのか):

tqx-cli はログイン設定を /root/.tqx/config.yaml に書き込みますが、これはコンテナのエフェメラルレイヤー上にあり、マシンの再起動のたびに消去されます — エージェントは気づかないうちにセッションを失うことになります。再起動後も存続するのは /data/workspace だけなので、studio は設定を /data/workspace/.tqx/ にミラーし、起動時に双方向で同期します (server.py の sync_tqx_config()、agent.py の _sync_tqx_config())。 これらのパスは意図的に固定されており、移植性の見落としではありません。すべてのエージェントが同一のレイアウトを持ちます — /data/workspace = 永続ボリューム、/root = 一時的。スタジオを拡張する際はこのルールを守ってください: 再起動をまたいで存続させる必要があるものはすべて workspace の下に書き込み、/root や /tmp の下には決して書き込まないこと。 スタジオ内の状態（data/backtests、data/journal、data/strategies）はすでに __file__ 相対であるため、スタジオ自体が workspace にコピーされている限り永続性を継承します。Starchild マシン以外でこれを実行する場合は、永続ルートを上書きしてください — コード内の他の部分は絶対パスを前提としていません。

データストレージ仕様:

• data/backtests/index.json + 実行ごとに 1 つの JSON — 戦略コード文字列全体（切り詰めたプレビューではなく）を必ず永続化し、どの実行も再ロードして再編集できるようにする必要があります。
• data/journal/*.jsonl — エージェントの決定ごとに 1 行、source: manual | agent のタグ付き、追記専用、決して書き換えない。
• data/strategies/ — 名前付きで保存された戦略。すべての状態はディスク上のプレーンな JSON です。DB はありません。

テスト仕様（スタジオを「動作中」と宣言する前に）:

1. curl localhost:8090/api/health（または任意の GET ルート）が JSON を返す — バックエンドが稼働中。
2. UI から 1 つの実際のバックテストを送信し、完全なコード + メトリクスとともに履歴パネルに表示されることを確認します。レンダリングされたページだけでは検証にはなりません。
3. backtest_result <id> --section trade で約定が存在することを確認します — SUCCESS ステータスで取引が 0 件の場合は、シンボルサフィックスのバグです（失敗表を参照）。
4. server.py を強制終了／再起動し、履歴が永続化されている（メモリではなくディスク）ことを確認します。