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

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.

  • getSymbol resolves to undefined when the source does not carry the market — the check to run before rendering.
  • getCandles pages internally past maxCandlesPerRequest; the field is exposed so a caller can size its own requests sensibly.
  • watchCandles is absent when the source has no realtime feed, in which case a consumer must poll getCandles.

GetCandlesParameters

marketNamestring

Market name as SYMMIO names it.

resolutionCandleResolution

Bar size to fetch. Must be listed in supportedResolutions.

fromnumber

Range start, unix ms, inclusive.

tonumber

Range end, unix ms, exclusive.

limitnumberoptional

Maximum bars to return. A source pages internally to satisfy this.

signalAbortSignaloptional

Aborts 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.

noMoreDataboolean

true 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

marketNamestring

Market name as SYMMIO names it.

resolutionCandleResolution

Bar size to stream.

onCandle(candle: Candle, meta: CandleUpdateMeta) => void

Called on every update to the in-progress bar, and once more with closed: true when that bar finalizes.

onReset(range?: CandleHistoryRange) => voidoptional

Called 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) => voidoptional

Called whenever the underlying connection status changes.

onError(error: SymmError) => voidoptional

Called 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.

Last updated on