Polymarket Relayer Client 教學
使用 TypeScript 的實作示範：安裝、錢包處理、常見流程（授權、split/merge）、以及無 gas 整合的實務建議。
Polymarket Relayer Client 教學
本指南示範如何在 TypeScript 中使用 Polymarket Relayer Client 建構無 gas 流程：錢包部署、ERC-20 授權管理、CTF 的 split/merge/redeem 操作，以及在 CLOB 上下單。如果你要在 Polymarket 做一個可用且無 gas 的整合，Polymarket Relayer Client 是開發者首選的 SDK。
重點摘要
- Polymarket Relayer Client 提供 TypeScript 與 Python SDK，處理錢包部署、授權、CTF 操作，以及透過 Polymarket Relayer 的下單流程。
- 對最終使用者而言，Polymarket 交易是無 gas 的：Relayer 贊助 gas，並抽象化錢包部署與授權流程。
- 常見流程為：錢包上線 → 檢查/請求授權 → split（鑄造完整一組 outcome 代幣）→ 下單（limit 或 FAK）→ 在決議後 merge/redeem。
- 永遠要為決議與結算風險設計：UMA 爭議、部分成交/滑點與時間風險都是真實存在的考量。
本指南適合誰
你是正在建構整合、交易機器人或放置交易的 UX 元件，會與 Polymarket 的 CLOB 與 CTF 互動的開發者。你應該熟悉 TypeScript、EVM 錢包（MetaMask、Rabby 等）與基本的 web3 概念。
SDK 涵蓋內容概覽
- 錢包上線：在首次使用時部署 Proxy 錢包，或在可用時使用預先部署的 Gnosis Safe。
- ERC-20 授權管理：處理 pUSD 與其他在 split/merge 中使用的代幣授權。
- CTF 操作：split、merge、redeem outcome 代幣（ERC-1155）。
- 透過 Relayer 向 CLOB 下單與取消訂單。
- 當你以 Builder 身份操作時，處理 Builder 歸因 header（參見 Builder Program 文件）。
注意：Polymarket 在 Polygon（chain ID 137）上運行，交易的結算資產為 pUSD（Polymarket 的包裝 USDC）。所有使用者交易皆透過 Relayer 無 gas 處理。
安裝與第一步
安裝 TypeScript 套件與常見的 web3 provider 套件。套件名稱會隨版本變動；以下範例使用 Relayer SDK 常見的匯入路徑。若專案中套件名稱不同，請參閱 SDK README。
Shell
npm install @polymarket/relayer-client ethers
基本初始化（TypeScript）
import { RelayerClient } from '@polymarket/relayer-client';
import { ethers } from 'ethers';
// 使用瀏覽器暴露的錢包 provider（MetaMask、Rabby 等）
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)
});
上例說明：RelayerClient 的建構子與選項物件為示意。請查看 SDK README 以取得正確的建構子簽名與可用選項。
上線流程：錢包部署與授權
Polymarket 支援兩種錢包模式：預先部署的 Gnosis Safe，以及在首次交易時自動部署的 Proxy 錢包。Relayer SDK 處理這兩種流程並贊助部署 gas。
你在 UX 中應實作的常見上線步驟：
- 檢測使用者是否已有 Proxy 或 Safe。若沒有，呼叫 SDK 的首次使用部署助手。
- 確認使用者錢包內有 pUSD。若沒有，指示如何橋接或存入（參閱 Polymarket 的資金指南）。
- 檢查 pUSD 的 ERC-20 授權狀態，必要時透過 Relayer 提示使用者進行免 gas 的授權。
範例：檢查並請求授權（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);
}
因為 Relayer 贊助 gas，授權呼叫是透過 Relayer 傳送，而不是使用者直接簽署一筆需支付 gas 的 on-chain 交易。
CTF 流程：split、merge、redeem
Conditional Token Framework（CTF）是 Polymarket 表示結果（ERC-1155 代幣）的方式。當你想買入完整一組時，典型順序如下：
- split：燒掉 pUSD 並鑄造完整一組 outcome 代幣
- 交易後，merge：把剩餘的 outcome 代幣合回共同持倉
- redeem：在決議後，燒掉贏的 outcome 代幣以換取每枚 $1.00
範例 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 會處理必要的授權與 relayer 提交。split 之後，你會在使用者的 Proxy 或 Safe 中收到 ERC-1155 outcome 代幣。
在 CLOB 上下單
CLOB 提供下單與檢視 orderbook 的介面。Relayer Client 會將下單流程透過 Relayer 路由，並在你為 Builder 時處理歸因 header。
重要的訂單類型：
- Limit 訂單：掛在書上，有機會成為 maker（maker 費用為零）。
- Market 訂單（FAK）：SDK 提供的 helper 可建立 FAK 訂單，會立即執行或取消。
範例：下 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);
若你以 Builder 身份操作，請包含歸因 header 或按 SDK 要求加入 builder 憑證。Builder Program 提供分級的 relayer 使用限額與獎勵；在 https://polymarket.com/settings 取得憑證。
讀取市況資料與 WebSocket
對於非交易的讀取，使用 Polymarket 的公開 REST 與 WebSocket 介面：
- 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
當訂閱 market WS 時，請要求 custom_feature_enabled: true 以接收 best_bid_ask 事件，並限制每個連線最多 500 個 instrument。
錯誤處理與常見陷阱
- 部分成交：市價單（FAK）可能會部分成交。務必檢查結果並處理剩餘部位。
- 滑點：對於激進的市價單，使用滑點限制保護。SDK 常在市價 helper 中暴露滑點設定。
- 決議與結算時序：UMA 爭議可能會暫停結算。請在 UI 與帳務中反映未結算資金，直到 redeem 完成。
- tick size 變動：在價格極端區間，tick size 會從 $0.01 調整為 $0.001；處理來自 WebSocket 的 tick_size_change 事件。
測試策略
- 端到端沙盒：完整測試上線流程 — 部署 Proxy 錢包、請求授權、split、下單，然後 merge/redeem。
- 封裝函式的單元測試：模擬 relayer 方法以斷言正確的授權與 split 順序。
- 注意速率限制：Gamma /markets 有速率限制（/markets 為 300 req / 10 s）— 批次與快取讀取結果。
這對你的交易或機器人邏輯有何影響
使用 Polymarket Relayer Client 可以移除為最終使用者管理 gas 的需要，並透過自動化 Proxy 部署與授權簡化上線流程。對於機器人而言，這讓你能把重心放在策略與市況資料：SDK 減少了執行 split/merge 與下單的整合表面。然而，你仍必須處理非執行風險，例如滑點、部分成交與預言機爭議。
參考與後續步驟
- Polymarket API 基礎 URL：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
- Builder Program 詳情與憑證請見 https://polymarket.com/settings
結語：Polymarket 透過 Relayer 贊助 gas，並提供 TypeScript 與 Python SDK 以簡化典型的錢包與 CTF 工作流程。Polymarket Relayer Client 是建立與 CLOB 和 CTF 互動的無 gas 整合的推薦路徑。
常見問題
什麼是 Polymarket Relayer Client？
Polymarket Relayer Client 是一組 SDK（TypeScript 與 Python），會將使用者交易透過 Polymarket 的 Relayer 路由，處理錢包部署、ERC-20 授權、CTF 操作與下單，使最終使用者能體驗到無 gas 的交易流程。
使用者還需要 pUSD 嗎？
需要。Polymarket 的結算資產是 pUSD（包裝的 USDC）。Relayer 贊助 gas，但使用者必須持有 pUSD 以執行 split 操作與下單。
我可以透過 Relayer Client 以 Builder 身份操作嗎？
可以。Builder Program 允許第三方在路由訂單時包含歸因 header 並賺取 builder 費用。在 https://polymarket.com/settings 取得憑證，並按 SDK 要求加入 builder header。
Relayer Client 會自動處理授權與錢包部署嗎？
SDK 提供在首次使用時自動部署 Proxy 錢包的 helper，以及透過 Relayer 請求免 gas ERC-20 授權的工具，簡化上線流程。
我在哪裡可以閱讀即時 orderbook 更新？
訂閱 Market WebSocket：wss://ws-subscriptions-clob.polymarket.com/ws/market。請求 custom_feature_enabled: true 以接收 best_bid_ask 事件，並留意每個連線 500 個 instrument 的限制。
參考術語
相關指南
僅作教育用途。非財務、法律或稅務建議。Polymarket 可能在你的司法管轄區無法使用。