Eine technische Einführung und Anleitung zum Handel mit der OKX API v5

Mit der Einführung des neuen Unified Account-Handelssystems von OKX haben wir unsere API mit neuen Funktionen und Verbesserungen aufgerüstet. In diesem Dokument erläutern wir die wichtigsten Änderungen in der v5, der neuesten API-Version, und führen Trader durch die verschiedenen Konfigurationsparameter, die nun über die OKX Trading-API verfügbar sind.

Änderungen in API v5 Vereinheitlichte API über Produkte hinweg

Im Gegensatz zur API v3 sind in v5 die Endpunkte – etwa zum Ordern und Abrufen von Positionen – produktübergreifend vereinheitlicht.

Beispiel: Beim Platzieren einer Order rufen wir nur noch diese URL auf und geben den Produkttyp (Instrumententyp) im Request-Body an:

POST /api/v5/trade/order

Für alle Instrumenttypen werden dieselben Request- und Response-Modelle verwendet. Es ist also nicht mehr nötig, für jedes Produkt eine eigene API-Abbildung zu pflegen.

Kürzere Namenskonvention

In API v5 werden camelCase und Abkürzungen verwendet, um Bandbreite und Speicher zu sparen.

Beispiele:

Feld V5 API V3 API Währung ccy currency Instrument-ID instId instrument_id Underlying uly underlying Nicht realisierter PnL upl unrealized_pnl Standard-WebSocket-Kompression

Die manuelle Dekomprimierung eingehender Nachrichten aus v3 entfällt. Stattdessen kommt die WebSocket-Erweiterung Per-Message Deflate zum Einsatz.

Aktiviere dafür die Erweiterung clientseitig; der Header sollte permessage-deflate enthalten.

Öffentliche und private WebSockets

WebSocket-Kanäle sind in öffentliche (z. B. Ticker, Candles) und private (z. B. Positionen, Konto) mit unterschiedlichen URLs aufgeteilt.

Beim öffentlichen WebSocket ist kein Login vor einer Subscription erforderlich; andernfalls lehnt der Server die Subscription ab.

Orders per WebSocket platzieren

Zusätzlich zu REST können Orders jetzt auch per WebSocket platziert/geändert/storniert werden. Details findest du im Trading-Abschnitt.

Authentifizierung

Die REST-Authentifizierung in v5 entspricht v3 (Signatur im Request-Header).

Die WebSocket-Authentifizierung ist ebenfalls ähnlich (Login-Nachricht), allerdings im Key-Value-Format:

{ "op": "login", "args": [ { "apiKey": "975d5d66-57ce-40fb-b714-afc0b66518083", "passphrase": "123456", "timestamp": "1538054050", "sign": "7L+zFQ+CEgGu5rzCj4+BdV2/uUHGqddA9pI6ztsLLPs=" } ] }

API-Keys von Sub-Accounts verwalten

Mit v5 lassen sich die API-Keys von Sub-Accounts per Master-Account (Hauptkonto) anlegen, lesen, ändern, löschen.

Aktion Endpoint Erstellen POST /api/v5/users/subaccount/apikey Lesen GET /api/v5/users/subaccount/apikey Ändern POST /api/v5/users/subaccount/modify-apikey Löschen POST /api/v5/users/subaccount/delete-apikey

Aus Sicherheitsgründen wird dringend empfohlen, API-Keys an feste IP-Adressen zu binden.

Konten und Sub-Accounts konfigurieren

Nach dem Anlegen von Sub-Accounts und deren API-Keys können Haupt- und Sub-Accounts per API konfiguriert werden.

Konto-Konfiguration

Die Konto-Konfiguration jedes (Sub-)Accounts lässt sich via REST abrufen:

GET /api/v5/account/config

Zurückgegeben werden: (1) Account-Modus, (2) Positions-Modus, (3) Auto-Borrow-Einstellung, (4) Option-Greeks-Typ.

Account-Modus

Im Unified Account gibt es: (i) Simple Mode, (ii) Single-Currency Margin Mode, (iii) Multi-Currency Margin Mode.

Diese Modi können nur in der Web-UI geändert werden (Nutzerinteraktion erforderlich).

Position

Der Net-Positionsmodus wurde zusätzlich zu Long/Short eingeführt.

Modus Beschreibung Net-Position Es kann nur eine Seite gehalten werden. Die Börse öffnet/schließt je nach angegebenem Vorzeichen automatisch. Long/Short Long- und Short-Positionen können gleichzeitig gehalten werden.

Positions-Modus umstellen (alle Positionen müssen vorher geschlossen sein):

POST /api/v5/account/set-position-mode

Auto Borrow

Auto Borrow ist neu, gilt nur im Multi-Currency Margin Mode und kann nur über die Web-UI geändert werden.

Option-Greeks-Typ

Per REST in v5 ähnlich wie in v3:

POST /api/v5/account/set-greeks

Cross/Isolated-Margin-Modus

Im Unified Account kannst du dasselbe Instrument gleichzeitig mit Cross- und Isolated-Margin traden. Es gibt daher keine API mehr, um den Margin-Modus pro Underlying zu setzen; der Trade-Modus wird pro Order angegeben.

Leverage verwalten Leverage abrufen GET /api/v5/account/leverage-info

Es gibt keine globale Leverage-Einstellung; Hebel werden je nach Geltungsbereich gesetzt.

Leverage setzen POST /api/v5/account/set-leverage

Damit lässt sich ein Programm erstellen, das den Hebel vorab pro Instrument setzt.

Beispiel-Szenario:

Account-Modus: Multi-Currency Margin

Positions-Modus: Net

Ziel-Leverage 3,0 für:

BTC-USDT, EOS-USDT, LTC-BTC, LTC-USDT

BTC-USD-210319, BTC-USD-210326, BTC-USD-210625

BTC-USD-SWAP

Nur Cross-Margin für die obigen Instrumente

Für Spot/Margin wird der Hebel pro Coin gesetzt (z. B. BTC, USDT, EOS, LTC):

{ "lever": "3.0", "mgnMode": "cross", "ccy": "BTC" }

Für die Futures mit demselben Underlying (BTC-USD) reicht ein Setzen:

{ "lever": "3.0", "mgnMode": "cross", "instId": "BTC-USD-210326" }

Für BTC-USD-SWAP separat (trotz gleichen Underlyings):

{ "lever": "3.0", "mgnMode": "cross", "instId": "BTC-USD-SWAP" }

Damit sind die 8 Instrumente mit 6 API-Calls abgedeckt.

Trading mit API v5 Trade-Modus

Durch die flexible Wahl zwischen Cross und Isolated pro Order muss der Trade-Modus (tdMode) gesetzt werden. (Siehe Tabelle in der Originaldoku.)

Beispiel-Order:

Account-Modus: Multi-Currency Margin

Positions-Modus: Net

Instrument: BTC-USDT-SWAP

Margin: Cross

Seite: Buy (Long)

Typ: Limit

Preis: 50 912,4 USDT

Größe: 1 Kontrakt

Hier ist tdMode = "cross". Empfehlung: Client-Order-ID (clOrdId) setzen (alphanumerisch, case-sensitiv, mit Buchstabe beginnend, max. 32 Zeichen). Beispiel: testBTC0123.

Orders-Kanal abonnieren

Vor dem Ordern den WebSocket-Kanal orders abonnieren, um Zustandsänderungen (z. B. live, filled) zu erhalten.

Subscriptions sind in verschiedenen Granularitäten möglich (Instrumenttyp, Typ+Underlying, Typ+Instrument-ID). Beispiele:

// Instrumenttyp { "op": "subscribe", "args": [{ "channel": "orders", "instType": "SWAP" }] }

// Typ + Underlying (nur Derivate) { "op": "subscribe", "args": [{ "channel": "orders", "instType": "SWAP", "uly": "BTC-USDT" }] }

// Typ + Instrument-ID { "op": "subscribe", "args": [{ "channel": "orders", "instType": "SWAP", "instId": "BTC-USDT-SWAP" }] }

instType: "ANY" abonniert alle Produkttypen.

Hinweis: Der Orders-Kanal sendet keinen initialen Snapshot. Für offene Orders vor der Subscription:

GET /api/v5/trade/orders-pending

Order platzieren

REST:

POST /api/v5/trade/order

{ "instId": "BTC-USDT-SWAP", "tdMode": "cross", "clOrdId": "testBTC0123", "side": "buy", "ordType": "limit", "px": "50912.4", "sz": "1" }

Die erfolgreiche Antwort bestätigt Eingang & ordId, nicht den Live-Status.

WebSocket:

{ "id": "NEWtestBTC0123", "op": "order", "args": [{ "instId": "BTC-USDT-SWAP", "tdMode": "cross", "clOrdId": "testBTC0123", "side": "buy", "ordType": "limit", "px": "50912.4", "sz": "1" }] }

Antwort enthält dieselbe id und die ordId. Auch hier: nur Empfangsbestätigung.

Order-Status prüfen

Nach dem Platzieren erwarten wir über orders den Status live. Nach Ausführung folgt eine Nachricht mit filled und tradeId (für Abgleich/Reconciliation).

Order ändern

Preis (newPx) und/oder Größe (newSz) sind änderbar; optional cxlOnFail (bei Fehlschlag stornieren).

REST: POST /api/v5/trade/amend-order

WebSocket: "op": "amend-order"

Bereits voll ausgeführte oder stornierte Orders sind nicht änderbar.

Order stornieren

REST: POST /api/v5/trade/cancel-order

WebSocket: "op": "cancel-order"

Die Order gilt erst als storniert, wenn eine orders-Nachricht mit state: "canceled" empfangen wurde.

Batch-Operationen

Batch-Platzierung/Änderung/Storno von max. 20 Orders gleichzeitig, auch gemischte Instrumenttypen.

REST:

Platzieren: POST /api/v5/trade/batch-orders

Ändern: POST /api/v5/trade/amend-batch-orders

Stornieren: POST /api/v5/trade/cancel-batch-orders

WebSocket:

Platzieren: "op": "batch-orders"

Ändern: "op": "batch-amend-orders"

Stornieren: "op": "batch-cancel-orders"

Batch ist nicht atomar – Teilerfolg möglich; prüfe je Order sCode/sMsg.

Konto- und Positionsdaten Unified Account

Im Unified Account gibt es nur ein gemeinsames Konto über alle Instrumenttypen hinweg (kein separater Spot/Margin/Futures/Swap/Options-Account).

WebSocket-Subscription (Account)

Empfohlen: den Account-Kanal abonnieren. Optionaler Parameter ccy filtert auf eine Währung.

Initialer Snapshot: Für alle Coins mit nicht-null Guthaben (Equity/Available) wird ein Snapshot gesendet.

Spätere Updates:

Ereignisgetrieben (Order-/Cancel-Events); nur betroffene Coins, auch wenn der Saldo auf 0 fällt.

Zeitgetrieben (Intervall, z. B. 10 s); wie der initiale Snapshot für alle nicht-null Coins (oder die in ccy angegebenen).

REST-Abruf (Kontostände) GET /api/v5/account/balance

Optional: ccy=BTC,USDT,ETH (einzelne oder mehrere, max. 20). Im Gegensatz zum WebSocket werden explizit angefragte Coins immer zurückgegeben, auch wenn der Saldo 0 ist (sofern schon einmal gehalten).

Maximal verfügbare Handelsmenge

Mit Auto Borrow im Multi-Currency Margin Mode kann über den verfügbaren Cash-Saldo hinaus getradet werden.

Nützlich ist dann:

GET /api/v5/account/max-avail-size

Beispiel (BTC-USDT, Cross):

GET /api/v5/account/max-avail-size?instId=BTC-USDT&tdMode=cross

Antwortfelder: availBuy (bei Spot in Quote), availSell (in Base).

Positionen WebSocket-Subscription (Positions)

Mehrere Granularitäten (Instrumenttyp, Typ+Underlying, Typ+Instrument-ID). instType: "ANY" abonniert alle.

Initialer Snapshot: Für nicht-null Positionen (pos ≠ 0).

Spätere Updates:

Ereignisgetrieben (Öffnen/Schließen; Aggregation möglich; Publikation auch beim Schließen auf 0).

Zeitgetrieben (Intervall, z. B. 10 s; alle nicht-null Positionen gemäß Subscription).

Positions-ID

posId identifiziert eine Position eindeutig (gebildet aus mgnMode + posSide + instId + ccy) und bleibt stabil, auch wenn die Position geschlossen und später erneut geöffnet wird. Sie kann als Query-Parameter im REST-Abruf verwendet werden.

REST-Abruf (Positionen) GET /api/v5/account/positions

Granularitäten:

Nach Instrumenttyp: ?instType=SWAP

Nach Instrument-ID: ?instId=BTC-USDT-SWAP

Nach einzelner posId: ?posId=287999792370819074

Nach mehreren posId (max. 20): ?posId=ID1,ID2

Explizit angefragte Positionen werden immer zurückgegeben (auch wenn sie inzwischen geschlossen sind), sofern sie zuvor existierten.

Abgleich zwischen Fills und Positionen

Mit der tradeId im Positions-Kanal ist ein Abgleich zwischen Order-Fills (orders) und Positionen möglich (z. B. Position aus Fills herleiten). Neue Fills erhalten steigende tradeId.

Stolpersteine:

Nicht jedes Order-Update lässt sich exakt matchen (Aggregation möglich – oft nur letzte tradeId).

Liquidation/ADL erzeugen kein Order-Update (System-Order).

Positions-Updates durch Liquidation/ADL aktualisieren die tradeId nicht.

Nutze daher zusätzlich Positionsdaten (z. B. uTime) beim Abgleich, nicht nur die tradeId.

In diesem Leitfaden haben wir die Änderungen der API v5 erläutert und gezeigt, wie Sub-Accounts mit der neuen API eingerichtet, Konten konfiguriert, Konto-/Positionsdaten über WebSocket abgerufen sowie Orders platziert und Positionen abgeglichen werden können.

Hinweis: Details können sich ändern, wenn OKX das Unified Account-System weiterentwickelt. Bitte konsultiere die API-v5-Dokumentation für die aktuellsten Spezifikationen.