You access Bitvavo SDK using REST or WebSocket. The Base URLs are:

• REST: https://api.bitvavo.com/v2/
• WebSocket: wss://ws.bitvavo.com/v2/

Both protocols return JSON encoded responses, and use standard HTTP status codes. All calls to Bitvavo related to trading, transfer or your account must be authenticated. Bitvavo Rate limits ensure the best performance and stability.

To make your first calls to Bitvavo:

1. Setup your development environment

   To access Bitvavo API, either:

   • Use your existing framework to make REST calls or connect to WebSocket
   • Integrate Bitvavo SDK for Python, Node.js, Java, or Go into your app

2. Copy your Bitvavo authentication information locally

   Download your API key and secret from Bitvavo Dashboard to a secure location.

   You download the API secret when you create the API key and secret pair.

3. Retrieve Market data or Synchronize with Bitvavo

   Use these unauthenticated endpoints to retrieve the information you need to trade. For example, to retrieve the open, high, low, close, volume and volumeQuote for each market for the last 24 hours, call:

   curl --location 'https://api.bitvavo.com/v2/ticker/24h'
   

   The returned JSON object looks like:

   [
     {
       "market": "1INCH-EUR",
       "startTimestamp": 1704276900209,
       "timestamp": 1704363300209,
       "open": "0.44323",
       "openTimestamp": 1704277090309,
       "high": "0.44454",
       "low": "0.33101",
       "last": "0.43167",
       "closeTimestamp": 1704363292923,
       "bid": "0.42915",
       "bidSize": "1161.3",
       "ask": "0.43215",
       "askSize": "1152.4",
       "volume": "717262.96917523",
       "volumeQuote": "290421.5350422048742"
     },
     {
       "market": "AAVE-EUR",
       // ...
     },
     // ...
   ]
   

4. Trade on Bitvavo, transfer funds or update your account

   Use these highly secure endpoints to handle all aspects of your financial interactions with Bitvavo. For example, to place an order, sign the following REST request and run:

   curl --location 'https://api.bitvavo.com/v2/order' \
     --header 'Bitvavo-Access-Key: <replace with your access key>' \
     --header 'Bitvavo-Access-Signature: <A SHA256 HMAC hex digest of timestamp + method + url + body>' \
     --header 'Bitvavo-Access-Timestamp: <Current timestamp in milliseconds>' \
     --header 'Bitvavo-Access-Window: 10000' \
     --header 'Content-Type: application/json' \
     --data '{
       "market": "BTC-EUR",
       "side": "buy",
       "orderType": "market",
       "amount": "10",
       "responseRequired": true
     }'
   

   The returned JSON object looks like:

   {
       "orderId": "1be6d0df-d5dc-4b53-a250-jamesbondis007",
       "market": "BTC-EUR",
       "created": 1542621155181,
       "updated": 1542621155181,
       "status": "new",
       "side": "buy",
       "orderType": "limit",
       "amount": "10",
       "amountRemaining": "9.995",
       "price": "7000",
       "amountQuote": "5000",
       "amountQuoteRemaining": "5000",
       "onHold": "9109.61",
       "onHoldCurrency": "BTC",
       "filledAmount": "0",
       "filledAmountQuote": "0",
       "feePaid": "0",
       "feeCurrency": "EUR",
       "fills": [
           {
               "id": "371c6bd3-d06d-4573-9f15-spectre",
               "timestamp": 1542967486256,
               "amount": "0.005",
               "price": "5000.1",
               "taker": true,
               "fee": "0.03",
               "feeCurrency": "EUR",
               "settled": true
           }
       ],
       "selfTradePrevention": "decrementAndCancel",
       "visible": true,
       "timeInForce": "GTC",
       "postOnly": true,
       "disableMarketProtection": true
   }
   

And that is all, you are ready to trade on Bitvavo using the API.

The structure of Bitvavo API is:

• Unauthenticated endpoints: return public information about markets and trades on Bitvavo.

  You can make calls to these endpoints without your API key and secret. However, unauthenticated calls have lower rate limits based on your IP address, and your account is blocked for longer if you exceed your limit.

  • Market data endpoints: information about the state of the market on Bitvavo.
  • Synchronization endpoints: align the system clock on your trading platform with Bitvavo.

• Authenticated endpoints: these private endpoints enable account-specific interactions, such as placing and managing orders, viewing your account history, or withdrawing assets.

  For these calls to succeed you must create your API key and secret and make Authenticated calls.

  • Trading endpoints: manage your orders and trades on Bitvavo.
  • Transfer endpoints: deposit and withdraw funds in Bitvavo.
  • Account endpoints: information about your Bitvavo account.

• Subscription WebSocket: securely subscribe to these channels and retrieve the latest information about markets, your trades and your account in your WebSocket callback.

  • WebSocket: implement low-latency, high-frequency trading.
  • Market data subscription WebSocket: retrieve the latest information about markets, your trades and your account in your WebSocket callback.
  • Trading subscription WebSocket: the latest information about your trades and your account in your WebSocket callback.

  Bitvavo is hosted in the Amazon Frankfurt region.

You control the actions your app can execute using the permissions you assign to an
API key. Each key consists of an API key name and a corresponding API secret.

Possible permissions are:

• Read-only: retrieve information from Transfer endpoints and
  Account endpoints. GET your account balance and the trading fees you have incurred. Also the history of deposits to and withdrawals from your account.

• Trade digital assets: place, update, view and cancel orders using the Trading endpoints. Check your open orders, view your order and trade history. To obtain 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 verified bank account.

Best practice is to NOT grant this privilege. Withdrawals made using Bitvavo API do not require 2FA and e-mail confirmation.

You create API keys in Bitvavo Dashboard. When you create an API key, you must download the API secret to a secure location immediately, you cannot retrieve it later. Best practice is to limit access each API key to a few whitelisted IP addresses.

To make an authenticated connection with Bitvavo, you send the following HTTP headers in every call to Bitvavo API:

For Bitvavo-Access-Signature, the SHA256 HMAC hex digest of the following values:

• secret: bitvavo
• timestamp: 1548172481125
• method: POST
• url: /v2/order
• body: {"market":"BTC-EUR","side":"buy","price":"5000","amount":"1.23","orderType":"limit"}

is 44d022723a20973a18f7ee97398b9fdd405d2d019c8d39e24b8cc0dcb39ca016.

WebSocket example

The following Python code sample shows how to sign a request for a call to the authenticate action:

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))

REST example

The following Python code sample shows how to sign a request for a call to the POST /order endpoint:

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

You use Bitvavo SDKs to easily execute your advanced trading strategies from your app. These wrapper SDKS do all the hard work for you, enabling you to rapidly integrate Bitvavo functionality and start trading. Bitvavo SDKs enable you to call every REST endpoint in Bitvavo API, or use WebSocket to subscribe to the latest data and rapidly trade.

To easily integrate Bitvavo into your app, use the following SDKs:

• Bitvavo SDK for Python
• Bitvavo SDK for Node.js
• Bitvavo SDK for Java
• Bitvavo SDK for Go

Retrieve the market data that is used by your algorithms for trading.

An order is an instruction made by a Bitvavo user to buy or sell a quantity of digital assets at a specific price. The order price is given as a specific amount in base currency or quote currency, or a specific price-per-unit in quote currency.

When a sell order made by one user matches a buy order by another user, Bitvavo fills the buy order and sell order in a trade. Each order may be filled by executing one or multiple trades. When the complete quantity in one order cannot be filled exactly with the other order, Bitvavo progressively completes the larger order with multiple trades. An order is partially filled when there is still an open quantity left on the order book. For example, multiple buy fills for one sell fill. An order is filled when the full quantity in the buy or sell order is matched by fills.

The market name is the combination of the:

• Base currency: the first currency in a market. For example, in the BTC-EUR market the base currency is Bitcoin.
• Quote currency: the second currency in a market. You use the quote currency to
  determine the value of the base currency. For example, in the BTC-EUR market the value of 1 Bitcoin is 34,243 Euro.

A taker is a Bitvavo user who fills a buy or sell order made by a maker. A maker is the Bitvavo user who made the initial order.

Manage your orders and trades on Bitvavo.

Deposit and withdraw funds in Bitvavo.

Information about your Bitvavo account