Polymarket Relayer Client Tutorial

Questa guida mostra come usare il Polymarket Relayer Client in TypeScript per costruire flussi gasless: deployment del wallet, gestione delle approvazioni ERC-20, operazioni CTF di split/merge/redeem e invio ordini sul CLOB. Se vuoi un'integrazione funzionante e senza gas con Polymarket, il Polymarket Relayer Client è l'SDK rivolto agli sviluppatori che userai per primo.

Punti chiave

• Il Polymarket Relayer Client fornisce SDK in TypeScript e Python per gestire deployment dei wallet, approvazioni, operazioni CTF e invio ordini tramite il Relayer di Polymarket.
• Le transazioni su Polymarket sono gasless per gli utenti finali: il Relayer sponsorizza il gas e astrae il deployment del wallet e le approvazioni.
• I flussi comuni sono: onboarding del wallet → controllo/ richiesta approvazione → split (mint) di un set completo → creazione ordine (limit o FAK) → merge/redeem dopo la risoluzione.
• Progetta sempre tenendo conto dei rischi di risoluzione e regolamento: dispute UMA, riempimenti parziali/slippage e tempistiche sono considerazioni reali.

A chi è rivolta questa guida

Sei uno sviluppatore che costruisce integrazioni, bot o componenti UX che inviano trade sul CLOB di Polymarket e interagiscono con il CTF. Dovresti essere a tuo agio con TypeScript, wallet EVM (MetaMask, Rabby, ecc.) e concetti web3 di base.

Panoramica rapida di cosa copre l'SDK

• Onboarding del wallet: deploy di Proxy wallet al primo utilizzo o uso di una Gnosis Safe se disponibile.
• Gestione delle approvazioni ERC-20 per pUSD e altri token usati in split/merge.
• Operazioni CTF: split, merge, redeem dei token di outcome (ERC-1155).
• Invio e cancellazione ordini contro il CLOB tramite il Relayer.
• Header di attribuzione Builder quando agisci come Builder (vedi la documentazione del Builder Program).

Nota: Polymarket usa Polygon (chain ID 137) e l'asset di regolamento per il trading è pUSD (il wrapped USDC di Polymarket). Tutte le transazioni utente sono gasless tramite il Relayer.

Installazione e primi passi

Installa il pacchetto TypeScript e un provider web3 standard. I nomi dei pacchetti possono variare per release; gli esempi sotto usano il path di import canonico comune negli SDK del relayer. Se i nomi dei pacchetti differiscono nel tuo progetto, consulta il README dell'SDK.

Shell

npm install @polymarket/relayer-client ethers

Inizializzazione di base (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)
});

Note sull'esempio sopra: il costruttore RelayerClient e l'oggetto opzioni sono illustrativi. Controlla il README dell'SDK per la firma esatta del costruttore e le opzioni disponibili.

Onboarding: deployment del wallet e approvazioni

Polymarket supporta due modelli di wallet: Gnosis Safe pre-deployate e Proxy wallet che vengono auto-deployati alla prima transazione. L'SDK del Relayer gestisce entrambi i flussi e sponsorizza il gas per il deployment.

Passi comuni di onboarding che dovresti implementare nell'UX:

1. Rileva se l'utente ha già un Proxy o una Safe. Se no, chiama l'helper dell'SDK per il deploy-on-first-use.
2. Assicurati che l'utente abbia pUSD nel wallet. Se no, istruiscilo su come bridgeare o depositare (vedi la guida di funding di Polymarket).
3. Controlla lo stato di approvazione ERC-20 per pUSD e chiedi un'approvazione gasless tramite il Relayer se necessario.

Esempio: controllo e richiesta di approvazione (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);
}

Poiché il Relayer sponsorizza il gas, la chiamata di approval viene inviata tramite il Relayer invece che come transazione on-chain diretta firmata dall'utente.

Flussi CTF: split, merge, redeem

Il Conditional Token Framework (CTF) è il modo in cui Polymarket rappresenta gli outcome (token ERC-1155). Sequenza tipica quando vuoi comprare un set completo:

• split: brucia pUSD e mint un set completo di token di outcome
• dopo il trading, merge: converte i token di outcome rimanenti in una posizione comune
• redeem: dopo la risoluzione, brucia i token vincenti per $1.00 ciascuno

Esempio di 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);

L'SDK gestirà le approvazioni necessarie e l'invio al relayer. Dopo lo split, riceverai i token ERC-1155 di outcome nel Proxy o nella Safe dell'utente.

Invio ordini sul CLOB

Il CLOB espone invio ordini e letture dell'orderbook. Il Relayer Client instrada l'invio ordini tramite il Relayer, gestendo gli header di attribuzione Builder se sei un Builder.

Tipi di ordine importanti:

• Ordini limit: vengono postati nel book e possono rimanere come maker (le fee maker sono zero).
• Ordini market (FAK): l'SDK espone helper per creare ordini FAK che eseguono immediatamente o vengono cancellati.

Esempio: inviare un ordine 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);

Se operi come Builder, includi header di attribuzione o le credenziali Builder come richiesto dal Builder Program. Il Builder Program offre limiti relayer a livelli e ricompense; ottieni le credenziali su https://polymarket.com/settings.

Lettura dei dati di mercato e WebSocket

Per letture non di trading, usa le superfici REST e WebSocket pubbliche di 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 per aggiornamenti realtime del book

Quando ti iscrivi ai feed WS di mercato, richiedi custom_feature_enabled: true per ricevere eventi best_bid_ask e limita la sottoscrizione a 500 strumenti per connessione.

Gestione errori e insidie comuni

• Riempimenti parziali: gli ordini market (FAK) possono riempirsi parzialmente. Ispeziona sempre il risultato e gestisci gli avanzi.
• Slippage: proteggi gli ordini market aggressivi con limiti di slippage. L'SDK spesso espone impostazioni di slippage sugli helper market.
• Tempistiche di risoluzione e regolamento: le dispute UMA possono mettere in pausa il regolamento. Progetta UI e contabilità per riflettere fondi non regolati fino al completamento del redeem.
• Cambi di tick size: il tick size passa da $0.01 a $0.001 vicino agli estremi di prezzo; gestisci gli eventi tick_size_change dal WebSocket.

Strategie di testing

• End-to-end sandbox: esercita l'intero onboarding — deploy del Proxy wallet, richiesta di approval, split, invio ordine e merge/redeem.
• Unit test delle funzioni wrapper: fai il mock dei metodi del relayer per asserire le sequenze corrette di approval e split.
• Consapevolezza dei rate-limit: /markets di Gamma ha limiti (300 req / 10 s per /markets) — raggruppa e cache le letture.

Come questo influisce sulla tua logica di trading o del bot

Usare il Polymarket Relayer Client elimina la necessità di gestire il gas per gli utenti finali e semplifica l'onboarding automatizzando i deployment dei Proxy e le approvazioni. Per i bot, questo significa che puoi concentrarti sulla strategia e sui dati di mercato: l'SDK riduce la superficie d'integrazione per eseguire i flussi di split/merge e ordine. Tuttavia, devi comunque gestire rischi non legati all'esecuzione come slippage, riempimenti parziali e dispute dell'oracolo.

Riferimenti e passi successivi

• URL base delle API di 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
• Dettagli del Builder Program e credenziali su https://polymarket.com/settings

Nota di chiusura: Polymarket sponsorizza il gas tramite il Relayer e fornisce SDK in TypeScript e Python per snellire i flussi tipici di wallet e CTF. Il Polymarket Relayer Client è il percorso raccomandato per costruire integrazioni gasless che interagiscono con il CLOB e il CTF.

Domande frequenti

Cos'è il Polymarket Relayer Client?

Il Polymarket Relayer Client è l'SDK (TypeScript e Python) che instrada le transazioni utente tramite il Relayer di Polymarket, gestendo il deployment del wallet, le approvazioni ERC-20, le operazioni CTF e l'invio ordini in modo che gli utenti finali sperimentino trading gasless.

Gli utenti devono comunque avere pUSD per fare trading?

Sì. L'asset di regolamento di Polymarket è pUSD (wrapped USDC). Il Relayer sponsorizza il gas, ma gli utenti devono possedere pUSD per effettuare operazioni di split e inviare ordini.

Posso agire come Builder tramite il Relayer Client?

Sì. Il Builder Program permette a terzi di instradare ordini con header di attribuzione e guadagnare builder fees. Ottieni le credenziali su https://polymarket.com/settings e includi gli header Builder come richiesto dall'SDK.

Il Relayer Client gestisce automaticamente approvazioni e deployment del wallet?

L'SDK fornisce helper per il deployment automatico del Proxy wallet al primo utilizzo e per richiedere approvazioni ERC-20 gasless tramite il Relayer, semplificando l'onboarding.

Dove posso leggere aggiornamenti realtime dell'orderbook?

Iscriviti al Market WebSocket su wss://ws-subscriptions-clob.polymarket.com/ws/market. Richiedi custom_feature_enabled: true per ricevere eventi best_bid_ask e nota il limite di sottoscrizione di 500 strumenti.