Skip to main content

API structure

Use our REST API for request-response messaging over HTTP between your app and Bitvavo.

Request format​

All API requests are made to https://api.bitvavo.com/v2/ and include:

HTTP method​

The HTTP method of an endpoint defines the type of action it performs on a given resource. The Bitvavo API supports the following methods:

  • GET - retrieve information.
  • POST - submit data to create a resource.
  • PUT - update a resource.
  • DELETE - remove a resource.

Path​

Each endpoint has a path. The reference documentation for each endpoint includes the path to use in your request, for example GET /{market}/trades.

The curly brackets {} indicate a path parameter that you need to replace with the actual value. For example, in the path /markets/{market}, replace {market} with the actual market you want to retrieve information about.

Headers​

Every request includes the following headers:

  • Content-Type: application/json - indicates that the request body is in JSON format.
  • For authenticated endpoints, additional headers are required:
    • Bitvavo-Access-Key: your API key.
    • Bitvavo-Access-Signature: a SHA256 HMAC hex digest.
    • Bitvavo-Access-Timestamp: Unix timestamp in milliseconds.
    • Bitvavo-Access-Window: (optional) time window for request validity in milliseconds.

Authentication​

To authenticate requests, you need to create a signature using your API secret and the headers specified above. The signature is a SHA256 HMAC hex digest of the concatenated string: timestamp + method + url + body.

To learn how to create a signature, see Authentication.

Example authenticated POST request to place an order
  curl -L 'https://api.bitvavo.com/v2/order' \
  -H 'Content-Type: application/json' \
  -H 'Bitvavo-Access-Key: YOUR_API_KEY' \
  -H 'Bitvavo-Access-Signature: YOUR_GENERATED_SIGNATURE' \
  -H 'Bitvavo-Access-Timestamp: CURRENT_TIMESTAMP' \
  -H 'Bitvavo-Access-Window: 10000' \
  -D '{
    "market": "BTC-EUR",
    "side": "buy",
    "orderType": "limit",
    "amount": "1.5",
    "price": "30000"
  }'

Parameters​

Some API methods require or allow you to send additional information in parameters in your request. These can be: path parameters, body parameters, and query parameters.

Path parameters​

Path parameters required and modify the endpoint path. For example, in the path /markets/{market}, replace {market} with the actual market you want to retrieve information about.

Query parameters​

Query parameters are optional and are added to the URL after a ?. They are used to filter or modify the response.

Get the last 5 trades for the BTC-EUR market
GET /BTC-EUR/trades?limit=5

Body parameters​

Body parameters allow you to pass additional data to the API, mostly in POST and PUT requests. These parameters can be optional or required, depending on the endpoint.

Response format​

After you make a request, the API returns:

Status code​

Indicates the success or failure of the request, for example 200 OK. For example:

Status CodeDescription
200 OKThe request was successful.
400 Bad RequestThe request was malformed or contained invalid parameters.
403 ForbiddenThe request is not allowed, or permissions are insufficient.
429 Too Many RequestsThe request was rate-limited.
500 Internal Server ErrorA problem occurred on Bitvavo's server.

To learn more, see the full list of error codes.

Response headers​

Include the rate limit information:

  • bitvavo-ratelimit-remaining: number of remaining wight points before the reset.
  • bitvavo-ratelimit-resetat: the time when bitvavo-ratelimit-remaining resets to bitvavo-ratelimit-limit.
  • bitvavo-ratelimit-limit: number of available weight points in one minute.

Response body​

The response body is a JSON object with the requested information or an error message. For example:

Successful response
{
  "orderId": "1be6d0df-d5dc-4b53-a250-1234567890ab",
  "market": "BTC-EUR",
  "created": 1615555555555,
  "updated": 1615555555555,
  "status": "new",
  "side": "buy",
  "orderType": "limit",
  "amount": "1.5",
  "amountRemaining": "1.5",
  "price": "30000",
  "amountQuote": "45000",
  "amountQuoteRemaining": "45000",
  "onHold": "1.5",
  "onHoldCurrency": "BTC",
  "filledAmount": "0",
  "filledAmountQuote": "0",
  "feePaid": "0",
  "feeCurrency": "EUR",
  "fills": [],
  "selfTradePrevention": "decrementAndCancel",
  "visible": true,
  "timeInForce": "GTC",
  "postOnly": false,
  "disableMarketProtection": false
}

Endpoints​

Below are the available endpoints for the Bitvavo REST API.

Public endpoints​

The endpoints below 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​

Synchronization endpoints​

  • GET /time - get the current server time.
  • GET /markets - get information about all available trading pairs.
  • GET /assets - get details about all supported assets.

Private endpoints​

The endpoints below 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​

Transfer endpoints​

Account endpoints​

Handle errors​

In case of errors, the API responds with an HTTP status code and a JSON object with the error details.

Error response
{
  "errorCode": 205,
  "error": "Invalid parameter: price"
}

To learn more, see the full list of error codes.