Pular para o conteúdo principal

watchOrders

Receba atualizações em tempo real sobre o status das ordens de compra e venda.

Subscrição​

{
"action": "subscribe",
"channel": "watchOrders"
}

Identificador e sequência de cada mensagem​

Toda mensagem do canal, ao vivo ou reenviada, traz dois campos além de channel e message:

{
"channel": "watchorders",
"message": { "id": "string", "status": "OPEN" },
"messageId": "string",
"sequence": 1042
}
CampoTipoDescrição
messageIdstringIdentificador único da mensagem. A mesma mensagem mantém o mesmo messageId mesmo que seja entregue de novo ou reenviada — use-o para ignorar duplicatas
sequencenumberNúmero de registro da mensagem. Sempre cresce, por empresa e por ambiente: a sequência de sandbox e a de produção são independentes

Duas regras de leitura:

  • sequence é o ponto de retomada, não a ordem dos eventos. Guarde o maior sequence que você recebeu; é ele que você informa ao pedir o que perdeu (próxima seção). Para decidir qual é o estado mais recente de uma ordem, continue usando updatedAt, como descrito em O canal é complemento, não substituto.
  • A sequência é contínua. Um salto (por exemplo de 41 para 43) quer dizer que você não recebeu a mensagem que falta: peça o reenvio a partir do último sequence que você processou, como descrito na próxima seção. A única exceção é numa troca de infraestrutura de contingência, quando a sequência pode dar um salto proposital; o reenvio dessa faixa volta vazio, e isso não é perda.

Reenvio de mensagens perdidas​

A conexão cai (veja Conexão), e o que acontece com a ordem nesse intervalo você não recebe. Para recuperar, peça o reenvio pela própria conexão, depois de assinar o canal de novo:

{
"action": "resendMessages",
"channel": "watchOrders",
"fromSequence": 1042
}
CampoTipoDescrição
channelstringwatchOrders. Hoje é o único canal com reenvio
fromSequencenumberReenvia as mensagens com sequence maior que este valor. Informe o último que você processou. 0 pede desde a mais antiga guardada
sincenumberAlternativa ao fromSequence: horário em epoch de segundos. Reenvia as mensagens registradas a partir dele, inclusive, com uma folga de alguns segundos para trás — pode vir uma ou outra mensagem a mais na borda, nunca a menos

Envie exatamente um entre fromSequence e since. Prefira o fromSequence: ele não depende do relógio do seu sistema.

Cada mensagem reenviada chega como no tempo real, com o mesmo messageId e o mesmo sequence, mais o campo replayed: true:

{
"channel": "watchorders",
"message": { "id": "string", "status": "CANCELLED" },
"messageId": "string",
"sequence": 1043,
"replayed": true
}

As mensagens reenviadas chegam em ordem crescente de sequence, e depois delas vem um fechamento:

{
"action": "resendMessagesResult",
"channel": "watchorders",
"count": 2,
"fromSequence": 1042,
"lastSequence": 1044,
"hasMore": false,
"nextSequence": null,
"oldestAvailableSequence": 980
}
CampoDescrição
countQuantas mensagens foram reenviadas neste pedido
lastSequenceO maior sequence reenviado; null se nada foi reenviado
hasMoretrue quando ainda há mensagens a reenviar
nextSequenceQuando hasMore é true, o valor a usar como fromSequence no próximo pedido
oldestAvailableSequenceO sequence da mensagem mais antiga ainda guardada; null se não há nenhuma

Limites e regras

  • Cada pedido reenvia até 500 mensagens. Se hasMore vier true, peça de novo com fromSequence igual ao nextSequence, até vir false.
  • As mensagens ficam guardadas por pelo menos 7 dias. Se o seu fromSequence for menor que oldestAvailableSequence, existe um trecho que não pode mais ser reenviado: reconcilie esse trecho pelo REST (fetchOrder).
  • Um reenvio por vez em cada conexão. Um segundo pedido enquanto o primeiro não terminou volta resend already in progress; espere o resendMessagesResult antes de pedir de novo.
  • O reenvio só entrega o que você tem permissão de receber no canal, a mesma regra do subscribe, e só da sua empresa.
  • Você pode receber a mesma mensagem duas vezes, ao vivo e reenviada, se o pedido de reenvio cruzar com o tempo real. Ignore a que tiver messageId já processado.
  • O reenvio não é automático: ao reconectar, assine o canal e peça o reenvio a partir do último sequence que você guardou.

Quando o pedido é recusado, o fechamento vem com error no lugar dos contadores, e nada é reenviado:

{ "action": "resendMessagesResult", "channel": "watchorders", "error": "send exactly one of fromSequence or since" }
errorCausa
invalid JSON bodyo corpo não é um objeto JSON
channel is requiredfaltou channel
channel not supportedo canal não tem reenvio
permission denied for channela sua chave não tem permissão para o canal
send exactly one of fromSequence or sinceveio os dois, ou nenhum
fromSequence must be a non-negative integerfromSequence fora do formato
since must be a unix timestamp in secondssince fora do formato (milissegundos, ou no futuro)
resend already in progressjá há um reenvio em andamento nesta conexão
internal errorfalha do nosso lado; tente de novo em alguns segundos

Payload de Dados​

Notificação enviada quando o status de uma ordem muda. O conteúdo de message segue o mesmo schema retornado por GET /orders/fetchOrder — varia conforme o status:

  • Ordens em estados não terminais (ex.: pending, executed) trazem apenas o bloco base abaixo.
  • Ordens closed trazem o bloco base + campos estendidos (account, orderPoolId, filledStatus, cost, price, info, fee, trades, RFQ, settlement).
  • Ordens rejected trazem o bloco base com errorMessage preenchido e sem os campos estendidos.

Exemplo de ordem closed​

{
"channel": "watchorders",
"messageId": "string",
"sequence": 1042,
"message": {
"id": "string",
"exchange": "string",
"symbol": "string",
"side": "buy",
"type": "market",
"status": "closed",
"errorMessage": "",
"amount": "string",
"amountOriginal": "string",
"remainingAmount": "string",
"quoteAmount": "string",
"quoteAmountOriginal": "string",
"remainingQuoteAmount": "string",
"average": "string",
"createdAt": 1712100000,
"updatedAt": 1712100012,
"executedAt": 1712100012,
"channel": "string",
"rule": "string",
"operationalFees": "string",
"fxComposition": {
"side": "ask",
"dollarBase": "string",
"iofPercentage": "string",
"brokerageFeePercentage": "string",
"outsideBizHoursSpreadPercentage": "string",
"dollarWithFxFees": "string",
"feesIncludedByProvider": false
},
"account": "string",
"orderPoolId": "string",
"filledStatus": "filled",
"filled": "string",
"remaining": "string",
"cost": "string",
"price": "string",
"info": "string",
"fee": {
"cost": "string",
"rate": "string",
"cripto": "string",
"tierCaas": {
"currentTierFeeRate": "string",
"currentTierFeeFiat": "string",
"currentTierFeeCripto": "string"
}
},
"trades": [
{
"id": "string",
"takerOrMaker": "string",
"type": "string",
"side": "string",
"price": "string",
"amount": "string",
"cost": "string",
"timestamp": 1712100012,
"fee": {
"cost": "string",
"rate": "string",
"cripto": "string"
}
}
]
}
}

Exemplo de ordem rejected​

{
"channel": "watchorders",
"messageId": "string",
"sequence": 1043,
"message": {
"id": "string",
"exchange": "string",
"symbol": "string",
"side": "sell",
"type": "market",
"status": "rejected",
"errorMessage": "Insufficient balance",
"amount": "string",
"quoteAmount": "string",
"quoteAmountOriginal": "string",
"remainingQuoteAmount": "string",
"average": "0",
"createdAt": 1712100000,
"updatedAt": 1712100120,
"channel": "string",
"rule": "string",
"operationalFees": "string",
"fxComposition": {
"side": "ask",
"dollarBase": "string",
"iofPercentage": "string",
"brokerageFeePercentage": "string",
"outsideBizHoursSpreadPercentage": "string",
"dollarWithFxFees": "string",
"feesIncludedByProvider": false
}
}
}

Campos do message​

Campos base (presentes em qualquer status)​

CampoTipoDescrição
idstringIdentificador da ordem
exchangestringExchange utilizada. Em modo liqi-managed retorna "liqi".
symbolstringPar de mercado (ex: BTC/BRL)
sidestringbuy ou sell
typestringTipo da ordem (market por padrão)
statusstringStatus atual — ver tabela de status abaixo
errorMessagestringMensagem de erro quando status = "rejected"; vazio nos demais casos
amountstringQuantidade de cripto
quoteAmountstringValor em FIAT (R$)
quoteAmountOriginalstringValor em FIAT originalmente solicitado
remainingQuoteAmountstringValor restante em FIAT
averagestringPreço médio de execução
createdAtnumberTimestamp Unix de criação
updatedAtnumberTimestamp Unix da última atualização
executedAtnumber?Timestamp Unix da execução (quando aplicável)
channelstringCanal de origem da ordem
rulestringRegra SOR utilizada
operationalFeesstringTaxas operacionais
fxCompositionobject?Composição do dólar de câmbio, quando a operação é em exchange em dólar. Opcional: quando não se aplica a chave não vem (nunca null). Mesmo conteúdo da consulta REST — ver Composição do dólar. Não vem no frame de fallback, publicado quando a releitura da ordem falha
executedExchangestring?Exchange que de fato executou. Presente quando difere do exchange — em modo liqi-managed é aqui que vem o nome real
evaluatedTickersarray?Preço que cada exchange oferecia no instante da cotação, e o motivo do desvio quando houve contingência. Mesmo conteúdo da consulta REST — ver Melhor execução

O payload deste canal é montado pelo mesmo formatador da consulta fetchOrder: campo que aparece lá aparece aqui, no mesmo formato.

fxComposition​

Objeto opcional, no topo do message, irmão de operationalFees. Só vem em ordem em exchange em dólar e nunca vem null: quando não se aplica, a chave está ausente. Os exemplos acima o mostram nos estados closed e rejected.

CampoTipoDescrição
sidestringLado do dólar usado: ask (compra) ou bid (venda)
dollarBasestringDólar base (USD/BRL) cotado no provedor de câmbio, com 4 casas
iofPercentagestringIOF, em percentual com 4 casas ("1.1000" = 1,1%)
brokerageFeePercentagestringCorretagem do câmbio, em percentual com 4 casas
outsideBizHoursSpreadPercentagestringSpread de fora do horário comercial, em percentual com 4 casas
dollarWithFxFeesstringDólar com as taxas de câmbio, truncado em 4 casas. Não é o dólar de liquidação da ordem
feesIncludedByProviderbooleantrue quando o provedor já entrega o dólar com as taxas embutidas; então IOF, corretagem e fora do horário vêm "0.0000"

Regras completas, fórmula e exceções em Composição do dólar.

Campos estendidos (em status = "closed"; RFQ e settlement também em executed)​

CampoTipoDescrição
accountstringID da conta do cliente
orderPoolIdstringID da ordem no pool
filledStatusstringDetalhe do preenchimento (ex.: filled, partiallyFilled)
amountOriginalstringQuantidade originalmente solicitada
remainingAmountstringQuantidade restante em cripto
filledstringQuantidade efetivamente preenchida
remainingstringQuantidade restante a preencher
coststringCusto total da ordem
pricestringPreço médio
infostringInformação adicional do provedor
feeobjectDetalhes das taxas (Liqi + tier)
tradesarrayLista de trades individuais que compuseram a ordem
RFQobject?Liquidação da ordem por cotação, em executed e closed: ordem RFQ e ordem a limite executada por cotação RFQ (ver Execução por cotação RFQ). Liquide por este objeto
settlementobject?Liquidação da ordem a limite, mantida por compatibilidade: amount, price e cost, em string decimal (somente em ordem a limite executada, em executed e closed; ordens antigas não trazem). Na ordem executada por cotação, traz os mesmos valores do RFQ. Ver fetchOrder

Status possíveis​

StatusDescrição
pendingOrdem aberta, em validação ou aguardando execução
executedOrdem executada no provedor, aguardando finalização
closedOrdem finalizada com sucesso (campos estendidos presentes)
rejectedOrdem rejeitada (errorMessage preenchido)
expiredCotação RFQ que expirou antes de virar ordem
observação

O canal sempre chega em minúsculas no payload ("channel": "watchorders"), mesmo se você tiver subscrito como watchOrders.

Ordem a limite​

O canal cobre a ordem a limite desde agosto de 2026, e publica todas as mudanças de status — não apenas o encerramento.

TransiçãoQuando chega
OPENa ordem foi validada e passou a ser observada
TRIGGEREDo preço alcançou o alvo e a execução foi disparada
PROCESSING / EXECUTED / closedo ciclo de execução, igual ao da ordem a mercado
OPEN (de novo)re-arm: a execução falhou de forma recuperável e a ordem voltou a observar
CANCELLINGcancelamento de uma ordem foi aceito (não ocorre no cancelamento em lote)
CANCELLEDcancelamento concluído — um evento por ordem, inclusive no lote
EXPIREDo prazo terminou sem a ordem atingir o alvo
REJECTEDrecusa definitiva (duplicata, saldo ou recusa da exchange) — ver a lista de casos

O message é o mesmo objeto do fetchOrder: além dos campos base desta página, a ordem a limite traz type: "limit", limitPrice, expiresAt, statusGroup e, depois do disparo, triggerPrice, triggerExchange, triggeredAt e evaluatedTickers. O motivo de uma rejeição vem em errorMessage, nos casos descritos em como o motivo do encerramento aparece. Quando a ordem volta para OPEN depois de uma tentativa que falhou (re-arm), o evento traz o motivo dela em lastRejectionReason, em código (ver motivo de cada tentativa). Campo novo da ordem a limite passa a viajar aqui automaticamente, sem mudança de contrato.

O canal é complemento, não substituto

A entrega ao vivo é de melhor esforço: uma conexão que caiu não recebe o que perdeu sozinha. O que perdeu pode ser recuperado pelo reenvio, enquanto estiver guardado. A fonte do estado continua sendo o REST — para reconciliar, use fetchOrder com orderId + status + updatedAt.

Os eventos também podem chegar fora de ordem: duas mudanças de status próximas — por exemplo TRIGGERED e PROCESSING, com cerca de um segundo de diferença — podem ser entregues trocadas. Não use a ordem de chegada como sequência de status: aplique o evento só se o updatedAt dele for maior que o do último já aplicado àquela ordem. Como o updatedAt tem resolução de segundos, dois eventos podem trazer o mesmo valor; nesse caso, confirme o estado com o fetchOrder.

Exemplo JavaScript​

const token = 'SEU_TOKEN_OPERACIONAL';
const ws = new WebSocket(`wss://websocket-caas-it-sandbox.liqi.app.br/?token=${token}`);

ws.onopen = () => {
ws.send(JSON.stringify({
action: 'subscribe',
channel: 'watchOrders'
}));
};

ws.onmessage = (event) => {
const { channel, message } = JSON.parse(event.data);
if (channel === 'watchorders') {
console.log(`Ordem ${message.id}: ${message.status}`);
console.log(`${message.side} ${message.amount} ${message.symbol} @ ${message.average}`);
}
};