Polymarket Relayer Client Tutorial

Dieser Leitfaden zeigt, wie man den Polymarket Relayer Client in TypeScript verwendet, um gaslose Abläufe zu bauen: Wallet-Deployment, ERC-20-Approval-Handling, CTF split/merge/redeem-Operationen und Order-Platzierung auf dem CLOB. Wenn du eine funktionierende, gaslose Integration mit Polymarket willst, ist der Polymarket Relayer Client das Entwickler-SDK, das du zuerst verwenden wirst.

Wesentliche Erkenntnisse

• Der Polymarket Relayer Client stellt TypeScript- und Python-SDKs bereit, die Wallet-Deployment, Approvals, CTF-Operationen und Order-Platzierung über den Polymarket Relayer abwickeln.
• Polymarket-Transaktionen sind für Endnutzer gaslos: der Relayer sponsert Gas und abstrahiert Wallet-Deployment und Approvals.
• Gängige Abläufe sind: Wallet-Onboarding → Approval-Check/Approval → split (mint) eines vollständigen Sets → Order erstellen (Limit oder FAK) → merge/redeem nach Resolution.
• Plane stets für Resolution- und Settlement-Risiken: UMA-Dispute, partielle Fills/Slippage und Timing sind reale Faktoren.

Für wen dieser Leitfaden gedacht ist

Du bist Entwickler und baust Integrationen, Bots oder UI-Komponenten, die Orders auf Polymarket's CLOB platzieren und mit dem CTF interagieren. Du solltest mit TypeScript, EVM-Wallets (MetaMask, Rabby usw.) und grundlegenden Web3-Konzepten vertraut sein.

Kurzer Überblick, was das SDK abdeckt

• Wallet-Onboarding: Proxy-Wallets bei erster Nutzung deployen oder eine vorhandene Gnosis Safe verwenden.
• Verwaltung von ERC-20-Approvals für pUSD und andere Token, die bei split/merge verwendet werden.
• CTF-Operationen: split, merge, redeem von Outcome-Token (ERC-1155).
• Order-Platzierung und Stornierung gegen das CLOB über den Relayer.
• Builder-Attributions-Header, wenn du als Builder agierst (siehe Builder Program-Dokumentation).

Hinweis: Polymarket läuft auf Polygon (chain ID 137) und das Settlement-Asset ist pUSD (Polymarket's wrapped USDC). Alle Nutzertransaktionen sind über den Relayer gaslos.

Installation und erste Schritte

Installiere das TypeScript-Paket und ein gängiges Web3-Providerpaket. Exakte Paketnamen können je nach Release variieren; die Beispiele unten verwenden den kanonischen Importpfad, wie er in Relayer-SDKs üblich ist. Wenn die Paketnamen in deinem Projekt abweichen, siehe das SDK-README.

Shell

npm install @polymarket/relayer-client ethers

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

Hinweise zum obigen Beispiel: Der RelayerClient-Konstruktor und das Options-Objekt sind illustrativ. Prüfe das SDK-README auf die genaue Konstruktor-Signatur und verfügbare Optionen.

Onboarding: Wallet-Deployment und Approvals

Polymarket unterstützt zwei Wallet-Modelle: vor-deployte Gnosis Safes und Proxy-Wallets, die bei der ersten Transaktion automatisch deployed werden. Das Relayer-SDK handhabt beide Abläufe und sponsert das Deployment-Gas.

Gängige Onboarding-Schritte, die du in der UX umsetzen solltest:

1. Erkenne, ob der Nutzer bereits eine Proxy- oder Safe-Adresse hat. Falls nicht, rufe den deploy-on-first-use-Helfer des SDK auf.
2. Stelle sicher, dass der Nutzer pUSD in seiner Wallet hat. Falls nicht, erkläre, wie man bridged oder einzahlt (siehe Polymarket's Funding-Guide).
3. Prüfe den ERC-20-Approval-Status für pUSD und initiiere bei Bedarf eine gaslose Approval-Anfrage über den Relayer.

Beispiel: Approval prüfen & anfordern (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);
}

Da der Relayer Gas sponsert, wird der Approval-Aufruf über den Relayer gesendet und nicht als direkte On-Chain-Gas-Transaktion des Nutzers.

CTF-Abläufe: split, merge, redeem

Das Conditional Token Framework (CTF) ist die Darstellung von Outcomes auf Polymarket (ERC-1155-Token). Übliche Abfolge, wenn du ein vollständiges Set kaufen willst:

• split: pUSD verbrennen und ein vollständiges Set von Outcome-Token minten
• nach dem Trading, merge: verbleibende Outcome-Token in eine gemeinsame Position konvertieren
• redeem: nach Resolution die gewinnenden Outcome-Token für $1.00 pro Token verbrennen

Beispiel 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);

Das SDK kümmert sich um notwendige Approvals und das Einreichen beim Relayer. Nach dem split erhält die Proxy- oder Safe-Adresse des Nutzers die ERC-1155-Outcome-Token.

Orders auf dem CLOB platzieren

Das CLOB stellt Order-Platzierung und Orderbook-Lesezugriffe bereit. Der Relayer Client routet Order-Platzierung durch den Relayer und übernimmt Builder-Attributions-Header, falls du als Builder agierst.

Wichtige Order-Typen:

• Limit-Orders: im Orderbuch platzieren und womöglich als Maker sitzen (Maker-Gebühren sind null).
• Market-Orders (FAK): das SDK stellt Helfer bereit, um FAK-Orders zu erstellen, die sofort ausführen oder abbrechen.

Beispiel: FAK-Market-Order platzieren (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);

Wenn du als Builder operierst, füge Attributions-Header oder Builder-Credentials hinzu, wie vom Builder Program verlangt. Das Builder Program bietet gestaffelte Relayer-Limits und Rewards; Credentials erhältst du unter https://polymarket.com/settings.

Marktdaten lesen & WebSocket

Für nicht-trading Reads verwende Polymarket's öffentliche REST- und WebSocket-Schnittstellen:

• 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- und Order-Platzierungs-APIs)
• Market WebSocket: wss://ws-subscriptions-clob.polymarket.com/ws/market für Echtzeit-Book-Updates

Wenn du Market-WS-Feeds abonnierst, fordere custom_feature_enabled: true an, um best_bid_ask-Events zu erhalten, und beschränke Abonnements auf 500 Instruments pro Connection.

Fehlerbehandlung und häufige Fallstricke

• Partielle Fills: Market-Orders (FAK) können partiell ausgeführt werden. Prüfe stets das Ergebnis und behandle verbleibende Positionen.
• Slippage: Schütze aggressive Market-Orders mit Slippage-Limits. Das SDK bietet oft Slippage-Einstellungen für Market-Helfer.
• Resolution- und Settlement-Timing: UMA-Dispute können die Settlement-Phase pausieren. Gestalte UIs und Buchhaltung so, dass nicht abgewickelte Gelder bis zum Abschluss von redeem als unsicher erscheinen.
• Tick-Size-Änderungen: Die Tick-Größe ändert sich von $0.01 auf $0.001 nahe Extrempreisen; verarbeite tick_size_change-WebSocket-Events.

Teststrategien

• End-to-End-Sandbox: teste das vollständige Onboarding — deploye eine Proxy-Wallet, fordere Approval an, splitte, platziere eine Order und merge/redeem.
• Unit-Tests für Wrapper-Funktionen: mocke Relayer-Methoden, um korrekte Approval- und Split-Sequenzen zu prüfen.
• Rate-Limit-Bewusstsein: Gamma /markets hat Rate-Limits (300 req / 10 s für /markets) — bündle und cache Leseaufrufe.

Auswirkungen auf deine Trading- oder Bot-Logik

Der Einsatz des Polymarket Relayer Client entbindet dich davon, Gas für Endnutzer zu managen, und vereinfacht das Onboarding, indem Proxy-Deployments und Approvals automatisiert werden. Für Bots bedeutet das, dass du dich stärker auf Strategie und Marktdaten konzentrieren kannst: das SDK reduziert die Integrationsoberfläche für split/merge- und Order-Abläufe. Du musst dennoch Nicht-Ausführungsrisiken wie Slippage, partielle Fills und Oracle-Dispute behandeln.

Referenzen und nächste Schritte

• Polymarket API-Basen-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 und Credentials unter https://polymarket.com/settings

Abschließende Anmerkung: Polymarket sponsert Gas über den Relayer und stellt TypeScript- und Python-SDKs bereit, um typische Wallet- und CTF-Workflows zu vereinfachen. Der Polymarket Relayer Client ist der empfohlene Weg, um gaslose Integrationen zu bauen, die mit dem CLOB und CTF interagieren.

Häufig gestellte Fragen

Was ist der Polymarket Relayer Client?

Der Polymarket Relayer Client ist das SDK (TypeScript und Python), das Nutzertransaktionen durch Polymarket's Relayer routet und Wallet-Deployment, ERC-20-Approvals, CTF-Operationen und Order-Platzierung handhabt, sodass Endnutzer gaslos traden.

Brauchen Nutzer weiterhin pUSD, um zu traden?

Ja. Das Settlement-Asset von Polymarket ist pUSD (wrapped USDC). Der Relayer sponsert Gas, aber Nutzer müssen pUSD halten, um split-Operationen durchzuführen und Orders zu platzieren.

Kann ich als Builder über den Relayer Client agieren?

Ja. Das Builder Program erlaubt Drittparteien, Orders mit Attributions-Headern zu routen und Builder-Gebühren zu verdienen. Erhalte Credentials unter https://polymarket.com/settings und füge die Builder-Header wie vom SDK verlangt hinzu.

Handhabt der Relayer Client Approvals und Wallet-Deployment automatisch?

Das SDK stellt Helfer zur automatischen Proxy-Wallet-Deployment bei erster Nutzung sowie zur Anforderung gasloser ERC-20-Approvals über den Relayer bereit und vereinfacht so das Onboarding.

Wo kann ich Echtzeit-Orderbook-Updates lesen?

Abonniere den Market WebSocket unter wss://ws-subscriptions-clob.polymarket.com/ws/market. Fordere custom_feature_enabled: true an, um best_bid_ask-Events zu erhalten, und beachte das Limit von 500 Instruments pro Subscription.