Xây dựng bot Polymarket: scanner, sizing, execution, giám sát

Hướng dẫn này minh họa cách xây dựng một bot Polymarket liên tục quét thị trường, định cỡ cơ hội, thực thi qua CLOB và giám sát hiệu suất. Nội dung tập trung vào kiến trúc và các mẫu cho nhà phát triển bạn có thể triển khai bằng các API công khai của Polymarket và mô hình Relayer.

Những điểm chính

• Kiến trúc bot thành bốn dịch vụ độc lập: scanner, sizer, executor và monitor.
• Dùng Gamma và CLOB APIs của Polymarket để lấy danh sách và đặt lệnh; dùng WebSocket để cập nhật sổ đặt lệnh thời gian thực.
• Ưu tiên lệnh thị trường FAK để thực thi tốc độ cao nhưng luôn tính đến trượt giá và phí.
• Ghi chỉ số giám sát và công tắc tắt nhanh cho tranh chấp oracle, trì hoãn thanh toán hoặc khớp lệnh bất thường.

Tại sao cần cấu trúc này

Hệ thống giao dịch dễ hiểu hơn khi trách nhiệm được tách rõ. Một scanner tìm các edge ứng viên, một sizer chuyển edge thành vị thế, một executor đặt lệnh qua CLOB, và một monitor đảm bảo đúng đắn và an toàn. Sự tách biệt này cho phép bạn mở rộng, test và phân tích độ trễ cùng rủi ro một cách độc lập.

H2: Nguồn dữ liệu và API

Bắt đầu bằng việc kết nối các endpoint Polymarket sau vào các dịch vụ của bạn:

• Gamma (metadata thị trường): https://gamma-api.polymarket.com — markets, events, tags, series. Dùng phân trang với after_cursor; tránh offset.
• CLOB (sổ đặt lệnh & giao dịch): https://clob.polymarket.com — đọc orderbook là công khai; giao dịch cần API key + HMAC. Các SDK CLOB xử lý việc đặt lệnh.
• Market WebSocket (sổ đặt lệnh thời gian thực): wss://ws-subscriptions-clob.polymarket.com/ws/market — đăng ký để nhận book, price_change, best_bid_ask và tick_size_change. Gửi PING mỗi 10s.
• Data API (vị thế, open interest): https://data-api.polymarket.com để phân tích sau giao dịch.

Ghi chú thiết kế: kết hợp danh sách từ Gamma với feed WebSocket để quét trực tiếp hiệu quả. Tôn trọng giới hạn tốc độ của Gamma (ví dụ giới hạn /markets) và yêu cầu khóa của CLOB khi đặt lệnh.

H2: Scanner — tìm các cơ hội ứng viên

Chức năng

Scanner phát hiện các cơ hội phù hợp chiến lược của bạn: spread intra-market nhị phân, tổng nhiều kết quả, hoặc mẫu endgame. Nó nên không giữ trạng thái, có thể scale ngang, và tập trung vào tính toán edge thô.

Đầu vào và tần suất

• Đăng ký Market WebSocket với custom_feature_enabled: true để nhận best_bid_ask và các thay đổi tick.
• Backfill bằng Gamma /markets khi gặp một instrument mới để lấy metadata và các outcome.
• Duy trì một ảnh nhớ ngắn (in-memory) về best asks/bids cho mỗi outcome.

Tính toán edge

• Intra-market nhị phân: tính edge = 1.00 - (bestAsk(YES) + bestAsk(NO)). Edge dương là ứng viên.
• Nhiều outcome: edge = 1.00 - sum(bestAsk(outcomes)).

Ngưỡng và bộ lọc

• Ngưỡng edge tối thiểu (ví dụ > số cent cấu hình) để bù phí taker và rủi ro thực thi.
• Kiểm tra thanh khoản tối thiểu: độ sâu tại best ask phải đủ kích thước lấp mong muốn.
• Nhận biết tick-size: xử lý sự kiện tick_size_change — độ trơn giá có thể thay đổi thành $0.001 khi giá tiến về các cực.

H2: Sizing — quản lý rủi ro và phân bổ vốn

Mục tiêu

Sizing biến edge thô thành kế hoạch lệnh: mua bao nhiêu cổ phần cho mỗi outcome, và chia lệnh thế nào để hạn chế trượt giá.

Thành phần

• Giới hạn phơi nhiễm: giới hạn pUSD theo thị trường và toàn cục.
• Sizing giới hạn theo độ sâu: tính khối lượng tích lũy có sẵn theo các mức giá kế tiếp trên phía ask; chỉ sizing tới khối lượng giữ được trượt giá kỳ vọng trong ngưỡng chấp nhận được.
• Dự phòng phí: lấy đi phí taker dự kiến (biến thiên, tối đa 1.8% ở một số danh mục) từ edge gộp trước khi quyết định giao dịch.

Mẫu thực hành

• Bắt đầu với lấp thận trọng: ưu tiên nhiều lệnh FAK nhỏ thay vì một lệnh lớn trừ khi bạn kiểm soát được sổ.
• Nếu bạn mua một complete set qua luồng CTF split/merge, cộng chi phí split/merge gas (được Relayer xử lý) và sai số làm tròn do tick size.

H2: Executor — đặt lệnh và xử lý khớp

Loại lệnh và giới hạn

• Dùng endpoint giao dịch CLOB để đặt lệnh: https://clob.polymarket.com. SDK CLOB và Relayer quản lý triển khai ví, approvals và ký lệnh.
• Vì tốc độ, dùng lệnh thị trường FAK (Fill-And-Kill) khi phù hợp. FAK thực thi ngay hoặc huỷ; chúng giúp tránh phơi nhiễm kéo dài nhưng có thể khớp một phần.

Luồng thực thi

1. Chuẩn bị ý định giao dịch: danh sách token id của outcome và số lượng mục tiêu do sizer trả về.
2. Nếu thực thi complete-set nhiều outcome, bạn cũng có thể thực hiện CTF split (đúc một complete set) rồi bán các nhánh — Relayer và SDK che giấu thao tác CTF.
3. Gửi lệnh qua API giao dịch CLOB với header gán attribution phù hợp nếu bạn tham gia Builder Program.
4. Quan sát khớp lệnh từ WebSocket last_trade_price và cập nhật best_bid_ask hoặc từ phản hồi giao dịch của CLOB.

An toàn và đối chiếu

• Theo dõi khớp một phần và huỷ phần còn lại hoặc đặt giá lại ngay lập tức.
• Đối chiếu số dư CTF on-chain (qua Data API) sau khớp để đảm bảo bạn thực sự nắm giữ token outcome như mong đợi.
• Thiết lập idempotency keys và xử lý nonce cho việc thử lại lệnh.

H2: Giám sát và an toàn vận hành

Những gì cần giám sát

• Tỷ lệ khớp, trượt giá trung bình so với kỳ vọng, edge thực hiện sau phí.
• Độ trễ giữa cập nhật WebSocket và gửi lệnh.
• Sự kiện bất thường: tranh chấp UMA, tick_size_change, sự cố toàn nền tảng.

Cảnh báo và công tắc tắt

• Soft kill tự động: tạm dừng đặt lệnh mới khi P&L thực tế ròng giảm dưới ngưỡng hoặc khi trượt giá khớp vượt quá giới hạn.
• Hard kill: dừng tất cả lưu lượng ngay lập tức nếu UMA báo tranh chấp cho thị trường bạn đang nắm vị thế, hoặc nếu Relayer báo vấn đề thanh toán.

Nhật ký kiểm toán và quan sát

• Lưu mọi ý định lệnh, snapshot thị trường thô và khớp lệnh đã thực thi. Dùng những log này cho phân tích hậu kỳ và backtesting.
• Gắn tag log với market id, condition_ids và request ids để đối chiếu với bản ghi Gamma và CLOB.

H2: Builder Program, chứng thực và giới hạn tốc độ

Nếu bạn dự định định tuyến lệnh có attribution, tham gia Builder Program và quản lý khóa qua cài đặt Polymarket. Các tier Builder kiểm soát giới hạn relayer hàng ngày và phần thưởng. Để giao dịch qua CLOB bạn cần API key + HMAC và phải tôn trọng giới hạn tốc độ và quota relayer.

H2: Các rủi ro phổ biến và biện pháp giảm thiểu

Không bao giờ cho rằng edge toán học là chắc chắn. Các rủi ro cần tính tới:

• Rủi ro resolution: tranh chấp UMA có thể tạm dừng hoặc thay đổi thanh toán.
• Trượt giá và khớp một phần: FAK có thể khớp một phần; lập kế hoạch cho phơi nhiễm còn lại.
• Phí: phí taker thay đổi theo danh mục và có thể làm xói mòn các edge nhỏ (Geopolitics không tính phí).
• Thời gian thanh toán: thời gian redeem/merge và trì hoãn oracle có thể giữ vốn.
• Lỗi smart-contract hoặc Relayer: thiết kế phương án dự phòng và cảnh báo cho con người.

Ảnh hưởng tới giao dịch của bạn

Thiết kế bot sao cho mỗi đơn vị giao dịch nhỏ, có thể quan sát và đảo ngược trong giới hạn rủi ro của bạn. Định cỡ thận trọng, giám sát nhanh và điều kiện kill rõ ràng làm giảm rủi ro đuôi. Dùng Gamma và CLOB endpoints để có trạng thái thị trường xác định và ưu tiên lệnh FAK cho thực thi nhanh, nhưng luôn đo lường trượt giá thực tế so với kỳ vọng.

Kết luận

Kiến trúc trên cung cấp bản thiết kế thực dụng để xây dựng bot giao dịch Polymarket: một scanner dung lượng cao, sizer thận trọng, executor vững chắc dùng CLOB và Relayer, và lớp giám sát. Bắt đầu nhỏ, instrument mạnh mẽ và lặp lại trên sizing cùng bộ lọc khi bạn tích lũy dữ liệu trực tiếp.

Câu hỏi thường gặp

Nên dùng API nào để lấy danh sách thị trường và dữ liệu sổ thầu trực tiếp?

Dùng https://gamma-api.polymarket.com cho metadata thị trường (/markets) và wss://ws-subscriptions-clob.polymarket.com/ws/market cho sổ đặt lệnh thời gian thực và sự kiện best_bid_ask. Dùng https://clob.polymarket.com cho đọc order-book và giao dịch; đọc là công khai nhưng giao dịch cần API key + HMAC.

Nên dùng limit orders hay lệnh thị trường (FAK) cho arbitrage?

FAK (Fill-And-Kill) market orders thường được dùng vì tốc độ và để tránh phơi nhiễm kéo dài. Chúng có thể khớp một phần, vì vậy thiết kế sizing và đối chiếu phù hợp. SDK CLOB cung cấp helper để tạo lệnh thị trường FAK.

Tôi tính phí thế nào khi sizing lệnh?

Lấy đi phí taker dự kiến từ edge gộp trước khi giao dịch. Phí taker thay đổi theo danh mục (0% đến 1.8% hiện tại). Dùng ngưỡng edge ròng để bao phủ phí cộng trượt giá dự kiến và đệm giám sát.

Những gì cần giám sát cho một bot hoạt động?

Giám sát tỷ lệ khớp, trượt giá thực tế, độ trễ, thông báo tranh chấp UMA, sự kiện tick_size_change và sức khỏe Relayer. Triển khai soft và hard kill-switch cho trượt giá lớn, giảm P&L, hoặc tranh chấp oracle.

Tôi có thể định tuyến lệnh qua Builder Program không?

Có. Builder Program cho phép bên thứ ba định tuyến lệnh với attribution và kiếm builder fees. Các tier điều khiển giới hạn relayer hàng ngày và phần thưởng; chứng thực lấy tại polymarket.com/settings.