Thị trường dự đoán là một trong những lĩnh vực đòi hỏi kỹ thuật cao nhất để xây dựng API. Bạn phải đối phó với các công cụ tài chính có thời hạn, các xác suất được định giá theo thời gian thực, các sự kiện đa kết quả với các mối quan hệ vốn phức tạp, và một cơ sở người dùng bao gồm cả con người nhấp chuột vào giao diện người dùng và các bot giao dịch tự động chạy chiến lược kinh doanh chênh lệch giá. Mọi quyết định thiết kế đều được kiểm tra căng thẳng ngay lập tức.
Polymarket, hiện là nền tảng thị trường dự đoán lớn nhất thế giới xét về khối lượng, đã xây dựng một hệ sinh thái API đáng để nghiên cứu chính vì lý do này. Đây không chỉ là một API CRUD trên một cơ sở dữ liệu. Đó là một kiến trúc phân lớp được thiết kế cẩn thận để xử lý sự căng thẳng cơ bản giữa tính mở và bảo mật, giữa dữ liệu thời gian thực và dữ liệu lịch sử, và giữa các mô hình tài chính truyền thống với các nguyên thủy gốc crypto.
Dưới đây là tám mẫu thiết kế đáng để học hỏi từ cách họ đã làm.
Mẫu 1: Các lớp API phân tách theo miền nghiệp vụ
Polymarket cung cấp ba API riêng biệt, mỗi API có một miền nghiệp vụ rõ ràng:
- Gamma API (
gamma-api.polymarket.com) — khám phá thị trường, sự kiện, thẻ, tìm kiếm - CLOB API (
clob.polymarket.com) — dữ liệu sổ lệnh, định giá, đặt lệnh - Data API (
data-api.polymarket.com) — vị thế người dùng, giao dịch, phân tích, bảng xếp hạng
Đây không chỉ là một quy ước đặt tên — mỗi API có các yêu cầu xác thực khác nhau, tần suất cập nhật khác nhau và hồ sơ người dùng khác nhau. Gamma API hoàn toàn công khai, được tối ưu hóa cho việc duyệt và khám phá. CLOB API có cả điểm cuối công khai (bất kỳ ai cũng có thể đọc sổ lệnh) và điểm cuối có xác thực (giao dịch yêu cầu thông tin đăng nhập). Data API công khai nhưng được định danh bằng địa chỉ ví — bạn truy vấn vị thế theo địa chỉ người dùng.
Bài học thiết kế ở đây là việc phân tách theo miền nghiệp vụ thay vì theo thực thể tạo ra các API mạch lạc hơn. Một cách tiếp cận đơn giản có thể sẽ gộp /markets, /orders, /users tất cả dưới một mái nhà. Thay vào đó, Polymarket đặt câu hỏi: "API này dùng để làm gì?" và sau đó xây dựng xung quanh câu hỏi đó. Khám phá có các mẫu truy cập khác với giao dịch. Giao dịch có các yêu cầu độ trễ khác với phân tích. Việc mỗi API có URL cơ sở riêng có nghĩa là mỗi API có thể phát triển, mở rộng quy mô và xác thực độc lập.
Mẫu 2: Truy cập dữ liệu công khai là ưu tiên hàng đầu
Mọi thứ về dữ liệu thị trường — giá cả, sổ lệnh, siêu dữ liệu sự kiện, giao dịch lịch sử — đều hoàn toàn công khai:
curl "https://gamma-api.polymarket.com/events?limit=5"
Không cần khóa API. Không cần OAuth. Không có giới hạn tần suất trên các điểm cuối đọc. Bạn có được dữ liệu.
Đây là một lựa chọn có chủ đích mà hầu hết các nền tảng tài chính không thực hiện. Các sàn giao dịch truyền thống bảo vệ dữ liệu thị trường như một nguồn doanh thu. Polymarket coi đó là cơ sở hạ tầng — càng nhiều người có thể đọc và xây dựng dựa trên dữ liệu, thị trường càng trở nên thanh khoản và hữu ích hơn. Đó là logic hàng hóa công áp dụng cho một API.
Hệ quả thực tế đối với các nhà thiết kế API đáng được lưu ý: việc coi quyền đọc và quyền ghi là mối quan tâm hàng đầu và tách biệt chúng, thay vì áp dụng xác thực đồng nhất, gần như luôn là lựa chọn đúng đắn cho các nền tảng nơi lượng tiêu thụ dữ liệu vượt xa lượng sản xuất dữ liệu. Nếu người dùng có thể đọc giá thị trường mà không cần thông tin đăng nhập, bạn đã loại bỏ trở ngại cho 95% đối tượng tiềm năng của mình. Bạn chỉ tạo trở ngại tại điểm thực sự quan trọng — khi họ muốn đặt một lệnh thực.
Mẫu 3: Xác thực hai cấp độ phản ánh sự tin cậy thực tế
Các điểm cuối giao dịch yêu cầu xác thực, nhưng mô hình xác thực của Polymarket có một cấu trúc mà hầu hết các nhà thiết kế API chưa từng thấy: hai cấp độ với các mục đích riêng biệt.
Xác thực cấp 1 (L1) sử dụng chữ ký EIP-712 từ khóa riêng của người dùng. Nó chứng minh quyền sở hữu ví. Bạn sử dụng nó chính xác một lần (hoặc không thường xuyên) để tạo thông tin xác thực API:
// L1: Sử dụng khóa riêng của bạn để tạo thông tin xác thực API
const credentials = await client.createOrDeriveApiKey();
// → { key: "...", secret: "...", passphrase: "..." }
Xác thực cấp 2 (L2) sử dụng HMAC-SHA256 với các thông tin xác thực đã tạo đó. Đây là thứ bạn đính kèm vào mọi yêu cầu giao dịch:
// Tiêu đề L2 trên mọi yêu cầu giao dịch
{
"POLY_ADDRESS": "0x...",
"POLY_SIGNATURE": "<hmac-sha256>",
"POLY_TIMESTAMP": "1716000000",
"POLY_API_KEY": "550e8400-...",
"POLY_PASSPHRASE": "..."
}
Điều quan trọng là các hoạt động khác nhau xứng đáng có các nghi thức bảo mật khác nhau. Việc tạo khóa API yêu cầu chứng minh quyền kiểm soát ví — đó là một hành động có rủi ro cao đòi hỏi một chữ ký mật mã từ khóa riêng. Nhưng một khi bạn đã thiết lập sự tin cậy đó, các yêu cầu giao dịch thông thường không nên yêu cầu ký lại bằng khóa riêng của bạn trên mỗi lần gọi. Thông tin xác thực L2 đủ nhẹ để sử dụng tần suất cao trong khi vẫn gắn với danh tính L1.
Mẫu này áp dụng tốt ngoài lĩnh vực tiền mã hóa: hãy nghĩ về nó như sự khác biệt giữa "chứng minh bạn là người này" (L1, thực hiện không thường xuyên với thông tin xác thực mạnh nhất hiện có) và "chứng minh yêu cầu này đến từ bạn" (L2, thực hiện liên tục với thông tin xác thực phiên). Hầu hết các ứng dụng web gộp chúng vào một luồng xác thực và mất đi sự tinh tế về bảo mật.
Mẫu 4: Lệnh dưới dạng tin nhắn đã ký, không phải lệnh gọi API
Đây là điểm mà thị trường dự đoán khác biệt rõ rệt nhất so với thiết kế API thông thường. Khi bạn đặt một lệnh trên Polymarket, bạn không chỉ gửi dữ liệu đến một máy chủ — bạn đang tạo một tin nhắn được ký mật mã, đó là một cam kết tài chính có thể thực thi:
const response = await client.createAndPostOrder(
{
tokenID: "71321045679...",
price: 0.65,
size: 100,
side: Side.BUY,
},
{
tickSize: "0.01",
negRisk: false,
},
OrderType.GTC
);
Bên dưới, SDK xây dựng một cấu trúc dữ liệu dạng EIP-712, ký nó bằng khóa riêng của bạn và gửi chữ ký cùng với lệnh. Công cụ khớp lệnh hoạt động ngoài chuỗi, nhưng khi các giao dịch được khớp, chúng sẽ được thanh toán trên chuỗi thông qua Polygon bằng cách sử dụng các chữ ký đó. Nhà điều hành không thể giả mạo giao dịch hoặc chuyển tiền — tin nhắn đã ký là ủy quyền.
Điều này thay đổi ngữ nghĩa của một "lệnh gọi API". Thông thường, việc gửi đến một điểm cuối có nghĩa là "vui lòng thực hiện điều này thay mặt tôi." Ở đây, việc gửi một lệnh có nghĩa là "đây là một công cụ đã ký ủy quyền giao dịch này." API không phải là một trung gian đưa ra quyết định — nó là một bộ chuyển tiếp cho các tin nhắn tự ủy quyền bằng mật mã.
Đối với các nhà thiết kế API ngoài không gian tiền mã hóa, bài học rút ra là: khi bản thân payload có thể mang theo ủy quyền thay vì dựa hoàn toàn vào thông tin xác thực lớp vận chuyển, bạn sẽ có được khả năng không thể phủ nhận và khả năng xác minh một cách miễn phí. Các hệ thống tài chính, tài liệu pháp lý và các hoạt động có rủi ro cao đều là những ứng cử viên cho mẫu này.
Mẫu 5: Tri thức luận rõ ràng trong mô hình dữ liệu
Polymarket cấu trúc dữ liệu của mình xung quanh hai đối tượng: Sự kiện (Events) và Thị trường (Markets). Sự khác biệt là quan trọng.
Một Sự kiện là một câu hỏi: "Ai sẽ thắng cuộc đua Thượng viện Hoa Kỳ năm 2026 tại Pennsylvania?" Nó có tiêu đề, một danh mục, một ngày giải quyết. Một Thị trường là một kết quả nhị phân có thể giao dịch cụ thể trong sự kiện đó: "Liệu Bob Casey có thắng không?" Một sự kiện có thể chứa nhiều thị trường.
{
"id": "501",
"title": "Cuộc đua Thượng viện Pennsylvania 2026",
"negRisk": true,
"markets": [
{ "id": "2301", "question": "Liệu Bob Casey có thắng không?", "outcomePrices": "[\"0.42\", \"0.58\"]" },
{ "id": "2302", "question": "Liệu Dave McCormick có thắng không?", "outcomePrices": "[\"0.35\", \"0.65\"]" },
{ "id": "2303", "question": "Liệu một ứng cử viên thứ ba có thắng không?", "outcomePrices": "[\"0.23\", \"0.77\"]" }
]
}
Đây là tri thức luận rõ ràng — API không chỉ lưu trữ dữ liệu, nó còn mã hóa các mối quan hệ khái niệm giữa các thực thể. Giá được biểu thị dưới dạng các mảng song song trong đó vị trí chỉ mục là quy ước ràng buộc: outcomes[0] tương ứng với outcomePrices[0]. Cờ negRisk ở cấp độ sự kiện báo hiệu rằng các thị trường bên trong nó có các mối quan hệ vốn không tồn tại trong các thị trường độc lập.
Hầu hết các API làm phẳng các mối quan hệ này. Polymarket đưa chúng lên bề mặt vì chúng rất quan trọng đối với cách hệ thống hoạt động. Nếu bạn đang xây dựng một bot giao dịch tự động và bạn bỏ qua negRisk: true, bạn sẽ xây dựng mô hình vị thế sai và có khả năng mất tiền. Thiết kế API làm cho cấu trúc khái niệm hiển thị để việc bỏ qua nó là một lựa chọn có ý thức, không phải là mặc định thầm lặng.
Mẫu 6: NegRisk — Mối quan hệ vốn là mối quan tâm hàng đầu
Cờ negRisk trên các sự kiện chỉ ra một trong những mẫu thiết kế API thú vị nhất của Polymarket: làm cho các tương đương tài chính có thể lập trình.
Trong một sự kiện đa kết quả tiêu chuẩn, mỗi thị trường là độc lập. Nhưng trong một sự kiện NegRisk, nơi chỉ có đúng một kết quả có thể thắng, một mối quan hệ toán học tồn tại giữa các vị thế:
1 Mã thông báo "Không" cho kết quả A ≡ 1 Mã thông báo "Có" cho mọi kết quả khác
Đây không chỉ là toán học — nó được triển khai trong hợp đồng thông minh và hiển thị thông qua API. Khi bạn giữ vị thế "Không" trên "Khác" trong cuộc đua Thượng viện Pennsylvania, bạn có thể chuyển đổi nó:
| Trước | Sau |
|---|---|
| 1× Không (Khác) | 1× Có (Casey) + 1× Có (McCormick) |
API làm cho điều này rõ ràng: negRisk: true trong đối tượng thị trường, và negRisk: true được yêu cầu trong các tùy chọn lệnh của bạn khi giao dịch các thị trường này. Nếu bạn hiểu sai, lệnh của bạn sẽ bị từ chối hoặc thanh toán không chính xác.
Mẫu thiết kế ở đây là mã hóa các bất biến miền nghiệp vụ thành các trường API có kiểu thay vì để chúng làm ghi chú trong tài liệu. Cờ NegRisk không tồn tại vì nó tiện lợi — nó tồn tại vì việc bỏ qua nó sẽ gây ra hành vi không chính xác. Khi miền nghiệp vụ của bạn có các ràng buộc cứng (chỉ một kết quả có thể thắng, các vị thế có các tương đương chuyển đổi), những ràng buộc đó nên xuất hiện trên bề mặt API, không chỉ trong tài liệu.
Mẫu 7: Kích thước bước giá động như trạng thái thị trường
Hầu hết các API tài chính coi kích thước bước giá là một cấu hình tĩnh. Polymarket làm một điều thú vị hơn: kích thước bước giá thay đổi động dựa trên giá thị trường, và API phơi bày điều này dưới dạng một luồng sự kiện thời gian thực.
Khi giá của một thị trường tiếp cận các thái cực (trên 0.96 hoặc dưới 0.04), kích thước bước giá tối thiểu thu hẹp từ 0.01 xuống 0.001:
{
"event_type": "tick_size_change",
"asset_id": "65818619657...",
"old_tick_size": "0.01",
"new_tick_size": "0.001",
"timestamp": "100000000"
}
Lý do là trực quan: tại các xác suất cực đoan, một bước giá 1 xu đại diện cho một thay đổi 25% (từ 0.04 đến 0.03). Điều đó quá thô để khám phá giá có ý nghĩa. Các bước giá nhỏ hơn gần các thái cực cho phép thị trường thể hiện các xác suất như 97.3% thay vì làm tròn đến 97%.
Điều làm cho điều này đáng chú ý như một lựa chọn thiết kế API là kích thước bước giá không phải là một tham số bạn lấy một lần — đó là một trạng thái thay đổi và phải được theo dõi. WebSocket phơi bày các sự kiện tick_size_change chính xác để khách hàng có thể giữ logic xây dựng lệnh của họ nhất quán với trạng thái thị trường hiện tại. Nếu bạn mã hóa cứng kích thước bước giá và bỏ lỡ sự kiện này, lệnh của bạn sẽ bị từ chối.
Điều này phản ánh một nguyên tắc rộng hơn: thiết kế API cho các hệ thống tài chính phải coi trạng thái là một khái niệm hạng nhất. Các tham số thị trường không tĩnh. Các quy tắc giải quyết thay đổi. Các kết quả được làm rõ. API cần truyền đạt rõ ràng các chuyển đổi trạng thái này, không để khách hàng tự khám phá chúng thông qua các yêu cầu bị từ chối.
Mẫu 8: Hai lớp WebSocket cho các hồ sơ người dùng khác nhau
Polymarket chạy hai hệ thống WebSocket riêng biệt, và việc hiểu lý do tại sao lại cho thấy một mẫu về phân khúc đối tượng.
Kênh Thị trường (Market Channel) (wss://ws-subscriptions-clob.polymarket.com/ws/market) được xây dựng cho người tiêu dùng giao dịch. Đăng ký theo ID mã thông báo, nhận các ảnh chụp nhanh sổ lệnh, thay đổi giá, thực hiện giao dịch và thay đổi kích thước bước giá. Mọi thứ được gắn với ID tài sản và tối ưu hóa cho việc xây dựng lệnh với độ trễ thấp:
{
"assets_ids": ["65818619657568813474341868652308942079804919287380422192892211131408793125422"],
"type": "market"
}
Socket Dữ liệu Thời gian thực (Real-Time Data Socket) (wss://ws-live-data.polymarket.com) được xây dựng cho một hồ sơ hoàn toàn khác. Nó truyền tải bình luận, giá tiền mã hóa từ Binance và Chainlink, giá cổ phiếu và các sự kiện tương tác xã hội. Đăng ký theo chủ đề:
{
"action": "subscribe",
"subscriptions": [
{ "topic": "crypto_prices", "type": "update", "filters": "btcusdt,ethusd" }
]
}
Hai hệ thống này phục vụ các đối tượng có nhu cầu cơ bản khác nhau. Một nhà tạo lập thị trường cần các delta sổ lệnh liên quan đến micro giây. Một giao diện người dùng hiển thị "điều gì đang xảy ra trên Polymarket ngay bây giờ" cần nguồn cấp dữ liệu bình luận và hoạt động xã hội. Việc kết hợp chúng có nghĩa là một là thiết kế quá mức nguồn cấp dữ liệu xã hội với yêu cầu độ trễ cấp độ giao dịch, hai là thiết kế dưới mức nguồn cấp dữ liệu sổ lệnh với giả định độ tin cậy cấp độ xã hội.
Bài học đơn giản nhưng thường bị bỏ qua: khi người tiêu dùng thời gian thực của bạn có dung sai độ trễ, khối lượng dữ liệu và chế độ lỗi khác nhau đáng kể, hãy cung cấp cho họ cơ sở hạ tầng riêng biệt. Các điểm cuối WebSocket được chia sẻ cố gắng phục vụ nhiều mục đích có xu hướng sụp đổ về mức độ phức tạp cao nhất và hiệu suất thấp nhất.
Những điểm chung của các mẫu này
Thiết kế API của Polymarket phản ánh một triết lý cụ thể: API nên làm cho cấu trúc thực tế của miền nghiệp vụ hiển thị, không trừu tượng hóa nó.
Kiến trúc ba lớp ánh xạ tới các ranh giới miền nghiệp vụ thực tế. Việc truy cập ưu tiên công khai phản ánh cách thức hoạt động của giá trị thị trường dự đoán. Xác thực hai cấp độ phản ánh sự khác biệt thực tế giữa việc chứng minh danh tính và ủy quyền một hành động. Các lệnh dưới dạng tin nhắn đã ký mã hóa đảm bảo không lưu ký. Hệ thống phân cấp Sự kiện/Thị trường và cờ NegRisk phơi bày các mối quan hệ mà nếu không thì sẽ vô hình. Kích thước bước giá động giữ trạng thái khách hàng nhất quán với trạng thái thị trường. Các lớp WebSocket riêng biệt phục vụ các đối tượng riêng biệt.
Hầu hết lời khuyên thiết kế API tập trung vào tính công thái học: làm cho nó dễ gọi, nhất quán trong cách đặt tên, dễ đoán trong xử lý lỗi. API của Polymarket làm được tất cả những điều đó — nhưng những lựa chọn thú vị hơn là về sự trung thực với miền nghiệp vụ. Khi miền nghiệp vụ có một sự khác biệt có ý nghĩa, API làm nổi bật nó. Khi miền nghiệp vụ có một ràng buộc, API thực thi nó. Khi miền nghiệp vụ có một trạng thái thay đổi, API phát sóng nó.
Kết quả là một API đòi hỏi nhiều hơn từ người tiêu dùng của nó, nhưng một API mà việc làm đúng có nghĩa là bạn thực sự hiểu hệ thống bạn đang giao dịch. Đó không phải là ngẫu nhiên — đối với một thị trường dự đoán, nơi mục đích chính là giá cả phản ánh thông tin, một API buộc bạn phải hiểu cấu trúc của thị trường đang làm chính xác những gì nó nên làm.