Bitvavo API for REST and WebSocket (2.2.4)

Crypto starts with Bitvavo. You use Bitvavo API to buy, sell and store over 200 digital assets on Bitvavo from inside your app. Want to try out the APIs before you start developing your app?

Run in Postman

By accessing or making use of the Bitvavo API or other Bitvavo developer documentation, you agree to be bound by the Bitvavo Developer Agreement. All trades on Bitvavo are handled according to the Trading rules.

Getting started

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.

API structure

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.

  • 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.

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

    Bitvavo is hosted in the Amazon Frankfurt region.

Authentication

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.

Authentication headers

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

HTTP Header Description Required
Bitvavo-Access-Key An API Key with the authentication permissions required for the trading workflow you are implementing.
Bitvavo-Access-Timestamp A unix-timestamp in milliseconds showing the time you make this call to Bitvavo.
Bitvavo-Access-Signature A SHA256 HMAC hex digest of:
  • secret: the API secret that corresponds to Bitvavo-Access-Key.
  • timestamp: the same value as Bitvavo-Access-Timestamp.
  • method: the HTTP method of the request. For example, GET or POST.
  • url: the endpoint you are calling. For example, /order.
  • body: for GET requests, this can be an empty string. For all other methods, a string representation of the call body. For example, the parameters for a call to /order looks like:

    { "market":"BTC-EUR", "side":"buy", "price":"5000", "amount":"1.23", "orderType":"limit" }.

Bitvavo-Access-Window The execution timeout in milliseconds after Bitvavo-Access-Timestamp. The default value is 10000, the maximum value is 60000. That is, 10 seconds and 60 seconds respectively.

Signature example

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.

Python examples

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

SDKs

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:

Market data endpoints

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.

Order book

Retrieve the list of bids and asks for market. That is, the buy and sell orders made by all Bitvavo users in a specific market. The orders in the return parameters are sorted by price.

Rate limit weight points: 1

Websocket action: getBook

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
path Parameters
market
required
string
Example: BTC-EUR

The market you want the order book for.

Call GET /markets to retrieve the list of markets available on Bitvavo.

query Parameters
depth
integer

Return the top depth orders only.

Responses

Request samples

// The Javascript SDK works with callbacks and with promises. For info, check our GitHub.
const bitvavo = require('bitvavo')()
bitvavo.book('BTC-EUR', {}, (error, response) => {
  if (error === null) {
    for (let entry of response.bids) {
      console.log('Bids: ', entry)
    }
    for (let entry of response.asks) {
      console.log('Asks: ', entry)
    }
  } else {
    console.log(error)
  }
})

Response samples

Content type
application/json
{
  • "market": "BTC-EUR",
  • "nonce": 438524,
  • "bids": [
    ],
  • "asks": [
    ]
}

Trades

Retrieve the list of all trades made by all Bitvavo users for market. That is, the trades that have been executed in the past.

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 have multiple trades.

To retrieve the list of your trades, call GET /trades. To retrieve the IDs of the trades associated with an order, see the fills field in the response parameters for GET /orders.

Rate limit weight points: 5

Websocket action: getTrades

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
path Parameters
market
required
string
Example: BTC-EUR

The market you want the trades for.

Call GET /markets to retrieve the list of markets available on Bitvavo.

query Parameters
limit
integer [ 1 .. 1000 ]
Default: 500

Return the limit most recent trades only.

You use limit in conjunction with the other parameters to manage result filtering.

start
integer <unix-timestamp in milliseconds> >= 0

Return limit trades executed after start.

end
integer <unix-timestamp in milliseconds> <= 8640000000000000

Return limit trades executed before end.

tradeIdFrom
string

Return limit trades executed after tradeIdFrom was made.

tradeIdTo
string

Return limit trades executed before tradeIdTo was made.

tradeId
string
Deprecated

Deprecated: use tradeIdFrom and tradeIdTo.

Responses

Request samples

// The Javascript SDK works with callbacks and with promises. For info, check our GitHub.
const bitvavo = require('bitvavo')()
// All optional parameters are used to limit the results.
bitvavo.publicTrades('BTC-EUR', {}, (error, response) => {
  if (error === null) {
    console.log('Trade: ', response)
  } else {
    console.log(error)
  }
})

Response samples

Content type
application/json
[
  • {
    }
]

Candles

Retrieve the Open, High, Low, Close, Volume (OHLCV) data you use to create candlestick charts for market with interval time between each candlestick.

Candlestick data is always returned in chronological data from newest to oldest. Data is returned when trades are made in the interval represented by that candlestick. When no trades occur you see a gap in data flow, zero trades are represented by zero candlesticks.

Rate limit weight points: 1

Websocket action: getCandles

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
path Parameters
market
required
string
Example: BTC-EUR

The market you want candlestick data for.

Call GET /markets to retrieve the list of markets available on Bitvavo.

query Parameters
interval
required
string
Enum: "1m" "5m" "15m" "30m" "1h" "2h" "4h" "6h" "8h" "12h" "1d"

Define the time interval between each candlestick.

limit
integer [ 1 .. 1440 ]
Default: 1440

Return a maximum of the limit most recent candlesticks only.

start
integer <unix-timestamp in milliseconds> >= 0

Return a maximum of limit candlesticks for trades made from start.

Candlestick data is always returned in chronological data from newest to oldest. For example, a call to https://api.bitvavo.com/v2/INJ-EUR/candles?interval=1h&limit=4&start=1710489600000 returns:

[
  [1710500400000,"39.249","39.493","38.782","38.973","1380.03770802"],
  [1710496800000,"39.41","39.856","39.052","39.297","4128.54897663"],
  [1710493200000,"38.678","39.57","36.763","39.388","17871.84796621"],
  [1710489600000,"40.798","40.798","38.519","38.523","7397.32403022"]
]

That is, the candlestick at start is the last one returned. Best practice is to use the end parameter.

end
integer <unix-timestamp in milliseconds> <= 8640000000000000

Return a maximum of limit candlesticks for trades made before end.

Candlestick data is always returned in chronological data from newest to oldest. For example, a call to https://api.bitvavo.com/v2/INJ-EUR/candles?interval=1h&limit=4&end=1710500400000 returns:

  [
    [1710496800000,"39.41","39.856","39.052","39.297","4128.54897663"],
    [1710493200000,"38.678","39.57","36.763","39.388","17871.84796621"],
    [1710489600000,"40.798","40.798","38.519","38.523","7397.32403022"],
    [1710486000000,"41.111","41.153","40.272","40.777","3445.23876149"]
  ]

That is, the last candlestick returned is the one generated prior to end.

Responses

Request samples

// The Javascript SDK works with callbacks and with promises. For info, check our GitHub.
const bitvavo = require('bitvavo')()
bitvavo.candles('BTC-EUR', '1h', {}, (error, response) => {
  if (error === null) {
    for (let entry of response.candles) {
      console.log('Timestamp: ', entry[0], ' Open: ', entry[1], ' High: ', entry[2], ' Low: ', entry[3], ' Close: ', entry[4], ' Volume: ', entry[5])
    }
  } else {
    console.log(error)
  }
})

Response samples

Content type
application/json
[
  • "1538784000000",
  • "4999",
  • "5012",
  • "4999",
  • "5012",
  • "0.45"
]

Ticker price

Retrieve the price of the latest trades on Bitvavo for all markets or a single market.

A tick in a market is any change in the price of a digital asset.

Rate limit weight points: 1

Websocket action: getTickerPrice

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
query Parameters
market
string
Example: market=BTC-EUR

The market you want the latest trade price for.

Call GET /markets to retrieve the list of markets available on Bitvavo.

Responses

Request samples

// The Javascript SDK works with callbacks and with promises. For info, check our GitHub.
const bitvavo = require('bitvavo')()
bitvavo.tickerPrice({}, (error, response) => {
  if (error === null) {
    console.log('Current price for', response.market, ':', response.price)
  } else {
    console.log(error)
  }
})

Response samples

Content type
application/json
[
  • {
    }
]

Ticker book

Retrieve the highest buy and the lowest sell prices currently available for all markets, or a single market in the Bitvavo order book.

Rate limit weight points: 1

Websocket action: getTickerBook

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
query Parameters
market
string
Example: market=BTC-EUR

The market you want the best bid and ask information for.

Responses

Request samples

// The Javascript SDK works with callbacks and with promises. For info, check our GitHub.
const bitvavo = require('bitvavo')()
bitvavo.tickerBook({}, (error, response) => {
  if (error === null) {
    console.log(response.market, 'book, bid:', response.bid, ' ask:', response.ask)
  } else {
    console.log(error)
  }
})

Response samples

Content type
application/json
[
  • {
    }
]

Ticker 24h

Retrieve high, low, open, last, and volume information for trades and orders for a single market, or all markets on Bitvavo over the previous 24 hours.

Rate limit weight points:

  • All markets: 25
  • One market: 1

Websocket action: getTicker24h

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
query Parameters
market
string
Example: market=BTC-EUR

The market you want the ticker information for.

Responses

Request samples

// The Javascript SDK works with callbacks and with promises. For info, check our GitHub.
const bitvavo = require('bitvavo')()
bitvavo.ticker24h({}, (error, response) => {
  if (error === null) {
    for (let object of response) {
      console.log(object)
    }
  } else {
    console.log(error)
  }
})

Response samples

Content type
application/json
[
  • {
    }
]

Trading endpoints

Manage your orders and trades on Bitvavo.

New order

Place an order to buy or sell digital assets on Bitvavo.

All orders are added to the Bitvavo order book immediately. You use the orderType parameter to control the conditions under which your order is filled. While market and limit ordersTypes are filled immediately, stop* and take* orders are filled when trigger conditions are met.

You can have a maximum of 100 open orders at any one time in each market.

See the Payload Request samples for examples of the parameters you need to set for each orderType.

Rate limit weight points: 1

Websocket action: privateCreateOrder

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
Request Body schema: application/json

The desired order to create

market
required
string

Set the market you want to place the order in.

Call GET /markets to retrieve the list of markets available on Bitvavo. Call GET /{market}/book to retrieve the list of bids and asks for market on Bitvavo.

side
required
string
Enum: "buy" "sell"

In market, either:

orderType
required
string
Enum: "market" "limit" "stopLoss" "stopLossLimit" "takeProfit" "takeProfitLimit"

Set the type of order you want to place. Possible values are:

For limit orders, set amount and price. For market orders, set either amount or amountQuote.

clientOrderId
string <UUID>

Set a personalized UUID for any orderType. For example 2be7d0df-d8dc-7b93-a550-8876f3b393e9.

This value is unique for market, you use it to more easily track the order status and align with your internal systems. If you do not set clientOrderId, Bitvavo omits this field from all responses and WebSocket subscriptions.

amount
string

Set the quantity of base currency to buy or sell for any orderType.

Use the GET /assets endpoint to check the decimal precision available for the quantity of base currency you wish to buy or sell. For example, the decimals return parameter for https://api.bitvavo.com/v2/assets?symbol=BTC indicates that you can set up to 8 digits for the value of amount.

Use the GET /markets endpoint to check the minimum and maximum amounts you can create a new order for on Bitvavo.

Do not set amountQuote when you set amount.

amountQuote
string

Set the quantity of quote currency to buy or sell for market, stopLoss, or takeProfit orderTypes. For example, 5000 Euros in the BTC-EUR market.

Use the GET /markets endpoint to check the minimum and maximum amounts you can create a new order for on Bitvavo. Do not set amount when you set amountQuote.

price
string

Set the price you are offering to buy or sell 1 base currency at in quote currency for limit, stopLossLimit, or takeProfitLimit orderTypes.

You can use a maximum of five digits for price. For example: 10001, 1.0001, 10.001, 0.010001 or 38,469 Euros for 1 Bitcoin in the BTC-EUR market

When you set price, you must also set amount to show the quantity of base currency to buy or sell at price. Use the GET /markets endpoint to check the minimum and maximum amounts you can create a new order for on Bitvavo.

triggerAmount
string

Set the price to buy or sell 1 base currency in quote currency for a stopLoss, stopLossLimit, takeProfit, or takeProfitLimit orderType.

For example, when you set triggerAmount to 4000 and triggerType to price, your order is placed in market when the triggerReference price in quote currency reaches 4000. Use the GET /markets endpoint to check the minimum and maximum amounts you can create a new order for on Bitvavo.

To generate a trigger, you must set triggerType, triggerAmount and triggerReference.

triggerType
string
Value: "price"

Set to price when you create a trigger for a stopLoss, stopLossLimit, takeProfit, or takeProfitLimit orderType on market.

Currently the price triggerType only is supported.

To generate a trigger, you must set triggerType, triggerAmount and triggerReference.

triggerReference
string
Enum: "lastTrade" "bestBid" "bestAsk" "midPrice"

Define the price type that triggers this order to be filled for a stopLoss, stopLossLimit, takeProfit, or takeProfitLimit orderType on market. For example, to buy at the best price on Bitvavo, set to bestAsk.

Set to one of the following:

  • lastTrade: the price at which the latest buy order and sell order was filled in a trade on Bitvavo for market.

  • bestBid: the highest offer available on Bitvavo for market. This is the best price you can sell at.

  • bestAsk: the lowest offer available on Bitvavo for market. This is the best price you can buy at.

  • midPrice: the average of the current bid and ask prices available on Bitvavo.

To generate a trigger, you must set triggerType, triggerAmount and triggerReference.

timeInForce
string
Default: "GTC"
Enum: "GTC" "IOC" "FOK"

Set how long any orderType remains active for.

Set to one of the following:

  • FOK: Fill-Or-Kill, fill the entire order from existing orders, or cancel the entire order.

  • GTC: Good-Til-Canceled, remain on the order book until the entire order is filled, or you manually cancel it.

  • IOC: Immediate-Or-Cancel, fill against existing orders then cancel the unfilled balance.

postOnly
boolean
Default: false

Control the fees you pay on Bitvavo for limit, stopLossLimit, or takeProfitLimit orderTypes. Set to one of the following:

  • true: the order is filled with orders placed after this one, you pay the maker fee only. If this order has to be filled against existing orders, the entire order is cancelled.

  • false: this default value means that your order is filled with existing and more recent orders.

selfTradePrevention
string
Default: "decrementAndCancel"
Enum: "cancelBoth" "cancelNewest" "cancelOldest" "decrementAndCancel"

Control the way self trading is rolled back on Bitvavo for conflicting orders for any orderType.

Self-trading is when the same user is both the buyer and the seller in a trade. That is, when a trade is made, the digital asset does not change beneficial owner.

Self-trading is not allowed on Bitvavo.

Set to one of the following:

  • decrementAndCancel: this default setting decrements your buy and sell orders by the amount that would have been filled in the trade. This cancels the smaller order. For example, if your sell order was for 500 BTC and the buy order for 300 BTC. The buy order is canceled and the sell order becomes 200 BTC.

  • cancelOldest: cancel the order that was submitted first to Bitvavo in the self-trade .

  • cancelNewest: cancel the order that was submitted more recently to Bitvavo in the self-trade.

  • cancelBoth: cancel both orders in the self-trade.

disableMarketProtection
boolean
Default: false

Best practice is to never disable market protection. Set to true to allow any fill for market, stopLoss, or takeProfit orderTypes.

By default, market orders are canceled when the next fill price is 10% worse than the best fill price. This prevents you from filling market orders at an undesirable price. Bitvavo uses the following formula for prices at the top of the order book to calculate this difference:

Highest bid
-----------
Lowest ask
responseRequired
boolean
Default: true

Control the amount of data in the return parameters for any orderType.

Set to either:

  • true: you receive all return parameters in the 200 Response.
  • false: an acknowledgement of success or failure only is returned. Use this option to reduce the response time.

Responses

Request samples

Content type
application/json
Example
{
  • "market": "BTC-EUR",
  • "side": "buy",
  • "orderType": "limit",
  • "amount": "10",
  • "price": 7000,
  • "responseRequired": false,
  • "clientOrderId": "2be7d0df-d8dc-7b93-a550-8876f3b393e6"
}

Response samples

Content type
application/json
Example
{
  • "orderId": "1be6d0df-d5dc-4b53-a250-3376f3b393e6",
  • "clientOrderId": "2be7d0df-d8dc-7b93-a550-8876f3b393e9",
  • "market": "BTC-EUR",
  • "created": 1706100650751,
  • "updated": 1706100650751,
  • "status": "new",
  • "side": "buy",
  • "orderType": "limit",
  • "amount": "10",
  • "amountRemaining": "10",
  • "price": "7000",
  • "amountQuote": "5000",
  • "amountQuoteRemaining": "5000",
  • "onHold": "9109.61",
  • "onHoldCurrency": "BTC",
  • "triggerPrice": "4000",
  • "triggerAmount": "4000",
  • "triggerType": "price",
  • "triggerReference": "lastTrade",
  • "filledAmount": "0",
  • "filledAmountQuote": "0",
  • "feePaid": "0",
  • "feeCurrency": "EUR",
  • "fills": [
    ],
  • "selfTradePrevention": "decrementAndCancel",
  • "visible": true,
  • "timeInForce": "GTC",
  • "postOnly": true,
  • "disableMarketProtection": true
}

Update order

Updates a previous placed limit order. Make sure that at least one of the optional parameters is set, otherwise nothing will be updated. This is faster than (and preferred over) canceling orders and creating new orders. During the update your order is briefly removed from the order book.

You must set either orderId or clientOrderId. If you set both, clientOrderId takes precedence. clientOrderId is only added in the response when you set it in the request.

Rate limit weight points: 1.
Websocket action: privateUpdateOrder.

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
Request Body schema: application/json
market
required
string

Market for which an order should be updated.

orderId
string <UUID>

Specify the order to update with the orderId generated by Bitvavo and returned in the response parameters when you made the original call to POST /order.

You must set either orderId or clientOrderId. If you set both, clientOrderId takes precedence.

clientOrderId
string <UUID>

Specify the order to update with the personalized UUID you assigned in the original call to POST /order.

You must set either orderId or clientOrderId. If you set both, clientOrderId takes precedence.

amount
string

Updates amount to this value (and also changes amountRemaining accordingly).

amountQuote
string

Only for market orders: If amountQuote is specified, [amountQuote] of the quote currency will be bought/sold for the best price available.

amountRemaining
string

Updates amountRemaining to this value (and also changes amount accordingly).

price
string

Specifies the amount in quote currency that is paid/received for each unit of base currency.

triggerAmount
string

Only for stop orders: Specifies the amount that is used with the triggerType. Combine this parameter with triggerType and triggerReference to create the desired trigger.

timeInForce
string
Enum: "GTC" "IOC" "FOK"

Only for limit orders: Determines how long orders remain active. Possible values: Good-Til-Canceled (GTC), Immediate-Or-Cancel (IOC), Fill-Or-Kill (FOK). GTC orders will remain on the order book until they are filled or canceled. IOC orders will fill against existing orders, but will cancel any remaining amount after that. FOK orders will fill against existing orders in its entirety, or will be canceled (if the entire order cannot be filled).

selfTradePrevention
string
Enum: "decrementAndCancel" "cancelOldest" "cancelNewest" "cancelBoth"

Self trading is not allowed on Bitvavo. Multiple options are available to prevent this from happening. The default ‘decrementAndCancel’ decrements both orders by the amount that would have been filled, which in turn cancels the smallest of the two orders. ‘cancelOldest’ will cancel the entire older order and places the new order. ‘cancelNewest’ will cancel the order that is submitted. ‘cancelBoth’ will cancel both the current and the old order.

postOnly
boolean

Only for limit orders: When postOnly is set to true, the order will not fill against existing orders. This is useful if you want to ensure you pay the maker fee. If the order would fill against existing orders, the entire order will be canceled.

responseRequired
boolean
Default: true

If this is set to 'true', all order information is returned. Set this to 'false' when only an acknowledgement of success or failure is required, this is faster.

Responses

Request samples

Content type
application/json
{
  • "market": "BTC-EUR",
  • "orderId": "95d92d6c-ecf0-4960-a608-9953ef71652e",
  • "clientOrderId": "2be7d0df-d8dc-7b93-a550-8876f3b393e9",
  • "amount": "1.567",
  • "amountQuote": "5000",
  • "amountRemaining": "1.560",
  • "price": "6000",
  • "triggerAmount": "4000",
  • "timeInForce": "GTC",
  • "selfTradePrevention": "decrementAndCancel",
  • "postOnly": true,
  • "responseRequired": true
}

Response samples

Content type
application/json
Example
{
  • "orderId": "1be6d0df-d5dc-4b53-a250-3376f3b393e6",
  • "clientOrderId": "2be7d0df-d8dc-7b93-a550-8876f3b393e9",
  • "market": "BTC-EUR",
  • "created": 1706100650751,
  • "updated": 1706100650751,
  • "status": "new",
  • "side": "buy",
  • "orderType": "limit",
  • "amount": "10",
  • "amountRemaining": "10",
  • "price": "7000",
  • "amountQuote": "5000",
  • "amountQuoteRemaining": "5000",
  • "onHold": "9109.61",
  • "onHoldCurrency": "BTC",
  • "triggerPrice": "4000",
  • "triggerAmount": "4000",
  • "triggerType": "price",
  • "triggerReference": "lastTrade",
  • "filledAmount": "0",
  • "filledAmountQuote": "0",
  • "feePaid": "0",
  • "feeCurrency": "EUR",
  • "fills": [
    ],
  • "selfTradePrevention": "decrementAndCancel",
  • "visible": true,
  • "timeInForce": "GTC",
  • "postOnly": true,
  • "disableMarketProtection": true
}

Get order

Returns information about an order you placed previously.

You must set either orderId or clientOrderId. If you set both, clientOrderId takes precedence.

Rate limit weight points: 1.
Websocket action: privateGetOrder.

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
query Parameters
market
required
string
Example: market=BTC-EUR

The market you placed this order in.

orderId
required
string <UUID>
Example: orderId=ff403e21-e270-4584-bc9e-9c4b18461465

The UUID assigned by Bitvavo to this order.

clientOrderId
string <UUID>
Example: clientOrderId=2be7d0df-d8dc-7b93-a550-8876f3b393e9

The personalized UUID you assigned to an order.

Responses

Request samples

// The Javascript SDK works with callbacks and with promises. For info, check our GitHub.
const bitvavo = require('bitvavo')().options({
  APIKEY: '<APIKEY>',
  APISECRET: '<APISECRET>'
})
bitvavo.getOrder('BTC-EUR', 'a8d260d8-9228-4bcb-979a-01aeaab4e961', (error, response) => {
  if (error === null) {
    console.log(response)
  } else {
    console.log(error)
  }
})

Response samples

Content type
application/json
{
  • "orderId": "1be6d0df-d5dc-4b53-a250-3376f3b393e6",
  • "clientOrderId": "2be7d0df-d8dc-7b93-a550-8876f3b393e9",
  • "market": "BTC-EUR",
  • "created": 1706100650751,
  • "updated": 1706100650751,
  • "status": "new",
  • "side": "buy",
  • "orderType": "limit",
  • "amount": "10",
  • "amountRemaining": "10",
  • "price": "7000",
  • "amountQuote": "5000",
  • "amountQuoteRemaining": "5000",
  • "onHold": "9109.61",
  • "onHoldCurrency": "BTC",
  • "triggerPrice": "4000",
  • "triggerAmount": "4000",
  • "triggerType": "price",
  • "triggerReference": "lastTrade",
  • "filledAmount": "0",
  • "filledAmountQuote": "0",
  • "feePaid": "0",
  • "feeCurrency": "EUR",
  • "fills": [
    ],
  • "selfTradePrevention": "decrementAndCancel",
  • "visible": true,
  • "timeInForce": "GTC",
  • "postOnly": true,
  • "disableMarketProtection": true
}

Cancel order

Cancel an open order.

You must set either orderId or clientOrderId. If you set both, clientOrderId takes precedence.

To find all the orders you have placed that are currently open, call GET /ordersOpen. To filter the orders you want to retrieve, call GET /orders.

Rate limit weight points: This endpoint is not rate limited, if you have reached your rate limit, you can still call this endpoint to cancel an order.
Websocket action: privateCancelOrder.

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
query Parameters
market
required
string
Example: market=BTC-EUR

Set the market the order you want to cancel is in.

Call GET /markets to retrieve the list of markets available on Bitvavo.

orderId
string <UUID>
Example: orderId=ff403e21-e270-4584-bc9e-9c4b18461465

Specify the order to cancel with the orderId generated by Bitvavo and returned in the response parameters when you made the original call to POST /order .

You must set either orderId or clientOrderId. If you set both, clientOrderId takes precedence.

clientOrderId
string <UUID>
Example: clientOrderId=2be7d0df-d8dc-7b93-a550-8876f3b393e9

Specify the order to update with the personalized UUID you assigned in the original call to POST /order.

You must set either orderId or clientOrderId. If you set both, clientOrderId takes precedence.

Responses

Request samples

// The Javascript SDK works with callbacks and with promises. For info, check our GitHub.
const bitvavo = require('bitvavo')().options({
  APIKEY: '<APIKEY>',
  APISECRET: '<APISECRET>'
})

bitvavo.cancelOrder('BTC-EUR', 'c8719781-7251-4fd7-9673-cce170e4f33a', (error, response) => {
  if (error === null) {
    console.log('We canceled order ', response)
  } else {
    console.log(error)
  }
})

Response samples

Content type
application/json
{
  • "orderId": "2e7ce7fc-44e2-4d80-a4a7-d079c4750b61",
  • "clientOrderId": "2be7d0df-d8dc-7b93-a550-8876f3b393e9"
}

Get open orders

Returns all current open orders at once.

Rate limit weight points: 25 (without market) or 1 (with market).
Websocket action: privateGetOrdersOpen.

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
query Parameters
market
string

If market is not specified all open orders will be returned.

Responses

Request samples

// The Javascript SDK works with callbacks and with promises. For info, check our GitHub.
const bitvavo = require('bitvavo')().options({
  APIKEY: '<APIKEY>',
  APISECRET: '<APISECRET>'
})

bitvavo.ordersOpen({}, (error, response) => {
  if (error === null) {
    console.log(response)
  } else {
    console.log(error)
  }
})

Response samples

Content type
application/json
[
  • {
    }
]

Get trades

Returns historic trades for your account.

Rate limit weight points: 5.
Websocket action: privateGetTrades.

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
query Parameters
market
required
string
Example: market=BTC-EUR
limit
integer [ 1 .. 1000 ]
Default: 500

Filter used to limit the returned results. Most recent [limit] trades will be returned.

start
integer <unix-timestamp in milliseconds> >= 0

Integer specifying from (i.e. showing those later in time) which time all orders should be returned. Should be a timestamp in milliseconds since 1 Jan 1970.

end
integer <unix-timestamp in milliseconds> <= 8640000000000000

Integer specifying up to (i.e. showing those earlier in time) which time all orders should be returned. Should be a timestamp in milliseconds since 1 Jan 1970.

tradeIdFrom
string

Filter used to limit the returned results. All trades after this trade ID are returned (i.e. showing those later in time).

tradeIdTo
string

Filter used to limit the returned results. All trades up to this trade ID are returned (i.e. showing those earlier in time).

tradeId
string
Deprecated

Deprecated: tradeId is interpreted as tradeIdTo. Filter used to limit the returned results. All trades up to this trade ID are returned.

Responses

Request samples

// The Javascript SDK works with callbacks and with promises. For info, check our GitHub.
const bitvavo = require('bitvavo')().options({
  APIKEY: '<APIKEY>',
  APISECRET: '<APISECRET>'
})

bitvavo.trades('BTC-EUR', {}, (error, response) => {
  if (error === null) {
    console.log(response)
  } else {
    console.log(error)
  }
})

Response samples

Content type
application/json
[
  • {
    }
]

Get orders

Returns data for multiple orders at once.

Rate limit weight points: 5.
Websocket action: privateGetOrders.

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
query Parameters
market
required
string
Example: market=BTC-EUR
limit
integer [ 1 .. 1000 ]
Default: 500

Filter used to limit the returned results. Most recent [limit] orders will be returned.

start
integer <unix-timestamp in milliseconds> >= 0

Integer specifying from (i.e. showing those later in time) which time all orders should be returned. Should be a timestamp in milliseconds since 1 Jan 1970.

end
integer <unix-timestamp in milliseconds> <= 8640000000000000

Integer specifying up to (i.e. showing those earlier in time) which time all orders should be returned. Should be a timestamp in milliseconds since 1 Jan 1970.

orderIdFrom
string <UUID>

Filter used to limit the returned results. All orders after this order ID are returned (i.e. showing those later in time).

orderIdTo
string <UUID>

Filter used to limit the returned results. All orders up to this order ID are returned (i.e. showing those earlier in time).

orderId
string
Deprecated

Deprecated: orderId is interpreted as orderIdTo. Filter used to limit the returned results. All orders up to this order ID are returned.

Responses

Request samples

// The Javascript SDK works with callbacks and with promises. For info, check our GitHub.
const bitvavo = require('bitvavo')().options({
  APIKEY: '<APIKEY>',
  APISECRET: '<APISECRET>'
})
bitvavo.getOrders('BTC-EUR', {}, (error, response) => {
  if (error === null) {
    console.log(response)
  } else {
    console.log(error)
  }
})

Response samples

Content type
application/json
[
  • {
    }
]

Cancel orders

Cancel multiple orders at once. Either for an entire market or for the entire account.

Rate limit weight points: This endpoint is not rate limited, if you have reached your rate limit, you can still call this endpoint to cancel an order.
Websocket action: privateCancelOrders.

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
query Parameters
market
string
Example: market=BTC-EUR

Filter used to specify for which market orders should be canceled. If market is not specified, all open orders will be canceled.

Responses

Request samples

// The Javascript SDK works with callbacks and with promises. For info, check our GitHub.
const bitvavo = require('bitvavo')().options({
  APIKEY: '<APIKEY>',
  APISECRET: '<APISECRET>'
})

bitvavo.cancelOrders({}, (error, response) => {
  if (error === null) {
    console.log(response)
  } else {
    console.log(error)
  }
})

Response samples

Content type
application/json
[
  • {
    }
]

Transfer endpoints

Deposit and withdraw funds in Bitvavo.

Deposit assets

Returns deposit address (with paymentid for some assets) or bank account information to increase your balance.

Rate limit weight points: 1.
Websocket action: privateDepositAssets.

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
query Parameters
symbol
required
string

Short version of the asset name to deposit.

Responses

Request samples

// The Javascript SDK works with callbacks and with promises. For info, check our GitHub.
const bitvavo = require('bitvavo')().options({
  APIKEY: '<APIKEY>',
  APISECRET: '<APISECRET>'
})

bitvavo.depositAssets('BTC', (error, response) => {
  if (error === null) {
    console.log(response)
  } else {
    console.log(error)
  }
})

Response samples

Content type
application/json
Example
{
  • "address": "CryptoCurrencyAddress",
  • "paymentid": "10002653"
}

Deposit history

Returns the deposit history of the account.

Rate limit weight points: 5.
Websocket action: privateGetDepositHistory.

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
query Parameters
symbol
string

Optional filter used to specify for which asset the deposit history should be returned. When no symbol is specified, all deposits will be returned.

limit
integer [ 1 .. 1000 ]
Default: 500

Filter used to limit the returned results. Most recent [limit] deposits will be returned.

start
integer <unix-timestamp in milliseconds> >= 0

Integer specifying from (i.e. showing those later in time) which time all deposits should be returned. Should be a timestamp in milliseconds since 1 Jan 1970.

end
integer <unix-timestamp in milliseconds> <= 8640000000000000

Integer specifying up to (i.e. showing those earlier in time) which time all deposits should be returned. Should be a timestamp in milliseconds since 1 Jan 1970.

Responses

Request samples

// The Javascript SDK works with callbacks and with promises. For info, check our GitHub.
const bitvavo = require('bitvavo')().options({
  APIKEY: '<APIKEY>',
  APISECRET: '<APISECRET>'
})

bitvavo.depositHistory({}, (error, response) => {
  if (error === null) {
    console.log(response)
  } else {
    console.log(error)
  }
})

Response samples

Content type
application/json
Example
{
  • "timestamp": 1706609321000,
  • "symbol": "BTC",
  • "amount": "0.99994",
  • "address": "14qViLJfdGaP4EeHnDyJbEGQysnCpwk3gd",
  • "paymentId": "10002653",
  • "txId": "927b3ea50c5bb52c6854152d305dfa1e27fc01d10464cf10825d96d69d235eb3",
  • "fee": "0.000063"
}

Withdraw assets

Request a withdrawal to an external cryptocurrency address or verified bank account. Please note that 2FA and address confirmation by e-mail are disabled for API withdrawals.

Rate limit weight points: 1.
Websocket action: privateWithdrawAssets.

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
Request Body schema: application/json

The desired withdrawal to create

symbol
required
string

Short version of asset name to withdraw.

amount
required
string

The amount to be withdrawn.

address
required
string

Wallet address or IBAN. For digital assets: please double check this address. Funds sent can not be recovered.

paymentId
string

For digital assets only. Payment IDs are used to identify transactions to merchants and exchanges with a single address. This is mostly called a note, memo or tag. Should be set when withdrawing straight to another exchange or merchants that require payment id's.

internal
boolean
Default: false

For digital assets only. Should be set to true if the withdrawal must be sent to another Bitvavo user internally. No transaction will be broadcast to the blockchain and no fees will be applied. This operation fails if the wallet does not belong to a Bitvavo user.

addWithdrawalFee
boolean
Default: false

If set to true, the fee will be added on top of the requested amount, otherwise the fee is part of the requested amount and subtracted from the withdrawal.

Responses

Request samples

Content type
application/json
{
  • "symbol": "BTC",
  • "amount": "1.5",
  • "address": "BitcoinAddress",
  • "paymentId": "10002653",
  • "internal": false,
  • "addWithdrawalFee": false
}

Response samples

Content type
application/json
{
  • "success": true,
  • "symbol": "BTC",
  • "amount": "1.5"
}

Withdrawal history

Returns the withdrawal history.

Rate limit weight points: 5.
Websocket action: privateGetWithdrawalHistory.

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
query Parameters
symbol
string

Optional filter used to specify for which asset the withdrawal history should be returned. When no symbol is specified, all deposits will be returned.

limit
integer [ 1 .. 1000 ]
Default: 500

Filter used to limit the returned results. Most recent [limit] withdrawals will be returned.

start
integer <unix-timestamp in milliseconds> >= 0

Integer specifying from (i.e. showing those later in time) which time all withdrawals should be returned. Should be a timestamp in milliseconds since 1 Jan 1970.

end
integer <unix-timestamp in milliseconds> <= 8640000000000000

Integer specifying up to (i.e. showing those earlier in time) which time all withdrawals should be returned. Should be a timestamp in milliseconds since 1 Jan 1970.

Responses

Request samples

// The Javascript SDK works with callbacks and with promises. For info, check our GitHub.
const bitvavo = require('bitvavo')().options({
  APIKEY: '<APIKEY>',
  APISECRET: '<APISECRET>'
})

bitvavo.withdrawalHistory({}, (error, response) => {
  if (error === null) {
    console.log(response)
  } else {
    console.log(error)
  }
})

Response samples

Content type
application/json
{
  • "timestamp": 1542967486256,
  • "symbol": "BTC",
  • "amount": "0.99994",
  • "address": "BitcoinAddress",
  • "paymentId": "10002653",
  • "txId": "927b3ea50c5bb52c6854152d305dfa1e27fc01d10464cf10825d96d69d235eb3",
  • "fee": "0.00006",
  • "status": "awaiting_processing"
}

Account endpoints

Information about your Bitvavo account

Account

Returns the current fees for this account.

Rate limit weight points: 1.
Websocket action: privateGetAccount.

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)

Responses

Request samples

// The Javascript SDK works with callbacks and with promises. For info, check our GitHub.
const bitvavo = require('bitvavo')().options({
  APIKEY: '<APIKEY>',
  APISECRET: '<APISECRET>'
})

bitvavo.account((error, response) => {
  if (error == null) {
    console.log(response)
  } else {
    console.log(error)
  }
})

Response samples

Content type
application/json
{
  • "fees": {
    }
}

Balance

Returns the current balance for this account.

Rate limit weight points: 5.
Websocket action: privateGetBalance.

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
query Parameters
symbol
string

Filter used to specify for which asset the balance should be returned. If symbol is omitted, all assets with a non-zero balance are returned plus those traded at least once.

Responses

Request samples

// The Javascript SDK works with callbacks and with promises. For info, check our GitHub.
const bitvavo = require('bitvavo')().options({
  APIKEY: '<APIKEY>',
  APISECRET: '<APISECRET>'
})

bitvavo.balance({}, (error, response) => {
  if (error === null) {
    console.log(response)
  } else {
    console.log(error)
  }
})

Response samples

Content type
application/json
[
  • {
    }
]

Fees

Retrieve the fees you are charged for trading in a specific market.


With trading fees ranging from 0.00% to 0.25%, Bitvavo's fees are among the lowest in the industry. The fee tier you are member of is dependant on your total trading volume over the past 30 days in all markets. For example, if you traded €26 million on Bitvavo over the last 30 days, you are in tier 8 in the Bitvavo fee structure.

The trading fee you are charged depends on the Category that market is included in. For example, if your trading volume puts you in tier 8, the taker fee you are charged to trade a Category B asset is 0.04%. In Category A the taker fee is 0.02%.

Rate limit weight points: 1

Websocket action: privateGetFees

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
query Parameters
market
string
Example: market=BTC-EUR

The market you want your fee information for. Leave this parameter empty to retrieve the fee for your current tier in Category B.

Call GET /markets to retrieve the list of markets available on Bitvavo.

Responses

Request samples

{
  "action" : "privateGetFees"
  "market" : "BTC-EUR"
}

Response samples

Content type
application/json
{
  • "tier": "0",
  • "volume": "10000.00",
  • "taker": "0.0025",
  • "maker": "0.0015"
}

Synchronization endpoints

Synchronize information with your app. Including the markets and assets traded on Bitvavo.

Time

Returns the current timestamp in milliseconds since 1 Jan 1970. This can be useful if you need to synchronize your time with Bitvavo's servers.

Rate limit weight points: 1.
Websocket action: getTime.

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)

Responses

Request samples

import javaBitvavoApi.Bitvavo;

Bitvavo bitvavo = new Bitvavo();
System.out.println("Current time is " + bitvavo.time().getLong("time"));

Response samples

Content type
application/json
{
  • "time": 1539180275424
}

Markets

Retrieve information about one or all markets on Bitvavo.

Rate limit weight points: 1

Websocket action: getMarkets

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
query Parameters
market
string
Example: market=BTC-EUR

The market you want data about.

Responses

Request samples

// The Javascript SDK works with callbacks and with promises. For info, check our GitHub.
const bitvavo = require('bitvavo')()
// If all markets should be returned, pass an empty options object.
bitvavo.markets({}, (error, response) => {
  if (error === null) {
    for (let object of response) {
      console.log('Market response: ', object)
    }
  } else {
    console.log(error)
  }
})

Response samples

Content type
application/json
[
  • {
    }
]

Assets

Returns information on the supported assets. An optional filter can be passed to limit the results.

Rate limit weight points: 1.
Websocket action: getAssets.

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
query Parameters
symbol
string
Example: symbol=BTC

Filter used to specify for which asset data should be returned.

Responses

Request samples

// The Javascript SDK works with callbacks and with promises. For info, check our GitHub.
const bitvavo = require('bitvavo')()
bitvavo.assets({}, (error, response) => {
  if (error === null) {
    for (let object of response) {
      console.log('Asset: ', object)
    }
  } else {
    console.log(error)
  }
})

Response samples

Content type
application/json
[
  • {
    }
]

WebSocket

To implement low-latency, high-frequency trading, you interact with Bitvavo using WebSocket. In a hurry? WebSocket is implemented for you in the Bitvavo SDKs.

About WebSocket

All REST endpoints in Bitvavo API are available using WebSocket. The base URL for Bitvavo WebSocket is wss://ws.bitvavo.com/v2/, and you encode all messages to the WebSocket in a JSON object. For all endpoints, you pass the same parameters as the REST requests in the JSON object, plus the action parameter to specify the endpoint. For example, the HTTP GET request to retrieve data about a specific market, https://api.bitvavo.com/v2/markets?market=AION-EUR is written as:

{
  "action":"getMarkets",
  "market":"AION-EUR"
}

The WebSocket action is listed with each endpoint in this page. For example, GET /markets.

Trace actions

With WebSocket, to easily associate the return parameters with your initial request, use the requestId parameter. Bitvavo inserts the integer value of requestId with the return parameters for the action. For example, a call to:

{
  "action":"getMarkets",
  "market":"AION-EUR", 
  "requestId": 4051979 
}

returns:

{
  "action": "getMarkets",
  "response": {
    "market": "AION-EUR",
    "status": "halted",
    "base": "AION",
    "quote": "EUR",
    "pricePrecision": 5,
    "minOrderInBaseAsset": "10",
    "minOrderInQuoteAsset": "5",
    "maxOrderInBaseAsset": "1000000000",
    "maxOrderInQuoteAsset": "1000000000",
    "orderTypes": [
      "market",
      "limit",
      "stopLoss",
      "stopLossLimit",
      "takeProfit",
      "takeProfitLimit"
    ]
  },
  "requestId": 4051979
}

Subscribe to data

To receive updates using WebSocket, subscribe to one or more of the following channels:

  • account: Events related to your orders: create, update, cancel or fill events are sent to this channel. Requires authentication.
  • book: Order book updates such as bids and asks in the format [price, size] are sent to this channel. Use this and getBook to maintain a local copy of the Bitvavo order books.
  • trades: After a trade, public trade information is sent to this channel.
  • ticker: Updates to the best bid, best ask and/or last price.
  • ticker24h: Updated ticker24h objects are sent to this channel once a second. A ticker24h object is considered updated if one of the values besides timestamp has changed.
  • candles: After a trade, a new candle is sent to this channel.

The subscribe and unsubscribe actions require a channels parameter. This is a list of JSON objects. Each object has a:

  • name: The name of the channel. For example, book.
  • markets: The list of markets. For example, ["BTC-EUR"].
  • interval: The list of intervals. For example, ["1h"]. This is only for candles.

For example:

  {
    "action": "subscribe",
    "channels": [
      {
        "name": "candles",
        "interval": [
          "1h"
        ],
        "markets": [
          "BTC-EUR"
        ]
      },
      {
        "name": "book",
        "markets": [
          "BTC-EUR",
          "XRP-EUR"
        ]
      }
    ]
  }

The following events are emitted for the subscribed channels: order, fill, book, trade, ticker, ticker24h, candle. The authenticate, unauthenticate, subscribed and unsubscribed events are sent after authentication or (un)subscribe messages.

WebSocket authentication

To securely connect to Bitvavo in a WebSocket, you must send a message that provides authentication for the duration of the connection. For example:

{
  "action": "authenticate",
  "key": "ExampleKey",
  "signature": "653fc0505431c63a043273da4bd2f0927eae83948d796084f313e5d1131b0d6f",
  "timestamp": 1548175200641
}

This JSON object has the following parameters:

  • action: authenticate.

  • key: Your API Key.

  • signature: A signature generated following the REST specification with a GET request to /v2/websocket and no body.

    For example, If timestamp is 1548175200641, and secret is bitvavo. This string, 1548175200641GET/v2/websocket results in the following signature 653fc0505431c63a043273da4bd2f0927eae83948d796084f313e5d1131b0d6f.

  • timestamp: The current timestamp in milliseconds since 1 Jan 1970. For example: 1548175200641.

  • window (optional) : The time in milliseconds that your request is allowed to execute in. The default value is 10000 (10s), the maximum value is 60000 (60s).

Market data subscription WebSocket

Receive the latest information about markets, and market trades in your WebSocket callback.

Ticker subscription

Subscribes to the ticker channel, which returns an object each time the best bid or ask changes.

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
Request Body schema: application/json
action
required
string

The action that should be performed by the websocket server, "subscribe" is used for all subscriptions.

required
Array of objects

Object containing the desired subscriptions.

Responses

Request samples

Content type
application/json
{
  • "action": "subscribe",
  • "channels": [
    ]
}

Response samples

Content type
application/json
{
  • "event": "subscribed",
  • "subscriptions": {
    }
}

Ticker 24 hour subscription

Subscribes to the ticker 24 hour channel, which returns an object every second, if values have changed.

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
Request Body schema: application/json
action
required
string

The action that should be performed by the websocket server, "subscribe" is used for all subscriptions.

required
Array of objects

Object containing the desired subscriptions.

Responses

Request samples

Content type
application/json
{
  • "action": "subscribe",
  • "channels": [
    ]
}

Response samples

Content type
application/json
{
  • "event": "subscribed",
  • "subscriptions": {
    }
}

Candles subscription

Subscribes to candle data and returns a candle each time a new one is formed.

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
Request Body schema: application/json
action
required
string

The action that should be performed by the websocket server, "subscribe" is used for all subscriptions.

required
Array of objects

Object containing the desired subscriptions.

Responses

Request samples

Content type
application/json
{
  • "action": "subscribe",
  • "channels": [
    ]
}

Response samples

Content type
application/json
{
  • "event": "subscribed",
  • "subscriptions": {
    }
}

Trades subscription

Subscribes to the trades channel, which sends an object whenever a trade has occurred.

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
Request Body schema: application/json
action
required
string

The action that should be performed by the websocket server, "subscribe" is used for all subscriptions.

required
Array of objects

Object containing the desired subscriptions.

Responses

Request samples

Content type
application/json
{
  • "action": "subscribe",
  • "channels": [
    ]
}

Response samples

Content type
application/json
{
  • "event": "subscribed",
  • "subscriptions": {
    }
}

Book subscription

Subscribes to the book and returns a delta on every change to the book.

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
Request Body schema: application/json
action
required
string

The action that should be performed by the websocket server, "subscribe" is used for all subscriptions.

required
Array of objects

Object containing the desired subscriptions.

Responses

Request samples

Content type
application/json
{
  • "action": "subscribe",
  • "channels": [
    ]
}

Response samples

Content type
application/json
{
  • "event": "subscribed",
  • "subscriptions": {
    }
}

Trading subscription WebSocket

Receive the latest information about your trades and your account in your WebSocket callback.

Track your orders

The channels you create with a subscribe action send an event to your WebSocket every time there is an update related to orders you placed on Bitvavo in the markets you specify.

Each trading subscription WebSocket receives the following events:

  • Subscribe: confirmation that the channel you created to receive order and fill events for specific markets has been created.

  • Order: receive a JSON object containing data about every order you created or updated with calls to POST /order, PUT /order, DELETE /order or DELETE /orders in the markets you subscribed to in this channel.

  • Fill: receive a JSON object containing data about every partial or complete fill or trade executed for an order you placed on Bitvavo in the markets you subscribed to in this channel.

Authorizations:
(API Key: Bitvavo-Access-KeyAPI Key: Bitvavo-Access-TimestampAPI Key: Bitvavo-Access-SignatureAPI Key: Bitvavo-Access-Window)
Request Body schema: application/json
action
required
string

Set to subscribe to receive information about the fills and trades related to the orders you make in the markets you define in channels.

required
Array of objects

Listen for trading events in one or more markets in one or more channels.

Responses

Request samples

Content type
application/json
{
  • "action": "subscribe",
  • "channels": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "event": "subscribed",
  • "subscriptions": {
    }
}

Rate limits

Each REST endpoint and WebSocket action in Bitvavo API is allocated Rate limit weight points. For example, a call to POST /order uses 1 weight point. For each call to Bitvavo, Rate limit weight points is subtracted from bitvavo-ratelimit-limit, leaving bitvavo-ratelimit-remaining until bitvavo-ratelimit-resetat. For authenticated users, if you use more than bitvavo-ratelimit-limit points in one minute, Bitvavo returns error code 110 in an HTTP 429 response and your account is blocked for 1 minute. For unauthenticated users, the IP used to make calls to Bitvavo is blocked for 15 minutes.

When you make a REST call to Bitvavo API, rate limit information is returned in the following headers:

  • bitvavo-ratelimit-remaining: your remaining weight points until the counter resets.
  • bitvavo-ratelimit-resetat: the timestamp when the counter resets.
  • bitvavo-ratelimit-limit: your allocated weight points per minute. The default value is 1000.

The rate limit applies to the sum of all calls made using REST and WebSocket. When you use WebSocket in your trading app, rate limit information is not sent to your callback. Make REST calls to keep track of your weight points.

Although you can connect to Bitvavo with multiple WebSockets in parallel, each WebSocket is limited to 500 requests per second. If you exceed the request limit, Bitvavo returns error code 112 in an HTTP 429 response and your account is blocked for 1 minute.

If you use Bitvavo SDKs, track your weight points with calls to:

limit = bitvavo.getRemainingLimit()

Error messages

This section contains information about all possible error messages returned by Bitvavo. Each error message is associated with one of the following HTTP status messages:

HTTP 400: Bad Request

The following table explains the reason for each errorCode returned by Bitvavo with a HTTP 400 status code:

errorCode Reason
102 The JSON object you sent is invalid.
200 Path parameters are not accepted for this endpoint. Take care, parameters are case-sensitive.
201 Body parameters are not accepted for this endpoint. Take care, query parameters are case-sensitive.
202 A parameter in your call to POST | PUT /order is not supported for this orderType. For example, you cannot set price for a market, stopLoss, or takeProfit orderType.
203 Either you did not include a required parameter in you request, or you included incompatible parameters. For example, in a call to POST /order, market is required, amount and amountQuote are incompatible.
204 You used a parameter that is not in the parameter list for this endpoint.
205 The value you set for a parameter is incorrect. For example, in a call to GET /{market}/candles you set interval to 6d, which is not in the interval enum.
206 You set incompatible parameters in your call. For example, in a call to GET /orders you set orderIdTo and orderIdFrom.
210 The value of amount in your POST | PUT /order request is greater than maxOrderInBaseAsset. To see the highest value allowed for amount in market, call GET /markets.
211 The value of price in your POST | PUT /order request is greater than 100000000000.
212 The value of amount in your POST | PUT /order request is lower than minOrderInBaseAsset. To see the lowest value allowed for amount in market, call GET /markets.
213 The value of price in your POST | PUT /order request is lower than 0.000000000000001.
214 The value of price in your POST | PUT /order request has too many significant digits. See pricePrecision in GET /markets for the maximum number of significant digits.
215 The value of price in your POST | PUT /order request has more than 15 digits after the decimal point.
216 Your balance is not sufficient to perform this operation.
217 The value of amountQuote in your POST | PUT /order request is lower than minOrderInQuoteAsset. To see the lowest value allowed for amountQuote in market, call GET /markets.
218 The value of triggerAmount in your POST | PUT /order request has too many significant digits. See pricePrecision, in GET /markets for the maximum number of significant digits.
219 The market you want to trade in your POST | PUT /order is no longer listed on Bitvavo.
220 Conflict
231 When markets are paused, you must set timeInForce to GTC in your POST | PUT /order request.
232 For your PUT /order request to be successful, change one or more of amount, amountRemaining, price, timeInForce, selfTradePrevention or postOnly.
233 To DELETE /order, the value of status in the return parameters for this order must be new or partiallyFilled.
234 You cannot PUT /order a market orderType.
235 You can have a maximum of 100 open orders at any one time in each market.
236 You can set one only of amount, amountRemaining, or amountQuote when you call PUT /order for any orderType.
237 You must set one of amount, amountRemaining, amountQuote, triggerAmount or selfTradePrevention when you call PUT /order for a stopLoss orderType.
238 You must set one of amount, amountRemaining, price, triggerAmount, timeInForce, selfTradePrevention or postOnly when you call PUT /order for a stopLossLimit orderType.
239 You cannot swap between amount and amountQuote when you update an order. For example, when you set amount in your call to POST /order, you cannot update amountQuote in subsequent calls to PUT /order.
400 Server error
401 Deposits for this asset are not available at this time.
402 Verify your identity before you deposit or POST /withdraw digital assets.
403 Verify your phone number before you deposit or POST /withdraw digital assets.
404 Could not complete this operation. Internal server error.
405 You cannot POST /withdraw digital assets during the cooldown period. The cooldown period may also apply after you add a new bank account.
406 The value of amount in your POST /withdraw request is below the minimum allowed value. To see the lowest amount allowed for symbol, call GET /assets.
407 Internal transfer is not possible.
408 Your balance is not sufficient to perform this operation.
409 Please verify your bank account and try again.
410 You cannot POST /withdraw for this asset at the moment.
411 You cannot transfer assets to yourself.
412 Error when you attempted to deposit or POST /withdraw digital assets.
413 The IP address set for address in your POST /withdraw request is not in your IP whitelist.
414 You cannot withdraw assets within 2 minutes of logging in.

HTTP 403: Forbidden

The following table explains the reason for each errorCode returned by Bitvavo with a HTTP 403 status code:

errorCode Reason
105 You have exceeded your Rate limit. If your calls to Bitvavo are authenticated, your account is blocked for 1 minute. If your calls are unauthenticated, the IP this call was made from is blocked for 15 minutes.
300 Setup REST or WebSocket authentication to successfully call this endpoint.
301 The API key you use for REST or WebSocket authentication must be 64 characters long.
302 The access timestamp you set for REST or WebSocket authentication must be in milliseconds. For example, 1709904125666.
303 The access window you set for REST or WebSocket authentication must be between 100 and 60000 milliseconds.
304 Your request was not received within the access window you set for REST or WebSocket authentication.
305 The API key used for this call is not active.
306 The API key used for this call is not active. Ensure that you have confirmed the API key.
307 The IP this call was made from is not in the whitelist for this API key.
308 The signature you use for REST or WebSocket authentication must be a 64 character hexadecimal string.
309 The signature you use for REST or WebSocket authentication is invalid.
310 This API key does not have permissions to use the Trading endpoints.
311 This API key does not have permissions to use the Account endpoints.
312 This API key does not have permissions to Withdraw assets.
313 Your Bitvavo session is not valid.
314 You must use REST to connect from a browser.
316 You can use this WebSocket to retrieve public information about assets only.
317 This account is locked. Please contact support@bitvavo.com.
318 You must verify your account to use Bitvavo API for Rest and WebSocket.

HTTP 404: Not found

The following table explains the reason for each errorCode returned by Bitvavo with a HTTP 404 status code:

errorCode Reason
110 Unknown REST endpoint. Please check the URL and HTTP method called against the Bitvavo API reference.
240 No order found. This error can happen when you call POST /order and PUT /order at the same time.
415 Unknown WebSocket action. Please check the action called against the Bitvavo API reference

HTTP 409: Conflict

The following table explains the reason for each errorCode returned by Bitvavo with a HTTP 409 status code:

errorCode Reason
110 The clientOrderId in your call to POST /order already exists in market.

HTTP 429: Too many requests

The following table explains the reason for each errorCode returned by Bitvavo with a HTTP 429 status code:

errorCode Reason
110 You have exceeded your Rate limit by making too many calls to Bitvavo in the last minute.
112 You have exceeded your Rate limit of 500 requests per WebSocket per second.

HTTP 500: internal server error

The following table explains the reason for each errorCode returned by Bitvavo with a HTTP 500 status code:

errorCode Reason
101 Unknown error. This call to Bitvavo may or may not have succeeded.

HTTP 503: service unavailable

The following table explains the reason for each errorCode returned by Bitvavo with a HTTP 503 status code:

errorCode Reason
107 Bitvavo is overloaded. Please wait 500ms and resubmit your call.
108 Bitvavo could not process your oder. Please either increase the execution window in your REST or WebSocket implementation or wait 500ms and resubmit your call.
109 Bitvavo did not respond on time. This operation may or may not have succeeded.

Release notes

The following changes have been made to Bitvavo API:

v2.4.0

Use the new Fees endpoint to retrieve the transaction costs you are charged for trading in a specific market.

v2.3.0

Improve order status tracking with the clientOrderID parameter:

v2.2.2

2.2.1:

  • clientOrderId: Set a personalized UUID for each new order. You use this ID to easily track the order status.
  • requestId: Set a personalized ID to an initial WebSocket request. This value is added to the return parameters for the action.

2.2.0:

  • Added stopLoss, stopLossLimit, takeProfit, takeProfitLimit order types.
  • Added account endpoint.

2.1.2:

  • Added networks to assets.

2.1.1:

  • Added orderId to user trades.

2.1.0:

  • Added bestBidSize and bestAskSize to tickerBook and WebSocket ticker.
  • Added bestBid, bestBidSize, bestAsk, bestAskSize and timestamp to ticker24h.
  • Added tradeIdFrom/tradeIdTo and orderIdFrom/orderIdTo to limit returned trades/orders (deprecating tradeId/orderId in those searches).
  • Added ticker24h WebSocket stream.