2026 台灣地方選舉 · Polymarket 下注監控
追蹤 Polymarket 上台灣各縣市首長選舉賭盤的即時賠率與每一筆成交明細，
包含下單錢包地址、顯示名稱、買賣方向、金額與時間。頂端頁簽切換縣市。
目前涵蓋 19 個縣市，全部 2026-11-28 到期：
| 縣市 | Event ID | 網址錨點 |
|---|
| 基隆市 | 848410 | #keelung |
| 臺北市 | 848341 | #taipei |
| 新北市 | 848347 | #new-taipei |
| 桃園市 | 848370 | #taoyuan |
| 高雄市 | 848409 | #kaohsiung |
| 新竹市 | 848435 | #hsinchu-city |
| 新竹縣 | 848418 | #hsinchu-county |
| 臺中市 | 848407 | #taichung |
| 臺南市 | 848408 | #tainan |
| 彰化縣 | 848438 | #changhua |
| 南投縣 | 848447 | #nantou |
| 雲林縣 | 848448 | #yunlin |
| 嘉義縣 | 848449 | #chiayi-county |
| 屏東縣 | 848479 | #pingtung |
| 花蓮縣 | 848480 | #hualien |
| 臺東縣 | 848481 | #taitung |
| 宜蘭縣 | 848417 | #yilan |
| 嘉義市 | 848453 | #chiayi-city |
| 苗栗縣 | 848436 | #miaoli |
兩個網址（內容完全相同）
兩者都接同一個 GitHub repo 自動部署，Actions 每次 commit 快照後兩邊都會更新。
網址帶錨點可直接開到指定縣市，例如
https://keelung-polymarket-tracker.vercel.app/#kaohsiung。
這個東西為什麼要這樣設計
Polymarket 封鎖台灣 IP。 這是整套架構的前提。
直接用瀏覽器打 polymarket.com 的 API，在台灣會連不上；掛 VPN 才通。
所以資料來源做成兩條腿，網頁會自己選能走的那條。
而且要用到的兩個 API 穩定度差很多，所以它們是分開判斷的：
| API | 用途 | 從瀏覽器直連 |
|---|
| Data API | 每一筆成交明細（核心資料） | 穩定 |
| Gamma API | 盤口賠率、成交量、流動性 | 時好時壞 |
Gamma API 的請求送得到伺服器，但 Cloudflare 有時回傳的內容不帶
access-control-allow-origin 標頭，瀏覽器就擋下來了。
（用 curl 測反而會成功，因為拿到的是快取版本——所以不要用 curl 判斷瀏覽器能不能連。）
因此實際行為有三種：
開啟網頁 → 同時試「成交明細」和「盤口賠率」（各自重試 3 次）
│
├─ 兩個都成功 ─────────→ 🟢 即時直連，無提示
│
├─ 成交成功、盤口失敗 ─→ 🟢 即時直連 ＋ 一行說明：
│ 「賠率是 X 時間的快照值，成交紀錄是當下最新」
│
└─ 成交也失敗 ─────────→ 🟡 快照資料，提示連 VPN
關鍵是成交明細抓得到就算即時——賠率抓不到只是換個來源，不該讓整頁降級。
中間那種混合狀態一定會在畫面上講清楚哪個是舊的、哪個是新的，
不會讓人誤把舊資料當成當下行情。
快照由 scripts/snapshot.py 產生。它可以在你自己電腦跑（要開 VPN），
也可以掛在 GitHub Actions 上跑——GitHub 的機器在美國，不受台灣封鎖影響，
等於免費幫你顧一台永遠連得到 Polymarket 的機器。
檔案結構
keelung_polymarket/
├── index.html 前端入口
├── app.js 全部前端邏輯（抓取、篩選、三種視圖、CSV）
├── style.css 樣式（深色為主，可切淺色）
├── data-<eventId>.json ← 各縣市最新快照，前端連不到 API 時讀這個
│
├── scripts/
│ ├── snapshot.py 抓取腳本（純標準庫，不用 pip install）
│ ├── should_commit.py 判斷這一輪值不值得留一個 commit
│ └── backfill_new_wallets.py 一次性：回填 new-wallets.json 的歷史資料
│
├── cron-worker/ Cloudflare Worker：每 5 分鐘觸發 Actions（見該資料夾 README）
│
├── seen_wallets.json ← 已知錢包名冊，新錢包偵測的依據
├── new-wallets.json ← 新進錢包完整明細，「新進錢包通知」頁籤讀這個
│
├── snapshots/
│ └── YYYY-MM-DD.json 每天一份賠率與統計存檔（不含逐筆明細）
│
└── .github/workflows/snapshot.yml GitHub Actions 排程（每小時）＋ 寄信
怎麼用
本機看
cd keelung_polymarket
python3 -m http.server 8765
然後開 http://localhost:8765/index.html。
不能直接用滑鼠雙擊 index.html 開啟。用 file:// 開的話瀏覽器會擋掉讀取
data.json 的請求，一定要透過上面的小伺服器。
手動更新快照（需要 VPN）
python3 scripts/snapshot.py
會同時更新 data.json 和 snapshots/當天日期.json。
上線給別人看
- 把這個資料夾推到 GitHub，Settings → Pages 選擇從 main 分支的根目錄發布
- Actions 會自動照
.github/workflows/snapshot.yml 每小時抓一次快照並 commit
- 沒有 VPN 的人打開網站會走快照模式，你自己開 VPN 打開就是即時模式
三種檢視模式
| 模式 | 用途 |
|---|
| 📋 表格 | 每筆成交一列，可依任一欄位排序、分頁，適合逐筆核對 |
| 📰 動態 | 卡片式時間軸，適合快速掃過最近有誰在下注 |
| 👛 錢包 | 依錢包彙總：累計筆數、買進/賣出金額、淨投入、押注標的、首次進場時間 |
錢包視圖會把開盤 24 小時內就進場的錢包標記出來——早期交易者可能有資訊優勢，
是值得優先看的對象。這個時間窗可以在 app.js 的 EARLY_WINDOW_H 調整。
所有錢包地址都可以點擊，三個入口：Polygonscan（鏈上紀錄）、
Polymarket（個人頁）、Relay（跨鏈轉帳，回溯 USDC.e 的來源鏈）。
滑鼠移到地址上會出現複製按鈕。表格視圖最右欄也有 Relay 連結。
新進錢包通知（頁籤）
頁籤列上跟各縣市同一層，有一個 🔔 新進錢包通知。它是所有縣市的彙整，
列出每個錢包第一次在某個縣市下注的那一筆交易——跟寄出去的通知信同一份資料，
差別只在信會過期、這一頁可以隨時回頭查。
資料來自 new-wallets.json，由 Actions 每輪產生，所以沒有 VPN 也看得到。
可以依縣市、日期、交易者名稱或錢包地址篩選，也能只看跨縣市錢包，並匯出 CSV。
頂端三個數字分別是：符合目前篩選條件的筆數、最近 24 小時的新進錢包、
以及其中跨縣市的錢包數。
同一個錢包在不同縣市各算一筆（它在每個縣市都有自己的「首航」），
所以列數會比錢包數多。
為什麼不是每輪重算
new-wallets.json 採合併寫入：只補新的，不動既有紀錄。
首筆交易明細是從 data-*.json 撈的，而那些檔有 MAX_OFFSET 上限。
等成交筆數成長到截斷，早期錢包的首筆交易會從 data-*.json 消失；
若每輪重建，這份名單會跟著愈縮愈短。合併寫入則是記過就不會掉。
歷史資料由 scripts/backfill_new_wallets.py 一次性補齊（2026-09-21 執行，回填 1,447 筆），
之後日常維護交給 snapshot.py，不需要再跑。
新錢包進場的郵件通知
每次抓完資料後，比對 seen_wallets.json 名冊，出現從未見過的錢包就寄信。
十個縣市合併成一封信，依縣市分段，不會一次收到八封。
信裡列出每個新錢包的首筆動作（押哪位候選人、買賣、Yes/No、股數、成交價、金額），
以及 Polygonscan、Polymarket、Relay 三個直達連結。
主旨會標註筆數與涉及幾個縣市，有跨縣市錢包時加註「N 個跨縣市」，
否則標註金額逾 $50 的筆數，讓人從手機通知欄就能判斷輕重。
跨縣市標記
同一個錢包在多個縣市都下注時，信裡會用黃色標籤標出「也出現在 ○○、○○」。
這是單一縣市看不出來的模式，也是最值得優先檢視的訊號。
目前約 380 個錢包裡有 136 個跨縣市，其中有錢包同時押了 9 個縣市。
需要的 GitHub Secret
| 名稱 | 內容 | 必填 |
|---|
MAIL_USERNAME | 寄件的 Gmail 地址 | 是 |
MAIL_PASSWORD | Google 應用程式密碼（16 碼，不是登入密碼） | 是 |
MAIL_TO | 額外收件地址，多個用逗號分隔 | 否，不填就只寄給自己 |
MAIL_TO 是「加上去」而不是「取代掉」——MAIL_USERNAME 那個信箱一定收得到，
填了 MAIL_TO 就是再多寄給那些人。收件地址放 secret 而不是寫死在 workflow 裡，
是因為這個 repo 是公開的，寫死會被爬蟲撈去發垃圾信。
應用程式密碼在 https://myaccount.google.com/apppasswords 產生（需先開兩步驟驗證），
只能用來寄信，隨時可撤銷。設定方式：
gh secret set MAIL_USERNAME --body "你的信箱@gmail.com"
gh secret set MAIL_PASSWORD # 執行後貼上 16 碼
寄測試信
到 Actions → snapshot → Run workflow，勾選「寄一封測試信」。
它會拿最近進場的錢包組一封標示為測試的信寄出，內容格式與真實通知完全相同——
測試信長什麼樣，真信就長什麼樣。不會動到名冊，可以放心重複測試。
換信箱、或懷疑通知壞掉時都用這個驗證。
名冊的結構與防呆
seen_wallets.json 依 event id 分組，每個縣市各有自己的名冊：
{ "updated_at": "...", "count": 533,
"events": { "848410": { "0xabc…": {"first_seen": "...", "name": "..."} }, ... } }
不從 data-*.json 反推「看過哪些錢包」，是因為那些檔有 MAX_OFFSET（10000 筆）上限。
將來筆數成長到會截斷時，早期的錢包會從資料裡消失，被誤判成新錢包而爆寄一整批信。
三種情況會靜默建檔、不寄信，避免一次收到上百封：
- 名冊檔不存在（第一次啟用）
- 名冊內容損毀（JSON 壞掉）
- 新加入的縣市第一次抓取
要把某個縣市重設為「全部已知」，把它在 events 底下那一段刪掉再跑一次即可。
縣市與候選人設定
所有縣市與候選人中文名都集中在兩個地方，要新增縣市就各加一筆，其餘程式碼完全不用動：
app.js 最上面的 EVENTS 陣列（前端顯示用，含政黨配色）scripts/snapshot.py 最上面的 EVENTS 清單（抓取與通知信用）
{
id: 848410, slug: 'keelung', city: '基隆市', office: '市長',
candidates: {
'Hsieh Kuo-liang': { zh: '謝國樑', party: 'kmt', partyZh: '國民黨' },
'Tung Tzu-wei': { zh: '童子瑋', party: 'dpp', partyZh: '民進黨' },
},
},
⚠️ 中文名不要用 Polymarket 網站的翻譯
Polymarket 的 zh-hant 介面是機器翻譯，而且有錯：
- 宜蘭的標題被譯成「宜蘭縣治安法官選舉優勝者」（Magistrate＝縣長）
- 桃園 94% 那位，API 英文名是
Chang San-cheng（張善政），
中文介面卻顯示「鄭文燦」——兩者是不同人。
目前依 Ches 判斷採用「鄭文燦」，程式碼裡有註記，若日後確認有誤改一行即可。
所以中文名一律以設定表為準，人工對照 API 回傳的英文拼音（groupItemTitle）。
政黨標記與未確認的中譯
party 只填確定的，沒把握的一律留空（顯示為中性灰）。
寧可不標也不要標錯——標錯會影響判讀。
同理，中譯沒把握的候選人乾脆不放進對照表，前端會顯示英文拼音原文，
不會把人漏掉。以下幾位待確認，確認後補進兩張設定表即可：
| 縣市 | 英文拼音 | 備註 |
|---|
| 彰化縣 | Wei Ping-cheng、Hung Jung-chang | |
| 南投縣 | Wen Shih-cheng | |
| 嘉義縣 | Wu Pin-jui、Tsai Sung-yi | |
| 花蓮縣 | Yu Shu-chen、Yeh Yao-hui、Lo Pei-chin | Yu Shu-chen 目前領先 |
| 臺東縣 | Wu Hsiu-hua、Li Wu Ying-chih | Wu Hsiu-hua 目前領先 |
佔位盤口
每個 event 底下有 29～33 個 market，但真候選人只有 2～6 位，
其餘是 Candidate A ～ Candidate Z 的佔位盤（成交量 0、賠率固定 0.5）。
前端預設隱藏沒人下注的佔位盤，只在下方標註還有幾個。
之後若有新人參選、佔位盤被改成真名，把名字加進設定表就會自動顯示；
沒加的話會顯示英文原文，不會被吃掉。
資料來源與欄位
| API | 用途 | 認證 |
|---|
gamma-api.polymarket.com/events?id=<eventId> | 盤口賠率、成交量、流動性 | 不需要 |
data-api.polymarket.com/trades?eventId=<eventId>&takerOnly=true | 每一筆成交明細 | 不需要 |
takerOnly=true 很重要：鏈上每筆撮合都有 maker、taker 兩方，
不加這個參數會把同一筆交易算成兩筆，成交數直接膨脹一倍。
資料判讀要注意的兩件事：
name / pseudonym 是使用者在 Polymarket 上的公開暱稱，不是實名。
部分帳號的 name 是系統自動填的錢包地址字串（例如 0xfBd8...-1779347618060），
程式會辨識出來並改用 pseudonym 或標示為「未具名」。- 錢包地址是 Polymarket 幫每個帳號部署的 proxy 合約錢包，
不是使用者自己持有私鑰的 EOA。要往上游追資金來源，還要看這個 proxy 錢包
是從哪個地址存入、由哪個 Relayer 代付 gas。
已知限制
- Data API 的
offset 上限是 10000。目前最大的高雄盤約 482 筆，離上限還很遠；
真的成長到那個量級時，snapshot.py 要改用 start/end 時間窗分段抓。
- GitHub Actions 的 cron 不保證準時。 實測延遲 30～106 分鐘都出現過，
尖峰時 GitHub 甚至可能把整班排程丟掉不執行——官方文件寫明排程是盡力而為，
不是真正的定時器。所以「預定 05:30」實際上可能 06:30 才跑，這不是腳本壞掉。
cron 的分鐘刻意設在
:30 以避開整點前後的排隊高峰。
要真正即時就用直連模式（開 VPN），網頁會自己去抓最新的。
- 改完
app.js 或 style.css 要記得把 index.html 裡的 ?v= 數字加一，
否則瀏覽器會一直用快取的舊版本。
網頁載入時 console 會印出 [選舉賭盤監控] app.js v8，
版號跟你剛改的對不上就是中了快取，按 Cmd+Shift+R 強制重新載入。
更新頻率
| 什麼 | 多久一次 | 改哪裡 |
|---|
| 網頁自動重抓 | 5 分鐘 | app.js 的 REFRESH_INTERVAL |
| Actions 抓快照＋檢查新錢包 | 5 分鐘（由 Cloudflare Worker 觸發） | cron-worker/wrangler.toml 的 crons |
⚠️ cron 寫多密，跟實際多久跑一次沒什麼關係
2026-09-22 實測：把 cron 從每 3 小時改成每小時，平均間隔幾乎沒變。
| 預期間隔 | 實際平均間隔 |
|---|
每 3 小時（30 */3 * * *） | 3 小時 | 4.6 小時 |
每 1 小時（30 * * * *） | 1 小時 | 4.3 小時 |
改成每小時後的 23 小時內只跑了 4 班，執行率 17%。
結論是 GitHub 給這個 repo 的排程執行大約就是一天 5～6 次，跟 cron 寫多密無關。
這是 GitHub 對免費／公開 repo 排程的節流，官方文件只寫「schedule 事件可能因負載而延遲」，
沒說會直接砍掉這麼多班。
還是維持每小時而不調回 3 小時，是因為反正配額一樣，
提出的請求多一點、被分配到的機會也多一點，沒有壞處。
解法：外部排程去按「Run workflow」
節流只限制排程，不限制手動觸發——按 Run workflow 都是秒級啟動。
所以真正的解法是讓 GitHub 以外的服務定時呼叫 workflow_dispatch API。
cron-worker/ 就是這件事：一支 Cloudflare Worker，每 5 分鐘打一次那支 API。
設定方式見 cron-worker/README.md。
snapshot.yml 裡的排程保留不動，當作 Worker 掛掉時的備援。
每 5 分鐘跑，但不是每 5 分鐘 commit
一天跑 288 次，如果每次都 commit，兩個月就是一萬七千個 commit，git pull 會愈來愈慢。
而這些 commit 絕大多數沒有意義——這個盤一天約 50 筆成交，288 個快照裡大概有 250 個
除了時間戳之外內容一模一樣。
所以 scripts/should_commit.py 會先判斷「這個盤真的有新動作嗎」：
| 會觸發 commit |
|---|
| 任何縣市有新成交 | ✅ |
| 錢包名冊出現新錢包 | ✅ |
| 新進錢包名單有新項目 | ✅ |
時間戳（fetched_at／updated_at） | ❌ |
| 盤口賠率、流動性、總成交量 | ❌ |
錢包的全站預測次數（traded） | ❌ |
下面三類為什麼不算：它們會自己一直跳動，跟「有沒有人在這個盤下注」無關——
賠率會因做市商調單而變，traded 會因為那個錢包在 Polymarket 其他市場
（跟台灣選舉無關）交易而變。讓它們觸發 commit 等於回到每輪都 commit。
代價：沒有新成交的那段時間，快照裡的賠率會停在最後一次 commit 的數字。
但沒有成交時賠率本來就不太會動，而且網頁連得到 API 時是直接讀即時賠率，
快照只是備援。
想看當下最新不必等排程：到 Actions → snapshot → Run workflow 手動觸發一次，
約一分半後網頁就是新的（按右上角 ↻ 重載）。終端機也可以直接下
gh workflow run snapshot.yml。
架構參考來源
概念參考自 tw-election-2026-tracker
（全國地方選舉政黨盤），沿用了它的深色介面風格與雙視圖設計，
但抓取邏輯、分組維度（政黨 → 候選人）、資料來源策略均為重寫。
主要差異：原專案靠一台 VPS 常駐 Python 程式抓資料再 git push，
單點故障且需要自行維運（其線上資料已停更）；這裡改為前端直連優先、
GitHub Actions 快照備援，不需要任何伺服器。
