This is a lightweight library that works as a connector to the Binance public API
- Supported APIs:
/api/*/sapi/*- Spot Websocket Market Stream
- Spot User Data Stream
- Test cases and examples
Replace LATEST_VERSION with the latest version number and paste the snippet below in pom.xml
<dependency>
<groupId>io.github.binance</groupId>
<artifactId>binance-connector-java</artifactId>
<version>LATEST_VERSION</version>
</dependency>
Run mvn install where pom.xml is located to install the dependency.
https://www.javadoc.io/doc/io.github.binance/binance-connector-java/latest/index.html
The examples are located under src/test/java/examples.
Before running any of it, PrivateConfig.java must be set up correctly with API_KEY and SECRET_KEY or PRIVATE_KEY_PATH (if using RSA Keys).
Note that this PrivateConfig.java is only used for examples,
you should have your own configuration file when using the library.
The endpoints are categorized according to the Binance API document. Each object corresponds to its category which will be used to call its respective endpoints.
| Category | Object |
|---|---|
| Binance Code | createGiftCard |
| BLVT | createBlvt |
| BSwap | createBswap |
| C2C | createC2C |
| Convert | createConvert |
| CryptoLoans | createCrytoLoans |
| Fiat | createFiat |
| Futures | createFutures |
| Margin | createMargin |
| Market | createMarket |
| Mining | createMining |
| NFT | createNFT |
| Pay | createPay |
| Portfolio Margin | createPortfolioMargin |
| Rebate | createRebate |
| Savings | createSavings |
| Staking | createStaking |
| Sub Account | createsubAccount |
| Trade | createTrade |
| UserData | createUserData |
| Wallet | createWallet |
SpotClientImpl client = new SpotClientImpl();
String result = client.createMarket().exchangeInfo();LinkedHashMap<String,Object> parameters = new LinkedHashMap<String,Object>();
SpotClientImpl client = new SpotClientImpl(PrivateConfig.API_KEY, PrivateConfig.SECRET_KEY);
parameters.put("symbol","BTCUSDT");
parameters.put("side", "SELL");
parameters.put("type", "LIMIT");
parameters.put("timeInForce", "GTC");
parameters.put("quantity", 0.01);
parameters.put("price", 9500);
String result = client.createTrade().testNewOrder(parameters);While /sapi/* endpoints don't have testnet environment yet, /api/* endpoints can be tested in
Spot Testnet. You can use it by changing the base URL:
LinkedHashMap<String,Object> parameters = new LinkedHashMap<>();
SpotClientImpl client = new SpotClientImpl(PrivateConfig.TESTNET_API_KEY, PrivateConfig.TESTNET_SECRET_KEY, PrivateConfig.TESTNET_URL);
String result = client.createMarket().time();If baseUrl is not provided, it defaults to api.binance.com.
It's recommended to pass in the baseUrl parameter, even in production as Binance provides alternative URLs
in case of performance issues:
https://api1.binance.comhttps://api2.binance.comhttps://api3.binance.com
All parameters are read from a LinkedHashMap<String,Object> object where String is the
name of the parameter and Object is the value of the parameter. The parameters should follow their exact naming as in the API documentation.
LinkedHashMap<String,Object> parameters = new LinkedHashMap<String,Object>();
parameters.put("symbol","BTCUSDT");
parameters.put("side", "SELL");
parameters.put("type", "LIMIT");
parameters.put("timeInForce", "GTC");
parameters.put("quantity", 0.01);
parameters.put("price", 9500);The Binance API server provides weight usages in the headers of each response. This value can be return by
calling setShowLimitUsage and setting it to true.
SpotClientImpl client = new SpotClientImpl();
client.setShowLimitUsage(true);
String result = client.createMarket().time();
logger.info(result);output:
INFO: {"data":"{"serverTime":1633434339494}","x-mbx-used-weight":"1","x-mbx-used-weight-1m":"1"}
ch.qos.logback is used for logging in this connector. The configuration xml file can be found under
src/main/resources.
There are 3 types of error which may be thrown by this library.
BinanceConnectorException- This is thrown when there is a validation error for parameters.For instance, mandatory parameter not sent. This error will be thrown before the request is sent to the server.
BinanceClientException- This is thrown when server returns
4XX, it's an issue from client side. - The error consists of these 3 objects which will help in debugging the error:
httpStatusCode- HTTP status codeerrorCode- API Server's error code, e.g.-1102errMsg- API Server's error message, e.g.Unknown order sent.
- This is thrown when server returns
BinanceServerException- This is thrown when server returns
5XX, it's an issue from server side.
- This is thrown when server returns
try {
String result = client.createTrade().newOrder(parameters);
logger.info(result);
} catch (BinanceConnectorException e) {
logger.error("fullErrMessage: {}", e.getMessage(), e);
} catch (BinanceClientException e) {
logger.error("fullErrMessage: {} \nerrMessage: {} \nerrCode: {} \nHTTPStatusCode: {}",
e.getMessage(), e.getErrMsg(), e.getErrorCode(), e.getHttpStatusCode(), e);
}WebsocketClientImpl client = new WebsocketClientImpl(); // defaults to production environment unless stated,
int streamID1 = client.aggTradeStream("btcusdt",((event) -> {
System.out.println(event);
}));
//Combining Streams
ArrayList<String> streams = new ArrayList<>();
streams.add("btcusdt@trade");
streams.add("bnbusdt@trade");
int streamID2 = client.combineStreams(streams, ((event) -> {
System.out.println(event);
}));
//Listening to User Data Stream
int streamID3 = client.listenUserStream(listenKey, ((event) -> {
System.out.println(event);
}));
//Closing a single stream
client.closeConnection(streamID1); //closes aggTradeStream-btcusdt
//Closing all streams
client.closeAllConnections();More websocket examples are available in the test/examples folder
mvn clean test
Contributions are welcome.
If you've found a bug within this project, please open an issue to discuss what you would like to change.
If it's an issue with the API, please open a topic at Binance Developer Community