@mathieuc/tradingview 3.5.2 → 4.0.0-beta.0

package/dist/chart/timeframes.d.ts

@@ -0,0 +1,7 @@
+import type { Timeframe } from './types.js';
+/**
+ * Approximate duration of one bar in seconds, or `undefined` for
+ * resolutions that are not time-based (ticks, ranges...).
+ * Months count as 30 days.
+ */
+export declare function timeframeSeconds(timeframe: Timeframe): number | undefined;

package/dist/chart/timeframes.js

@@ -0,0 +1,22 @@
+/**
+ * Approximate duration of one bar in seconds, or `undefined` for
+ * resolutions that are not time-based (ticks, ranges...).
+ * Months count as 30 days.
+ */
+export function timeframeSeconds(timeframe) {
+    const match = /^(\d*)([SDWM]?)$/i.exec(String(timeframe).trim());
+    if (!match)
+        return undefined;
+    const [, amountText, unitText] = match;
+    const amount = amountText ? Number(amountText) : 1;
+    if (!Number.isFinite(amount) || amount <= 0)
+        return undefined;
+    switch (unitText.toUpperCase()) {
+        case '': return amountText ? amount * 60 : undefined;
+        case 'S': return amount;
+        case 'D': return amount * 86_400;
+        case 'W': return amount * 604_800;
+        case 'M': return amount * 2_592_000;
+        default: return undefined;
+    }
+}

package/dist/chart/types.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Exchange-qualified symbol such as `BINANCE:BTCEUR` or `NASDAQ:AAPL`.
+ * A bare ticker (`BTCEUR`) lets TradingView pick an exchange.
+ */
+export type MarketSymbol = string;
+/**
+ * Bar resolution: minutes (`1`, `5`, `60`, `240`), seconds (`1S`), or
+ * days/weeks/months (`D`, `1D`, `W`, `M`...). Custom values such as `20`
+ * or `1S` need an account with access to them.
+ */
+export type Timeframe = '1S' | '5S' | '10S' | '15S' | '30S' | '1' | '3' | '5' | '15' | '30' | '45' | '60' | '120' | '180' | '240' | '1D' | '1W' | '1M' | 'D' | 'W' | 'M' | '3M' | '6M' | '12M' | (string & {});
+/** Chart timezone. `exchange` uses the exchange timezone. Any IANA name TradingView supports is accepted. */
+export type Timezone = 'Etc/UTC' | 'exchange' | 'Pacific/Honolulu' | 'America/Juneau' | 'America/Los_Angeles' | 'America/Phoenix' | 'America/Vancouver' | 'US/Mountain' | 'America/El_Salvador' | 'America/Bogota' | 'America/Chicago' | 'America/Lima' | 'America/Mexico_City' | 'America/Caracas' | 'America/New_York' | 'America/Toronto' | 'America/Argentina/Buenos_Aires' | 'America/Santiago' | 'America/Sao_Paulo' | 'Atlantic/Reykjavik' | 'Europe/Dublin' | 'Africa/Lagos' | 'Europe/Lisbon' | 'Europe/London' | 'Europe/Amsterdam' | 'Europe/Belgrade' | 'Europe/Berlin' | 'Europe/Brussels' | 'Europe/Copenhagen' | 'Africa/Johannesburg' | 'Africa/Cairo' | 'Europe/Luxembourg' | 'Europe/Madrid' | 'Europe/Malta' | 'Europe/Oslo' | 'Europe/Paris' | 'Europe/Rome' | 'Europe/Stockholm' | 'Europe/Warsaw' | 'Europe/Zurich' | 'Europe/Athens' | 'Asia/Bahrain' | 'Europe/Helsinki' | 'Europe/Istanbul' | 'Asia/Jerusalem' | 'Asia/Kuwait' | 'Europe/Moscow' | 'Asia/Qatar' | 'Europe/Riga' | 'Asia/Riyadh' | 'Europe/Tallinn' | 'Europe/Vilnius' | 'Asia/Tehran' | 'Asia/Dubai' | 'Asia/Muscat' | 'Asia/Ashkhabad' | 'Asia/Kolkata' | 'Asia/Almaty' | 'Asia/Bangkok' | 'Asia/Jakarta' | 'Asia/Ho_Chi_Minh' | 'Asia/Chongqing' | 'Asia/Hong_Kong' | 'Australia/Perth' | 'Asia/Shanghai' | 'Asia/Singapore' | 'Asia/Taipei' | 'Asia/Seoul' | 'Asia/Tokyo' | 'Australia/Brisbane' | 'Australia/Adelaide' | 'Australia/Sydney' | 'Pacific/Norfolk' | 'Pacific/Auckland' | 'Pacific/Fakaofo' | 'Pacific/Chatham' | (string & {});
+/** Custom bar types computed by TradingView. */
+export type ChartType = 'HeikinAshi' | 'Renko' | 'LineBreak' | 'Kagi' | 'PointAndFigure' | 'Range';
+/** Server study used for each chart type. */
+export declare const CHART_TYPE_STUDIES: Record<ChartType, string>;
+/** Inputs for custom chart types. */
+export interface ChartTypeInputs {
+    /** Renko/Kagi/PointAndFigure ATR length. */
+    atrLength?: number;
+    /** Renko/LineBreak/Kagi source. */
+    source?: 'open' | 'high' | 'low' | 'close' | 'hl2' | 'hlc3' | 'ohlc4';
+    /** Renko/Kagi/PointAndFigure style. */
+    style?: 'ATR' | (string & {});
+    /** Renko/PointAndFigure box size. */
+    boxSize?: number;
+    /** Kagi/PointAndFigure reversal amount. */
+    reversalAmount?: number;
+    /** Renko/PointAndFigure sources. */
+    sources?: 'Close' | (string & {});
+    /** Renko wicks. */
+    wicks?: boolean;
+    /** LineBreak number of lines. */
+    lb?: number;
+    /** PointAndFigure one-step-back building. */
+    oneStepBackBuilding?: boolean;
+    /** Range phantom bars. */
+    phantomBars?: boolean;
+    /** Range size. */
+    range?: number;
+    [input: string]: unknown;
+}
+/** Price adjustment. */
+export type Adjustment = 'splits' | 'dividends' | 'none' | (string & {});
+/** Trading session. */
+export type TradingSession = 'regular' | 'extended' | (string & {});
+/** One bar. `time` is the bar open time as a Unix timestamp in seconds. */
+export interface Candle {
+    time: number;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume: number;
+}
+export interface Subsession {
+    id: string;
+    description: string;
+    private: boolean;
+    session: string;
+    'session-correction': string;
+    'session-display': string;
+}
+/** Symbol metadata from `symbol_resolved`. Fields vary by market; unknown ones are kept. */
+export interface SymbolInfo {
+    /** Series ID used by this chart (`ser_1`). */
+    series_id: string;
+    name: string;
+    full_name: string;
+    pro_name: string;
+    description: string;
+    short_description: string;
+    exchange: string;
+    listed_exchange: string;
+    provider_id: string;
+    base_currency?: string;
+    base_currency_id?: string;
+    currency_id: string;
+    currency_code: string;
+    type: string;
+    timezone: string;
+    session: string;
+    session_display?: string;
+    subsession_id?: string;
+    subsessions?: Subsession[];
+    pricescale: number;
+    pointvalue?: number;
+    minmov: number;
+    minmove2?: number;
+    fractional: boolean;
+    has_intraday: boolean;
+    has_adjustment?: boolean;
+    has_extended_hours?: boolean;
+    is_tradable: boolean;
+    is_replayable?: boolean;
+    allowed_adjustment?: string;
+    variable_tick_size?: string;
+    pro_perm?: string;
+    typespecs?: string[];
+    resolutions?: string[];
+    aliases?: string[];
+    alternatives?: string[];
+    [key: string]: unknown;
+}

package/dist/chart/types.js

@@ -0,0 +1,9 @@
+/** Server study used for each chart type. */
+export const CHART_TYPE_STUDIES = {
+    HeikinAshi: 'BarSetHeikenAshi@tv-basicstudies-60!',
+    Renko: 'BarSetRenko@tv-prostudies-40!',
+    LineBreak: 'BarSetPriceBreak@tv-prostudies-34!',
+    Kagi: 'BarSetKagi@tv-prostudies-34!',
+    PointAndFigure: 'BarSetPnF@tv-prostudies-34!',
+    Range: 'BarSetRange@tv-basicstudies-72!',
+};

package/dist/client/client.d.ts

@@ -0,0 +1,89 @@
+import { TradingViewError } from '../errors.js';
+import { Emitter } from '../events.js';
+import { type Credentials } from '../http/request.js';
+import { type ServerHello, type ServerPacket } from '../protocol/framing.js';
+import { type TransportFactory } from './transport.js';
+import { ChartSession } from '../chart/chart-session.js';
+import { QuoteSession, type QuoteSessionOptions } from '../quote/quote-session.js';
+/** Websocket server. `prodata` is used by paid accounts, `widgetdata` by widgets. */
+export type ServerName = 'data' | 'prodata' | 'widgetdata' | (string & {});
+export type DebugOption = boolean | ((...args: unknown[]) => void);
+export interface ClientOptions {
+    /** Account cookies. Without them, the client uses anonymous (delayed/limited) access. */
+    credentials?: Credentials;
+    /** Websocket auth token (`User.authToken`). Skips the account lookup done with `credentials`. */
+    authToken?: string;
+    /** Websocket server. Default: `data`. */
+    server?: ServerName;
+    /** Page used to load the account from `credentials`, e.g. `https://fr.tradingview.com/`. */
+    location?: string;
+    /** Extra websocket headers. */
+    headers?: Record<string, string>;
+    /** Logs packets: `true` uses `console.log`, a function receives the log arguments. */
+    debug?: DebugOption;
+    /** Custom websocket transport (proxies, tests). */
+    transport?: TransportFactory;
+    /** Custom `fetch` for the account lookup. */
+    fetch?: typeof fetch;
+    /** Time allowed to open and authenticate the connection. Default: 20 000 ms. */
+    connectTimeoutMs?: number;
+}
+export interface ClientEvents {
+    [event: string]: unknown[];
+    /** The websocket is open. */
+    open: [];
+    /** The server greeting was received. */
+    hello: [hello: ServerHello];
+    /** The auth token was sent; queued packets are now flowing. */
+    ready: [];
+    /** A server heartbeat was received (the client answers automatically). */
+    heartbeat: [id: number];
+    /** A packet not addressed to any session of this client. */
+    packet: [packet: ServerPacket];
+    /** The websocket closed. */
+    close: [code?: number, reason?: string];
+    error: [error: TradingViewError];
+}
+/** @internal Implemented by chart, replay and quote sessions. */
+export interface SessionHandler {
+    onPacket(packet: ServerPacket): void;
+    /** `expected` is true when the connection was closed with `client.close()`. */
+    onClose?(error: TradingViewError, expected: boolean): void;
+}
+/**
+ * One websocket connection to TradingView. Chart and quote sessions are
+ * multiplexed over it.
+ *
+ * The connection opens immediately; packets are queued until it is open and
+ * authenticated. Always call `close()` when you are done.
+ */
+export declare class TradingViewClient extends Emitter<ClientEvents> {
+    #private;
+    readonly ready: Promise<void>;
+    constructor(options?: ClientOptions);
+    /** True while the websocket is open. */
+    get isOpen(): boolean;
+    /** True once the auth token has been sent. */
+    get isAuthenticated(): boolean;
+    /** True after `close()` or a disconnection. */
+    get isClosed(): boolean;
+    /** Server greeting, once received. */
+    get serverInfo(): ServerHello | undefined;
+    /** Creates a chart session on this connection. */
+    createChart(): ChartSession;
+    /** Creates a quote session on this connection. */
+    createQuoteSession(options?: QuoteSessionOptions): QuoteSession;
+    /**
+     * Sends a raw packet. Packets are queued until the connection is ready.
+     * Prefer session methods; this is an escape hatch for unsupported commands.
+     */
+    send(method: string, params?: readonly unknown[]): void;
+    /** @internal Registers a session to receive its packets. */
+    registerSession(id: string, handler: SessionHandler): void;
+    /** @internal */
+    unregisterSession(id: string): void;
+    /** @internal Debug logger shared with sessions. */
+    log(...args: unknown[]): void;
+    /** Closes the connection. Resolves once the websocket is closed. Idempotent. */
+    close(): Promise<void>;
+}

package/dist/client/client.js

@@ -0,0 +1,254 @@
+import { TradingViewError, toTradingViewError } from '../errors.js';
+import { Emitter } from '../events.js';
+import { getUser } from '../http/account.js';
+import { DEFAULT_USER_AGENT } from '../http/request.js';
+import { decodeFrames, encodeHeartbeat, encodePacket, } from '../protocol/framing.js';
+import { wsTransport } from './transport.js';
+import { ChartSession } from '../chart/chart-session.js';
+import { QuoteSession } from '../quote/quote-session.js';
+/**
+ * One websocket connection to TradingView. Chart and quote sessions are
+ * multiplexed over it.
+ *
+ * The connection opens immediately; packets are queued until it is open and
+ * authenticated. Always call `close()` when you are done.
+ */
+export class TradingViewClient extends Emitter {
+    #transport;
+    #sessions = new Map();
+    #queue = [];
+    #log;
+    ready;
+    #authenticated = false;
+    #authToken;
+    #closed = false;
+    #closing = false;
+    #closeRequested = false;
+    #failure;
+    #hello;
+    #resolveReady;
+    #rejectReady;
+    #readyTimer;
+    #closeWaiters = [];
+    constructor(options = {}) {
+        super();
+        if (options.debug === true)
+            this.#log = (...args) => console.log('[tradingview]', ...args);
+        else if (typeof options.debug === 'function')
+            this.#log = options.debug;
+        this.ready = new Promise((resolve, reject) => {
+            this.#resolveReady = resolve;
+            this.#rejectReady = reject;
+        });
+        this.ready.catch(() => { });
+        const timeout = options.connectTimeoutMs ?? 20_000;
+        this.#readyTimer = setTimeout(() => {
+            this.#fail(new TradingViewError('TIMEOUT', `Connection not ready after ${timeout} ms`));
+        }, timeout);
+        const server = options.server ?? 'data';
+        const factory = options.transport ?? wsTransport;
+        this.#transport = factory({
+            url: `wss://${server}.tradingview.com/socket.io/websocket?from=chart&type=chart`,
+            origin: 'https://www.tradingview.com',
+            headers: {
+                'User-Agent': DEFAULT_USER_AGENT,
+                'Accept-Language': 'en-US,en;q=0.9',
+                'Cache-Control': 'no-cache',
+                Pragma: 'no-cache',
+                ...options.headers,
+            },
+        }, {
+            onOpen: () => this.#onOpen(),
+            onMessage: (data) => this.#onMessage(data),
+            onClose: (code, reason) => this.#onClose(code, reason),
+            onError: (error) => {
+                if (this.#closing)
+                    return;
+                this.#fail(new TradingViewError('CONNECTION_ERROR', `WebSocket error: ${error.message}`, { cause: error }));
+            },
+        });
+        if (options.authToken) {
+            this.#authToken = options.authToken;
+        }
+        else if (options.credentials?.session) {
+            getUser(options.credentials, { location: options.location, fetch: options.fetch })
+                .then((user) => {
+                if (this.#closed)
+                    return;
+                this.#authToken = user.authToken;
+                this.#authenticate();
+            })
+                .catch((error) => {
+                this.#fail(new TradingViewError('AUTH_ERROR', `Credentials error: ${toTradingViewError(error).message}`, {
+                    cause: error,
+                }));
+            });
+        }
+        else {
+            this.#authToken = 'unauthorized_user_token';
+        }
+    }
+    /** True while the websocket is open. */
+    get isOpen() {
+        return !this.#closed && this.#transport.isOpen;
+    }
+    /** True once the auth token has been sent. */
+    get isAuthenticated() {
+        return this.#authenticated;
+    }
+    /** True after `close()` or a disconnection. */
+    get isClosed() {
+        return this.#closed;
+    }
+    /** Server greeting, once received. */
+    get serverInfo() {
+        return this.#hello;
+    }
+    /** Creates a chart session on this connection. */
+    createChart() {
+        return new ChartSession(this);
+    }
+    /** Creates a quote session on this connection. */
+    createQuoteSession(options = {}) {
+        return new QuoteSession(this, options);
+    }
+    /**
+     * Sends a raw packet. Packets are queued until the connection is ready.
+     * Prefer session methods; this is an escape hatch for unsupported commands.
+     */
+    send(method, params = []) {
+        if (this.#closed) {
+            throw new TradingViewError('INVALID_STATE', `Cannot send '${method}': the client is closed`);
+        }
+        this.#queue.push(encodePacket(method, params));
+        this.#flush();
+    }
+    /** @internal Registers a session to receive its packets. */
+    registerSession(id, handler) {
+        this.#sessions.set(id, handler);
+    }
+    /** @internal */
+    unregisterSession(id) {
+        this.#sessions.delete(id);
+    }
+    /** @internal Debug logger shared with sessions. */
+    log(...args) {
+        this.#log?.(...args);
+    }
+    /** Closes the connection. Resolves once the websocket is closed. Idempotent. */
+    close() {
+        if (this.#closed)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            this.#closeWaiters.push(resolve);
+            this.#closeRequested = true;
+            if (this.#closing)
+                return;
+            this.#closing = true;
+            // Do not hang if the server never acknowledges the close.
+            setTimeout(() => this.#onClose(1000, 'Close timeout'), 3_000).unref?.();
+            this.#transport.close();
+        });
+    }
+    #onOpen() {
+        this.#log?.('open');
+        this.emit('open');
+        this.#authenticate();
+    }
+    #authenticate() {
+        if (this.#authenticated || !this.#authToken || !this.#transport.isOpen || this.#closing)
+            return;
+        this.#transport.send(encodePacket('set_auth_token', [this.#authToken]));
+        this.#authenticated = true;
+        clearTimeout(this.#readyTimer);
+        this.#resolveReady();
+        this.emit('ready');
+        this.#flush();
+    }
+    #flush() {
+        while (this.#authenticated && this.#transport.isOpen && this.#queue.length > 0) {
+            const packet = this.#queue.shift();
+            this.#log?.('send', packet);
+            this.#transport.send(packet);
+        }
+    }
+    #onMessage(data) {
+        if (this.#closed)
+            return;
+        for (const frame of decodeFrames(data)) {
+            if (frame.type === 'heartbeat') {
+                if (this.#transport.isOpen)
+                    this.#transport.send(encodeHeartbeat(frame.id));
+                this.emit('heartbeat', frame.id);
+                continue;
+            }
+            if (frame.type === 'invalid') {
+                this.#log?.('invalid frame', frame.raw);
+                continue;
+            }
+            if (frame.type === 'data') {
+                this.#log?.('data', frame.data);
+                const hello = frame.data;
+                if (hello && typeof hello === 'object' && 'session_id' in hello) {
+                    this.#hello = hello;
+                    this.emit('hello', hello);
+                }
+                continue;
+            }
+            const { packet } = frame;
+            this.#log?.('packet', packet);
+            if (packet.m === 'protocol_error') {
+                this.emit('error', new TradingViewError('PROTOCOL_ERROR', `Protocol error: ${String(packet.p[0] ?? '')}`, {
+                    details: packet.p,
+                }));
+                this.#transport.close();
+                continue;
+            }
+            const sessionId = packet.p[0];
+            const session = typeof sessionId === 'string' ? this.#sessions.get(sessionId) : undefined;
+            if (session)
+                session.onPacket(packet);
+            else
+                this.emit('packet', packet);
+        }
+    }
+    #fail(error) {
+        if (this.#closed)
+            return;
+        clearTimeout(this.#readyTimer);
+        const wasReady = this.#authenticated;
+        this.#failure ??= error;
+        this.#rejectReady(error);
+        // Before readiness, `ready` rejects with this error: only notify explicit listeners.
+        if (wasReady || this.hasListeners('error'))
+            this.emit('error', error);
+        if (!wasReady || error.code === 'AUTH_ERROR' || error.code === 'CONNECTION_ERROR') {
+            this.#closing = true;
+            this.#transport.close();
+            // Some transports never emit close after a failed handshake.
+            setTimeout(() => this.#onClose(undefined, error.message), 3_000).unref?.();
+        }
+    }
+    #onClose(code, reason) {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#authenticated = false;
+        clearTimeout(this.#readyTimer);
+        this.#log?.('close', code, reason);
+        const cause = this.#failure;
+        const why = cause?.message ?? reason;
+        const error = new TradingViewError('DISCONNECTED', `Connection closed${why ? `: ${why}` : ''}`, {
+            details: { code, reason },
+            cause,
+        });
+        this.#rejectReady(error);
+        for (const session of [...this.#sessions.values()])
+            session.onClose?.(error, this.#closeRequested);
+        this.#sessions.clear();
+        this.#queue.length = 0;
+        this.emit('close', code, reason);
+        for (const resolve of this.#closeWaiters.splice(0))
+            resolve();
+    }
+}

package/dist/client/index.d.ts

@@ -0,0 +1,4 @@
+export { TradingViewClient } from './client.js';
+export type { ClientEvents, ClientOptions, DebugOption, ServerName, SessionHandler, } from './client.js';
+export { wsTransport } from './transport.js';
+export type { Transport, TransportFactory, TransportHandlers, TransportRequest, } from './transport.js';

package/dist/client/index.js

@@ -0,0 +1,2 @@
+export { TradingViewClient } from './client.js';
+export { wsTransport } from './transport.js';

package/dist/client/transport.d.ts

@@ -0,0 +1,27 @@
+/** Callbacks a transport must call. */
+export interface TransportHandlers {
+    onOpen(): void;
+    onMessage(data: string): void;
+    onClose(code?: number, reason?: string): void;
+    onError(error: Error): void;
+}
+/** Minimal websocket abstraction used by `TradingViewClient`. */
+export interface Transport {
+    /** True when the connection is open and can send. */
+    readonly isOpen: boolean;
+    send(data: string): void;
+    /** Starts a graceful close. `onClose` must be called once closed. */
+    close(): void;
+}
+export interface TransportRequest {
+    url: string;
+    origin: string;
+    headers: Record<string, string>;
+}
+/**
+ * Creates a transport. The default uses the `ws` package (Node and Bun).
+ * Provide your own to use a proxy, another websocket library or a test double.
+ */
+export type TransportFactory = (request: TransportRequest, handlers: TransportHandlers) => Transport;
+/** Default transport based on the `ws` package. */
+export declare const wsTransport: TransportFactory;

package/dist/client/transport.js

@@ -0,0 +1,38 @@
+import WebSocket from 'ws';
+function toText(data) {
+    if (typeof data === 'string')
+        return data;
+    if (Array.isArray(data))
+        return Buffer.concat(data).toString('utf8');
+    if (data instanceof ArrayBuffer)
+        return Buffer.from(data).toString('utf8');
+    return data.toString('utf8');
+}
+/** Default transport based on the `ws` package. */
+export const wsTransport = (request, handlers) => {
+    // Bun's `ws` implementation ignores the `origin` option: also send it as a header.
+    const socket = new WebSocket(request.url, {
+        origin: request.origin,
+        headers: { Origin: request.origin, ...request.headers },
+    });
+    socket.on('open', () => handlers.onOpen());
+    socket.on('message', (data) => handlers.onMessage(toText(data)));
+    socket.on('close', (code, reason) => handlers.onClose(code, reason.toString()));
+    socket.on('error', (error) => handlers.onError(error));
+    return {
+        get isOpen() {
+            return socket.readyState === WebSocket.OPEN;
+        },
+        send(data) {
+            socket.send(data);
+        },
+        close() {
+            if (socket.readyState === WebSocket.CLOSED)
+                return;
+            if (socket.readyState === WebSocket.CONNECTING)
+                socket.terminate();
+            else
+                socket.close();
+        },
+    };
+};

package/dist/data/candles.d.ts

@@ -0,0 +1,40 @@
+import type { Candle, SymbolInfo } from '../chart/types.js';
+import type { CandleSourceWorker, MarketDataProvider } from './provider.js';
+import { type ChartQuery, type RangeQuery } from './history.js';
+import { type OperationOptions, type WatchHandlers, type Watcher } from './operation.js';
+export interface CandleQuery extends ChartQuery, RangeQuery, OperationOptions {
+}
+/**
+ * Fetches candles once, oldest first, then releases every resource.
+ *
+ * - `{ symbol, timeframe, count }`: the `count` most recent bars (deep history
+ *   is loaded automatically when `count` exceeds one server batch).
+ * - `{ symbol, timeframe, from, to }`: every bar in the range.
+ *
+ * @example
+ * const candles = await getCandles({ symbol: 'BINANCE:BTCUSDT', timeframe: '60', count: 500 });
+ */
+export declare function getCandles(query: CandleQuery | string, provider?: MarketDataProvider): Promise<Candle[]>;
+export type WatchCandlesQuery = ChartQuery & OperationOptions;
+export interface CandleHandlers extends WatchHandlers {
+    /** Receives a fresh immutable snapshot (oldest first) on every update. */
+    onData(candles: readonly Candle[]): void;
+}
+export interface CandleWatcher extends Watcher {
+    /** Latest snapshot, oldest first (at most `count` bars). */
+    readonly latest: readonly Candle[];
+    /** Symbol metadata. */
+    readonly symbolInfo: SymbolInfo | undefined;
+}
+/**
+ * Streams candles in real time. Resolves once the initial history is loaded
+ * (and already passed to `onData`); call `stop()` when finished.
+ *
+ * @example
+ * const watcher = await watchCandles({ symbol: 'BINANCE:BTCUSDT', timeframe: '1' }, {
+ *   onData: (candles) => console.log(candles.at(-1)?.close),
+ * });
+ * await watcher.stop();
+ */
+export declare function watchCandles(query: WatchCandlesQuery, handlers: CandleHandlers): Promise<CandleWatcher>;
+export declare function watchCandles(query: WatchCandlesQuery, handlers: CandleHandlers, provider: MarketDataProvider): Promise<CandleSourceWorker>;