Build a Polymarket bot: scanner, sizing, execution, monitoring

Dieser Leitfaden zeigt, wie Sie einen Polymarket-Bot bauen, der kontinuierlich Märkte scannt, Chancen bemisst, über das CLOB ausführt und die Performance überwacht. Er konzentriert sich auf Architektur und Entwicklerpatterns, die Sie mit den öffentlichen APIs von Polymarket und dem Relayer-Modell implementieren können.

Wesentliche Erkenntnisse

• Architekturieren Sie den Bot als vier unabhängige Dienste: Scanner, Sizer, Executor und Monitor.
• Verwenden Sie Gammas und CLOB-APIs für Listings und Orderplatzierung; WebSocket für Echtzeit-Book-Updates.
• Bevorzugen Sie FAK-Market-Orders für Ausführung mit beliebiger Geschwindigkeit, berücksichtigen Sie aber immer Slippage und Gebühren.
• Instrumentieren Sie Monitoring und schnelle Kill-Switches für Oracle-Dispute, Siedlungsverzögerungen oder unerwartete Fills.

Warum diese Struktur

Handelssysteme sind leichter nachvollziehbar, wenn Verantwortlichkeiten getrennt sind. Ein Scanner findet Kandidaten-Edges, ein Sizer wandelt Edge in eine Positionsgröße um, ein Executor platziert Orders über das CLOB und ein Monitor stellt Korrektheit und Sicherheit sicher. Diese Trennung erlaubt Skalierung, Testing und getrennte Betrachtung von Latenz und Risiko.

H2: Data sources and APIs

Beginnen Sie damit, diese Polymarket-Endpunkte in Ihre Dienste zu integrieren:

• Gamma (Markt-Metadaten): https://gamma-api.polymarket.com — markets, events, tags, series. Verwenden Sie Paginierung mit after_cursor; vermeiden Sie offset.
• CLOB (Orderbuch & Trading): https://clob.polymarket.com — Orderbook-Reads sind öffentlich; Trading erfordert API key + HMAC. Die CLOB-SDKs übernehmen Orderplatzierung.
• Market WebSocket (Echtzeit-Book): wss://ws-subscriptions-clob.polymarket.com/ws/market — abonnieren Sie book, price_change, best_bid_ask und tick_size_change. PING alle 10s.
• Data API (Positionen, open interest): https://data-api.polymarket.com für Post-Trade-Analysen.

Design-Notiz: Kombinieren Sie Gamma-Listings mit dem WebSocket-Feed für effizientes Live-Scanning. Respektieren Sie Gamas Rate-Limits (z. B. /markets Caps) und die CLOB-Schlüsselanforderungen für Orderplatzierung.

H2: Scanner — finding candidate opportunities

Funktion

Der Scanner entdeckt Chancen, die zu Ihrer Strategie passen: intra-market binary spreads, multi-outcome Summen oder Endgame-Muster. Er sollte zustandslos, horizontal skalierbar und auf die Berechnung roher Edges fokussiert sein.

Inputs und Takt

• Abonnieren Sie den Market WebSocket mit custom_feature_enabled: true, um best_bid_ask- und Tick-Änderungen zu erhalten.
• Backfillen Sie mit Gamma /markets, wenn Sie ein neues Instrument zum ersten Mal sehen, um Metadaten und Outcomes zu erhalten.
• Pflegen Sie eine kleine In-Memory-Ansicht von best asks/bids für jedes Outcome.

Edge-Berechnung

• Binary intra-market: berechnen Sie edge = 1.00 - (bestAsk(YES) + bestAsk(NO)). Ein positiver Edge ist ein Kandidat.
• Multi-outcome: edge = 1.00 - sum(bestAsk(outcomes)).

Schwellen und Filter

• Mindest-Edge-Schwelle (z. B. > konfigurierte Cents), um Taker-Gebühren und Ausführungsrisiko abzudecken.
• Mindestliquiditätsprüfungen: Tiefe am best ask muss die Mindest-Fill-Size erfüllen.
• Tick-Size-Awareness: Berücksichtigen Sie tick_size_change-Events — Preisgranularität kann sich nahe Extremen auf $0.001 ändern.

H2: Sizing — risk and capital allocation

Ziele

Sizing wandelt einen rohen Edge in einen Orderplan um: wie viele Shares pro Outcome zu kaufen sind und wie Bestellungen aufgeteilt werden, um Slippage zu begrenzen.

Komponenten

• Exposure-Caps: per-Markt und global pUSD-Exposure-Limits.
• Depth-limited Sizing: Berechnen Sie das kumulative Volumen an aufeinanderfolgenden Preisstufen auf der Ask-Seite; dimensionieren Sie nur bis zum Volumen, das erwartete Slippage innerhalb der Toleranz hält.
• Fee-Allowance: Ziehen Sie erwartete Taker-Gebühren (variabel, bis zu 1.8% in einigen Kategorien) vom Brutto-Edge ab, bevor Sie entscheiden zu handeln.

Praktisches Muster

• Beginnen Sie konservativ: Bevorzugen Sie mehrere kleine FAK-Market-Orders statt einer großen Order, es sei denn, Sie kontrollieren das Buch.
• Wenn Sie ein komplettes Set via CTF split/merge ausführen, berücksichtigen Sie die Kosten von split/merge (vom Relayer gehandhabt) und mögliche Rundung aufgrund der Tick-Size.

H2: Executor — placing orders and handling fills

Ordertypen und Beschränkungen

• Verwenden Sie den CLOB-Trading-Endpunkt für Orderplatzierung: https://clob.polymarket.com. Das CLOB-SDK und der Relayer verwalten Wallet-Deployment, Approvals und Order-Signing.
• Für Geschwindigkeit verwenden Sie FAK (Fill-And-Kill) Market-Orders, wo angebracht. FAKs führen sofort aus oder cancelln; sie helfen, verweilende Exposures zu vermeiden, können aber partial-fill auftreten.

Ausführungsablauf

1. Bereiten Sie die Trade-Intention vor: Liste von Outcome-Token-IDs und Zielmengen, die vom Sizer zurückgegeben wurden.
2. Wenn Sie ein Multi-Outcome-Complete-Set ausführen, können Sie stattdessen eine CTF split (ein komplettes Set minten) und dann Beine verkaufen — der Relayer und das SDK abstrahieren CTF-Operationen.
3. Senden Sie Orders über die CLOB-Trading-API mit korrekten Attribution-Headern, falls Sie Teil des Builder Program sind.
4. Beobachten Sie Fills über den WebSocket last_trade_price und best_bid_ask-Updates oder über CLOB-Trade-Responses.

Sicherheit und Abgleich

• Verfolgen Sie partielle Fills und canceln Sie Restmengen oder repricen Sie sofort.
• Reconciliieren Sie on-chain CTF-Balances (via Data API) nach Fills, um sicherzustellen, dass Sie tatsächlich die Outcome-Tokens halten, die Sie erwarten.
• Implementieren Sie Idempotency-Keys und Nonce-Handling für Order-Retries.

H2: Monitoring and operational safety

Was zu überwachen ist

• Fill-Raten, durchschnittliche Slippage gegenüber Erwartung, realisierter Edge nach Gebühren.
• Latenz zwischen WebSocket-Updates und Order-Submission.
• Ungewöhnliche Ereignisse: UMA-Disputes, tick_size_change, Marktplatz-weite Ausfälle.

Alerts und Kill-Switches

• Automatisierter Soft Kill: Pausieren Sie neue Orderplatzierung, wenn das netto realisierte P&L unter eine Schwelle fällt oder wenn Fill-Slippage Limits überschreitet.
• Hard Kill: Stoppen Sie sofort allen Traffic, wenn UMA einen Disput für einen Markt meldet, in dem Sie Positionen halten, oder wenn der Relayer Siedlungsprobleme signalisiert.

Audit-Logs und Observability

• Speichern Sie alle Order-Intents, rohen Marktsnapshots und ausgeführte Fills. Verwenden Sie diese Logs für Post-Mortem und Backtesting.
• Taggen Sie Logs mit market id, condition_ids und request ids, um Gamma- und CLOB-Datensätze abzugleichen.

H2: Builder Program, credentials, and rate limits

Wenn Sie Orders mit Attribution routen wollen, treten Sie dem Builder Program bei und verwalten Sie Keys über Polymarket-Einstellungen. Builder-Tiers steuern tägliche Relayer-Limits und Rewards. Für Trading über das CLOB benötigen Sie API key + HMAC und müssen Rate-Limits und Relayer-Quotas respektieren.

H2: Common risks and mitigations

Nehmen Sie niemals an, dass der mathematische Edge garantiert ist. Risiken, die Sie berücksichtigen müssen:

• Resolution-Risiko: UMA-Disputes können Auszahlungen anhalten oder ändern.
• Slippage und partielle Fills: FAKs können partial-fill; planen Sie für Rest-Exposure.
• Gebühren: Taker-Gebühren variieren nach Kategorie und können kleine Edges aufzehren (Geopolitics ist gebührenfrei).
• Siedlungszeit: Redeem/merge-Zeiten und Oracle-Resolution-Delays können Kapital binden.
• Smart-Contract- oder Relayer-Ausfälle: Instrumentieren Sie Fallbacks und menschliche Alarmierung.

Wie sich das auf Ihr Trading auswirkt

Designen Sie Ihren Bot so, dass jede Trade-Einheit klein, beobachtbar und innerhalb Ihrer Risikolimits reversibel ist. Konservatives Sizing, schnelles Monitoring und klare Kill-Bedingungen reduzieren Tail-Risiken. Verwenden Sie die Gamma- und CLOB-Endpunkte für deterministischen Marktstatus und bevorzugen Sie FAK-Orders für schnelle Ausführung, messen Sie aber stets realisierte Slippage gegen Erwartungen.

Abschluss

Die obige Architektur liefert ein pragmatisches Blueprint, um einen Polymarket-Trading-Bot zu bauen: einen hochdurchsatzfähigen Scanner, einen konservativen Sizer, einen robusten Executor mit CLOB und Relayer sowie geschichtetes Monitoring. Starten Sie klein, instrumentieren Sie aggressiv und iterieren Sie bei Sizing und Filtern, während Sie Live-Daten sammeln.

Frequently asked questions

Which APIs should I use to get market listings and live book data?

Use https://gamma-api.polymarket.com for market metadata (/markets) and wss://ws-subscriptions-clob.polymarket.com/ws/market for real-time order book and best_bid_ask events. Use https://clob.polymarket.com for order-book reads and trading; reads are public but trading requires API key + HMAC.

Should I use limit orders or market (FAK) orders for arbitrage?

FAK (Fill-And-Kill) market orders are commonly used for speed and to avoid lingering exposure. They can partial-fill, so design sizing and reconciliation accordingly. The CLOB SDK exposes helpers for creating FAK market orders.

How do I account for fees when sizing trades?

Subtract expected taker fees from your gross edge before trading. Taker fees vary by category (0% to 1.8% currently). Use a net-edge threshold that covers fees plus expected slippage and monitoring buffers.

What monitoring is essential for a live bot?

Monitor fill rates, realized slippage, latency, UMA dispute notices, tick_size_change events, and Relayer health. Implement soft and hard kill-switches for large slippage, P&L drawdowns, or oracle disputes.

Can I route orders through the Builder Program?

Yes. The Builder Program lets third parties route orders with attribution and earn builder fees. Tiers control daily relayer limits and rewards; credentials are obtained at polymarket.com/settings.