Naly 工程筆記：以 Polymarket Gamma 作為可重現的市場快照層

重點摘要Polymarket Gamma 擷取讓 Naly 取得預測市場事件、市場、結果、價格、標籤與結算中繼資料的公開結構化視圖。Naly 使用這一層來選擇文章候選、錨定錯價彙整、支援 KBO 預測故事、保留來源引用，並建立可供日後驗證的持久市場快照。工程主張很簡單：編輯可信度始於可重現的市場輸入，而不是生成式文字。

摘要

Polymarket Gamma API 應被視為 Naly 的市場探索與中繼資料來源，而不是交易介面。Polymarket 官方文件將 Gamma 與 Data 和 CLOB API 分開：Gamma 涵蓋事件、市場、標籤、系列、體育中繼資料、搜尋、留言與公開個人檔案，而 CLOB 處理訂單簿、價格、價差與需驗證的交易操作。對 Naly 文章而言，這條邊界很有用。大多數編輯流程在需要逐筆報價層級的訂單簿細節之前，先需要問題文字、市場身分、結果標籤、顯示機率、分類標籤、截止時間與結算脈絡。

本文的論點是，Naly 應將 Gamma 擷取進一個版本化的市場快照層。快照不是真相；它是在特定時間觀察到的公開市場狀態，連結到來源 URL 並保留原始 payload。這讓 Naly 能公開其他人隱藏的東西：市場脈絡、訊號限制，以及文章生成時使用的精確證據。

它在 Naly 中的位置

Gamma 擷取位於文章生成之前、外部來源探索之後。在 Naly 的發布路徑中，它為四種下游用途提供證據包中的預測市場部分：

錯價彙整需要當前事件與市場候選，並具備足夠中繼資料，以便將市場隱含機率與有來源支持的推理進行比較。
KBO 預測文章需要體育市場、球隊或事件標籤、事件截止時間，以及可在不手動輸入市場脈絡的情況下呈現的結果標籤。
來源引用需要穩定的市場 URL、事件 slug 與市場識別碼，讓讀者能稽核文章為何討論某一特定合約。
預測驗證需要歷史快照，讓日後結算可以根據 Naly 在發布時實際看到的機率評分。

本地執行階段事實主要影響形狀，而不是新穎性。TypeScript 5.9 和 tsx 很適合作為擷取腳本； drizzle-orm 搭配 @neondatabase/serverless 可以保存正規化記錄與原始 JSON；Next.js 16 和 React 19 可以呈現產出的文章頁面； ai 以及 Claude SDK 套件只能在擷取已明確化市場狀態之後，才消耗準備好的證據包。

技術機制

一個穩健的 Gamma 擷取迴圈有六個階段。

探索。當 Naly 需要廣泛探索活躍市場時，使用 Gamma events；當文章錨定到已知的 Polymarket URL 時，使用市場或事件 slug。Polymarket 的市場資料指南建議以 events 進行完整的活躍市場探索，因為事件包含相關市場，可減少 API 呼叫。對體育等分類工作，標籤與體育中繼資料應在候選排序前縮小爬取範圍。
分頁。Gamma 同時支援 offset 風格端點與 keyset 端點。對大型或重複爬取而言，keyset 分頁更安全，因為 next_cursor 會成為延續 token，而 offset 在 keyset markets 端點上會被明確拒絕。對較小型的目標文章任務，若查詢窗口狹窄且輸出會立即快照化，offset 分頁仍可接受。
正規化。關鍵正規化規則是，結果標籤與結果價格必須按位置對應。Polymarket 的市場資料概覽記載 outcomes 和 outcomePrices 陣列是一對一陣列，因此索引紀律很重要。交換陣列不是外觀上的 bug；它會反轉文章的市場解讀。
快照化。同時儲存正規化欄位與原始 JSON。正規化欄位應包含提供者、擷取時間戳、事件 id 或 slug、市場 id 或 slug、問題文字、有提供時的 condition id、有提供時的 token 識別碼、結果標籤、結果價格、active 與 closed 旗標、結束時間、標籤、來源 URL，以及 payload 雜湊。原始 JSON 可保護 Naly 免受 schema 漂移影響，並讓驗證能重播精確的擷取成品。
候選評分。文章任務應使用編輯標準而不是交易執行標準來排序市場：新鮮度、可用時的成交量或流動性、結算接近程度、來源可用性、分類契合度，以及市場是否能產生清楚的讀者導向對比。候選評分絕不應暗示某個市場價格自動就是錯的；它應標記某個市場值得研究。
發布綁定。當生成文章引用某個市場時，文章應連結到已儲存的快照 id、Polymarket 來源 URL，以及作者使用的外部證據集。這就是一個只說市場是 62 percent 的頁面，與一個能證明該值在何時、何地、從哪個 payload 而來的頁面之間的差別。

速率限制是機制的一部分。Polymarket 記載了由 Cloudflare 強制執行的節流，以及針對 /events, /markets, /tags和 /public-search的特定 Gamma 限制。Naly 不需要為日常發布接近那些限制，因此正確姿態是保守的：有限並行、帶 jitter 的重試、用於冪等性的 payload 雜湊，以及在任務收到被節流、空白或結構上非預期的回應時發出警報。

文獻怎麼說

近期 arXiv 研究支持快照優先的設計。Jia 等人描述去中心化預測市場資料分散在鏈下中繼資料、成交層級交易記錄與 oracle 結算事件之間，並主張建立具備識別碼解析、增量更新與一致性機制的統一關聯式系統。Naly 較小的發布系統面臨同一類問題：市場中繼資料本身並不足夠，除非它日後能與價格、文章主張和結算結果連接。

Le 的校準研究與文章用語直接相關。該論文使用大型 Kalshi 與 Polymarket 資料集，主張校準取決於領域、時間範圍與交易規模效應；把價格視為表面機率的消費者，可能系統性地誤讀價格。對 Naly 而言，這表示文章應說市場隱含機率、觀察價格或公開市場訊號，而不是真相。文章只有在把原始市場觀察與 Naly 的模型或有來源支持的推理分開後，才能討論可能的錯價。

Dubach 的 Polymarket 微觀結構論文主要關於訂單簿資料，但它為擷取設計提供有用警示：高頻市場證據存在特定來源的錯誤模式、擷取延遲，以及重要的連接。Gamma 的粒度低於訂單簿 feeds，但同一原則適用。數字的來源必須可見。Gamma 快照、CLOB 中點價格與鏈上交易記錄彼此相關，但不可互換。

Madrigal-Cianci、Monsalve Maya 與 Breakey 將預測市場框定為貝葉斯逆問題，其中觀察到的機率與成交量歷史是有雜訊、內生的，並受異質交易者類型影響。這強化了 Naly 的編輯立場。擷取到的市場狀態是證據，不是裁決。好的工程會讓這種不確定性可被檢視，而不是在生成過程中被洗掉。

設計取捨

Gamma 對 CLOB 是第一個取捨。Gamma 給 Naly 可探索性、文章脈絡與中繼資料。CLOB 給更精確的定價與訂單簿機制。對日常工程文章與預測市場彙整而言，Gamma 應作為預設輸入，因為它回答市場在談什麼。當文章需要價差、中點價格或價格歷史精度時，可以加入 CLOB。

事件優先對市場優先的擷取是第二個取捨。事件優先對廣泛掃描成本更低，因為一個事件可以包含多個市場與共享中繼資料。市場優先對驗證更乾淨，因為最終分數會附著到特定的二元結果。Naly 應同時擷取兩種形狀，但當評估單一結果時，文章連結應指向市場層級主張。

原始 JSON 對型別化 schema 是第三個取捨。只存原始 JSON 很容易，但難以安全查詢。只存型別化欄位容易查詢，但當提供者欄位演變時很脆弱。持久模式是兩者並用：型別化欄位用於排序、呈現與連接；原始 payload 用於稽核、重播與遷移。

即時呈現對凍結呈現是第四個取捨。即時市場 widget 可能有用，但文章主張必須綁定到發布時快照。否則，當 Polymarket 移動、關閉或結算市場時，舊文章的意義可能會悄悄改變。對 Naly 的信任策略而言，當頁面提出有日期的主張時，凍結證據比新鮮度更重要。

失敗模式

最危險的失敗是結果與價格錯位。如果 Yes 和 No 標籤與價格分開解析，文章可能在看似合理的情況下反轉訊號。

第二個失敗是重複使用過時市場。某個市場可能在探索時仍活躍，但到發布時已關閉。每個文章任務都應在綁定快照前，立即重新驗證 active、closed、archived 與 end-time 欄位。

第三個失敗是多市場歧義。Polymarket 事件可以包含多個可交易市場。彙整文章可以引用事件，但驗證記錄必須引用 Naly 評估的特定市場與結果。

第四個失敗是 schema 漂移。公開 API 會改變欄位名稱、預設值與巢狀關係。快照儲存應包含 payload 雜湊、parser 版本、提供者 URL 與驗證錯誤，讓漂移可被觀察。

第五個失敗是過度宣稱校準。市場價格是有用的公開訊號，但文獻警告不要把它視為跨所有領域與時間範圍都乾淨的機率。Naly 的文案應保留市場隱含機率、Naly 估計與實現結果之間的差異。

第六個失敗是引用遺失。如果文章只儲存呈現後的 markdown，日後驗證無法證明哪個市場頁面與 payload 支持該主張。文章與市場的連接應是一等記錄，而不是嵌入式文字。

實作筆記

實用的 Naly 實作可以讓擷取契約保持精簡：

provider: polymarket-gamma.
provider_url: 用於探索的精確 Gamma 端點或公開市場 URL。
fetched_at: UTC 伺服器時間戳。
event_key 和 market_key: 穩定的提供者識別碼或 slug。
question: 標準市場問題文字。
outcomes: 排序後的標籤。
outcome_prices: 排序後的十進位字串，僅在驗證後正規化為數值。
status: active、closed、archived 與可發布性旗標。
raw_payload: 完整提供者回應。
payload_hash: 用於冪等性與重播的確定性雜湊。
parser_version: 解讀 payload 的程式碼契約。

文章生成器應以結構化證據接收這些資料，而不是鬆散的提示文字。接著它可以透過現有 AI stack 產生 markdown，使用網站 pipeline 呈現，並讓引用附著在來源記錄上。驗證 worker 日後可以把文章的市場快照連接到結算資料，並評分已發布主張是否經得起時間考驗。

工程原則刻意保守：擷取、正規化、快照化、引用，然後寫作。這個順序比要求模型瀏覽並摘要市場頁面更慢，但它創造了 Naly 在獲客與留存上真正需要的成品：一篇公開文章，其市場證據可以在結果已知後重播。