實戰手冊 · Field Manual 2026 春季號

github.com/ent0n29/polybot · 651 ★

第 03 期 · 量化交易 / Polymarket

Polymarket 開源交易基礎設施
與策略反向工程工具箱。

Polybot 是 ent0n29 開源的 Polymarket 交易基礎設施。五個 Java 21 微服務 + ClickHouse 行情倉 + Redpanda 事件流 + Python 研究腳本，從紙上回測串到實盤下單，並以 replication_score 量化任何目標使用者的訂單流分布。這份手冊帶你從零安裝、跑完一筆 Up/Down complete-set 套利，並理解 replication_score 的計算機制。

651

GitHub Stars

Java 微服務

Java 21

Corretto + Maven

MIT

研究用途授權

架構概覽

五個微服務構成的
可量測訂單流基礎設施。

ent0n29 在 README 把 Polybot 定位成「Open-source Polymarket trading infrastructure and strategy reverse-engineering toolkit」。兩個設計目標並列:前半是把整個 Polymarket 交易棧開源做出來,後半是反向工程任何一位使用者的策略。它是 AWARE 商業產品(trader intelligence + fund mirroring)的開源研究地基。

架構上它不是一個單機腳本,而是五個 Java 21 微服務:executor-service 負責下單與紙上/實盤雙模式,strategy-service 跑策略 runtime 與做市,ingestor-service 把市場與用戶交易吃進 ClickHouse,analytics-service 算複製分數與績效,infrastructure-orchestrator-service 管整條鏈的服務狀態。資料層用 ClickHouse 當行情倉,訊息匯流用 Redpanda(Kafka 相容),監控則是 Grafana + Prometheus + Alertmanager 一整套。

Polybot 把「策略複製」列為一級主題。research/ 目錄的 replication_score.py、replication_score_orders.py、sim_trade_match_report.py 是專門量化「候選機器人與目標使用者成交分布接近程度」的度量工具。用法是選定一位 Polymarket 目標使用者，以統計分數衡量訂單流的逼近程度，而非單純靠策略碰運氣。

Polybot Pipeline · 從行情到策略複製

Ingest→ ClickHouse→ Strategy→ Executor→ Analytics→ Replication Score→ Grafana

「reverse-engineer every polymarket strategy and trade fast」
反向工程每一條 Polymarket 策略,並快速跟上腳步。

— ent0n29 · Polybot GitHub About

本機安裝

四項前置環境就緒後，
執行 start-all-services 啟動整條服務棧。

前置環境是Amazon Corretto 21(或任一 Java 21+)、Maven 3.8+、Docker Engine 與 Docker Compose、Python 3.11+。Java 跑微服務,Maven 編譯,Docker 起 ClickHouse / Redpanda / Grafana / Prometheus,Python 負責 research/ 底下所有的策略複製與回測腳本。下面這段是 README 的 quick start,直接照貼即可。

# 抓 repo、進目錄、拉起整條服務棧
git clone https://github.com/ent0n29/polybot.git
cd polybot
./start-all-services.sh

# 編譯與測試(略過測試以加速第一次啟動)
mvn clean package -DskipTests
mvn test

# 觀察各服務健康狀態
curl http://localhost:8080/actuator/health
tail -f logs/strategy-service.log
      

環境變數:從 .env.example 開始

repo 根目錄附了 .env.example,把它複製成 .env 再填值。重點分四組:Polymarket 憑證(若要走實盤)、Kafka / Redpanda 連線、ClickHouse 主機與帳密、Grafana 與 Slack 警報整合。預設模式是 paper trading,你不填 Polymarket 憑證也能跑完整個 ingest → analytics → 紙上下單的鏈路。

cp .env.example .env
vim .env   # 填入 Polymarket / Kafka / ClickHouse / Slack 設定

# 監控與分析的 docker compose 是分開的
docker compose -f docker-compose.monitoring.yaml up -d
docker compose -f docker-compose.analytics.yaml up -d

# 收工
./stop-all-services.sh
      

第一次跑請保留在 paper 模式。README 明確標註「for educational and research purposes only」,作者要求所有策略在紙上跑過再上實盤。本手冊後面的 06 注意事項會列出實盤上線前該確認的清單。

五個服務 + 一整櫃研究腳本

各元件職責對應
訊號至下單鏈路的不同階段。

Polybot 由 Java 服務(撮合與策略執行)和 Python 腳本(研究與複製分析)兩層組成。優先理解三個核心元件:executor-service 的下單機制、research/replication_score.py 的訂單流比對邏輯、research/calibrate_maker_fill_model.py 將實盤成交時間餵回紙上模擬的方法。其餘元件均以此三者為基礎衍生。

Service · 01

executor-service

下單引擎

負責紙上與實盤雙模式的訂單執行,內建 Up/Down binaries 的 complete-set 套利策略。連到 Polymarket 帳號之前先在 paper 模式驗證。

Service · 02

strategy-service

策略運行時

策略 runtime 與市場做市邏輯。Java 寫的微服務,接收 ingestor 推來的事件,輸出訂單指令給 executor。

Service · 03

ingestor-service

市場抓取器

把 Polymarket 的市場行情與目標用戶的成交流,寫進 ClickHouse 與 Redpanda。是整條 pipeline 的源頭。

Service · 04

analytics-service

績效分析

量化分析、複製分數計算、策略表現報表。背靠 docker-compose.analytics.yaml,輸出餵到 Grafana 儀表板。

Service · 05

infrastructure-orchestrator-service

服務編排

統一管控其他四個服務的生命週期。對應 start-all-services.sh / stop-all-services.sh 的後台執行者。

Core · 06

polybot-core

共享核心

五個微服務共用的型別、領域模型、Polymarket 介面定義。Maven 多模組專案的根節點 pom.xml 從這裡走。

Data · 07

scripts/clickhouse

行情倉定義

ClickHouse 的 schema 與初始化腳本。每筆 trade、book change、用戶訂單都在這裡建表,後續所有研究腳本的源資料。

Data · 08

Redpanda

事件匯流排

Kafka 相容的事件流,連通 ingestor → strategy → executor → analytics。所有跨服務訊息走這條,環境變數在 .env 設定。

Research · 09

replication_score.py

分布比對

候選機器人與目標使用者的成交分布配對分數。衡量策略複製的接近程度，是反向工程工作流的核心量化工具。

Research · 10

replication_score_orders.py

訂單流比對

替紙上 / 實盤機器人,逐筆對比訂單流的決策序列。比成交配對更嚴格,看你下單時點是否一致。

Research · 11

calibrate_maker_fill_model.py

成交時延校準

估算掛單成交時間模型,讓 paper 模式的成交時點接近實盤。沒有它,你的回測會偏樂觀。

Research · 12

sim_trade_match_report.py

模擬對照表

把 paper bot 與目標使用者的成交一筆筆並排,輸出差異報告。是覆盤策略落差最直接的工具。

Research · 13

snapshot_report.py

離線快照

不依賴 ClickHouse，直接讀取凍結的快照檔，產出摘要報告。適合無服務連線的環境使用。

Research · 14

run_simulation.py

模擬主程式

執行端到端模擬。配合 backtest/ 子目錄與 paper_trading_dashboard.py,可以一次跑完策略迴圈與指標。

Research · 15

market_coverage_report.py

市場覆蓋率

檢查哪些市場、時間段、價格區間進了你的資料。沒有覆蓋就沒有策略,這份報告是回測前必跑。

Ops · 16

monitoring/

Grafana 儀表板

Prometheus + Grafana + Alertmanager 的設定檔。用 docker-compose.monitoring.yaml 拉起,Slack 警報連線在 .env.example 有範例。

哪個元件先跑?一張表決定

你正在做什麼	主要元件	搭配腳本
觀察 Polymarket 即時行情	`ingestor-service` + ClickHouse	`market_coverage_report.py`
把策略邏輯先在歷史資料上跑	`research/backtest/`	`run_simulation.py`
挑一位高手反向工程	`analytics-service`	`replication_score.py` + `replication_score_orders.py`
準備上實盤,先校準時延	`executor-service`(paper)	`calibrate_maker_fill_model.py`

進階使用模式 · Power-User Patterns

來自 README 與 docs 的
進階使用模式。

Polybot 是給研究人員使用的工作站，非即裝即用的交易程式。以下十條使用模式來自 README、docs/STRATEGY_RESEARCH_GUIDE.md、docs/EXAMPLE_STRATEGY_SPEC.md 與目錄結構，涵蓋第一週常見的組態與工作流問題。

TIP 01

paper 模式是實盤前的驗證階段，非選填步驟

README 把 paper trading 明確定位成「實盤前的必經驗證」。預設模式為 paper，不填 Polymarket 憑證也能跑完整條 pipeline。此為設計決策，非功能限制。

來源 · README Disclaimer

TIP 02

以 EXAMPLE_STRATEGY_SPEC.md 為起點撰寫策略

docs 附有策略規格範本，按此格式描述策略邏輯，後續所有 Java 服務與研究腳本即可直接接入。建議先讀 STRATEGY_RESEARCH_GUIDE.md，再按 spec 寫第一版。

來源 · docs/

TIP 03

complete-set 套利策略是內建的程式碼參考

executor-service 內建一個針對 Up/Down binaries 的 complete-set arbitrage 策略，可作為新策略的程式碼參考。在 paper 模式執行一輪，即可理解整個下單回路。

來源 · README · Built-in Strategies

TIP 04

snapshot_report.py 支援離線執行，不依賴 ClickHouse

snapshot_report.py 設計為完全離線運作。將生產資料 dump 為快照檔後，不需服務連線即可計算指標，適合無網路環境使用。

來源 · research/snapshot_report.py

TIP 05

replication_score 衡量分布配對，與 PnL 無直接關係

此指標衡量成交分布的配對程度，而非獲利金額。複製目標使用者時，應優先確認分數是否收斂。PnL 高但分數低，通常代表成交結果與目標策略並不相符。

來源 · research/replication_score.py

TIP 06

replication_score_orders.py 驗證訂單流的決策序列

replication_score_orders.py 比 replication_score.py 更嚴格，逐筆對齊下單的決策序列。兩個分數並用，才能區分「策略邏輯吻合」與「事後成交碰巧相近」這兩種不同情況。

來源 · research/replication_score_orders.py

TIP 07

未校準成交時延時，回測結果偏向樂觀

calibrate_maker_fill_model.py 估算掛單的實際成交時間分布，並將模型套回 paper 模式。跳過此步驟，backtest 的盈虧數字將脫離實盤條件。

來源 · research/calibrate_maker_fill_model.py

TIP 08

analytics 與 monitoring 的 docker compose 為獨立檔案

repo 根目錄有兩份 yaml：docker-compose.analytics.yaml 與 docker-compose.monitoring.yaml，可單獨啟動。研究階段不需要 Prometheus，觀察線上狀態時可暫時略過 analytics。

來源 · repo root

TIP 09

paper_trading_dashboard.py 提供不依賴 Grafana 的本機儀表板

執行 run_simulation.py 後接 paper_trading_dashboard.py，即可取得本機儀表板，無需啟動完整監控棧。適合早期迭代階段使用。

來源 · research/paper_trading_dashboard.py

TIP 10

Slack 警報整合：設定欄位已在 .env.example 預留

monitoring stack 預設支援 Slack 整合，設定欄位在 .env.example 已提供範本。實盤上線後，建議將策略偏差、ingestor 斷流、executor 失敗統一推送至 #polybot-alerts 頻道。

來源 · .env.example · monitoring/

從零跑一次

從 clone 到第一份
replication_score 報告。

以下情境模擬：在一台乾淨的 Mac 上跑通 Polybot，步驟包含啟動服務、進入 paper 模式、擷取歷史行情、執行 complete-set 套利範本，並對一位 Polymarket 目標使用者計算複製分數。所有指令均來自 README 與 research 目錄的腳本。

~/work/polybot · paper mode · Java 21 · ClickHouse

$ git clone https://github.com/ent0n29/polybot.git && cd polybot

[Cloning into 'polybot' · ~140 MB · Java 72.6% / Python 26.5%]

$ cp .env.example .env $ vim .env # 預設 mode=paper,先不填 Polymarket 憑證 # 補上 ClickHouse / Redpanda / Grafana 預設帳密即可

$ ./start-all-services.sh

[infra orchestrator] starting... [ingestor-service] :8080 HEALTHY [strategy-service] :8081 HEALTHY [executor-service] :8082 HEALTHY · mode=paper [analytics-service] :8083 HEALTHY [orchestrator] :8084 HEALTHY [clickhouse] ready [redpanda] ready

$ curl http://localhost:8080/actuator/health {"status":"UP","components":{"clickhouse":{"status":"UP"},"redpanda":{"status":"UP"}}}

$ tail -f logs/ingestor-service.log [ingestor] subscribed: polymarket.markets.* (Up/Down binaries) [ingestor] inserted 4,212 book updates into ch.trades_raw (last 60s)

$ cd research && python market_coverage_report.py --since 30d

market_coverage_report.py markets covered: 312 trade prints: 1,084,392 missing minutes: 0.4 % (within tolerance) → ready for backtest

$ python calibrate_maker_fill_model.py --strategy complete-set

[fitting maker fill model on last 14 days of book data] model.fill_time_p50 = 2.4s · p95 = 38s · saved to models/maker_fill_v1.joblib

$ python run_simulation.py --strategy complete-set --paper

[executor-service · paper] received 87 orders [strategy-service] complete-set arb on Up/Down · spread > 1.5¢ simulation complete · 87 trades · gross 142.30 USDC · fees 11.84 USDC

$ python paper_trading_dashboard.py --open [serving dashboard on http://localhost:8090 · open in browser]

$ python replication_score.py --target 0xA1B2…polymarket_top_trader \ --candidate runs/2026-05-19_complete-set

[loading 30d of target prints from ClickHouse] [aligning candidate trades by market_id + minute bucket] replication_score (distribution match) : 0.41 → not even close — target's edge is in event-window timing, not pricing

$ python replication_score_orders.py --target 0xA1B2… --candidate runs/2026-05-19_complete-set

replication_score_orders (order-stream match) : 0.18 → confirms timing mismatch · see sim_trade_match_report.py for per-trade diff

$ python sim_trade_match_report.py --target 0xA1B2… --out reports/

[wrote reports/sim_trade_match_2026-05-19.html — 312 rows] finding · target enters within 90s of news drops · candidate lags ~6 min

$ ./stop-all-services.sh # 收工

complete-set 套利分數 0.41，訂單流分數 0.18。
差距來自進場時機，而非策略邏輯本身。

— paper run 輸出示例，Polybot replication_score

pipeline 輸出的資訊意義

整條 pipeline 跑完，Polybot 輸出的核心數據是與目標使用者的差距量化：成交分布是否接近、下單時點是否對齊、是否缺少特定事件訊號。這些指標比 PnL 數字提供更多可操作的診斷資訊。

從 clone 到第一份報告，流程經過五個服務、ClickHouse、Redpanda、一個成交時延模型，以及兩個 replication 分數。設計目的是量化策略與目標使用者的距離，而非提供交易建議。AWARE 商業層即以此量化流程為核心包裝成產品。

注意事項與限制

使用邊界與實盤上線
前的確認清單。

READ THE DISCLAIMER。README 寫得很明白:「for educational and research purposes only」。Polybot 是研究工具,不是投資建議。所有實盤決策由你自負。
paper 模式驗證至少涵蓋一個完整市場循環後，再接實盤帳號。作者要求所有策略先在 paper 模式完成驗證，週期需包含結算與爭議事件，方可進入實盤。
分散式系統的協調問題在此架構中全部存在。五個 Java 服務 + ClickHouse + Redpanda，任何一段斷流都會導致後段做出錯誤決策。請在啟動服務前先把 monitoring stack 啟動，Grafana 與 Prometheus 是必要的觀測工具。
complete-set 套利範本不等於穩賺。它是教學範例,告訴你 executor 怎麼接策略邏輯。Up/Down 兩腿成交不對稱、價差被吃掉、結算時點落差,都會讓「理論套利」歸零。
replication_score 不能取代風控。分數高代表「你跟對方像」,不代表「對方真的賺」。對方可能正在連敗,你跟著複製的是賠錢部位。
ClickHouse 磁碟用量隨 ingestor 長期運行持續增長。請在部署前設定保留週期（TTL），避免本機 SSD 被寫滿後才進行補救。
Polymarket 涉及政治敏感交易品種。選舉、地緣事件、加密相關判決會引發劇烈波動與監管討論。Polybot 不處理任何合規 / KYC / 司法管轄議題，使用者須自行確認所在地的合法使用條件。
research/ 目錄以 CLI 腳本為主，不含 GUI 或權限控管機制。若需對外提供服務，須自行加入認證、稽核、版本鎖定與記錄追蹤等機制。

進階路徑

將 Polybot 整合至研究堆疊的延伸方向。

Polybot 已提供行情倉 + 事件流 + 策略執行 + 複製分析的完整基礎鏈。下一步是在此基礎上建立個人或團隊的工作站。以下五個方向可作為延伸參考。

五個延伸方向

1. 撰寫策略 spec。從 docs/EXAMPLE_STRATEGY_SPEC.md 開始，將策略邏輯按相同格式描述，接到 strategy-service。executor 與 analytics 無需更動，即可執行回測與績效報表。

2. 將研究腳本納入 CI。把 replication_score.py 與 sim_trade_match_report.py 配置為 GitHub Actions job，每次提交策略改動時自動執行，避免驗證步驟被跳過。

3. 將 Grafana 警報推送至 Slack。monitoring/ 與 .env.example 已預留 Slack 整合欄位。將策略偏差、ingestor 斷流、executor 失敗推送至 #polybot-alerts 頻道，實現 24/7 監控。

4. 作為 AWARE 商業層的後端基礎。Polybot 是 AWARE（trader intelligence + fund mirroring）的開源研究地基。需要可審計的後端參考實作時，可直接在此基礎上延伸。

5. 擴展至多市場版本。ingestor / strategy / executor 的介面設計為抽象層。將 Polymarket 介面替換為 Kalshi、PredictIt 或其他平台的 API，即可擴展至其他預測市場。

三份延伸閱讀

① docs/STRATEGY_RESEARCH_GUIDE.md：策略研究方法論，涵蓋資料準備、回測至複製分數的完整流程。
② docs/EXAMPLE_STRATEGY_SPEC.md：策略規格範本，撰寫第一版策略時可直接套用結構。
③ CONTRIBUTING.md：專案開發守則，提交 PR 與參與設計討論前先閱讀。

Open-source Polymarket trading infrastructure and
strategy reverse-engineering toolkit.

— ent0n29,Polybot README