Skip to main content

WebSocket Streams

Subscribe to real-time market data via WebSocket. All streams return fs2.Stream[F, A] with typed event models.

Binance API Reference: WebSocket Streams

Setup​

import io.github.rafafrdz.binance4s.ws.client.BinanceWsClient
import io.github.rafafrdz.binance4s.api.ws.*

BinanceWsClient.resource[IO](config).use { ws =>
  ws.subscribe(KlineStream("BTCUSDT", KlineInterval.`1m`))
    .evalMap(k => IO.println(s"Close: ${k.k.c}"))
    .compile.drain
}

Available Stream Types​

Aggregate Trade​

Compressed trade information pushed every time a trade occurs.

ws.subscribe(AggTradeStream("BTCUSDT"))
// Stream[F, WsAggTrade]
FieldTypeDescription
eStringEvent type ("aggTrade")
sStringSymbol
pStringPrice
qStringQuantity
TLongTrade time
mBooleanIs buyer the maker?

Individual Trade​

Raw individual trade event.

ws.subscribe(TradeStream("ETHUSDT"))
// Stream[F, WsTrade]

Kline / Candlestick​

Kline/candlestick update pushed every second.

ws.subscribe(KlineStream("BTCUSDT", KlineInterval.`1h`))
// Stream[F, WsKline]

The kline data is nested under the k field:

stream.evalMap { event =>
  IO.println(s"Symbol: ${event.s}, Close: ${event.k.c}, Volume: ${event.k.v}")
}

Mini Ticker​

24hr rolling window mini-ticker for a single symbol.

ws.subscribe(MiniTickerStream("BTCUSDT"))
// Stream[F, WsMiniTicker]

All Market Mini Tickers​

Mini-ticker for all symbols, pushed every second.

ws.subscribe(AllMiniTickerStream())
// Stream[F, List[WsMiniTicker]]

Individual Symbol Ticker​

Full 24hr ticker for a single symbol.

ws.subscribe(TickerStream("BTCUSDT"))
// Stream[F, WsTicker]

All Market Tickers​

Full ticker for all symbols.

ws.subscribe(AllTickerStream())
// Stream[F, List[WsTicker]]

Book Ticker​

Best bid/ask update in real-time.

ws.subscribe(BookTickerStream("BTCUSDT"))
// Stream[F, WsBookTicker]

Average Price​

Average price for a symbol, updated every second.

ws.subscribe(AvgPriceStream("BTCUSDT"))
// Stream[F, WsAvgPrice]

Partial Book Depth​

Top bids and asks at specified depth level.

ws.subscribe(DepthStream("BTCUSDT", levels = 10, speed = "100ms"))
// Stream[F, WsDepthUpdate]

Levels: 5, 10, or 20. Speed: 1000ms (default) or 100ms.

Diff Depth​

Order book updates pushed in real-time.

ws.subscribe(DiffDepthStream("BTCUSDT", speed = "100ms"))
// Stream[F, WsDepthUpdate]

Multi-Stream Subscription​

Subscribe to multiple streams over a single connection:

ws.subscribeMulti(List(
  "btcusdt@trade",
  "ethusdt@trade",
  "bnbusdt@miniTicker"
))
// Stream[F, Json] — raw JSON, parse by stream name

Composing Streams​

Since WebSocket streams are fs2.Stream, you can compose them with full stream combinators:

val btcTrades = ws.subscribe(TradeStream("BTCUSDT"))
val ethTrades = ws.subscribe(TradeStream("ETHUSDT"))

// Merge two streams
val allTrades = btcTrades.merge(ethTrades)

// Take first 100 events then stop
allTrades.take(100).compile.toList

// Window into 10-second chunks
allTrades.groupWithin(100, 10.seconds)