Sources

Sources

Abstract

A source loads a finite window of OHLCV bars for the chart and engine. Sources live in src/sources/catalog.ts and register into the unified registry via ensureSourcesRegistered().

Conceptual model

Rendering…

Built-in catalog

UI order is BUILTIN_SOURCES array order (Binance first).

Interface surface

Every source implements SourcePlugin (contracts):

fetchHistorical({
  symbol,
  interval,
  limit?,
  startTime?,   // unix seconds (optional)
  endTime?,     // unix seconds (optional) — walk-back pagination
  signal?,      // AbortSignal for background jobs
  config?,
}): Promise<Bar[]>

One-shot Load vs Data Source Manager

Do not pass startTime + endTime together when paginating on Binance-style venues: they return the first N bars from startTime, which can falsely complete a multi-year job in one page.

Config highlights

binance-rest

When Settings → Data has a Binance key in the session vault, Load uses signed REST (higher weight) and falls back to the Worker /api/market/binance/signed/klines on CORS failure. Keys are never written to disk.

mock-walk

csv-upload

• No schema fields. User must Upload a CSV (time,open,high,low,close[,volume]) or JSON array first; otherwise throws a clear error.

Internals

Interval → venue codes

Helpers map AXIS intervals (1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w, 1M) to OKX bar, Bybit interval codes, Coinbase granularity seconds. Unmapped intervals fall back to daily-ish defaults — check venue docs if you add exotic TFs. Some venues omit a subset (MEXC has no 3m/2h/6h/8h/12h/3d; Kraken has no 3m/2h).

Dynamic registration

registerDynamicSource(plugin)  // from catalog / loader
unregisterDynamicSource(id)
listDynamicSourceIds()

Loader path: kind === 'source' + fetchHistorical required.

Invariants & edge cases

1. Time unit — always seconds unix (Binance ms ÷ 1000).
2. Binance fallback — offline demos “work” but are not real prices; disable fallback for strict desk research.
3. CORS — browser → public venue APIs must allow CORS; corporate proxies may require a Worker /api/proxy (not shipped as a general proxy today — plan carefully).
4. Newest-first venues (OKX, Bybit, Coinbase) — catalog reverses/sorts ascending by time for the chart.

Worked example

// Minimal custom source (ES module for loader)
export default {
  id: 'static-two',
  name: 'Two Bars',
  kind: 'source',
  async fetchHistorical() {
    return [
      { time: 1_700_000_000, open: 1, high: 2, low: 0.5, close: 1.5, volume: 10 },
      { time: 1_700_000_060, open: 1.5, high: 2, low: 1, close: 1.2, volume: 12 },
    ];
  },
};

Failure modes

See also

• Streams
• Contracts
• Plugin examples (CoinGecko)