# TW Exchange Arbitrage Scanner (paper)

MAX / BitoPro 台幣交易對的**純套利掃描器**（不下單、不連錢包，只記錄可執行價差）。

## 它算什麼

1. **單所三角（MAX）**：對每個同時有 `XXX/TWD` 與 `XXX/USDT` 的幣，計算
   - `TWD → USDT → XXX → TWD`
   - `TWD → XXX → USDT → TWD`
   用**真實訂單簿深度**逐檔吃單算 VWAP，扣三腿手續費。
2. **跨所同交易對（MAX vs BitoPro）**：BTC/TWD、ETH/TWD、USDT/TWD 的雙邊價差。
3. 每一輪輸出到 `logs/scan.csv`，欄位見下。

## 重要限制（必讀）

- **MAX**：使用公開 `depth` 真實盤口。
- **BitoPro**：公開 orderbook / WebSocket 對外不可直接存取（REST 回 404 或
  `Invalid request header`，WS 回 404）。因此跨所列用 BitoPro **tickers 最新成交價**，
  標記 `note=approx_bito_last`，**只能當粗篩候選**，不是可執行價。
  要升級成雙邊真實深度，需要 BitoPro API key 或可用的盤口端點。
- 薄盤保護：任一腿 `spread > 2%` 或盤口交叉 → 該幣跳過（列在 `illiquid`）。
  這是必要的，否則會看到 NEAR/DOGE 那種 -70% 的假 edge。
- 三角列只有在 `complete=1`（深度足夠吃滿 clip）且 `|gross| <= 5%` 時才 `ok=1`。

## 用法

### 一次性掃描（`scan.py`）

```bash
cd brain/research/2026-11-14_tw_exchange_arb_scan
python3 scan.py --cycles 3 --interval 4 --assets BTC,ETH,XRP,SOL,DOGE,NEAR
```

### 24/7 常駐（`service.py` + `run.sh`）

```bash
./run.sh start --interval 10 --assets BTC,ETH,XRP,SOL,DOGE,NEAR,LINK
./run.sh status     # pid + state/health.json
./run.sh stop
./run.sh fg         # 前景除錯（同 service.py 參數）
```

常駐產出：

| 路徑 | 內容 |
|---|---|
| `logs/scan-YYYYMMDD.csv` | 每日輪替的逐輪記錄 |
| `logs/episodes.csv` | 淨利 >0 的連續事件（start/end、max、duration、samples） |
| `reports/summary-YYYYMMDD.json` | 每日彙總（每 5 分鐘 + 結束時更新） |
| `reports/summary-YYYYMMDD.md` | 同上，人看得懂的版本 |
| `state/health.json` | 心跳（cycle、uptime、errors、active episodes） |
| `logs/service.out` | stdout / error |

服務特性：每日 CSV 輪替、例外指數退避（最多 60s）、SIGTERM 優雅收尾（關閉事件、寫最終 summary）、原子寫入 health。

常用參數：

| 參數 | 預設 | 說明 |
|---|---|---|
| `--assets` | BTC,ETH,XRP,SOL | 要掃的幣（大寫逗號分隔） |
| `--clip` | 50000 | 每筆起始 TWD 名義金額 |
| `--max-fee` / `--bito-fee` | 0.0015 | 每腿 taker 費率（小數） |
| `--buffer` | 0.0005 | 安全緩衝（小數） |
| `--max-leg-spread` | 0.02 | 單腿最大可接受價差 |
| `--interval` | 10 | 掃描間隔秒數 |
| `--cycles` / `--max-cycles` | 0 | 輪數上限（0=無限；`scan.py` 用 `--cycles`） |
| `--near-threshold` | 0.05 | 距離獲利 5bp 內視為 near-miss（%） |
| `--summary-interval` | 300 | 常駐版 summary 更新間隔（秒） |
| `--depth-limit` | 20 | 每本盤口抓幾檔 |
| `--out` | logs/scan.csv | `scan.py` 輸出檔 |

## CSV 欄位

`ts` 時間戳、`kind`（triangle/cross）、`venue`、`asset`、`direction`、
`clip_twd`、`gross_pct`（未扣費價差 %）、`fee_pct`、`net_pct`（扣費+緩衝後）、
`complete`（三角深度是否吃滿）、`ok`（可列入排名）、`note`。

判斷只看 `ok=1` 且 `net_pct > 0` 的列。

## 升級路徑

- [x] 24/7 常駐：每日 CSV 輪替、事件偵測、summary、health heartbeat
- [ ] 接上 BitoPro 真實盤口（API key / 可用端點）→ 跨所列變可執行價
- [ ] MAX/BitoPro WebSocket（目前兩邊公開 WS 皆不可用，暫以輪詢取代）
- [ ] paper 執行模擬（FOK 三腿）+ 滑價回填
- [ ] 跑滿 1–2 週後，用 `reports/summary-*.md` 的 episode / near-miss 決定是否值得投入
