Polymarket API-Leitfaden – Baue deinen ersten Trading-Bot im Jahr 2026

Die Kurzfassung

Polymarket stellt dir drei öffentliche APIs bereit (eine API ermöglicht Programmen, automatisch Daten zu lesen oder Trades zu platzieren): CLOB (Trading), Gamma (Marktsuche) und Data (Analysen). Das offizielle Python-SDK ist py-clob-client 0.34.6. Die Authentifizierung erfolgt über einen API-Schlüssel + ECDSA-Signatur, und Orders werden über EIP-712 durch ein Polygon-Proxy-Wallet signiert. Rate Limits begrenzen dich auf ungefähr 60 Orders pro Minute je Schlüssel. Der größte Stolperstein für neue Entwickler ist das condition_id → token_id Mapping-Problem zwischen Gamma und CLOB. Löse das zuerst, dann wird der Rest deutlich einfacher. Auf Polymarket werden ungefähr 40 Millionen US-Dollar pro Monat durch Liquiditätsprämien und von Bots vereinnahmte Spreads verdient, fast vollständig von API-Nutzern.

Teil 1: Die drei APIs

Polymarket verteilt die Aufgaben klar auf drei separate Services. Wenn du für jede Aufgabe die passende API nutzt, bleibt dein 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 „Lager“.

Teil 2: Authentifizierung & das Proxy-Wallet-Modell

Polymarket signiert Trades nicht mit dem privaten Schlüssel deines Haupt-Wallets. Stattdessen wird ein Proxy-Wallet im Stil von Gnosis Safe verwendet. Dein Haupt-Wallet autorisiert einen Proxy, und der Proxy führt alle Trades auf Polygon aus. Dein API-Bot kommuniziert mit diesem Proxy.

Was du brauchst

• API-Schlüssel – in Polymarket Settings → Developer erstellen
• Privater Schlüssel – der Schlüssel deines Trading-Wallets (NICHT deine Haupt-Seed-Phrase aus MetaMask)
• Funder-Adresse – die Adresse deines Proxy-Wallets (angezeigt unter Settings → Wallet)
• Chain ID – 137 (Polygon mainnet)
• Signature type – 1 (POLY_PROXY, Standard für Retail-Nutzer)

Teil 3: py-clob-client installieren

Das offizielle Python SDK ist der schnellste Weg vom Start bis zur ersten Order. Wir verwenden Version 0.34.6 – das aktuelle Release auf PyPI (Februar 2026) und die Version, die nahezu jeder produktive Bot nutzt.

# 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 Aufruf create_or_derive_api_creds() signiert eine Nachricht mit deinem privaten Schlüssel. Im Gegenzug erhältst du einen API-Key, ein Secret und eine Passphrase. Speichere diese Werte nach dem ersten Lauf in deiner .env, damit du nicht bei jedem Start den Derive-Endpunkt aufrufst.

Teil 4: Märkte über Gamma finden

Bevor du handeln kannst, musst du Märkte finden, bei denen sich Trading lohnt. Gamma liefert JSON mit allem, was auch die Polymarket-Oberfläche anzeigt: Frage, Outcomes, Preise, 24-Stunden-Volumen, Ablaufdatum, 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: Die Zuordnung von condition_id zu token_id

Das ist der häufigste Stolperstein beim Bau von Polymarket-Bots. Gamma liefert eine condition_id (eine pro Markt). CLOB-Trades verwenden eine token_id (eine pro Outcome). Du brauchst immer beides.

# 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']

Stolperstelle bei der Outcome-Reihenfolge

Das outcomes-Array und das clobTokenIds-Array von Gamma sind indexgleich. Lies immer das Outcome-Label. Gehe nicht davon aus, dass Index 0 "Yes" ist. In Märkten mit mehreren Outcomes (NegRisk, Oscars, Wahlen) kann Index 0 auch "Kamala Harris" oder "Taylor Swift" sein. Die Reihenfolge ist fest, 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 (Bids absteigend, Asks aufsteigend). Jede Stufe hat einen price und eine size. Um die Slippage für eine größere Order abzuschätzen, gehst du das Buch durch und summierst den Nominalwert, bis deine Zielgröße gefüllt ist.

Teil 6b: Die CLOB v2 REST-Endpunkte (direkt, ohne SDK)

Das SDK kapselt diese Endpunkte. Wenn du die direkten Endpunkte kennst, kannst du aber besser debuggen, eine andere Sprache verwenden oder einen schlanken Client bauen. Basis-URL: https://clob.polymarket.com. Alle unten genannten Lesezugriffe sind öffentlich – keine Authentifizierung erforderlich. Sie wurden im Juni 2026 live verifiziert.

Verifizierte Antworten direkt aus der Live-API:

$ curl "https://clob.polymarket.com/price?token_id=7347...&side=buy"
{"price":"0.14"}

$ curl "https://clob.polymarket.com/midpoint?token_id=7347..."
{"mid":"0.21"}

$ curl "https://clob.polymarket.com/spread?token_id=7347..."
{"spread":"0.14"}

$ curl "https://clob.polymarket.com/tick-size?token_id=7347..."
{"minimum_tick_size":0.01}

L2-Auth-Header (für Raw-REST ohne SDK)

Lese-Endpunkte sind öffentlich. Um Orders über Raw-REST zu platzieren oder zu stornieren, signierst du jede Anfrage mit deinen API-Zugangsdaten. Das SDK übernimmt das für dich; hier siehst du, was es im Hintergrund erstellt:

Teil 7: Orders platzieren – Kaufen und Verkaufen

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 Aufruf create_order signiert eine strukturierte EIP-712-Nachricht mit deinem privaten Schlüssel. Anschließend übermittelt post_order sie an CLOB. Du sendest niemals rohe private Schlüssel über die Leitung – nur signierte Orders.

Richte deinen Preis zuerst am Tick aus

Jeder Orderpreis muss ein exaktes Vielfaches der minimum_tick_size des Marktes sein (0,01 bei den meisten Märkten, 0,001 bei engen Spreads). Ein Preis außerhalb des Tick-Rasters wird abgelehnt. Rufe den Tick einmal ab und runde darauf:

from py_clob_client.clob_types import OrderArgs, OrderType

tick = float(client.get_tick_size(token_id=yes_token))   # e.g. 0.01
def to_tick(p, tick): return round(round(p / tick) * tick, 4)

price = to_tick(0.453, tick)   # -> 0.45 on a 0.01 market

Kaufen

side="BUY", size wird in Anteilen angegeben (nicht in Dollar). 100 Anteile zu 0,45 US-Dollar kosten höchstens 45 US-Dollar und zahlen 100 US-Dollar aus, wenn das Ergebnis gewinnt. Der Mindest-Orderwert liegt bei etwa 1 US-Dollar.

buy = OrderArgs(token_id=yes_token, price=to_tick(0.45, tick), size=100, side="BUY")
resp = client.post_order(client.create_order(buy), OrderType.GTC)
print(resp)   # {'success': True, 'orderID': '0x...', 'status': 'live', ...}

Verkaufen

Zum Verkaufen verwenden Sie denselben Aufruf mit side="SELL". Sie können nur Anteile verkaufen, die Sie bereits halten – ein Verkauf über Ihre Position hinaus wird mit dem Fehler „insufficient balance“ abgelehnt. Um eine Position zu schließen, verkaufen Sie denselben token_id, den Sie gekauft haben.

sell = OrderArgs(token_id=yes_token, price=to_tick(0.62, tick), size=100, side="SELL")
resp = client.post_order(client.create_order(sell), OrderType.GTC)

Orderparameter auf einen Blick

Alles zusammen: Ihr erster API-Trade (ein ausführbares Skript)

Das ist der komplette Ablauf von Anfang bis Ende: verbinden, einen liquiden Markt finden, das Orderbuch lesen, an die Tick-Größe anpassen, eine kleine echte Order platzieren und sie anschließend stornieren. Tragen Sie Ihre beiden Secrets ein und führen Sie das Skript aus. Beginnen Sie beim allerersten Durchlauf mit einem sehr kleinen Umfang (ein paar Dollar).

import os, json, requests
from dotenv import load_dotenv
from py_clob_client.client import ClobClient
from py_clob_client.constants import POLYGON
from py_clob_client.clob_types import OrderArgs, OrderType

load_dotenv()

# 1) Connect (signing key in your EOA, funds in your proxy/funder)
client = ClobClient(
    "https://clob.polymarket.com",
    key=os.environ["POLY_PRIVATE_KEY"],
    chain_id=POLYGON,            # 137
    signature_type=1,            # 1 = email/Magic proxy, 2 = browser-wallet proxy
    funder=os.environ["POLY_FUNDER"],
)
client.set_api_creds(client.create_or_derive_api_creds())   # cache these after first run

# 2) Find the most-traded open market (Gamma, no auth)
m = requests.get(
    "https://gamma-api.polymarket.com/markets",
    params={"active": "true", "closed": "false", "order": "volume24hr",
            "ascending": "false", "limit": 1}, timeout=10,
).json()[0]
token_id = json.loads(m["clobTokenIds"])[0]   # index 0 = first outcome (read the label!)
print("Trading:", m["question"])

# 3) Read the book + the tick size
tick = float(client.get_tick_size(token_id))
book = client.get_order_book(token_id)
best_ask = float(book.asks[0].price)
print("best ask", best_ask, "| tick", tick)

# 4) Place a small BUY at the ask (tiny size to start)
price = round(round(best_ask / tick) * tick, 4)      # snap to tick
order = OrderArgs(token_id=token_id, price=price, size=5, side="BUY")  # 5 shares
resp = client.post_order(client.create_order(order), OrderType.GTC)
print(resp)                                          # {'success': True, 'orderID': '0x...', ...}

# 5) Cancel it (clean up)
# client.cancel(order_id=resp["orderID"])

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 ineffizient, und Sie stoßen schnell an Rate Limits. Der WebSocket-Feed streamt Orderbuch- und Trade-Updates in Echtzeit mit Latenzen unter einer Sekunde.

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)

Es gibt zwei Feeds. Der /market-Feed enthält das öffentliche Orderbuch und Trades. Der /user-Feed enthält Ihre eigenen Order- und Fill-Events (authentifiziert). Produktions-Bots verbinden sich mit beiden, stellen die Verbindung nach einem Disconnect automatisch wieder her und behandeln den WebSocket als maßgebliche Quelle für das aktuelle Orderbuch.

Teil 9: Rate Limits & Backoff

Wenn eine HTTP 429 auftritt, gibt der Server einen Retry-After-Header zurück. Verwenden Sie 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 Referenzarchitektur für Bots

Jeder zuverlässige Polymarket-Bot besteht aus denselben sechs Komponenten. Implementieren Sie jede davon als eigenes Modul und halten Sie die Kopplung gering.

Teil 11: Häufige Fehlerursachen

• Ablehnung wegen ungültigem Tick-Preis - der Preis muss ein exaktes Vielfaches der minimum_tick_size des Marktes sein. Rufe sie über /tick-size?token_id= ab und runde, bevor du signierst, sonst wird die Order abgewiesen.
• 404 "No orderbook exists" - du hast /book, /price oder /midpoint für ein geschlossenes/aufgelöstes Token abgefragt. Verwende /sampling-markets, um Tokens mit aktivem Orderbuch zu finden.
• Veraltete WebSocket-Daten - erfasse pro Asset den Zeitpunkt der letzten Nachricht; wenn es in einem aktiven Markt länger als >30s keine Updates gibt, erzwinge eine REST-Aktualisierung.
• Nonce-Kollisionen - py-clob-client übernimmt die Order-Nonces für dich. Wenn du jedoch einen eigenen Signer verwendest, erhöhe die Nonce bei jeder Order.
• Unzureichendes Guthaben - prüfe immer das USDC-Guthaben, bevor du platzierst; das Orderbuch zeigt deine Order möglicherweise an, das Matching lehnt sie aber ab.
• Markt pausiert oder in Auflösung - prüfe vor dem Trading market.active && !market.closed. Gamma-Updates liegen CLOB rund um die Auflösung um einige Sekunden hinterher.
• NegRisk-Adapter passt nicht - Märkte mit mehreren Ergebnissen werden über einen separaten NegRisk-Adapter geroutet. Das SDK übernimmt das, aber prüfe, ob deine Order am richtigen Handelsplatz gelandet ist.

Teil 12: Liquiditätsprämien per API

Polymarket zahlt ca. 5 Mio. USD/Monat an allgemeinen Liquiditätsprämien sowie mehr als 5 Mio. USD/Monat an sportspezifischen Prämien aus (siehe Liquidity Rewards). Der Großteil davon geht an API-gesteuerte Market Maker. Sie stellen über Tausende von Märkten hinweg enge zweiseitige Quotes.

Die Prämienformel bevorzugt Orders nahe am Mittelpunkt, gewichtet nach Größe und Verweildauer im Orderbuch. Hier ist eine minimale Market-Making-Schleife:

1. Orderbuch für den Zielmarkt lesen
2. Einen fairen Mittelpunkt berechnen (z. B. VWAP der jeweils 3 besten Level auf beiden Seiten)
3. Ein Bid bei mid − spread_target/2 und ein Ask bei mid + spread_target/2 einstellen
4. Bei jedem WebSocket-Update neu bepreisen, wenn dein Quote mehr als einen Tick vom Ziel abweicht
5. Stornieren und aussteigen, wenn das Orderbuch ausdünnt oder Nachrichten die Lage verändern

Teil 13: In Produktion gehen

• Hosting: Ein VPS für 6 USD/Monat (Hetzner, DigitalOcean) in Europa oder US-East reicht für die meisten Bots aus. Platziere ihn nahe bei Polygon RPC, wenn du Latenzen unter 10 ms brauchst.
• RPC: Verwende Alchemy, Infura oder QuickNode für zuverlässiges Polygon RPC. Kostenlose Tarife reichen aus, bis du Hunderte von Orders pro Minute platzierst.
• Monitoring: Prometheus + Grafana für Metriken; ein Telegram-Bot für Benachrichtigungen. Protokolliere jede Order-ID, die du sendest, und jede Ausführung, die du erhältst.
• Backups: Speichere den Zustand jede Minute persistent. Wenn der VPS mitten in einer Ausführung ausfällt, willst du in Sekunden fortsetzen können, statt alles manuell abzugleichen.
• Steuern: Dein Logger ist zugleich dein Audit-Trail - siehe Tax Guide.

Teil 14 - Bewährte Pro-Tipps für die Polymarket API

Cheat Sheet: Situation → Action

Wie geht es weiter?

• Tools & Ressourcen - Drittanbieter-Dashboards, Analysen und Datenfeeds, die die API ergänzen
• Fortgeschrittene Strategien - Multi-Leg-Arbitrage und optionsähnliche Konstruktionen für Bots
• Liquiditätsprämien - genaue Formeln zum Verdienen von Market-Making-Rabatten
• Order-Book-Guide - tieferes Verständnis dafür, wie du das Book liest, bevor du dagegen programmierst
• Glossar - verständliche Definitionen aller Begriffe in diesem Leitfaden

Kurzcheck