CandleSource
The SDK’s charting boundary. Every chart library needs the same three things — symbol metadata, bars for a time range, and a live subscription — so that is exactly what a source provides. Chart-library adapters (toTradingViewDatafeed) and framework hooks (useCandles) are written against this interface, never against a specific venue.
interface CandleSource {
readonly id: string; // stable identifier, scopes query keys (e.g. "binance:usd-m-futures")
readonly priceBasis: CandlePriceBasis;
readonly supportedResolutions: readonly CandleResolution[];
readonly maxCandlesPerRequest: number;
getSymbol(marketName: string): Promise<CandleSymbol | undefined>;
getCandles(parameters: GetCandlesParameters): Promise<GetCandlesReturnType>;
watchCandles?(parameters: WatchCandlesParameters): Unwatch;
}Construct a source explicitly. Reference exchanges use their own endpoints; deployment-specific sources such as
createLowcapCandleSource resolve endpoints from Config.
getSymbolresolves toundefinedwhen the source does not carry the market — the check to run before rendering.getCandlespages internally pastmaxCandlesPerRequest; the field is exposed so a caller can size its own requests sensibly.watchCandlesis absent when the source has no realtime feed, in which case a consumer must pollgetCandles.
GetCandlesParameters
marketNamestringMarket name as SYMMIO names it.
resolutionCandleResolutionBar size to fetch. Must be listed in supportedResolutions.
fromnumberRange start, unix ms, inclusive.
tonumberRange end, unix ms, exclusive.
limitnumberoptionalMaximum bars to return. A source pages internally to satisfy this.
signalAbortSignaloptionalAborts in-flight requests. Wired to TanStack Query cancellation by the hooks.
GetCandlesReturnType
candlesCandle[]Bars in ascending time order, de-duplicated and clipped to the requested range.
noMoreDatabooleantrue when the source confirms there is no earlier history to page into. A chart paging backwards should stop when
it sees this; the result can still contain the earliest available candles. false also covers unknown exhaustion
when a provider supplies no boundary metadata; an empty window alone is not proof that history has ended.
WatchCandlesParameters
marketNamestringMarket name as SYMMIO names it.
resolutionCandleResolutionBar size to stream.
onCandle(candle: Candle, meta: CandleUpdateMeta) => voidCalled on every update to the in-progress bar, and once more with closed: true when that bar finalizes.
onReset(range?: CandleHistoryRange) => voidoptionalCalled after a reconnect or historical correction. When a range is supplied, revalidate retained windows that
intersect it; otherwise revalidate all retained history. Existing handlers may ignore the range and reload all
history. Use refreshCandleHistory or React’s
history.refresh(range).
onStatusChange(status: SocketStatus) => voidoptionalCalled whenever the underlying connection status changes.
onError(error: SymmError) => voidoptionalCalled on a transport or parse error; does not stop the subscription.
CandleUpdateMeta is { closed: boolean } — true when the interval has ended. Completed bars may still be corrected by the provider.
CandleHistoryRange is { from: number; to: number }, measured in Unix milliseconds with an inclusive start and exclusive end. In onReset, it identifies corrected candle start times. An omitted range means the source cannot bound the correction; it does not mean there is nothing to refresh.
Implementing your own source
Anything that can answer the three questions plugs in: a solver mark-price stream folded into bars (priceBasis: "solver-mark"), a DEX pool OHLCV API ("dex-pool"), another exchange. Declare honest supportedResolutions, keep time in unix milliseconds aligned to the resolution boundary, report volume: 0 when the venue cannot supply it, and give the source a stable id — it scopes the query cache.
Use getSymbol to report volumeUnit and volumeCurrency whenever known. USD volume uses volumeUnit: "quote" and volumeCurrency: "USD"; it must not be labeled as base-asset volume. See CandleSymbol.
Related
createBinanceCandleSource— the reference implementation.Candle— the bar and symbol shapes.getCandlesQueryOptions— TanStack Query overgetCandles.