Bitvavo Java client

This a java client for the API that Bitvavo provides. Bitvavo also provides an API that you can find here, but this client provides specific request and response classes to enhance the developer experience.

BitvavoClient

The main entrypoint of this library is the BitvavoClient class. This class contains no logic, but simple creates the underlying BitvavoHttpClient and BitvavoWebsocketClient clients needed to call the API. If you only need the BitvavoHttpClient or the BitvavoWebsocketClient you can simply create those clients individually.

The BitvavoClientConfiguration class is used to configure the different clients. You can create an apiKey and apiSecret on the Bitvavo website.

BitvavoClientConfiguration configuration = new BitvavoClientConfiguration.Builder()
    .withApiKey("<apiKey>")
    .withApiSecret("<apiSecret>")
    .withRestUrl("https://api.bitvavo.com/v2/")
    .withWsUrl("wss://ws.bitvavo.com/v2/")
    .withAccessWindow(10000)
    .build();


BitvavoClient client = new BitvavoClient(configuration);
BitvavoHttpClient httpClient = client.httpClient();
BitvavoWebsocketClient websocketClient = client.websocketClient();

BitvavoResponse

The response of an API call is always wrapped in a BitvavoResponse class. This class contains a result or an error message if something went wrong. This also ensures that you "the developer" take into account that an API call can fail and if it fails what should happen.

Successful Response

public class Test {

  public static void main(String[] args) {
    BitvavoResponse<String> okResponse = BitvavoResponse.ok("RESULT");

    System.out.println(okResponse.getOrThrow());
    // RESULT
    System.out.println(okResponse.map((result) -> "SUCCESSFUL_" + result).getOrThrow());
    // SUCCESSFUL_RESULT
    switch (okResponse) {
      case BitvavoResponse.Ok(var value) -> System.out.println(value);
      case BitvavoResponse.Error(var errorMessage) -> System.out.println(errorMessage);
    }
    // RESULT
  }
}

Failed Response

public class Test {

  public static void main(String[] args) {
    BitvavoResponse<String> errorResponse = BitvavoResponse.error(new BitvavoErrorMessage.Builder()
            .withErrorCode("101")
            .withErrorMessage("Something went wrong!")
            .build());

    System.out.println(errorResponse.getOrThrow());
    // Exception in thread "main" java.util.NoSuchElementException: No value present, but there was an error: (101: Something went wrong!)
    //	 at be.davidopdebeeck.bitvavo.client.response.BitvavoResponse$Error.getOrThrow(BitvavoResponse.java:50)
    switch (errorResponse) {
      case BitvavoResponse.Ok(var value) -> System.out.println(value);
      case BitvavoResponse.Error(var errorMessage) -> System.out.println(errorMessage);
    }
    // 101: Something went wrong!
  }
}

TODOs

• Implement all endpoints
  • for the BitvavoHttpClient
  • for the BitvavoWebsocketClient
• Implement rate limiting
  • for the BitvavoHttpClient
  • for the BitvavoWebsocketClient
• Add examples for endpoints
  • for the BitvavoHttpClient
  • for the BitvavoWebsocketClient

Endpoints

• General
  • Time
  • Markets
  • Assets
• Market Data
  • Orderbook
  • Trades
  • Candles
  • Ticker Price
  • Ticker Book
  • Ticker 24h
• Orders
  • New order
  • Update order
  • Cancel order
  • Get order
  • Get orders
  • Cancel orders
  • Get open orders
• Trades
  • Get trades
• Account
  • Account
  • Balance
  • Deposit assets
  • Deposit history
  • Withdraw assets
  • Withdrawal history
• Subscriptions
  • Ticker subscription
  • Ticker 24 hour subscription
  • Account subscription
  • Candles subscription
  • Trades subscription
  • Book subscription

Conventions

Class naming

All classes that are exposed as part of the API start with the Bitvavo prefix.

BitvavoRequest classes

Fields

• All fields should be marked as final.
• All required fields need to be validated in the constructor using the requireNonNull() method.
• All optional fields need to have an optional getter method.

Other

• A nested Builder class should be provided for consistent object creation.

BitvavoResponse classes

Fields

• No fields should be marked as final.
• All required fields need to be validated in the constructor using the requireNonNull() method.
• All optional fields need to have an optional getter method.

Other

• An empty constructor should be provided for Jackson.
• A nested Builder class should be provided for consistent object creation.

BitvavoClient

GET endpoints

1. The method on the client has the same value as the name of the REST endpoint.
   • When the endpoint contains a path variable, then it is included in the naming.
   • When the endpoint contains a nested path, then all parts are combined using camelCase naming convention.
2. The query parameters for the REST endpoint are conveyed with a Bitvavo(pathVariable)(endpointName)Request parameter object.
3. The path variables for the REST endpoint are conveyed with a parameter object.
4. The response of the REST endpoint is conveyed with a Bitvavo(pathVariable)(endpointName)Response object.

POST / PUT / DELETE endpoints

1. The method on the client has the same value as the action of the REST endpoint.
   • When the endpoint contains a path variable, then it is included in the naming.
   • When the endpoint contains a nested path, then all parts are combined using camelCase naming convention.
2. The query parameters for the REST endpoint are conveyed with a Bitvavo(pathVariable)(endpointName)Request parameter object.
3. The request body for the REST endpoint are conveyed with a Bitvavo(pathVariable)(endpointName)Request parameter object.
4. The path variables for the REST endpoint are conveyed with a parameter object.
5. The response of the REST endpoint is conveyed with a Bitvavo(pathVariable)(endpointName)Response object.