DEV Community

Cover image for API-Designmuster von Polymarket: Der weltweit größte Vorhersagemarkt
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

API-Designmuster von Polymarket: Der weltweit größte Vorhersagemarkt

Prognosemärkte gehören zu den technisch anspruchsvollsten Bereichen der API-Entwicklung. Sie kombinieren ablaufende Finanzinstrumente, Wahrscheinlichkeiten mit Echtzeit-Preisbildung, Ereignisse mit mehreren Ergebnissen, komplexe Kapitalbeziehungen und eine Nutzerbasis aus UI-Nutzern sowie automatisierten Handelsbots mit Arbitrage-Strategien. Jede Designentscheidung wird dadurch unmittelbar auf Belastbarkeit geprüft.

Apidog noch heute ausprobieren

Polymarket, derzeit die weltweit größte Prognosemarkt-Plattform nach Volumen, hat deshalb ein API-Ökosystem aufgebaut, das sich als Referenz für API-Designer eignet. Es handelt sich nicht nur um eine CRUD-API über einer Datenbank, sondern um eine geschichtete Architektur für Offenheit und Sicherheit, Echtzeit- und historische Daten sowie traditionelle Finanzmuster und krypto-native Primitive.

Im Folgenden finden Sie acht konkrete Designmuster und Hinweise, wie Sie diese in eigenen APIs anwenden können.

Muster 1: Domänengetrennte API-Schichten

Polymarket stellt drei APIs mit klar abgegrenzten Verantwortlichkeiten bereit:

  • Gamma API (gamma-api.polymarket.com) — Marktentdeckung, Ereignisse, Tags und Suche
  • CLOB API (clob.polymarket.com) — Orderbuchdaten, Preise und Orderplatzierung
  • Data API (data-api.polymarket.com) — Benutzerpositionen, Trades, Analysen und Bestenlisten

Diese Trennung ist mehr als eine Namenskonvention. Jede API hat eigene Authentifizierungsanforderungen, Aktualisierungsfrequenzen und Konsumenten:

API Primärer Zweck Zugriff
Gamma API Märkte entdecken und durchsuchen Öffentlich
CLOB API Orderbücher lesen und handeln Öffentlich + authentifiziert
Data API Wallet-bezogene Daten und Analysen Öffentlich, über Wallet-Adresse adressiert

Die Gamma API ist für Browsing und Entdeckung optimiert. Bei der CLOB API kann jeder das Orderbuch lesen, während das Platzieren von Orders Anmeldeinformationen erfordert. Die Data API ist öffentlich, aber ihre Abfragen beziehen sich auf Wallet-Adressen.

Umsetzungshinweis

Trennen Sie APIs nach Nutzungskontext, nicht nur nach Entitäten.

Ein naiver Entwurf bündelt alles unter einer Basis-URL:

/markets
/orders
/users
Enter fullscreen mode Exit fullscreen mode

Ein domänenorientierter Entwurf stellt stattdessen diese Fragen:

  1. Wofür wird diese API genutzt?
  2. Welche Latenz benötigt dieser Anwendungsfall?
  3. Welche Authentifizierung ist erforderlich?
  4. Wie muss dieser Teil unabhängig skalieren?

Marktentdeckung hat andere Zugriffsmuster als Handel. Handel hat andere Latenzanforderungen als Analysen. Separate Basis-URLs erlauben es, diese Bereiche unabhängig weiterzuentwickeln, zu skalieren und abzusichern.

Muster 2: Öffentlichkeitsorientierter Datenzugriff

Marktdaten wie Preise, Orderbücher, Ereignismetadaten und historische Trades sind öffentlich abrufbar:

curl "https://gamma-api.polymarket.com/events?limit=5"
Enter fullscreen mode Exit fullscreen mode

Kein API-Schlüssel. Kein OAuth. Keine Rate Limits auf Lese-Endpunkten. Die Daten sind direkt verfügbar.

Das ist eine bewusste Architekturentscheidung. Traditionelle Börsen behandeln Marktdaten oft als Einnahmequelle. Polymarket behandelt sie als Infrastruktur: Je mehr Entwickler Daten abrufen und darauf aufbauen können, desto liquider und nützlicher kann der Markt werden.

Umsetzungshinweis

Behandeln Sie Lese- und Schreibzugriffe als getrennte Sicherheitsprobleme.

Für datenintensive Plattformen kann diese Matrix sinnvoll sein:

Operation Beispiel Authentifizierung
Öffentliche Daten lesen Preise, Kataloge, Metadaten Keine
Persönliche Daten lesen Positionen, Kontostand Nutzer- oder Wallet-Kontext
Zustand ändern Order erstellen, Zahlung auslösen Starke Authentifizierung
Kritische Aktion bestätigen Schlüssel erzeugen, Auszahlung freigeben Kryptografischer Nachweis oder MFA

Wenn Nutzer Marktpreise ohne Anmeldeinformationen abrufen können, entfällt Reibung für den größten Teil potenzieller Konsumenten. Authentifizierung sollte dort eingesetzt werden, wo tatsächlich eine geschäftskritische Aktion stattfindet.

Muster 3: Zweistufige Authentifizierung, die echtes Vertrauen abbildet

Handels-Endpunkte erfordern Authentifizierung. Polymarket verwendet dafür zwei Ebenen mit unterschiedlichen Aufgaben.

L1-Authentifizierung verwendet eine EIP-712-Signatur mit dem privaten Schlüssel des Nutzers. Sie beweist die Kontrolle über das Wallet und wird verwendet, um API-Anmeldeinformationen abzuleiten:

// L1: API-Anmeldeinformationen mit dem privaten Schlüssel ableiten
const credentials = await client.createOrDeriveApiKey();

// → { key: "...", secret: "...", passphrase: "..." }
Enter fullscreen mode Exit fullscreen mode

L2-Authentifizierung verwendet HMAC-SHA256 mit den abgeleiteten Anmeldeinformationen. Diese Header werden an jede Handelsanfrage angehängt:

// L2-Header für jede Handelsanfrage
{
  "POLY_ADDRESS": "0x...",
  "POLY_SIGNATURE": "<hmac-sha256>",
  "POLY_TIMESTAMP": "1716000000",
  "POLY_API_KEY": "550e8400-...",
  "POLY_PASSPHRASE": "..."
}
Enter fullscreen mode Exit fullscreen mode

Warum dieses Muster funktioniert

Verschiedene Operationen benötigen unterschiedliche Sicherheitsniveaus:

  • Das Erstellen oder Ableiten eines API-Schlüssels ist eine Aktion mit hohem Risiko. Sie sollte den Nachweis der Wallet-Kontrolle verlangen.
  • Routinemäßige Handelsanfragen müssen schnell und automatisierbar bleiben. Sie sollten nicht bei jedem Aufruf eine erneute Signatur mit dem privaten Schlüssel verlangen.

L1 etabliert Vertrauen. L2 nutzt dieses Vertrauen effizient für wiederkehrende Anfragen.

Übertragbares Muster

Dieses Prinzip funktioniert auch außerhalb von Krypto:

  • L1: „Beweise, dass du diese Identität kontrollierst.“
  • L2: „Beweise, dass diese einzelne Anfrage aus deiner autorisierten Sitzung stammt.“

Viele Anwendungen behandeln beide Probleme mit demselben Token. Eine explizite Trennung ermöglicht präzisere Sicherheitsmodelle.

Muster 4: Orders als signierte Nachrichten statt als gewöhnliche API-Aufrufe

Beim Platzieren einer Order auf Polymarket senden Sie nicht nur Daten an einen Server. Sie erstellen eine kryptografisch signierte Nachricht, die eine durchsetzbare finanzielle Verpflichtung repräsentiert:

const response = await client.createAndPostOrder(
  {
    tokenID: "71321045679...",
    price: 0.65,
    size: 100,
    side: Side.BUY,
  },
  {
    tickSize: "0.01",
    negRisk: false,
  },
  OrderType.GTC
);
Enter fullscreen mode Exit fullscreen mode

Das SDK erstellt im Hintergrund eine EIP-712-Datenstruktur, signiert sie mit dem privaten Schlüssel und übermittelt Signatur und Order an die Matching-Engine.

Die Matching-Engine arbeitet Off-Chain. Wenn Trades gematcht werden, erfolgt die Abwicklung über Polygon auf Basis dieser Signaturen. Der Operator kann keine Trades fälschen oder Gelder willkürlich bewegen: Die signierte Nachricht enthält die Autorisierung.

Umsetzungshinweis

Unterscheiden Sie zwischen zwei Semantiken:

Klassischer API-Aufruf:
"Bitte führe diese Aktion in meinem Namen aus."

Signierte Nachricht:
"Hier ist ein überprüfbares Instrument, das diese Aktion autorisiert."
Enter fullscreen mode Exit fullscreen mode

Wenn die Nutzlast selbst die Autorisierung trägt, statt sich ausschließlich auf Transport-Credentials zu verlassen, entstehen wichtige Eigenschaften:

  • Nichtabstreitbarkeit
  • Überprüfbarkeit
  • Entkopplung zwischen Autorisierung und Transport
  • Nachweisbare Zustimmung für hochkritische Aktionen

Dieses Muster eignet sich besonders für Finanzsysteme, juristische Dokumente und andere Aktionen mit hohem Schadenspotenzial.

Muster 5: Explizite Ontologie im Datenmodell

Polymarket strukturiert seine Daten um zwei zentrale Objekte: Events und Markets.

Ein Event ist eine übergeordnete Frage, zum Beispiel:

„Wer gewinnt das US-Senatsrennen 2026 in Pennsylvania?“

Ein Market ist ein konkretes handelbares binäres Ergebnis innerhalb dieses Events, zum Beispiel:

„Wird Bob Casey gewinnen?“

Ein Event kann mehrere Markets enthalten:

{
  "id": "501",
  "title": "2026 Pennsylvania Senate Race",
  "negRisk": true,
  "markets": [
    {
      "id": "2301",
      "question": "Will Bob Casey win?",
      "outcomePrices": "[\"0.42\", \"0.58\"]"
    },
    {
      "id": "2302",
      "question": "Will Dave McCormick win?",
      "outcomePrices": "[\"0.35\", \"0.65\"]"
    },
    {
      "id": "2303",
      "question": "Will a third candidate win?",
      "outcomePrices": "[\"0.23\", \"0.77\"]"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Die API liefert damit nicht nur Rohdaten, sondern kodiert die konzeptuellen Beziehungen der Domäne.

Beispielsweise sind Outcomes und Preise über ihre Indexposition verbunden:

outcomes[0] === outcomePrices[0];
Enter fullscreen mode Exit fullscreen mode

Zusätzlich signalisiert negRisk auf Event-Ebene, dass zwischen Märkten Kapitalbeziehungen bestehen, die bei unabhängigen Märkten nicht vorhanden sind.

Umsetzungshinweis

Machen Sie tragende Domänenbeziehungen im API-Modell sichtbar.

Verstecken Sie kritische Beziehungen nicht ausschließlich in Dokumentation oder impliziten Konventionen. Wenn ein Client negRisk: true ignoriert, kann er ein falsches Positionsmodell berechnen. Ein explizites Feld macht diese Abhängigkeit sichtbar und testbar.

Muster 6: NegRisk — Kapitalbeziehungen als erstklassiges API-Konzept

Das Feld negRisk verweist auf ein zentrales Muster: Finanzielle Äquivalenzen werden programmierbar gemacht.

In einem gewöhnlichen Multi-Outcome-Event ist jeder Market unabhängig. Bei einem NegRisk-Event, bei dem genau ein Ergebnis gewinnen kann, gilt jedoch folgende Beziehung:

1 No-Token auf Ergebnis A ≡ 1 Yes-Token auf jedem anderen Ergebnis

Wenn Sie beispielsweise eine No-Position auf „Andere“ im Senatsrennen von Pennsylvania halten, lässt sich diese Position konvertieren:

Vorher Nachher
1× Nein (Andere) 1× Ja (Casey) + 1× Ja (McCormick)

Die API macht diese Bedingung explizit:

  • negRisk: true im Marktobjekt
  • negRisk: true in den Orderoptionen beim Handel mit solchen Märkten

Wenn dieser Wert nicht korrekt gesetzt wird, kann eine Order abgelehnt oder falsch abgewickelt werden.

Umsetzungshinweis

Kodieren Sie Domäneninvarianten als typisierte API-Felder.

Nicht ausreichend:

Siehe Dokumentation: Diese Märkte haben besondere Regeln.
Enter fullscreen mode Exit fullscreen mode

Besser:

{
  "marketId": "2301",
  "negRisk": true,
  "requiresSpecialSettlementRules": true
}
Enter fullscreen mode Exit fullscreen mode

Wenn das Weglassen einer Information zu falschem Verhalten führt, gehört diese Information in die API-Oberfläche, nicht nur in einen Dokumentationsabschnitt.

Muster 7: Dynamische Tick-Größe als Marktstatus

Viele Finanz-APIs behandeln die Tick-Größe als statische Konfiguration. Polymarket behandelt sie als dynamischen Marktstatus.

Wenn ein Marktpreis an die Extreme gelangt — über 0.96 oder unter 0.04 — sinkt die minimale Tick-Größe von 0.01 auf 0.001:

{
  "event_type": "tick_size_change",
  "asset_id": "65818619657...",
  "old_tick_size": "0.01",
  "new_tick_size": "0.001",
  "timestamp": "100000000"
}
Enter fullscreen mode Exit fullscreen mode

Die Begründung: Bei extremen Wahrscheinlichkeiten ist ein Tick von einem Cent zu grob. Eine Änderung von 0.04 auf 0.03 entspricht bereits einer relativen Bewegung von 25 %. Kleinere Ticks ermöglichen präzisere Wahrscheinlichkeiten wie 97,3 % statt einer Rundung auf 97 %.

Umsetzungshinweis

Behandeln Sie veränderliche Konfiguration als Ereignis, nicht als einmalig abgerufenen Parameter.

Ein Client sollte nicht so implementiert werden:

const tickSize = "0.01"; // Fehleranfällig: fest codiert
Enter fullscreen mode Exit fullscreen mode

Stattdessen muss er Tick-Größenänderungen verarbeiten und seinen lokalen Zustand aktualisieren:

socket.on("tick_size_change", (event) => {
  tickSizes.set(event.asset_id, event.new_tick_size);
});
Enter fullscreen mode Exit fullscreen mode

Der WebSocket stellt tick_size_change-Ereignisse bereit, damit Clients ihre Orderkonstruktion mit dem aktuellen Marktstatus synchron halten können. Wer die Tick-Größe fest codiert, riskiert abgelehnte Orders.

Das allgemeine Prinzip lautet:

Finanz-APIs müssen Zustand als erstklassiges Konzept behandeln.

Marktparameter können sich ändern. Auflösungsregeln können angepasst werden. Ergebnisse können präzisiert werden. APIs sollten solche Zustandsübergänge aktiv kommunizieren, statt Clients sie erst über Fehlermeldungen entdecken zu lassen.

Muster 8: Zwei WebSocket-Schichten für unterschiedliche Konsumentenprofile

Polymarket betreibt zwei getrennte WebSocket-Systeme. Der Grund liegt in unterschiedlichen Anforderungen der Konsumenten.

Der Markt-Kanal (wss://ws-subscriptions-clob.polymarket.com/ws/market) richtet sich an Handelsanwendungen. Clients abonnieren Token-IDs und erhalten Orderbuch-Snapshots, Preisänderungen, Handelsausführungen und Tick-Größenänderungen.

{
  "assets_ids": [
    "65818619657568813474341868652308942079804919287380422192892211131408793125422"
  ],
  "type": "market"
}
Enter fullscreen mode Exit fullscreen mode

Der Echtzeit-Daten-Socket (wss://ws-live-data.polymarket.com) adressiert ein anderes Profil. Er streamt Kommentare, Krypto-Preise von Binance und Chainlink, Aktienkurse sowie soziale Interaktionsereignisse.

{
  "action": "subscribe",
  "subscriptions": [
    {
      "topic": "crypto_prices",
      "type": "update",
      "filters": "btcusdt,ethusd"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Umsetzungshinweis

Trennen Sie Echtzeit-Infrastruktur, wenn sich diese Faktoren stark unterscheiden:

  • Latenztoleranz
  • Datenvolumen
  • Fehlerverhalten
  • Zuverlässigkeitsanforderungen
  • Abonnementmodell
  • Zielgruppe

Ein Market Maker benötigt Orderbuch-Deltas mit minimaler Latenz. Eine Benutzeroberfläche für aktuelle Plattformaktivitäten benötigt dagegen Kommentare, soziale Ereignisse und breitere Feeds.

Ein gemeinsamer WebSocket-Endpunkt für beide Fälle führt oft zu einem ungünstigen Kompromiss:

  • Der Social Feed wird unnötig komplex und teuer.
  • Der Handels-Feed erfüllt seine Latenz- und Zuverlässigkeitsanforderungen nicht mehr zuverlässig.

Wenn Konsumenten grundlegend unterschiedliche Anforderungen haben, sollten sie getrennte Infrastruktur erhalten.

Was diese Muster gemeinsam haben

Das API-Design von Polymarket folgt einer klaren Philosophie: Die API soll die tatsächliche Struktur der Domäne sichtbar machen, nicht sie hinter einer generischen Abstraktion verstecken.

Die drei API-Schichten bilden reale Domänengrenzen ab. Der öffentliche Zugriff auf Daten reflektiert den Nutzen offener Marktinformationen. Die zweistufige Authentifizierung trennt Identitätsnachweis und laufende Anfragesignierung. Signierte Orders kodieren eine nicht-treuhänderische Autorisierung. Die Event/Market-Hierarchie und negRisk machen finanzielle Beziehungen explizit. Dynamische Tick-Größen behandeln Marktparameter als veränderlichen Zustand. Getrennte WebSockets bedienen unterschiedliche Echtzeit-Profile.

Viele API-Design-Ratschläge konzentrieren sich auf Ergonomie:

  • konsistente Benennung
  • einfache Aufrufe
  • vorhersehbare Fehlerbehandlung

Diese Punkte bleiben wichtig. Die interessanteren Entscheidungen liegen jedoch in der Treue zur Domäne:

  1. Gibt es in der Domäne eine wichtige Unterscheidung? Dann machen Sie sie als Typ, Feld oder Endpunkt sichtbar.
  2. Gibt es eine harte Einschränkung? Dann validieren und erzwingen Sie sie über die API.
  3. Gibt es veränderlichen Zustand? Dann veröffentlichen Sie Zustandsübergänge aktiv.
  4. Gibt es unterschiedliche Konsumentenprofile? Dann entwerfen Sie Infrastruktur gezielt für diese Profile.

Das Ergebnis ist möglicherweise eine API, die mehr Verständnis von ihren Konsumenten verlangt. Dafür verstehen Entwickler, die sie korrekt integrieren, auch die Struktur des Systems, auf dem sie arbeiten. Für Prognosemärkte, deren Zweck darin besteht, Informationen in Preisen abzubilden, ist das genau die richtige Eigenschaft.

Top comments (0)