BinanceJ

A Java 8 implementation of the Binance API Specification.

Licensing

BinanceJ is released under the MIT license.

Rate Limiting

BinanceJ does not perform rate limiting, so you are responsible for limiting your requests. Pay attention to the errors you receive from Binance and check to see if they are a 429. If they are, you need to back off or face a temporary ban.

API Coverage

The following endpoints are currently covered:

1. GET /api/v1/ping
2. GET /api/v1/time
3. GET /api/v1/exchangeInfo
4. GET /api/v1/depth
5. GET /api/v1/klines
6. GET /api/v3/ticker/price

More will be added in future PRs as they become necessary to me or the people using the library.

Return Types

All functions return an Either type. For those of you not in the know - an Either type represents a disjoint union. Typically this means a "success" and "failure" case that must be handled uniquely. They work well with stream processing and are a very natural way to delineate success and failure cleanly. Additionally it eliminates the pattern of throwing exceptions on errors, and allows exceptions to be reserved for truly exceptional behavior as intended.

By convention I adapted the Haskell Either type style to this code. What this means is that the Either type's Right value is the correct one (mnemonic: "right" as in correct) and the Left value is the ServiceError.

How do I extract the raw value from the Either type?

There are a few ways to do this using Ambivalent, but the most prevalent way in BinanceJ's tests is:

Either<TypeA, TypeB> val = clazz.getThing();

// Good path case
if(val.isRight()) {
  TypeB thing = val.right().join(Function.identity(), Function.identity());
}

Alternatively you are welcome to use Helpers.extractEitherValueSafely method to make your code cleaner.

Examples

Server alive check with ping

GeneralUtilities generalUtilities = GeneralUtilities.builder().apiKey("KEY").secretKey("KEY").build();
Either<ServiceError, Ping> res = generalUtilities.ping();
if(res.isRight()) {
    // Successful ping
}

Getting current server time

GeneralUtilities generalUtilities = GeneralUtilities.builder().apiKey("KEY").secretKey("KEY").build();
Either<ServiceError, ServerTime> res = generalUtilities.getServerTime();

if(res.isRight()) {
    ServerTime response = Helpers.extractEitherValueSafely(res.right());
    //...
}

Getting Exchange Information

GeneralUtilities generalUtilities = GeneralUtilities.builder().apiKey("KEY").secretKey("KEY").build();
Either<ServiceError, ExchangeInfo> res = generalUtilities.getExchangeInfo();

if(res.isRight()) {
    ExchangeInfo response = Helpers.extractEitherValueSafely(res.right());
    //...
}

Getting Candlestick data

MarketData marketData = MarketData.builder().apiKey("KEY").secretKey("KEY").build();
Either<ServiceError, List<Candlestick>> res = marketData.getCandlestickData("ETHBTC", Interval.ONE_MINUTE);

if(res.isRight()) {
    List<Candlestick> data = Helpers.extractEitherValueSafely(res.right());
    //...
}

Getting market depth

MarketData marketData = MarketData.builder().apiKey("KEY").secretKey("KEY").build();
Either<ServiceError, OrderBookDepth> res = marketData.getOrderBookDepth("ETHBTC", 1000);

if(res.isRight()) {
    OrderBookDepth orderBookDepth = Helpers.extractEitherValueSafely(res.right());
    //...
}

Getting ticker price for an instrument

MarketData marketData = MarketData.builder().apiKey("KEY").secretKey("KEY").build();
Either<ServiceError, TickerPrice> res = marketData.getTickerPriceForSymbol("ETHBTC");

if(res.isRight()) {
    TickerPrice tickerPrice = Helpers.extractEitherValueSafely(res.right());
    //...
}

Contributing

Head over to our CONTRIBUTING.md to get started. All features are welcome as long as they are in scope of the API and following the contributing guide.