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;
}

Unlike most SDK actions, a source is not derived from Config: a reference exchange is not a SYMMIO chain deployment, and which venue to chart is the consumer’s choice. Construct one and pass it in explicitly.

  • 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 has nothing at or before from — typically because the request predates the instrument’s listing. A chart paging backwards should stop when it sees this.

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

Called after a reconnect, when bars may have been missed while the socket was down. Drop cached bars and refetch history rather than splicing a live bar onto a stale series.

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 bar has finalized and the next update starts a new one.

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.

Last updated on
CandleOverview