Polymarket Relayer Client Tutorial

Panduan ini menunjukkan cara menggunakan Polymarket Relayer Client dalam TypeScript untuk membangun alur gasless: deployment wallet, penanganan ERC-20 approval, operasi CTF split/merge/redeem, dan penempatan order di CLOB. Jika Anda menginginkan integrasi gasless yang bekerja dengan Polymarket, Polymarket Relayer Client adalah SDK untuk developer yang akan Anda gunakan pertama.

Key takeaways

• Polymarket Relayer Client menyediakan SDK TypeScript dan Python untuk menangani deployment wallet, approval, operasi CTF, dan penempatan order melalui Polymarket Relayer.
• Transaksi Polymarket bersifat gasless untuk pengguna akhir: Relayer mensponsori gas dan mengabstraksi deployment wallet serta approval.
• Alur umum adalah: onboarding wallet → pemeriksaan/permintaan approval → split (mint) complete set → buat order (limit atau FAK) → merge/redeem setelah resolusi.
• Selalu rancang dengan mempertimbangkan risiko resolusi dan penyelesaian: dispute UMA, partial fill/slippage, dan timing adalah pertimbangan nyata.

Siapa yang cocok untuk panduan ini

Anda adalah developer yang membangun integrasi, bot, atau komponen UX yang menempatkan trade di CLOB Polymarket dan berinteraksi dengan CTF. Anda sebaiknya nyaman dengan TypeScript, wallet EVM (MetaMask, Rabby, dll.), dan konsep web3 dasar.

Gambaran singkat cakupan SDK

• Onboarding wallet: deploy Proxy wallet pada penggunaan pertama atau gunakan Gnosis Safe jika tersedia.
• Manajemen ERC-20 approval untuk pUSD dan token lain yang dipakai pada split/merge.
• Operasi CTF: split, merge, redeem token outcome (ERC-1155).
• Penempatan dan pembatalan order terhadap CLOB melalui Relayer.
• Header atribusi Builder saat Anda bertindak sebagai Builder (lihat dokumen Builder Program).

Catatan: Polymarket menggunakan Polygon (chain ID 137), dan aset penyelesaian untuk trading adalah pUSD (wrapped USDC Polymarket). Semua transaksi pengguna bersifat gasless melalui Relayer.

Instalasi dan langkah pertama

Instal paket TypeScript dan paket penyedia web3 standar. Nama paket yang tepat bisa berubah per rilis; contoh di bawah menggunakan path import kanonik yang umum pada relayer SDK. Jika nama paket berbeda di proyek Anda, periksa README SDK.

Shell

npm install @polymarket/relayer-client ethers

Inisialisasi dasar (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)
});

Catatan tentang contoh di atas: konstruktor RelayerClient dan objek opsi bersifat ilustratif. Periksa README SDK untuk tanda tangan konstruktor dan opsi yang tepat.

Onboarding: deployment wallet dan approvals

Polymarket mendukung dua model wallet: Gnosis Safe yang sudah dideploy sebelumnya dan Proxy wallet yang auto-deploy pada transaksi pertama. Relayer SDK menangani kedua alur dan mensponsori gas deployment.

Langkah onboarding umum yang sebaiknya Anda implementasikan di UX:

1. Deteksi apakah pengguna sudah memiliki Proxy atau Safe. Jika belum, panggil helper SDK untuk deploy-on-first-use.
2. Pastikan pengguna memiliki pUSD di wallet mereka. Jika tidak, arahkan cara bridge atau deposit (lihat panduan pendanaan Polymarket).
3. Periksa status approval ERC-20 untuk pUSD dan minta approval gasless melalui Relayer jika perlu.

Contoh: pemeriksaan & permintaan 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);
}

Karena Relayer mensponsori gas, panggilan approval dikirim melalui Relayer daripada pengguna menandatangani transaksi gas on-chain langsung.

Alur CTF: split, merge, redeem

Conditional Token Framework (CTF) adalah cara Polymarket merepresentasikan outcome (token ERC-1155). Urutan tipikal saat Anda ingin membeli complete set:

• split: membakar pUSD dan mencetak complete set token outcome
• setelah trading, merge: mengubah token outcome tersisa kembali ke posisi umum
• redeem: setelah resolusi, membakar token outcome pemenang untuk $1.00 masing-masing

Contoh 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 akan menangani approval yang diperlukan dan pengiriman ke relayer. Setelah split, Anda akan menerima token outcome ERC-1155 di Proxy atau Safe pengguna.

Menempatkan order di CLOB

CLOB menyediakan penempatan order dan pembacaan orderbook. Relayer Client merutekan penempatan order melalui Relayer, menangani header atribusi builder jika Anda adalah Builder.

Tipe order penting:

• Limit orders: diposting ke buku dan berpotensi menjadi maker (maker fee nol).
• Market orders (FAK): SDK menyediakan helper untuk membuat order FAK yang dieksekusi segera atau dibatalkan.

Contoh: membuat market order 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);

Jika Anda beroperasi sebagai Builder, sertakan header atribusi atau kredensial builder sesuai yang diminta oleh Builder Program. Builder Program menawarkan batas relayer bertingkat dan reward; dapatkan kredensial di https://polymarket.com/settings.

Membaca data pasar & WebSocket

Untuk pembacaan non-trading, gunakan surface REST dan WebSocket publik 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 dan API penempatan order)
• Market WebSocket: wss://ws-subscriptions-clob.polymarket.com/ws/market untuk pembaruan buku secara real-time

Saat berlangganan feed WS pasar, minta custom_feature_enabled: true untuk menerima event best_bid_ask dan batasi langganan ke 500 instrumen per koneksi.

Penanganan error dan jebakan umum

• Partial fills: market order (FAK) dapat terisi sebagian. Selalu periksa hasil dan tangani sisa order.
• Slippage: lindungi market order agresif dengan batas slippage. SDK sering menyediakan pengaturan slippage pada helper market.
• Waktu resolusi dan penyelesaian: dispute UMA dapat menghentikan penyelesaian. Rancang UI dan pencatatan agar mencerminkan dana yang belum terselesaikan sampai redeem selesai.
• Perubahan tick size: tick size bergerak dari $0.01 ke $0.001 dekat ekstrem harga; tangani event tick_size_change dari WebSocket.

Strategi pengujian

• End-to-end sandbox: jalankan onboarding penuh — deploy Proxy wallet, minta approval, split, tempatkan order, dan merge/redeem.
• Unit test fungsi pembungkus: mock method relayer untuk memastikan urutan approval dan split yang benar.
• Kesadaran rate-limit: /markets di Gamma memiliki limit (300 req / 10 s untuk /markets) — batch dan cache pembacaan.

Bagaimana ini memengaruhi logika trading atau bot Anda

Menggunakan Polymarket Relayer Client menghilangkan kebutuhan mengelola gas untuk pengguna akhir dan menyederhanakan onboarding dengan mengotomatiskan deployment Proxy dan approval. Untuk bot, ini berarti Anda dapat fokus pada strategi dan data pasar: SDK mengurangi area integrasi untuk mengeksekusi alur split/merge dan order. Namun, Anda harus tetap menangani risiko non-eksekusi seperti slippage, partial fills, dan dispute oracle.

Referensi dan langkah selanjutnya

• Base URL API Polymarket: 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
• Detail Builder Program dan kredensial di https://polymarket.com/settings

Catatan penutup: Polymarket mensponsori gas melalui Relayer dan menyediakan SDK TypeScript serta Python untuk merampingkan alur wallet dan CTF tipikal. Polymarket Relayer Client adalah jalur yang direkomendasikan untuk membangun integrasi gasless yang berinteraksi dengan CLOB dan CTF.

Frequently asked questions

What is the Polymarket Relayer Client?

Polymarket Relayer Client adalah SDK (TypeScript dan Python) yang merutekan transaksi pengguna melalui Polymarket Relayer, menangani deployment wallet, approval ERC-20, operasi CTF, dan penempatan order sehingga pengguna akhir mengalami trading tanpa gas.

Do users still need pUSD to trade?

Ya. Aset penyelesaian Polymarket adalah pUSD (wrapped USDC). Relayer mensponsori gas, tetapi pengguna harus memegang pUSD untuk melakukan operasi split dan menempatkan order.

Can I act as a Builder through the Relayer Client?

Ya. Builder Program memungkinkan pihak ketiga merutekan order dengan header atribusi dan memperoleh builder fees. Dapatkan kredensial di https://polymarket.com/settings dan sertakan header builder sesuai yang diminta oleh SDK.

Does the Relayer Client handle approvals and wallet deployment automatically?

SDK menyediakan helper untuk deployment Proxy wallet otomatis pada penggunaan pertama dan untuk meminta approval ERC-20 gasless melalui Relayer, menyederhanakan onboarding.

Where can I read real-time orderbook updates?

Berlangganan Market WebSocket di wss://ws-subscriptions-clob.polymarket.com/ws/market. Minta custom_feature_enabled: true untuk menerima event best_bid_ask dan perhatikan batas langganan 500 instrumen.