Orderbook

Topic Format

symbol@deep

• symbol: The trading pair symbol (e.g., ETH_USDT).

Example Topic: ETH_USDT@deep

---

Message Structure

Fields

Field	Type	Description
et	int32	Event type (1 for orderbook updates).
f	string	The starting version of the orderbook.
t	string	The final version of the orderbook.
s	string	Symbol name (e.g., ETH_USDT).
b	string[]	List of bid prices.
d	string[]	List of bid sizes corresponding to each bid price in b.
a	string[]	List of ask prices.
c	string[]	List of ask sizes corresponding to each ask price in a.

Note:

• Each index in b corresponds to the same index in d for the bid side of the orderbook. For example, b[0] = 100, d[0] = 12 means at bid price 100, the volume is 12.
• Similarly, each index in a corresponds to the same index in c for the ask side of the orderbook.

---

Example Message

{
    "et": 1,
    "f": "7",
    "t": "9",
    "s": "ETH_USDT",
    "b": [
        "1.0000000"
    ],
    "d": [
        "0.170"
    ],
    "a": [
        "4.0000000",
        "5.0000000"
    ],
    "c": [
        "0.010",
        "0.130"
    ]
}

---

Managing Orderbook on Client

Understanding Versioning

To manage the orderbook effectively, it's essential to understand how versioning works:

• Each time an order is created or canceled, the orderbook changes, and the version increments by 1.
• To optimize data transfer from server to clients, multiple versions of the orderbook are combined into a single event and sent to all listening clients.

---

Steps to Manage Orderbook Locally

1. Connect and Subscribe

   • Connect to the Socket.IO server and subscribe to the topic for the orderbook (e.g., ETH_USDT@deep).

2. Buffer Incoming Messages

   • Place received messages into a buffer.
   • Sort the buffer in ascending order by the f field.

3. Wait for Completion

   • Wait for the "connect" event to be triggered in the Socket.IO client to ensure the connection is successfully established.

4. Fetch Snapshot

   • Fetch the orderbook snapshot using the /orderbook API.
   • Define the current version of your local orderbook as current_version = i from the snapshot.

5. Filter Buffer

   • Discard events in the buffer where t <= current_version as these updates are already applied in the snapshot.

6. Apply Events

   • For events satisfying f <= current_version + 1 <= t:
     • Update the local orderbook.
     • Remove the event from the buffer.
     • Update current_version = t.

7. Repeat

   • Repeat step 6 until no events in the buffer satisfy the condition or the buffer is empty.

---

Updating Local Orderbook

• Discard Old Events

  • If t <= current_version, ignore the event.

• Buffer Out-of-Order Events

  • If f > current_version, add the event to the buffer and sort it by f.

• Apply Events in Order

  • For events where f <= current_version + 1 <= t:
    • Update the local orderbook.
    • Update current_version = t.
    • Check and apply other events in the buffer that satisfy this condition.

• Handling Prices and Volumes

  • For each price level in bids and asks:
    • Volume > 0:
      • Update the price level in the local orderbook if it exists.
      • Insert the price level into the local orderbook if it does not exist.
      • Example: If the event contains a bid at price 12 with volume 100 and the local orderbook has no entry at price 12, insert it. If it exists with volume 36, update it to 100.
    • Volume = 0:
      • Remove the price level from the local orderbook.

---

Handling Missing Data

If an event remains in the buffer for too long without being processed (e.g., current_version = 12, and the first event in the buffer has f = 15 and t = 17) and stays there for 60 seconds without being processed, it indicates missing data for versions 13 and 14. In this case:

• Fetch a new snapshot of the orderbook from the /orderbook API.