> ## 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@BASE_QUOTE

> Subscribe to real-time level 2 order book updates with aggregated orders by price

This topic will notify whenever an order is opened, canceled or a trade happens for the given pair (BASE\_QUOTE). Since it is a level 2 orderbook, the orders are going to be grouped by price. By default, the system notifies the topic every 30 seconds, even if a transaction has not taken place. Each side will contain up to 100 price levels.

## 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@BASE_QUOTE`

  Example: `["orderbook/level_2@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@BASE_QUOTE`)
</ResponseField>

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

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

  <Expandable title="Order Book 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 aggregated sell orders (ask side), grouped by price

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

        <ResponseField name="amount" type="number">
          Total amount available at this price level (sum of all orders)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="bids" type="array">
      Array of aggregated buy orders (bid side), grouped by price

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

        <ResponseField name="amount" type="number">
          Total amount available at this price level (sum of all orders)
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Subscription Example

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

## Stream Response Example

```json theme={null}
{
  "id": 3,
  "topic": "orderbook/level_2@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
      }
    ]
  }
}
```

## Multiple Pairs Example

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

## Update Frequency

* **Default**: Every 30 seconds
* **On Change**: Immediately when an order is opened, canceled, or a trade happens
* **Updates Include**: Both sides of the order book (asks and bids)

## Key Characteristics

* **Level 2**: Orders aggregated by price level
* **Up to 100 Levels**: Each side contains maximum 100 price levels
* **Hash Value**: Used to verify order book integrity
* **Aggregated Volume**: Total volume at each price level
* **Simplified View**: Easier to work with than Level 3

## Differences from Level 3

| Aspect       | Level 2                  | Level 3           |
| ------------ | ------------------------ | ----------------- |
| Granularity  | Aggregated by price      | Individual orders |
| Data Size    | Smaller                  | Larger            |
| Price Levels | Up to 100                | Up to 100 orders  |
| Use Case     | Charts, general analysis | Detailed analysis |
| Performance  | Better                   | More detailed     |

## Usage Notes

* **Price Levels**: Orders at the same price are aggregated
* **Total Volume**: The `amount` represents the total volume at that price level
* **Spread**: The difference between lowest ask and highest bid is the bid-ask spread
* **Hash Verification**: Use the hash to verify the order book hasn't been corrupted
* **Real-time Updates**: Receive immediate updates when orders change

## Use Cases

* **Price Charts**: Display real-time candlestick or depth charts
* **Spread Analysis**: Monitor bid-ask spread for trading decisions
* **Market Overview**: Get a clear view of market depth and liquidity
* **Trading Alerts**: Set alerts based on price level volumes
* **Market Snapshots**: Take periodic snapshots for analysis