Huobi Java SDK (beta version)

This is Huobi Java SDK, This is a lightweight Java library, you can import to your Java project and use this SDK to query all market data, trading and manage your account.

The SDK supports both synchronous and asynchronous RESTful API invoking, and subscribe the market data from the Websocket connection.

Table of Contents

• Beginning

  • Installation
  • Quick Start
  • Request vs. Subscription
  • Clients
  • Create client
  • Custom host

• Usage

  • Synchronous
  • Asynchronous
  • Subscription
  • Errir handling

• Request example

  • Reference data
    • Exchange timestamp
    • Symbol and currencies
  • Market data
    • Candlestick/KLine
    • Depth
    • Latest trade
    • Best bid/ask
    • Historical
    • 24H Statistics
  • Account
  • Wallet
    • Withdraw
    • Cancel withdraw
    • Withdraw and deposit history
  • Trading
    • Create order
    • Cancel order
    • Cancel open orders
    • Get order info
    • Historical orders
  • Margin Loan
    • Apply loan
    • Reply loan
    • Loan history

• Subscription example

  • Subscribe trade update
  • Subscribe candlestick/KLine update
  • Subscribe order update
  • Subscribe account change
  • Unsubscribe

Beginning

Installation

The SDK is compiled by Java8

For Beta version, please import the source code in java IDE (idea or eclipse)

The example code is in huobi-api-sdk/java/src/test/java/com/huobi/client/examples.

Quick Start

In your Java project, you can follow below steps:

• Create the client instance.
• Call the interfaces provided by client.

SyncRequestClient syncClient = SyncRequestClient.create();

// Get the timestamp from Huobi server and print on console
long timestamp = syncClient.getExchangeTimestamp();
System.out.println(timestamp);

// Get the latest btcusdt‘s candlestick data and print the highest price on console
List<Candlestick> candlestickList =
    syncClient.getLatestCandlestick("btcusdt", CandlestickInterval.DAY1, 20);
for (Candlestick item : candlestickList) {
    System.out.println(item.getHigh());
}

Please NOTE:

All timestamp which is got from SDK is the Unix timestamp based on UTC.

Request vs. Subscription

Huobi API supports 2 types of invoking.

1. Request method: You can use request method to trade, withdraw and loan. You can also use it to get the market related data from Huobi server.
2. Subscription method: You can subscribe the market updated data and account change from Huobi server. For example, if you subscribed the price depth update, you will receive the price depth message when the price depth updates on Huobi server.

We recommend developers to use request method to trade, withdraw and loan, to use subscription method to access the market related data.

Clients

There are 2 clients for request method, SyncRequestClient and AsyncRequestClient. One client for subscription method, SubscriptionClient.

• SyncRequestClient: It is a synchronous request, it will invoke the Huobi API via synchronous method, all invoking will be blocked until receiving the response from server.

• AsyncRequestClient: It is an asynchronous request, it will invoke the Huobi API via asynchronous method, all invoking will return immediately, instead of waiting the server's response. So you must implement the onResponse() method inRequestCallback interface. As long as receiving the response of the server, callback method you defined will be called. You can use the lambda expression to simplify the implementation, see Asynchronous usage for detail.

• SubscriptionClient: It is the subscription, it is used for subscribing any market data update and account change. It is asynchronous, so you must implement onUpdate() method in SubscriptionListener interface. The server will push any update for the client. if client receive the update, the onUpdate() method will be called. You can use the lambda expression to simplify the implementation, see Subscription usage for detail.

Create client

You can assign the API key and Secret key when you create the client. See below:

SyncRequestClient syncClient = SyncRequestClient.create(
  "xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxx",
  "xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxx");

AsyncRequestClient asyncClient = AsyncRequestClient.create(
  "xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxx",
  "xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxx");

SubscriptionClient subscriptionClient = SubscriptionClient.create(
  "xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxx",
  "xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxx");

The API key and Secret key are used for authentication.

Some APIs related with account, trading, deposit and withdraw etc require the authentication. We can name them after private interface.

The APIs only return the market data that don't need the authentication. We can name them after public interface.

If you want to invoke both public interface and private interface. You must apply API Key and Secret Key from Huobi and put them into the client you created.

If the authentication cannot pass, the invoking of private interface will fail.

If you want to invoke public interface only. You can create the client as follow:

SyncRequestClient syncClient = SyncRequestClient.create();

AsyncRequestClient asyncClient = AsyncRequestClient.create();

SubscriptionClient subscriptionClient = SubscriptionClient.create();

Custom host

To support huobi cloud, you can specify the custom host.

1. Set your custom host to RequestOptions or SubscriptionOptions.
2. Set the options to client when creating the client instance.

See below example

// Set custom host for request
RequestOptions options = new RequestOptions();
options.setUrl("https://www.xxx.yyy/");

SyncRequestClient syncClient = SyncRequestClient.create(
  "xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxx",
  "xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxx",
  options);
AsyncRequestClient asyncClient = AsyncRequestClient.create(
  "xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxx",
  "xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxx",
  options);

// Set custom host for subscription
SubscriptionOptions options = new SubscriptionOptions();
options.setUri("wss://www.xxx.yyy");

SubscriptionClient subscriptionClient = SubscriptionClient.create(
  "xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxx",
  "xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxx",
  options);

If you do not set yout custom host, below default host will be used:

For request: https://api.huobi.pro

For subscription: wss://api.huobi.pro

Usage

Synchronous

To invoke the interface by synchronous, you can create the SyncRequestClient by calling SyncRequestClient.create(), and call the API directly.

SyncRequestClient syncClient = SyncRequestClient.create();
// Get the best bid and ask for btcusdt, print the best ask price and amount on console.
BestQuote bestQuote = client.getBestQuote("btcusdt");
System.out.println(bestQuote.getAskPrice());
System.out.println(bestQuote.getAskAmount());

Asynchronous

To invoke the interface by asynchronous, you can create the AsyncRequestClient by calling AsyncRequestClient.create(), and call the API which implement the callback by yourself. You will get a resultset after the asynchronous invoking completed, call succeeded() to check whether the invoking succeeded or not, then call getData() to get the server's response data.

AsyncRequestClient asyncClient = AsyncRequestClient.create();
// Get the price depth for btcusdt, print bid price and ask price in first level.
asyncClient.getPriceDepth("btcusdt", 5, (priceDepthResult) -> {
    if (priceDepthResult.succeeded() {
      System.out.println(priceDepthResult.getData().getBids().get(0).getPrice());
      System.out.println(priceDepthResult.getData().getAsks().get(0).getPrice());
    }
});

Subscription

To receive the subscribed data, you can create the SubscriptionClient by calling SubscriptionClient.create(). When subscribing the event, you should define your listener. See below example:

SubscriptionClient subscriptionClient = HuobiClientFactory.createSubscriptionClient();
// Subscribe the trade update for btcusdt.
subscriptionClient.subscribeTradeEvent("btcusdt", (tradeEvent) -> {
  System.out.println(event.getSymbol());
  for (Trade trade : tradeEvent.getTradeData()) {
    System.out.println(trade.getPrice());
  }
});

The subscription method supports multi-symbol string. Each symbol should be separated by a comma.

subscriptionClient.subscribeTradeEvent("btcusdt,ethusdt", (tradeEvent) -> {
  ......
});

Error handling

For synchronous

In error case, such as you set the invalid symbol to getBestQuote(). The HuobiApiException will be thrown. See below example:

try {
  SyncRequestClient syncClient = service.createSyncRequestClient();
  // Set the invaild symbol
  BestQuote bestQuote = client.getBestQuote("abcdefg");
  System.out.println(bestQuote.getAskPrice());
  System.out.println(bestQuote.getAskAmount());
} catch (HuobiApiException e) {
  System.err.println(e.getErrorCode());
  System.err.println(e.getMessage());
}

For asynchronous

If the invoking failed, you can get the HuobiApiException in the resultset. See below example:

asyncClient.getPriceDepth("btcusdt", 5, (priceDepthResult) -> {
  if (priceDepthResult.succeeded() {
    System.out.println(priceDepthResult.getData().getBids().get(0).getPrice());
    System.out.println(priceDepthResult.getData().getAsks().get(0).getPrice());
  } else {
    System.err.println(e.getErrorCode());
    System.err.println(e.getMessage());
  }  
});

For Subscription

If you want to check the error, you should implement your SubscriptionErrorHandler. See below example:

subscriptionClient.subscribeTradeEvent("btcusdt",
    (tradeEvent) -> {
      System.out.println(event.getSymbol());
      for (Trade trade : tradeEvent.getTradeData()) {
        System.out.println(trade.getPrice());
      }
    },
    (e) -> {
      System.err.println(e.getErrorCode());
      System.err.println(e.getMessage());
    }
});

Any error made during subscription will be output to a log file, If you do not define your SubscriptionErrorHandler, the error will be output to log file only.

Request example

Reference data

Exchange timestamp

//Synchronous
long timestamp = syncClient.getExchangeTimestamp();
System.out.println(timestamp);

//Asynchronous
asyncClient.getExchangeTimestamp((timestampResult) -> {
  if (timestampResult.succeeded()) {
    System.out.println(timestampResult.getData())
  }  
});

Symbol and currencies

//Synchronous
ExchangeInfo info = syncClient.getExchangeInfo();
for (String currency : info.getCurrencies()) {
  System.out.println(currency);
}

//Asynchronous
asyncClient.getExchangeInfo((result) -> {
  if (result.succeeded()) {
    for (String currency : result.getData().getCurrencies()) {
      System.out.println(currency);
    }   
  }
});

Market data

Candlestick/KLine

//Synchronous
List<Candlestick> candlestickList = syncClient.getLatestCandlestick(
  "btcusdt", CandlestickInterval.DAY1, 20);
for (Candlestick candlestick : candlestickList) {
  System.out.println(candlestick.getHigh());
}

//Asynchronous
asyncClient.getCandlestick("btcusdt", CandlestickInterval.DAY1, 20, (candlestickResult) -> 
{
  if (candlestickResult.succeeded()) {
    for (Candlestick candlestick : candlestickResult.getData()) {
      System.out.println(candlestick.getHigh());
    }
  }
});

Depth

//Synchronous
PriceDepth depth = syncClient.getPriceDepth("btcusdt", 5);
for (DepthEntry entry : depth.getBids()) {
    System.out.println(entry.getPrice());
}

//Asynchronous
asyncClient.getPriceDepth("btcusdt", 5, (depthResult) -> {
    for (DepthEntry entry : depthResult.getData().getBids()) {
        System.out.println(entry.getPrice());
    }
}

Latest trade

//Synchronous
Trade trade = syncClient.getLastTrade("btcusdt");
System.out.println(trade.getPrice());

//Asynchronous
asyncClient.getLastTrade("btcusdt", (tradeResult) -> {
  if (tradeResult.succeeded()) {
    System.out.println(tradeResult.getData().getPrice());
  }
});

Best bid/ask

//Synchronous
BestQuote bestQuote = syncClient.getBestQuote("btcusdt");
System.out.println(bestQuote.getBidPrice());
System.out.println(bestQuote.getAskPrice());

//Asynchronous
asyncClient.getBestQuote("btcusdt", (bestQuoteResult) -> {
  if (bestQuoteResult.succeeded()) {
    System.out.println(bestQuoteResult.getData().getBidPrice());
    System.out.println(bestQuoteResult.getData().getAskPrice());
  }
});

Historical

//Synchronous
List<Trade> tradeList = syncClient.getHistoricalTrade("btcusdt", 5);
System.out.println(tradeList.get(0).getPrice());

//Asynchronous
asyncClient.getHistoricalTrade("btcusdt", 5, (tradeResult) -> {
      if (tradeResult.succeeded()) {
        for (Trade trade : tradeResult.getData()) {
          System.out.println(trade.getPrice());
        }
      }
});

24H statistics

//Synchronous
TradeStatistics statistics = syncClient.get24HTradeStatistics("btcusdt");
System.out.println(statistics.getOpen());

//Asynchronous
asyncClient.get24HTradeStatistics("btcusdt", (statisticsResult) -> {
  if (statisticsResult.succeeded()) {
    System.out.println(statisticsResult.getData().getHigh());
  }
});

Account

Authentication is required.

//Synchronous
Account balance = syncClient.getAccountBalance(AccountType.SPOT);
System.out.println(balance.getBalance("btc").get(0).getBalance());

//Asynchronous
asyncClient.getAccountBalance(AccountType.SPOT, (accountResult) -> {
  if (accountResult.succeeded()) {
    System.out.println(accountResult.getData().getBalance("btc").get(0).getBalance());
  }
});

Wallet

Withdraw

Authentication is required.

//Synchronous
WithdrawRequest request = new WithdrawRequest("xxxxxxx", new BigDecimal(0.1), "btc");
long id = syncClient.withdraw(request);
System.out.println(id);

//Asynchronous
WithdrawRequest request = new WithdrawRequest("xxxxxxx", new BigDecimal(0.1), "btc");
asyncClient.withdraw(request, (withdrawResult) -> {
  if (withdrawResult.succeeded())
    System.out.println(withdrawResult.getData());
});

Cancel withdraw

Authentication is required.

//Synchronous
syncClient.cancelWithdraw("btc", id);

//Asynchronous
asyncClient.cancelWithdraw("btc", id, (withdrawResult) -> {
  if (withdrawResult.succeeded()) {}
});

Withdraw and deposit history

Authentication is required.

//Synchronous
List<Withdraw> withdrawList = syncClient.getWithdrawHistory("btc", id, 10);
System.out.println(withdrawList.get(0).getAmount());
List<Deposit> depositList = syncClient.getDepositHistory("btc", id, 10);
System.out.println(depositList.get(0).getAmount());

//Asynchronous
asyncClient.getWithdrawHistory("btc", id, 10, (withdrawResult) -> {
  if (withdrawResult.succeeded()) {
    System.out.println(withdrawResult.getData().get(0).getAmount());
  }
});
asyncClient.getDepositHistory("btc", id, 10, (depositResult) -> {
  if (depositResult.succeeded()) {
    System.out.println(depositResult.getData().get(0).getAmount());
  }
});

Trading

Create order

Authentication is required.

//Synchronous
NewOrderRequest request = new NewOrderRequest(
    "btcusdt", AccountType.SPOT, OrderType.SELL_MARKET, new BigDecimal(0.1), null);
long id = syncClient.createOrder(request);
System.out.println(id);

//Asynchronous
NewOrderRequest request = new NewOrderRequest(
    "btcusdt", AccountType.SPOT, OrderType.SELL_MARKET, new BigDecimal(0.1), null);
asyncClient.createOrder(request, (orderResult) -> {
  if (orderResult.succeeded()) {
    System.out.println(orderResult.getData());
  }
});

Cancel order

Authentication is required.

//Synchronous
syncClient.cancelOrder("btcusdt", id);

//Asynchronous
asyncClient.cancelOrder("btcusdt", id, (cancelResult) -> {
  if (cancelResult.succeeded()) {}
});

Cancel open orders

Authentication is required.

//Synchronous
CancelOpenOrderRequest request = new CancelOpenOrderRequest("btcusdt", AccountType.SPOT);
BatchCancelResult result = syncClient.cancelOpenOrders(request);
System.out.println(result.getSuccessCount());

//Asynchronous
CancelOpenOrderRequest request = new CancelOpenOrderRequest("btcusdt", AccountType.SPOT);
asyncClient.cancelOpenOrders("btcusdt", (cancelResult) -> {
  if (cancelResult.succeeded()) {
    System.out.println(cancelResult.getData().getSuccessCount());
  }
});

Get order info

Authentication is required.

//Synchronous
Order order = syncClient.getOrder(id);
System.out.println(order.getPrice());

//Asynchronous
asyncClient.getOrder("btcusdt", id, (orderResult) -> {
  if (orderResult.succeeded()) {
    System.out.println(orderResult.getData().getPrice());
  }
});

Historical orders

Authentication is required.

//Synchronous
HistoricalOrdersRequest request =
    new HistoricalOrdersRequest("btcusdt", OrderState.SUBMITTED);
List<Order> orderList = syncClient.getHistoricalOrders(request);
System.out.println(orderList.get(0).getPrice());

//Asynchronous
HistoricalOrdersRequest request =
    new HistoricalOrdersRequest("btcusdt", OrderState.SUBMITTED);
asyncClient.getHistoricalOrders(request, (orderResult) ->{
  if (orderResult.succeeded()) {
    System.out.println(orderResult.getData().get(0).getPrice());
  }
});

Margin Loan

Apply loan

Authentication is required.

//Synchronous
long id = syncClient.applyLoan("btcusdt", "btc", new BigDecimal(10.0));
System.out.println("id");

//Asynchronous
asyncClient.applyLoan("btcusdt", "btc", new BigDecimal(10.0), (loanResult) -> {
  if (loanResult.succeeded()) {
    System.out.println(loanResult.getData());
  }
});

Repay loan

Authentication is required.

//Synchronous
long id = syncClient.repayLoan(id, new BigDecimal(10.0));
System.out.println("id");

//Asynchronous
asyncClient.applyLoan("btcusdt", "btc", new BigDecimal(10.0), (loanResult) -> {
  if (loanResult.succeeded()) {
    System.out.println(loanResult.getData());
  }
});

Loan history

Authentication is required.

//Synchronous
LoanOrderRequest request = new LoanOrderRequest("btcusdt");
List<Loan> loanList = syncClient.getLoanHistory(request);
System.out.println(loanList.get(0).getLoanAmount());

//Asynchronous
LoanOrderRequest request = new LoanOrderRequest("btcusdt");
asyncClient.getLoanHistory("btcusdt", (loanResult) -> {
  if (loanResult.succeeded()) { 
    System.out.println(loanResult.getData().get(0).getLoanAmount());
  }
});

Subscription example

Subscribe trade update

// Subscribe the trade update for btcusdt.
subscriptionClient.subscribeTradeEvent("btcusdt", (tradeEvent) -> {
    System.out.println(event.getSymbol());
    for (Trade trade : tradeEvent.getTradeData()) {
      System.out.println(trade.getPrice());
    }
});

###Subscribe candlestick/KLine update

// Subscribe candlestick update for btcusdt.
subscriptionClient.subscribeCandlestickEvent("btcusdt", (candlestickEvent) -> {
    System.out.println(candlestickEvent.getSymbol());
});

Subscribe order update

Authentication is required.

// Subscribe order update
subscriptionClient.subscribeOrderUpdateEvent("btcusdt", (orderEvent) -> {
    System.out.println(orderEvent.getData().getPrice());
});

Subscribe account change

Authentication is required.

// Subscribe account change.
subscriptionClient.subscribeAccountEvent(BalanceMode.AVAILABLE, (accountEvent) -> {
    for (AccountChange change : accountEvent.getData()) {
        System.out.println(change.getAccountType());
        System.out.println("Balance: " + change.getBalance());
    }
});

Unsubscribe

You can cancel all subscription by calling unsubscribeAll().

subscriptionClient.unsubscribeAll();