Experimentelle Combo-API

Combos handeln ein festes Verhältnis von Options-Legs als eine einzige Order. Ein Fill führt alle erforderlichen Legs gemeinsam aus. Ihre Positionen bleiben die einzelnen Optionen.

Experimenteller Vertrag

Alle /experimental-Endpunkte und ausdrücklich als experimentell gekennzeichneten WebSocket-Nachrichten sind instabil. Inkompatible Änderungen können mit einer Vorankündigung von einem Tag (24 Stunden) in Kraft treten. Dazu gehören das Entfernen oder Umbenennen von Feldern oder Endpunkten, Änderungen von Feldtypen sowie Änderungen am Anfrage- oder Antwortverhalten. Änderungen werden im API-Changelog angekündigt. Clients müssen diese Hinweise verfolgen und vor dem angegebenen Inkrafttreten aktualisiert werden. Bestehende nicht-experimentelle API-Verträge fallen nicht unter diese Richtlinie.

Die Verfügbarkeit hängt von Ihrer Umgebung ab. Diese Seite beschreibt die experimentelle Schnittstelle. Sie kündigt weder die Verfügbarkeit in der Produktion noch eine neue Oberfläche in der Trading-App an.

Für die gemeinsamen Verbindungs- und Signaturkonventionen verwenden Sie die REST-Referenz, den Authentifizierungsleitfaden und den WebSocket-Leitfaden.

Ein Combo entdecken

Anfrage	Ergebnis
`GET /experimental/combos`	Eine begrenzte Seite nicht verfallener Definitionen, optional gefiltert nach `underlying`
`GET /experimental/combos/{symbol}`	Eine nicht verfallene Definition und ihre aufgelösten Options-Legs

Erstellung durch die erste Order: Übermitteln Sie eine kanonische combo_definition mit POST /order, wenn das Combo noch nicht auffindbar ist. Die erste akzeptierte Order veröffentlicht ihre Definition, auch wenn sie sofort gefüllt wird. Eine abgelehnte Order veröffentlicht nichts. Es gibt keinen separaten Endpunkt zur Erstellung.

Auffindbarkeitsdauer: Eine Definition bleibt auffindbar, bis ihr erstes Leg verfällt, auch wenn keine ruhenden Orders vorhanden sind.

Paginierung: Antworten enthalten combos und next_cursor. Setzen Sie limit auf 1–1.000 (Standard 100). Übergeben Sie den zurückgegebenen Cursor bei der nächsten Anfrage als cursor und behalten Sie denselben underlying-Filter bei. Ein Null-Cursor bedeutet, dass keine weitere Zeile beobachtet wurde. Ungültige Limits oder Cursor liefern HTTP 400.

GET /experimental/combos?underlying=BTC&limit=100
GET /experimental/combos?underlying=BTC&limit=100&cursor=<next_cursor>

Seitenreihenfolge: frühester Leg-Verfall, danach Combo-ID. Behandeln Sie Cursor als opak. Jede Seite spiegelt den aktuellen Auffindbarkeitszustand wider. Definitionen können zwischen Anfragen verfallen oder hinzukommen. Nutzen Sie Erstellungs-Updates oder starten Sie die Abfrage neu, um neu erstellte Definitionen zu erfassen, die vor einem gespeicherten Cursor einsortiert werden.

Identität: Ein Symbol besteht aus COMBO- gefolgt von 64 hexadezimalen Kleinbuchstaben-Zeichen. Seine inhaltsgebundene ID legt die Leg-Instrumente und die vorzeichenbehafteten ganzzahligen Verhältnisse fest. Ein bestehendes Symbol kann seine Bedeutung nicht ändern.

Anfänglicher Umfang: zwei bis acht verschiedene Options-Legs mit demselben Basiswert. Jedes Leg muss gelistet, nicht verfallen und für die angeforderte Ausführungsroute zulässig sein.

Seite, Preis und Größe verstehen

Für eine kanonische Definition mit den Verhältnissen +1 A, -1 B gilt:

Ein Paket kaufen: ein A kaufen und ein B verkaufen.
Ein Paket verkaufen: ein A verkaufen und ein B kaufen.
Nettopreis: price(A) - price(B), quotiert pro Paket.
Limit: Ein Kauf akzeptiert einen Nettopreis auf oder unter seinem Limit. Ein Verkauf akzeptiert einen Nettopreis auf oder über seinem Limit.

Negative Preise und Nullpreise sind gültig. Handelt A bei $8 und B bei$ 10, beträgt der kanonische Nettopreis -2. Der Kauf dieses Pakets erhält vor Gebühren $2. Der Verkauf zahlt vor Gebühren$ 2. Jedes tatsächliche Options-Leg hat weiterhin einen positiven Ausführungspreis.

Order-Inkremente: Die Paketgröße verwendet menschenlesbare Kontrakteinheiten mit einem Inkrement von 0.000001. Der Netto-Limitpreis verwendet ein Inkrement von 0.000001. Jedes ausgeführte Leg muss zusätzlich seine eigenen Mengen- und Preisinkremente erfüllen. Ein Teil-Fill erhält alle Verhältnisse und füllt eine vollständige zulässige Paketmenge.

Gebühren: Es gelten die bestehenden Gebührensätze und Zulässigkeiten pro Leg, ohne Paketrabatt. Die eingehende Order ist auf ihren eigenen Legs der Taker, mit ihrer übermittelten Builder-Zuordnung. Bei einer Outright-über-Combo-Route erhält die Combo-Parent-Order die normale Taker-Gebührenzuordnung auf den zusätzlichen unterstützenden Legs gegenüber den unterstützenden Outright-Makern. Diese Legs haben keine Builder-Zuordnung. Reservierungen für ruhende Combos berücksichtigen konservativ voraussichtliche Taker-Gebühren auf die Brutto-Leg-Beträge. Die aktuelle Standard-Margin-Ausführung erfordert null Handelsgebühren für Orderbuch- und RFQ-Fills. Eine Route mit einem SM-Teilnehmer kann nicht mit Handelsgebühren ungleich null ausgeführt werden.

Margin: Die Börse prüft für jedes Konto die resultierenden Optionspositionen und das verbleibende Order-Exposure. Ein Combo kombiniert keine Sicherheiten über Wallets hinweg und verspricht keine bestimmte Senkung der Margin. Erlaubt Ihre Kontostufe nur gedeckte Optionsverkäufe, teilen sich ruhende Outright-Orders und die Verkaufs-Legs jeder Combo-Parent-Order denselben gefüllten Long-Bestand. Separate Parent-Orders und aufgeteilte Fills können diesen Bestand nicht jeweils erneut verwenden. Ungefüllte Kauf-Legs erhöhen die Deckung nicht.

Eine Order platzieren

Verwenden Sie die bestehende signierte POST /order-Anfrage mit dem Combo-Symbol. Die Signaturfelder der Order sind unverändert. Signieren Sie genau die Strings symbol, size und price, die Sie senden, einschließlich des Minuszeichens eines negativen Preises. Fügen Sie bei einem neuen Combo dessen kanonische combo_definition wie unten beschrieben hinzu. Das signierte inhaltsgebundene Symbol legt sich auf diese Definition fest. Eine nicht übereinstimmende Definition wird abgelehnt. Bei bekannten Combos kann sie weggelassen werden.

{
  "wallet": "<your wallet>",
  "symbol": "<discovered COMBO symbol>",
  "side": "Buy",
  "size": "1",
  "price": "-2",
  "tif": "gtc",
  "route": "best_execution",
  "client_id": "spread-001",
  "reduce_only": false,
  "mmp_enabled": false,
  "nonce": 1,
  "signature": "<signed order>"
}

Ersetzen Sie die Platzhalter und die Nonce durch Ihre tatsächlichen Werte. Der Preis dient nur der Veranschaulichung und ist keine aktuelle Marktquote.

Einstellung	Verhalten
`route: "book_only"`	Verfügbare direkte und unterstützte implizite Liquidität matchen, danach die Time-in-Force anwenden
`route: "best_execution"`	Eine Preisverbesserungsauktion für das vollständige Paket prüfen und bei Bedarf auf die Orderbuch-Ausführung zurückfallen
`route: "rfq_only"`	Auf `/order` abgelehnt
`tif: "gtc"`	Den ungefüllten Paket-Rest ruhen lassen
`tif: "ioc"`	Den ungefüllten Rest stornieren
`tif: "fok"`	Die gesamte angeforderte Paketmenge ausführen oder nichts ausführen

Preisverbesserung vergleicht den signierten Nettopreis des vollständigen Pakets mit einer ausführbaren Orderbuch-Referenz in voller Größe. Quote-Anbieter müssen jedes Leg im exakt angeforderten Verhältnis und in der exakt angeforderten Menge liefern. Eine Quote nur nach ihrem ersten Leg zu bewerten, reicht nicht aus. Sowohl direkte Combo-Liquidität als auch unterstützte implizite Routen können zur Referenz beitragen. Ist die Referenz nicht verfügbar oder unvollständig, wird die Order an die Orderbuch-Ausführung übergeben.

Zulässigkeit von Quotes: Die bestehenden RFQ-Gebührenregeln gelten ebenfalls. Verwendet einer der Teilnehmer Standard Margin, erfordert die RFQ-Ausführung null Handelsgebühren. Eine Quote, die Gebühren-, Sicherheiten- oder exakte Zuteilungsprüfungen nicht besteht, überlässt die Ausführung dem aktuellen Orderbuch-Pfad. Ihre Legs werden nicht teilweise ausgeführt.

Implizites Matching kann ein Combo mit seiner unterstützenden Outright-Optionsliquidität kombinieren. Beispielsweise kann eine Outright-Order auf A atomar gegen ein A-minus-B-Combo und B-Liquidität handeln. Ein Kunde, der nur A handelt, erhält keine B-Position.

Implizite Suchen haben Ressourcenlimits. Erreicht eine Outright-Order diese Limits, wird ihre unterstützende Liquidität nicht verfügbar oder kann die optionale Route die Outright-Order-Inkremente nicht abbilden, kann sie unter den üblichen Orderregeln weiterhin gegen ihr direktes Options-Orderbuch handeln. Die Combo-Unterstützung ändert die akzeptierten Outright-Mengen- oder Preisinkremente nicht. Die Zieloption muss für den Orderbuch-Handel zulässig bleiben. Eine Combo-Order, die die Suchlimits überschreitet, wird ohne Teilzuteilung abgelehnt.

Aktuelle Einschränkungen: Native Combo-Orders erfordern mmp_enabled: false. Geschützte Outright-Teilnehmer behalten MMP. Ein Paket, das einen Schwellenwert auslöst, schließt seine Legs ab und beendet weiteres Matching. Ein unvollständiges FOK oder ein atomarer Ersatz macht den vollständigen Kandidaten rückgängig. Reduce-only-Orders überspringen die Preisverbesserungsauktion und verwenden die Orderbuch-Zulassung, bei der jedes resultierende Leg die Reduce-only-Prüfungen erfüllen muss. Stornieren Sie ein ruhendes Combo über seine Parent-Order-ID oder Client-Order-ID mit den bestehenden Stornierungsendpunkten.

Ersetzen: PUT /order kann eine Parent-Order innerhalb derselben Combo-Definition atomar ersetzen. Ein abgelehnter Ersatz lässt seinen Vorgänger unverändert. Native Einträge bei einem Massenersatz verwenden ebenfalls einen atomaren Befehl pro Parent-Order. Der Batch ist keine einzelne Alles-oder-nichts-Transaktion. Das Ersetzen zwischen einem Combo und einer Outright-Order oder zwischen unterschiedlichen Combo-Definitionen wird abgelehnt.

Self-Trade-Prevention: Das Matching stoppt, bevor eine Route ein Konto gegen sich selbst handeln würde, und storniert die ruhende Maker-Order. Frühere abgeschlossene Fills bleiben bestehen, während der eingehende Rest storniert wird. Ohne frühere Fills wird die eingehende Order abgelehnt. FOK-Orders und fehlgeschlagene atomare Ersetzungen behalten ihr Alles-oder-nichts-Verhalten bei, einschließlich der Rücknahme vorläufiger Maker-Stornierungen.

Ein Combo in der ersten Order definieren

Vor dem Signieren kanonisieren: Fassen Sie doppelte Instrument-IDs zusammen, entfernen Sie Nullverhältnisse, sortieren Sie die IDs numerisch, teilen Sie die Verhältnisse durch ihren größten gemeinsamen Teiler und machen Sie das erste Verhältnis positiv. Kehrt die Normalisierung die Verhältnisse um, kehren Sie die beabsichtigte Orderseite um und negieren Sie den Nettopreis. Teilt sie die Verhältnisse durch einen Faktor, multiplizieren Sie die Paketgröße mit diesem Faktor und teilen Sie den Nettopreis durch ihn.

Die ID der Version eins ist der Keccak-256-Hash der folgenden Verkettung:

UTF-8("hypercall:combo-definition\0")
|| version as unsigned 16-bit big-endian (1)
|| leg count as unsigned 16-bit big-endian
|| each sorted leg:
     instrument ID as 32 big-endian bytes
     ratio as signed 64-bit two's-complement big-endian

Instrument-IDs sind der Keccak-256-Hash von UTF-8 "instrument", gefolgt vom exakten kanonischen Optionssymbol. Die veröffentlichte Combo-ID ist der vollständige Digest, kodiert als 0x plus 64 hexadezimale Kleinbuchstaben-Zeichen. Das Combo-Symbol verwendet dieselben Hex-Ziffern nach COMBO-.

Fügen Sie combo_definition in den gewöhnlichen signierten POST /order-Body ein. Die Definition enthält version, id und legs. Jedes Leg enthält instrument_id und ratio. Kodieren Sie IDs als 0x plus 64 hexadezimale Kleinbuchstaben-Ziffern und Verhältnisse als kanonische vorzeichenbehaftete Dezimal-Strings, etwa "1" oder "-1". JSON-Zahlen, führende Pluszeichen und führende Nullen werden für Verhältnisse abgelehnt.

{
  "combo_definition": {
    "version": 1,
    "id": "<canonical content hash as 0x plus 64 hex digits>",
    "legs": [
      {"instrument_id": "<first canonical instrument ID>", "ratio": "1"},
      {"instrument_id": "<second canonical instrument ID>", "ratio": "-1"}
    ]
  }
}

Dieses Fragment wird zum vollständigen Order-Beispiel oben hinzugefügt. Ersetzen Sie die Platzhalter durch tatsächliche IDs und verwenden Sie das entsprechende COMBO--Symbol. Es gibt keine zusätzliche Definitionssignatur und keine separate Veröffentlichungs-Nonce. Der Dienst prüft den kanonischen Inhalt und seine Identität gegen das signierte Symbol. Outright-Orders müssen combo_definition weglassen.

Annahme und Auffindbarkeit: Jede akzeptierte Combo-Order speichert ihre Definition in ihrem dauerhaften Order-Datensatz und stellt idempotent sicher, dass der Katalogeintrag existiert. Eine spätere Order überschreibt den ersten Erstellungsdatensatz nicht. Eine sofort gefüllte Order erzeugt dennoch Auffindbarkeitsdaten, abgelehnte Orders nicht. Die Auffindbarkeit kann der Order-Bestätigung hinterherhinken, da sie aus festgeschriebenen Daten projiziert wird. Das erneute Übermitteln derselben Definition in einer späteren Order wird unterstützt, auch während ihr erster Katalogeintrag noch nachgezogen wird.

Orders und Ausführungen lesen

Anfrage	Zweck
`GET /experimental/orders`	Orders mit expliziter Instrumentklassifizierung lesen, einschließlich Combo-Parent-Orders
`GET /experimental/trades`	Standardmäßig echte Leg-Trades lesen, oder Paketzusammenfassungen für ein Combo mit `view=packages&symbol=<COMBO symbol>`
`GET /experimental/fills`	Standardmäßig Wallet-Fills lesen, oder Wallet-Paketzusammenfassungen mit `view=packages`

Die unterstützten Filter und Cursor finden Sie in der REST-Referenz. Paketansichten paginieren mit limit (1 bis 1.000, Standard 100) und before_execution_id, nicht mit offset: Übergeben Sie die zurückgegebene next_before_execution_id, um die nächste Seite abzurufen. Paket-Trades erfordern ein kanonisches COMBO--symbol. Paket-Fills verwenden wallet und ein optionales symbol. Paketzusammenfassungen sind Gruppierungsdatensätze: Über Ausführungs-IDs und Leg-Trade-IDs können Sie sie mit den tatsächlichen Optionsausführungen verknüpfen. Addieren Sie Paketmenge, Prämie oder Gebühren bei der Berechnung von Kontosummen nicht zu den zugehörigen Einzelausführungen.

Präzision von Bezeichnern: Experimentelle Order-IDs, Paket-Ausführungs-IDs, zugehörige Trade- und Order-IDs, Parent-Order-IDs und Paket-Paginierungscursor sind Dezimal-Strings. Behalten Sie sie in Ihrem Client als Strings bei. Die Umwandlung in JavaScript-Zahlen kann zu Präzisionsverlust führen. Legacy-Antworten mit view=legs behalten ihre bestehenden Darstellungen.

Kompatibilität: Die Legacy-Instrumentabfrage und Legacy-Orderansichten behalten ihren Outright-Vertrag. Tatsächliche Ausführungen von Options-Legs erscheinen weiterhin in den Legacy-Trade- und Fill-Feeds, und Positionen bleiben Optionspositionen. Die Parent-Order eines Combos ist keine Sammlung unabhängig ruhender Leg-Orders.

Explizit abonnieren

Experimentelle private Kanäle erfordern den bestehenden WebSocket-Authentifizierungsschritt und ein explizites Abonnement. Sie veröffentlichen nur die Parent-Datensätze der authentifizierten Wallet.

Kanal	Nachricht	Zielgruppe
`experimental_order_updates`	`ExperimentalOrderUpdate` mit Parent-ID, Symbol, Instrumenttyp (`option`, `perp` oder `combo`), Status, Menge, gefüllter Menge und Nettopreis	Authentifizierte Wallet
`experimental_combo_trades`	`ComboTrade` mit Ausführungs-ID, Symbol, Paketmenge, Nettopreis und Leg-Trade-IDs	Öffentlich
`experimental_combo_fills`	`ComboFill` mit der Parent-Order-ID der Wallet, der Seite und der Paketausführung	Authentifizierte Wallet

{"type":"Subscribe","channel":"experimental_order_updates"}

ExperimentalOrderUpdate.status verwendet Acked, Open, PartiallyFilled, Filled, Canceled oder Rejected, nicht die großgeschriebenen Werte von OrderUpdate. IDs und Mengen sind Strings.

Abonnieren Sie den bestehenden Orderbuch-Kanal mit einem entdeckten Combo-Symbol:

{"type":"Subscribe","channel":"orderbook","symbols":["<discovered COMBO symbol>"]}

Updates zur Marktauffindbarkeit können dieselbe unveränderliche Definition wiederholen. Deduplizieren Sie anhand der Combo-ID. Sie verwenden MarketUpdate auf market_updates, mit action: "ComboCreated", dem Combo-Symbol, der ID, den kanonischen Legs und dem Zeitstempel. Behandeln Sie Auffindbarkeit, Parent-Order-Status, Paketausführungszusammenfassungen und tatsächliche Leg-Fills beim Abgleich in Ihrem Client als getrennte Datensätze.

Ein Combo entdecken​

Seite, Preis und Größe verstehen​

Eine Order platzieren​

Ein Combo in der ersten Order definieren​

Orders und Ausführungen lesen​

Explizit abonnieren​