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

> Subscribe to real-time level 2 order book updates including user identifiers

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, and this also includes an array with users ids that have an order at that level. 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_with_users@BASE_QUOTE`

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

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

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

  <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 with user info

      <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
        </ResponseField>

        <ResponseField name="users" type="array">
          Array of user IDs that have orders at this price level
        </ResponseField>
      </Expandable>
    </ResponseField>

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

      <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
        </ResponseField>

        <ResponseField name="users" type="array">
          Array of user IDs that have orders at this price level
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Subscription Example

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

## Stream Response Example

```json theme={null}
{
  "id": 5,
  "topic": "orderbook/level_2_with_users@ETH_BRL",
  "timestamp": 1672856653428,
  "body": {
    "pair": "ETH_BRL",
    "hash": "2254383345",
    "asks": [
      {
        "price": 20,
        "amount": 184.9,
        "users": [
          "5EF6B2C9-28C9-4C50-99EA-7F3A38958F0A"
        ]
      },
      {
        "price": 25,
        "amount": 10,
        "users": [
          "5EF6B2C9-28C9-4C50-99EA-7F3A38958F0A"
        ]
      }
    ],
    "bids": [
      {
        "price": 5,
        "amount": 400,
        "users": [
          "5EF6B2C9-28C9-4C50-99EA-7F3A38958F0A"
        ]
      },
      {
        "price": 4,
        "amount": 20,
        "users": [
          "5EF6B2C9-28C9-4C50-99EA-7F3A38958F0A"
        ]
      }
    ]
  }
}
```

## Update Frequency

* **Default**: Every 30 seconds
* **On Change**: Immediately when an order is opened, canceled, or a trade happens
* **Updates Include**: Both sides with user information

## Key Characteristics

* **Level 2 with Users**: Aggregated by price but includes user IDs
* **Up to 100 Levels**: Each side contains maximum 100 price levels
* **User Tracking**: See which users have orders at each price level
* **Hash Value**: Used to verify order book integrity
* **Multiple Users**: Multiple users can have orders at the same price level

## Differences from Standard Level 2

| Aspect      | Level 2        | Level 2 with Users |
| ----------- | -------------- | ------------------ |
| User Info   | Not included   | Includes user IDs  |
| Data Size   | Smaller        | Slightly larger    |
| Use Case    | General charts | User analysis      |
| Performance | Better         | Slightly lower     |

## Usage Notes

* **User IDs**: Array of user identifiers at each price level
* **Multiple Users**: Price level may contain orders from multiple users
* **User Count**: You can infer order concentration by user count
* **Market Structure**: Understand who is providing liquidity at each level
* **Concentration Risk**: Identify if liquidity is concentrated in few users

## Use Cases

* **User-based Analysis**: Analyze which users are providing liquidity
* **Large Order Detection**: Identify large orders from specific users
* **Market Participant Tracking**: Track participation of key market makers
* **Concentration Analysis**: Monitor liquidity concentration
* **Relationship Mapping**: Understand market structure and relationships

## Privacy Considerations

* **User IDs**: Only shows UUID, not personal information
* **Order Privacy**: Individual order sizes at the price level are aggregated
* **Market Data**: This is public market data
* **No Personal Info**: User identifiers are anonymized UUIDs