API experimental de combos

Los combos negocian una proporción fija de patas de opciones como una sola orden. Un fill ejecuta todas las patas requeridas a la vez. Sus posiciones siguen siendo las opciones individuales.

Contrato experimental

Todos los endpoints /experimental y los mensajes de WebSocket marcados explícitamente como experimentales son inestables. Los cambios incompatibles pueden entrar en vigor con un día (24 horas) de aviso previo, lo que incluye eliminar o renombrar campos o endpoints, cambiar tipos de campos y modificar el comportamiento de solicitudes o respuestas. Los cambios se anuncian en el registro de cambios de la API. Los clientes deben seguir estos avisos y actualizarse antes de la hora de entrada en vigor indicada. Los contratos de API existentes que no son experimentales quedan fuera de esta política.

La disponibilidad depende de su entorno. Esta página describe la interfaz experimental; no anuncia disponibilidad en producción ni una nueva interfaz en la aplicación de trading.

Consulte la referencia REST, la guía de autenticación y la guía de WebSocket para las convenciones compartidas de conexión y firma.

Descubrir un combo

Solicitud	Resultado
GET /experimental/combos	Una página acotada de definiciones no vencidas, opcionalmente filtrada por underlying
GET /experimental/combos/{symbol}	Una definición no vencida y sus patas de opciones resueltas

Creación con la primera orden: envíe una combo_definition canónica con POST /order cuando el combo aún no sea descubrible. La primera orden aceptada publica su definición, incluso si la orden se ejecuta de inmediato. Una orden rechazada no publica nada. No existe un endpoint de creación separado.

Vigencia del descubrimiento: una definición sigue siendo descubrible hasta que vence su primera pata, aunque no tenga órdenes en reposo.

Paginación: las respuestas contienen combos y next_cursor. Establezca limit entre 1 y 1000 (por defecto 100). Pase el cursor devuelto como cursor en la siguiente solicitud, manteniendo el mismo filtro underlying. Un cursor nulo significa que no se observaron más filas. Los límites o cursores inválidos devuelven HTTP 400.

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

Orden de las páginas: primero por el vencimiento más temprano de las patas y luego por ID del combo. Trate los cursores como opacos. Cada página refleja el estado actual del descubrimiento; las definiciones pueden vencer o agregarse entre solicitudes. Use las actualizaciones de creación o reinicie el descubrimiento para capturar definiciones recién creadas que se ordenen antes de un cursor guardado.

Identidad: un símbolo es COMBO- seguido de 64 caracteres hexadecimales en minúscula. Su ID ligado al contenido fija los instrumentos de las patas y las proporciones enteras con signo. Un símbolo existente no puede cambiar de significado.

Alcance inicial: de dos a ocho patas de opciones distintas con el mismo activo subyacente. Cada pata debe estar listada, no vencida y ser elegible para la ruta de ejecución solicitada.

Entender el lado, el precio y el tamaño

Para una definición canónica con proporciones +1 A, -1 B:

• Comprar un paquete: comprar una A y vender una B.
• Vender un paquete: vender una A y comprar una B.
• Precio neto: price(A) - price(B), cotizado por paquete.
• Límite: una compra acepta un precio neto igual o inferior a su límite; una venta acepta un precio neto igual o superior a su límite.

Los precios negativos y cero son válidos. Si A cotiza a $8 y B a$10, el precio neto canónico es -2. Comprar ese paquete recibe $2 antes de comisiones. Venderlo paga$2 antes de comisiones. Cada pata real de opción sigue teniendo un precio de ejecución positivo.

Incrementos de la orden: el tamaño del paquete usa unidades de contrato legibles con un incremento de 0.000001; el precio límite neto usa un incremento de 0.000001. Cada pata ejecutada también debe cumplir sus propios incrementos de cantidad y precio. Un fill parcial conserva todas las proporciones y ejecuta una cantidad completa y permitida del paquete.

Comisiones: se aplican las tasas y la elegibilidad existentes por pata, sin descuento por paquete. La orden entrante es taker en sus propias patas, con la atribución de builder que envió. En una ruta outright-a-través-de-combo, la orden padre del combo recibe la atribución normal de comisión taker en las patas de soporte adicionales frente a los makers outright de soporte; esas patas no tienen atribución de builder. Las reservas de combos en reposo incluyen de forma conservadora las comisiones taker prospectivas sobre los importes brutos de las patas. La ejecución actual de Standard Margin requiere comisiones de trading cero para fills del libro y de RFQ; una ruta que involucre a un participante SM no puede ejecutarse con comisiones de trading distintas de cero.

Margen: el exchange verifica las posiciones de opciones resultantes y la exposición restante de las órdenes para cada cuenta. Un combo no combina colateral entre wallets ni promete una reducción de margen concreta. Si el nivel de su cuenta solo permite ventas cubiertas de opciones, las órdenes outright en reposo y las patas de venta de cada orden padre de combo comparten el mismo inventario long ejecutado. Distintas órdenes padre y fills divididos no pueden reutilizar cada uno ese inventario; las patas de compra no ejecutadas no añaden cobertura.

Enviar una orden

Use la solicitud firmada existente POST /order con el símbolo del combo. Los campos de firma de la orden no cambian. Firme exactamente las cadenas symbol, size y price que envía, incluido el signo menos de un precio negativo. Para un combo nuevo, agregue su combo_definition canónica como se describe más abajo. El símbolo firmado y ligado al contenido se compromete con esa definición; una definición que no coincida se rechaza. Los combos ya conocidos pueden omitirla.

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

Reemplace los marcadores y el nonce por sus valores reales. El precio es ilustrativo, no una cotización actual del mercado.

Parámetro	Comportamiento
route: "book_only"	Casa contra la liquidez directa e implícita admitida disponible y luego aplica el time in force
route: "best_execution"	Considera una subasta de mejora de precio del paquete completo y, cuando corresponde, recurre a la ejecución en el libro
route: "rfq_only"	Rechazado en /order
tif: "gtc"	Deja en reposo el remanente no ejecutado del paquete
tif: "ioc"	Cancela el remanente no ejecutado
tif: "fok"	Ejecuta toda la cantidad de paquetes solicitada o no ejecuta nada

La mejora de precio compara el precio neto firmado del paquete completo con una referencia ejecutable del libro a tamaño completo. Los proveedores de cotizaciones deben cubrir cada pata con la proporción y la cantidad exactas solicitadas. Clasificar una cotización solo por su primera pata es insuficiente. Tanto la liquidez directa del combo como las rutas implícitas admitidas pueden contribuir a la referencia. Una referencia no disponible o incompleta envía la orden a ejecución en el libro.

Elegibilidad de cotizaciones: también se aplican las reglas de comisiones de RFQ existentes. Si alguno de los participantes usa Standard Margin, la ejecución por RFQ requiere comisiones de trading cero. Una cotización que no supera las verificaciones de comisiones, colateral o asignación exacta deja la ejecución en la ruta actual del libro; no ejecuta parcialmente sus patas.

El matching implícito puede combinar un combo con la liquidez de opciones outright que lo respalda. Por ejemplo, una orden outright sobre A puede operar de forma atómica contra un combo A-menos-B y liquidez de B. Un cliente que solo opera A no recibe ninguna posición en B.

Las búsquedas implícitas tienen límites de recursos. Si una orden outright alcanza esos límites, su liquidez de soporte deja de estar disponible o la ruta opcional no puede representar los incrementos de la orden outright, aún puede operar contra su libro de opciones directo bajo las reglas habituales de órdenes. El soporte de combos no cambia los incrementos de cantidad o precio aceptados para órdenes outright. La opción objetivo debe seguir siendo elegible para operar en el libro. Una orden de combo que supere los límites de búsqueda se rechaza sin asignación parcial.

Restricciones actuales: las órdenes de combo nativas requieren mmp_enabled: false. Los participantes outright protegidos conservan MMP. Un paquete que activa el umbral completa sus patas y detiene el matching posterior; una orden FOK incompleta o un reemplazo atómico revierte el candidato completo. Las órdenes reduce-only omiten la subasta de mejora de precio y usan la admisión en el libro, donde cada pata resultante debe superar las verificaciones reduce-only. Cancele un combo en reposo por el ID de su orden padre o por el ID de orden del cliente usando los endpoints de cancelación existentes.

Reemplazo: PUT /order puede reemplazar atómicamente una orden padre dentro de la misma definición de combo. Un reemplazo rechazado deja intacta la orden anterior. Las entradas nativas en reemplazos masivos también usan un comando atómico por orden padre; el lote no es una única transacción de todo o nada. Se rechaza el reemplazo entre un combo y una orden outright, o entre definiciones de combo distintas.

Prevención de autonegociación: el matching se detiene antes de que una ruta haga operar a una cuenta contra sí misma, y cancela la orden maker en reposo. Los fills completados previamente se mantienen, mientras que el remanente entrante se cancela. Si no hubo fills previos, la orden entrante se rechaza. Las órdenes FOK y los reemplazos atómicos fallidos conservan su comportamiento de todo o nada, incluida la reversión de las cancelaciones tentativas de órdenes maker.

Definir un combo en su primera orden

Canonicalice antes de firmar: combine los IDs de instrumento duplicados, elimine las proporciones cero, ordene los IDs numéricamente, divida las proporciones por su máximo común divisor y haga positiva la primera proporción. Si la normalización invierte las proporciones, invierta el lado previsto de la orden y cambie el signo del precio neto. Si divide las proporciones por un factor, multiplique el tamaño del paquete por ese factor y divida el precio neto por él.

El ID de la versión uno es el Keccak-256 de la siguiente concatenación:

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

Los IDs de instrumento son el Keccak-256 de "instrument" en UTF-8 seguido del símbolo canónico exacto de la opción. El ID de combo publicado es el digest completo, codificado como 0x más 64 caracteres hexadecimales en minúscula. El símbolo del combo usa los mismos dígitos hexadecimales después de COMBO-.

Incluya combo_definition en el cuerpo firmado habitual de POST /order. La definición contiene version, id y legs; cada pata contiene instrument_id y ratio. Codifique los IDs como 0x más 64 dígitos hexadecimales en minúscula y las proporciones como cadenas decimales canónicas con signo, como "1" o "-1". Para las proporciones se rechazan los números JSON, los signos más iniciales y los ceros iniciales.

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

Este fragmento se añade al ejemplo completo de orden anterior. Reemplace los marcadores por IDs reales y use el símbolo COMBO- correspondiente. No hay una firma adicional de la definición ni un nonce de publicación separado. El servicio verifica el contenido canónico y su identidad frente al símbolo firmado; las órdenes outright deben omitir combo_definition.

Aceptación y descubrimiento: cada orden de combo aceptada conserva su definición en su registro durable de orden y garantiza de forma idempotente que exista la entrada en el catálogo. Una orden posterior no sobrescribe el primer registro de creación. Una orden ejecutada de inmediato igualmente genera datos de descubrimiento; las órdenes rechazadas no. El descubrimiento puede ir por detrás de la confirmación de la orden, porque se proyecta a partir de datos confirmados. Se admite reenviar la misma definición en una orden posterior, incluso mientras su primera entrada en el catálogo aún se está poniendo al día.

Leer órdenes y ejecuciones

Solicitud	Propósito
GET /experimental/orders	Leer órdenes con clasificación explícita del instrumento, incluidas las órdenes padre de combos
GET /experimental/trades	Leer por defecto las operaciones reales de cada pata, o resúmenes de paquete de un combo con view=packages&symbol=<COMBO symbol>
GET /experimental/fills	Leer por defecto los fills de la wallet, o resúmenes de paquete de la wallet con view=packages

Consulte la referencia REST para los filtros y cursores admitidos. Las vistas de paquete se paginan con limit (de 1 a 1000, por defecto 100) y before_execution_id, no con offset: pase el next_before_execution_id devuelto para obtener la página siguiente. Las operaciones por paquete requieren un symbol canónico COMBO-; los fills por paquete aceptan wallet y un symbol opcional. Los resúmenes de paquete son registros de agrupación: los IDs de ejecución y los IDs de operación de cada pata le permiten vincularlos con las ejecuciones reales de opciones. No sume la cantidad, la prima ni las comisiones del paquete a las de las ejecuciones que lo componen al calcular los totales de la cuenta.

Precisión de los identificadores: los IDs de órdenes experimentales, los IDs de ejecución de paquetes, los IDs de operaciones y órdenes constituyentes, los IDs de órdenes padre y los cursores de paginación de paquetes son cadenas decimales. Manténgalos como cadenas en su cliente; convertirlos a números de JavaScript puede provocar pérdida de precisión. Las respuestas heredadas view=legs conservan sus representaciones existentes.

Compatibilidad: el descubrimiento de instrumentos y las vistas de órdenes heredados mantienen su contrato outright. Las ejecuciones reales de las patas de opciones siguen apareciendo en los feeds heredados de operaciones y fills, y las posiciones siguen siendo posiciones de opciones. La orden padre de un combo no es una colección de órdenes de patas en reposo independientes.

Suscribirse explícitamente

Los canales privados experimentales requieren el paso de autenticación de WebSocket existente y una suscripción explícita. Solo publican los registros padre de la wallet autenticada.

Canal	Mensaje	Audiencia
experimental_order_updates	ExperimentalOrderUpdate con ID de la orden padre, símbolo, tipo de instrumento (option, perp o combo), estado, cantidad, cantidad ejecutada y precio neto	Wallet autenticada
experimental_combo_trades	ComboTrade con ID de ejecución, símbolo, cantidad de paquetes, precio neto e IDs de operación de las patas	Público
experimental_combo_fills	ComboFill con el ID de la orden padre de la wallet, el lado y la ejecución del paquete	Wallet autenticada

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

ExperimentalOrderUpdate.status usa Acked, Open, PartiallyFilled, Filled, Canceled o Rejected, no los valores en mayúsculas de OrderUpdate. Los IDs y las cantidades son cadenas.

Suscríbase al canal de libro existente usando un símbolo de combo descubierto:

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

Las actualizaciones de descubrimiento de mercado pueden repetir la misma definición inmutable; elimine duplicados por ID de combo. Usan MarketUpdate en market_updates, con action: "ComboCreated", el símbolo del combo, el ID, las patas canónicas y la marca de tiempo. Trate el descubrimiento, el estado de las órdenes padre, los resúmenes de ejecución de paquetes y los fills reales de las patas como registros distintos al conciliar su cliente.