> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.ripio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# orderbook/level_2_delta@BASE_QUOTE

> Subscribe to real-time delta (changes) to level 2 order book

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

<ParamField body="method" type="string" required>
  Subscribe method. Must be `subscribe`
</ParamField>

<ParamField body="topics" type="array" required>
  Array of topics to subscribe to. Format: `orderbook/level_2_delta@BASE_QUOTE`

  Example: `["orderbook/level_2_delta@ETH_BRL"]`
</ParamField>

## Stream Response

<ResponseField name="id" type="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.
</ResponseField>

<ResponseField name="topic" type="string">
  Topic name (format: `orderbook/level_2_delta@BASE_QUOTE`)
</ResponseField>

<ResponseField name="timestamp" type="integer">
  Timestamp in milliseconds
</ResponseField>

<ResponseField name="body" type="object">
  Order book delta details object

  <Expandable title="Delta Details">
    <ResponseField name="pair" type="string">
      Trading pair code (e.g., ETH\_BRL)
    </ResponseField>

    <ResponseField name="hash" type="string">
      Hash representing the current order book state. For examples of how the order book checksum hash is computed, see: [https://github.com/ripio/api/tree/main/websocket-checksum-hash](https://github.com/ripio/api/tree/main/websocket-checksum-hash)
    </ResponseField>

    <ResponseField name="asks" type="array">
      Array of changed sell orders (ask side)

      <Expandable title="Changed Ask Price Level">
        <ResponseField name="price" type="number">
          Ask price level that changed
        </ResponseField>

        <ResponseField name="amount" type="number">
          New total amount at this price level. If 0, remove this price level from the book.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="bids" type="array">
      Array of changed buy orders (bid side)

      <Expandable title="Changed Bid Price Level">
        <ResponseField name="price" type="number">
          Bid price level that changed
        </ResponseField>

        <ResponseField name="amount" type="number">
          New total amount at this price level. If 0, remove this price level from the book.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Subscription Example

```json theme={null}
{
  "method": "subscribe",
  "topics": [
    "orderbook/level_2_delta@ETH_BRL"
  ]
}
```

## Initial Snapshot Response (First Message)

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```javascript theme={null}
// 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