Manage subscriptions

The CVEX API provides a WebSocket interface for real-time market and portfolio updates, offering a more efficient and cost-effective solution for serious API usage compared to traditional polling methods. Once subscribed, the WebSocket API delivers updates as they occur without additional API credit deductions, ensuring that clients can receive continuous data streams as long as the connection remains open.

To begin using the CVEX WebSocket API, establish a connection using your API Key:

const socket = new WebSocket('wss://ws.cvex.trade/ws/v1?api_key=YOUR_API_KEY');

After establishing the connection, subscribe to the desired topics to receive notifications. Here's an example for index price updates:

socket.send(
  JSON.stringify({
    id: 123,
    jsonrpc: '2.0',
    method: 'market.index_price.subscribe',
    params: {
      index: 'BTC',
      with_snapshot: true
    }
  })
);

If the subscription was successful, you receive an immediate response with the same ID as in the request:

{
    "jsonrpc": "2.0",
    "id": 123,
    "result": {
        "success": true
    }
}

To unsubscribe from the particular topic, you can use the unsubscribe method with the same parameters that were used for the subscription:

socket.send(
  JSON.stringify({
    id: 123,
    jsonrpc: '2.0',
    method: 'market.index_price.unsubscribe',
    params: {
      index: 'BTC'
    }
  })
);

Types of subscriptions:

• Market Data:
  • Index price updates: Notifications about changes in index prices.
  • Contract price updates: Alerts on price changes for specific contracts.
  • Mark price updates: Updates about the mark price for contracts.
  • Contract updates: Notifications on contract status changes (settling, etc).
  • Order book updates: Real-time changes in the order book.
  • Latest trades: Information on the most recent trades executed.
• Portfolio Data:
  • Portfolio updates: Alerts whenever significant portfolio parameters such as equity or margin requirements change.
  • Order updates: Notifications about order status changes.
  • Position updates: Updates on adjustments to open positions.
  • Transaction updates: Information regarding financial transactions like deposits and withdrawals.

Managing Data Integrity

The from_block_id parameter enables subscribers to define a starting point for receiving event data upon subscribing to a WebSocket feed. This is limited to the last 100 blocks. This parameter is particularly valuable for ensuring data continuity, especially in scenarios involving re-connections. By setting from_block_id, users can resume receiving events from a specific blockchain number, thus ensuring that no events are missed during any interruptions.

For instance, if a WebSocket connection is lost and the last event received was associated with block 1050, configuring from_block_id=1051 upon re-connection guarantees that the subscriber immediately continues receiving updates from where they left off, thereby maintaining both data integrity and continuity.

Most subscription topics deliver an initial snapshot of data when a subscription is initiated, providing immediate context before regular updates commence. For event-based topics, this snapshot includes the 50 most recent events, offering a detailed view of recent activities such as orders, positions, and transactions. For portfolio-related topics, the snapshot presents current metrics like equity and margin utilization, ensuring subscribers are immediately up-to-date with the latest account status. Meanwhile, the order book topic provides the most recent status of the order book as a snapshot.

If from_block_id parameter is specified, with_snapshot value will be ignored.