Skip to main content

API structure

Use our WS Market Data Pro API to connect in real time to the Bitvavo exchange.

Connect to WebSocket​

To establish a connection to the Bitvavo WebSocket API, use the following URL:

wss://ws-mdpro.bitvavo.com/v2/

Message types​

Bitvavo WS Market Data Pro API supports two types of messaging:

  • Actions: send a message to the server to request data and receive a one-time JSON-encoded response.
  • Channels: subscribe to a channels to stream event-based updates in real time.

Actions​

To use actions, you first need to have an established authenticated connection to our WebSocket server. After the connection is established, you send messages with specific actions that return JSON-encoded responses equivalent to the ones over REST API.

Message​

When you establish a connection to the Bitvavo WebSocket server, you send a message as a JSON-encoded object with the following parameters:

  • action (required): the action you want to perform. For example, getMarkets.
  • markets(required): the markets in which to make the request. For example, ["BTC-EUR"].
  • requestId: your identifier for the request.
  • Any additional parameters required for the action. This is specified for every action in the WebSocket API reference.

For example, getMarkets is a WebSocket action that returns market data equivalent to the GET /markets request:

Request to get market data for BTC-EUR
{
  "action":"getMarkets",
  "market":"BTC-EUR"
}

Event​

Every time you send a message with a specific action, the server responds with a JSON-encoded object with the following parameters:

  • action (required): the action you performed.
  • requestId: your identifier for the request.
  • response (required): the JSON object containing the requested data.

In the example of the getMarkets action, the response returns the latest market data for the BTC-EUR pair:

Response with market data for BTC-EUR
{
  "action": "getMarkets",
  "response": {
    "market": "BTC-EUR",
    "status": "trading",
    "base": "BTC",
    "quote": "EUR",
    "pricePrecision": null,
    "minOrderInBaseAsset": "0.000061",
    "minOrderInQuoteAsset": "5",
    "maxOrderInBaseAsset": "1000000000",
    "maxOrderInQuoteAsset": "1000000000",
    "orderTypes": [
      "market",
      "limit",
      "stopLoss",
      "stopLossLimit",
      "takeProfit",
      "takeProfitLimit"
    ]
  }
}

Channels​

After you open an authenticated connection to our server, you send a subscription message to connect to a specific channel. Unlike for actions, the server then continuously streams updates as the events happen on that channel.

Subscribe and unsubscribe​

To start the stream, you send a subscribe action to the server and specify the channel you want to subscribe to. The server streams the data as the specified events happen. To stop the stream, you send an identical message with the unsubscribe action to the server.

The format of the subscribe and unsubscribe messages is a JSON object with:

  • action (required): set this to subscribe or unsubscribe.
  • channels (required): an object with the following parameters:
    • name: the events to which you want to subscribe. For example, ticker.
    • markets: the markets for which you want stream the data. For example, ["BTC-EUR"].
    • interval (only for candles) the time period for which to return the data. For example, ["1h"].

For example:

Subscribe to the ticker channel
{
  "action": "subscribe",
  "channels": [
    {
      "name": "ticker",
      "markets": [
        "BTC-EUR"
      ]
    }
  ]
}
Unubscribe to the ticker channel
{
  "action": "unsubscribe",
  "channels": [
    {
      "name": "ticker",
      "markets": [
        "BTC-EUR"
      ]
    }
  ]
}

Event​

There are two types of events that you receive when you subscribe to a channel:

Subscribe or unsubscribe events​

These are event messages you get after you send a subscribe action messages. The server confirms that you are subscribed or unsubscribed to the channel.

For example:

Subscribed to ticker channel event
{
  "event": "subscribed",
  "subscriptions": {
    "ticker": [
      "BTC-EUR"
    ]
  }
}
Unubscribed event
{
  "event": "unsubscribed",
  "subscriptions": {}
}

Data stream events​

While the WebSocket connection is open, and you are subscribed to a channel, you keep getting event messages.

The server keeps sending JSON-encoded objects with the following parameters:

  • event: the event that you subscribed to. For example, ticker.
  • All the data related to the event. For example, the latest ticker data for the BTC-EUR pair.
Ticker data event
{
    "event": "ticker",
    "market": "BTC-EUR",
    "bestBid": "91294",
    "bestBidSize": "0.00161762"
}

Supported actions and channels​

Below are all available actions and channels for the Bitvavo WebSocket API.

Actions​

  • getBook - get the order book for a specific market.
  • getTickerPrice - obtain the latest price for all markets or a specific market.
  • getTickerBook - get the current best bid and ask for all or a specific market.
  • getTrades - get recent public trades for a specific market.
  • getMarkets - get information about all available trading pairs.
  • getAssets - get details about all supported assets.

Channels​

  • book - real-time order book updates for subscribed markets.
  • ticker - updates to the best bid, best ask, and/or last price.
  • trades - live trade execution notifications.

Track your actions​

To help you track the return parameters back to your initial request, you can use the requestId parameter. Bitvavo adds the integer value of requestId to the return parameters for the action. For example, a message:

Action to get order book
    {
      "action": "getBook",
      "requestId": 1,
      "market": "BTC-EUR",
      "depth": 4
    }

returns:

Response with the mdSeqNo
    {
      "action": "getBook",
      "requestId": 1,
      "response": {
        "market": "BTC-EUR",
        "nonce": 438524,
        "bids": [
          [
            "4999.9",
            "0.015"
          ],
          [
            "4999.8",
            "0.015"
          ],
          [
            "4999.7",
            "0.015"
          ],
          [
            "4999.6",
            "0.015"
          ]
        ],
        "asks": [
          [
            "5001.1",
            "0.015"
          ],
          [
            "5001.2",
            "0.015"
          ],
          [
            "5001.3",
            "0.015"
          ],
          [
            "5001.4",
            "0.015"
          ]
        ],
        "timestamp": 1542967486256,
        "mdSeqNo": 438524
      }
    }

Handle disconnections​

The connection may be closed due to:

  • Network issues
  • Rate limiting
  • Server restarts
  • Authentication failures

To counter this, you can add logic to automatically reconnect. For example:

Reconnect logic in JavaScript
function connect() {
  const ws = new WebSocket('wss://ws.bitvavo.com/v2/');

  ws.onopen = () => console.log("Connected to Bitvavo WebSocket");
  ws.onclose = () => {
    console.log("Disconnected. Reconnecting in 5 seconds...");
    setTimeout(connect, 5000);
  };
}

connect();

Handle errors​

In case of errors, the API responds with an HTTP status code and a JSON object with the error details.

Error response
{
  "event": "error",
  "errorCode": 100,
  "error": "Invalid JSON format"
}

To learn more, see the full list of error codes.

See also​