Authentication

Learn how to authenticate your requests to Bitvavo REST API. For the API reference, see REST API.

Headers

To authenticate requests, you need to add a signature with the following HTTP headers in every request to Bitvavo REST API:

• Bitvavo-Access-Key (required): an API Key with the required permissions.
• Bitvavo-Access-Timestamp (required): a Unix timestamp in milliseconds of the time you make the request.
• Bitvavo-Access-Signature (required): a HMAC-SHA256 hex-encoded string of the following values:
  • secret: the API secret for your Bitvavo-Access-Key.
  • timestamp: the same Unix timestamp as for Bitvavo-Access-Timestamp.
  • method: the HTTP method of the request. For example, GET or POST.
  • path: the API endpoint to which you make the request. For example, /order.
  • body: for the GET method, an empty string. For every other method, a request body as a string.
• Bitvavo-Access-Window (optional): the execution timeout in milliseconds after Bitvavo-Access-Timestamp. The default value is 10000, and the maximum value is 60000.

Create a signature

To create the HMAC-SHA256 hex-encoded Bitvavo-Access-Signature:

1. Prepare the header values. For example:
   • timestamp: 1548172481125
   • method: POST
   • path: /v2/order
   • body (optional): {"market":"BTC-EUR","side":"buy","price":"5000","amount":"1.23","orderType":"limit"}
2. Concatenate the values without a delimiter:
   Concatenated string

   1548172481125POST/v2/order{"market":"BTC-EUR","side":"buy","price":"5000","amount":"1.23","orderType":"limit"}
3. Prepare the API secret for your Bitvavo-Access-Key. For example:
   Example API secret

   bitvavo
4. Using your API secret, encode the concatenated string to HMAC-SHA256:
   Signature encoded with the Example API secret

   HQBEGVb0mXdRE4gWbmrP09DnYrO03Ca457gxn0OBZ6hMCFgnRJQoJNtsjPvlACPz7FpG51m2tRTQooKi/h2RNdGJuL18EFA3mMgXiG2FT10XoXd8iUxflXJlZ9EUf9OJkyZGM07Q4L7DlOBUZ131GA==

Python example

Below is a Python code sample on how to sign a Create order request:

Sign a create order request

import hashlib
import hmac
import json
import requests
import time

class BitvavoRestClient:
    """
    A class to interact with the Bitvavo REST 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.base = 'https://api.bitvavo.com/v2'

    def place_order(self, market: str, side: str, order_type: str, body: dict):
        """
        Send an instruction to Bitvavo to buy or sell a quantity of digital assets at a specific price.
        :param market: the market to place the order for. For example, `BTC-EUR`.
        :param side: either 'buy' or 'sell' in `market`.
        :param order_type: the character of the order. For example, a `stopLoss` order type is an instruction to
                           buy or sell a digital asset in `market` when it reaches the price set in `body`.
        :param body: the parameters for the call. For example, {'amount': '0.1', 'price': '2000'}.
        """
        body['market'] = market
        body['side'] = side
        body['orderType'] = order_type
        return self.private_request(method='POST', endpoint='/order', body=body)

    def private_request(self, endpoint: str, body: dict | None = None, method: str = 'GET'):
        """
        Create the headers to authenticate your request, then make the call to Bitvavo API.
        :param endpoint: the endpoint you are calling. For example, `/order`.
        :param body: for GET requests, this can be an empty string. For all other methods, a string
                     representation of the call body.
        :param method: the HTTP method of the request.
        """
        now = int(time.time() * 1000)
        sig = self.create_signature(now, method, endpoint, body)
        url = self.base + endpoint
        headers = {
            'bitvavo-access-key': self.api_key,
            'bitvavo-access-signature': sig,
            'bitvavo-access-timestamp': str(now),
            'bitvavo-access-window': str(self.access_window),
        }

        r = requests.request(method=method, url=url, headers=headers, json=body)
        return r.json()

    def create_signature(self, timestamp: int, method: str, url: str, body: dict | None):
        """
        Create a hashed code to authenticate requests to Bitvavo API.
        :param timestamp: a unix timestamp showing the current time.
        :param method: the HTTP method of the request.
        :param url: the endpoint you are calling. For example, `/order`.
        :param body: for GET requests, this can be an empty string. For all other methods, a string
                     representation of the call body. For example, for a call to `/order`:
                     `{"market":"BTC-EUR","side":"buy","price":"5000","amount":"1.23", "orderType":"limit"}`.
        """
        string = str(timestamp) + method + '/v2' + url
        if (body is not None) and (len(body.keys()) != 0):
            string += json.dumps(body, separators=(',', ':'))
        signature = hmac.new(self.api_secret.encode('utf-8'), string.encode('utf-8'), hashlib.sha256).hexdigest()
        return signature

TypeScript example

Below is a pre-script in TypeScript you can use to authenticate a request:

Sign a create order request

const crypto = require('crypto-js');

const secret = "YOUR_API_SECRET"; // Replace with your actual secret key
const timestamp = Date.now(); // Generate the current timestamp in milliseconds
const method = pm.request.method; // GET, POST, etc.
const path = pm.request.url.getPathWithQuery(); // Path and query string of the URL
const body = pm.request.body ? pm.request.body.raw || "" : ""; // Raw body content or empty if none

// Generate the token: timestamp + method + path + body
const token = `${timestamp}${method}${path}${body}`;

// Generate the HMAC-SHA256 signature as a hex-encoded string
const hmacSignature = crypto.HmacSHA256(token, crypto.enc.Utf8.parse(secret)).toString(crypto.enc.Hex);

// Add headers
pm.request.headers.add({ key: "Bitvavo-Access-Timestamp", value: timestamp.toString() });
pm.request.headers.add({ key: "Bitvavo-Access-Signature", value: hmacSignature });
pm.request.headers.add({ key: "Bitvavo-Access-Key", value: "28e64869f8e827344e7a33a6726d956c1049416250e47d8f8dfa52fe351b8311" });

// Debugging logs
console.log("Timestamp:", timestamp);
console.log("Path:", path);
console.log("Body:", body);
console.log("Token:", token);
console.log("Signature:", hmacSignature);

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.