API Combo expérimentale

Les combos négocient un ratio fixe de jambes d'options sous la forme d'un seul ordre. Une exécution réalise toutes les jambes requises ensemble. Vos positions restent les options individuelles.

Contrat expérimental

Tous les endpoints /experimental et les messages WebSocket explicitement expérimentaux sont instables. Des changements incompatibles peuvent entrer en vigueur avec un jour (24 heures) de préavis, notamment la suppression ou le renommage de champs ou d'endpoints, la modification des types de champs et la modification du comportement des requêtes ou des réponses. Les changements sont annoncés dans le changelog de l'API. Les clients doivent suivre ces annonces et se mettre à jour avant l'heure d'entrée en vigueur indiquée. Les contrats d'API existants non expérimentaux ne relèvent pas de cette politique.

La disponibilité dépend de votre environnement. Cette page décrit l'interface expérimentale ; elle n'annonce ni une disponibilité en production ni une nouvelle interface dans l'application de trading.

Consultez la référence REST, le guide d'authentification et le guide WebSocket pour les conventions communes de connexion et de signature.

Découvrir un combo

Requête	Résultat
GET /experimental/combos	Une page bornée de définitions non expirées, éventuellement filtrée par underlying
GET /experimental/combos/{symbol}	Une définition non expirée et ses jambes d'options résolues

Création par le premier ordre : soumettez un combo_definition canonique avec POST /order lorsque le combo n'est pas encore découvrable. Le premier ordre accepté publie sa définition, y compris un ordre exécuté immédiatement. Un ordre rejeté ne publie rien. Il n'existe pas d'endpoint de création distinct.

Durée de découverte : une définition reste découvrable jusqu'à l'échéance de sa première jambe, même lorsqu'elle n'a aucun ordre en attente.

Pagination : les réponses contiennent combos et next_cursor. Définissez limit entre 1 et 1 000 (100 par défaut). Transmettez le curseur renvoyé en tant que cursor dans la requête suivante, en conservant le même filtre underlying. Un curseur nul signifie qu'aucune ligne supplémentaire n'a été observée. Des limites ou curseurs invalides renvoient une erreur HTTP 400.

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

Ordre des pages : échéance de jambe la plus proche, puis ID du combo. Traitez les curseurs comme opaques. Chaque page reflète l'état actuel de la découverte ; des définitions peuvent expirer ou être ajoutées entre deux requêtes. Utilisez les mises à jour de création ou relancez la découverte pour capturer les définitions nouvellement créées qui se classent avant un curseur enregistré.

Identité : un symbole est COMBO- suivi de 64 caractères hexadécimaux en minuscules. Son ID lié au contenu fixe les instruments des jambes et les ratios entiers signés. Un symbole existant ne peut pas changer de signification.

Périmètre initial : de deux à huit jambes d'options distinctes ayant le même sous-jacent. Chaque jambe doit être listée, non expirée et éligible à la route d'exécution demandée.

Comprendre le sens, le prix et la taille

Pour une définition canonique avec les ratios +1 A, -1 B :

• Acheter un package : acheter un A et vendre un B.
• Vendre un package : vendre un A et acheter un B.
• Prix net : price(A) - price(B), coté par package.
• Limite : un achat accepte un prix net inférieur ou égal à sa limite ; une vente accepte un prix net supérieur ou égal à sa limite.

Les prix négatifs et nuls sont valides. Si A se négocie à 8 $et B à 10$, le prix net canonique est -2. L'achat de ce package reçoit 2 $avant frais. Sa vente paie 2$ avant frais. Chaque jambe d'option réelle conserve un prix d'exécution positif.

Incréments d'ordre : la taille du package utilise des unités de contrat lisibles avec un incrément de 0.000001 ; le prix limite net utilise un incrément de 0.000001. Chaque jambe exécutée doit également respecter ses propres incréments de quantité et de prix. Une exécution partielle préserve tous les ratios et exécute une quantité de package complète admissible.

Frais : les taux et règles d'éligibilité existants par jambe s'appliquent, sans remise sur le package. L'ordre entrant est le taker sur ses propres jambes, avec l'attribution builder qu'il a soumise. Dans une route outright via combo, l'ordre parent du combo reçoit l'attribution normale des frais taker sur les jambes de soutien supplémentaires face aux makers outright de soutien ; ces jambes n'ont pas d'attribution builder. Les réservations des combos en attente incluent prudemment les frais taker potentiels sur les montants bruts des jambes. L'exécution actuelle en Standard Margin exige des frais de trading nuls pour les exécutions sur le carnet et en RFQ ; une route impliquant un participant SM ne peut pas s'exécuter avec des frais de trading non nuls.

Marge : la plateforme vérifie les positions d'options résultantes et l'exposition restante des ordres pour chaque compte. Un combo ne combine pas le collatéral entre portefeuilles et ne garantit pas une réduction de marge particulière. Si le niveau de votre compte n'autorise que les ventes d'options couvertes, les ordres outright en attente et les jambes de vente de chaque ordre parent de combo partagent le même inventaire long exécuté. Des ordres parents distincts et des exécutions fractionnées ne peuvent pas réutiliser chacun cet inventaire ; les jambes d'achat non exécutées n'ajoutent aucune couverture.

Passer un ordre

Utilisez la requête signée existante POST /order avec le symbole du combo. Les champs de signature de l'ordre sont inchangés. Signez exactement les chaînes symbol, size et price que vous envoyez, y compris le signe moins d'un prix négatif. Pour un nouveau combo, ajoutez son combo_definition canonique comme décrit ci-dessous. Le symbole signé lié au contenu engage cette définition ; une définition incohérente est rejetée. Les combos connus peuvent l'omettre.

{
  "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>"
}

Remplacez les placeholders et le nonce par vos valeurs réelles. Le prix est une illustration, pas une cotation de marché actuelle.

Paramètre	Comportement
route: "book_only"	Exécute contre la liquidité directe et implicite prise en charge disponible, puis applique la durée de validité
route: "best_execution"	Envisage une enchère d'amélioration de prix sur le package complet, puis se replie sur l'exécution dans le carnet le cas échéant
route: "rfq_only"	Rejeté sur /order
tif: "gtc"	Laisse en attente le reliquat non exécuté du package
tif: "ioc"	Annule le reliquat non exécuté
tif: "fok"	Exécute la totalité de la quantité de package demandée ou rien

L'amélioration de prix compare le prix net signé du package complet à une référence exécutable du carnet pour la taille complète. Les fournisseurs de cotations doivent fournir chaque jambe au ratio et à la quantité exacts demandés. Classer une cotation sur sa seule première jambe est insuffisant. La liquidité directe sur le combo et les routes implicites prises en charge peuvent toutes deux contribuer à la référence. Une référence indisponible ou incomplète renvoie l'ordre vers l'exécution dans le carnet.

Éligibilité des cotations : les règles de frais RFQ existantes s'appliquent également. Si l'un des participants utilise la Standard Margin, l'exécution RFQ exige des frais de trading nuls. Une cotation qui échoue aux contrôles de frais, de collatéral ou d'allocation exacte laisse l'exécution au chemin actuel du carnet ; elle n'exécute pas partiellement ses jambes.

L'appariement implicite peut combiner un combo avec la liquidité outright de soutien sur les options. Par exemple, un ordre outright sur A peut s'exécuter de manière atomique contre un combo A moins B et de la liquidité sur B. Un client qui ne négocie que A ne reçoit aucune position sur B.

Les recherches implicites ont des limites de ressources. Si un ordre outright atteint ces limites, si sa liquidité de soutien devient indisponible ou si la route optionnelle ne peut pas représenter les incréments de l'ordre outright, il peut toujours s'exécuter contre son carnet d'options direct selon les règles habituelles des ordres. La prise en charge des combos ne modifie pas les incréments de quantité ou de prix acceptés pour les ordres outright. L'option cible doit rester éligible à la négociation dans le carnet. Un ordre combo qui dépasse les limites de recherche est rejeté sans allocation partielle.

Restrictions actuelles : les ordres combo natifs exigent mmp_enabled: false. Les participants outright protégés conservent la MMP. Un package qui déclenche un seuil complète ses jambes puis arrête tout appariement supplémentaire ; un FOK incomplet ou un remplacement atomique annule l'ensemble du candidat. Les ordres reduce-only ne passent pas par l'enchère d'amélioration de prix et utilisent l'admission dans le carnet, où chaque jambe résultante doit satisfaire les contrôles reduce-only. Annulez un combo en attente via l'ID de son ordre parent ou l'ID d'ordre client en utilisant les endpoints d'annulation existants.

Remplacement : PUT /order peut remplacer atomiquement un ordre parent au sein de la même définition de combo. Un remplacement rejeté laisse son prédécesseur intact. Les entrées natives d'un remplacement groupé utilisent également une commande atomique par ordre parent ; le lot ne constitue pas une transaction tout-ou-rien unique. Le remplacement entre un combo et un outright, ou entre différentes définitions de combo, est rejeté.

Prévention de l'auto-exécution : l'appariement s'arrête avant qu'une route ne fasse négocier un compte contre lui-même, et annule l'ordre maker en attente. Les exécutions déjà réalisées sont conservées, tandis que le reliquat entrant est annulé. En l'absence d'exécutions antérieures, l'ordre entrant est rejeté. Les ordres FOK et les remplacements atomiques échoués conservent leur comportement tout-ou-rien, y compris l'annulation des annulations provisoires d'ordres maker.

Définir un combo dans son premier ordre

Canonisez avant de signer : fusionnez les IDs d'instruments en double, supprimez les ratios nuls, triez les IDs numériquement, divisez les ratios par leur plus grand commun diviseur et rendez le premier ratio positif. Si la normalisation inverse les ratios, inversez le sens de l'ordre prévu et prenez l'opposé du prix net. Si elle divise les ratios par un facteur, multipliez la taille du package par ce facteur et divisez le prix net par celui-ci.

L'ID de la version un est le Keccak-256 de la concaténation suivante :

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

Les IDs d'instruments sont le Keccak-256 de la chaîne UTF-8 "instrument" suivie du symbole d'option canonique exact. L'ID de combo publié est le condensé complet, encodé sous la forme 0x suivi de 64 caractères hexadécimaux en minuscules. Le symbole du combo utilise les mêmes chiffres hexadécimaux après COMBO-.

Incluez combo_definition dans le corps ordinaire signé de POST /order. La définition contient version, id et legs ; chaque jambe contient instrument_id et ratio. Encodez les IDs sous la forme 0x suivi de 64 chiffres hexadécimaux en minuscules et les ratios sous forme de chaînes décimales signées canoniques, comme "1" ou "-1". Les nombres JSON, les signes plus initiaux et les zéros initiaux sont rejetés pour les ratios.

{
  "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"}
    ]
  }
}

Ce fragment s'ajoute à l'exemple d'ordre complet ci-dessus. Remplacez les placeholders par les IDs réels et utilisez le symbole COMBO- correspondant. Il n'y a ni signature supplémentaire de la définition ni nonce de publication distinct. Le service vérifie le contenu canonique et son identité par rapport au symbole signé ; les ordres outright doivent omettre combo_definition.

Acceptation et découverte : chaque ordre combo accepté conserve sa définition dans son enregistrement d'ordre durable et garantit de manière idempotente l'existence de l'entrée du catalogue. Un ordre ultérieur n'écrase pas le premier enregistrement de création. Un ordre exécuté immédiatement crée tout de même les données de découverte ; les ordres rejetés non. La découverte peut être en retard sur l'accusé de réception de l'ordre, car elle est projetée à partir des données validées. Il est possible de soumettre à nouveau la même définition dans un ordre ultérieur, y compris pendant que sa première entrée de catalogue est encore en cours de mise à jour.

Lire les ordres et les exécutions

Requête	Objet
GET /experimental/orders	Lire les ordres avec une classification explicite des instruments, y compris les ordres parents de combos
GET /experimental/trades	Lire par défaut les transactions réelles par jambe, ou les résumés de package d'un combo avec view=packages&symbol=<COMBO symbol>
GET /experimental/fills	Lire par défaut les exécutions du portefeuille, ou les résumés de package du portefeuille avec view=packages

Consultez la référence REST pour les filtres et curseurs pris en charge. Les vues par package se paginent avec limit (de 1 à 1 000, 100 par défaut) et before_execution_id, et non offset : transmettez le next_before_execution_id renvoyé pour obtenir la page suivante. Les transactions par package exigent un symbol COMBO- canonique ; les exécutions par package prennent wallet et un symbol optionnel. Les résumés de package sont des enregistrements de regroupement : les IDs d'exécution et les IDs de transaction des jambes vous permettent de les rattacher aux exécutions d'options réelles. N'ajoutez pas la quantité, la prime ou les frais du package aux exécutions constitutives lors du calcul des totaux du compte.

Précision des identifiants : les IDs d'ordres expérimentaux, les IDs d'exécution de package, les IDs de transactions et d'ordres constitutifs, les IDs d'ordres parents et les curseurs de pagination des packages sont des chaînes décimales. Conservez-les sous forme de chaînes dans votre client ; les convertir en nombres JavaScript peut entraîner une perte de précision. Les réponses héritées view=legs conservent leurs représentations existantes.

Compatibilité : la découverte d'instruments et les vues d'ordres héritées conservent leur contrat outright. Les exécutions réelles des jambes d'options continuent d'apparaître dans les flux hérités de transactions et d'exécutions, et les positions restent des positions sur options. L'ordre parent d'un combo n'est pas un ensemble d'ordres de jambes en attente indépendants.

S'abonner explicitement

Les canaux privés expérimentaux exigent l'étape d'authentification WebSocket existante et un abonnement explicite. Ils ne publient que les enregistrements d'ordres parents du portefeuille authentifié.

Canal	Message	Destinataires
experimental_order_updates	ExperimentalOrderUpdate avec l'ID parent, le symbole, le type d'instrument (option, perp ou combo), le statut, la quantité, la quantité exécutée et le prix net	Portefeuille authentifié
experimental_combo_trades	ComboTrade avec l'ID d'exécution, le symbole, la quantité du package, le prix net et les IDs de transaction des jambes	Public
experimental_combo_fills	ComboFill avec l'ID de l'ordre parent du portefeuille, le sens et l'exécution du package	Portefeuille authentifié

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

ExperimentalOrderUpdate.status utilise Acked, Open, PartiallyFilled, Filled, Canceled ou Rejected, et non les valeurs en majuscules de OrderUpdate. Les IDs et les quantités sont des chaînes.

Abonnez-vous au canal de carnet existant avec un symbole de combo découvert :

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

Les mises à jour de découverte de marché peuvent répéter la même définition immuable ; dédupliquez-les par ID de combo. Elles utilisent MarketUpdate sur market_updates, avec action: "ComboCreated", le symbole du combo, l'ID, les jambes canoniques et l'horodatage. Traitez la découverte, le statut des ordres parents, les résumés d'exécution des packages et les exécutions réelles des jambes comme des enregistrements distincts lors du rapprochement dans votre client.