Polymarket Relayer Client Tutorial

Hướng dẫn này trình bày cách sử dụng Polymarket Relayer Client trong TypeScript để xây dựng các luồng không tốn gas: triển khai ví, xử lý ERC-20 approval, thao tác CTF split/merge/redeem, và đặt lệnh trên CLOB. Nếu bạn muốn một tích hợp hoạt động không tốn gas với Polymarket, Polymarket Relayer Client là SDK dành cho nhà phát triển mà bạn sẽ dùng đầu tiên.

Những điểm chính

• Polymarket Relayer Client cung cấp SDK cho TypeScript và Python để xử lý triển khai ví, approvals, thao tác CTF và đặt lệnh thông qua Polymarket Relayer.
• Giao dịch trên Polymarket không tốn gas cho người dùng cuối: Relayer tài trợ gas và trừu tượng hóa việc triển khai ví và approvals.
• Các luồng phổ biến: onboarding ví → kiểm tra/phê duyệt approval → split (mint) một bộ outcome hoàn chỉnh → tạo lệnh (limit hoặc FAK) → merge/redeem sau khi resolution.
• Luôn thiết kế để xử lý rủi ro resolution và settlement: tranh chấp UMA, fills không đầy/độ trượt giá, và thời gian là những yếu tố thực tế.

Ai nên đọc hướng dẫn này

Bạn là nhà phát triển xây dựng tích hợp, bot, hoặc thành phần UX đặt lệnh trên CLOB của Polymarket và tương tác với CTF. Bạn nên thành thạo TypeScript, ví EVM (MetaMask, Rabby, v.v.), và các khái niệm web3 cơ bản.

Tổng quan nhanh về phạm vi của SDK

• Onboarding ví: triển khai Proxy wallets khi dùng lần đầu hoặc dùng Gnosis Safe nếu có.
• Quản lý ERC-20 approvals cho pUSD và các token khác dùng trong split/merge.
• Thao tác CTF: split, merge, redeem các outcome token (ERC-1155).
• Đặt lệnh và hủy lệnh trên CLOB thông qua Relayer.
• Header attribution cho Builder khi bạn hoạt động như Builder (xem tài liệu Builder Program).

Lưu ý: Polymarket chạy trên Polygon (chain ID 137), và tài sản thanh toán cho giao dịch là pUSD (wrapped USDC của Polymarket). Tất cả giao dịch người dùng được miễn phí gas thông qua Relayer.

Cài đặt và bước đầu

Cài đặt package TypeScript và một package provider web3 tiêu chuẩn. Tên package chính xác có thể thay đổi theo phiên bản; ví dụ dưới dùng đường dẫn import chuẩn thường thấy trong các relayer SDK. Nếu tên package khác trong dự án của bạn, hãy tham khảo README của SDK.

Shell

npm install @polymarket/relayer-client ethers

Khởi tạo cơ bản (TypeScript)

import { RelayerClient } from '@polymarket/relayer-client';
import { ethers } from 'ethers';

// Use a wallet provider exposed in the browser (MetaMask, Rabby, etc.)
const provider = new ethers.providers.Web3Provider((window as any).ethereum);
const signer = provider.getSigner();

const relayer = new RelayerClient({
  signer,
  network: 'polygon', // Polymarket runs on Polygon (chainId 137)
});

Ghi chú về ví dụ trên: constructor của RelayerClient và object options mang tính minh họa. Kiểm tra README của SDK để biết chữ ký constructor và các tùy chọn chính xác.

Onboarding: triển khai ví và approvals

Polymarket hỗ trợ hai mô hình ví: Gnosis Safe đã được tiền-triển khai và Proxy wallets được tự động triển khai khi thực hiện giao dịch đầu tiên. Relayer SDK xử lý cả hai luồng và tài trợ gas cho việc triển khai.

Các bước onboarding phổ biến bạn nên triển khai trong UX:

1. Phát hiện xem người dùng đã có Proxy hoặc Safe chưa. Nếu chưa, gọi helper deploy-on-first-use của SDK.
2. Đảm bảo người dùng có pUSD trong ví. Nếu không, hướng dẫn họ cách bridge hoặc nạp tiền (xem hướng dẫn nạp tiền của Polymarket).
3. Kiểm tra trạng thái ERC-20 approval cho pUSD và yêu cầu phê duyệt không tốn gas qua Relayer nếu cần.

Ví dụ: kiểm tra & yêu cầu approval (TypeScript)

// Pseudocode — adapt to SDK methods
const pUsdAddress = '0x...'; // use SDK constant if provided
const allowance = await relayer.checkAllowance(pUsdAddress);
if (allowance.lt(requiredAmount)) {
  await relayer.requestApproval(pUsdAddress, requiredAmount);
}

Vì Relayer tài trợ gas, cuộc gọi approval được gửi qua Relayer thay vì người dùng ký một giao dịch gas trực tiếp trên-chain.

Luồng CTF: split, merge, redeem

Conditional Token Framework (CTF) là cách Polymarket biểu diễn các outcome (ERC-1155 tokens). Thứ tự điển hình khi bạn muốn mua một bộ hoàn chỉnh:

• split: burn pUSD và mint một bộ outcome tokens hoàn chỉnh
• sau khi giao dịch, merge: chuyển các outcome token dư thừa về một vị thế chung
• redeem: sau resolution, burn token outcome thắng để lấy $1.00 mỗi token

Ví dụ split (TypeScript)

// Pseudocode using the Relayer SDK
const conditionId = '0x...';
const amount = ethers.utils.parseUnits('1.0', 6); // pUSD has 6 decimals
await relayer.split(conditionId, amount);

SDK sẽ xử lý approvals cần thiết và gửi qua relayer. Sau split, bạn sẽ nhận được ERC-1155 outcome tokens trong Proxy hoặc Safe của người dùng.

Đặt lệnh trên CLOB

CLOB cung cấp API để đặt lệnh và đọc orderbook. Relayer Client định tuyến việc đặt lệnh qua Relayer, xử lý header attribution nếu bạn là Builder.

Các loại lệnh quan trọng:

• Limit orders: post lên book và có thể nằm đó như maker (maker fees bằng không).
• Market orders (FAK): SDK cung cấp helper để tạo FAK orders thực thi ngay hoặc hủy.

Ví dụ: đặt lệnh market FAK (TypeScript)

// Conceptual example
const instrumentId = 'POLY_MARKET_INSTRUMENT_ID';
const side = 'buy';
const size = ethers.utils.parseUnits('10', 6);

const result = await relayer.createMarketOrder({
  instrumentId,
  side,
  size,
  slippageTolerance: 0.01, // 1% slippage protection
});

console.log('fill result', result);

Nếu bạn hoạt động như Builder, hãy đính kèm attribution headers hoặc chứng thực builder theo yêu cầu của Builder Program. Builder Program cung cấp hạn mức relayer theo tầng và phần thưởng; lấy thông tin đăng nhập tại https://polymarket.com/settings.

Đọc dữ liệu thị trường & WebSocket

Với việc đọc không giao dịch, sử dụng các bề mặt REST và WebSocket công khai của Polymarket:

• Gamma API: https://gamma-api.polymarket.com (markets, events)
• Data API: https://data-api.polymarket.com (positions, trades, open interest)
• CLOB API: https://clob.polymarket.com (orderbook and order placement APIs)
• Market WebSocket: wss://ws-subscriptions-clob.polymarket.com/ws/market for real-time book updates

Khi đăng ký feed WS thị trường, yêu cầu custom_feature_enabled: true để nhận sự kiện best_bid_ask và giới hạn đăng ký tối đa 500 instruments mỗi kết nối.

Xử lý lỗi và các lỗi thường gặp

• Partial fills: market orders (FAK) có thể bị fill một phần. Luôn kiểm tra kết quả và xử lý phần còn lại.
• Slippage: bảo vệ lệnh thị trường mạnh bằng giới hạn slippage. SDK thường cung cấp thiết lập slippage trên các helper market.
• Thời gian resolution và settlement: tranh chấp UMA có thể tạm dừng settlement. Thiết kế UI và hạch toán để phản ánh quỹ chưa được settle cho tới khi redeem hoàn tất.
• Thay đổi tick size: tick size thay đổi từ $0.01 sang $0.001 khi giá tiến về vùng biên; xử lý sự kiện tick_size_change từ WebSocket.

Chiến lược kiểm thử

• End-to-end sandbox: kiểm tra toàn bộ onboarding — triển khai Proxy wallet, yêu cầu approval, split, đặt lệnh, và merge/redeem.
• Unit test các wrapper: mock các method của relayer để khẳng định chuỗi approval và split được gọi đúng.
• Nhận biết giới hạn tần suất: Gamma /markets có rate limit (300 req / 10 s cho /markets) — gom nhóm và cache các lần đọc.

Điều này ảnh hưởng thế nào đến logic giao dịch hoặc bot của bạn

Dùng Polymarket Relayer Client loại bỏ nhu cầu quản lý gas cho người dùng cuối và đơn giản hóa onboarding bằng cách tự động triển khai Proxy và approvals. Với bot, điều này cho phép bạn tập trung vào chiến lược và dữ liệu thị trường: SDK giảm diện tích tích hợp để thực hiện các luồng split/merge và đặt lệnh. Tuy nhiên, bạn vẫn phải xử lý các rủi ro không phải thực thi như slippage, partial fills, và tranh chấp oracle.

Tham khảo và bước tiếp theo

• Polymarket API base URLs: Gamma (https://gamma-api.polymarket.com), Data (https://data-api.polymarket.com), CLOB (https://clob.polymarket.com)
• Market WebSocket: wss://ws-subscriptions-clob.polymarket.com/ws/market
• Chi tiết Builder Program và thông tin đăng nhập tại https://polymarket.com/settings

Ghi chú kết: Polymarket tài trợ gas qua Relayer và cung cấp SDK TypeScript và Python để đơn giản hóa các luồng ví và CTF điển hình. Polymarket Relayer Client là con đường được khuyến nghị để xây dựng các tích hợp không tốn gas tương tác với CLOB và CTF.

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

Polymarket Relayer Client là gì?

Polymarket Relayer Client là SDK (TypeScript và Python) định tuyến giao dịch người dùng qua Polymarket Relayer, xử lý triển khai ví, ERC-20 approvals, thao tác CTF và đặt lệnh để người dùng trải nghiệm giao dịch không tốn gas.

Người dùng có vẫn cần pUSD để giao dịch không?

Có. Tài sản thanh toán của Polymarket là pUSD (wrapped USDC). Relayer tài trợ gas, nhưng người dùng phải giữ pUSD để thực hiện split và đặt lệnh.

Tôi có thể hoạt động như Builder thông qua Relayer Client không?

Có. Builder Program cho phép bên thứ ba định tuyến lệnh với header attribution và kiếm builder fees. Lấy thông tin đăng nhập tại https://polymarket.com/settings và đính kèm header builder theo yêu cầu của SDK.

Relayer Client xử lý approvals và triển khai ví tự động không?

SDK cung cấp helper cho triển khai Proxy wallet khi dùng lần đầu và yêu cầu approval ERC-20 không tốn gas qua Relayer, giúp đơn giản hóa onboarding.

Tôi có thể đọc cập nhật orderbook theo thời gian thực ở đâu?

Đăng ký Market WebSocket tại wss://ws-subscriptions-clob.polymarket.com/ws/market. Yêu cầu custom_feature_enabled: true để nhận sự kiện best_bid_ask và lưu ý giới hạn 500 instruments mỗi kết nối.