> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voxfi.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Conexão

> Conectando ao WebSocket e gerenciando a conexão

## URL do WebSocket

Todas as conexões WebSocket devem ser feitas para:

```
wss://data-ws-dev.voxfi.com.br
```

## Estabelecendo Conexão

Para conectar ao WebSocket, estabeleça uma conexão WebSocket padrão na URL acima. Não é necessário autenticação na conexão inicial, mas alguns canais requerem autenticação ao se inscrever.

## Ping/Pong

O WebSocket implementa um sistema de heartbeat automático para manter a conexão ativa e detectar desconexões.

### Heartbeat Automático

O servidor envia automaticamente mensagens de ping a cada **10 segundos**. Você deve responder com pong dentro de **20 segundos** para evitar desconexão por timeout.

### Ping Manual

Você também pode enviar manualmente uma mensagem de texto simples para verificar latência:

**Enviar:**

```
ping
```

**Receber:**

```
pong
```

### Timeout

Se você não responder aos pings do servidor dentro de 20 segundos, a conexão será fechada automaticamente. Certifique-se de que sua implementação WebSocket responde automaticamente aos pings do servidor.

## Canais Disponíveis

O WebSocket oferece três tipos de canais para receber diferentes tipos de atualizações:

### Canal User

Receba atualizações sobre suas próprias ordens e transações. Requer autenticação com chave de API.

[Documentação completa do Canal User](/pt/websockets/user-channel)

### Canal Market

Receba atualizações sobre mercados específicos (orderbook e trades). Não requer autenticação.

[Documentação completa do Canal Market](/pt/websockets/market-channel)

### Canal Event

Receba atualizações sobre eventos específicos (inclui todos os mercados do evento). Não requer autenticação.

[Documentação completa do Canal Event](/pt/websockets/event-channel)

## Tipos de Atualizações

Você pode filtrar o tipo de atualização que deseja receber nos canais `market` e `event`:

* **`all`** ou `""` (padrão): Todas as atualizações (orderbook e trades);
* **`orderbook`**: Apenas atualizações de orderbook;
* **`trades`**: Apenas atualizações de trades.

## Exemplo de Conexão

<CodeGroup>
  ```javascript JavaScript theme={null}
  const ws = new WebSocket('wss://data-ws-dev.voxfi.com.br');

  ws.onopen = () => {
    console.log('Conectado ao WebSocket');
    
    // Enviar ping para verificar latência
    ws.send('ping');
  };

  ws.onmessage = (event) => {
    if (event.data === 'pong') {
      console.log('Pong recebido');
    } else {
      const data = JSON.parse(event.data);
      console.log('Mensagem recebida:', data);
    }
  };

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

  ws.onclose = (event) => {
    console.log('Conexão fechada:', event.code, event.reason);
  };
  ```

  ```python Python theme={null}
  import asyncio
  import websockets
  import json

  async def connect_websocket():
      uri = "wss://data-ws-dev.voxfi.com.br"
      
      async with websockets.connect(uri) as websocket:
          # Enviar ping
          await websocket.send('ping')
          
          # Receber mensagens
          async for message in websocket:
              if message == 'pong':
                  print('Pong recebido')
              else:
                  data = json.loads(message)
                  print('Mensagem recebida:', data)

  asyncio.run(connect_websocket())
  ```
</CodeGroup>

## Boas Práticas

* **Reconexão Automática**: Implemente lógica de reconexão automática em caso de desconexão. Use backoff exponencial para evitar reconexões muito frequentes;
* **Heartbeat Automático**: O servidor envia pings automaticamente a cada 10 segundos. Certifique-se de que sua implementação responde aos pings do servidor automaticamente;
* **Ping Manual**: Você pode enviar `ping` manualmente para verificar latência, mas não é necessário devido ao heartbeat automático;
* **Tratamento de Erros**: Sempre trate erros e desconexões adequadamente. Verifique os códigos de erro para entender a causa da desconexão;
* **Filtros Específicos**: Use filtros (`orderbook` ou `trades`) quando precisar apenas de um tipo de atualização para reduzir o tráfego de rede;
* **Múltiplas Inscrições**: Você pode se inscrever em múltiplos mercados e eventos na mesma conexão WebSocket;
* **Gerenciamento de Estado**: Mantenha o estado local do orderbook e atualize conforme as mensagens chegam;
* **Buffer de Mensagens**: Em caso de reconexão, considere fazer uma requisição HTTP para obter o estado atual antes de continuar recebendo atualizações via WebSocket.

## Casos de Uso

* **Monitoramento de Preços em Tempo Real**: Use o canal `market` com filtro `orderbook` para receber atualizações de preço instantâneas e construir uma visualização em tempo real;
* **Tracking de Trades**: Use o canal `market` ou `event` com filtro `trades` para monitorar atividade de negociação e identificar padrões;
* **Gerenciamento de Ordens**: Use o canal `user` para receber atualizações sobre suas próprias ordens e transações, permitindo reação rápida a mudanças;
* **Dashboard de Mercado**: Combine múltiplos canais para criar um dashboard completo de mercado em tempo real com preços, trades e suas próprias posições;
* **Alertas de Preço**: Monitore mudanças de preço e execute ações automaticamente quando certos níveis são atingidos;
* **Análise de Liquidez**: Use atualizações de orderbook para analisar a profundidade do mercado e tomar decisões de negociação informadas;
* **Arbitragem**: Monitore preços em múltiplos mercados simultaneamente para identificar oportunidades de arbitragem.