WebSockets

A API Liqi CaaS oferece conexões WebSocket para acompanhamento em tempo real de preços, ordens e saldos.

URLs de Conexão

Ambiente	URL base
Sandbox	wss://websocket-caas-it-sandbox.liqi.app.br/
Production	wss://ws.liqi-caas.com.br/

Autenticação

A conexão WebSocket é autenticada no $connect via token operacional passado em query string. O token é o mesmo obtido em POST /auth/signin (ver Autenticação).

wss://<host>/?token=<TOKEN_OPERACIONAL>

Conexões sem token ou com token inválido são recusadas pelo API Gateway antes de qualquer handler ser executado. Não é possível se conectar primeiro e autenticar depois.

Como Conectar

JavaScript

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

ws.onopen = () => {
  console.log('Conectado ao WebSocket');

  // Subscrever a um canal
  ws.send(JSON.stringify({
    action: 'subscribe',
    channel: 'watchTicker',
    data: {
      symbol: 'BTC/BRL'
    }
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Dados recebidos:', data);
};

ws.onerror = (error) => {
  console.error('Erro no WebSocket:', error);
};

ws.onclose = () => {
  console.log('Conexão fechada');
};

Python

import asyncio
import websockets
import json

async def connect():
    token = "SEU_TOKEN_OPERACIONAL"  # obtido em POST /auth/signin
    uri = f"wss://websocket-caas-it-sandbox.liqi.app.br/?token={token}"
    async with websockets.connect(uri) as ws:
        # Subscrever
        await ws.send(json.dumps({
            "action": "subscribe",
            "channel": "watchTicker",
            "data": {"symbol": "BTC/BRL"}
        }))

        # Receber mensagens
        async for message in ws:
            data = json.loads(message)
            print("Recebido:", data)

asyncio.run(connect())

Canais Disponíveis

Canal	Descrição	Dados Necessários
watchOrders	Acompanha status de ordens em tempo real	-
watchTicker	Preço de um par específico	symbol
watchTickers	Preços de todos os pares	onlyPriority (opcional)
watchBalance	Saldos em tempo real	-

Formato das Mensagens

Subscrição

{
  "action": "subscribe",
  "channel": "<nome-do-canal>",
  "data": { ... }
}

O campo action aceita "subscribe" ou "unsubscribe". O nome do canal é case-insensitive no envio — watchOrders, watchorders e WATCHORDERS são tratados da mesma forma. Por padronização, os payloads recebidos sempre vêm com o canal em minúsculas (watchorders, watchbalance, watchticker, watchtickers).

Confirmação da Subscrição

Após cada subscribe ou unsubscribe, o servidor responde na mesma conexão:

Sucesso:

{ "success": true, "message": "Successfully subscribed to channel: watchticker#btcbrl" }

Erro (canal inexistente, sem permissão, payload inválido, etc.):

{ "success": false, "message": "Permission denied for this channel" }

Dados Recebidos

{
  "channel": "<nome-do-canal-em-minusculas>",
  "message": { ... }
}

Permissões por Canal

Cada canal requer uma permissão específica na chave API utilizada para gerar o token operacional. Se a chave não tiver a permissão necessária, o subscribe é recusado com "Permission denied for this channel".

Canal	Permissão necessária
watchOrders	orders:*
watchBalance	wallet:*
watchTicker	market:*
watchTickers	market:*
(qualquer)	* (wildcard)