Polymarket Relayer Client Tutorial

เอกสารนี้อธิบายวิธีใช้ Polymarket Relayer Client ใน TypeScript เพื่อสร้างงานแบบ gasless: การเปิดกระเป๋า, การจัดการ ERC-20 approvals, การดำเนินการ CTF (split/merge/redeem) และการวางคำสั่งบน CLOB. หากคุณต้องการการรวมงานแบบใช้งานได้จริงที่ gasless กับ Polymarket, Polymarket Relayer Client คือ SDK ฝั่งนักพัฒนาที่ควรเริ่มใช้ก่อน.

Key takeaways

• Polymarket Relayer Client ให้ SDK ทั้ง TypeScript และ Python เพื่อจัดการการเปิดกระเป๋า, approvals, การดำเนินการ CTF, และการวางคำสั่งผ่าน Polymarket Relayer.
• ธุรกรรมบน Polymarket สำหรับผู้ใช้เป็นแบบ gasless: Relayer ออกค่าแก๊สและซ่อนความซับซ้อนของการเปิดกระเป๋าและการอนุมัติ.
• การไหลงานที่พบบ่อยคือ: การนำผู้ใช้มาใช้งาน (onboarding) → ตรวจสอบ/ขอการอนุมัติ → split (mint) ชุดผลลัพธ์ครบ → สร้างคำสั่ง (limit หรือ FAK) → merge/redeem หลังการ resolution.
• ออกแบบระบบโดยคำนึงถึงความเสี่ยงของการ resolution และการชำระเงินเสมอ: UMA disputes, การถูกเติมบางส่วน/slippage, และปัญหาเรื่องเวลา เป็นความเสี่ยงที่แท้จริง.

Who this guide is for

คู่มือนี้สำหรับนักพัฒนาที่สร้างการรวมระบบ, บอต หรือส่วนติดต่อผู้ใช้ที่วางคำสั่งบน CLOB ของ Polymarket และโต้ตอบกับ CTF. คุณควรคุ้นเคยกับ TypeScript, กระเป๋า EVM (MetaMask, Rabby, ฯลฯ) และแนวคิดพื้นฐานของ web3.

Quick overview of what the SDK covers

• การนำผู้ใช้เข้าระบบของกระเป๋า: เปิด Proxy wallets ในการใช้งานครั้งแรก หรือใช้ Gnosis Safe ถ้ามี.
• การจัดการ ERC-20 approvals สำหรับ pUSD และโทเค็นอื่นที่ใช้ใน split/merge.
• การดำเนินการ CTF: split, merge, redeem ของโทเค็นผลลัพธ์ (ERC-1155).
• การวางคำสั่งและยกเลิกคำสั่งกับ CLOB ผ่าน Relayer.
• หัวข้อการให้เครดิต Builder เมื่อคุณทำหน้าที่เป็น Builder (ดูเอกสาร Builder Program).

หมายเหตุ: Polymarket ใช้ Polygon (chain ID 137) และสินทรัพย์สำหรับการตั้งค่าการเทรดคือ pUSD (wrapped USDC ของ Polymarket). ธุรกรรมของผู้ใช้ทั้งหมดเป็นแบบ gasless ผ่าน Relayer.

Install and first steps

ติดตั้งแพ็กเกจ TypeScript และแพ็กเกจ web3 provider มาตรฐาน. ชื่อแพ็กเกจอาจต่างกันไปตามเวอร์ชัน; ตัวอย่างด้านล่างใช้เส้นทางการนำเข้าที่เป็นที่นิยมใน relayer SDKs. หากชื่อแพ็กเกจในโปรเจกต์ของคุณต่างออกไป ให้ดูใน README ของ SDK.

Shell

npm install @polymarket/relayer-client ethers

Basic initialization (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)
});

หมายเหตุเกี่ยวกับตัวอย่างด้านบน: ตัวสร้าง RelayerClient และออบเจ็กต์ options เป็นตัวอย่างเชิงประกอบ. ตรวจสอบ README ของ SDK สำหรับพารามิเตอร์ตัวสร้างและตัวเลือกที่แน่นอน.

Onboarding: wallet deployment and approvals

Polymarket รองรับสองรูปแบบกระเป๋า: Gnosis Safes ที่ถูกเปิดไว้ล่วงหน้า และ Proxy wallets ที่จะถูกเปิดอัตโนมัติเมื่อมีธุรกรรมครั้งแรก. Relayer SDK ดูแลทั้งสองไหลงานและออกค่าแก๊สสำหรับการเปิด.

ขั้นตอน onboarding ที่ควรนำไปใช้ใน UX:

1. ตรวจสอบว่าผู้ใช้มี Proxy หรือ Safe อยู่แล้วหรือไม่. หากไม่มี ให้เรียก helper ของ SDK เพื่อ deploy-on-first-use.
2. ตรวจสอบให้แน่ใจว่าผู้ใช้มี pUSD ในกระเป๋า. หากไม่มี ให้แนะนำวิธี bridge หรือฝาก (ดูคู่มือการเติมเงินของ Polymarket).
3. ตรวจสอบสถานะ ERC-20 approval สำหรับ pUSD และกระตุ้นการขออนุมัติแบบ gasless ผ่าน Relayer หากจำเป็น.

Example: check & request 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);
}

เพราะ Relayer ออกค่าแก๊ส การเรียกขออนุมัติจะถูกส่งผ่าน Relayer แทนที่ผู้ใช้จะเซ็นธุรกรรมแก๊สโดยตรงบนเครือข่าย.

CTF flows: split, merge, redeem

Conditional Token Framework (CTF) คือวิธีที่ Polymarket แสดงผลลัพธ์เป็นโทเค็น (ERC-1155). ลำดับทั่วไปเมื่อคุณต้องการซื้อชุดครบ:

• split: เบิร์น pUSD และ mint ชุดผลลัพธ์ครบ
• หลังการเทรด, merge: แปลงโทเค็นผลลัพธ์ที่เหลือกลับเป็นตำแหน่งร่วม
• redeem: หลัง resolution เบิร์นโทเค็นผลลัพธ์ที่ชนะเพื่อรับ $1.00 ต่อโทเค็น

Example 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 จะจัดการ approvals ที่จำเป็นและการส่งผ่าน relayer. หลัง split คุณจะได้รับโทเค็นผลลัพธ์ ERC-1155 ใน Proxy หรือ Safe ของผู้ใช้.

Placing orders on the CLOB

CLOB เปิดเผยการวางคำสั่งและการอ่าน orderbook. Relayer Client จะ rout การวางคำสั่งผ่าน Relayer พร้อมจัดการหัวข้อการให้เครดิต Builder หากคุณเป็น Builder.

ประเภทคำสั่งที่สำคัญ:

• Limit orders: โพสต์ลงบนหนังสือและอาจนั่งเป็น maker (maker fees เท่ากับศูนย์).
• Market orders (FAK): SDK มี helper เพื่อสร้าง FAK orders ที่ดำเนินการทันทีหรือล้มเหลวแล้วยกเลิก.

Example: place a FAK market order (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 ให้รวมหัวข้อการให้เครดิตหรือข้อมูลรับรอง Builder ตามที่ SDK ต้องการ. Builder Program มีระดับข้อจำกัด relayer และรางวัล; ขอรับข้อมูลรับรองที่ https://polymarket.com/settings.

Reading market data & the WebSocket

สำหรับการอ่านข้อมูลที่ไม่ใช่การเทรด ให้ใช้ REST และ WebSocket สาธารณะของ 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

เมื่อสมัครรับฟีดตลาดผ่าน WS ให้ร้องขอ custom_feature_enabled: true เพื่อรับเหตุการณ์ best_bid_ask และจำกัดการสมัครรับข้อมูลไม่เกิน 500 instruments ต่อการเชื่อมต่อ.

Error handling and common pitfalls

• Partial fills: market orders (FAK) อาจถูกเติมบางส่วน. ตรวจสอบผลลัพธ์เสมอและจัดการกับส่วนที่เหลือ.
• Slippage: ปกป้องคำสั่งตลาดที่ก้าวร้าวด้วยขีดจำกัด slippage. SDK มักจะมีการตั้งค่าการ slippage บน helper ของ market.
• Resolution และเวลาในการชำระ: UMA disputes อาจทำให้การชำระเงินหยุดชะงัก. ออกแบบ UI และการบัญชีให้สะท้อนเงินที่ยังไม่ถูกรับจนกว่า redeem จะเสร็จ.
• Tick size changes: ขนาด tick เปลี่ยนจาก $0.01 เป็น $0.001 ใกล้ช่วงราคาที่สุดขั้ว; จัดการเหตุการณ์ tick_size_change ของ WebSocket.

Testing strategies

• End-to-end sandbox: ทดสอบการนำผู้ใช้ครบวงจร — เปิด Proxy wallet, ขออนุมัติ, split, วางคำสั่ง, และ merge/redeem.
• Unit test ฟังก์ชัน wrapper: โมคเมธอดของ relayer เพื่อยืนยันลำดับการขออนุมัติและ split ที่ถูกต้อง.
• ตระหนักถึงขีดจำกัดอัตรา: Gamma /markets มี rate limits (300 req / 10 s สำหรับ /markets) — ทำ batch และแคชการอ่าน.

How this affects your trading or bot logic

การใช้ Polymarket Relayer Client ช่วยให้คุณไม่จำเป็นต้องจัดการแก๊สสำหรับผู้ใช้และทำให้ง่ายขึ้นในการนำผู้ใช้เข้าระบบโดยอัตโนมัติด้วยการ deploy Proxy และขออนุมัติ. สำหรับบอต นั่นหมายความว่าคุณสามารถมุ่งเน้นที่กลยุทธ์และข้อมูลตลาด: SDK ลดพื้นผิวการรวมสำหรับการดำเนินการ split/merge และการวางคำสั่ง. อย่างไรก็ตาม คุณยังต้องจัดการความเสี่ยงที่ไม่ใช่การดำเนินการ เช่น slippage, partial fills, และ oracle disputes.

References and next steps

• 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
• Builder Program details and credentials at https://polymarket.com/settings

Closing note: Polymarket sponsors gas via the Relayer and provides TypeScript and Python SDKs to streamline typical wallet and CTF workflows. The Polymarket Relayer Client is the recommended path for building gasless integrations that interact with the CLOB and CTF.

Frequently asked questions

What is the Polymarket Relayer Client?

The Polymarket Relayer Client is the SDK (TypeScript and Python) that routes user transactions through Polymarket's Relayer, handling wallet deployment, ERC-20 approvals, CTF operations, and order placement so end users experience gasless trading.

Do users still need pUSD to trade?

Yes. Polymarket's settlement asset is pUSD (wrapped USDC). The Relayer sponsors gas, but users must hold pUSD to perform split operations and place orders.

Can I act as a Builder through the Relayer Client?

Yes. The Builder Program lets third parties route orders with attribution headers and earn builder fees. Obtain credentials at https://polymarket.com/settings and include builder headers as required by the SDK.

Does the Relayer Client handle approvals and wallet deployment automatically?

The SDK provides helpers for automatic Proxy wallet deployment on first use and for requesting gasless ERC-20 approvals through the Relayer, simplifying onboarding.

Where can I read real-time orderbook updates?

Subscribe to the Market WebSocket at wss://ws-subscriptions-clob.polymarket.com/ws/market. Request custom_feature_enabled: true to receive best_bid_ask events and note the 500-instrument subscription limit.