Authentication

Learn how to authenticate your requests to Bitvavo WebSocket API. For the API reference, see WebSocket API. Similar to the REST API, the WebSocket API requires authentication for operations related to trading, transfers, or account management.

Authentication

For messages that require authentication, you must first send a message to authenticate your WebSocket connection. After the connection is authenticated, you can start sending messages to the WebSocket API.

To do this, you need to:

1. Create a signature.
2. Send an action to authenticate your connection.

STEP 1: Create a signature

You first need to create an HMAC-SHA256 hex-encoded signature:

1. Prepare the parameter values:

• timestamp: 1548175200641
• method: GET
• path: /v2/websocket
• body: do not include a body.

2. Concatenate the values without a delimiter:
   Concatenated string

   1548175200641GET/v2/websocket
3. Prepare the API secret for your Bitvavo-Access-Key. For example:
   API secret

   bitvavo
4. Encode the concatenated string to HMAC-SHA256 using the API secret for your API key. You get:
   Signature

   0F3ZsjokueFAcg8S04+yX35z6Rm9Xg1IkqdHYKhswP4=

STEP 2: Send an action to authenticate

Now that you have created a signature, to authenticate your connection to the WebSocket API:

1. Connect to wss://ws.bitvavo.com/v2/
2. Create a JSON object with:
   • action: authenticate
   • key: YOUR_API_KEY
   • signature: the signature you created.
   • timestamp: the Unix timestamp in milliseconds of the time you make the request.
   • window (optional): the time in milliseconds in which your request is allowed to execute. The default value is 10000, and the maximum value is 60000.
3. Send the message to the WebSocket API:

Authenticate message

{
  "action": "authenticate",
  "key": "YOUR_API_KEY",
  "signature": "0F3ZsjokueFAcg8S04+yX35z6Rm9Xg1IkqdHYKhswP4=",
  "timestamp": 1548175200641
}

4. Your connection is now authenticated, and you can start sending messages to the WebSocket API.

Python example

The following Python code sample shows how to sign authenticate message. To learn more, see our Python SDK.

Authenticate message

import hashlib
import hmac
import json
import websocket
import time

class BitvavoWebSocketClient:
    """
    A class to interact with the Bitvavo WebSocket API.
    """

    def __init__(self, api_key: str, api_secret: str, access_window: int = 10000):
        self.api_key = api_key
        self.api_secret = api_secret
        self.access_window = access_window
        self.endpoint = 'wss://ws.bitvavo.com/v2/'
        self.request_id = 0
        self.ws = None
    
    def authenticate(self):
        """
        Send an instruction to Bitvavo to authenticate your connection.
        """
        timestamp = int(time.time() * 1000)
        body = {
          'key': self.api_key,
          'signature': self.create_signature(timestamp),
          'timestamp': timestamp,
          'window': self.access_window,
        }
        self.call_action(action='authenticate', body=body)
    
    def create_signature(self, timestamp: int):
        """
        Create a hashed code to authenticate your connection to Bitvavo API.
        """
        string = str(timestamp) + 'GET' + '/v2/websocket'
        signature = hmac.new(self.api_secret.encode('utf-8'), string.encode('utf-8'), hashlib.sha256).hexdigest()
        return signature
    
    def call_action(self, action: str, body: dict):
        """
        Send an instruction to Bitvavo to perform an action.
        :param action: the action to perform. For example, `authenticate`.
        :param body: the parameters for the call. For example, {'key': 'your_api_key', 'signature': 'your_signature'}.
        """
        request_id = self.request_id
        self.request_id += 1
        
        body['action'] = action
        body['requestId'] = request_id
        
        self.send_message(body)
    
    def send_message(self, message: dict):
        """
        Send a message to Bitvavo API.
        """
        if self.ws is None:
            self.ws = websocket.create_connection(self.endpoint)
        self.ws.send(json.dumps(message))

Permissions

To control the actions your app can execute, you add permissions to your API key in your Bitvavo dashboard.

You can enable:

• Read-only: retrieve information about your account and transfers. To retrieve order and trade information, your API key must also have the Trade digital currencies permission.
• Trade digital assets: place, update, view, and cancel orders. To retrieve order and trade information, your API key must also have the Read-only permission.
• Withdraw digital assets: withdraw your assets to an external cryptocurrency address or a verified bank account.
  warning

  Withdrawals made using Bitvavo API do not require 2FA and e-mail confirmation.