> ## 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 and Unsubscribe

> Subscribing and unsubscribing from WebSocket channels

## Subscribe

Subscribe to a channel to receive real-time updates.

### Message Structure

```json theme={null}
{
  "type": "subscribe",
  "channel": "user" | "market" | "event",
  "auth": "string", // Required only for "user" channel
  "markets": ["string"], // Required for "market" channel
  "events": ["string"], // Required for "event" channel
  "filter": "all" | "orderbook" | "trades" // Optional for "market" and "event" channels
}
```

### Fields

* **`type`** (required): Must be `"subscribe"`;
* **`channel`** (required): Channel type (`"user"`, `"market"` or `"event"`);
* **`auth`** (required only for `channel: "user"`): User's API key (`X-Api-Key`);
* **`markets`** (required for `channel: "market"`): Array of market IDs;
* **`events`** (required for `channel: "event"`): Array of event IDs;
* **`filter`** (optional for `channel: "market"` and `channel: "event"`): Desired update type
  * `""` or `"all"`: All updates (default)
  * `"orderbook"`: Only orderbook updates
  * `"trades"`: Only trade updates

### Examples

#### Subscribe to User Channel

```json theme={null}
{
  "type": "subscribe",
  "channel": "user",
  "auth": "your-api-key-here"
}
```

#### Subscribe to Market Channel

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

#### Subscribe to Event Channel

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

### Multiple Subscriptions

You can subscribe to multiple channels and multiple resources on the same WebSocket connection:

```javascript theme={null}
// Subscribe to multiple markets
ws.send(JSON.stringify({
  type: 'subscribe',
  channel: 'market',
  markets: ['market-1', 'market-2', 'market-3'],
  filter: 'all'
}));

// Subscribe to multiple events
ws.send(JSON.stringify({
  type: 'subscribe',
  channel: 'event',
  events: ['event-1', 'event-2'],
  filter: 'orderbook'
}));
```

## Unsubscribe

Cancel subscription to a channel to stop receiving updates.

### Message Structure

```json theme={null}
{
  "type": "unsubscribe",
  "channel": "user" | "market" | "event",
  "markets": ["string"], // Required for "market" channel
  "events": ["string"] // Required for "event" channel
}
```

### Fields

* **`type`** (required): Must be `"unsubscribe"`;
* **`channel`** (required): Channel type (`"user"`, `"market"` or `"event"`);
* **`markets`** (required for `channel: "market"`): Array of market IDs to unsubscribe from;
* **`events`** (required for `channel: "event"`): Array of event IDs to unsubscribe from.

### Examples

#### Unsubscribe from User Channel

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

#### Unsubscribe from Specific Markets

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

#### Unsubscribe from Specific Events

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

## Complete Example

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

ws.onopen = () => {
  // Subscribe to a market
  ws.send(JSON.stringify({
    type: 'subscribe',
    channel: 'market',
    markets: ['market-id-1'],
    filter: 'orderbook'
  }));
  
  // After some time, unsubscribe
  setTimeout(() => {
    ws.send(JSON.stringify({
      type: 'unsubscribe',
      channel: 'market',
      markets: ['market-id-1']
    }));
  }, 60000); // Unsubscribe after 60 seconds
};

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

## Important Notes

* **Subscriptions Persist**: Once subscribed, you will continue receiving updates until you unsubscribe or disconnect;
* **Multiple Subscriptions to Same Resource**: You can subscribe to the same market/event multiple times without issues;
* **Partial Cancellation**: For `market` and `event` channels, you can unsubscribe from specific resources without affecting others;
* **Reconnection**: In case of reconnection, you will need to subscribe again to all desired channels.