A java implementation of the Binance API Specification
Taylor Bockman 42abdde19a Bump version, move central repo to xchg 2 years ago
.circleci Initial GET Work (#1) 2 years ago
.github Initial GET Work (#1) 2 years ago
gradle/wrapper init 2 years ago
src Remove logging dependency (#8) 2 years ago
.codeclimate.yml Code Climate Updates (#3) 2 years ago
.gitignore init 2 years ago
CONTRIBUTING.md First OSSRH config (#6) 2 years ago
LICENSE Initial GET Work (#1) 2 years ago
README.md Bump version, move central repo to xchg 2 years ago
build.gradle Bump version, move central repo to xchg 2 years ago
gradlew init 2 years ago
gradlew.bat init 2 years ago
settings.gradle init 2 years ago



CircleCI Maintainability

A Java 8 implementation of the Binance API Specification.

Getting BinanceJ




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


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.


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


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.


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();

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");


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.