This is a lightweight library that works as a connector to the Binance public API.
It supports the following APIs:
/api/*endpoints;/sapi/*endpoints;- Spot WebSocket Market Stream;
- Spot User Data Stream;
- Spot WebSocket API;
Additionally, it includes test cases and examples.
https://www.javadoc.io/doc/io.github.binance/binance-connector-java/latest/index.html
Copy and paste the following dependency snippet into your pom.xml file, replacing `LATEST_VERSION`` with the most recent version available:
<dependency>
<groupId>io.github.binance</groupId>
<artifactId>binance-connector-java</artifactId>
<version>LATEST_VERSION</version>
</dependency>
Next, install the dependency by executing mvn install in the directory where your pom.xml is located.
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.
SpotClient client = new SpotClientImpl();
Map<String, Object> parameters = new LinkedHashMap<>();
String result = client.createMarket().exchangeInfo(parameters);SpotClient client = new SpotClientImpl(PrivateConfig.API_KEY, PrivateConfig.SECRET_KEY);
Map<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);
String result = client.createTrade().testNewOrder(parameters);WebSocketStreamClient wsStreamClient = new WebSocketStreamClientImpl(); // defaults to live exchange unless stated.
// Single stream
int streamID1 = wsStreamClient.aggTradeStream("btcusdt",((event) -> {
System.out.println(event);
}));
// Combined streams
ArrayList<String> streams = new ArrayList<>();
streams.add("btcusdt@trade");
streams.add("bnbusdt@trade");
int streamID2 = wsStreamClient.combineStreams(streams, ((event) -> {
System.out.println(event);
}));
// Close single stream
wsStreamClient.closeConnection(streamID1); //closes aggTradeStream-btcusdt
// Close all streams
wsStreamClient.closeAllConnections();Different types of WebSocket callbacks are available. Please refer to the src/test/java/examples/websocketstream/TradeStreamWithAllCallbacks.java example file to explore their usage.
RsaSignatureGenerator signatureGenerator = new RsaSignatureGenerator("PRIVATE_KEY_PATH");
WebSocketApiClient wsApiClient = new WebSocketApiClientImpl("API_KEY", signatureGenerator); // defaults to live exchange unless stated
// Open connection with a callback as parameter
wsApiClient.connect(((message) -> {
System.out.println(message);
}));
JSONObject optionalParams = new JSONObject();
optionalParams.put("requestId", "request123");
optionalParams.put("quantity", 1);
wsApiClient.trade().testNewOrder("BTCUSDT", "BUY", "MARKET", optionalParams);
Thread.sleep(60000);
// Close connection
wsApiClient.close();If requestId is empty (""), null or not sent, this library will generate a UUID string for it.
Different types of WebSocket callbacks are available. Please refer to the src/test/java/examples/websocketapi/WsApiwithAllCallbacks.java example file to explore their usage.
While /sapi/* endpoints do not yet have a testnet environment, /api/* endpoints can be tested on the Spot Testnet.
You can use it by changing the base URL:
Map<String,Object> parameters = new LinkedHashMap<>();
SpotClient 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:
https://api1.binance.comhttps://api2.binance.comhttps://api3.binance.comhttps://api4.binance.com
Parameters can be set in any implementation of Map<String, Object> interface, where String represents the parameter name and Object the parameter value. These parameters should have the same naming as in the API doc."
Map<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, which can be returned if you set setShowLimitUsage(true).
SpotClient 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"}
To set HTTP Proxy, call setProxy() with ProxyAuth and before submitting requests:
SpotClient client = new SpotClientImpl();
Proxy proxyConn = new Proxy(Proxy.Type.HTTP, new InetSocketAddress("127.0.0.1", 8080));
ProxyAuth proxy = new ProxyAuth(proxyConn, null);
client.setProxy(proxy);
logger.info(client.createMarket().time());For authenticated Proxy, define ProxyAuth with Authenticator from okhttp3:
SpotClient client = new SpotClientImpl();
Proxy proxyConn = new Proxy(Proxy.Type.HTTP, new InetSocketAddress("127.0.0.1", 8080));
Authenticator auth = new Authenticator() {
public Request authenticate(Route route, Response response) throws IOException {
if (response.request().header("Proxy-Authorization") != null) {
return null; // Give up, we've already failed to authenticate.
}
String credential = Credentials.basic("username", "password");
return response.request().newBuilder().header("Proxy-Authorization", credential).build();
}
};
ProxyAuth proxy = new ProxyAuth(proxyConn, auth);
client.setProxy(proxy);
logger.info(client.createMarket().time());To undo Proxy, use unsetProxy() before submitting requests:
client.unsetProxy();
logger.info(client.createMarket().time());Complete examples are available at src/test/java/examples/spot/proxy folder.
This connector uses SLF4J as an abstraction layer for diverse logging frameworks.
It's end-user's responsibility to select the appropriate SLF4J binding to use as the logger (e.g, slf4j-jdk14 or logback-classic).
Otherwise, you might see the following informative output:
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.In case you want to use our custom logback-classic, it's available at binance-logback.
If you prefer to not use a logger and suppress the SLF4J messages instead, you can refer to slf4j-nop.
When creating SpotClient, WebSocketStreamClient or WebSocketApiClient, you use one of the following types of Signature Generator to create signatures (for SIGNED endpoints) based on your security preference:
HmacSignatureGenerator- Use of API Key and Secret Key.
HmacSignatureGenerator signGenerator = new HmacSignatureGenerator("SecretKey");
SpotClient client = new SpotClientImpl("ApiKey", signGenerator);RsaSignatureGenerator- Use of API Key and RSA algorithm keys.
RsaSignatureGenerator signGenerator = new RsaSignatureGenerator("PathToPrivateKey");
// or if Private Key is protected
// RsaSignatureGenerator signGenerator = new RsaSignatureGenerator("PathToPrivateKey", "PrivateKeyPassword")
SpotClient client = new SpotClientImpl("ApiKey", signGenerator);Ed25519SignatureGenerator- Use of API Key and Ed25519 algorithm keys.
Ed25519SignatureGenerator signGenerator = new Ed25519SignatureGenerator("PathToPrivateKey");
SpotClient client = new SpotClientImpl("ApiKey", signGenerator);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);
}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 itself, you can submit on the Binance Developer Community
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent