API de Combos Experimental

Combos negociam uma proporção fixa de pernas de opções como uma única ordem. Um fill executa todas as pernas exigidas em conjunto. Suas posições continuam sendo as opções individuais.

Contrato experimental

Todos os endpoints /experimental e as mensagens WebSocket explicitamente experimentais são instáveis. Mudanças incompatíveis podem entrar em vigor com um dia (24 horas) de aviso prévio, incluindo a remoção ou renomeação de campos ou endpoints, a alteração de tipos de campos e a mudança no comportamento de requisições ou respostas. As mudanças são anunciadas no changelog da API. Os clientes devem acompanhar esses avisos e se atualizar antes do horário de vigência informado. Os contratos de API existentes não experimentais estão fora desta política.

A disponibilidade depende do seu ambiente. Esta página descreve a interface experimental; ela não anuncia disponibilidade em produção nem uma nova interface no aplicativo de trading.

Use a referência REST, o guia de autenticação e o guia de WebSocket para as convenções compartilhadas de conexão e assinatura.

Descobrir um combo

Requisição	Resultado
GET /experimental/combos	Uma página limitada de definições não vencidas, opcionalmente filtrada por underlying
GET /experimental/combos/{symbol}	Uma definição não vencida e suas pernas de opção resolvidas

Criação pela primeira ordem: envie um combo_definition canônico com POST /order quando o combo ainda não puder ser descoberto. A primeira ordem aceita publica sua definição, inclusive uma ordem que é executada imediatamente. Uma ordem rejeitada não publica nada. Não existe um endpoint de criação separado.

Tempo de vida da descoberta: uma definição permanece descobrível até o vencimento de sua primeira perna, mesmo quando não há ordens em repouso.

Paginação: as respostas contêm combos e next_cursor. Defina limit entre 1 e 1.000 (padrão 100). Passe o cursor retornado como cursor na próxima requisição, mantendo o mesmo filtro underlying. Um cursor nulo significa que nenhuma linha adicional foi observada. Limites ou cursores inválidos retornam HTTP 400.

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

Ordenação das páginas: vencimento da perna mais próxima, depois ID do combo. Trate os cursores como opacos. Cada página reflete o estado atual da descoberta; definições podem vencer ou ser adicionadas entre requisições. Use as atualizações de criação ou reinicie a descoberta para capturar definições recém-criadas que fiquem ordenadas antes de um cursor salvo.

Identidade: um símbolo é COMBO- seguido de 64 caracteres hexadecimais minúsculos. Seu ID vinculado ao conteúdo fixa os instrumentos das pernas e as proporções inteiras com sinal. Um símbolo existente não pode mudar de significado.

Escopo inicial: de duas a oito pernas de opção distintas com o mesmo ativo subjacente. Toda perna deve estar listada, não vencida e elegível para a rota de execução solicitada.

Entender lado, preço e tamanho

Para uma definição canônica com proporções +1 A, -1 B:

• Comprar um pacote: compra um A e vende um B.
• Vender um pacote: vende um A e compra um B.
• Preço líquido: price(A) - price(B), cotado por pacote.
• Limite: uma compra aceita um preço líquido igual ou inferior ao seu limite; uma venda aceita um preço líquido igual ou superior ao seu limite.

Preços negativos e zero são válidos. Se A é negociado a $8 e B a$10, o preço líquido canônico é -2. Quem compra esse pacote recebe $2 antes das taxas. Quem o vende paga$2 antes das taxas. Cada perna real de opção continua tendo um preço de execução positivo.

Incrementos da ordem: o tamanho do pacote usa unidades de contrato legíveis com incremento de 0.000001; o preço limite líquido usa incremento de 0.000001. Cada perna executada também deve respeitar seus próprios incrementos de quantidade e preço. Um fill parcial preserva todas as proporções e executa uma quantidade completa e permitida de pacotes.

Taxas: aplicam-se as alíquotas e a elegibilidade existentes por perna, sem desconto por pacote. A ordem entrante é a taker em suas próprias pernas, com a atribuição de builder enviada. Em uma rota de outright via combo, a ordem combo pai recebe a atribuição normal de taxa de taker nas pernas de suporte adicionais contra os makers outright de suporte; essas pernas não têm atribuição de builder. As reservas de combos em repouso incluem de forma conservadora as taxas de taker prospectivas sobre os valores brutos das pernas. A execução atual em Standard Margin exige taxas de trading zero para fills no livro e via RFQ; uma rota que envolva um participante SM não pode ser executada com taxas de trading diferentes de zero.

Margem: a exchange verifica as posições de opções resultantes e a exposição das ordens restantes para cada conta. Um combo não combina colateral entre carteiras nem promete uma redução de margem específica. Se o nível da sua conta permite apenas vendas cobertas de opções, as ordens outright em repouso e as pernas de venda de cada combo pai compartilham o mesmo inventário long executado. Pais separados e fills divididos não podem reutilizar esse inventário cada um; pernas de compra não executadas não adicionam cobertura.

Enviar uma ordem

Use a requisição assinada existente POST /order com o símbolo do combo. Os campos de assinatura da ordem não mudam. Assine exatamente as strings symbol, size e price que você envia, incluindo o sinal de menos de um preço negativo. Para um novo combo, adicione seu combo_definition canônico conforme descrito abaixo. O símbolo assinado, vinculado ao conteúdo, compromete-se com essa definição; uma definição divergente é rejeitada. Combos conhecidos podem omiti-la.

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

Substitua os placeholders e o nonce pelos seus valores reais. O preço é ilustrativo, não uma cotação atual de mercado.

Configuração	Comportamento
route: "book_only"	Executa contra a liquidez direta e a liquidez implícita suportada disponíveis e depois aplica o time in force
route: "best_execution"	Considera um leilão de melhoria de preço do pacote completo e recorre à execução no livro quando apropriado
route: "rfq_only"	Rejeitado em /order
tif: "gtc"	Deixa em repouso o restante não executado do pacote
tif: "ioc"	Cancela o restante não executado
tif: "fok"	Executa toda a quantidade de pacotes solicitada ou não executa nada

A melhoria de preço compara o preço líquido assinado do pacote completo com uma referência executável do livro para o tamanho total. Os provedores de cotação devem fornecer todas as pernas na proporção e quantidade exatas solicitadas. Classificar uma cotação apenas pela primeira perna é insuficiente. Tanto a liquidez direta de combos quanto as rotas implícitas suportadas podem compor a referência. Uma referência indisponível ou incompleta envia a ordem para execução no livro.

Elegibilidade das cotações: as regras de taxas de RFQ existentes também se aplicam. Se qualquer um dos participantes usar Standard Margin, a execução via RFQ exige taxas de trading zero. Uma cotação que falhe nas verificações de taxa, colateral ou alocação exata deixa a execução com o caminho atual do livro; ela não executa parcialmente suas pernas.

O matching implícito pode combinar um combo com a liquidez outright de opções que o sustenta. Por exemplo, uma ordem outright em A pode ser negociada atomicamente contra um combo A menos B e liquidez em B. Um cliente que negocia apenas A não recebe posição em B.

As buscas implícitas têm limites de recursos. Se uma ordem outright atingir esses limites, se sua liquidez de suporte ficar indisponível ou se a rota opcional não puder representar os incrementos da ordem outright, ela ainda pode ser negociada contra seu livro de ofertas direto de opções sob as regras usuais de ordens. O suporte a combos não altera os incrementos de quantidade ou preço aceitos para outrights. A opção alvo deve continuar elegível para negociação no livro. Uma ordem combo que exceda os limites de busca é rejeitada sem alocação parcial.

Restrições atuais: ordens combo nativas exigem mmp_enabled: false. Participantes outright protegidos mantêm o MMP. Um pacote que dispare o limite conclui suas pernas e interrompe o matching posterior; um FOK incompleto ou uma substituição atômica reverte o candidato completo. Ordens reduce-only pulam o leilão de melhoria de preço e usam a admissão no livro, onde cada perna resultante deve passar nas verificações de reduce-only. Cancele um combo em repouso pelo ID da ordem pai ou pelo ID de ordem do cliente usando os endpoints de cancelamento existentes.

Substituição: PUT /order pode substituir atomicamente uma ordem pai dentro da mesma definição de combo. Uma substituição rejeitada mantém a ordem anterior intacta. Entradas nativas em substituições em lote também usam um comando atômico por ordem pai; o lote não é uma única transação tudo ou nada. Substituições entre um combo e um outright, ou entre definições de combo diferentes, são rejeitadas.

Prevenção de self-trade: o matching para antes que uma rota negocie uma conta contra ela mesma e cancela a ordem maker em repouso. Os fills concluídos anteriormente permanecem, enquanto o restante da ordem entrante é cancelado. Sem fills anteriores, a ordem entrante é rejeitada. Ordens FOK e substituições atômicas com falha preservam seu comportamento tudo ou nada, incluindo a reversão de cancelamentos provisórios de makers.

Definir um combo na primeira ordem

Canonicalize antes de assinar: combine IDs de instrumento duplicados, remova proporções zero, ordene os IDs numericamente, divida as proporções pelo máximo divisor comum e torne a primeira proporção positiva. Se a normalização inverter as proporções, inverta o lado pretendido da ordem e negue o preço líquido. Se ela dividir as proporções por um fator, multiplique o tamanho do pacote por esse fator e divida o preço líquido por ele.

O ID da versão um é o Keccak-256 da seguinte concatenação:

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

IDs de instrumento são o Keccak-256 de "instrument" em UTF-8 seguido do símbolo canônico exato da opção. O ID do combo publicado é o digest completo, codificado como 0x mais 64 caracteres hexadecimais minúsculos. O símbolo do combo usa os mesmos dígitos hexadecimais após COMBO-.

Inclua combo_definition no corpo assinado comum de POST /order. A definição contém version, id e legs; cada perna contém instrument_id e ratio. Codifique os IDs como 0x mais 64 dígitos hexadecimais minúsculos e as proporções como strings decimais canônicas com sinal, como "1" ou "-1". Números JSON, sinais de mais à esquerda e zeros à esquerda são rejeitados nas proporções.

{
  "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 é adicionado ao exemplo completo de ordem acima. Substitua os placeholders pelos IDs reais e use o símbolo COMBO- correspondente. Não há assinatura adicional da definição nem nonce de publicação separado. O serviço verifica o conteúdo canônico e sua identidade contra o símbolo assinado; ordens outright devem omitir combo_definition.

Aceitação e descoberta: toda ordem combo aceita mantém sua definição no registro durável da ordem e garante de forma idempotente que a entrada no catálogo exista. Uma ordem posterior não sobrescreve o primeiro registro de criação. Uma ordem executada imediatamente ainda cria dados de descoberta; ordens rejeitadas não. A descoberta pode atrasar em relação à confirmação da ordem porque é projetada a partir de dados confirmados. Reenviar a mesma definição em uma ordem posterior é suportado, inclusive enquanto a primeira entrada no catálogo ainda está sendo atualizada.

Ler ordens e execuções

Requisição	Finalidade
GET /experimental/orders	Lê ordens com classificação explícita de instrumento, incluindo ordens combo pai
GET /experimental/trades	Lê os trades reais das pernas por padrão, ou resumos de pacotes de um combo com view=packages&symbol=<COMBO symbol>
GET /experimental/fills	Lê os fills da carteira por padrão, ou resumos de pacotes da carteira com view=packages

Use a referência REST para os filtros e cursores suportados. As visões de pacotes paginam com limit (1 a 1.000, padrão 100) e before_execution_id, não offset: passe o next_before_execution_id retornado para obter a próxima página. Trades de pacotes exigem um symbol COMBO- canônico; fills de pacotes recebem wallet e um symbol opcional. Resumos de pacotes são registros de agrupamento: os IDs de execução e os IDs de trade das pernas permitem relacioná-los às execuções reais de opções. Não some a quantidade, o prêmio ou as taxas do pacote às execuções constituintes ao calcular os totais da conta.

Precisão dos identificadores: IDs de ordens experimentais, IDs de execução de pacotes, IDs de trades/ordens constituintes, IDs de ordens pai e cursores de paginação de pacotes são strings decimais. Mantenha-os como strings no seu cliente; convertê-los para números JavaScript pode causar perda de precisão. As respostas legadas de view=legs mantêm suas representações existentes.

Compatibilidade: a descoberta de instrumentos e as visões de ordens legadas mantêm seu contrato outright. As execuções reais das pernas de opção continuam aparecendo nos feeds legados de trades/fills, e as posições continuam sendo posições de opções. A ordem pai de um combo não é uma coleção de ordens de pernas em repouso independentes.

Assinar explicitamente

Os canais privados experimentais exigem a etapa existente de autenticação WebSocket e uma assinatura explícita. Eles publicam apenas os registros pai da carteira autenticada.

Canal	Mensagem	Público
experimental_order_updates	ExperimentalOrderUpdate com ID da ordem pai, símbolo, tipo de instrumento (option, perp ou combo), status, quantidade, quantidade executada e preço líquido	Carteira autenticada
experimental_combo_trades	ComboTrade com ID de execução, símbolo, quantidade de pacotes, preço líquido e IDs de trade das pernas	Público
experimental_combo_fills	ComboFill com o ID da ordem pai da carteira, lado e execução do pacote	Carteira autenticada

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

ExperimentalOrderUpdate.status usa Acked, Open, PartiallyFilled, Filled, Canceled ou Rejected, e não os valores em maiúsculas de OrderUpdate. IDs e quantidades são strings.

Assine o canal de livro existente usando um símbolo de combo descoberto:

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

Atualizações de descoberta de mercado podem repetir a mesma definição imutável; deduplique pelo ID do combo. Elas usam MarketUpdate em market_updates, com action: "ComboCreated", o símbolo do combo, ID, pernas canônicas e timestamp. Trate descoberta, status da ordem pai, resumos de execução de pacotes e fills reais das pernas como registros distintos ao reconciliar seu cliente.