BinanceJ

A Java 8 implementation of the Binance API Specification.

Getting BinanceJ

Maven

<dependency>
    <groupId>com.sigmaflare</groupId>
    <artifactId>binancej</artifactId>
    <version>1.0.4</version>
</dependency>

Gradle

compile group: 'com.sigmaflare', name: 'binancej', version: '1.0.4'

Licensing

BinanceJ is released under the MIT license.

Rate Limiting

BinanceJ will throw a RateLimitExceededException when a HTTP 429 error code comes back. This is an important exception to catch and handle because if you do not back off they will issue a temporary ban. If you don't listen, you'll be receiving IpBannedExceptions.

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.

HTTP Exceptions

Checked Exceptions

Any function in the API can throw a handful of exceptions related to HTTP:

1. IpBannedException: Your IP has been banned after ignoring rate limit exceeded messages
2. RateLimitExceededException: Your IP has exceeded the rate limit and needs to slow down
3. InternalServiceErrorException: An error occurred on Binance's server side (see note below)
4. MalformedRequestException: A malformed request was sent, the error exists on the sender's side (check error code and message)

Note: A 504 error in general should not be treated as an error (though it is "exceptional" behavior). In the case of InternalServiceErrorExceptions it is critical to check the code member of the exception.

The "more general" HTTP exceptions (MalformedRequestException and InternalServiceErrorException) have a code component so you can check the specifics against the Binance Error Documentation.

Standard Exceptions

Runtime Exceptions

In the event an unknown error occurs, the code will throw an UnexpectedErrorException. These are generally complete showstoppers.

Notes

Be sure to call close on the API container class (GeneralUtilities, MarketData, etc) in order to close the CloseableHttpClient resource.

Dates

Dates coming in from Binance have a UTC time zone. You can check this by calling generalUtilities.getExchangeInfo() and checking the value of the timezone field.

Dates are returned to you in the form of a long, so understanding that the date coming back is UTC you should be able to convert it in a straight forward way to a Java 8 Date data type.

Examples

Server alive check with ping

If the ping method does not throw an exception, the ping was successful.

GeneralUtilities generalUtilities = GeneralUtilities.builder().apiKey("KEY").secretKey("KEY").build();
generalUtilities.ping();

Getting current server time

GeneralUtilities generalUtilities = GeneralUtilities.builder().apiKey("KEY").secretKey("KEY").build();
ServerTime = generalUtilities.getServerTime();

Getting Exchange Information

GeneralUtilities generalUtilities = GeneralUtilities.builder().apiKey("KEY").secretKey("KEY").build();
ExchangeInfo res = generalUtilities.getExchangeInfo();

Getting Candlestick data

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

Getting market depth

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

Getting ticker price for an instrument

MarketData marketData = MarketData.builder().apiKey("KEY").secretKey("KEY").build();
TickerPrice res = marketData.getTickerPriceForSymbol("ETHBTC");

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.