Skip to Content
Symmio Trading-SDK — the SDK surface for builders on Arbitrum
ReactCandles hooks

Candles hooks

React bindings over the candles slice. The hooks own the source’s memoization, the subscription lifecycle, and error normalization; everything about how bars are fetched, paged, and streamed lives in core.

All reads.

Import

import { useBinanceCandleSource, useLowcapCandleSource, type UseLowcapCandleSourceParameters, useCandles, useCandleHistory, type UseCandleHistoryParameters, type UseCandleHistoryReturnType, useCandleStream, useTradingViewDatafeed, type UseBinanceCandleSourceParameters, type UseCandlesParameters, type UseCandlesReturnType, type UseCandleStreamParameters, type UseCandleStreamReturnType, type UseTradingViewDatafeedParameters, } from "@symmio/trading-react";

The same hooks are also available from the @symmio/trading-react/candles subpath. Value types (Candle, CandleSource, CandleResolution, CandleSymbol, TradingViewDatafeed) come from @symmio/trading-core.

Choosing a hook

You wantUse
Incremental history for panning or zoominguseCandleHistory
Historical bars through TanStack QueryuseCandles
The live bar — a price header, a sparkline, an imperative chartuseCandleStream
A full TradingView Charting Library widgetuseTradingViewDatafeed

All these hooks need a source. Build it with useBinanceCandleSource for major markets or useLowcapCandleSource for price-service lowcaps.

useBinanceCandleSource

Creates a memoized Binance CandleSource.

A source caches the venue’s exchangeInfo for its lifetime, so recreating it on every render would refetch that on every symbol resolve — and a new source identity tears down any live subscription built on it.

const source = useBinanceCandleSource();

Parameters

Takes the same options as createBinanceCandleSource.

NameTypeDefaultNotes
market?"usd-m-futures" | "spot""usd-m-futures"Futures symbols are perpetual contracts, matching what a SYMMIO market is.
restUrl?stringvenue defaultA regional mirror or your own caching proxy.
wsUrl?stringvenue defaultKeep the futures /market/ route — see the core page’s routing note.
resolveSymbol?(marketName: string) => string | undefinedupper-case identityPass a stable reference — it participates in the memo.
webSocketConstructor?WebSocketConstructorglobalThis.WebSocketPass the ws package in Node.

Return type

A CandleSource, stable for as long as its options are unchanged.

useLowcapCandleSource

Creates a memoized createLowcapCandleSource. The hook resolves SDK context and active chain; the core source owns all fetching, pagination, and live-candle behavior.

function useLowcapCandleSource(parameters?: UseLowcapCandleSourceParameters): CandleSource; type UseLowcapCandleSourceParameters = LowcapCandleSourceParameters & ConfigParameter;
ParameterDefaultMeaning
configSDK providerExplicit config override.
chainIdActive wallet chainDeployment whose price service to use.
solverIdChain defaultPrice-service owner.
includeFlatfalseInclude flat candles; sent explicitly to the service.
refreshIntervalMs30_000Recent OHLCV reconciliation while subscribed; minimum 1,000 ms.

Returns a CandleSource stable while the config and option values remain unchanged. Unsupported deployments report errors through the history and stream hooks; invalid construction options throw. Pin chainId if the chart should not follow wallet chain changes. It declares USD quote volume and priceBasis: "price-service".

import { SymmioSupportedChainId } from "@symmio/trading-core"; import { useState } from "react"; const source = useLowcapCandleSource({ chainId: SymmioSupportedChainId.ARBITRUM }); const [initialRange] = useState(() => { const to = Date.now(); return { from: to - 300 * 3_600_000, to }; }); const history = useCandleHistory({ source, marketName, resolution: "1h", ...initialRange, followLatest: true, query: { staleTime: 0, refetchOnWindowFocus: false, retry: 1 }, }); const stream = useCandleStream({ source, marketName, resolution: "1h", onReset: (range) => { void history.refresh(range); }, });

Flat candles are filtered by default; pass includeFlat: true to include them. Use the full market name from price-service listings. followLatest: true advances the newest window’s end on refresh, including newly completed intervals without changing the initial query key. Connect history.loadOlder to your chart’s older-edge gesture. Changing market, resolution, or source releases the old subscription and clears its live candle.

Forward the optional onReset range to history.refresh(range). Recent corrections then fetch only corrected intervals and any missing live tail; reconnects and hourly checks omit the range and refresh all retained history. The example disables focus refetching and retries failed history once. Provide a Refresh control for recovery or for use while streaming is disabled.

An empty range is a normal result. On deployments without has_older, noMoreData stays false because exhaustion is unknown. See paging, flat candles, and provisional volume before enabling automatic history loading.

useCandleHistory

Use this hook when the chart retains loaded candles while the user pans into older dates. It works with any CandleSource. Paging and merging are implemented by getCandleHistoryQueryOptions in core; the hook adds React lifecycle and normalized errors.

function useCandleHistory(parameters: UseCandleHistoryParameters): UseCandleHistoryReturnType; type UseCandleHistoryParameters = GetCandleHistoryOptions & { source: CandleSource };
ParameterMeaning
sourceSource from useBinanceCandleSource, useLowcapCandleSource, or your own implementation.
marketName, resolutionMarket and supported bar size.
from, toStable initial window in milliseconds, [from, to). Each older window spans to - from milliseconds; the source aligns its own candle buckets.
followLatest?Defaults to false. When true, fetching or refreshing the newest window extends its end through the current time.
query?TanStack enabled, retry, stale-time, and refetch settings. Query identity, selection, and paging are owned by the SDK.

The return type extends UseInfiniteQueryResult<CandleHistoryData, SymmioRequestError>:

FieldMeaning
data.candlesAll retained candles, ascending and unique by start time.
data.noMoreDataThe oldest requested window has confirmed exhaustion. Empty data alone never sets this.
data.pages, data.pageParamsRetained responses and requested windows, newest window first.
loadOlder()Fetch only the preceding window. Concurrent calls are deduplicated; calls during fetching, after an error, or after confirmed exhaustion do nothing.
refresh(range?)Revalidate all windows when omitted, cancelling active work. With a CandleHistoryRange, wait for active paging and refresh only corrected intervals and any missing live tail. Displayed data remains available during refresh and after errors.
isFetchingNextPageAn older window is loading. “Next page” means older history in this query.
isFetching, errorOverall request state and normalized error.

Wire loadOlder to a deliberate chart interaction. No page is fetched automatically after an empty response; another interaction can traverse the next window. Use refresh() to recover from an error, then retry older navigation. Full refetches revalidate every retained window. Bounded refreshes replace only corrected intervals and fetch any missing live tail; a source may split each requested range internally to respect its request cap. Bars outside those ranges and their paging boundaries are preserved. Range selection and coordination live in core’s refreshCandleHistory.

Full refreshes take priority over concurrent bounded corrections for the same query, including across hook instances. With followLatest: true, a correction to an older page or outside retained history still fetches a missing newest tail.

refresh resolves after the operation; request failures are exposed through error. A scheduled correction is discarded when the hook unmounts, its query identity changes, or a full refresh supersedes it. Other consumers of the same query keep their shared requests.

TanStack’s focus and reconnect policies remain consumer-configurable. The hook does not globally disable them. Set query.refetchOnWindowFocus: false when using explicit refresh and stream corrections to avoid reloading all retained history on tab focus; keep staleTime: 0 for mutable candle data.

Keep the initial range stable while paging. Changing it, the market, resolution, source identity, or follow policy creates a separate query. An obsolete request is aborted when it has no remaining observers. Use useCandles for an explicit, independently selected range; use useCandleHistory for incremental navigation.

useCandles

Historical bars through TanStack Query.

const source = useBinanceCandleSource(); const { data, isLoading, error } = useCandles({ source, marketName: "BTCUSDT", resolution: "1m", from: rangeStart, to: rangeEnd, });

Parameters

NameTypeDefaultNotes
sourceCandleSource—Its id is part of the query key, so venues never share a cache entry.
marketNamestring—Market name as SYMMIO names it.
resolutionCandleResolution—Must be listed in source.supportedResolutions.
fromnumber—Range start, unix ms, inclusive.
tonumber—Range end, unix ms, exclusive.
limit?number—Max bars; the source pages internally to satisfy it.
query?QueryParameter—TanStack overrides.

Return type

UseQueryResult<GetCandlesReturnType, SymmioRequestError> — data.candles in ascending time order plus data.noMoreData, which tells a chart paging backwards to stop.

from/to are part of the query key. Passing a live Date.now() mints a new cache entry on every render — derive the range from state that only changes when the user actually pans or changes resolution.

useCandleStream

Subscribe to live bar updates for one market and resolution.

const { candle, closed, status, error } = useCandleStream({ source, marketName: "BTCUSDT", resolution: "1m", onCandle: (candle) => series.update(candle), onReset: () => refetchHistory(), });

Parameters

NameTypeDefaultNotes
sourceCandleSource—Must implement watchCandles; the hook stays closed otherwise.
marketNamestring—Changing it tears down the old subscription.
resolutionCandleResolution—Bar size to stream.
enabled?booleantrueSubscribe only when true.
onCandle?(candle: Candle, meta: CandleUpdateMeta) => void—Called ahead of the state update. Read through a ref, so an inline arrow does not re-subscribe.
onReset?(range?: CandleHistoryRange) => void—Forward to history.refresh(range). Known corrections bound the refresh; an omitted range requests full revalidation. Read through a ref.

Return type

FieldTypeNotes
candleCandle | nullThe most recent bar, null until the first update.
closedbooleantrue when the candle interval has ended; historical corrections remain possible.
statusSocketStatusLive socket status.
errorSymmioRequestError | nullLast transport or parse error, normalized.

Returns the latest bar as state for simple cases (a price header, a sparkline). For a full chart, prefer the onCandle callback and let the charting library own the series — re-rendering a React tree on every tick is wasted work when the chart mutates its own canvas.

useTradingViewDatafeed

Create a memoized TradingView datafeed over a CandleSource.

const source = useBinanceCandleSource(); const datafeed = useTradingViewDatafeed({ source, exchange: "Binance" }); useEffect(() => { const widget = new TradingView.widget({ datafeed, symbol: "BTCUSDT", interval: "60" }); return () => widget.remove(); }, [datafeed]);

Parameters

source plus the presentation options of toTradingViewDatafeed (exchange?, session?, timezone?).

Return type

A TradingViewDatafeed to pass straight to widget({ datafeed }).

The datafeed owns its live subscriptions, so it must outlive a render — a new instance would orphan the sockets the chart is already holding. Keep the source stable (see useBinanceCandleSource) and this stays stable too.

Know which price you are drawing

Every source declares a priceBasis. Binance’s is reference-exchange — a third-party venue’s perp price, not the SYMMIO solver’s mark a trade settles against. Trade math (margin, PnL, liquidation, TP/SL) must read the Price Service, never the chart’s series.

Last updated on