@mathieuc/tradingview 3.5.2 → 4.0.0-beta.1

package/dist/protocol/ids.js

@@ -0,0 +1,10 @@
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+/** Creates a random session or request ID such as `cs_Ab12Cd34Ef56`. */
+export function createSessionId(prefix = 'xs') {
+    const bytes = new Uint8Array(12);
+    globalThis.crypto.getRandomValues(bytes);
+    let id = '';
+    for (const byte of bytes)
+        id += ALPHABET[byte % ALPHABET.length];
+    return `${prefix}_${id}`;
+}

package/dist/protocol/index.d.ts

@@ -0,0 +1,4 @@
+export { decodeFrames, encodeFrame, encodeHeartbeat, encodePacket, } from './framing.js';
+export type { Frame, ServerHello, ServerPacket } from './framing.js';
+export { decodeCompressed, normaliseBase64, readFirstZipEntry } from './compression.js';
+export { createSessionId } from './ids.js';

package/dist/protocol/index.js

@@ -0,0 +1,3 @@
+export { decodeFrames, encodeFrame, encodeHeartbeat, encodePacket, } from './framing.js';
+export { decodeCompressed, normaliseBase64, readFirstZipEntry } from './compression.js';
+export { createSessionId } from './ids.js';

package/dist/quote/fields.d.ts

@@ -0,0 +1,35 @@
+/** Quote fields TradingView can stream. Other field names are accepted too. */
+export type QuoteField = 'base-currency-logoid' | 'ch' | 'chp' | 'currency-logoid' | 'provider_id' | 'currency_code' | 'current_session' | 'description' | 'exchange' | 'format' | 'fractional' | 'is_tradable' | 'language' | 'local_description' | 'logoid' | 'lp' | 'lp_time' | 'minmov' | 'minmove2' | 'original_name' | 'pricescale' | 'pro_name' | 'short_name' | 'type' | 'update_mode' | 'volume' | 'ask' | 'bid' | 'fundamentals' | 'high_price' | 'low_price' | 'open_price' | 'prev_close_price' | 'rch' | 'rchp' | 'rtc' | 'rtc_time' | 'status' | 'industry' | 'basic_eps_net_income' | 'beta_1_year' | 'market_cap_basic' | 'earnings_per_share_basic_ttm' | 'price_earnings_ttm' | 'sector' | 'dividends_yield' | 'timezone' | 'country_code' | (string & {});
+/** `all` requests every known field, `price` only the last price (`lp`). */
+export type QuoteFieldPreset = 'all' | 'price';
+export declare const ALL_QUOTE_FIELDS: readonly QuoteField[];
+/** Resolves a preset or explicit list into field names. */
+export declare function resolveQuoteFields(fields?: QuoteFieldPreset | readonly QuoteField[]): QuoteField[];
+/**
+ * Latest quote values. Only requested fields that TradingView sent are
+ * present; numbers are raw server values.
+ */
+export interface QuoteData {
+    /** Last price. */
+    lp?: number;
+    /** Time of the last price (Unix seconds). */
+    lp_time?: number;
+    /** Change since previous close. */
+    ch?: number;
+    /** Change since previous close, in percent. */
+    chp?: number;
+    bid?: number;
+    ask?: number;
+    volume?: number;
+    open_price?: number;
+    high_price?: number;
+    low_price?: number;
+    prev_close_price?: number;
+    description?: string;
+    short_name?: string;
+    pro_name?: string;
+    exchange?: string;
+    currency_code?: string;
+    type?: string;
+    [field: string]: unknown;
+}

package/dist/quote/fields.js

@@ -0,0 +1,21 @@
+export const ALL_QUOTE_FIELDS = [
+    'base-currency-logoid', 'ch', 'chp', 'currency-logoid',
+    'currency_code', 'current_session', 'description',
+    'exchange', 'format', 'fractional', 'is_tradable',
+    'language', 'local_description', 'logoid', 'lp',
+    'lp_time', 'minmov', 'minmove2', 'original_name',
+    'pricescale', 'pro_name', 'short_name', 'type',
+    'update_mode', 'volume', 'ask', 'bid', 'fundamentals',
+    'high_price', 'low_price', 'open_price', 'prev_close_price',
+    'rch', 'rchp', 'rtc', 'rtc_time', 'status', 'industry',
+    'basic_eps_net_income', 'beta_1_year', 'market_cap_basic',
+    'earnings_per_share_basic_ttm', 'price_earnings_ttm',
+    'sector', 'dividends_yield', 'timezone', 'country_code',
+    'provider_id',
+];
+/** Resolves a preset or explicit list into field names. */
+export function resolveQuoteFields(fields = 'all') {
+    if (Array.isArray(fields))
+        return fields.length ? [...fields] : [...ALL_QUOTE_FIELDS];
+    return fields === 'price' ? ['lp'] : [...ALL_QUOTE_FIELDS];
+}

package/dist/quote/index.d.ts

@@ -0,0 +1,4 @@
+export { QuoteSession, QuoteSubscription, quoteSymbolKey } from './quote-session.js';
+export type { QuoteSessionEvents, QuoteSessionOptions, QuoteSubscriptionEvents, QuoteSubscriptionOptions, } from './quote-session.js';
+export { ALL_QUOTE_FIELDS, resolveQuoteFields } from './fields.js';
+export type { QuoteData, QuoteField, QuoteFieldPreset } from './fields.js';

package/dist/quote/index.js

@@ -0,0 +1,2 @@
+export { QuoteSession, QuoteSubscription, quoteSymbolKey } from './quote-session.js';
+export { ALL_QUOTE_FIELDS, resolveQuoteFields } from './fields.js';

package/dist/quote/quote-session.d.ts

@@ -0,0 +1,73 @@
+import type { TradingViewClient } from '../client/client.js';
+import { TradingViewError } from '../errors.js';
+import { Emitter } from '../events.js';
+import type { TradingSession } from '../chart/types.js';
+import type { ServerPacket } from '../protocol/framing.js';
+import { type QuoteData, type QuoteField, type QuoteFieldPreset } from './fields.js';
+export interface QuoteSessionOptions {
+    /** `all` (default), `price`, or an explicit list of fields. */
+    fields?: QuoteFieldPreset | readonly QuoteField[];
+}
+export interface QuoteSubscriptionOptions {
+    /** Trading session. Default: `regular`. */
+    session?: TradingSession;
+}
+export interface QuoteSubscriptionEvents {
+    [event: string]: unknown[];
+    /** Initial values were received. */
+    loaded: [];
+    /** New values. `quote` is the merged snapshot, `changes` only the new fields. */
+    data: [quote: QuoteData, changes: QuoteData];
+    error: [error: TradingViewError];
+}
+export interface QuoteSessionEvents {
+    [event: string]: unknown[];
+    error: [error: TradingViewError];
+}
+/** Key identifying a symbol + session in quote packets. */
+export declare function quoteSymbolKey(symbol: string, session?: TradingSession): string;
+/** Live quotes for one symbol. Create it with `quoteSession.subscribe()`. */
+export declare class QuoteSubscription extends Emitter<QuoteSubscriptionEvents> {
+    #private;
+    readonly symbol: string;
+    readonly session: TradingSession;
+    /** @internal */
+    readonly key: string;
+    /** @internal Use `quoteSession.subscribe()`. */
+    constructor(symbol: string, session: TradingSession, onClose: (subscription: QuoteSubscription) => void);
+    /** Latest merged values. */
+    get data(): QuoteData;
+    /** True after the initial values were received. */
+    get isLoaded(): boolean;
+    get isClosed(): boolean;
+    /** Stops receiving quotes for this subscription. Idempotent. */
+    close(): void;
+    /** @internal Copies the state of a loaded subscription to the same symbol. */
+    seed(source: QuoteSubscription): void;
+    /** @internal */
+    handlePacket(packet: ServerPacket): void;
+    /** @internal */
+    handleClose(error: TradingViewError, expected: boolean): void;
+}
+/**
+ * A set of live quote subscriptions sharing the same fields.
+ * Create it with `client.createQuoteSession()`.
+ */
+export declare class QuoteSession extends Emitter<QuoteSessionEvents> {
+    #private;
+    readonly id: string;
+    readonly client: TradingViewClient;
+    constructor(client: TradingViewClient, options?: QuoteSessionOptions);
+    /** Requested fields. */
+    get fields(): readonly QuoteField[];
+    get isDeleted(): boolean;
+    /** Changes the requested fields for every subscription. */
+    setFields(fields: QuoteFieldPreset | readonly QuoteField[]): void;
+    /**
+     * Subscribes to a symbol. Several subscriptions to the same symbol share
+     * one server subscription.
+     */
+    subscribe(symbol: string, options?: QuoteSubscriptionOptions): QuoteSubscription;
+    /** Deletes the session and all its subscriptions. Idempotent. */
+    delete(): void;
+}

package/dist/quote/quote-session.js

@@ -0,0 +1,205 @@
+import { TradingViewError } from '../errors.js';
+import { Emitter } from '../events.js';
+import { createSessionId } from '../protocol/ids.js';
+import { resolveQuoteFields, } from './fields.js';
+/** Key identifying a symbol + session in quote packets. */
+export function quoteSymbolKey(symbol, session = 'regular') {
+    return `=${JSON.stringify({ session, symbol })}`;
+}
+/** Live quotes for one symbol. Create it with `quoteSession.subscribe()`. */
+export class QuoteSubscription extends Emitter {
+    symbol;
+    session;
+    /** @internal */
+    key;
+    #onClose;
+    #data = {};
+    #loaded = false;
+    #closed = false;
+    /** @internal Use `quoteSession.subscribe()`. */
+    constructor(symbol, session, onClose) {
+        super();
+        this.symbol = symbol;
+        this.session = session;
+        this.key = quoteSymbolKey(symbol, session);
+        this.#onClose = onClose;
+    }
+    /** Latest merged values. */
+    get data() {
+        return { ...this.#data };
+    }
+    /** True after the initial values were received. */
+    get isLoaded() {
+        return this.#loaded;
+    }
+    get isClosed() {
+        return this.#closed;
+    }
+    /** Stops receiving quotes for this subscription. Idempotent. */
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#onClose(this);
+    }
+    /** @internal Copies the state of a loaded subscription to the same symbol. */
+    seed(source) {
+        if (!source.isLoaded)
+            return;
+        queueMicrotask(() => {
+            if (this.#closed || this.#loaded)
+                return;
+            this.#data = source.data;
+            this.#loaded = true;
+            this.emit('data', this.data, this.data);
+            this.emit('loaded');
+        });
+    }
+    /** @internal */
+    handlePacket(packet) {
+        if (this.#closed)
+            return;
+        if (packet.m === 'quote_completed') {
+            this.#loaded = true;
+            this.emit('loaded');
+            return;
+        }
+        const payload = packet.p[1];
+        if (payload?.s === 'ok') {
+            const changes = { ...payload.v };
+            this.#data = { ...this.#data, ...changes };
+            this.emit('data', this.data, changes);
+        }
+        else if (payload?.s === 'error') {
+            this.emit('error', new TradingViewError('QUOTE_ERROR', `Quote error (${this.symbol}): ${payload.errmsg ?? 'unknown'}`, {
+                details: packet.p,
+            }));
+        }
+    }
+    /** @internal */
+    handleClose(error, expected) {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        if (!expected)
+            this.emit('error', error);
+    }
+}
+/**
+ * A set of live quote subscriptions sharing the same fields.
+ * Create it with `client.createQuoteSession()`.
+ */
+export class QuoteSession extends Emitter {
+    id = createSessionId('qs');
+    client;
+    #subscriptions = new Map();
+    #fields;
+    #deleted = false;
+    constructor(client, options = {}) {
+        super();
+        this.client = client;
+        this.#fields = resolveQuoteFields(options.fields);
+        client.registerSession(this.id, {
+            onPacket: (packet) => this.#onPacket(packet),
+            onClose: (error, expected) => this.#onClientClose(error, expected),
+        });
+        client.send('quote_create_session', [this.id]);
+        client.send('quote_set_fields', [this.id, ...this.#fields]);
+    }
+    /** Requested fields. */
+    get fields() {
+        return this.#fields;
+    }
+    get isDeleted() {
+        return this.#deleted;
+    }
+    /** Changes the requested fields for every subscription. */
+    setFields(fields) {
+        this.#assertAlive();
+        this.#fields = resolveQuoteFields(fields);
+        this.client.send('quote_set_fields', [this.id, ...this.#fields]);
+    }
+    /**
+     * Subscribes to a symbol. Several subscriptions to the same symbol share
+     * one server subscription.
+     */
+    subscribe(symbol, options = {}) {
+        this.#assertAlive();
+        if (!symbol)
+            throw new TradingViewError('INVALID_ARGUMENT', 'A symbol is required');
+        const subscription = new QuoteSubscription(symbol, options.session ?? 'regular', (sub) => this.#release(sub));
+        let set = this.#subscriptions.get(subscription.key);
+        if (!set) {
+            set = new Set();
+            this.#subscriptions.set(subscription.key, set);
+            this.client.send('quote_add_symbols', [this.id, subscription.key]);
+        }
+        else {
+            const loaded = [...set].find((sub) => sub.isLoaded);
+            if (loaded)
+                subscription.seed(loaded);
+        }
+        set.add(subscription);
+        return subscription;
+    }
+    /** Deletes the session and all its subscriptions. Idempotent. */
+    delete() {
+        if (this.#deleted)
+            return;
+        this.#deleted = true;
+        if (!this.client.isClosed)
+            this.client.send('quote_delete_session', [this.id]);
+        this.client.unregisterSession(this.id);
+        for (const set of this.#subscriptions.values())
+            for (const sub of set)
+                sub.close();
+        this.#subscriptions.clear();
+    }
+    #release(subscription) {
+        const set = this.#subscriptions.get(subscription.key);
+        if (!set?.delete(subscription))
+            return;
+        if (set.size === 0) {
+            this.#subscriptions.delete(subscription.key);
+            if (!this.#deleted && !this.client.isClosed) {
+                this.client.send('quote_remove_symbols', [this.id, subscription.key]);
+            }
+        }
+    }
+    #assertAlive() {
+        if (this.#deleted)
+            throw new TradingViewError('INVALID_STATE', 'The quote session is deleted');
+    }
+    #onClientClose(error, expected) {
+        if (this.#deleted)
+            return;
+        this.#deleted = true;
+        if (!expected)
+            this.emit('error', error);
+        for (const set of this.#subscriptions.values())
+            for (const sub of set)
+                sub.handleClose(error, expected);
+        this.#subscriptions.clear();
+    }
+    #onPacket(packet) {
+        this.client.log('quote', this.id, packet);
+        let key;
+        if (packet.m === 'quote_completed')
+            key = String(packet.p[1]);
+        else if (packet.m === 'qsd')
+            key = packet.p[1]?.n;
+        else
+            return;
+        if (key === undefined)
+            return;
+        const set = this.#subscriptions.get(key);
+        if (!set) {
+            // Data for a symbol nobody listens to anymore.
+            if (!this.#deleted && !this.client.isClosed)
+                this.client.send('quote_remove_symbols', [this.id, key]);
+            return;
+        }
+        for (const sub of [...set])
+            sub.handlePacket(packet);
+    }
+}

package/docs/README.es.md

@@ -0,0 +1,58 @@
+# TradingView-API
+
+**Pruébalo con un agente alojado:** [Crea un vigilante de mercado en Molted Studio](https://molted.studio/dreams/market-watch-alerts) — sin instalación local.
+
+<a href="https://trendshift.io/repositories/26416?utm_source=repository-badge&amp;utm_medium=badge&amp;utm_campaign=badge-repository-26416" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/26416" alt="Mathieu2301/TradingView-API | #1 Repo Of The Day on Trendshift" width="250" height="55"/></a>
+
+**Idioma:** [English](../README.md) · [Français](README.fr.md) · Español · [Português](README.pt.md)
+
+**Datos de mercado e indicadores para construir tus herramientas.** Velas, cotizaciones, indicadores y estrategias, en una sola petición o en tiempo real. Proyecto comunitario independiente y no oficial.
+
+> **¿Tienes un problema, una pregunta o una idea? [Abre un issue](https://github.com/Mathieu2301/TradingView-API/issues/new/choose).** No necesitas una reproducción perfecta para preguntar.
+
+> **La versión 4 es una reescritura completa en TypeScript**, con una nueva API y sin capa de compatibilidad. ¿Vienes de la v3? Lee la [guía de migración](migration-v4.md) (en inglés). Todas las funciones de la v3 siguen disponibles: consulta la [matriz de cobertura](v4-coverage.md). Las versiones npm 3.x mantienen la API `Client` anterior.
+
+## Elige cómo empezar
+
+- **Instalación de V4 beta:** clona este repositorio y ejecuta `npm ci && npm run build && node examples/candles.js` (Node.js 20+ o Bun). **npm todavía entrega V3**, no las importaciones V4 de abajo. Consulta los [ejemplos](../examples).
+- **Con Claude Code, Codex, OpenClaw u otro asistente:** comparte este repositorio y la [guía de la API de datos](data-api.md).
+- **Sin instalación local:** [Molted](https://molted.cloud/) ofrece un espacio de trabajo con agente alojado que puede trabajar desde este repositorio. Es opcional.
+
+## API de datos
+
+```ts
+import { getCandles, watchCandles, getQuote } from '@mathieuc/tradingview/data';
+
+const candles = await getCandles({ symbol: 'BINANCE:BTCUSDT', timeframe: 'D', count: 100 });
+console.log(candles.at(-1)); // { time, open, high, low, close, volume }, de la más antigua a la más reciente
+
+const quote = await getQuote('BINANCE:BTCUSDT');
+
+const watcher = await watchCandles({ symbol: 'BINANCE:BTCUSDT', timeframe: '1' }, {
+  onData: (snapshot) => console.log(snapshot.at(-1)?.close),
+  onError: console.error,
+});
+await watcher.stop();
+```
+
+Cada función gestiona la conexión, el tiempo máximo (`timeoutMs`), la cancelación (`signal`) y la limpieza. Otras funciones: `getQuotes`, `watchQuotes`, `getSymbolInfo`, `getIndicatorData`, `watchIndicator`, `searchMarkets`, `searchIndicators`, `getTechnicalAnalysis`. Detalles: [guía de la API de datos](data-api.md).
+
+## API de bajo nivel
+
+```ts
+import { TradingViewClient } from '@mathieuc/tradingview';
+
+const client = new TradingViewClient();
+const chart = client.createChart();
+chart.on('update', () => console.log(chart.lastCandle?.close));
+chart.setMarket('BINANCE:BTCUSDT', { timeframe: 'D' });
+// Al terminar: await client.close();
+```
+
+Gráficos, modo replay, estudios Pine e integrados, cotizaciones, cuentas, dibujos y permisos Pine: consulta la [referencia de bajo nivel](low-level-api.md) y los [ejemplos](../examples).
+
+Sin cuenta, TradingView limita los datos (menos historial intradía, sin indicadores Pine). Con tus cookies `sessionid` y `sessionid_sign` (`credentials`), accedes a lo que permite tu cuenta. Guárdalas en variables de entorno, nunca en el código, issues o prompts.
+
+[Repositorio GitHub](https://github.com/Mathieu2301/TradingView-API) · [Paquete npm](https://www.npmjs.com/package/@mathieuc/tradingview) · [Issues](https://github.com/Mathieu2301/TradingView-API/issues/new/choose)
+
+TradingView es una marca de su propietario. Este proyecto no está afiliado ni respaldado por TradingView. Revisa los términos y permisos de datos de tu proveedor.

package/docs/README.fr.md

@@ -0,0 +1,58 @@
+# TradingView-API
+
+**Essayez avec un agent hébergé :** [Créez votre veille de marché sur Molted Studio](https://molted.studio/fr/dreams/market-watch-alerts) — sans installation locale.
+
+<a href="https://trendshift.io/repositories/26416?utm_source=repository-badge&amp;utm_medium=badge&amp;utm_campaign=badge-repository-26416" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/26416" alt="Mathieu2301/TradingView-API | #1 Repo Of The Day on Trendshift" width="250" height="55"/></a>
+
+**Langue :** [English](../README.md) · Français · [Español](README.es.md) · [Português](README.pt.md)
+
+**Des données de marché et des indicateurs pour construire vos outils.** Bougies, cotations, indicateurs et stratégies, en une requête ou en temps réel. Projet communautaire indépendant, non officiel.
+
+> **Un problème, une question ou une idée ? [Ouvrez une issue](https://github.com/Mathieu2301/TradingView-API/issues/new/choose).** Pas besoin d'avoir déjà une reproduction parfaite.
+
+> **La version 4 est une réécriture complète en TypeScript**, avec une nouvelle API et sans couche de compatibilité. Vous venez de la v3 ? Lisez le [guide de migration](migration-v4.md) (en anglais). Toutes les fonctionnalités de la v3 restent disponibles : voir la [matrice de couverture](v4-coverage.md). Les versions npm 3.x gardent l'ancienne API `Client`.
+
+## Choisissez votre parcours
+
+- **Installation de la V4 bêta :** clonez ce dépôt, puis lancez `npm ci && npm run build && node examples/candles.js` (Node.js 20+ ou Bun). **npm fournit encore la V3**, pas les imports V4 ci-dessous. Consultez les [exemples](../examples).
+- **Avec Claude Code, Codex, OpenClaw ou un autre assistant :** donnez-lui ce dépôt et le [guide de l'API de données](data-api.md).
+- **Sans installation locale :** [Molted](https://molted.cloud/) propose un espace d'agent hébergé pouvant travailler à partir de ce dépôt. Ce choix est facultatif.
+
+## API de données
+
+```ts
+import { getCandles, watchCandles, getQuote } from '@mathieuc/tradingview/data';
+
+const candles = await getCandles({ symbol: 'BINANCE:BTCUSDT', timeframe: 'D', count: 100 });
+console.log(candles.at(-1)); // { time, open, high, low, close, volume }, du plus ancien au plus récent
+
+const quote = await getQuote('BINANCE:BTCUSDT');
+
+const watcher = await watchCandles({ symbol: 'BINANCE:BTCUSDT', timeframe: '1' }, {
+  onData: (snapshot) => console.log(snapshot.at(-1)?.close),
+  onError: console.error,
+});
+await watcher.stop();
+```
+
+Chaque fonction gère la connexion, le délai maximal (`timeoutMs`), l'annulation (`signal`) et le nettoyage. Autres fonctions : `getQuotes`, `watchQuotes`, `getSymbolInfo`, `getIndicatorData`, `watchIndicator`, `searchMarkets`, `searchIndicators`, `getTechnicalAnalysis`. Détails : [guide de l'API de données](data-api.md).
+
+## API bas niveau
+
+```ts
+import { TradingViewClient } from '@mathieuc/tradingview';
+
+const client = new TradingViewClient();
+const chart = client.createChart();
+chart.on('update', () => console.log(chart.lastCandle?.close));
+chart.setMarket('BINANCE:BTCUSDT', { timeframe: 'D' });
+// À la fin : await client.close();
+```
+
+Graphiques, mode replay, études Pine et intégrées, cotations, comptes, dessins et permissions Pine : voir la [référence bas niveau](low-level-api.md) et les [exemples](../examples).
+
+Sans compte, TradingView limite les données (historique intraday réduit, pas d'indicateurs Pine). Avec vos cookies `sessionid` et `sessionid_sign` (`credentials`), vous accédez à ce que permet votre compte. Gardez-les dans des variables d'environnement, jamais dans le code, les issues ou les prompts.
+
+[Dépôt GitHub](https://github.com/Mathieu2301/TradingView-API) · [Package npm](https://www.npmjs.com/package/@mathieuc/tradingview) · [Issues](https://github.com/Mathieu2301/TradingView-API/issues/new/choose)
+
+TradingView est une marque de son propriétaire. Ce projet n'est ni affilié ni approuvé par TradingView. Vérifiez les conditions d'utilisation et droits sur les données de votre fournisseur.

package/docs/README.pt.md

@@ -0,0 +1,58 @@
+# TradingView-API
+
+**Experimente com um agente hospedado:** [Crie um monitor de mercado no Molted Studio](https://molted.studio/dreams/market-watch-alerts) — sem instalação local.
+
+<a href="https://trendshift.io/repositories/26416?utm_source=repository-badge&amp;utm_medium=badge&amp;utm_campaign=badge-repository-26416" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/26416" alt="Mathieu2301/TradingView-API | #1 Repo Of The Day on Trendshift" width="250" height="55"/></a>
+
+**Idioma:** [English](../README.md) · [Français](README.fr.md) · [Español](README.es.md) · Português
+
+**Dados de mercado e indicadores para construir suas ferramentas.** Candles, cotações, indicadores e estratégias, em uma única requisição ou em tempo real. Projeto comunitário independente e não oficial.
+
+> **Tem um problema, uma dúvida ou uma ideia? [Abra uma issue](https://github.com/Mathieu2301/TradingView-API/issues/new/choose).** Não é preciso ter uma reprodução perfeita para perguntar.
+
+> **A versão 4 é uma reescrita completa em TypeScript**, com uma nova API e sem camada de compatibilidade. Vindo da v3? Leia o [guia de migração](migration-v4.md) (em inglês). Todos os recursos da v3 continuam disponíveis: veja a [matriz de cobertura](v4-coverage.md). As versões npm 3.x mantêm a API `Client` anterior.
+
+## Escolha como começar
+
+- **Instalação da V4 beta:** clone este repositório e execute `npm ci && npm run build && node examples/candles.js` (Node.js 20+ ou Bun). **O npm ainda entrega a V3**, não os imports V4 abaixo. Consulte os [exemplos](../examples).
+- **Com Claude Code, Codex, OpenClaw ou outro assistente:** compartilhe este repositório e o [guia da API de dados](data-api.md).
+- **Sem instalação local:** o [Molted](https://molted.cloud/) oferece um espaço de agente hospedado que pode trabalhar a partir deste repositório. É opcional.
+
+## API de dados
+
+```ts
+import { getCandles, watchCandles, getQuote } from '@mathieuc/tradingview/data';
+
+const candles = await getCandles({ symbol: 'BINANCE:BTCUSDT', timeframe: 'D', count: 100 });
+console.log(candles.at(-1)); // { time, open, high, low, close, volume }, do mais antigo ao mais recente
+
+const quote = await getQuote('BINANCE:BTCUSDT');
+
+const watcher = await watchCandles({ symbol: 'BINANCE:BTCUSDT', timeframe: '1' }, {
+  onData: (snapshot) => console.log(snapshot.at(-1)?.close),
+  onError: console.error,
+});
+await watcher.stop();
+```
+
+Cada função cuida da conexão, do tempo máximo (`timeoutMs`), do cancelamento (`signal`) e da limpeza. Outras funções: `getQuotes`, `watchQuotes`, `getSymbolInfo`, `getIndicatorData`, `watchIndicator`, `searchMarkets`, `searchIndicators`, `getTechnicalAnalysis`. Detalhes: [guia da API de dados](data-api.md).
+
+## API de baixo nível
+
+```ts
+import { TradingViewClient } from '@mathieuc/tradingview';
+
+const client = new TradingViewClient();
+const chart = client.createChart();
+chart.on('update', () => console.log(chart.lastCandle?.close));
+chart.setMarket('BINANCE:BTCUSDT', { timeframe: 'D' });
+// Ao terminar: await client.close();
+```
+
+Gráficos, modo replay, estudos Pine e integrados, cotações, contas, desenhos e permissões Pine: veja a [referência de baixo nível](low-level-api.md) e os [exemplos](../examples).
+
+Sem conta, o TradingView limita os dados (menos histórico intraday, sem indicadores Pine). Com seus cookies `sessionid` e `sessionid_sign` (`credentials`), você acessa o que sua conta permite. Guarde-os em variáveis de ambiente, nunca no código, em issues ou prompts.
+
+[Repositório GitHub](https://github.com/Mathieu2301/TradingView-API) · [Pacote npm](https://www.npmjs.com/package/@mathieuc/tradingview) · [Issues](https://github.com/Mathieu2301/TradingView-API/issues/new/choose)
+
+TradingView é uma marca do seu proprietário. Este projeto não é afiliado nem endossado pelo TradingView. Verifique os termos e permissões de dados do seu provedor.