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.

Version compatibility table

JDK LTS version	Scala version
11	2.12.x, 2.13.x, 3.0.x, 3.1.x
17	2.12.x, 2.13.x, 3.0.x, 3.1.x

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 two seconds.
• Diff. Depth Stream: Order book price and quantity depth updates used to locally manage an order book.
• Book Tickers Streams: Pushes any update to the best bid or ask's price or quantity in real-time for the selected 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
• Order book: Get order book
• Cancel order: Cancel an active order
• All open orders: Get all open orders
• 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.
• Diff. Depth Book Streams: Bids and asks, pushed every 250 milliseconds, 500 milliseconds, 100 milliseconds (if existing)
• Partial Book Depth Streams: Top bids and asks

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(
  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(
  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.std.Console
import cats.effect.{IO, IOApp}
import fs2.Stream
import io.github.paoloboni.binance.BinanceClient
import io.github.paoloboni.binance.common.SpotConfig

import scala.concurrent.duration.DurationInt

object PriceMonitor extends IOApp.Simple {

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

  override def run: IO[Unit] =
    BinanceClient
      .createSpotClient[IO](config)
      .use { client =>
        Stream
          .awakeEvery[IO](5.seconds)
          .repeat
          .evalMap(_ => client.V3.getPrices())
          .evalMap(prices => Console[IO].println("Current prices: " + prices))
          .compile
          .drain
      }
}

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!