1. 單一 config + Account
共用 一個策略檔 v-mm/mm-hub/algo/spot-future-arb/config.json:根層放共用參數(execute、demo、quote_coin、threshold、WS 間隔等),instances[] 每列一個 symbol(id、spot_symbol、future_symbol、order_qty、state_path 等)。API key 仍放 algo/bybit-account.json。
- mm-hub Start 會對每個
instances[].id 起一個 subprocess:spot-future-arb --config config.json --instance <id>。
- 無
instances[] 時退回單一策略(舊式根層直接寫 symbol),唔使 --instance。
- 若 API 未配置,只可 dry-run/demo。
- 重啟後讀各自
state_path snapshot;若 snapshot / 交易所不一致,應先停機 reconcile。
2. Formula
spot_mid = (spot_bid + spot_ask) / 2
future_mid = (future_bid + future_ask) / 2
basis_bps = (future_mid / spot_mid - 1) × 10000
+10 bps = future 比 spot 貴 0.1%。
-10 bps = future 比 spot 平 0.1%。
entry_threshold_bps 越細,交易機會越多,但更容易被 spread / fee / slippage 吃掉。
3. Entry Chasing
Entry 單只放 spot leg,並追 top-of-book。追價節奏由 chase_interval_ms 控制;價格偏離超過 chase_max_slip_bps 時 cancel + replace,否則 amend。
- 正 basis:spot buy at best bid。
- 負 basis:spot sell at best ask。
- spot sell 之前會檢查 base coin wallet balance,避免 insufficient balance 後連續重試。
4. Race Exit After Spot Fill
Spot entry 成交後立即開兩張互斥 exit order,讓策略在 hedge 與回吐 spot 之間 race。
- long spot 後:future sell at best ask;spot sell at
max(best ask, entry)。
- short/sell spot 後:future buy at best bid;spot buy at
min(best bid, entry)。
- 其中一張成交,即 cancel 另一張;兩張同時成交時會 market close over-hedged future。
5. State Machine
flat → entry_working → race_exit → carry_hedged / flat。任何 critical submit / unwind 失敗會進入 halted。
halted 不是 crash;它代表策略故意不再下新單,保留 stdout/metric 讓 operator 檢查。
Stop 是 pause subprocess,不會自動 market unwind;algo state 會保存到 snapshot,下一次 Start 先恢復。
- 只有確認 exchange flat、open orders = 0、algo snapshot 無 exposure 時,才應人工清理 state。
6. Over-Hedge & Emergency
如果 future exit 與 spot exit 幾乎同時成交,視為 over-hedge;策略會即時 market close future。Carry 狀態下若 fut - spot 穿 emergency threshold,就 market unwind spot/future。
emergency_unwind_bps <= 0 代表停用 emergency threshold。
- market unwind 任一 leg 失敗時,策略會
halted,避免假裝回到 flat。
7. Operator Runbook
- 更新
algo/bybit-account.json:API key、權限、IP allowlist。
- 只改
algo/spot-future-arb/config.json:根層共用參數 + instances[] 增減幣種;每列獨立 state_path 避免 snapshot 互踩。
- 部署:重新
cmake build spot-future-arb、重啟 mm-hub;瀏覽 /arb 睇表格「跑緊/LIVE/掛單/單/填」。
- 某行
halted:讀該行 error 同 stdout,唔好盲目全 fleet 重啟。
- Stop 只停 subprocess、唔自動 market unwind;要平倉用策略流程或人工確認。