Skip to main content

​
Subscribe

Subscribe to a channel to receive real-time updates.

​
Message Structure

{
  "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

{
  "type": "subscribe",
  "channel": "user",
  "auth": "your-api-key-here"
}

​
Subscribe to Market Channel

{
  "type": "subscribe",
  "channel": "market",
  "markets": ["market-id-1", "market-id-2"],
  "filter": "orderbook"
}

​
Subscribe to Event Channel

{
  "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: 
// 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

{
  "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

{
  "type": "unsubscribe",
  "channel": "user"
}

​
Unsubscribe from Specific Markets

{
  "type": "unsubscribe",
  "channel": "market",
  "markets": ["market-id-1", "market-id-2"]
}

​
Unsubscribe from Specific Events

{
  "type": "unsubscribe",
  "channel": "event",
  "events": ["event-id-1"]
}

​
Complete Example

const ws = new WebSocket('wss://data-ws.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.