掃描全台股（上市 + 上櫃），計算每一檔個股在回溯區間內：
| 指標 | 定義 |
|---|---|
| 融資回撤% | (區間融資餘額高點 − 目前融資餘額) / 區間融資餘額高點 × 100 |
| 股價回撤% | (區間股價高點 − 目前收盤價) / 區間股價高點 × 100 |
| 差值% | 融資回撤% − 股價回撤% |
可以用上述任何一欄排序。
差值的解讀
- 差值為正：融資退場的幅度大於股價下跌的幅度 → 浮額清洗、籌碼沉澱。股價撐住但融資大量退場，通常視為籌碼轉優。
- 差值為負：股價跌幅大於融資減少的幅度 → 融資戶尚未認賠，套牢賣壓仍積壓在上方。
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt若使用 uv：
uv pip install -r requirements.txt# 預設：回溯一年，依「差值」由大到小排序，顯示前 30 名
python main.py
# 依融資回撤排序，找融資從高點大量退場的個股
python main.py --sort margin --top 50
# 依股價回撤排序，找跌最深的個股
python main.py --sort price --top 50
# 匯出 Excel / CSV
python main.py --format xlsx
python main.py --format csv --out out/scan.csv
# 只看特定個股
python main.py --codes 2330 2454 3045
# 自選股群組（詳見下方「自選股群組」）
python main.py --group group1
# 每日增量更新（快取已建立後，只重抓最近 5 天）
python main.py --refresh-days 5
# 完全離線，只用本機快取
python main.py --no-fetch完整參數請執行 python main.py --help。
| 參數 | 說明 | 預設 |
|---|---|---|
--lookback-days N |
往前回溯的日曆天數 | 365 |
--start / --end |
直接指定區間（YYYY-MM-DD） |
— |
--sort |
margin / price / spread / code / margin_balance |
spread |
--asc |
改為由小到大排序 | 由大到小 |
--top N |
顯示前 N 筆（0 表示全部） |
30 |
--market |
all / twse（上市）/ tpex（上櫃） |
all |
--min-margin |
融資高點需達到的張數，濾掉小額雜訊 | 100 |
--min-price |
最新收盤價下限 | 0 |
--include-etf |
納入 ETF / ETN | 只掃一般個股 |
--max-stale-days |
剔除最後資料距今超過 N 天者（已下市／停牌） | 10 |
--no-dividend-adjust |
不還原除權息造成的價格跳空 | 預設會還原 |
--no-split-adjust |
不還原股票分割造成的價格斷點 | 預設會還原 |
--format |
table / csv / xlsx |
table |
把常追蹤的股票存成群組，之後用群組名稱掃描：
# 建立／新增（群組不存在會自動建立，重複的代號會自動略過）
python main.py --group-add group1 2330 2454 2317
python main.py --group-add 金融股 2892 2880 2884
# 用群組掃描
python main.py --group group1
# 多個群組取聯集
python main.py --group group1 金融股
# 群組也能搭配排序與匯出
python main.py --group group1 --sort margin
python main.py --group group1 --format xlsx
# 管理
python main.py --group-list # 列出所有群組
python main.py --group-remove group1 2317
python main.py --group-delete group1群組存在專案根目錄的 groups.json，格式扁平、可直接手動編輯：
{
"group1": ["2330", "2454", "2317"],
"金融股": ["2892", "2880", "2884"]
}行為說明
--group與--codes一樣會略過--min-margin、--include-etf、--max-stale-days等篩選條件，也不受--top截斷 —— 你指定的股票一定 全部列出。- 若群組內有代號查無資料（打錯字、已下市），會單獨列出提醒。
- 若群組內有個股資料已停更（例如已下市），會警告其「現值」並非最新。
官方公告的收盤價未還原權息，除息當天股價會向下跳空一段股利金額。只要 這個跳空落在股價高點之後，就會被算進股價回撤，讓跌幅看起來比實際大。
程式預設會還原權息，以官方公布的
除權息參考價 ÷ 除權息前收盤價 為倍數，把除權息之前的股價調整到同一基準；
配股的部分另以 (前收盤價 − 息值) ÷ 參考價 同步放大先前的融資張數（配股
使股數變多，張數會跟著變多）。--no-dividend-adjust 可關閉。
實測（2025-08-04 ~ 2026-08-04）：
| 代號 | 名稱 | 除息日 | 未還原股價回撤 | 已還原（實質跌幅） |
|---|---|---|---|---|
| 9942 | 茂順 | 2026-07-30 | 9.2% | 3.5% |
| 9926 | 新海 | 2026-07-21 | 13.3% | 9.5% |
| 9905 | 大華 | 2026-07-09 | 5.5% | 0.7% |
| 1737 | 臺鹽 | 2025-08-20 | 4.2% | 0.9% |
融資餘額則不受除權息影響 —— 這點常被誤解，本專案實測如下。
融資沒有「除權息強制回補」規定：強制回補只適用於融券（停止過戶前 六個營業日起停止融券賣出並了結）。融資買進者反而是參與股利分派的一方。 且自 2015-03-16 起，連「停止過戶前停止融資買進 3 日」的限制也已取消。
以本專案一年份資料對 1,394 筆除權息事件做事件研究，比較除權息日當天 與 25 個交易日前的融資餘額：
| 分位 | 融資餘額變化 |
|---|---|
| P10 | −28.9% |
| P25 | −14.2% |
| P50（中位數） | −1.6% |
| P75 | +11.0% |
| P90 | +45.0% |
| 平均 | +11.4% |
中位數僅 −1.6%，平均甚至是正的。進一步看融資高峰出現的時點，中位數 落在除權息前一日（T−1），T−5~T−1 明顯集中 —— 這是搶息買盤 （除息前用融資卡位領股利），與「提前了結」方向相反。
所以：若掃描結果出現融資回撤 80%、90% 的個股，成因不是除權息，而是限制 6 （高點採單日最高值） —— 短暫暴衝墊高了高點。例如 2880 華南金全年基期約 500 張，2026 年 5 月單月衝到 4,673 張後打回原形，回撤其實是在測量「從尖峰 回到常態」。另一種則是真實的融資多空循環（如 2892 第一金：1,000 →19,387 →1,910），那本來就是這個工具該抓出來的訊號。
被合併下市或長期停牌的個股，最後的融資餘額會永遠停在殘值，回撤被算成接近 100%，直接霸佔排行榜前段。實測中 4987 科誠（資料停在 2026-05-28）、 3454 晶睿（2026-03-26）、2809 京城銀（2025-09-30，已併購下市）都是這種情況。
程式預設剔除「最後一筆資料距最新交易日超過 10 天」的個股（--max-stale-days）。
台股有 ±10% 漲跌幅限制，任何單日超出此範圍的價格變動都不是市場行為， 而是股票分割、面額變更或減資造成的價格斷點。這種斷點會同時汙染兩個欄位： 股價腰斬十倍，融資張數也因股數變成十倍而暴增。
實測 8422 可寧衛在 2025-11-17 單日 −90.1%（面額變更）：
| 股價高點 | 收盤價 | 股價回撤 | |
|---|---|---|---|
| 未還原 | 250.00 | 26.25 | 89.5%（假訊號） |
| 已還原 | 51.90 | 26.25 | 49.4%（實際跌幅） |
程式預設以標準「向後調整」還原：偵測到單日比例落在 [0.80, 1.25] 之外時，
把該日之前的股價乘上該比例、融資張數除以該比例。一年區間內約有 50 檔個股
會觸發。匯出檔的「已還原分割」欄可看出哪些被調整過，--no-split-adjust
可關閉。
證交所的除權息結果表只公布「權值+息值」合計，同時配股又配息的個股 （約佔 4%）無法拆出息值，這些個股的融資張數會保守地當作股數不變。 純配息（約 90%）與純配股不受影響；櫃買中心有分開公布權值與息值，可精確計算。
官方個股層級的融資資料以張數計算，非金額。股價大幅波動時，張數與金額的 回撤幅度會有落差。
單日的融資異常暴衝（例如除息前的搶息套利）會墊高高點，使回撤看起來特別大。
--min-margin 可濾掉一部分雜訊，但仍建議對照匯出檔中的「融資高點日」欄位判讀。
全部使用官方公開 API，免申請金鑰：
| 來源 | 端點 | 內容 |
|---|---|---|
| 證交所 | rwd/zh/marginTrading/MI_MARGN |
上市個股融資餘額 |
| 證交所 | rwd/zh/afterTrading/MI_INDEX |
上市個股收盤價 |
| 櫃買中心 | www/zh-tw/margin/balance |
上櫃個股融資餘額 |
| 櫃買中心 | www/zh-tw/afterTrading/otc |
上櫃個股收盤價 |
| 證交所 | rwd/zh/exRight/TWT49U |
上市除權息還原倍數 |
| 櫃買中心 | www/zh-tw/bulletin/exDailyQ |
上櫃除權息還原倍數 |
除權息只需要「已發生」的事件：尚未除息的個股股價還沒跳空，不必還原。 兩張表都含有除權息前收盤價與參考價，整段區間僅需 2 次請求。
這些 API 的單位是「某一天的全市場資料」，不是「某一檔的歷史資料」。 因此本工具是逐交易日抓取全市場快照（每天 4 次請求），再堆疊成面板資料。 掃描一年約 260 個交易日 ≈ 1,040 次請求，首次執行約 15–20 分鐘。
若改用「逐檔查詢」，1,800 檔 × N 天的請求量會直接被證交所擋掉。
每個「來源 × 日期」的快照存成一個 parquet 檔於 data/cache/：
- 第二次之後執行只會抓新增的交易日，通常幾秒內完成。
- 非交易日會存成 0 列的檔案，不會重複請求。
- 網路錯誤不會寫入快取，重跑指令即可自動補抓。
證交所對高頻請求會封鎖 IP，config.py 中的 HOST_MIN_INTERVAL
（證交所 2 秒、櫃買 1 秒）請勿隨意調小。
margin/
├── main.py # 進入點
├── requirements.txt
├── groups.json # 自選股群組（執行 --group-add 後產生）
└── margin_scan/
├── config.py # 端點、路徑、節流與預設值
├── http_client.py # per-host 節流 + 指數退避重試
├── fetchers.py # 四個端點的 JSON 解析
├── cache.py # 單日快照 parquet 快取
├── pipeline.py # 抓取排程（雙主機並行）與面板組裝
├── exrights.py # 除權息還原倍數
├── analysis.py # 權息／分割還原、回撤計算、篩選、排序
├── groups.py # 自選股群組（groups.json）
└── cli.py # 命令列介面與輸出
本工具僅供研究與資訊彙整用途，不構成任何投資建議。資料以證交所與櫃買中心 官方公告為準，使用前請自行驗證。