Skip to main content
This means that they will receive JSON-RPC notification-messages from the server when certain events occur, such as changes to the index price, changes to the order book for a certain instrument, or updates to user account information.

​
Notification Format

In accordance with the JSON-RPC specification, the format of a notification is that of a request message without an id field. The value of the method field will always be "subscription". The params field will always be an object with 2 members: channel and data.

​
Basic Structure

{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "channel": "channel_name",
        "data": {
            // Channel-specific data
        }
    }
}

​
Example Notification

{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "channel": "deribit_price_index.btc_usd",
        "data": {
            "timestamp": 1535098298227,
            "price": 6521.17,
            "index_name": "btc_usd"
        }
    }
}

​
Setting Up Subscriptions

The API methods public/subscribe and private/subscribe are used to set up a subscription. Since HTTP does not support the sending of messages from server to client, these methods are only available when using the WebSocket transport mechanism. At the moment of subscription, a “channel” must be specified. The channel determines the type of events that will be received.

Subscription Channels

Complete reference of all available subscription channels

Connection Management

Best practices for managing WebSocket connections and subscriptions

​
Subscription Example

{
    "jsonrpc": "2.0",
    "method": "public/subscribe",
    "params": {
        "channels": [
            "book.BTC-PERPETUAL.100ms",
            "ticker.BTC-PERPETUAL.100ms",
            "deribit_price_index.btc_usd"
        ]
    },
    "id": 1
}

​
Channel Types

Deribit provides two main categories of channels:
Public channels provide market data and platform information that does not require authentication:
  • Order Book (book.{instrument_name}.{interval}) - Real-time order book updates
  • Order Book (Grouped) (book.{instrument_name}.{group}.{depth}.{interval}) - Grouped order book updates with specified depth
  • Ticker (ticker.{instrument_name}.{interval}) - Instrument price and volume information
  • Incremental Ticker (incremental_ticker.{instrument_name}) - Incremental ticker updates
  • Trades (trades.{instrument_name}.{interval}) - Public trade information
  • Trades by Kind (trades.{kind}.{currency}.{interval}) - Public trades filtered by instrument kind and currency
  • Index Prices (deribit_price_index.{index_name}) - Index price updates
  • Price Ranking (deribit_price_ranking.{index_name}) - Price ranking information
  • Price Statistics (deribit_price_statistics.{index_name}) - Price statistics
  • Volatility Index (deribit_volatility_index.{index_name}) - Volatility index updates
  • Estimated Expiration Price (estimated_expiration_price.{index_name}) - Estimated expiration price
  • Platform State (platform_state) - Platform status and announcements
  • Platform State (Public Methods) (platform_state.public_methods_state) - Public methods state
  • Perpetual Funding (perpetual.{instrument_name}.{interval}) - Funding rate information
  • Chart Data (chart.trades.{instrument_name}.{resolution}) - TradingView-compatible chart data
  • Chart Data (Simple) (chart.trades.{instrument_name}) - Chart data without resolution specification
  • Quote (quote.{instrument_name}) - Quote information
  • Instrument State (instrument.state.{kind}.{currency}) - Instrument state updates by kind and currency
  • Mark Price (Options) (markprice.options.{index_name}) - Options mark price updates
  • Block RFQ Trades (block_rfq.trades.{currency}) - Block RFQ trade information
  • Block Trade Confirmations (block_trade_confirmations) - Block trade confirmation updates
  • Block Trade Confirmations (Currency) (block_trade_confirmations.{currency}) - Block trade confirmations filtered by currency

​
Notification Intervals

Many channels support different notification intervals to control the frequency of updates:
  • raw - Immediate notifications for every change (order book only)
  • 100ms - Notifications aggregated over 100 milliseconds
  • agg2 - Notifications aggregated over 2 seconds
Using aggregated intervals (like 100ms or agg2) can reduce the number of messages you receive and help manage bandwidth and processing load.

​
Order Book Notifications

Order book notifications have special characteristics:

​
First Notification (Full Book)

The first notification after subscribing contains the complete order book (bid and ask amounts for all price levels): 
{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "channel": "book.BTC-PERPETUAL.100ms",
        "data": {
            "timestamp": 1535098298227,
            "instrument_name": "BTC-PERPETUAL",
            "change_id": 123456,
            "bids": [
                ["new", 50000.0, 10.5],
                ["new", 49999.5, 5.2],
                // ... more price levels
            ],
            "asks": [
                ["new", 50001.0, 8.3],
                ["new", 50001.5, 12.1],
                // ... more price levels
            ]
        }
    }
}

​
Subsequent Notifications (Incremental Updates)

After the first notification, you will only receive incremental updates for changed price levels: 
{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "channel": "book.BTC-PERPETUAL.100ms",
        "data": {
            "timestamp": 1535098298327,
            "instrument_name": "BTC-PERPETUAL",
            "prev_change_id": 123456,
            "change_id": 123457,
            "bids": [
                ["change", 50000.0, 9.8],
                ["delete", 49999.5, 0]
            ],
            "asks": [
                ["new", 50002.0, 3.5]
            ]
        }
    }
}

​
Change ID Tracking

Each order book notification contains a change_id field, and each message (except the first) contains a prev_change_id field. This allows you to detect if any messages have been missed:
  • If prev_change_id matches the change_id of the previous message, no messages were missed
  • If prev_change_id does not match, you may have missed some updates and should consider re-subscribing

​
Action Types

Order book updates use three action types:
  • new - A new price level has been added
  • change - An existing price level has been updated
  • delete - A price level has been removed (amount is typically 0)

​
User-Specific Notifications

​
Order Updates

Subscribe to receive real-time updates about your orders: 
{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "channel": "user.orders.BTC-PERPETUAL.100ms",
        "data": {
            "order": {
                "order_id": "12345678",
                "instrument_name": "BTC-PERPETUAL",
                "direction": "buy",
                "amount": 10.0,
                "price": 50000.0,
                "order_state": "open",
                // ... more order fields
            }
        }
    }
}

​
Trade Executions

Receive notifications when your orders are filled: 
{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "channel": "user.trades.BTC-PERPETUAL.100ms",
        "data": [
            {
                "trade_id": "87654321",
                "order_id": "12345678",
                "instrument_name": "BTC-PERPETUAL",
                "direction": "buy",
                "amount": 5.0,
                "price": 50000.0,
                "timestamp": 1535098298227,
                // ... more trade fields
            }
        ]
    }
}

​
Portfolio Updates

Monitor your account balance and positions: 
{
    "jsonrpc": "2.0",
    "method": "subscription",
    "params": {
        "channel": "user.portfolio.BTC",
        "data": {
            "currency": "BTC",
            "equity": 100.5,
            "available_funds": 95.2,
            "maintenance_margin": 3.1,
            "initial_margin": 5.3,
            // ... more portfolio fields
        }
    }
}

​
Notification Ordering and Reliability

​
Message Ordering

  • Notifications are sent in the order they occur on the server
  • Different channels may send notifications at different rates
  • Notifications from different channels may arrive out of order relative to each other

​
Handling Missed Messages

For order book subscriptions, use change_id and prev_change_id to detect gaps: 
let lastChangeId = null;

ws.on('message', function incoming(data) {
    const message = JSON.parse(data);
    if (message.method === 'subscription' && message.params.channel.startsWith('book.')) {
        const changeId = message.params.data.change_id;
        const prevChangeId = message.params.data.prev_change_id;
        
        if (lastChangeId !== null && prevChangeId !== lastChangeId) {
            console.warn('Missed order book updates! Re-subscribing...');
            // Re-subscribe to get full book snapshot
            resubscribe();
        }
        
        lastChangeId = changeId;
    }
});

​
Reconnection Handling

When a WebSocket connection is lost and re-established:
  1. Re-authenticate if using private channels
  2. Re-subscribe to all channels you were previously subscribed to
  3. For order book channels, the first notification will be a full snapshot
  4. For other channels, you may miss updates during the disconnection period
Consider implementing a subscription manager that tracks your active subscriptions and automatically re-subscribes after reconnection. See Connection Management Best Practices for more details.

​
Best Practices

​
Subscription Management

  • Limit the number of subscriptions - Each subscription consumes resources. Only subscribe to channels you actually need.
  • Use appropriate intervals - Use aggregated intervals (100ms, agg2) when real-time updates aren’t critical to reduce message volume.
  • Unsubscribe when done - Use public/unsubscribe or private/unsubscribe to clean up subscriptions you no longer need.

​
Processing Notifications

  • Handle notifications asynchronously - Don’t block your message handler with slow processing
  • Validate notification structure - Always check that the expected fields are present
  • Track change IDs - For order book subscriptions, monitor change_id to detect missed messages
  • Separate concerns - Use different WebSocket connections for heavy market data subscriptions vs. order management to avoid blocking order execution

​
Performance Considerations

  • Separate connections - Consider using separate WebSocket connections for:
    • Heavy market data subscriptions (many instruments, high frequency)
    • Order management and user-specific notifications
    • This prevents market data floods from delaying order execution
  • Filter subscriptions - Subscribe only to instruments you’re actively trading or monitoring
  • Use aggregated intervals - For non-critical data, use agg2 interval instead of 100ms or raw
Subscribing to too many channels or using raw intervals for many instruments can overwhelm your connection and cause delays in processing other messages, including order execution confirmations.