Skip to main content

Stream data with WS Market Data Pro

The WebSocket Market Data Pro API provides non-conflated Level 2 (L2) market data with sequence numbering that allows you to track every change in the order book exactly as it happens.

You can then use this data to process live updates and handle potential data gaps to ensure your local book is always in sync with Bitvavo’s state.

Why use WS Market Data Pro​

You should stream data using WS Market Data Pro if you:

If you only need conflated updates or a simpler feed, you can continue using the standard WebSocket and REST APIs. To learn how to use them, see Manage local order book.

Improved latency​

The WS Market Data Pro streams events about 47.5 milliseconds faster than the standard WebSocket API. This provides almost 9 times more messages to ensure a smoother, more accurate view of the market.

Latency ComparisonStandard WebSocketMarket Data Pro
Average delay~100 ms (batched updates)~52.5 ms faster (non-batched)
Update frequency1 message / 100 ms~9.1 messages / 100 ms
Price reactivitySingle delayed updateInstant, multi-point updates
Feed behaviorBufferedReal-time

To compare the streams of book events between the two WebSocket APIs, we simulated activity near the top of the order books. We then measured how long it took for the changes to appear in the book subscriptions.

You can see the comparison in the graph below. The orange line (WS Market Data Pro) reacts instantly to market movements, while the blue line (standard WebSocket) shows a delay caused by batching.

latency

Advanced sequence tracking​

The standard WebSocket API uses a single nonce field to help you detect missed updates. While this works for basic use cases, it can be challenging to identify exactly which events are missing when gaps occur.

The Market Data Pro API introduces a start–end sequence range model that provides more robust event tracking:

  • mdSeqNo: The sequence number of the last event applied to that snapshot
  • startMdSeqNo and endMdSeqNo: The range of events covered by that update message
  • type: All events now include a type: "update" field for forward compatibility

This range-based model gives you explicit verification of the complete sequence. While startMdSeqNo and endMdSeqNo are typically equal (representing a single event), they can differ when the system groups multiple events into one message under high load. For example:

  • Update with startMdSeqNo: 101 and endMdSeqNo: 102 confirms that events 101 and 102 are both included
  • The next message begins with startMdSeqNo: 103

This makes it easier to detect gaps and recover from missed updates, ensuring your local order book stays in sync with Bitvavo.

caution

WS Market Data Pro nonce values are not shared with REST or standard WebSocket APIs.

Sync your local order book​

Prerequisites​

Before you start, make sure you’ve done the following:

Step 1: Subscribe to order book updates​

  1. Connect to the WS Market Data Pro API using the wss://ws-mdpro.bitvavo.com/v2/ endpoint.

  2. Subscribe to the Book subscription channel for a market, for example BTC-EUR.

    Book subscription message
    {
      "action": "subscribe",
      "channels": [
        {
          "name": "book",
          "markets": [
            "BTC-EUR"
          ]
        }
      ]
    }

  3. You start receiving book events with the market data. Every event includes a range of update identified by the sequence numbers:

    • startMdSeqNo: Sequence number identifying the start of the range of events that the order book update includes.
    • endMdSeqNo: Sequence number identifying the end of the range of events that the order book update includes.
    Book update event
    {
      "event": "book",
      "market": "BTC-EUR",
      "nonce": 438524,
      "bids": [
        [
          "9209.3",
          "0.015"
        ]
      ],
      "asks": [
      ],
      "timestamp": 1542967486256,
      "startMdSeqNo": 438524,
      "endMdSeqNo": 438524,
      "type": "update"
    }

  4. Go to step 2 to get a snapshot of the order book and establish the initial state of your local order book.

    caution

    Do not apply any updates until you’ve confirmed the correct ordering of events.

Step 2: Get a snapshot of the order book​

  1. Make a Get order book request for that market, in this example BTC-EUR.

    WS Market Data Pro getBook action
    {
      "action": "getBook",
      "requestId": 1,
      "market": "BTC-EUR",
      "depth": 1000
    }

    The response returns:

    Snapshot
    {
      "action": "getBook",
      "requestId": 1,
      "response": {
        "market": "BTC-EUR",
        "nonce": 438525,
        "bids": [
          [
            "4999.9",
            "0.015"
          ],
          ...
        ],
        "asks": [
          [
            "5001.1",
            "0.015"
          ],
          ...
        ],
        "timestamp": 1542967486256,
        "mdSeqNo": 438525
      }
    }

  2. Save the returned mdSeqNo from the snapshot.

    Matching engine sequence number
    {
      "mdSeqNo": 438525
    }

    You will use the mdSeqNo sequence number of this snapshot for the initial state of your local order book.

Step 3: Compare the sequence numbers​

  1. After you get the snapshot, compare its mdSeqNo,for example 438525, with the startMdSeqNo of the next incoming book event from your active subscription.
  2. If the startMdSeqNo is lower than or equal to the mdSeqNo of the snapshot, skip the event (it’s already included).
  3. If the startMdSeqNo is exactly one higher than the snapshot mdSeqNo, for example 438526, start applying the updates in order.

Step 4: Apply the update and advance​

After you've confirmed the correct ordering:

  1. Update the bids and asks in your local order book to the state from each event.
  2. After each update, set your local mdSeqNo to the endMdSeqNo of the last event.
  3. Continue applying new event updates in sequential order.

Troubleshoot and recover​

If you detect a gap in the sequence numbers, for example, if the startMdSeqNo of an event is not exactly one higher than your local mdSeqNo:

  1. Discard your local order book.
  2. Re-subscribe to the Book subscription channel.
  3. Get a new snapshot by making a Get order book request and repeat the process.

See also​