Polymarket-API-Leitfaden - Bau deinen ersten Trading-Bot 2026

Kapitel 27 von 33

Die Kurzfassung

Polymarket stellt drei öffentliche APIs bereit: CLOB (Handel), Gamma (Markt-Discovery) und Data (Analytik). Das offizielle Python-SDK ist py-clob-client 0.34.6. Die Authentifizierung nutzt einen API-Key + ECDSA-Signatur, wobei Orders über EIP-712 durch eine Polygon-Proxy-Wallet signiert werden. Rate-Limits deckeln dich auf grob 60 Orders/Minute pro Key. Der mit Abstand größte Stolperstein für neue Entwickler ist das condition_id → token_id-Mapping-Problem zwischen Gamma und CLOB - löse das zuerst, und alles andere fügt sich. Grob 40 Mio. $/Monat an Liquiditäts-Rewards und bot-vereinnahmtem Spread werden auf Polymarket verdient, fast ausschließlich von API-Nutzern.

Teil 1: Die drei APIs

Polymarket trennt die Zuständigkeiten sauber über drei verschiedene Dienste. Für jede Aufgabe die richtige API zu nutzen hält deinen Bot schnell, einfach und innerhalb der Rate-Limits.

Eine typische Bot-Schleife nutzt Gamma, um Märkte zu finden, CLOB, um Orderbücher abzurufen und Trades zu platzieren, und Data, um die Strategie-Performance offline zu backtesten. Stell dir Gamma als den „Katalog“ vor, CLOB als die „Börse“ und Data als das „Lagerhaus“.

Teil 2: Authentifizierung & das Proxy-Wallet-Modell

Polymarket signiert Trades nicht mit dem Private Key deiner Haupt-Wallet. Stattdessen nutzt es eine Gnosis-Safe-artige Proxy-Wallet: Deine Haupt-Wallet autorisiert einen Proxy, und der Proxy führt alle Trades auf Polygon aus. Dein API-Bot spricht mit diesem Proxy.

Was du brauchst

• API-Key - in den Polymarket-Einstellungen → Developer generieren
• Private Key - der Key deiner Trading-Wallet (NICHT die Seed-Phrase deines Haupt-MetaMask)
• Funder-Adresse - deine Proxy-Wallet-Adresse (angezeigt in Einstellungen → Wallet)
• Chain-ID - 137 (Polygon-Mainnet)
• Signaturtyp - 1 (POLY_PROXY, Standard für Retail-Nutzer)

Teil 3: py-clob-client installieren

Das offizielle Python-SDK ist der schnellste Weg von null zur ersten Order. Wir nutzen Version 0.34.6, die Stand April 2026 aktuell ist.

# Create a virtual environment first
python3 -m venv venv
source venv/bin/activate # macOS/Linux
venv\Scripts\activate # Windows

# Install the SDK
pip install py-clob-client==0.34.6 requests websocket-client python-dotenv

Grundlegende Client-Konfiguration

import os
from dotenv import load_dotenv
from py_clob_client.client import ClobClient
from py_clob_client.constants import POLYGON

load_dotenv()

client = ClobClient(
 host="https://clob.polymarket.com",
 key=os.environ["POLY_PRIVATE_KEY"],
 chain_id=POLYGON, # 137
 signature_type=1, # POLY_PROXY
 funder=os.environ["POLY_FUNDER"],
)

# One-time: derive and cache API credentials
client.set_api_creds(client.create_or_derive_api_creds())

Der create_or_derive_api_creds()-Aufruf signiert eine Nachricht mit deinem Private Key und tauscht sie gegen einen API-Key, ein Secret und eine Passphrase. Cache diese nach dem ersten Lauf in deiner .env, damit du nicht bei jedem Start den Derive-Endpunkt triffst.

Teil 4: Märkte über Gamma entdecken

Bevor du handeln kannst, musst du handelnswerte Märkte finden. Gamma gibt JSON mit allem zurück, was die Polymarket-Oberfläche zeigt: Frage, Ausgänge, Preise, 24-Std.-Volumen, Ablauf, Tags und Bilder.

import requests

resp = requests.get(
 "https://gamma-api.polymarket.com/markets",
 params={
 "active": "true",
 "closed": "false",
 "tag_slug": "politics",
 "limit": 20,
 "order": "volume24hr",
 "ascending": "false",
 },
 timeout=10,
)
resp.raise_for_status()
markets = resp.json()

for m in markets:
 print(f"{m['slug']:50} Yes ${float(m['outcomePrices'][0]):.3f} Vol24h ${m.get('volume24hr', 0):,.0f}")

Nützliche Gamma-Abfrageparameter

Teil 5: Das condition_id → token_id-Mapping

Das ist der Schmerzpunkt Nr. 1 in der Polymarket-Bot-Entwicklung. Gamma gibt eine condition_id zurück (eine pro Markt). CLOB-Trades nutzen eine token_id (eine pro Ausgang). Du brauchst immer beide.

# Each Gamma market object contains 'clobTokenIds' - a JSON string array
import json

market = markets[0]
token_ids = json.loads(market['clobTokenIds']) # ['7410...', '1120...']
yes_token = token_ids[0] # First outcome
no_token = token_ids[1] # Second outcome

# Alternative: ask CLOB directly using condition_id
info = client.get_market(condition_id=market['conditionId'])
yes_token = info['tokens'][0]['token_id']

Outcome-Reihenfolge-Stolperstein

Gammas outcomes-Array und clobTokenIds-Array sind index-gematcht. Lies immer das Outcome-Label, statt anzunehmen, dass Index 0 „Yes“ ist. In Multi-Outcome-Märkten (NegRisk, Oscars, Wahlen) könnte Index 0 „Kamala Harris“ oder „Taylor Swift“ sein - die Reihenfolge ist deterministisch, aber marktspezifisch.

Teil 6: Orderbücher lesen

book = client.get_order_book(token_id=yes_token)

best_bid = float(book.bids[0].price) if book.bids else None
best_ask = float(book.asks[0].price) if book.asks else None
mid = (best_bid + best_ask) / 2 if best_bid and best_ask else None
spread = best_ask - best_bid if best_bid and best_ask else None

print(f"Bid {best_bid} Ask {best_ask} Mid {mid:.4f} Spread {spread:.4f}")

Orderbücher werden als sortierte Arrays zurückgegeben (Gebote absteigend, Briefe aufsteigend). Jede Ebene hat price und size. Um die Slippage für eine größere Order abzuschätzen, geh das Buch durch und akkumuliere Nominal, bis du deine Zielgröße verbraucht hast.

Teil 7: Orders platzieren

Limit-Order (GTC - der Standard)

from py_clob_client.clob_types import OrderArgs, OrderType

args = OrderArgs(
 token_id=yes_token,
 price=0.45,
 size=100, # Shares, not dollars. 100 shares @ $0.45 = $45 max cost.
 side="BUY",
)
signed_order = client.create_order(args)
response = client.post_order(signed_order, OrderType.GTC)
print(response)

Der create_order-Aufruf signiert eine EIP-712-strukturierte Nachricht mit deinem Private Key. post_order übermittelt sie an CLOB. Du sendest nie rohe Private Keys über die Leitung - nur signierte Orders.

Ordertypen

Stornieren

# Single order
client.cancel(order_id="0xabc...")

# Cancel all orders on a specific market
client.cancel_market_orders(market=market['conditionId'])

# Nuclear option: cancel everything
client.cancel_all()

Teil 8: WebSocket-Streaming

Gamma jede Sekunde abzufragen ist verschwenderisch, und du triffst schnell auf Rate-Limits. Der WebSocket-Feed streamt Echtzeit-Orderbuch- und Trade-Updates mit Sub-Sekunden-Latenz.

import json, websocket

WS_URL = "wss://ws-subscriptions-clob.polymarket.com/ws/market"

def on_open(ws):
 ws.send(json.dumps({
 "type": "market",
 "assets_ids": [yes_token, no_token],
 }))

def on_message(ws, message):
 event = json.loads(message)
 if event.get("event_type") == "price_change":
 print(f"{event['market']} {event['side']} {event['price']} size={event['size']}")

ws = websocket.WebSocketApp(
 WS_URL,
 on_open=on_open,
 on_message=on_message,
)
ws.run_forever(ping_interval=20)

Zwei Feeds existieren: der /market-Feed (öffentliches Orderbuch + Trades) und der /user-Feed (deine eigenen Order- und Fill-Events, authentifiziert). Produktions-Bots verbinden sich typischerweise mit beiden, reconnecten automatisch bei Trennung und behandeln den WebSocket als Quelle der Wahrheit für den aktuellen Buchzustand.

Teil 9: Rate-Limits & Backoff

Wenn du auf einen HTTP 429 triffst, gibt der Server einen Retry-After-Header zurück. Implementiere exponentielles Backoff mit Jitter:

import random, time

def post_with_backoff(fn, *args, max_retries=6):
 for attempt in range(max_retries):
 try:
 return fn(*args)
 except Exception as e:
 if "429" in str(e):
 sleep = (2 ** attempt) + random.random()
 time.sleep(min(sleep, 30))
 continue
 raise
 raise RuntimeError("Too many retries")

Teil 10: Eine Referenz-Bot-Architektur

Jeder robuste Polymarket-Bot hat dieselben sechs Komponenten. Bau jede als eigenes Modul; halte sie lose gekoppelt.

Teil 11: Häufige Fehlermodi

• Veraltete WebSocket-Daten - Verfolge die Zeit der letzten Nachricht pro Asset; wenn es auf einem aktiven Markt >30s keine Updates gibt, erzwinge einen REST-Refresh.
• Nonce-Kollisionen - py-clob-client handhabt Order-Nonces für dich, aber wenn du deinen eigenen Signer baust, inkrementiere die Nonce bei jeder Order.
• Unzureichendes Guthaben - Prüfe immer das pUSD-Guthaben vor dem Platzieren; das Buch könnte deine Order zeigen, aber das Matching wird sie ablehnen.
• Markt pausiert oder löst auf - Prüfe market.active && !market.closed vor dem Handel. Gamma-Updates hinken CLOB rund um die Auflösung um ein paar Sekunden hinterher.
• NegRisk-Adapter-Mismatch - Multi-Outcome-Märkte laufen über einen separaten NegRisk-Adapter. Das SDK handhabt es, aber bestätige, dass deine Order an den richtigen Schauplatz ging.

Teil 12: Liquiditäts-Rewards über die API

Polymarket betreibt ~5 Mio. $/Monat an allgemeinen Liquiditäts-Rewards plus 5 Mio.+ $/Monat an sportspezifischen Rewards (siehe Liquiditäts-Rewards). Die große Mehrheit fließt an API-getriebene Market-Maker, die enge zweiseitige Quotes über Tausende von Märkten halten können.

Die Reward-Formel belohnt Orders nahe dem Mittelpunkt, Größe und Zeit-im-Buch. Eine minimale Market-Making-Schleife:

1. Orderbuch für den Zielmarkt lesen
2. Einen fairen Mittelpunkt berechnen (z. B. VWAP der obersten 3 Ebenen je Seite)
3. Ein Gebot bei mid − spread_target/2 und einen Brief bei mid + spread_target/2 posten
4. Bei jedem WebSocket-Update neu bepreisen, wenn dein Quote mehr als einen Tick vom Ziel driftet
5. Stornieren und aussteigen, wenn das Buch dünn wird oder Nachrichten einschlagen

Teil 13: In Produktion gehen

• Hosting: ein 6-$/Monat-VPS (Hetzner, DigitalOcean) in Europa oder US-East reicht für die meisten Bots. Co-Locate mit Polygon-RPC, wenn du Sub-10-ms-Latenz brauchst.
• RPC: nutze Alchemy, Infura oder QuickNode für zuverlässiges Polygon-RPC. Free-Tiers reichen, bis du Hunderte von Orders pro Minute platzierst.
• Monitoring: Prometheus + Grafana für Metriken; ein Telegram-Bot für Alarme. Protokolliere jede Order-ID, die du sendest, und jeden Fill, den du erhältst.
• Backups: persistiere den Zustand jede Minute. Wenn der VPS mitten im Fill stirbt, willst du in Sekunden fortsetzen, nicht von Hand abgleichen.
• Steuer: dein Logger ist auch dein Prüfpfad - siehe Steuer-Leitfaden.

Teil 14 - Validierte Profi-Tipps für die Polymarket-API

Situation → Aktion - Spickzettel

Was kommt als Nächstes?

• Tools & Ressourcen - Drittpartei-Dashboards, Analytik und Daten-Feeds, die die API ergänzen
• Fortgeschrittene Strategien - Multi-Leg-Arbitrage und optionsähnliche Konstruktionen, die für Bots geeignet sind
• Liquiditäts-Rewards - genaue Formeln zum Verdienen von Market-Making-Rebates
• Orderbuch-Leitfaden - tiefere Intuition für das Lesen des Buches, bevor du dagegen programmierst
• Glossar - klar verständliche Definitionen jedes Begriffs in diesem Leitfaden