Opinion Whale Tracker：把預測市場訂單簿聚合成巨鯨掛單監控的 Python 工具

用 AI 摘要這篇文章：

ChatGPT Claude Perplexity Google Grok

Opinion Whale Tracker 是一份用 Python 把預測市場訂單簿聚合成「巨鯨掛單監控層」的範例程式碼。它連的是 Opinion 這個建立在 BNB Smart Chain（BSC）上的預測市場，透過官方的 CLOB（中央限價訂單簿）SDK 分頁拉市場清單、逐個市場拉買賣掛單，再把單一側總價值超過門檻的掛單標成巨鯨。整份後端大約只有 19KB 的 Python，讀完一份 main.py 就能看懂它的資料流程。

Pin

這裡的 CLOB 指的是把買賣雙方掛單集中撮合的訂單簿結構，和你在交易所看到的限價掛單是同一類東西；Opinion 把它包裝成 SDK 與代理閘道供開發者取用。這份工具需要一組 Opinion 的 API 金鑰才能連到資料來源，沒有金鑰時後端只會回傳空資料。

判斷要不要用它之前，有一件事會直接決定答案：這份 repo 根本沒有授權檔，GitHub 的 API 也回傳 license: null，README 只寫了「用於技術演示與學習目的」。看得到程式碼在法律上不等於可以自由改作或商用，想拿它做產品得先跟作者談授權。這個前提會在後面「採用它之前要先接受的事」再展開。

這份程式碼實際在做什麼

把 backend/main.py 的邏輯攤開，資料流程是固定的四步。它先用 opinion_clob_sdk 的 Client 連到 Opinion 的代理閘道 proxy.opinion.trade:8443，逐頁把市場清單拉下來（預設拉七頁、每頁二十個，最多一百四十個市場，再取前五十個往下處理）。接著對每個市場判斷它是二元市場（只有 YES 與 NO 兩個結果）還是分類市場（一個題目下有多個子選項），兩種結構取訂單簿的路徑不同：二元市場直接拿 yes_token_id 查價格與掛單，分類市場則要先呼叫一次把底下的子市場全部撈出來，再逐一處理。

取到訂單簿之後，程式把買單與賣單各自的深度算成一個金額，算成「買牆」與「賣牆」的價值。最後把超過門檻的牆列出來，依金額由大到小排序，就是前端看到的那份巨鯨清單。每一筆被標出的巨鯨會帶上市場代號、屬於買方還是賣方、當下價格、掛單數量與換算後的美元價值，並依價值由大到小排列，方便你一眼看出哪一面牆最厚。整個過程還套了一層全域快取，後端會定期刷新，避免每次有人查詢都去打上游 API。

攤開程式碼會看到幾個具體的 SDK 呼叫。client.get_markets(page, limit) 負責分頁拉市場清單，回傳的結構裡帶有 yes_token_id、volume（成交量）與 status_enum（狀態）這些欄位；client.get_latest_price(token_id) 拿某一個結果代幣的當下價格；client.get_orderbook(token_id) 則把訂單簿的買賣掛單一次拉回來，程式再逐筆把 size 加總算深度。分類市場多一步 client.get_categorical_market(market_id)，用來展開它的子市場。這組呼叫順序就是你想換到別的 CLOB 資料來源時要照樣改寫的部分。

Pin

程式對資料量做了明確設限：即使分頁拉到了最多一百四十個市場，process_market 迴圈只會處理前五十個，serverless 版的 api/markets.py 更只處理前二十個。這是為了在 Vercel 六十秒的最長執行時間內跑完所做的取捨，也代表前端看到「只有這些市場」是程式刻意截斷的結果，不是 Opinion 上真的只有這些。如果你要看的市場排在五十名之外，得自己把這個上限放大。

這個流程很直白，靠的是分頁、加總與門檻判斷，沒有機器學習或錢包行為辨識。它的價值在於把「CLOB API 怎麼分頁、訂單簿怎麼拉、深度怎麼算」這幾件開發者一定會踩的事，用一份可讀的程式碼示範一遍。如果你想做的是類似的資料聚合監控，這份程式碼是一個還不錯的起點骨架；但如果你期待的是會自動判斷哪些錢包正在布局的智慧偵測，它目前沒有這一層。

巨鯨在這裡只是一個 500 美元的門檻

「巨鯨」這個詞在這個工具裡有明確定義，而且定義得很樸素。原始碼裡有一個常數 WHALE_THRESHOLD = 500，只要某個市場某一側的掛單總價值達到 500 美元，那一筆就會被標成巨鯨。它看的是訂單簿上「掛著」的單，不是鏈上的成交紀錄，也不是某個錢包的歷史持倉變化。它告訴你「此刻帳面上有大戶掛了一面牆」，但這面牆可能下一秒就被撤掉，工具本身沒有追蹤掛單的生命週期。

這個門檻可以透過 /api/whales?threshold=1000 這類查詢參數臨時調高或調低。要留意的是，500 美元算不算你心中的「巨鯨」完全由你自己決定：在一個總成交量很大的市場裡，500 美元的掛單可能稀鬆平常；在小市場裡它可能就是一面主導短期價格的牆。把門檻當成一個可調參數來觀察分布，會比直接把工具輸出的「巨鯨」當成市場訊號來得安全。

買賣牆價值算式在兩種市場類型之間不一致

讀 process_market 這個函式時，有一個會影響你怎麼解讀結果的細節：買牆與賣牆的價值算式，在二元市場和分類市場之間用的公式並不一樣。在二元市場裡，買牆深度是所有買單數量加總後乘上價格，賣牆深度則是數量加總乘上「一減價格」。到了分類市場，買牆和賣牆又都改用每筆價格乘數量再相加的口徑。

// 二元市場（main.py 簡化）
bid_depth = sum(bid.size) * price
ask_depth = sum(ask.size) * (1 - price)

// 分類市場（main.py 簡化）
bid_depth = sum(bid.price * bid.size)
ask_depth = sum(ask.price * ask.size)

這個差異不一定代表程式寫錯了，但它代表一件實務上要緊的事：如果你想拿這份程式碼改作，跨市場類型的巨鯨金額沒辦法直接放在一起排名或比較，因為同一筆掛單在兩種算法下的價值可能不同。二元市場的賣牆用「一減價格」而不是直接用價格，是一個不常見的選擇，你繼承這份程式碼時要先想清楚它符不符合你要的口徑，否則把不同市場的巨鯨金額混在同一張表裡會誤導讀者。

兩種跑法與六個 API 端點

這份 repo 提供兩種部署形式。完整的形式是 FastAPI 後端搭配一個靜態前端頁面，用附帶的 start.sh 啟動後，後端跑在 8000 埠、前端跑在 8080 埠，適合自己架來長期監看；前端是 Tailwind 寫的深色介面，用綠色長條標買牆、紅色長條標賣牆，巨鯨項目有滑入動畫。精簡的形式走 Vercel 的 serverless，由 api/markets.py 當無伺服器函式（最長執行六十秒）、public/ 當靜態資源，作者的線上 demo 就走這條路，適合快速給人看一眼。兩種形式背後的資料邏輯一致，但能打的端點不同：完整模式開出六個查詢端點加一個刷新端點，serverless 版的 Vercel 路由只指向單一的 /api/markets，想看個別市場或訂單簿得在這個整合回傳裡自己過濾，也沒有那份常駐快取。

完整 FastAPI 模式開出來的查詢端點有下面這六個，另外還有一個觸發快取刷新的 POST /api/refresh，開發者可以直接拿 curl 或瀏覽器打：

curl http://localhost:8000/api/markets
curl "http://localhost:8000/api/whales?threshold=1000"

安全設計上，程式碼裡不存放任何金鑰，API 金鑰透過 OPINION_API_KEY 環境變數注入，.gitignore 也排除了 .env* 與 .venv。如果沒有設定金鑰，後端會回傳空資料，不會丟出敏感錯誤訊息，這對部署 demo 比較友善，但也代表你看到空白畫面時要記得先檢查環境變數有沒有設對。連線設定裡用的私鑰是一組 0x...0001 的佔位值，因為這個工具只讀資料、不簽交易，所以不需要真實私鑰，這也算是一個可以安心看程式碼的設計。

沒有授權檔，而且綁死 Opinion 這一條鏈

幾個會改變採用決定的限制，誠實列出來。最關鍵的是授權狀態：repo 沒有 LICENSE 檔，GitHub 回傳 license: null，README 寫的是「用於技術演示與學習目的」。在沒有授權檔的情況下，預設是著作權人保留所有權利，你可以讀、可以學，但無法任意改作、再散布或拿去做商業產品。把它稱為「開源」並不準確，比較貼切的說法是 source-available，也就是看得到原始碼。想正式拿來用，最穩當的做法是去 repo 開一個 issue 問作者要不要補一份授權條款。這和另一份同樣只標「原始碼公開」的加密貨幣做市工具是同一類情況，想商用都得先處理授權。

它也只讀資料、不執行交易。這個工具把訂單簿和大額掛單整理出來給你看，但它不會幫你下單、不會發交易、也不產生交易訊號（程式碼裡全是查詢呼叫，沒有任何下單或簽章的邏輯）。把它當成資料監控儀表板來理解，會比較接近它的真實定位；若把它當成交易訊號來用，會超過它設計上要承擔的責任，預測市場的掛單本來就會頻繁撤改，掛單分布不等於未來價格走向。

它還綁定單一市場與單一鏈：只能看 Opinion 這個預測市場、只能走 BSC 鏈。它沒有辦法拿來監看 Polymarket 或其他鏈上的預測市場，因為 SDK 與代理閘道都是 Opinion 專屬的，想跨市場得自己換資料來源。維護訊號也偏弱：整份 repo 的程式碼集中在 2025 年 12 月 5 日同一天推送上來，之後就沒有再更新，0 個開 issue、58 顆星。它更像是一份作者分享出來的作品集等級範例，離一個有社群持續維護的專案還有距離。啟動後的快取刷新順暢度與上游 API 穩定度，要自己實際運行過才能確認。

想自建訂單簿監控層的開發者

這份程式碼最適合的讀者，是想理解預測市場 CLOB 資料怎麼聚合、或想自建一個訂單簿監控層的開發者。它用很少的程式碼把分頁、訂單簿、深度計算、門檻篩選串起來，當成學習材料或骨架都值得。相對地，如果你要的是一個裝起來就能用、有授權保障、跨多個預測市場、還能主動告警的成熟產品，它目前的狀態（沒有授權檔、單日推送、綁單一市場）還到不了那裡。

README 自己也列了幾個延伸方向，正好點出它現在缺什麼：接更多資料來源讓市場覆蓋更廣、把巨鯨與訂單簿做成圖形化呈現、以及接上 Prometheus 或 Grafana 做即時告警。這幾項目前都只是文字建議，沒有對應的實作，也就是說它給你的是「讀資料、算深度、列清單」這段骨幹，告警與歷史趨勢這類需要持久化與排程的能力要你自己補。對於只想快速驗證「某個市場有沒有大額掛單」的開發者，這段骨幹已經夠用；對於要做正式監控產品的人，它只是一塊還要大量加工的半成品。

想自己跑一遍的話，流程很短：建立虛擬環境、pip install -r backend/requirements.txt、設定 OPINION_API_KEY 環境變數、執行 python backend/main.py。金鑰得你自己去向 Opinion 取得，repo 裡沒有提供。跑起來之後先打 /api/stats 確認資料有進來，再調 /api/whales 的門檻觀察不同金額下的掛單分布，會比只看前端更有感。如果你只是想學 CLOB 聚合的思路，光是讀 main.py 的四個函式就值得了。