Java Binance Unofficial API Client
This library is designed to help you make your own projects that interact with the Binance API. This project seeks to have complete API coverage including User Data Streams and WebSockets for Binance Cryptocurrency Exchange
If you are seeking for a version with Android 4+ support, please take a look at https://github.com/shufps/java-binance-api
Getting Started
with Maven
Add the following Maven dependency to your project's pom.xml:
<dependency>
<groupId>com.webcerebrium</groupId>
<artifactId>binance-api</artifactId>
<version>1.0.9</version>
</dependency>
with Gradle
compile group: 'com.webcerebrium', name: 'binance-api', version: '1.0.9'
with Grapes
@Grapes([
@Grab(group = 'com.webcerebrium', module = 'binance-api', version = '1.0.9')
])
with latest source code
After git clone, please run gradle jar, which will result in having jar under build/distribution folder.
compilation you will have jar in your folder, which could be included as your dependency like this:
dependencies {
compile files('libs/binance-api-1.0.9.jar')
}
Example of Application
import com.webcerebrium.binance.api.BinanceApi;
import com.webcerebrium.binance.api.BinanceApiException;
try {
BinanceApi api = new BinanceApi();
System.out.println("ETH-BTC PRICE=" + api.pricesMap().get("ETHBTC"));
} catch (BinanceApiException e) {
System.out.println( "ERROR: " + e.getMessage());
}
Setting up API KEYS
For API keys you can set an environment variables or java Virtual Machine properties BINANCE_API_KEY, BINANCE_SECRET_KEY,
as well as setting up these variables in application.properties resource file of your project
Logging
Logging configuration can be corrected in logback.xml files.
To suppress requests/response logging, you might want to increase logging level for BinanceRequest component:
<logger name="com.webcerebrium.binance.api.BinanceRequest" level="WARN" />
Debugging Library from Source
If you cloned this GITHUB repository, the following tips might be useful:
Running tests
If you cloned this repository, tests with API coverage could be launched with gradle test. Before running, make sure API keys are set as described above.
For successful trading tests passing, it is desired to have some BTC, ETH and BNB on your account.
Running in Eclipse
This project uses Lombok. You will need to install lombok for Eclipse to make the project compile in Eclipse. It will compile via gradle just fine without this additional installation step.
Running in Intellij IDEA
This project uses Lombok. You will need to install corresponding plugin and enable Annotation processing in your Compiler settings. It will compile via gradle just fine without this additional installation step.
To start, import current directory as Gradle project.
Using API - General Endpoints
Checking Server Responsiveness
System.out.println((new BinanceApi()).ping() );View Output
{}Getting Server Time
System.out.println((new BinanceApi()).time().get("serverTime").getAsString());View Output
1508364584572
Using API - Getting Account Information
Getting Account Information
JsonObject account = (new BinanceApi()).account();
System.out.println("Maker Commission: " + account.get("makerCommission").getAsBigDecimal());
System.out.println("Taker Commission: " + account.get("takerCommission").getAsBigDecimal());
System.out.println("Buyer Commission: " + account.get("buyerCommission").getAsBigDecimal());
System.out.println("Seller Commission: " + account.get("sellerCommission").getAsBigDecimal());
System.out.println("Can Trade: " + account.get("canTrade").getAsBoolean());
System.out.println("Can Withdraw: " + account.get("canWithdraw").getAsBoolean());
System.out.println("Can Deposit: " + account.get("canDeposit").getAsBoolean());View Output
Maker Commission: 10 Taker Commission: 10 Buyer Commission: 0 Seller Commission: 0 Can Trade: true Can Withdraw: true Can Deposit: true
Getting All Balances
System.out.println((new BinanceApi()).balances());View Output
[{"asset":"BTC","free":"0.00001161","locked":"0.00000000"},{"asset":"LTC","free":"0.00000000","locked":"0.00000000"},...,{"asset":"ZEC","free":"0.00000000","locked":"0.00000000"}]
Getting Asset Balance
System.out.println((new BinanceApi()).balancesMap().get("ETH"));View Output
BinanceWalletAsset(asset=ETH, free=0.00859005, locked=0E-8)
Getting Open Orders
System.out.println((new BinanceApi()).openOrders(BinanceSymbol.valueOf("ETHBTC")));View Output
[BinanceOrder(symbol=ETHBTC, orderId=11111, clientOrderId=hNch6HItMQp2m9VuQZaA6L, price=0.18200000, origQty=1.00000000, executedQty=0E-8, status=NEW, timeInForce=GTC, type=LIMIT, side=SELL, stopPrice=0E-8, icebergQty=0E-8, time=1508361363677)]
Checking Order Status
BinanceApi api = new BinanceApi();
BinanceSymbol symbol = BinanceSymbol.valueOf("ETHBTC");
System.out.println(api.getOrderById(symbol, 333821L));
System.out.println(api.getOrderByOrigClientId(symbol, "2m9VuQZaA6LhNch6HItMQp"));View Output
BinanceOrder(symbol=ETHBTC, orderId=333821, clientOrderId=2m9VuQZaA6LhNch6HItMQp, price=0.18200000, origQty=1.00000000, executedQty=0E-8, status=NEW, timeInForce=GTC, type=LIMIT, side=SELL, stopPrice=0E-8, icebergQty=0E-8, time=1508361363677)
Getting All Orders
System.out.println((new BinanceApi()).allOrders(BinanceSymbol.valueOf("BQXBTC")));View Output
[BinanceOrder(symbol=BQXBTC, orderId=11111, clientOrderId=D0qeCsEBxKaXSRwxKUZkBZ, price=0.00018602, origQty=309.00000000, executedQty=309.00000000, status=FILLED, timeInForce=GTC, type=LIMIT, side=BUY, stopPrice=0E-8, icebergQty=0E-8, time=1506498038089), ... , BinanceOrder(symbol=BQXBTC, orderId=222222, clientOrderId=p2m9VuQZaA6LhNch6HItMQ, price=0.18200000, origQty=1.00000000, executedQty=0E-8, status=NEW, timeInForce=GTC, type=LIMIT, side=SELL, stopPrice=0E-8, icebergQty=0E-8, time=1508361363677)]
Getting My Trades
System.out.println((new BinanceApi()).myTrades(BinanceSymbol.valueOf("BQXBTC")));View Output
[BinanceTrade(id=1321, commissionAsset=BQX, price=0.00018602, qty=38.00000000, commission=0.03800000, time=1506499148055, isBuyer=true, isMaker=true, isBestMatch=true), ... , BinanceTrade(id=6315, commissionAsset=BNB, price=0.00015216, qty=449.00000000, commission=0.10018983, time=1507144715249, isBuyer=true, isMaker=true, isBestMatch=true)]
Withdrawals
String address = "0x1234567890123456789012345678901234567890";
System.out.println((new BinanceApi()).withdraw("ETH", 0.01, address, ""));Getting All Deposits History
Server side team still works on this endpoint. At the moment of writing that you will just receive a message in Chinese about parameters exception.
BinanceHistoryFilter historyFilter = new BinanceHistoryFilter();
System.out.println((new BinanceApi()).getDepositHistory(historyFilter));Getting Withdrawal History
Server side team still works on this endpoint. At the moment of writing that you will just receive a message in Chinese about parameters exception.
BinanceHistoryFilter historyFilter = new BinanceHistoryFilter("ETH");
Calendar cal = Calendar.getInstance();
cal.add(Calendar.MONTH, -3); // only last 3 months
historyFilter.setStartTime(cal.getTime());
System.out.println((new BinanceApi()).getWithdrawHistory(historyFilter));Using API - Getting Market Data
Getting Bids and Asks on Symbol
BinanceSymbol symbol = BinanceSymbol.valueOf("ETHBTC");
JsonObject depth = (new BinanceApi()).depth(symbol);
System.out.println("BIDS=" + depth.get("bids").getAsJsonArray());
System.out.println("ASKS=" + depth.get("asks").getAsJsonArray());View Output
``` BIDS=[["0.05577600","2.30000000",[]],["0.05577500","1.10000000",[]],["0.05577400","2.10000000",[]],...,["0.00000100","21000.00000000",[]]] ASKS=[["0.05590600","10.90900000",[]],["0.05590700","9.96000000",[]],["0.05590800","9.44200000",[]],...,["0.06102400","0.50000000",[]]] ```
Getting latest prices - as list of JsonObjects
System.out.println((new BinanceApi()).prices());View Output
[{"symbol":"ETHBTC","price":"0.05602000"},{"symbol":"LTCBTC","price":"0.01107300"},{"symbol":"BNBBTC","price":"0.00023561"},...,{"symbol":"BNTBTC","price":"0.00038649"}]
Getting latest prices - as map of decimals
System.out.println((new BinanceApi()).pricesMap());View Output
{ZECETH=0E-8, SALTETH=0.00940300, WTCETH=0.02207900, NEOETH=0.09463500, ... , MTHETH=0.00028000, FUNETH=0.00007538}
Getting latest price of a symbol
System.out.println((new BinanceApi()).pricesMap().get("ETHBTC"));View Output
0.05628800
Getting Aggregated Trades
BinanceSymbol symbol = new BinanceSymbol("ETHBTC");
List<BinanceAggregatedTrades> binanceAggregatedTrades = (new BinanceApi()).aggTrades(symbol, 5, null);
BinanceAggregatedTrades trade = binanceAggregatedTrades.get(0);
System.out.println("TRADE=" + trade.toString() );View Output
TRADE=BinanceAggregatedTrades{tradeId=2084592, price=0.05476100, quantity=6.87000000, firstTradeId=2192143, lastTradeId=2192143, timestamp=1508393572350, maker=true, bestPrice=true}
Getting All Book Tickers
System.out.println((new BinanceApi()).allBookTickers());View Output
[{"symbol":"ETHBTC","bidPrice":"0.05461000","bidQty":"29.73000000","askPrice":"0.05486300","askQty":"19.96000000"}, ... ,{"symbol":"ASTETH","bidPrice":"0.00102010","bidQty":"4030.00000000","askPrice":"0.00102920","askQty":"187.00000000"}]
Getting All Available Symbols
System.out.println((new BinanceApi()).allBookTickersMap().keySet());View Output
[ZECETH, SALTETH, WTCETH, NEOETH, IOTABTC, CTRBTC, SNMBTC, LRCETH, ... , MTLETH, SALTBTC, SUBBTC, MTHETH, FUNETH]
Getting 24hr Tickers for Symbol
BinanceSymbol symbol = BinanceSymbol.valueOf("ETHBTC");
System.out.println((new BinanceApi()).ticker24hr(symbol));View Output
{"priceChange":"-0.00180600","priceChangePercent":"-3.195","weightedAvgPrice":"0.05619267","prevClosePrice":"0.05652600","lastPrice":"0.05472000","lastQty":"0.26100000","bidPrice":"0.05472000","bidQty":"26.53900000","askPrice":"0.05486100","askQty":"0.53100000","openPrice":"0.05652600","highPrice":"0.05734100","lowPrice":"0.05460000","volume":"28260.45000000","quoteVolume":"1588.03005689","openTime":1508308200417,"closeTime":1508394600417,"firstId":2167326,"lastId":2192389,"count":25063}
Getting Klines / Candlesticks
BinanceSymbol symbol = new BinanceSymbol("ETHBTC");
List<BinanceCandlestick> klines = (new BinanceApi()).klines(symbol, BinanceInterval.ONE_HOUR, 5, null);
BinanceCandlestick binanceCandlestick = klines.get(0);
System.out.println("KLINE=" + binanceCandlestick.toString() );View Output
KLINE=BinanceCandlestick(openTime=1508378400000, open=0.05598000, high=0.05622000, low=0.05569100, close=0.05570500, volume=1514.33900000, closeTime=1508381999999, quoteAssetVolume=84.65979632, numberOfTrades=1683, takerBuyBaseAssetVolume=716.56500000, takerBuyQuoteAssetVolume=40.07877823)
Getting Exchange Market Information (Lot Sizes)
BinanceExchangeInfo binanceExchangeInfo = binanceApi.exchangeInfo();
List<BinanceExchangeSymbol> symbols = binanceExchangeInfo.getSymbols();
BinanceExchangeSymbol BNB = symbols.stream().filter(a -> a.getQuoteAsset().equals("BNB")).findFirst().get();View Output
BNB Lot Size: {"filterType":"LOT_SIZE","minQty":"0.01000000","maxQty":"10000000.00000000","stepSize":"0.01000000"}
Using API - Placing Orders
Placing a LIMIT order
BinanceApi api = new BinanceApi();
BinanceSymbol symbol = new BinanceSymbol("ETHBTC");
BinanceOrderPlacement placement = new BinanceOrderPlacement(symbol, BinanceOrderSide.BUY);
placement.setType(BinanceOrderType.LIMIT);
placement.setPrice(BigDecimal.valueOf(0.00001));
placement.setQuantity(BigDecimal.valueOf(10000)); // buy 10000 of asset for 0.00001 BTC
BinanceOrder order = api.getOrderById(symbol, api.createOrder(placement).get("orderId").getAsLong());
System.out.println(order.toString());Placing a MARKET order
BinanceApi api = new BinanceApi();
BinanceSymbol symbol = new BinanceSymbol("ETHBTC");
BinanceOrderPlacement placement = new BinanceOrderPlacement(symbol, BinanceOrderSide.BUY);
placement.setType(BinanceOrderType.MARKET);
placement.setPrice(BigDecimal.valueOf(0.00001));
placement.setQuantity(BigDecimal.valueOf(10000)); // buy 10000 of asset for 0.00001 BTC
BinanceOrder order = api.getOrderById(symbol, api.createOrder(placement).get("orderId").getAsLong());
System.out.println(order.toString());Placing a STOP LOSS order
BinanceApi api = new BinanceApi();
BinanceSymbol symbol = new BinanceSymbol("ETHBTC");
BinanceOrderPlacement placement = new BinanceOrderPlacement(symbol, BinanceOrderSide.SELL);
placement.setPrice(BigDecimal.valueOf(0.069));
placement.setStopPrice(BigDecimal.valueOf(0.068));
placement.setQuantity(BigDecimal.valueOf(1)); // sell 1 piece of asset
BinanceOrder order = api.getOrderById(symbol, api.createOrder(placement).get("orderId").getAsLong());
System.out.println(order.toString());Placing an ICEBERG order
BinanceApi api = new BinanceApi();
BinanceSymbol symbol = new BinanceSymbol("ETHBTC");
BinanceOrderPlacement placement = new BinanceOrderPlacement(symbol, BinanceOrderSide.SELL);
placement.setPrice(BigDecimal.valueOf(0.069));
placement.setQuantity(BigDecimal.valueOf(1)); // sell 1 piece of asset
placement.setIcebergQty(BigDecimal.valueOf(10));
BinanceOrder order = api.getOrderById(symbol, api.createOrder(placement).get("orderId").getAsLong());
System.out.println(order.toString());Cancel/Delete an order
BinanceOrder order = api.getOrderById(symbol, 123456L);
System.out.println(api.deleteOrder(order));View Output
{}
Using API - Using User Data Streams
Start User Data Stream
String listenKey = (new BinanceApi()).startUserDataStream();
System.out.println(listenKey);View Output
pqia91ma19a5s61cv6a81va65sdf19v8a65a1a5s61cv6a81va65sdf19v8a65a1
Keep User Data Stream Alive
String listenKey = "pqia91ma19a5s61cv6a81va65sdf19v8a65a1a5s61cv6a81va65sdf19v8a65a1";
(new BinanceApi()).keepUserDataStream(listenKey);View Output
{}
Close User Data Stream
String listenKey = "pqia91ma19a5s61cv6a81va65sdf19v8a65a1a5s61cv6a81va65sdf19v8a65a1";
(new BinanceApi()).deleteUserDataStream(listenKey);View Output
{}
Using API - Connecting to Web Sockets
Depth Web Socket Listener
BinanceSymbol symbol = new BinanceSymbol("ETHBTC");
Session session = (new BinanceApi()).websocketDepth(symbol, new BinanceWebSocketAdapterDepth() {
@Override
public void onMessage(BinanceEventDepthUpdate message) {
System.out.println(message.toString());
}
});
try { Thread.sleep(5000); } catch (InterruptedException e) {}
session.close();View Output
BinanceEventDepthUpdate(eventTime=1508411905630, symbol=ETHBTC, updateId=17379538, bids=[BinanceBidOrAsk(type=BID, price=0.05356100, quantity=0E-8), BinanceBidOrAsk(type=BID, price=0.05355800, quantity=0E-8)], asks=[BinanceBidOrAsk(type=ASK, price=0.05386000, quantity=0.62900000), BinanceBidOrAsk(type=ASK, price=0.05401300, quantity=0E-8), BinanceBidOrAsk(type=ASK, price=0.05401600, quantity=1.50000000)]) BinanceEventDepthUpdate(eventTime=1508411906630, symbol=ETHBTC, updateId=17379544, bids=[BinanceBidOrAsk(type=BID, price=0.05356200, quantity=0E-8), BinanceBidOrAsk(type=BID, price=0.05354900, quantity=15.00000000), BinanceBidOrAsk(type=BID, price=0.05069700, quantity=0E-8), BinanceBidOrAsk(type=BID, price=0.05066500, quantity=15.60000000)], asks=[BinanceBidOrAsk(type=ASK, price=0.05400600, quantity=1.50000000), BinanceBidOrAsk(type=ASK, price=0.05401600, quantity=0E-8)]) BinanceEventDepthUpdate(eventTime=1508411907630, symbol=ETHBTC, updateId=17379545, bids=[BinanceBidOrAsk(type=BID, price=0.05356500, quantity=10.00000000)], asks=[])
Klines Web Socket Listener
BinanceSymbol symbol = new BinanceSymbol("ETHBTC");
BinanceInterval interval = BinanceInterval.FIVE_MIN;
Session session = (new BinanceApi()).websocketKlines(symbol, interval, new BinanceWebSocketAdapterKline() {
@Override
public void onMessage(BinanceEventKline message) {
System.out.println(message.toString());
}
});
try { Thread.sleep(15000); } catch (InterruptedException e) {}
session.close();View Output
BinanceEventKline(eventTime=1508416507504, symbol=ETHBTC, interval=1m, startTime=1508416500000, endTime=1508416559999, firstTradeId=-1, lastTradeId=-1, open=0.05393800, close=0.05393800, high=0.05393800, low=0.05393800, volume=0E-8, numberOfTrades=0, isFinal=false, quoteVolume=0E-8, volumeOfActiveBuy=0E-8, quoteVolumeOfActiveBuy=0E-8)
Trades Web Socket Listener
BinanceSymbol symbol = new BinanceSymbol("ETHBTC");
Session session = (new BinanceApi()).websocketTrades(symbol, new BinanceWebSocketAdapterAggTrades() {
@Override
public void onMessage(BinanceEventAggTrade message) {
System.out.println(message.toString());
}
});
try { Thread.sleep(8000); } catch (InterruptedException e) {}
session.close();View Output
BinanceEventAggTrade(eventTime=1508412260766, symbol=ETHBTC, aggregatedTradeId=2089883, price=0.05369800, quantity=3.68000000, firstBreakdownTradeId=2197559, lastBreakdownTradeId=2197559, tradeTime=1508412260762, isMaker=false) BinanceEventAggTrade(eventTime=1508412260835, symbol=ETHBTC, aggregatedTradeId=2089884, price=0.05369800, quantity=1.00000000, firstBreakdownTradeId=2197560, lastBreakdownTradeId=2197560, tradeTime=1508412260832, isMaker=false)
User Data Web Socket Listener
BinanceApi api = new BinanceApi();
String listenKey = api.startUserDataStream();
Session session = api.websocket(listenKey, new BinanceWebSocketAdapterUserData() {
@Override
public void onOutboundAccountInfo(BinanceEventOutboundAccountInfo message) {
System.out.println(message.toString());
}
@Override
public void onExecutionReport(BinanceEventExecutionReport message) {
System.out.println(message.toString());
}
});
Thread.sleep(5000);
session.close();
api.deleteUserDataStream(listenKey);Contribution
This is an API that is not officially supported. So contributions in any form, especially pull requests are always welcome. If you like what we do, and want to support our development of distributed future, you can also send tips:
GAS: AKXysWVLmB2J5qxGPJLFBPducj5cNMYKLo
ETH: 0x95E972Ff1A4CB6112cb08FE7DE81542DF9b8a0F4
License
MIT. Anyone can copy, change, derive further work from this repository without any restrictions.