Scala client for Binance API

A functional Scala client for Binance, powered by cats-effect and fs2.

This client is rate limited, based on Binance API specification.

Getting started

If you use sbt add the following dependency to your build file:

libraryDependencies += "io.github.paoloboni" %% "binance-scala-client" % "<version>"

APIs supported

Spot API

Rest

• Exchange information: Current exchange trading rules and symbol information
• Kline/Candlestick data: Kline/candlestick bars for a symbol
• Symbol price ticker: Latest price for a symbol or symbols
• Balance information: Current balance information
• New order (trade): Send in a new order
• Query order (trade): Query status and fills of existing order
• Cancel order (trade): Cancel an active order
• Cancel open orders (trade): Cancels all active orders on a symbol
• Order book: Order book depth on a symbol

WebSocket

• Kline/Candlestick Streams: The Kline/Candlestick Stream push updates to the current klines/candlestick every second.
• Diff. Depth Stream: Order book price and quantity depth updates used to locally manage an order book.
• All Book Tickers Stream: Pushes any update to the best bid or ask's price or quantity in real-time for all symbols.
• Partial Book Depth Streams: Top bids and asks.
• Trade Streams: The Trade Streams push raw trade information.
• Aggregate Trade Streams: The Aggregate Trade Streams push trade information that is aggregated for a single taker order.

Future API

Rest

• Exchange information: Current exchange trading rules and symbol information
• Kline/Candlestick data: Kline/candlestick bars for a symbol
• Symbol price ticker: Latest price for a symbol or symbols
• Account information: Get current account information
• New order (trade): Send in a new order
• Query order: Check an order's status
• Cancel order: Cancel an active order
• Cancel all open orders: Cancel all open orders
• Change position mode (trade): Change user's position mode (Hedge Mode or One-way Mode ) on EVERY symbol
• Change initial leverage (trade): Change user's initial leverage of specific symbol market

WebSocket

• Aggregate trade streams: The Aggregate Trade Streams push trade information that is aggregated for a single taker order every 100 milliseconds.
• Kline/Candlestick Streams: The Kline/Candlestick Stream push updates to the current klines/candlestick every 250 milliseconds (if existing).
• Mark Price Stream: Mark price and funding rate for a single symbol pushed every 3 seconds.
• Mark Price Stream for All market: Mark price and funding rate for all symbols pushed every 3 seconds.
• Continuous Contract kline streams: Continuous Contract Kline/Candlestick Streams of updates every 250 milliseconds.

Initialise the client

The client initialisation returns an API object as a Cats Resource. There are two factories available at the moment, one for Spot API and the other one for Future API.

Spot client

import cats.effect.{IO, Resource}
import io.github.paoloboni.binance.BinanceClient
import io.github.paoloboni.binance.common.SpotConfig
import io.github.paoloboni.binance.spot.SpotApi

val config = SpotConfig.Default[IO](
  apiKey = "***",     // your api key
  apiSecret = "***"   // your api secret
)
val client: Resource[IO, SpotApi[IO]] = BinanceClient.createSpotClient[IO](config)

Future client

import cats.effect.{IO, Resource}
import io.github.paoloboni.binance.BinanceClient
import io.github.paoloboni.binance.common.FapiConfig
import io.github.paoloboni.binance.fapi.FutureApi

val config = FapiConfig.Default[IO](
  apiKey = "***",     // your api key
  apiSecret = "***"   // your api secret
)
val client: Resource[IO, FutureApi[IO]] = BinanceClient.createFutureClient[IO](config)

Documentation

The API documentation is available here.

Example app

This is a sample app to monitor the exchange prices (fetch every 5 seconds).

import cats.effect.{ExitCode, IO, IOApp}
import fs2.Stream
import io.github.paoloboni.binance.BinanceClient
import io.github.paoloboni.binance.common.SpotConfig
import org.typelevel.log4cats.Logger
import org.typelevel.log4cats.slf4j.Slf4jLogger

import scala.concurrent.duration.DurationInt

object PriceMonitor extends IOApp {

  val config = SpotConfig.Default[IO](
    apiKey = "***",
    apiSecret = "***"
  )

  override def run(args: List[String]): IO[ExitCode] = {
    implicit def log: Logger[IO] = Slf4jLogger.getLogger[IO]

    BinanceClient
      .createSpotClient[IO](config)
      .use { client =>
        Stream
          .awakeEvery[IO](5.seconds)
          .repeat
          .evalMap(_ => client.getPrices())
          .evalMap(prices => log.info("Current prices: " + prices))
          .compile
          .drain
      }
      .redeem(
        { t =>
          log.error(t)("Something went wrong")
          ExitCode(1)
        },
        _ => ExitCode.Success
      )
  }
}

Contributing

How to run unit and integration tests

sbt test

How to run end-to-end tests

FAPI_API_KEY=<your-fapi-api-key> \
    FAPI_SECRET_KEY=<your-fapi-secret-key> \
    SPOT_API_KEY=<your-spot-api-key> \
    SPOT_SECRET_KEY=<your-spot-secret-key> \
    sbt e2e:test

How to get Spot API and secret keys

• Navigate to https://testnet.binance.vision
• Login with your Github account
• Click on "Generate HMAC_SHA256 Key"
• Enter a description and press "Generate"
• Take note of the generated values

How to get Future API and secret keys

• Navigate to https://testnet.binancefuture.com
• Register a new account or login with an existing one
• Click on "API key" link in the lower part of the screen
• Take note of the values

Contributors ✨

Thanks goes to these wonderful people (emoji key):

DarkWingMcQuack 💻

Swoorup Joshi 💻

This project follows the all-contributors specification. Contributions of any kind welcome!