Skip to main content
New in v0.5.5 - Real-time candlestick data with WebSocket updates
Hook for subscribing to real-time OHLCV (Open, High, Low, Close, Volume) candlestick data via WebSocket.

Usage

Parameters

string
required
UUID of the trading pair. Get from sdk.market.getTradingPairBySymbol().
'SPOT' | 'MARGIN'
required
Trading mode for OHLCV data. Pass "MARGIN" for a perp market’s candles.
'1m' | '5m' | '15m' | '1h' | '4h' | '1d'
required
Candlestick time interval.
GetCandlesticksParams
Optional parameters for initial data fetch:
  • limit - Number of candlesticks to fetch (max 500)
  • startTime - Start timestamp for range
  • endTime - End timestamp for range

Return Values

Candlestick[]
Array of candlestick data, sorted by time (oldest first). Updates in real-time via WebSocket.
boolean
true while fetching initial candlestick data from REST API, false once loaded.
boolean
true after the OHLCV channel handler is registered, false otherwise. This does not report socket connection or channel delivery state.
Error | null
Error object if subscription or fetch fails, null otherwise.
() => void
Dismisses the current error. It does not retry the fetch or re-register the handler.

Candlestick Data Structure

Features

Hybrid Data Loading

  1. Initial REST Fetch: Fetches historical candlesticks via REST API
  2. WebSocket Updates: Subscribes to real-time updates after initial load
  3. Automatic Merging: New candlesticks are automatically appended or update the last candle if timestamps match

Stable Subscriptions

  • No data jitter: Prevents state updates after component unmount
  • Proper cleanup: WebSocket automatically unsubscribes when component unmounts
  • Race condition prevention: Cancellation flag prevents stale updates

Basic Example

Different Time Intervals

Fetch Historical Data

Error Handling

Display Latest Price

Calculate Price Change

Integration with Chart Libraries

Notes

  • The hook automatically manages WebSocket subscriptions and cleanup
  • Candlesticks are updated in real-time when the WebSocket receives new events
  • If the last candlestick has the same timestamp as an incoming update, it’s replaced; otherwise, a new candle is appended
  • Component unmounting automatically unsubscribes from the WebSocket channel

See Also