> ## 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.

# Subscribe e Unsubscribe

> Inscrevendo-se e cancelando inscrições em canais WebSocket

## Subscribe

Inscreve-se em um canal para receber atualizações em tempo real.

### Estrutura da Mensagem

```json theme={null}
{
  "type": "subscribe",
  "channel": "user" | "market" | "event",
  "auth": "string", // Obrigatório apenas para canal "user"
  "markets": ["string"], // Obrigatório para canal "market"
  "events": ["string"], // Obrigatório para canal "event"
  "filter": "all" | "orderbook" | "trades" // Opcional para canais "market" e "event"
}
```

### Campos

* **`type`** (obrigatório): Deve ser `"subscribe"`;
* **`channel`** (obrigatório): Tipo de canal (`"user"`, `"market"` ou `"event"`);
* **`auth`** (obrigatório apenas para `channel: "user"`): Chave de API (`X-Api-Key`) do usuário;
* **`markets`** (obrigatório para `channel: "market"`): Array de IDs de mercado;
* **`events`** (obrigatório para `channel: "event"`): Array de IDs de evento;
* **`filter`** (opcional para `channel: "market"` e `channel: "event"`): Tipo de atualização desejada
  * `""` ou `"all"`: Todas as atualizações (padrão)
  * `"orderbook"`: Apenas atualizações de orderbook
  * `"trades"`: Apenas atualizações de trades

### Exemplos

#### Subscribe no Canal User

```json theme={null}
{
  "type": "subscribe",
  "channel": "user",
  "auth": "sua-chave-api-aqui"
}
```

#### Subscribe no Canal Market

```json theme={null}
{
  "type": "subscribe",
  "channel": "market",
  "markets": ["market-id-1", "market-id-2"],
  "filter": "orderbook"
}
```

#### Subscribe no Canal Event

```json theme={null}
{
  "type": "subscribe",
  "channel": "event",
  "events": ["event-id-1", "event-id-2"],
  "filter": "trades"
}
```

### Múltiplas Inscrições

Você pode se inscrever em múltiplos canais e múltiplos recursos na mesma conexão WebSocket:

```javascript theme={null}
// Inscrever-se em múltiplos mercados
ws.send(JSON.stringify({
  type: 'subscribe',
  channel: 'market',
  markets: ['market-1', 'market-2', 'market-3'],
  filter: 'all'
}));

// Inscrever-se em múltiplos eventos
ws.send(JSON.stringify({
  type: 'subscribe',
  channel: 'event',
  events: ['event-1', 'event-2'],
  filter: 'orderbook'
}));
```

## Unsubscribe

Cancela a inscrição de um canal para parar de receber atualizações.

### Estrutura da Mensagem

```json theme={null}
{
  "type": "unsubscribe",
  "channel": "user" | "market" | "event",
  "markets": ["string"], // Obrigatório para canal "market"
  "events": ["string"] // Obrigatório para canal "event"
}
```

### Campos

* **`type`** (obrigatório): Deve ser `"unsubscribe"`;
* **`channel`** (obrigatório): Tipo de canal (`"user"`, `"market"` ou `"event"`);
* **`markets`** (obrigatório para `channel: "market"`): Array de IDs de mercado para cancelar inscrição;
* **`events`** (obrigatório para `channel: "event"`): Array de IDs de evento para cancelar inscrição.

### Exemplos

#### Unsubscribe do Canal User

```json theme={null}
{
  "type": "unsubscribe",
  "channel": "user"
}
```

#### Unsubscribe de Mercados Específicos

```json theme={null}
{
  "type": "unsubscribe",
  "channel": "market",
  "markets": ["market-id-1", "market-id-2"]
}
```

#### Unsubscribe de Eventos Específicos

```json theme={null}
{
  "type": "unsubscribe",
  "channel": "event",
  "events": ["event-id-1"]
}
```

## Exemplo Completo

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

ws.onopen = () => {
  // Inscrever-se em um mercado
  ws.send(JSON.stringify({
    type: 'subscribe',
    channel: 'market',
    markets: ['market-id-1'],
    filter: 'orderbook'
  }));
  
  // Após algum tempo, cancelar inscrição
  setTimeout(() => {
    ws.send(JSON.stringify({
      type: 'unsubscribe',
      channel: 'market',
      markets: ['market-id-1']
    }));
  }, 60000); // Cancelar após 60 segundos
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Atualização recebida:', data);
};
```

## Notas Importantes

* **Inscrições Persistem**: Uma vez inscrito, você continuará recebendo atualizações até cancelar a inscrição ou desconectar;
* **Múltiplas Inscrições no Mesmo Recurso**: Você pode se inscrever no mesmo mercado/evento múltiplas vezes sem problemas;
* **Cancelamento Parcial**: Para canais `market` e `event`, você pode cancelar a inscrição de recursos específicos sem afetar outros;
* **Reconexão**: Em caso de reconexão, você precisará se inscrever novamente em todos os canais desejados.