使用手冊

第 03 期 · 量化交易 / Polymarket

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

ent0n29 開源的 Polymarket 交易基礎設施 Polybot 完整說明。五個 Java 21 微服務、ClickHouse 行情倉、紙上與實盤雙模式、複製分數研究工具鏈，涵蓋從零安裝到第一筆策略執行的完整流程。

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

ent0n29/polybot
星標
681
分支
136
授權
—
資料截至
閱讀時間
13 分
更新日期
開啟原始報告
GitHub Stars
651
Java 微服務
5
Corretto + Maven
Java 21
研究用途授權
MIT
本頁章節

01架構概覽

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

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 目標使用者，以統計分數衡量訂單流的逼近程度，而非單純靠策略碰運氣。

  1. Ingest

  2. ClickHouse

  3. Strategy

  4. Executor

  5. Analytics

  6. Replication Score

  7. Grafana

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

— ent0n29 · Polybot GitHub About

02本機安裝

四項前置環境就緒後，執行 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,直接照貼即可。

bash
# 抓 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 → 紙上下單的鏈路。

bash
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

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

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

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 + ClickHousemarket_coverage_report.py
把策略邏輯先在歷史資料上跑research/backtest/run_simulation.py
挑一位高手反向工程analytics-servicereplication_score.py + replication_score_orders.py
準備上實盤,先校準時延executor-service(paper)calibrate_maker_fill_model.py

04進階使用模式 · Power-User Patterns

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

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

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

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

來源 · README Disclaimer

以 EXAMPLE_STRATEGY_SPEC.md 為起點撰寫策略

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

來源 · docs/

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

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

來源 · README · Built-in Strategies

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

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

來源 · research/snapshot_report.py

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

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

來源 · research/replication_score.py

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

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

來源 · research/replication_score_orders.py

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

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

來源 · research/calibrate_maker_fill_model.py

analytics 與 monitoring 的 docker compose 為獨立檔案

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

來源 · repo root

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

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

來源 · research/paper_trading_dashboard.py

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

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

來源 · .env.example · monitoring/

05從零跑一次

從 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


ok: 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]
ok: 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¢
ok: 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]
ok: 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


ok: 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]
ok: 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 商業層即以此量化流程為核心包裝成產品。

06注意事項與限制

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

07進階路徑

將 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