Skip to main content
This topic will always notify a change at a price level of the order book when an order is opened, canceled or a trade takes place for a given pair (BASE_QUOTE). In other words, it is the variation in the amount of assets available for buy or sell at a given price level. In each topic event the amount is the absolute quantity for a price level, and if the amount is 0, you should remove the price level from the order book. Important! In addition to the delta messages, the first message sent upon connection will be a snapshot of the level 2 order book.

​
Subscription Request

​
method
string
required
Subscribe method. Must be subscribe
​
topics
array
required
Array of topics to subscribe to. Format: orderbook/level_2_delta@BASE_QUOTEExample: ["orderbook/level_2_delta@ETH_BRL"]

​
Stream Response

​
id
integer
Each WebSocket message includes a sequential numeric id. Each topic has its own unique sequence, and for private topics, the sequence is unique to each topic and user. It’s important to note that some topics will send a “welcome message”, which will have an id value of -1. Additionally, this sequence may be reset between connections, so be sure to update this value locally whenever you reconnect.
​
topic
string
Topic name (format: orderbook/level_2_delta@BASE_QUOTE)
​
timestamp
integer
Timestamp in milliseconds
​
body
object
Order book delta details object

​
Subscription Example

{
  "method": "subscribe",
  "topics": [
    "orderbook/level_2_delta@ETH_BRL"
  ]
}

​
Initial Snapshot Response (First Message)

{
  "id": 4,
  "topic": "orderbook/level_2_delta@ETH_BRL",
  "timestamp": 1672856653428,
  "body": {
    "pair": "ETH_BRL",
    "hash": "2254383345",
    "asks": [
      {
        "price": 20,
        "amount": 184.9
      },
      {
        "price": 25,
        "amount": 10
      }
    ],
    "bids": [
      {
        "price": 5,
        "amount": 400
      },
      {
        "price": 4,
        "amount": 20
      }
    ]
  }
}

​
Delta Update Response

{
  "id": 5,
  "topic": "orderbook/level_2_delta@ETH_BRL",
  "timestamp": 1672856653428,
  "body": {
    "pair": "ETH_BRL",
    "hash": "2254383345",
    "asks": [
      {
        "price": 25,
        "amount": 0
      }
    ],
    "bids": [
      {
        "price": 25,
        "amount": 20
      }
    ]
  }
}

​
Key Characteristics

  • Delta Only: Only includes price levels that have changed
  • Snapshot First: First message after subscription is a full snapshot
  • Amount = 0: Indicates the price level should be removed from your local copy
  • Efficient Updates: Reduces bandwidth by only sending changes
  • Buildable: You can build a complete order book from delta messages

​
How to Use Delta Updates

  1. Receive Snapshot: First message after subscribing is a complete order book snapshot
  2. Apply Deltas: For subsequent messages, apply the changes to your local copy:
    • Update amount for each price level in the delta
    • Remove price levels where amount is 0
    • Keep all other price levels unchanged
  3. Maintain State: Your local order book stays in sync with the server

​
Implementation Example

// Start with empty order book
let orderBook = { asks: {}, bids: {} };

// Process incoming messages
function processMessage(message) {
  // First message is snapshot - rebuild order book
  if (isSnapshot) {
    orderBook.asks = {};
    orderBook.bids = {};
    message.body.asks.forEach(ask => {
      orderBook.asks[ask.price] = ask.amount;
    });
    message.body.bids.forEach(bid => {
      orderBook.bids[bid.price] = bid.amount;
    });
  } else {
    // Subsequent messages are deltas - apply changes
    message.body.asks.forEach(ask => {
      if (ask.amount === 0) {
        delete orderBook.asks[ask.price];
      } else {
        orderBook.asks[ask.price] = ask.amount;
      }
    });
    message.body.bids.forEach(bid => {
      if (bid.amount === 0) {
        delete orderBook.bids[bid.price];
      } else {
        orderBook.bids[bid.price] = bid.amount;
      }
    });
  }
}

​
Usage Notes

  • Bandwidth Efficient: Send only changes, not the full book each time
  • State Management: You need to maintain local state of the order book
  • Price Level Removal: Always check for amount = 0 to remove levels
  • Hash Verification: Use the hash to verify your local book matches the server
  • Error Recovery: If hash mismatch, resubscribe to get a new snapshot

​
Use Cases

  • Real-time Order Book: Build and maintain a real-time order book with minimal bandwidth
  • High-Frequency Updates: Efficiently handle rapid order book changes
  • Low-Bandwidth Clients: Ideal for mobile or bandwidth-constrained clients
  • Order Book Reconstruction: Rebuild order book state from delta stream