New in v0.5.5 - Real-time candlestick data with WebSocket updates
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 rangeendTime- 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
- Initial REST Fetch: Fetches historical candlesticks via REST API
- WebSocket Updates: Subscribes to real-time updates after initial load
- 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
- WebSocket API - Low-level OHLCV WebSocket channel
- TypeScript SDK - Core SDK WebSocket methods
- useMarket - Get trading pair metadata

