Polymarket Relayer Client Tutorial

Ce guide montre comment utiliser le Polymarket Relayer Client en TypeScript pour construire des flux gasless : déploiement de wallet, gestion des approbations ERC-20, opérations CTF split/merge/redeem et placement d'ordres sur le CLOB. Si vous voulez une intégration gasless fonctionnelle avec Polymarket, le Polymarket Relayer Client est le SDK destiné aux développeurs que vous utiliserez en premier.

Points clés

• Le Polymarket Relayer Client fournit des SDKs TypeScript et Python pour gérer le déploiement de wallets, les approbations, les opérations CTF et le placement d'ordres via le Relayer de Polymarket.
• Les transactions Polymarket sont gasless pour les utilisateurs finaux : le Relayer sponsorise le gas et abstrait le déploiement des wallets et les approbations.
• Les flux courants sont : onboarding du wallet → vérification/obtention d'approbation → split (mint) d'un ensemble complet → création d'ordre (limit ou FAK) → merge/redeem après résolution.
• Concevez toujours en tenant compte des risques de résolution et de règlement : disputes UMA, remplissages partiels/slippage et problèmes de timing sont des considérations réelles.

À qui s'adresse ce guide

Vous êtes développeur et vous créez des intégrations, des bots ou des composants UX qui passent des ordres sur le CLOB de Polymarket et interagissent avec le CTF. Vous devez être à l'aise avec TypeScript, les wallets EVM (MetaMask, Rabby, etc.) et les concepts web3 de base.

Aperçu rapide de ce que couvre le SDK

• Onboarding de wallet : déploiement de Proxy wallets au premier usage ou utilisation d'un Gnosis Safe si disponible.
• Gestion des approbations ERC-20 pour pUSD et autres tokens utilisés dans les opérations de split/merge.
• Opérations CTF : split, merge, redeem des tokens d'issue (ERC-1155).
• Placement et annulation d'ordres contre le CLOB via le Relayer.
• En-têtes d'attribution Builder lorsque vous agissez en tant que Builder (voir la documentation du Builder Program).

Remarque : Polymarket utilise Polygon (chain ID 137) et l'actif de règlement pour le trading est pUSD (le wrapped USDC de Polymarket). Toutes les transactions utilisateur sont gasless via le Relayer.

Installation et premières étapes

Installez le package TypeScript et un package provider web3 standard. Les noms de package exacts peuvent varier selon la release ; les exemples ci-dessous utilisent le chemin d'import canonique courant dans les SDK du relayer. Si les noms changent dans votre projet, consultez le README du SDK.

Shell

npm install @polymarket/relayer-client ethers

Initialisation basique (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)
});

Remarques sur l'exemple ci‑dessus : le constructeur RelayerClient et l'objet d'options sont illustratifs. Vérifiez le README du SDK pour la signature exacte du constructeur et les options disponibles.

Onboarding : déploiement de wallet et approbations

Polymarket prend en charge deux modèles de wallet : les Gnosis Safes pré‑déployés et les Proxy wallets qui sont auto‑déployés lors de la première transaction. Le SDK Relayer gère les deux flux et sponsorise le gas du déploiement.

Étapes d'onboarding courantes à implémenter dans l'UX :

1. Détecter si l'utilisateur possède déjà un Proxy ou un Safe. Si ce n'est pas le cas, appeler l'aide du SDK pour deploy-on-first-use.
2. S'assurer que l'utilisateur a du pUSD dans son wallet. Sinon, lui indiquer comment bridge ou déposer (voir le guide de financement de Polymarket).
3. Vérifier l'état d'approbation ERC-20 pour pUSD et proposer une approbation gasless via le Relayer si nécessaire.

Exemple : vérification et demande d'approbation (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);
}

Parce que le Relayer sponsorise le gas, l'appel d'approbation est envoyé via le Relayer plutôt que l'utilisateur ne signe une transaction on‑chain payante.

Flux CTF : split, merge, redeem

Le Conditional Token Framework (CTF) est la façon dont Polymarket représente les issues (tokens ERC-1155). Séquence typique lorsque vous souhaitez acheter un ensemble complet :

• split : brûler du pUSD et mint un ensemble complet de tokens d'issue
• après trading, merge : convertir les tokens d'issue restants en position commune
• redeem : après résolution, brûler les tokens gagnants pour $1.00 chacun

Exemple de 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);

Le SDK gèrera les approbations nécessaires et l'envoi via le relayer. Après un split, vous recevrez des tokens d'issue ERC-1155 dans le Proxy ou le Safe de l'utilisateur.

Placement d'ordres sur le CLOB

Le CLOB expose le placement d'ordres et la lecture du carnet. Le Relayer Client route le placement d'ordres via le Relayer, en gérant les en‑têtes d'attribution Builder si vous êtes Builder.

Types d'ordres importants :

• Ordres limit : poster sur le carnet et potentiellement rester comme maker (les frais maker sont nuls).
• Ordres de marché (FAK) : le SDK expose des helpers pour créer des ordres FAK qui s'exécutent immédiatement ou sont annulés.

Exemple : passer un ordre de marché 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);

Si vous opérez en tant que Builder, incluez les en‑têtes d'attribution ou les identifiants Builder requis par le Builder Program. Le Builder Program propose des limites de relayer par palier et des récompenses ; obtenez des identifiants sur https://polymarket.com/settings.

Lecture des données de marché & WebSocket

Pour les lectures non‑trading, utilisez les surfaces REST publiques et le WebSocket de 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 pour des mises à jour du carnet en temps réel

Lorsque vous vous abonnez aux flux WS du market, demandez custom_feature_enabled: true pour recevoir les events best_bid_ask et limitez l'abonnement à 500 instruments par connexion.

Gestion des erreurs et pièges courants

• Remplissages partiels : les ordres de marché (FAK) peuvent être partiellement remplis. Inspectez toujours le résultat et gérez les restes.
• Slippage : protégez les ordres de marché agressifs avec des limites de slippage. Le SDK expose souvent des paramètres de slippage sur les helpers marché.
• Timing de résolution et de règlement : les disputes UMA peuvent suspendre le règlement. Concevez les UIs et la comptabilité pour refléter des fonds non réglés tant que le redeem n'est pas complété.
• Changements de tick size : le tick size passe de $0.01 à $0.001 près des extrêmes de prix ; gérez les événements WebSocket tick_size_change.

Stratégies de test

• Sandbox end‑to‑end : testez l'onboarding complet — déployez un Proxy wallet, demandez une approbation, effectuez un split, placez un ordre, puis merge/redeem.
• Tests unitaires des wrappers : mockez les méthodes du relayer pour assurer la bonne séquence d'approbation et de split.
• Conscience des limites de taux : Gamma /markets a des limites (300 req / 10 s pour /markets) — batcher et mettre en cache les lectures.

Impact sur votre logique de trading ou de bot

L'utilisation du Polymarket Relayer Client supprime la nécessité de gérer le gas pour les utilisateurs finaux et simplifie l'onboarding en automatisant les déploiements de Proxy et les approbations. Pour les bots, cela signifie que vous pouvez vous concentrer sur la stratégie et les données de marché : le SDK réduit la surface d'intégration pour l'exécution des flows split/merge et des ordres. Cependant, vous devez toujours gérer les risques non liés à l'exécution comme le slippage, les remplissages partiels et les disputes d'oracle.

Références et étapes suivantes

• 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
• Détails du Builder Program et identifiants sur https://polymarket.com/settings

Note de clôture : Polymarket sponsorise le gas via le Relayer et fournit des SDKs TypeScript et Python pour rationaliser les workflows typiques de wallet et CTF. Le Polymarket Relayer Client est la voie recommandée pour construire des intégrations gasless qui interagissent avec le CLOB et le CTF.

Questions fréquentes

Qu'est‑ce que le Polymarket Relayer Client ?

Le Polymarket Relayer Client est le SDK (TypeScript et Python) qui route les transactions utilisateur via le Relayer de Polymarket, gérant le déploiement des wallets, les approbations ERC-20, les opérations CTF et le placement d'ordres afin que les utilisateurs finaux bénéficient d'un trading gasless.

Les utilisateurs ont‑ils toujours besoin de pUSD pour trader ?

Oui. L'actif de règlement de Polymarket est pUSD (wrapped USDC). Le Relayer sponsorise le gas, mais les utilisateurs doivent posséder du pUSD pour effectuer des opérations de split et placer des ordres.

Puis‑je agir en tant que Builder via le Relayer Client ?

Oui. Le Builder Program permet à des tiers de router des ordres avec des en‑têtes d'attribution et d'encaisser des builder fees. Obtenez des identifiants sur https://polymarket.com/settings et incluez les en‑têtes Builder requis par le SDK.

Le Relayer Client gère‑t‑il automatiquement les approbations et le déploiement de wallet ?

Le SDK fournit des helpers pour le déploiement automatique de Proxy wallets au premier usage et pour la demande d'approbations ERC-20 gasless via le Relayer, simplifiant l'onboarding.

Où puis‑je lire les mises à jour du carnet en temps réel ?

Abonnez‑vous au Market WebSocket à wss://ws-subscriptions-clob.polymarket.com/ws/market. Demandez custom_feature_enabled: true pour recevoir les events best_bid_ask et notez la limite d'abonnement de 500 instruments.