Skip to main content

Manage local order book

If you are keeping track of the order book locally, it is important to keep it in sync with Bitvavo. This prevents inaccurate trading caused by stale or out-of-sequence data and ensures your orders reflect the latest market conditions.

This is especially important for high-frequency trading strategies that rely on real-time data and trade on multiple exchanges.

Step 1: Subscribe to order book updates​

  1. Connect to the WebSocket API using the wss://api.bitvavo.com/v2/ endpoint.

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

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

  3. Store (buffer) the incoming events ordered by the value of the nonce parameter. This is a sequential identifier of the order book version.

    Book subscription event
    {
      "event": "book",
      "market": "BTC-EUR",
      "nonce": 123456789,
      "bids": [
        [ "30000.50", "0.1" ],
        [ "30000.00", "0.5" ]
      ],
      "asks": [
        [ "30001.00", "0.2" ],
        [ "30001.50", "0.3" ]
      ]
    }

Step 2: Get a snapshot of the order book​

  1. To get a snapshot of the order book, make a Get order book REST API or WebSocket request for a market.

    cURL request
    curl -L -g 'https://api.bitvavo.com/v2/{market}/book' \
       -H 'Accept: application/json' \
       -H 'Bitvavo-Access-Key: YOUR_API_KEY' \
       -H 'Bitvavo-Access-Timestamp: YOUR_GENERATED_SIGNATURE' \
       -H 'Bitvavo-Access-Signature: CURRENT_TIMESTAMP' \
       -H 'Bitvavo-Access-Window: 10000' \

    The response for REST and WebSocket is the same:

    Snapshot
    {   
      "market": "BTC-EUR",   
      "nonce": 123456788,
      "bids": [
        [ "30000.50", "0.1" ],
        [ "30000.00", "0.6" ],
        [ "29999.50", "0.2" ]
       ],
       "asks": [
        [ "30001.00", "0.2" ],
        [ "30001.50", "0.3" ],
        [ "30002.00", "0.1" ]
      ]
    }

  2. Compare the nonce of the snapshot with the nonce of the initial WebSocket update:

    • If the value nonce of the snapshot is greater than the nonce from the first update, go to Step 3.
    • If the nonce of the snapshot is smaller than or equal to the nonce from the first update, get a new snapshot and try again.

  3. Discard all stored updates where the nonce of the event is smaller than or equal to the nonce from the snapshot.

Step 3: Update your local order book​

  1. Update the bids and asks in your order book to the state from the snapshot.
  2. Set the update ID of your order book to the nonce of the snapshot.
  3. Apply the remaining stored updates with a nonce greater than the nonce of the snapshot.
  4. Continue to apply new WebSocket updates, using the update procedure below.

Step 4: Discard outdated data​

  1. If the nonce of the event is not greater exactly by 1 than the nonce of your local order book, your local book is out of sync. Discard it and restart the process from Step 1 (re-subscribe and get a new snapshot).
  2. For every price in bids and asks:
    • If the price is not in your local book, add it with the provided size (for example, price level "30000.50" and size "0.1").
    • If the size is 0, remove the price from your local book.
    • If the price already exists, update its size to the new value.
  3. After applying all updates from the event, set the nonce of your local book to match the nonce of the event.