binancej/README.md

# BinanceJ

[![CircleCI](https://circleci.com/gh/angrygoats/binancej/tree/master.svg?style=svg&circle-token=ec4614038357b8ff4bcc4773bedd4a264a1947b7)](https://circleci.com/gh/angrygoats/binancej/tree/master)
[![Maintainability](https://api.codeclimate.com/v1/badges/78e89cca82f04486b11e/maintainability)](https://codeclimate.com/github/angrygoats/binancej/maintainability)

A Java 8 implementation of the [Binance API Specification](https://github.com/binance-exchange/binance-official-api-docs/blob/master/rest-api.md).

## Getting BinanceJ 

### Maven

```
<dependency>
    <groupId>com.sigmaflare</groupId>
    <artifactId>binancej</artifactId>
    <version>1.0.2</version>
</dependency>
```

### Gradle

`compile group: 'com.sigmaflare', name: 'binancej', version: '1.0.2'`

## Licensing

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 `IpBannedException`s.

## 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 `InternalServiceErrorException`s 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](https://github.com/binance-exchange/binance-official-api-docs/blob/master/errors.md).

## Standard Exceptions

### Runtime Exceptions

In the event an unknown error occurs, the code will throw an `UnexpectedErrorException`. These are generally complete showstoppers.

## Notes

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

## Examples

### Server alive check with ping

If the ping method does not throw an exception, the ping was successful.

```java
GeneralUtilities generalUtilities = GeneralUtilities.builder().apiKey("KEY").secretKey("KEY").build();
generalUtilities.ping();
```

### Getting current server time

```java
GeneralUtilities generalUtilities = GeneralUtilities.builder().apiKey("KEY").secretKey("KEY").build();
ServerTime = generalUtilities.getServerTime();
```

### Getting Exchange Information

```java
GeneralUtilities generalUtilities = GeneralUtilities.builder().apiKey("KEY").secretKey("KEY").build();
ExchangeInfo res = generalUtilities.getExchangeInfo();
```

### Getting Candlestick data

```java
MarketData marketData = MarketData.builder().apiKey("KEY").secretKey("KEY").build();
List<Candlestick> res = marketData.getCandlestickData("ETHBTC", Interval.ONE_MINUTE);
```

### Getting market depth

```java
MarketData marketData = MarketData.builder().apiKey("KEY").secretKey("KEY").build();
OrderBookDepth res = marketData.getOrderBookDepth("ETHBTC", 1000);
```

### Getting ticker price for an instrument

```java
MarketData marketData = MarketData.builder().apiKey("KEY").secretKey("KEY").build();
TickerPrice res = marketData.getTickerPriceForSymbol("ETHBTC");
```

## Contributing

Head over to our [CONTRIBUTING.md](CONTRIBUTING.md) to get started. All features are welcome as long as they are
in scope of the API and following the contributing guide.