Naly 工程筆記：Polymarket Gamma API 用於預測市場文章的匯入

簡要Naly 將 Polymarket 的 Gamma API 作為所有預測市場工作流程中，決定性的發現與定價基礎，取代即時且隨機的新聞抓取，改以結構化市場實體為核心。每一輪週期中，它會將即時事件與市場轉換為可直接用於文章的訊號，供錯價彙整、KBO 前瞻、引用包與後續結果驗證使用，因此故事生成始終以可公開觀測的機率與市場結構為起點，而非推測意見。

摘要

Naly 將預測市場資料當作基礎設施，而非疊加層，因此編輯成果會直接連結到可後續稽核的外部市場狀態。Gamma API 提供事件、市场、標籤與價格的讀取路徑，不需要錢包層級金鑰。設計挑戰是要讓這個資料攝取層足夠嚴格以保證可靠性，同時仍保有內容團隊快速主題發掘所需的彈性。

在 Naly 中的位置

Polymarket Gamma 擷取位於原始市場原件與可發佈編輯資產之間的上游邊界。它是更完整流程的第一步：

輸入層： 從 Gamma 抓取事件、市場、標籤與市場狀態。
詮釋層： 標準化為 Naly 內部的 schema（event_id, market_id，代幣 ID、結果、機率、時間戳、啟用/關閉旗標）。
敘事層： 將標準化輸入提供給錯價彙總和 KBO 預測草稿流程。
驗證層： 保留已結算/已關閉的市場狀態，用於後續文章真值核查與回溯式記分卡。

截至 2026 年 6 月 10 日，這特別符合需要可信賴、可引用預測證據的進行中戰術：預測校準可見性、可重複的內容來源，以及後續驗證流程。

技術機制

Polymarket 定義三種 API，其中 Gamma 是事件／市場瀏覽與中繼資料的公開發現平面，而訂單薄／交易式資料由 CLOB 提供，使用者與持倉資料則由 Data API 提供（文件）。Gamma 與 Data 依 Polymarket 文件皆為公開介面，而 CLOB 則有私有且需認證的交易操作面。

Naly 只用公開端點即可實作穩健的每日流程：

發現活躍候選市場 透過 GET /events 使用 active=true, closed=false分頁（limit, offset），以及可選排序條件。
展開到子市場 使用事件層級 payload，因為事件會包含關聯市場，與逐一查詢市場相比可減少 API 呼叫次數。
鎖定精準實體 在已識別事件或市場時，使用基於 slug 的呼叫。
正規化定價 透過對應 outcomes 與 outcomePrices 陣列逐一對應到命名機率。
持久化稽核工件 同時以標準化資料列與原始快照保存，讓每篇文章都可追溯每個來源數值。
對下游生成加閘 依新鮮度＋結構檢查決定；過期或不完整快照在使用前先標記為需刷新。

Gamma 文件精確描述了這種作業模式：可供發現使用的有 /events, /markets, /public-search, /tags, 和 /series ，而分頁與篩選則透過 limit/offset, tag_id及相關 filters。它同時直接建議三種擷取模式：slug 查詢、以標籤為基礎的發現，以及事件列舉以進行廣泛掃描。對 Naly 來說，事件優先模式在建立大量每日候選時最具成本效益，因為每個事件可帶出多筆市場紀錄。

實務上，Naly 的最小真實來源紀錄應包含：

事件與市場 ID
市場 question
clobTokenIds （供後續與 CLOB 比對價格時使用）
outcomes 和 outcomePrices
enableOrderBook
active, closed時間欄位（開始／結束時間戳）
抓取時間戳與來源 URL

雖然 Gamma 已能提供堅固的機率基線，但可選的第二條精煉路徑仍可啟用：當 Naly 需要更短週期的盤中更新時，可在稍後納入 CLOB 端點，如 /price, /prices，或 /book 。

文獻回顧

對預測市場的研究支持這種資料優先的方法，但也會在解讀上補上防呆。

預測市場的市場資料模型只有在校準且正確詮釋時才有價值；價格在沒有脈絡下不是通用機率。2026 年一項關於 Polymarket 與 Kalshi 的研究發現，校準模式會依領域與時間範圍系統性變化，包括特定領域中可測到的不足信心。
另一份 2026 年聚焦生命週期的研究強調，具意義的市場分析需要同步的多層資料工程：市場中繼資料、交易事件與結算訊號必須明確連結並定期做一致性檢查，而非各自獨立抓取。
早期的市場微結構研究顯示，市場價格在連續拍賣式流程下會傳遞交易者資訊，因此 Naly 可將市場價格視為群體預測訊號，同時仍需隨時間驗證結果。
比較市場價格與其他方法（例如以問卷為基礎的預測）的文獻指出，預測市場可具高度可預測性，但前提是維持結果驗證與模型紀律。

對 Naly 來說，實務含意很直接：所有資料都要保留來源可追溯性，不要把任何單一價格快照當成最終真相，並且要分離 readiness （資料新鮮度＋完整性） story quality 與

（編輯敘事）。

設計權衡

Naly 有意在匯入上優先可靠性而非速度。 Gamma 單用 vs Gamma+CLOB：
Gamma 快速提供穩定的發現與公開脈絡；加入 CLOB 可提升微結構豐富度，但會增加認證與端點複雜度。 每日快照 vs 持續串流：
決定性排程抓取較易稽核與重現，但會錯過次分鐘等級的區間轉折。 先事件抓取 vs 先市場抓取：
事件優先可降低重複呼叫並提高脈絡覆蓋；市場優先在狹窄任務下可略減少回傳負載。 廣泛 schema vs 嚴格 schema：
廣泛 JSON-first schema 可加速整合，但會提高 schema 漂移風險；嚴格標準化可更早抓到漂移，但會增加遷移負擔。 通用欄位 vs 領域特定欄位：

使用共享欄位可提升跨文章重用；新增領域特定擴充（例如體育專用信心水平區間）可提高即時精度，但可能導致長期維運碎片化。

失效情境

最大的失效模式是營運端，而非演算法端。

分頁缺口導致資料遺失： 如果 limit 與 offset 在兩次輪詢間改變，可能出現重複或缺漏。緩解方式：對分頁游標做檢查點，並強制執行可重複 upsert。
預設 closed=false 遺失歷史脈絡： 開放市場抓取會省略已解決項目，除非 closed=true 明確要求。緩解方式：為驗證任務執行專用歷史回填路徑。
Slug 不穩定： 產品 URL 與可讀 slug 可能會漂移。緩解方式：內部優先採用主 ID，將 slug 當次要鍵保留。
語意欄位漂移： outcomes/outcomePrices 詮釋在 schema 順序假設錯誤時會壞掉。緩解方式：在匯入階段驗證陣列對齊與長度。
短暫 API 可用性或節流： 公開端點可能失敗或回傳部分 payload。緩解方式：使用指數退避重試、在反覆失敗時進入失敗佇列，並保留先前快照。
晚結算與過時敘事： 驗證文章可能在結算尚未完整落地前就先發佈。緩解方式：將結算狀態作為發布狀態的一部分保存，並用不可變更正日誌進行事後更新。

考量 Naly 的信任優先策略，這條流程應採取 fail closed：與其以無法驗證的市場狀態發文，不如延遲發佈。

實作備註

以既有執行堆疊來看，實作仍相當直接：

使用 Next.js server handlers（next@16.0.7)
在 Neon 中以 drizzle-orm@^0.44.7 保存標準化列 @neondatabase/serverless@^1.0.2 並加上市場識別碼的明確唯一條件。
將原始 payload 快照存到 Vercel Blob（@vercel/blob@^2.0.0)，便於稽核與事後差異比對。
將 markdown 來源生成與文章組裝保留在匯入核心之外；使用 marked@^17.0.1 做安全轉換 ai@6.0.0-beta.105 與 @anthropic-ai/claude-agent-sdk@^0.2.15 在資料完整性檢查通過後。
使用 tsx@^4.21.0/typescript@^5.9.3 在回填歷史窗口時進行可重現的一次性重播。

截至 2026 年 6 月 10 日，架構應優先確保三項硬結果：原始快照不可變性、內部 schema 的決定性映射，以及從來源 API URL 到最終文章引用的驗證導向稽核軌跡。