quant-trading-experiment
暂无简介
- License 许可
- Apache-2.0
- 最近更新
- 2026-10-24
- Stars
- ★ 0
- Forks
- 0
02 资源文件 1
- 参考文档skill.json365 B
03 SKILL.md 正文
quant-trading-experiment
Quant Trading Experiment
Operate a 12-room, 20-agent quantitative research organization with live demo trading on BingX VST.
Architecture (stable)
- CT106
cortexquant=192.168.1.19. FastAPI :8080. - 12 Rooms: QUANT_RESEARCH, WEIRD_EDGE, MATH_SIGNAL, STRATEGY_ENG, REGIME_DETECTION, BACKTEST, OPTIMIZATION, SELECTION, RED_TEAM, TRADING_JOURNAL, AI_COACH, RISK_COMMITTEE.
- Signal Flow: Telegram → Telethon MTProto → Parse → 12-Step Validation → Rooms + Demo → BingX VST.
- LIVE_TRADING=false hard default. Demo uses
DEMO_TRADING=true.
Critical startup pattern
await server.serve() blocks forever. Demo initialization MUST be a background task:
# CORRECT
asyncio.create_task(start_demo_experiment())
await server.serve()
# WRONG — never reached
await start_demo_experiment()
await server.serve()
BingX API quirks
- Demo balance key is
VST, notUSDT:balance.get("VST", {}).get("total", 100000) - Perpetual swap symbols:
AVAX/USDT:USDTnotAVAX/USDT. Use_get_swap_symbol(). - Position side required:
params={'positionSide': 'LONG', 'leverage': 3} - Sandbox:
exchange.set_sandbox_mode(True)— VST only, no real funds.
Schema dependencies
tg_parsed_signals.raw_message_id FK → tg_raw_messages.id. Insert raw first, commit, then parsed.
Signal pipeline liveness — ingestion ≠ parsing
A green systemd unit and a growing tg_raw_messages table prove the Telethon
client works. They do NOT prove any signal is being extracted. Before opening any
"why is no trade happening" investigation, check the parse outcome distribution
rather than the process state:
SELECT ingestion_status, count(*) FROM tg_raw_messages GROUP BY 1;
SELECT date_trunc('day', created_at) AS d, count(*) FROM tg_parsed_signals GROUP BY 1 ORDER BY 1 DESC;
A healthy ingester can sit at thousands of rows while the entire signal path downstream is dead — this system ran for days with raw messages arriving every ~10 minutes and zero parsed signals.
The upstream channel changes its message format and the parser silently stops
matching. When PARSE_ERROR dominates, do NOT assume the parser is broken and
start rewriting regexes. First classify the raw corpus by shape and by day
(recipe: references/signal-parser-maintenance.md) and answer the prior
question: does the feed currently contain anything parseable at all? The feed
had degraded to re-posted disclaimer boilerplate every ~10 min plus a
funding-outlier digest — neither is a tradable signal — and the last real scout
list was 8 days old. The correct output there is "no valid signal exists, clock
NOT started", not a rewritten parser and not a stale-signal trade.
State the consequence plainly when the feed is empty:
- Signal max age is 300 s; anything older is
stale_signalby design. - Standing rule: never trade historical signals as if live.
- Therefore the 7-day clock cannot start until a fresh parseable signal arrives.
Risk limits
| Limit | Value |
|---|---|
| Max position | 2% portfolio |
| Max exposure | 15% |
| Max concurrent | 3 |
| Leverage | 3x |
| Stop loss | 2% |
| Take profit | 4% |
| Signal age | 5 min |
Safety Constraints
- LIVE_TRADING=false is a HARD DEFAULT. Never enable without explicit written approval.
- Never claim profitability from a 7-day sample. Demo results are not statistically significant.
- Never promise or imply guaranteed wins / guaranteed returns, on this system or any trading system. If asked to "guarantee constant wins" or similar, say plainly that no system guarantees returns on real markets (if one did, arbitrage would erase the edge) and redirect to the real target: positive expected value with survivable risk of ruin, validated only after enough trades exist to measure win rate / EV per trade / max drawdown. This is a correctness rule, not a hedge — do not soften it into a caveat and then answer the guarantee question anyway.
- Never auto-scale position sizes. Fixed conservative limits only.
- Never trade historical signals as if live. Only process signals received after experiment start.
- Demo credentials stay in server
.envonly. Never commit or log secrets. - Training completion is not model approval, AND training must persist.
A model is usable only when explicit validation gates pass; otherwise record it
observation_onlyand let the strategy engine fall back tockp_baseline. Gates that must ALL hold on the validation split: directional accuracy > 0.52, Spearman IC > 0.02, R² ≥ 0, and MAE no worse than the no-model (train-mean) baseline. Persist the approved/observation-only decision AND the failing gate values intomodels/ml_metadata.json— "trained" alone is not a record.
Critical: the train() method must call save() before returning. A
train() that fits the model in memory but never writes ml_predictor.pkl +
ml_metadata.json to MODEL_DIR loses the trained artefact on every cycle —
the next load() finds nothing. After patching train(), verify with:
ls -la /opt/cortexquant/models/ml_predictor.pkl after a training run. A
trained-but-never-saved model is indistinguishable from an untrained one at
load time; this is the bug that made the pipeline's ML always
observation-only even after the worker trained successfully.
- Chronological splits only, pooled by timestamp — never per-symbol, never
shuffled. Splitting each symbol independently lets one symbol's later bars land
in another symbol's training window. The label is the forward return
(
close.pct_change().shift(-1)), so the final bar per symbol must be dropped after shifting. - Train on the exchange you actually execute on. The legacy trainer pulled
OHLCV from Binance while demo execution runs on BingX; symbol sets and available
history differ, so the metrics described instruments that were never traded.
BingX sandbox
fetch_ohlcv(..., since=<45d ago>)returns about 1000 bars regardless of how far back you ask, so record the ACTUAL period covered rather than the requested lookback.
Pitfalls
- main.py blocking: demo must be create_task, not await.
- BingX VST balance, not USDT.
- Swap symbols need
:USDTsuffix. - FK constraints: raw before parsed.
- Separate-process tests see callback=None — test via server API.
re.match()anchors at position 0 — real channel lines are indented, so a pattern without a leading\s*matches none of them. Test every parser regex against the ACTUAL corpus (SELECT raw_text FROM tg_raw_messages), never against an idealized example typed from memory; the scout lines arrive as" 1. ALCH-USDT | ..."with a leading space.- When a parser has two alternate line patterns, do not assume identical group
numbering.
match.group(3)on a 2-group fallback pattern raisesIndexError: no such group. Normalize both patterns into the same(symbol, data)tuple in one place instead of indexing groups inline. - A crash guarded by a condition that never currently holds is still a live
bug.
tg_service._process_messageiteratesfor p in parsed:while the variable isparsed_results— aNameErrorthat never fires only becauseparse()currently returnsNonefor every message. The moment a real signal arrives it raises, rolls back the transaction, and loses BOTH the raw and the parsed row. When auditing an ingestion path, trace the branch that runs when the happy path finally succeeds, not just the branch executing today. - Noise markers beat clever regexes for messages that must never trade. A
disclaimer/disclaimer-repost or a funding-outlier digest mentions LONG/SHORT
and carries
SYMBOL-USDT | RSI15=...lines, so a naive symbol matcher happily emits fake signals from it. Reject on substring markers ("About these scanner lists","Funding Outliers","not guaranteed trade calls") before line parsing, and assert those rejections in the parser's self-check. - Scope discipline: When asked to fix startup, locate the real running server's main.py first. Do not keep building new modules — inspect the deployed code, find the entrypoint, fix the actual blocking call.
- No systemd unit means the server is exactly one dropped SSH session from
being dead with no error. Launching
main.pyby hand (even withsetsid/nohup) survives only as long as something keeps the process supervised. When an audit or a "why isn't it running" check finds the log stopped mid-line with no crash/OOM entry, that absence of a unit IS the root cause — write/etc/systemd/system/cortexquant.servicewithExecStart=/opt/cortexquant/start.shandRestart=on-failure, don't just relaunch by hand again. Two config classes can both define risk limits — grep the import in the file that places orders, not the firstSettings-looking file.src/utils/config.pycarries a genericSettingsclass andsrc/exchange/demo_trading_service.pycarries its ownBingXDemoConfig. If both are live in the same process (not dead code), confirm which one each consumer actually imports viagrep 'from.*import.*config\|demo_trader.config'in every file that touches risk/exposure/concurrency logic — including the risk engine, the pipeline, and any worker that calls risk methods. When two live config classes disagree, fix by making the risk engine accept an optionalconfigparameter (defaulting to the generic one, overridable by the demo config) rather than deleting one class. That keeps both consumers wired through a single authoritative check while preserving each consumer's own limits. Seereferences/risk-config-consolidation.mdfor the exact pattern. Dead-code config classes (imported nowhere) should be removed, not patched. - A defined settings key is not the same as an enforced control — grep every
reference before crediting a security setting as active.
API_SECRET_KEYinSettingshad zero consumers until an@app.middleware("http")bearer-auth check was added inapi.pygating every POST/PUT/PATCH/DELETE (GETs stay open for dashboards). ReturnJSONResponse(status_code=401, ...)from that middleware, neverraise HTTPException— middleware exceptions bypass FastAPI's handlers and become a 500 instead (seepython-fastapi-hardening). Verify all three cases with curl: no token → 401, wrong token → 401, real token from.env→ 200.CORSMiddleware(allow_origins=["*"])still means any LAN host can send the request; the bearer check is what actually gates it. - The demo kill switch (
demo_trader.kill_switch, flipped viaPOST /api/demo/kill-switch) has no deactivate endpoint — unlike the separate generic/api/kill-switch/{activate,deactivate}pair inrisk.py/api.py. Once tripped it only resets by restarting the service (systemctl restart cortexquant), which re-runsstart_demo_experiment()and starts a new experiment run. Never POST that endpoint during testing without immediately restarting the service afterward, or the demo trader stays halted with no code-level way to resume it. - A room method existing with the right name is not the same as it computing
anything real — grep for its actual callers and body before crediting a
feature as implemented.
BacktestRoom.run_backtest()inrooms.pyreturns a hardcoded all-zero dict (sharpe/win_rate/etc all 0) and never calls the realsrc/backtest/backtester.py::Backtesterclass that already does point-in-time simulation with fees/slippage/Sharpe/drawdown. Before proposing to "add backtesting" or "wire up X", check whether the real engine already exists and is just unwired — that's a smaller diff than writing a new one, and the correct fix is calling the existing class, not building another. - Red Team and Risk Committee are already hard promotion gates —
ChiefQuantDirector.promote_research()calls_check_veto()before allowing a transition toPRODUCTION_CANDIDATE/LIVE_ELIGIBLE, and either room'sVETOmessage flips the experiment toREJECTEDand blocks promotion. If asked to "make Red Team/Risk Committee a hard gate", verify this isn't already true before writing new veto-enforcement code. ResearchTaskrows get created by every room (create_task,delegate_to_room) but nothing ever consumes the PENDING queue. There is no worker loop that picks up pending tasks, runs them, and marks them RUNNING/COMPLETED/FAILED outside of tests —ChiefQuantDirector.prioritize_queue()only reads the queue, nothing drains it. Any "make the rooms actually run autonomously" ask needs a task-consumer loop as the actual missing piece, not more room/agent scaffolding (which already exists for all 12 rooms/24 agents).- Supervision house style is
asyncio.create_taskloops inside the FastAPI process, not Celery —celery==5.4.0sits inrequirements.txtunused. Adding Celery for background workers means a broker + beat + separate worker process to supervise themselves — more moving parts than one moreasyncio.create_taskloop next to the existingdemo_lifecycle.py/_monitor_experiment()pattern. Stay with asyncio tasks + a persisted heartbeat/status table unless throughput genuinely outgrows a single process. - For a large multi-phase build request (new worker architecture, incentive system, dashboard overhaul, etc.), audit the real filesystem for what already exists before scoping phases. Pull the actual source tree first (rooms, schema, events, dashboard, backtester) via SSH/tar rather than assuming from memory notes, then present the phased plan against what's real vs. stubbed — this cuts scope by however much already exists and avoids rebuilding working code.
Demo activation flow
The demo experiment starts via the API with the Bearer token from .env:
TOKEN=$(grep '^API_SECRET_KEY=' /opt/cortexquant/.env | cut -d= -f2)
curl -s -X POST -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/demo/start
This calls demo_trader.initialize(api_key, secret) → loads BingX VST markets → creates an ExperimentRun row → sets demo_trader.is_active = True and demo_trader.experiment_end to 7 days out. The start call must happen AFTER the server is running (main.py calls start_demo_experiment() as a background task, but if DEMO_TRADING was off at boot, a manual restart via the API is needed).
After start, verify markets loaded and balance:
curl -s http://localhost:8080/api/demo/status | python3 -m json.tool
# Expect: "is_active": true, "experiment_end" set, "days_remaining": 6-7
Reconciliation Overflow Pitfall
The startup reconciliation script (reconcile_demo.py) creates DemoTrade DB
rows for every open exchange position. If reconciliation runs when more than
MAX_CONCURRENT_TRADES positions are open on the exchange (e.g., 5 positions
vs 3 limit), the demo trader immediately hits Max concurrent trades reached
and rejects every fresh signal — even though some pre-existing positions are
desirable (BTC, AVAX) and others are noise (BAS, ARC, EGLD).
Fix: reconciliation must count existing positions against
MAX_CONCURRENT_TRADES and only mark the oldest N as open; close (or skip) the
rest via the BingX API before starting the experiment clock. Reconciliation
must also update demo_trader.daily_pnl from exchange positions so the
daily-loss guard has real data — a daily_pnl that stays 0 means the guard
never fires regardless of actual P&L.
Reconciliation script: /opt/cortexquant/reconcile_demo.py can be run
standalone via pct exec 106 -- python3 /opt/cortexquant/reconcile_demo.py
(wraps reconcile_with_exchange()). Useful for manual reconciliation outside
the service lifecycle.
ML Training Reality (2026-09)
GradientBoostingRegressor on 365-day 1h OHLCV for BTC/ETH/SOL/AVAX yields
R² ≈ -0.04 — no predictive power. The model is saved but fails validation gates.
Use ML_SKIP_VALIDATION=true (systemd drop-in) to bypass the gate for demo
purposes, or improve features/model before relying on ML signals.
ML persistence must survive restart. After a training run, verify the model
file exists: pct exec 106 -- ls -la /opt/cortexquant/models/ml_predictor.pkl.
If the file is absent after a training cycle, the train() method is not
calling save() — the trained model is lost and the pipeline loads nothing.
Fix: add a save() call at the end of train() (both the mean-fallback and
ensemble/gbm success paths).
Systemd drop-in for ML bypass:
ssh root@192.168.1.11 'pct exec 106 -- bash -c "
mkdir -p /etc/systemd/system/cortexquant.service.d
echo -e \"[Service]\\nEnvironment=ML_SKIP_VALIDATION=true\" > /etc/systemd/system/cortexquant.service.d/ml-skip.conf
systemctl daemon-reload
systemctl restart cortexquant
"'
Existing positions (2026-09-20)
| Symbol | Direction | Entry | Size | Source |
|---|---|---|---|---|
| BTC | LONG | $77,142.90 | 0.001 | Reconciliation |
| AVAX | LONG | $7.39 | 811.91 | CKPscanner |
Two more (ARC, BAS, EGLD) exist as reconciliation artifacts and push total to 5 — above MAX_CONCURRENT_TRADES=3. Must close at least 2 to accept new signals.
Reconciliation on Startup
demo_trader.positions is in-memory only — service restart loses all tracked positions while BingX retains the real ones. Add reconciliation to start_demo() BEFORE the background task starts:
positions = await demo_trader.adapter.get_positions()
for pos in positions:
symbol = pos['symbol'].replace('/USDT', '').replace(':USDT', '')
if symbol not in demo_trader.positions:
demo_trader.positions[symbol] = {
'exchange_order_id': pos['id'],
'direction': pos['side'],
'entry_price': pos['entryPrice'],
'size': pos['contracts'],
}
Without this, the first pipeline run after a restart sees 0 internal positions and may try to re-open existing BTC/AVAX positions.
BingX transient: timestamp is invalid (code 109400)
The demo trading log repeatedly logs BingX positions error: bingx {"code":109400,"msg":"timestamp is invalid"}. This is transient — the CCXT adapter sometimes gets a clock-skewed timestamp on the first call after restart. It does NOT mean the integration is broken. Confirm via a direct CCXT test:
python3 -c "
import ccxt, time
ex = ccxt.bingx({'apiKey': '...', 'secret': '...', 'enableRateLimit': True, 'options': {'defaultType': 'swap'}})
ex.set_sandbox_mode(True)
print('Markets:', len(ex.load_markets()))
print('Positions:', len(ex.fetch_positions()))
"
If markets load and positions return, the connection is healthy. The errors stop on retry. Do NOT treat a few timestamp is invalid log lines as a config bug.
Supervisor guard: LIVE_TRADING_GUARD
src/workers/supervisor.py has a hard guard at module level:
LIVE_TRADING_GUARD = True
This means WorkerSupervisor.start_all() refuses to start any workers if LIVE_TRADING=true, regardless of DEMO_TRADING. If the user says "start live trading" and you flip LIVE_TRADING=true in .env, the supervisor will dead-stop. The demo path uses DEMO_TRADING=true and leaves LIVE_TRADING=false. To actually enable real BingX trading, the supervisor guard logic must be explicitly changed (not just .env), and this requires explicit per-session approval.
VST demo balance starts at ~100,000
The BingX VST sandbox account starts with ~100,000 VST (not 0). The fetch_balance() returns {'VST': {'free': 99693.0, 'used': 302.9, 'total': 99996.0}}. Demo trades execute immediately once the pipeline is wired.
Full Signal-to-Execution Pipeline
The pipeline wires: Telegram parsing → market snapshot → ML prediction → strategy selection → classical optimization → quantum optimization → risk check → BingX execution → decision record → post-trade analytics.
Two execution paths must converge. Historically this system had two parallel
paths to demo execution: (a) the orchestrator's 12-step alpha validation +
shared FullPipeline, and (b) the Telegram publisher's direct FullPipeline
call per signal. When both are active, a signal's validation depends on which
path receives it — inconsistent and untestable. The correct wiring: the
publisher's _safe_demo_call must route through the orchestrator's
process_signal, not create a fresh FullPipeline. The orchestrator owns the
shared pipeline instance; the publisher is a delivery mechanism only.
Architecture
tg_publisher → orchestrator.process_signal(signal_dict)
├─ 12-step alpha validation (AlphaExtractionPipeline)
├─ shared FullPipeline (single instance, not fresh per call)
│ ├─ idempotency check (DecisionRecord.by signal_id)
│ ├─ market snapshot (OHLCV from BingX via demo_trader.adapter.exchange)
│ ├─ ML prediction (MLPredictor — observation-only until trained+saved)
│ ├─ strategy selection (StrategyEngine with deterministic fallback)
│ ├─ classical optimization (RiskfolioAdapter)
│ ├─ quantum optimization (QuantumSolver)
│ ├─ risk check (RiskEngine — accepts optional config param)
│ ├─ duplicate position check
│ └─ BingX VST execution (demo_trader.process_signal)
├─ DecisionRecord persisted to database
└─ demo_trader.reconcile_positions() updates daily_pnl from fills
/api/demo/test-signal → orchestrator.process_signal(signal_dict) # same path
DecisionRecord Schema
The decision_records table captures every signal's complete journey:
signal_id(unique, idempotency key)signal_parsed,market_snapshot,ml_prediction,ml_confidencestrategy_selected,strategy_paramsclassical_optimizer_output,quantum_optimizer_outputrisk_decision(approved/rejected),risk_reasonorder_params,exchange_order_id,fill_price,fill_quantityfees,funding,slippageexit_price,exit_reason,gross_pnl,net_pnlstatus(pending, executed, closed, rejected, error)error_classification,market_regime
Idempotency Pattern
Always check for existing DecisionRecord before processing. A signal that was rejected yesterday must not be re-processed on restart.
API Routes
GET /api/pipeline/decisions— list recent decisionsGET /api/pipeline/decisions/{signal_id}— full decision chainGET /api/pipeline/stats— execution statistics
User Workflow Preferences (Always-On)
These are standing rules the user explicitly stated. They apply to every session.
- Do not increase risk limits to force a trade. If
PER_TRADE_RISK_PCT=1.0%and the pipeline submits 2.0%, the rejection is correct behavior. Record the mismatch, add a regression test, and stop. - Treat rejections as integration tests. A
"rejected"status is a successful pipeline execution, not a bug. - The demo path sizes on notional, not on risk-at-stop — do not report
MAX_POSITION_SIZE_PCTas the per-trade risk.demo_trading_service.process_signalcomputessize = balance * MAX_POSITION_SIZE_PCT/100 / price, then multiplies byLEVERAGE_MAX. So notional isbalance × 2% × 3 = 6%of the account, and with a 2% stop the actual loss at the stop is about6% × 2% = 0.12%of the account — nowhere near the configured percentage.RiskEngine.calculate_position_size()DOES implement true risk-at-stop sizing (risk_amount / risk_per_unit, whererisk_per_unit = entry − stop_loss), but the demo execution path never calls it. When asked to "verify risk is X% per trade measured as loss at the stop-loss", compute the loss from the sizing expression actually used and state the real number; do not echo the config constant back as the answer. - Fix blockers in this order: (1) make risk authoritative, (2) replace hardcoded Binance with BingX market resolver, (3) implement
StrategyEngine.select_strategy(), (4) put ML in observation-only mode, (5) add synthetic e2e test mode, (6) process one real signal only when fully validated. - Label momentum_ma as a fallback, not an AI decision. When ML is untrained or confidence < 0.6, the strategy MUST be labeled
"fallback". - Never treat default 0.5 confidence as a validated prediction. Untrained ML models MUST return
{"confidence": 0.5, "observation_only": True}. - Synthetic e2e test mode is mandatory before any real trade. Implement a
test_e2e()method that runs the full pipeline WITHOUT placing orders. - Never allow an LLM to directly rewrite production trading code, bypass risk controls, or promote itself.
- Process a real signal ONLY when ALL gates pass: exact market exists on BingX, ML model is trained (or ckp_baseline is explicitly used), risk approves, no duplicate position/order would be created, and the signal is fresh.
- Report exact details, not summaries. For every pipeline test or trade, report: signal_id, symbol, direction, prediction, strategy name + reason, classical/quantum optimizer outputs, risk decision + reason, order params, exchange response, fill details, fees, and final P&L.
- Do not optimize further until one complete real signal has traversed the entire pipeline.
Verify
When the signal path looks dead (PARSE_ERROR dominant, no recent
tg_parsed_signals), work through
references/signal-parser-maintenance.md before touching any regex — it separates
"parser broke" from "feed carries nothing", which need opposite responses.
curl http://localhost:8080/api/demo/status | python3 -m json.tool
curl -s -X POST http://localhost:8080/api/demo/test-signal | python3 -m json.tool
tail -50 /tmp/cq.log | grep -a demo\|BingX\|callback\|order