Polymarket API rate limits — Gamma, Data & CLOB

Giới hạn tốc độ API của Polymarket là các cơ chế điều chỉnh mà bạn phải thiết kế xung quanh khi xây dựng bot, bảng điều khiển hoặc hệ thống phân tích. Hướng dẫn này nêu rõ các giới hạn đã được tài liệu cho từng giao diện công khai (Gamma, Data, CLOB và Market WebSocket), giải thích các ràng buộc quan trọng của Gamma /markets (bao gồm quy tắc 300 req / 10 s cho /markets và phân trang theo cursor), và đưa ra các chiến lược cụ thể—gộp lệnh, bộ nhớ đệm, phân trang theo cursor, lùi dần mũ để giữ client của bạn đáng tin cậy dưới tải.

Những điểm chính

• Endpoint /markets của Gamma: 300 requests trong 10 giây; sử dụng tham số limit và after_cursor cho phân trang (không dùng offset).
• Giới hạn danh sách kết hợp: các cuộc gọi danh sách /markets + /events chia sẻ giới hạn 900 req / 10 s; tổng thể Gamma: 4000 req / 10 s.
• Dùng CLOB và Data APIs cho các truy vấn chuyên biệt; CLOB yêu cầu API key + HMAC cho lệnh giao dịch, các truy vấn đọc là công khai.
• WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market) cung cấp dữ liệu thời gian thực; ưu tiên WS cho cập nhật sổ lệnh trực tiếp thay vì polling.
• Mẫu giảm thiểu: gom yêu cầu, TTL bộ nhớ đệm, lùi dần mũ với jitter, hàng đợi nhận biết tỉ lệ, và lấy dữ liệu theo phân trang.

Tại sao giới hạn tốc độ quan trọng

Giới hạn tốc độ bảo vệ hạ tầng chia sẻ của Polymarket và ngăn các client ồn ào làm giảm trải nghiệm cho người khác. Với các nhà phát triển xây bot arbitrage hoặc hệ thống phân tích, việc chạm giới hạn dẫn tới từ chối yêu cầu ngay lập tức và có thể phá vỡ các luồng thời gian nhạy cảm. Lên kế hoạch mẫu yêu cầu trước giúp giảm bất ngờ và làm hệ thống bền bỉ hơn.

Giới hạn tốc độ và endpoint Polymarket đã được tài liệu

Gamma (metadata thị trường chính)

• Base URL: https://gamma-api.polymarket.com
• Giới hạn đáng chú ý:
  • /markets: tối đa 300 requests mỗi 10 giây. Sử dụng tham số limit (tối đa 1000) và phân trang theo cursor qua after_cursor. API sẽ từ chối offset với HTTP 422.
  • Giới hạn danh sách kết hợp /markets + /events: 900 requests mỗi 10 giây.
  • Toàn bộ giao diện Gamma: 4000 requests mỗi 10 giây.

Ghi chú thực tế:

• Luôn ưu tiên after_cursor do cuộc gọi trước trả về; đừng cố mô phỏng keyset bằng offset.
• Điều chỉnh limit để giảm số lần round trip. Nếu bạn cần danh sách toàn bộ markets, limit=1000 sẽ giảm số cuộc gọi.

Data (vị thế, giao dịch, holders)

• Base URL: https://data-api.polymarket.com
• Xác thực: Không yêu cầu cho các truy vấn công khai.
• Tài liệu ngắn gọn mô tả giao diện nhưng không liệt kê số giới hạn theo endpoint cho Data. Hãy coi Data là công khai, nhưng triển khai các điều khiển phía client thận trọng giống Gamma (gộp, bộ nhớ đệm, lùi dần).

CLOB (sổ lệnh và giao dịch)

• Base URL: https://clob.polymarket.com
• Truy vấn đọc là công khai. Giao dịch yêu cầu API key + HMAC.
• Giao diện CLOB cung cấp sổ lệnh, midpoint, lịch sử giá và đặt/hủy lệnh. Tài liệu không công bố số giới hạn theo endpoint rõ ràng cho các truy vấn CLOB; coi các đường dẫn giao dịch là nhạy cảm với tỉ lệ và sử dụng CLOB WebSocket hoặc Market WS để có dữ liệu sổ lệnh trực tiếp khi có thể.

Market WebSocket (cập nhật thị trường thời gian thực)

• URL: wss://ws-subscriptions-clob.polymarket.com/ws/market
• Không yêu cầu xác thực cho dữ liệu thị trường.
• Feeds: sổ lệnh thời gian thực, price_change, best_bid_ask (kích hoạt bằng custom_feature_enabled: true), last_trade_price, tick_size_change.
• PING heartbeat mỗi 10 giây. Tối đa 500 instruments trên mỗi kết nối.

Chi tiết /markets của Gamma bạn phải tuân theo

• Phân trang: chỉ after_cursor. API trả về next_cursor — truyền nguyên nó cho cuộc gọi tiếp theo.
• limit mặc định là 20, tối đa 1000. Dùng limit lớn hơn cho đồng bộ hóa khối lượng lớn.
• Tham số lọc chấp nhận mảng như slug, id, condition_ids, clob_token_ids, question_ids, market_maker_address và các tham số khác như closed, active, archived, tag_id.
• Sắp xếp: order chấp nhận danh sách trường cách nhau bởi dấu phẩy (ví dụ volume24hr,liquidity) và ascending là boolean với mặc định true.

Các tín hiệu lỗi phổ biến và cách phản ứng

• HTTP 429 (bị giới hạn): dừng polling ngay lập tức, lùi lại và thử lại với chiến lược lùi dần mũ cộng jitter.
• HTTP 422 khi dùng offset: chuyển sang phân trang after_cursor.
• Phản hồi không đầy đủ hoặc trang rỗng: tôn trọng cursors; kiểm tra bộ lọc của bạn. Nếu bạn tin rằng đã chạm quota phía server, giảm song song các yêu cầu client.

Mẫu thiết kế để tránh bị điều chỉnh băng thông

1. Cache tích cực

• Cache danh sách markets và metadata với TTL ngắn (30s–2m) tùy vào nhu cầu. Markets và danh sách sự kiện hiếm khi thay đổi theo từng giây.
• Cache theo khóa truy vấn (filters + order). Làm vô hiệu cache chỉ khi bạn nhận được sự kiện thay đổi (ví dụ từ WebSocket) hoặc khi TTL hết hạn.

2. Gộp và tăng limit

• Với đồng bộ hóa toàn bộ, dùng limit=1000 để giảm round trips tới /markets.
• Kéo các trang lớn vào khung giờ ít tải và dùng cập nhật tăng dần từ WebSocket.

3. Dùng WebSocket cho dữ liệu thời gian thực

• Với cập nhật sổ lệnh trực tiếp hoặc biến động giá, đăng ký Market WS thay vì polling Gamma hoặc truy vấn CLOB. WS hỗ trợ tới 500 instruments mỗi kết nối; phân mảnh client nếu bạn cần >500.

4. Hàng đợi nhận biết tỉ lệ và lùi dần

• Triển khai bộ giới hạn phía client theo leaky-bucket hoặc token-bucket khớp với đỉnh đã tài liệu (ví dụ 300/10s cho /markets).
• Khi nhận được 429, áp dụng lùi dần mũ với jitter và tăng dần cửa sổ thử lại.

5. Gộp các yêu cầu đồng thời giống hệt

• Nếu nhiều phần của ứng dụng yêu cầu cùng một truy vấn /markets đồng thời, gộp chúng thành một yêu cầu đang chờ và phân phát chung kết quả.

6. Đồng bộ theo cursor-first

• Luôn theo phân trang theo cursor. Với đồng bộ trực tiếp, yêu cầu trang đầu rồi đăng ký delta nếu được hỗ trợ. Đừng cố gắng thực hiện nhiều fetch cursor song song một cách ngây thơ có thể vượt quá giới hạn theo endpoint của Gamma.

Ví dụ chiến lược fetch

• Job lập chỉ mục lớn (không thời gian thực): fetch /markets?limit=1000 rồi theo next_cursor đến khi kết thúc. Nghỉ ngắn giữa các trang, và tôn trọng giới hạn 300/10s cho endpoint.
• UI gần thời gian thực: fetch bộ cơ sở một lần (cache 30s), rồi mở WebSocket để nhận delta và cập nhật best_bid_ask.
• Micro-client danh sách theo dõi: phân mảnh watchlists giữa nhiều kết nối WS nếu >500 instruments.

Hướng dẫn vận hành cho bot và client throughput cao

• Dùng CLOB WebSocket hoặc các truy vấn CLOB cho dữ liệu ở mức sổ lệnh, và Gamma cho metadata thay đổi chậm hơn.
• Giữ an toàn thông tin xác thực giao dịch (CLOB API key + HMAC); các endpoint giao dịch cần xác thực.
• Giám sát tỉ lệ 429 và các chỉ số độ trễ theo endpoint. Nếu bạn thường xuyên tiếp cận giới hạn đã tài liệu, yêu cầu quyền truy cập hoặc liên hệ qua kênh chính thức của Polymarket (Builder Program là con đường cho tích hợp khối lượng lớn và attribution).

Ảnh hưởng tới phát triển và triển khai của bạn

Nếu bạn xây bot giao dịch hoặc dịch vụ phân tích, lên kế hoạch cho luồng dữ liệu nhiều lớp: một lần fetch khối lượng lớn từ Gamma với limit lớn, sau đó đăng ký WebSocket để cập nhật trực tiếp, và một tập hợp nhỏ các poll định kỳ tới Gamma (có cache) cho metadata không có trong feed WS. Triển khai giới hạn phía client, gộp yêu cầu và phân trang theo cursor để tránh chạm giới hạn 300 req / 10 s cho /markets và các giới hạn danh sách kết hợp cũng như giới hạn tổng thể của Gamma.

Tóm tắt kết thúc

Giới hạn tốc độ API của Polymarket được nêu rõ cho các bề mặt liệt kê của Gamma và Market WS cung cấp một lựa chọn mở rộng cho feed trực tiếp. Thiết kế xung quanh phân trang theo cursor (after_cursor), sử dụng limit một cách chiến lược và ưu tiên WebSockets cho dữ liệu tần suất cao. Tuân theo các mẫu này sẽ giảm tình trạng bị điều chỉnh băng thông và làm cho tích hợp của bạn đáng tin cậy hơn.

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

Giới hạn /markets trên Gamma là bao nhiêu?

Endpoint /markets của Gamma bị giới hạn ở 300 requests mỗi 10 giây. Sử dụng limit (tối đa 1000) và phân trang theo cursor qua after_cursor. Đừng dùng offset—API sẽ từ chối với HTTP 422.

Có giới hạn kết hợp cho các endpoint của Gamma không?

Có. Các cuộc gọi liệt kê tới /markets và /events chia sẻ giới hạn kết hợp 900 requests mỗi 10 giây. Ngoài ra, toàn bộ bề mặt API của Gamma bị giới hạn 4000 requests mỗi 10 giây.

Tôi nên polling Gamma hay dùng WebSocket cho cập nhật trực tiếp?

Ưu tiên Market WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market) cho cập nhật sổ lệnh và giá trực tiếp—nó hiệu quả hơn và tránh polling lặp đi lặp lại. Dùng Gamma cho metadata thay đổi chậm hơn và đồng bộ khối lượng lớn ban đầu.

Client của tôi nên làm gì khi nhận HTTP 429?

Xử lý 429 như tín hiệu dừng polling mạnh mẽ. Triển khai lùi dần mũ với jitter, giảm concurrency và gộp các yêu cầu giống nhau. Theo dõi 429 để điều chỉnh bộ giới hạn tỉ lệ động.

API CLOB có yêu cầu xác thực không?

Các truy vấn đọc CLOB là công khai. Các thao tác giao dịch trên CLOB yêu cầu API key cộng HMAC để xác thực. Tôn trọng giới hạn giao dịch và ưu tiên feed WS cho cập nhật sổ lệnh.