API · Referenz

Das Lesen von Polymarket-Marktdaten braucht keinen Schlüssel. Orders platzieren oder stornieren braucht zwei Auth-Ebenen: eine L1-Wallet-Signatur (EIP-712) zum Erstellen deiner API-Zugangsdaten und eine L2-HMAC-Signatur bei jedem authentifizierten Request. Diese Seite behandelt beide, plus die vier Signaturtypen und die Funder-Adresse – die zwei Dinge, die die meisten Auth-Fehler verursachen.

Auf einen Blick
  • Lesen (Gamma, Data, öffentliches CLOB) – keine Auth.
  • L1 – deine Wallet signiert eine EIP-712-Nachricht (ClobAuth-Domain-Version "1"), um API-Zugangsdaten zu erstellen oder abzuleiten.
  • L2 – jeder Order-Request wird mit einem HMAC aus api_key / api_secret / api_passphrase signiert.

Erstelle oder leite deine API-Zugangsdaten ab (L1)

Deine Wallet signiert einmal, um einen deterministischen Satz API-Zugangsdaten zu erzeugen (oder erneut abzuleiten). Nutze das V2-SDK – der V1-py-clob-client (0.34.x) ist archiviert und nicht funktionsfähig.

from py_clob_client_v2 import ClobClient   # pip install py-clob-client-v2

# L1: your wallet signs to derive API credentials
client = ClobClient(host="https://clob.polymarket.com", chain_id=137, key=PRIVATE_KEY)
creds = client.create_or_derive_api_key()    # api_key, api_secret, api_passphrase

# L1 + L2: rebuild the client WITH creds for authenticated calls (no set_api_creds in v2)
client = ClobClient(host="https://clob.polymarket.com", chain_id=137, key=PRIVATE_KEY, creds=creds)
// polymarket_client_sdk_v2 - official Rust client (repo rs-clob-client-v2)
use polymarket_client_sdk_v2::clob::{Client, Config};
use polymarket_client_sdk_v2::clob::types::SignatureType;
let client = Client::new("https://clob.polymarket.com", Config::default())?
    .authentication_builder(&signer)
    .funder(deposit_wallet)                   // deposit wallets work in Rust today
    .signature_type(SignatureType::Poly1271)
    .authenticate().await?;

Speichere die drei Werte als Secrets (Umgebungsvariablen). Zum Lesen von Marktdaten werden sie nie gebraucht.

Signaturtypen (0–3)

Der Signaturtyp sagt der Börse, wie deine Order-Signatur auf die Wallet abgebildet wird, die die Gelder hält (der Funder). Wähle den, der dazu passt, wie dein Konto erstellt wurde.

TypNameWann
0EOAEine einfache Wallet (z. B. MetaMask), die sowohl signiert als auch Gelder hält.
1POLY_PROXYE-Mail-/Magic.link-Anmeldung – eine Proxy-Wallet hält die Gelder; dein Schlüssel signiert in ihrem Namen.
2POLY_GNOSIS_SAFEEin Gnosis Safe hält die Gelder; ein Signer-Schlüssel signiert für ihn.
3POLY_1271Eine Deposit-Wallet (EIP-1271-Smart-Contract-Signatur).

Wenn sich der signierende Schlüssel von der geldhaltenden Adresse unterscheidet (Typen 1–3), musst du sowohl den Private Key als auch die funder-Adresse übergeben.

Deposit-Wallets (Typ 3) – nutze heute Rust. Stand Juni 2026 haben die Python- (py-clob-client-v2) und TypeScript-Clients (@polymarket/clob-client-v2) einen offenen Bug: Die L1-Auth bindet den API-Schlüssel an deine EOA statt an die Deposit-Wallet, sodass Orders abgelehnt werden („maker address not allowed, please use the deposit wallet flow“). Der offizielle Rust-Client behandelt die EIP-1271-Deposit-Wallet-Signierung korrekt. Nicht-Rust-Workaround: Nutze ein E-Mail-/Magic-Konto und signiere mit signature_type = POLY_PROXY (Typ 1). Prüfe die Polymarket-Issues #70 (Python) / #65 (TS) auf einen Fix.

Requests signieren (L2)

Jeder authentifizierte Request trägt eine HMAC-Signatur, gebildet aus deinem API-Secret plus Request-Methode, -Pfad, -Body und einem Zeitstempel. Das V2-SDK baut diese Header für dich. Zwei Dinge müssen korrekt sein:

  • Uhr – ein Drift von mehr als ~60 Sekunden führt zur Ablehnung deiner Signatur. Synchronisiere per NTP.
  • Domains – die L2-/ClobAuth-EIP-712-Domain-Version bleibt "1"; nur die V2-Exchange-Domain (Order) wechselte auf "2". Ein V1-Client signiert die falsche Order-Domain und schlägt fehl – siehe order_version_mismatch.

Schlüsselsicherheit

  • Private Keys oder API-Secrets niemals hartkodieren – nutze Umgebungsvariablen; committe sie nie.
  • Halte deinen Signier-Schlüssel und die Funder-Adresse möglichst getrennt von deiner Alltags-Wallet.
  • Read-only-Bots brauchen keine Zugangsdaten – fang dort an.

Weiter: CLOB API: eine Order platzieren · Einen Auth-Fehler beheben · v1 → v2 migrieren.