Polymarket Bot Tutorial · Kapitel 8 von 32

Polymarket CLOB API für Bots: REST-Endpunkte für Order-Book-Snapshots, WebSocket-Subscriptions für Echtzeit-Updates, Parsing von Bids/Asks, Berechnung von Mid-Price und Depth, Code-Beispiele.

Von Harley Young, Chefredakteurin bei Polymarkets.co.il. Zuletzt überprüft: Mai 2026.

Was dieses Kapitel abdeckt

Die CLOB API ist der Ort, an dem Orders signiert, gesendet, gematcht werden und wo das Order Book lebt. Polymarket hat zwei SDK-Generationen - das veraltete v1 und das aktuelle v2. Dieses Kapitel behandelt nur v2; v1 sollte in keinem Bot auftauchen, den du 2026 auslieferst. Wir gehen den REST-Snapshot-Pfad, den WebSocket-Update-Kanal, die Parsing-Details, über die neue Builder stolpern, und die Reconnect-Logik durch, ohne die ein langlebiger Bot innerhalb weniger Stunden aus dem Takt gerät.

  • CLOB v1 vs v2 (verwende v2)
  • Order-Book-REST-Snapshot
  • WebSocket-Subscriptions: Market- und User-Channels
  • Parsing von Bids/Asks/Depth
  • Berechnung von Mid-Price und Best Bid/Ask
  • Maker Fees, Taker Fees, Rebates
  • Code: WS verbinden und Price-Change-Events verarbeiten
  • Reconnect und Gap-Handling

CLOB v1 vs v2 (verwende v2)

Polymarket pflegt zwei SDK-Generationen. v1 (@polymarket/clob-client auf npm, py-clob-client <0.30) ist veraltet und es fehlen mehrere Order-Typen, die 2024 hinzugefügt wurden. v2 (@polymarket/clob-client-v2 v1.0.6 in Node, py-clob-client 0.34.6+ in Python) ist der aktuelle Standard.

Drei konkrete Unterschiede. v2 unterstützt das negRisk-Flag für Multi-Outcome-Markets - erforderlich seit dem Start der NegRisk-Exchange Ende 2024. v2 liefert TypeScript-Typen für die Formen der WebSocket-Messages; v1 gibt any zurück. v2 verarbeitet den Gnosis Safe Signature-Flow vom August 2025 nativ; v1 benötigt benutzerdefiniertes Signing-Glue.

Der Rest dieses Kapitels ist durchgehend auf v2 ausgelegt. Wenn du in einem älteren Tutorial v1-Code siehst, behandle ihn zunächst als fehlerhaft, bis das Gegenteil bewiesen ist - insbesondere Order-Platzierungen gegen NegRisk-Markets werden unter v1 stillschweigend an den falschen Exchange-Contract weitergeleitet.

Order-Book-REST-Snapshot

Der REST-Snapshot-Endpunkt liefert das vollständige Buch für ein einzelnes Token zu einem bestimmten Zeitpunkt.

GET https://clob.polymarket.com/book?token_id=<ERC1155_TOKEN_ID>

Response-Shape:

{
  "market": "0x...",
  "asset_id": "5413...",
  "timestamp": "1715600000000",
  "hash": "0x...",
  "bids": [{"price":"0.45","size":"120"}, {"price":"0.44","size":"380"}, ...],
  "asks": [{"price":"0.47","size":"85"}, {"price":"0.48","size":"210"}, ...]
}

Preise sind Strings mit 2-3 Dezimalstellen; Sizes sind Strings, die Share-Anzahlen darstellen (nicht Dollar). Bids sind von hoch nach niedrig sortiert, Asks von niedrig nach hoch. hash ist ein Deduplizierungsmarker - wiederholte Polls eines unveränderten Books liefern denselben Hash und dein Bot kann die Verarbeitung überspringen.

Der REST-Snapshot ist die richtige Wahl für einmalige Abfragen (Price-Check bei einer Entry-Entscheidung). Für kontinuierliches Monitoring nutze den untenstehenden WebSocket-Channel.

WebSocket-Subscriptions: Market- und User-Channels

Zwei WebSocket-Channels sind wichtig.

Market-Channel: wss://ws-subscriptions-clob.polymarket.com/ws/market. Für ein oder mehrere Tokens abonnieren; Order-Book-Updates in Echtzeit erhalten.

{"type":"Market","markets":["0xCondId1","0xCondId2"]}

Messages kommen bei jeder Änderung an. Typen sind unter anderem book (vollständiger Snapshot), price_change (Delta), tick_size_change (selten) und last_trade_price (letzter Fill).

User-Channel: wss://ws-subscriptions-clob.polymarket.com/ws/user. Authentifiziert; du erhältst deine eigenen Order-Events - Fills, Partial Fills, Cancellations.

{"type":"User","auth":{"apiKey":"...","secret":"...","passphrase":"..."}}

Der User-Channel ist der sauberste Weg, einen Fill zu erkennen. Polling des Orders-REST-Endpunkts kostet mehr und kann Zustandsänderungen zwischen den Polls verpassen; das WebSocket pusht das Event in dem Moment, in dem der Matcher es bestätigt.

Parsing von Bids/Asks/Depth

Das Order Book ist eine Liste von Preisniveaus mit aggregierter Größe. Zwei Parsing-Konventionen sind entscheidend.

Order-Richtung: bids sind Kauforders (jemand möchte zu diesem Preis KAUFEN). Wenn DEIN Bot verkauft, triffst du einen Bid. Wenn dein Bot kauft, hebst du einen Ask an. Die Polymarket-UI zeigt dieselbe Richtung; manche andere Exchanges drehen sie um.

Sortierung: bids kommen absteigend sortiert an (bester Bid zuerst). asks kommen aufsteigend sortiert an (bester Ask zuerst). Best Bid ist bids[0]; Best Ask ist asks[0]. Vorsicht: Das öffentliche WebSocket sendet manchmal partielle Book-Updates, die nicht vorab sortiert sind - sortiere nach jedem Merge immer defensiv neu.

Depth auf einem Level ist der handelbare Dollar-Wert: price * size. Top-5-Level-Depth ist ein gängiger Liquiditätsindikator: sum(b.price * b.size for b in bids[:5]). Wenn die Top-5-Depth unter 100 $ liegt, ist das Book illiquide und die meisten Strategieannahmen brechen weg.

Mid-Price und Best Bid/Ask berechnen

Drei abgeleitete Preispunkte braucht dein Bot.

  • Best Bid / Best Ask: bids[0].price und asks[0].price. Die Preise, zu denen du tatsächlich handeln kannst, pro Share.
  • Mid-Price: (best_bid + best_ask) / 2. Das mathematische Zentrum des Spreads. Nützlich für Bewertung; du handelst nie zum Mid.
  • VWAP-Preis für Größe N: Laufe das Buch ab, bis die kumulierte Größe N erreicht, und gib den größengewichteten Durchschnittspreis zurück. Die tatsächlichen Kosten, um N Shares jetzt sofort ZU KAUFEN, inklusive Sweep in tiefere Levels.

Edge Case: Eine leere Bid- oder Ask-Seite (niemand verkauft oder niemand kauft) bedeutet, dass das Book einseitig ist. In der Marktstruktur von Polymarket passiert das bei aufgelösten oder fast aufgelösten Märkten, in denen eine Seite bei 0.999 liegt und niemand Liquidität auf der Verliererseite anbietet. Behandle best-bid = 0 oder best-ask = 1 als Signale für "nicht handeln".

Maker Fees, Taker Fees, Rebates

Polymarket hat den Grossteil seiner Geschichte gar keine Trading-Gebühren erhoben. Das hat sich 2026 geändert: Anfang des Jahres wurden Gebühren auf den 15-Minuten-Crypto-Markets eingeführt, am 30. März 2026 auf Sports ausgeweitet und seitdem auf die meisten Kategorien ausgerollt. Jedes Tutorial, das noch behauptet, Polymarket sei gebührenfrei, ist veraltet - und wer das bei einer Hochfrequenz-Strategie übersieht, wird leise aufgefressen. So funktioniert das Modell tatsächlich, Stand Mitte 2026.

Zuerst die beiden Seiten jedes Trades. Ein Maker ist, wer eine ruhende Limit-Order ins Book legt, die dort wartet; ein Taker ist, wer eine Order sendet, die sofort gegen vorhandene Liquidität ausgeführt wird. Maker zahlen weiterhin null Gebühren und erhalten obendrein ein Rebate; nur Taker zahlen eine Fee.

Die Taker-Fee ist kein fester Prozentsatz. Sie folgt einer Kurve, die sowohl von der Ordergrösse als auch vom Preis abhängt:

fee = shares × feeRate × price × (1 - price)

Der Term price × (1 - price) ist bei einem Preis von 0,50 (einem echten Münzwurf-Markt) maximal und schrumpft Richtung 0 oder 1. Mit anderen Worten: Auf den unsichersten Markets zahlst du die höchste Fee und auf nahezu entschiedenen fast nichts. Die feeRate wird pro Kategorie festgelegt:

  • Crypto: feeRate 0,07 (am höchsten, Spitzenwert um 1,8% effektiv), Maker-Rebate 20%.
  • Sports: feeRate 0,03 (Spitzenwert um 0,75%), Maker-Rebate 25%.
  • Finance, Politics, Tech, Mentions: feeRate 0,04, Maker-Rebate 25%.
  • Economics, Culture, Weather, allgemein: feeRate 0,05, Maker-Rebate 25%.
  • Geopolitics und grosse Weltereignisse: 0, weiterhin gebührenfrei.

Ein Rechenbeispiel. Angenommen, dein Bot nimmt 100 Shares eines Crypto-Markets zum Preis von 0,50. Die Fee beträgt 100 × 0,07 × 0,50 × (1 - 0,50) = 100 × 0,07 × 0,25 = $1,75. Nimmst du dieselben 100 Shares stattdessen bei 0,90, sinkt die Fee auf 100 × 0,07 × 0,90 × 0,10 = $0,63, weil der Preis weit von der unsicheren Mitte entfernt ist. Für einen Bot ist die Lehre eindeutig: Liquidität in volatilen, nahezu ausgeglichenen Crypto- und Sports-Markets zu nehmen, kostet am meisten Fee - genau dort lohnt es sich also am meisten, als Maker zu quoten und das Rebate zu kassieren, statt die Fee zu zahlen.

Zusätzlich zur expliziten Fee zahlst du jedes Mal den Bid-Ask-Spread, wenn du ihn kreuzt. Der Spread ist die Lücke zwischen dem besten Kauf- und dem besten Verkaufspreis, und bei einer Strategie, die per Taker ein- und aussteigt, ist diese Lücke eine echte Kostenposition zusätzlich zur Fee. Rechne bei typischen Books mit 1-3 Cents Round-Trip, bei illiquiden mehr. NegRisk-Markets (die Multi-Outcome-Exchange) nutzen dasselbe Fee-Modell, settlen aber auf einem separaten Contract, sodass ihre Rewards separat auflaufen. Kapitel 19 behandelt Liquidity-Rewards-Farming, wo das Kassieren von Maker-Rebates die Strategie selbst ist und nicht nur ein Nebeneffekt.

Code: WS verbinden und Price-Change-Events verarbeiten

Minimales Node-Beispiel: verbinden, abonnieren, jedes Price-Change-Event für ein Token loggen.

import WebSocket from "ws";
const ws = new WebSocket("wss://ws-subscriptions-clob.polymarket.com/ws/market");
ws.on("open", () => {
  ws.send(JSON.stringify({ type: "Market", markets: ["<CONDITION_ID>"] }));
});
ws.on("message", (data) => {
  const msg = JSON.parse(data.toString());
  if (msg.event_type === "price_change") {
    console.log("price_change", msg.asset_id, msg.changes);
  } else if (msg.event_type === "book") {
    console.log("book snapshot", msg.bids?.[0], msg.asks?.[0]);
  }
});
ws.on("close", () => console.log("closed"));
ws.on("error", (e) => console.error("err", e.message));

Abonniere bequem bis zu etwa 30 Tokens pro WebSocket-Verbindung. Darüber hinaus solltest du auf mehrere Verbindungen aufteilen - der Server wirft gelegentlich große Subscriptions kommentarlos weg, was zu stillen, veralteten Book-Reads führt.

Reconnect und Gap-Handling

Eine langlebige WebSocket-Verbindung wird ausfallen. Cloudflare zyklisiert Verbindungen alle paar Stunden; Netzwerke blinken; Polymarket deployt gelegentlich. Plane dafür.

Reconnect-Strategie: Bei close oder error warte mit Jitter min(2^attempt, 30) Sekunden und abonniere dann erneut. Setze den Attempt-Count nach der ersten erfolgreichen Message nach dem Reconnect zurück.

Gap-Handling ist wichtiger als Reconnect-Geschwindigkeit. Während das WebSocket getrennt war, hat sich das Book bewegt. Nach jedem Reconnect rufe den REST-Snapshot jedes abonnierten Tokens erneut ab und gleiche ab: Jede offene Position, deren Book sich spürbar bewegt hat, braucht eine erneute State-Prüfung, Exits müssen möglicherweise ausgelöst werden, Alarme könnten veraltet sein. Der Fall "Ich habe 30 Sekunden Book-Updates verpasst" ist der stille Killer langlaufender Bots - sie laufen auf veraltetem Zustand weiter und platzieren Orders zu Preisen, die nicht mehr existieren.

Defensives Muster: Snapshot von jedem abonnierten Book einmal pro Minute, unabhängig vom WebSocket-Status, und das WS als Fast-Path-Optimierung über dem Snapshot-Poll behandeln.

Häufig gestellte Fragen

Was ist der Polymarket CLOB API-Endpunkt?
Der zentrale CLOB-Endpunkt ist https://clob.polymarket.com (REST) und wss://ws-subscriptions-clob.polymarket.com/ws/market (WebSocket). Das sind die V2-Endpunkte, die von @polymarket/clob-client-v2 und py-clob-client verwendet werden.
Brauche ich einen API-Key, um das Order Book zu lesen?
Nein. Order-Book-Lesezugriffe (Snapshots und WebSocket-Subscriptions) sind öffentlich und benötigen keine Authentifizierung. Einen API-Key brauchst du nur zum Platzieren/Stornieren von Orders und zum Lesen kontospezifischer Daten (Positionen, Fills).
Wie schnell pusht das CLOB WebSocket Price-Updates?
So schnell, wie Orders gematcht werden. Aktive Markets sehen Updates alle paar hundert Millisekunden; dünne Markets aktualisieren sich nur bei tatsächlichen Orders. Sowohl Depth-Änderungen als auch Trade-Events laufen über denselben WS-Channel - parse den Event-Typ, um alles korrekt zu behandeln.
Wie berechne ich den Mid-Price eines Polymarket-Order-Books?
mid = (best_bid + best_ask) / 2, wenn beide existieren; andernfalls verwende last_trade_price als Fallback. Sei vorsichtig bei dünnen Books, in denen best_bid weit unter best_ask liegt - der Mid kann dann bedeutungslos sein. Berücksichtige immer auch den Spread, bevor du den Mid als fairen Preis behandelst.
Wie hoch ist die Maker Fee auf Polymarket im Jahr 2026?
Maker zahlen 0% und erhalten ein Rebate (20% bei Crypto, 25% bei den meisten anderen Kategorien). Nur Taker zahlen eine Fee, und sie ist nicht fest: Sie folgt fee = shares × feeRate × price × (1 - price) und ist damit bei Münzwurf-Markets nahe 0,50 am höchsten und schrumpft zu den Rändern hin. Die feeRates je Kategorie reichen von 0,03 (Sports, ca. 0,75% effektiver Spitzenwert) bis 0,07 (Crypto, ca. 1,8% effektiver Spitzenwert), wobei Geopolitics weiterhin gebührenfrei ist. Diese Maker-Taker-Asymmetrie ist der Grund, warum aktive Bots fast immer mit ruhenden Limit Orders quotieren, statt den Spread mit Market Orders zu kreuzen.
Wie gehe ich mit WebSocket-Disconnects um?
Verbinde mit exponential backoff neu (1s, 2s, 4s, max. 30s), abonniere dieselben Markets erneut und hole einen REST-Snapshot neu, um jede Lücke zu schließen. Vertraue niemals einem veralteten Order Book - wenn du länger als 5 Sekunden getrennt warst, fordere vor dem Platzieren von Orders einen frischen Snapshot an.