API structure
Use our WebSocket API to connect in real time to the Bitvavo exchange.
Connect to WebSocket
To establish a connection to the Bitvavo WebSocket API, use the following URL:
wss://ws.bitvavo.com/v2/
Message types
Bitvavo WebSocket API supports two types of messaging:
- Actions: send a message to the server to request data and receive a one-rime JSON-encoded response.
- Channels: subscribe to a channels to stream event-based updates in real time.
Actions
To use actions, you first need to have an established connection to our WebSocket server. After the connection is established, you send messages with specific actions that return JSON-encoded responses equivalent to the ones over REST API.
Some actions require an authentication signature in the message. To learn how to sign your WebSocket messages, see Authentication.
Message
When you establish a connection to the Bitvavo WebSocket server, you send a message as a JSON-encoded object with the following parameters:
action
(required): the action you want to perform. For example,getMarkets
.markets
(required): the markets in which to make the request. For example,["BTC-EUR"]
.requestId
: your identifier for the request.- Any additional parameters required for the action. This is specified for every action in the WebSocket API reference.
For example, getMarkets
is a WebSocket action that returns market data equivalent to the GET /markets
request:
{
"action":"getMarkets",
"market":"BTC-EUR"
}
Event
Every time you send a message with a specific action, the server responds with a JSON-encoded object with the following parameters:
action
(required): the action you performed.requestId
: your identifier for the request.response
(required): the JSON object containing the requested data.
In the example of the getMarkets
action, the response returns the latest market data for the BTC-EUR pair:
{
"action": "getMarkets",
"response": {
"market": "BTC-EUR",
"status": "trading",
"base": "BTC",
"quote": "EUR",
"pricePrecision": 5,
"minOrderInBaseAsset": "0.000061",
"minOrderInQuoteAsset": "5",
"maxOrderInBaseAsset": "1000000000",
"maxOrderInQuoteAsset": "1000000000",
"orderTypes": [
"market",
"limit",
"stopLoss",
"stopLossLimit",
"takeProfit",
"takeProfitLimit"
]
}
}
Channels
After you open a connection to our server, you send a subscription message to connect to a specific channel. Unlike for actions, the server then continuously streams updates as the events happen on that channel.
Some channels require an authentication signature in the message. To learn how to sign your WebSocket messages, see Authentication.
Subscribe and unsubscribe
To start the stream, you send a subscribe action
to the server and specify the channels you want to subscribe to. The server streams the data as the specified events happen. To stop the stream, you send an identical message with the unsubscribe action
to the server.
The format of the subscribe
and unsubscribe
messages is a JSON object with:
action
(required): set this to subscribe or unsubscribe.channels
(required): an object with the following parameters:name
: the events to which you want to subscribe. For example,ticker
.markets
: the markets for which you want stream the data. For example,["BTC-EUR"]
.interval
(only forcandles
) the time period for which to return the data. For example,["1h"]
.
For example:
{
"action": "subscribe",
"channels": [
{
"name": "ticker",
"markets": [
"BTC-EUR"
]
}
]
}
{
"action": "unsubscribe",
"channels": [
{
"name": "ticker",
"markets": [
"BTC-EUR"
]
}
]
}
Event
There are two types of events that you receive when you subscribe to a channel:
Subscribe or unsubscribe events
These are event messages you get after you send a subscribe action
messages. The server confirms that you are subscribed or unsubscribed to the channel.
For example:
{
"event": "subscribed",
"subscriptions": {
"ticker": [
"BTC-EUR"
]
}
}
{
"event": "unsubscribed",
"subscriptions": {}
}
Data stream events
While the WebSocket connection is open, and you are subscribed to a channel
, you keep getting event messages.
The server keeps sending JSON-encoded objects with the following parameters:
event
: the event that that you subscribed to. For example, ticker.- All the data related to the event. For example, the latest ticker data for the BTC-EUR pair.
{
"event": "ticker",
"market": "BTC-EUR",
"bestBid": "91294",
"bestBidSize": "0.00161762"
}
Some channels require an authentication signature in the message. To learn how to sign your WebSocket messages, see Authentication.
Supported actions and channels
Below are all available actions and channels for the Bitvavo WebSocket API.
Actions
Market data
getBook
- get the order book for a specific market.getTrades
- get recent public trades for a specific market.getTickerPrice
- obtain the latest price for all markets or a specific market.getTickerBook
- get the current best bid and ask for all or a specific market.getCandles
- get historical candlestick data for a market.getTicker24h
- access 24-hour statistics for all or a specific market.
Trading
privateCreateOrder
- place a new order.privateUpdateOrder
- update an existing order.privateGetOrder
- get information about an existing order.privateCancelOrder
- cancel an open order.privateGetOrdersOpen
- list all open orders.privateGetTrades
- get past trades for your account.privateGetOrders
- get all orders for a specific market.privateCancelOrders
- cancel multiple orders for a specified market or the account.
Transfer
privateDepositAssets
- get deposit addresses for a specific asset.privateGetDepositHistory
- get account deposit history.privateWithdrawAssets
- request a withdrawal to an external address.privateGetWithdrawalHistory
- get account withdrawal history.
Account
privateGetAccount
- get account information, including fee tiers.privateGetBalance
- get balances of all assets in your account.privateGetFees
- get information about trading fees.getAccountHistory
- get account transaction history.
Synchronization
getTime
- get the current server time.getMarkets
- get information about all available trading pairs.getAssets
- get details about all supported assets.
Channels
ticker
- updates to the best bid, best ask, and/or last price.ticker24h
- updated 24-hour ticker statistics, sent once per second.candles
- new OHLCV (Open, High, Low, Close, Volume) candles sent after a trade.trades
- live trade execution notifications.book
- real-time order book updates for subscribed markets.account
- real-time updates on order creation, updates, cancellations, and fills. (Requires authentication)
Track your actions
To help you track the return parameters back to your initial request, you can use the requestId
parameter. Bitvavo adds the integer value of requestId
to the return parameters for the action.
For example, a message:
{
"action":"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
}
Handle disconnections
The connection may be closed due to:
- Network issues
- Rate limiting
- Server restarts
- Authentication failures
To counter this, you can add logic to automatically reconnect. For example:
function connect() {
const ws = new WebSocket('wss://ws.bitvavo.com/v2/');
ws.onopen = () => console.log("Connected to Bitvavo WebSocket");
ws.onclose = () => {
console.log("Disconnected. Reconnecting in 5 seconds...");
setTimeout(connect, 5000);
};
}
connect();
Handle errors
In case of errors, the API responds with an HTTP status code and a JSON object with the error details.
{
"event": "error",
"errorCode": 100,
"error": "Invalid JSON format"
}
To learn more, see the full list of error codes.