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
}
| Campo | Tipo | Descrição |
|---|---|---|
messageId | string | Identificador único da mensagem. A mesma mensagem mantém o mesmo messageId mesmo que seja entregue de novo ou reenviada — use-o para ignorar duplicatas |
sequence | number | Nú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 maiorsequenceque 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 usandoupdatedAt, 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
sequenceque 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
}
| Campo | Tipo | Descrição |
|---|---|---|
channel | string | watchOrders. Hoje é o único canal com reenvio |
fromSequence | number | Reenvia as mensagens com sequence maior que este valor. Informe o último que você processou. 0 pede desde a mais antiga guardada |
since | number | Alternativa 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
}
| Campo | Descrição |
|---|---|
count | Quantas mensagens foram reenviadas neste pedido |
lastSequence | O maior sequence reenviado; null se nada foi reenviado |
hasMore | true quando ainda há mensagens a reenviar |
nextSequence | Quando hasMore é true, o valor a usar como fromSequence no próximo pedido |
oldestAvailableSequence | O sequence da mensagem mais antiga ainda guardada; null se não há nenhuma |
Limites e regras
- Cada pedido reenvia até 500 mensagens. Se
hasMoreviertrue, peça de novo comfromSequenceigual aonextSequence, até virfalse. - As mensagens ficam guardadas por pelo menos 7 dias. Se o seu
fromSequencefor menor queoldestAvailableSequence, 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 oresendMessagesResultantes 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
messageIdjá processado. - O reenvio não é automático: ao reconectar, assine o canal e peça o reenvio a partir do último
sequenceque 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" }
error | Causa |
|---|---|
invalid JSON body | o corpo não é um objeto JSON |
channel is required | faltou channel |
channel not supported | o canal não tem reenvio |
permission denied for channel | a sua chave não tem permissão para o canal |
send exactly one of fromSequence or since | veio os dois, ou nenhum |
fromSequence must be a non-negative integer | fromSequence fora do formato |
since must be a unix timestamp in seconds | since fora do formato (milissegundos, ou no futuro) |
resend already in progress | já há um reenvio em andamento nesta conexão |
internal error | falha 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
closedtrazem o bloco base + campos estendidos (account,orderPoolId,filledStatus,cost,price,info,fee,trades,RFQ,settlement). - Ordens
rejectedtrazem o bloco base comerrorMessagepreenchido 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)
| Campo | Tipo | Descrição |
|---|---|---|
id | string | Identificador da ordem |
exchange | string | Exchange utilizada. Em modo liqi-managed retorna "liqi". |
symbol | string | Par de mercado (ex: BTC/BRL) |
side | string | buy ou sell |
type | string | Tipo da ordem (market por padrão) |
status | string | Status atual — ver tabela de status abaixo |
errorMessage | string | Mensagem de erro quando status = "rejected"; vazio nos demais casos |
amount | string | Quantidade de cripto |
quoteAmount | string | Valor em FIAT (R$) |
quoteAmountOriginal | string | Valor em FIAT originalmente solicitado |
remainingQuoteAmount | string | Valor restante em FIAT |
average | string | Preço médio de execução |
createdAt | number | Timestamp Unix de criação |
updatedAt | number | Timestamp Unix da última atualização |
executedAt | number? | Timestamp Unix da execução (quando aplicável) |
channel | string | Canal de origem da ordem |
rule | string | Regra SOR utilizada |
operationalFees | string | Taxas operacionais |
fxComposition | object? | 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 |
executedExchange | string? | Exchange que de fato executou. Presente quando difere do exchange — em modo liqi-managed é aqui que vem o nome real |
evaluatedTickers | array? | 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.
| Campo | Tipo | Descrição |
|---|---|---|
side | string | Lado do dólar usado: ask (compra) ou bid (venda) |
dollarBase | string | Dólar base (USD/BRL) cotado no provedor de câmbio, com 4 casas |
iofPercentage | string | IOF, em percentual com 4 casas ("1.1000" = 1,1%) |
brokerageFeePercentage | string | Corretagem do câmbio, em percentual com 4 casas |
outsideBizHoursSpreadPercentage | string | Spread de fora do horário comercial, em percentual com 4 casas |
dollarWithFxFees | string | Dólar com as taxas de câmbio, truncado em 4 casas. Não é o dólar de liquidação da ordem |
feesIncludedByProvider | boolean | true 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)
| Campo | Tipo | Descrição |
|---|---|---|
account | string | ID da conta do cliente |
orderPoolId | string | ID da ordem no pool |
filledStatus | string | Detalhe do preenchimento (ex.: filled, partiallyFilled) |
amountOriginal | string | Quantidade originalmente solicitada |
remainingAmount | string | Quantidade restante em cripto |
filled | string | Quantidade efetivamente preenchida |
remaining | string | Quantidade restante a preencher |
cost | string | Custo total da ordem |
price | string | Preço médio |
info | string | Informação adicional do provedor |
fee | object | Detalhes das taxas (Liqi + tier) |
trades | array | Lista de trades individuais que compuseram a ordem |
RFQ | object? | 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 |
settlement | object? | 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
| Status | Descrição |
|---|---|
pending | Ordem aberta, em validação ou aguardando execução |
executed | Ordem executada no provedor, aguardando finalização |
closed | Ordem finalizada com sucesso (campos estendidos presentes) |
rejected | Ordem rejeitada (errorMessage preenchido) |
expired | Cotação RFQ que expirou antes de virar ordem |
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ção | Quando chega |
|---|---|
OPEN | a ordem foi validada e passou a ser observada |
TRIGGERED | o preço alcançou o alvo e a execução foi disparada |
PROCESSING / EXECUTED / closed | o 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 |
CANCELLING | cancelamento de uma ordem foi aceito (não ocorre no cancelamento em lote) |
CANCELLED | cancelamento concluído — um evento por ordem, inclusive no lote |
EXPIRED | o prazo terminou sem a ordem atingir o alvo |
REJECTED | recusa 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.
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}`);
}
};