Hướng dẫn API Polymarket: CLOB, REST & bot giao dịch (2026)

Phần 6: Đọc sổ lệnh

book = client.get_order_book(token_id=yes_token)

best_bid = float(book.bids[0].price) if book.bids else None
best_ask = float(book.asks[0].price) if book.asks else None
mid = (best_bid + best_ask) / 2 if best_bid and best_ask else None
spread = best_ask - best_bid if best_bid and best_ask else None

print(f"Bid {best_bid} Ask {best_ask} Mid {mid:.4f} Spread {spread:.4f}")

Sổ lệnh được trả về dưới dạng các mảng đã sắp xếp (bids giảm dần, asks tăng dần). Mỗi mức có price và size. Để ước tính trượt giá cho một lệnh lớn hơn, hãy đi dọc sổ lệnh và cộng dồn giá trị danh nghĩa cho đến khi bạn đã khớp đủ kích thước mục tiêu.

GTC nằm trên sổ lệnh, GTD tự động hủy tại dấu thời gian, FOK yêu cầu khớp đủ toàn bộ kích thước hoặc hủy, FAK lấy phần có thể ở mức giới hạn và hủy phần còn lại.

Phần 7: Đặt lệnh

Lệnh giới hạn (GTC - mặc định)

from py_clob_client.clob_types import OrderArgs, OrderType

args = OrderArgs(
 token_id=yes_token,
 price=0.45,
 size=100, # Cổ phiếu, không phải đô la. 100 cổ phiếu @ $0.45 = chi phí tối đa $45.
 side="BUY",
)
signed_order = client.create_order(args)
response = client.post_order(signed_order, OrderType.GTC)
print(response)

Lời gọi create_order ký một thông điệp có cấu trúc EIP-712 bằng khóa riêng của bạn. post_order gửi nó tới CLOB. Bạn không bao giờ gửi khóa riêng thô qua mạng - chỉ các lệnh đã được ký.

Các loại lệnh

Hủy lệnh

# Một lệnh
client.cancel(order_id="0xabc...")

# Hủy tất cả lệnh trên một thị trường cụ thể
client.cancel_market_orders(market=market['conditionId'])

# Phương án hạt nhân: hủy mọi thứ
client.cancel_all()

Phần 8: Streaming WebSocket

Polling Gamma mỗi giây là lãng phí và bạn sẽ nhanh chóng chạm giới hạn tốc độ. Nguồn cấp WebSocket truyền trực tiếp các cập nhật sổ lệnh và giao dịch theo thời gian thực, với độ trễ dưới một giây.

import json, websocket

WS_URL = "wss://ws-subscriptions-clob.polymarket.com/ws/market"

def on_open(ws):
 ws.send(json.dumps({
 "type": "market",
 "assets_ids": [yes_token, no_token],
 }))

def on_message(ws, message):
 event = json.loads(message)
 if event.get("event_type") == "price_change":
 print(f"{event['market']} {event['side']} {event['price']} size={event['size']}")

ws = websocket.WebSocketApp(
 WS_URL,
 on_open=on_open,
 on_message=on_message,
)
ws.run_forever(ping_interval=20)

Có hai nguồn cấp: nguồn cấp /market (sổ lệnh công khai + giao dịch) và nguồn cấp /user (các sự kiện lệnh và khớp lệnh của riêng bạn, đã xác thực). Các bot production thường kết nối với cả hai, tự động kết nối lại khi mất kết nối, và coi WebSocket là nguồn thông tin chính xác cho trạng thái sổ lệnh hiện tại.

Phần 9: Giới hạn tốc độ & Backoff

Khi bạn gặp HTTP 429, máy chủ sẽ trả về header Retry-After. Hãy triển khai exponential backoff với jitter:

import random, time

def post_with_backoff(fn, *args, max_retries=6):
 for attempt in range(max_retries):
 try:
 return fn(*args)
 except Exception as e:
 if "429" in str(e):
 sleep = (2 ** attempt) + random.random()
 time.sleep(min(sleep, 30))
 continue
 raise
 raise RuntimeError("Too many retries")

Phần 10: Kiến trúc bot tham chiếu

Mọi bot Polymarket vững chắc đều có cùng sáu thành phần. Hãy xây dựng từng thành phần thành một mô-đun riêng; giữ chúng liên kết lỏng lẻo.

Phần 11: Các chế độ lỗi thường gặp

• Dữ liệu WebSocket lỗi thời - Theo dõi thời điểm của tin nhắn cuối cùng theo từng tài sản; nếu không có cập nhật trong >30 giây trên một thị trường đang hoạt động, buộc làm mới bằng REST.
• Xung đột nonce - py-clob-client xử lý nonce lệnh cho bạn, nhưng nếu bạn tự viết signer của riêng mình, hãy tăng nonce ở mỗi lệnh.
• Số dư không đủ - Luôn kiểm tra số dư USDC trước khi đặt; sổ lệnh có thể hiển thị lệnh của bạn nhưng khớp lệnh sẽ từ chối nó.
• Thị trường bị tạm dừng hoặc đang chốt kết quả - Kiểm tra market.active && !market.closed trước khi giao dịch. Cập nhật Gamma bị trễ CLOB vài giây quanh thời điểm chốt kết quả.
• Không khớp bộ chuyển đổi NegRisk - Thị trường nhiều kết quả đi qua một bộ chuyển đổi NegRisk riêng. SDK xử lý việc này, nhưng hãy xác nhận lệnh của bạn đã đi đến đúng nơi.

Phần 12: Phần thưởng thanh khoản qua API

Polymarket chạy ~5 triệu USD/tháng cho phần thưởng thanh khoản chung cộng với trên 5 triệu USD/tháng cho phần thưởng theo thể thao (xem Phần thưởng thanh khoản). Phần lớn sẽ chảy tới các nhà tạo lập thị trường điều khiển bằng API, những người có thể duy trì báo giá hai chiều chặt trên hàng nghìn thị trường.

Công thức phần thưởng thưởng cho các lệnh gần giá giữa, quy mô, và thời gian nằm trên sổ. Một vòng lặp tạo lập thị trường tối thiểu:

1. Đọc sổ lệnh cho thị trường mục tiêu
2. Tính một giá giữa hợp lý (ví dụ, VWAP của 3 mức hàng đầu mỗi bên)
3. Đặt một bid tại mid - spread_target/2 và một ask tại mid + spread_target/2
4. Sau mỗi cập nhật WebSocket, định giá lại nếu báo giá của bạn lệch quá một tick so với mục tiêu
5. Hủy và thoát nếu sổ lệnh mỏng đi hoặc có tin tức mới

Phần 13: Đưa vào sản xuất

• Hosting: một VPS $6/tháng (Hetzner, DigitalOcean) ở châu Âu hoặc US-East là đủ cho hầu hết bot. Hãy đặt gần Polygon RPC nếu bạn cần độ trễ dưới 10 ms.
• RPC: dùng Alchemy, Infura, hoặc QuickNode cho Polygon RPC ổn định. Gói miễn phí là đủ cho đến khi bạn đặt hàng trăm lệnh mỗi phút.
• Giám sát: Prometheus + Grafana cho số liệu; một bot Telegram cho cảnh báo. Ghi lại mọi order ID bạn gửi và mọi khớp lệnh bạn nhận.
• Sao lưu: lưu trạng thái mỗi phút. Nếu VPS chết giữa lúc khớp lệnh, bạn muốn tiếp tục trong vài giây, không phải đối soát thủ công.
• Thuế: logger của bạn cũng là nhật ký kiểm toán - xem Hướng dẫn thuế.

Phần 14 - Mẹo được xác thực cho Polymarket API

Bảng tóm tắt Tình huống -> Hành động

Sắp tới là gì?

• Công cụ & Tài nguyên - các bảng điều khiển, phân tích và nguồn dữ liệu bên thứ ba bổ trợ cho API
• Chiến lược nâng cao - giao dịch chênh lệch giá nhiều chân và các cấu trúc giống quyền chọn phù hợp cho bot
• Phần thưởng thanh khoản - công thức chính xác để kiếm khoản hoàn lại khi tạo thanh khoản
• Hướng dẫn sổ lệnh - hiểu sâu hơn về cách đọc sổ lệnh trước khi bạn viết code tương tác với nó
• Bảng thuật ngữ - định nghĩa bằng tiếng Anh đơn giản của mọi thuật ngữ trong hướng dẫn này