@mathieuc/tradingview 4.0.0-beta.4 → 4.0.0-rc.0

package/examples/errors.js

@@ -0,0 +1,44 @@
+// Every error is a TradingViewError with a `code`.
+// Run: npm run build && node --env-file=.env examples/errors.js
+import {
+  getCandles, getIndicator, getIndicatorData, TradingViewClient, TradingViewError,
+} from '@mathieuc/tradingview';
+
+const credentials = process.env.SESSION
+  ? { session: process.env.SESSION, signature: process.env.SIGNATURE }
+  : undefined;
+
+async function show(title, run) {
+  try {
+    await run();
+    console.log(`${title}: no error`);
+  } catch (error) {
+    if (!(error instanceof TradingViewError)) throw error;
+    console.log(`${title}: [${error.code}] ${error.message}`);
+  }
+}
+
+await show('Wrong credentials', () => new TradingViewClient({ credentials: { session: 'FAKE' } }).ready);
+await show('Invalid symbol', () => getCandles('XXXXX'));
+await show('Invalid timeframe', () => getCandles({ symbol: 'BINANCE:BTCEUR', timeframe: 'XX' }));
+await show('Premium chart type without account', () => getCandles({ symbol: 'BINANCE:BTCEUR', timeframe: '15', chartType: 'Renko' }));
+await show('Inexistent indicator', () => getIndicator('STD;XXXXXXX'));
+await show('Timeout', () => getCandles({ symbol: 'BINANCE:BTCEUR', timeoutMs: 1 }));
+
+// Low-level sessions report errors through their `error` event.
+const client = new TradingViewClient();
+const chart = client.createChart();
+await show('Invalid timezone', () => new Promise((resolve, reject) => {
+  chart.on('error', reject);
+  chart.setMarket('BINANCE:BTCEUR');
+  chart.setTimezone('Nowhere/Nowhere');
+  setTimeout(resolve, 5_000);
+}));
+await show('Timeframe before market', async () => client.createChart().setTimeframe('15'));
+await client.close();
+
+if (credentials) {
+  const supertrend = await getIndicator('STD;Supertrend');
+  supertrend.setInput('Factor', -1);
+  await show('Invalid study input', () => getIndicatorData({ symbol: 'BINANCE:BTCEUR', indicator: supertrend, credentials }));
+}

package/examples/fake-replay.js

@@ -0,0 +1,24 @@
+// "Fake replay": walk forward from a past date by loading newer bars, which
+// also works on intraday timeframes without an account.
+// Run: npm run build && node examples/fake-replay.js
+import { TradingViewClient } from '@mathieuc/tradingview';
+
+const client = new TradingViewClient();
+const chart = client.createChart();
+
+chart.setMarket('BINANCE:BTCEUR', {
+  timeframe: '240',
+  count: -1, // Negative: load bars after `to` instead of before
+  to: Math.round(Date.now() / 1000) - 86_400 * 7, // Seven days ago
+});
+
+chart.on('seriesCompleted', async () => {
+  const last = chart.lastCandle;
+  console.log('Next ->', last && new Date(last.time * 1000).toISOString(), `(${chart.candles.length} bars)`);
+  if (!last || last.time > Date.now() / 1000 - 86_400) {
+    await client.close();
+    console.log('Done');
+    return;
+  }
+  chart.fetchMore(-2); // Two newer bars
+});

package/examples/from-to.js

@@ -0,0 +1,25 @@
+// Bars before or after a reference time, with an indicator on the same chart.
+// The reference time needs an account with enough history access.
+// Run: npm run build && node --env-file=.env examples/from-to.js
+import { getCandles, getIndicator, TradingViewClient } from '@mathieuc/tradingview';
+
+if (!process.env.SESSION || !process.env.SIGNATURE) throw new Error('Please set your SESSION and SIGNATURE cookies');
+const credentials = { session: process.env.SESSION, signature: process.env.SIGNATURE };
+
+// High level: every 4h bar between two dates.
+const range = await getCandles({
+  symbol: 'BINANCE:BTCEUR', timeframe: '240', from: new Date('2023-11-01'), to: new Date('2023-11-14'), credentials,
+});
+console.log(`${range.length} bars from ${new Date(range[0].time * 1000).toISOString()}`);
+
+// Low level: 2 bars before a timestamp (negative counts load bars after it) and a study.
+const client = new TradingViewClient({ credentials });
+const chart = client.createChart();
+chart.setMarket('BINANCE:BTCEUR', { timeframe: '240', count: 2, to: 1_700_000_000 });
+
+const supertrend = chart.createStudy(await getIndicator('STD;Supertrend'));
+supertrend.on('ready', async () => {
+  console.log('Prices:', chart.candles);
+  console.log('Study:', supertrend.values.slice(-2));
+  await client.close();
+});

package/examples/graphic-indicator.js

@@ -0,0 +1,18 @@
+// Indicators that draw labels, lines, boxes, tables, polygons...
+// Run: npm run build && node --env-file=.env examples/graphic-indicator.js
+import { getIndicatorData } from '@mathieuc/tradingview/data';
+
+if (!process.env.SESSION || !process.env.SIGNATURE) throw new Error('Please set your SESSION and SIGNATURE cookies');
+
+const { indicator, graphics } = await getIndicatorData({
+  symbol: 'BINANCE:BTCEUR',
+  timeframe: '5',
+  count: 1_000,
+  indicator: 'STD;Zig_Zag',
+  credentials: { session: process.env.SESSION, signature: process.env.SIGNATURE },
+});
+
+console.log(`'${indicator.description}' graphics:`);
+console.log('Lines:', graphics.lines.slice(0, 5)); // x positions are bars back from the latest bar
+console.log('Labels:', graphics.labels.slice(0, 5));
+console.log('Tables:', graphics.tables.map((t) => t.cells.map((row) => row.map((cell) => cell.text))));

package/examples/indicator-data.js

@@ -0,0 +1,23 @@
+// Indicator values with the high-level data API.
+// Pine indicators (STD;..., PUB;..., USER;...) need an account: set SESSION and SIGNATURE.
+// Run: npm run build && node --env-file=.env examples/indicator-data.js
+import { getIndicatorData } from '@mathieuc/tradingview/data';
+
+const credentials = process.env.SESSION
+  ? { session: process.env.SESSION, signature: process.env.SIGNATURE }
+  : undefined;
+
+// A built-in study works without an account.
+const volume = await getIndicatorData({ symbol: 'BINANCE:BTCEUR', indicator: 'Volume@tv-basicstudies-241', count: 5 });
+console.log('Volume rows:', volume.values);
+
+if (credentials) {
+  const rsi = await getIndicatorData({
+    symbol: 'BINANCE:BTCEUR',
+    timeframe: '60',
+    indicator: 'STD;RSI',
+    inputs: { Length: 21 }, // Input ID, number, inline name or internal ID
+    credentials,
+  });
+  console.log('Last RSI row:', rsi.values.at(-1));
+} else console.log('Set SESSION and SIGNATURE to run a Pine indicator');

package/examples/multiple-indicators.js

@@ -0,0 +1,16 @@
+// Several indicators in parallel over one shared connection.
+// Run: npm run build && node --env-file=.env examples/multiple-indicators.js
+import { getIndicatorData, TradingViewClient } from '@mathieuc/tradingview';
+
+if (!process.env.SESSION || !process.env.SIGNATURE) throw new Error('Please set your SESSION and SIGNATURE cookies');
+const credentials = { session: process.env.SESSION, signature: process.env.SIGNATURE };
+
+const client = new TradingViewClient({ credentials });
+try {
+  const results = await Promise.all(['STD;RSI', 'STD;MACD', 'STD;Bollinger_Bands'].map((indicator) => (
+    getIndicatorData({ symbol: 'BINANCE:DOTUSDT', indicator, client, credentials })
+  )));
+  for (const { indicator, values } of results) console.log(indicator.description, values.at(-1));
+} finally {
+  await client.close();
+}

package/examples/pine-permissions.js

@@ -0,0 +1,18 @@
+// Manage who can use an invite-only script you own.
+// Run: npm run build && node --env-file=.env examples/pine-permissions.js <PUB;pineId>
+import { PinePermissionManager } from '@mathieuc/tradingview';
+
+if (!process.env.SESSION || !process.env.SIGNATURE) throw new Error('Please set your SESSION and SIGNATURE cookies');
+const pineId = process.argv[2];
+if (!pineId) throw new Error('Please specify a Pine ID as first argument');
+
+const manager = new PinePermissionManager(pineId, {
+  credentials: { session: process.env.SESSION, signature: process.env.SIGNATURE },
+});
+
+console.log('Users:', await manager.getUsers());
+console.log("Adding 'TradingView':", await manager.addUser('TradingView')); // 'ok' or 'exists'
+console.log('Expiring tomorrow:', await manager.modifyExpiration('TradingView', new Date(Date.now() + 86_400_000)));
+console.log('Removing expiration:', await manager.modifyExpiration('TradingView'));
+console.log('Removing user:', await manager.removeUser('TradingView'));
+console.log('Users:', await manager.getUsers());

package/examples/private-indicators.js

@@ -0,0 +1,27 @@
+// Run every private (saved) indicator of your account on a chart.
+// Run: npm run build && node --env-file=.env examples/private-indicators.js
+import { getIndicator, getPrivateIndicators, TradingViewClient } from '@mathieuc/tradingview';
+
+if (!process.env.SESSION || !process.env.SIGNATURE) throw new Error('Please set your SESSION and SIGNATURE cookies');
+const credentials = { session: process.env.SESSION, signature: process.env.SIGNATURE };
+
+const list = await getPrivateIndicators(credentials);
+if (!list.length) {
+  console.log('Your account has no private indicators');
+  process.exit(0);
+}
+
+const client = new TradingViewClient({ credentials });
+const chart = client.createChart();
+chart.setMarket('BINANCE:BTCEUR', { timeframe: 'D' });
+
+for (const item of list) {
+  const study = chart.createStudy(await getIndicator(item.id, { version: item.version, credentials }));
+  study.on('error', (error) => console.error(item.name, error.message));
+  study.on('ready', () => {
+    console.log(item.name, 'last values:', study.values.at(-1));
+    if (study.strategyReport.performance.all) console.log(item.name, 'strategy:', study.strategyReport.performance.all);
+  });
+}
+
+setTimeout(() => client.close(), 15_000);

package/examples/quote-session.js

@@ -0,0 +1,17 @@
+// Low-level quote session: several symbols sharing one subscription list.
+// Run: npm run build && node examples/quote-session.js
+import { TradingViewClient } from '@mathieuc/tradingview';
+
+const client = new TradingViewClient();
+const quotes = client.createQuoteSession({ fields: ['lp', 'ch', 'chp', 'volume'] });
+
+for (const symbol of ['BINANCE:BTCEUR', 'BINANCE:ETHEUR']) {
+  const subscription = quotes.subscribe(symbol);
+  subscription.on('data', (quote, changes) => console.log(symbol, changes));
+  subscription.on('error', (error) => console.error(symbol, error.message));
+}
+
+setTimeout(async () => {
+  quotes.delete();
+  await client.close();
+}, 10_000);

package/examples/quotes.js

@@ -0,0 +1,15 @@
+// Quotes with the high-level data API.
+// Run: npm run build && node examples/quotes.js
+import { getQuote, getQuotes, watchQuotes } from '@mathieuc/tradingview/data';
+
+const btc = await getQuote('BINANCE:BTCUSDT');
+console.log('BTC/USDT', btc.lp, `${btc.chp}%`);
+
+const prices = await getQuotes({ symbols: ['NASDAQ:AAPL', 'NASDAQ:MSFT', 'FX:EURUSD'], fields: 'price' });
+for (const [symbol, quote] of Object.entries(prices)) console.log(symbol, quote.lp);
+
+const watcher = await watchQuotes({ symbols: ['BINANCE:BTCUSDT', 'BINANCE:ETHUSDT'], fields: ['lp', 'chp'] }, {
+  onData: (symbol, quote) => console.log(symbol, quote.lp),
+  onError: (error) => console.error(error.message),
+});
+setTimeout(() => watcher.stop(), 15_000);

package/examples/replay.js

@@ -0,0 +1,36 @@
+// Replay mode: step through history bar by bar with indicators.
+// Run: npm run build && node --env-file=.env examples/replay.js
+import { BuiltInIndicator, getIndicator, TradingViewClient } from '@mathieuc/tradingview';
+
+const credentials = process.env.SESSION
+  ? { session: process.env.SESSION, signature: process.env.SIGNATURE }
+  : undefined;
+
+const client = new TradingViewClient({ credentials });
+const chart = client.createChart();
+chart.setMarket('BINANCE:BTCEUR', {
+  timeframe: 'D',
+  replay: Math.round(Date.now() / 1000) - 86_400 * 7, // Start seven days ago
+  count: 1,
+});
+
+const studies = { Volume: chart.createStudy(new BuiltInIndicator('Volume@tv-basicstudies-241')) };
+if (credentials) {
+  const ema = await getIndicator('STD;EMA');
+  studies.EMA_50 = chart.createStudy(ema.clone().setInput('Length', 50));
+}
+
+let ended = false;
+chart.on('replayEnd', () => { ended = true; });
+await new Promise((resolve) => { chart.once('replayLoaded', resolve); });
+
+while (!ended) {
+  await chart.replayStep(1);
+  const bar = chart.lastCandle;
+  const values = Object.fromEntries(Object.entries(studies).map(([name, study]) => [name, study.values.at(-1)]));
+  console.log(bar && new Date(bar.time * 1000).toISOString(), bar?.close, values);
+}
+
+// chart.replayStart(1000) plays automatically; chart.replayStop() pauses.
+await client.close();
+console.log('Done');

package/examples/screener.js

@@ -0,0 +1,10 @@
+import { getScreener } from '@mathieuc/tradingview/data';
+
+const page = await getScreener({
+  market: 'america',
+  columns: ['name', 'close', 'volume', 'Stoch.RSI.D'],
+  filter: [{ left: 'type', operation: 'equal', right: 'stock' }],
+  sort: { sortBy: 'volume', sortOrder: 'desc' },
+  range: [0, 10],
+});
+console.table(page.rows.map(({ symbol, values }) => ({ symbol, ...values })));

package/examples/search.js

@@ -0,0 +1,11 @@
+// Market search, indicator search and technical ratings.
+// Run: npm run build && node examples/search.js
+import { getTechnicalAnalysis, searchIndicators, searchMarkets } from '@mathieuc/tradingview';
+
+const markets = await searchMarkets('BINANCE:BTC', { type: 'crypto' });
+console.log('Markets:', markets.slice(0, 5).map((m) => `${m.id} (${m.description})`));
+
+const indicators = await searchIndicators('RSI');
+console.log('Indicators:', indicators.slice(0, 5).map((i) => `${i.id} - ${i.name} [${i.access}]`));
+
+console.log('Daily ratings for', markets[0].id, (await getTechnicalAnalysis(markets[0].id))?.['1D']);

package/examples/simple-chart.js

@@ -0,0 +1,36 @@
+// Low-level chart session: change market, timeframe and chart type on one chart.
+// Run: npm run build && node examples/simple-chart.js
+import { TradingViewClient } from '@mathieuc/tradingview';
+
+const client = new TradingViewClient();
+const chart = client.createChart();
+
+chart.on('error', (error) => console.error('Chart error:', error.code, error.message));
+chart.on('symbolLoaded', (info) => console.log(`Market "${info.description}" loaded`));
+chart.on('update', () => {
+  const last = chart.lastCandle;
+  if (last) console.log(`[${chart.symbolInfo?.description}] ${last.close} ${chart.symbolInfo?.currency_id}`);
+});
+
+chart.setMarket('BINANCE:BTCEUR', { timeframe: 'D' });
+
+setTimeout(() => {
+  console.log('\nSetting market to BINANCE:ETHEUR...');
+  chart.setMarket('BINANCE:ETHEUR', { timeframe: 'D' });
+}, 5_000);
+
+setTimeout(() => {
+  console.log('\nSetting timeframe to 15 minutes...');
+  chart.setTimeframe('15');
+}, 10_000);
+
+setTimeout(() => {
+  console.log('\nSetting the chart type to Heikin Ashi...');
+  chart.setMarket('BINANCE:ETHEUR', { timeframe: 'D', type: 'HeikinAshi' });
+}, 15_000);
+
+setTimeout(async () => {
+  console.log('\nClosing...');
+  chart.delete();
+  await client.close();
+}, 20_000);

package/examples/strategy-report.js

@@ -0,0 +1,30 @@
+// Run: npm run build && node --env-file=.env examples/strategy-report.js
+// Computes a public Pine strategy; does not place orders or export the TradingView UI.
+import { getIndicatorData, summarizeStrategyReport } from '@mathieuc/tradingview';
+
+if (!process.env.SESSION || !process.env.SIGNATURE) {
+  console.error('Set SESSION and SIGNATURE in your environment (see .env.sample).');
+  process.exitCode = 1;
+} else {
+  try {
+    const { strategyReport } = await getIndicatorData({
+      symbol: 'BINANCE:BTCEUR',
+      timeframe: '60',
+      count: 300,
+      indicator: 'STD;Supertrend%Strategy',
+      inputs: { commission_type: 'percent', default_qty_value: 20 },
+      credentials: { session: process.env.SESSION, signature: process.env.SIGNATURE },
+      timeoutMs: 30_000,
+      signal: AbortSignal.timeout(45_000),
+    });
+    if (!strategyReport.performance.all) throw new Error('No strategy performance received');
+    // Missing aggregates remain undefined, not zero. totalPnL requires both components.
+    console.log('Summary:', summarizeStrategyReport(strategyReport));
+    // Most recent first. An exit valuation alone does NOT prove that a trade is closed.
+    console.log('Latest trade records:', strategyReport.trades.slice(0, 5));
+    console.log('Available history:', Object.keys(strategyReport.history));
+  } catch (error) {
+    console.error(error.code ?? 'STRATEGY_ERROR', error.message);
+    process.exitCode = 1;
+  }
+}

package/examples/user-login.js

@@ -0,0 +1,15 @@
+// Sign in to get session cookies (accounts with 2FA/captcha are not supported).
+// Never commit or share the printed cookies.
+// Run: npm run build && node examples/user-login.js <username/email> <password>
+import { getUser, loginUser } from '@mathieuc/tradingview';
+
+const [username, password] = process.argv.slice(2);
+if (!username || !password) throw new Error('Usage: node examples/user-login.js <username/email> <password>');
+
+const user = await loginUser({ username, password, remember: false });
+console.log('Signed in as', user.username, `(id ${user.id})`);
+console.log('Put these in .env as SESSION and SIGNATURE:', { session: user.session, signature: user.signature });
+
+// Later, the account can be loaded from the cookies alone:
+const again = await getUser({ session: user.session, signature: user.signature });
+console.log('Reloaded', again.username);

package/examples/watch-candles.js

@@ -0,0 +1,16 @@
+// Real-time candles with the high-level data API.
+// Run: npm run build && node examples/watch-candles.js
+import { watchCandles } from '@mathieuc/tradingview/data';
+
+const watcher = await watchCandles({ symbol: 'BINANCE:BTCUSDT', timeframe: '1', count: 10 }, {
+  onData: (candles) => {
+    const last = candles.at(-1);
+    console.log(new Date(last.time * 1000).toISOString(), 'close', last.close);
+  },
+  onError: (error) => console.error('Watcher error:', error.code, error.message),
+});
+
+console.log(`Watching ${watcher.symbolInfo?.description}... (stops after 30 seconds)`);
+setTimeout(() => watcher.stop(), 30_000);
+await watcher.closed;
+console.log('Stopped');

package/llms.txt

@@ -0,0 +1,26 @@
+# TradingView-API
+# https://github.com/Mathieu2301/TradingView-API
+# https://www.npmjs.com/package/@mathieuc/tradingview
+
+Independent community library for TradingView market data. Not an official TradingView API.
+Version 4 beta: TypeScript, ESM, Node >= 20 or Bun. Breaking rewrite of v3 (no compatibility layer). Install the prerelease with npm install @mathieuc/tradingview@beta; the default latest tag remains v3.
+
+Simple data API (import from '@mathieuc/tradingview/data' or the root entry):
+- getCandles({ symbol, timeframe?, count?, from?, to?, chartType?, ... }) -> Candle[] oldest first, time in Unix seconds.
+- watchCandles(query, { onData, onError? }) -> watcher { latest, stop(), closed }.
+- getQuote(symbol), getQuotes({ symbols }), watchQuotes({ symbols }, { onData }).
+- getSymbolInfo(symbol), getIndicatorData({ symbol, indicator, inputs? }), watchIndicator(...).
+- getScreener({ columns, market?, filter?, sort?, range?, symbols? }) -> { totalCount, rows }; one HTTP page, not a streaming screener.
+- getHotlist({ kind, ... }) -> scanner-ranked rows, not guaranteed TradingView UI parity.
+- getWatchlists({ credentials }) -> read-only account lists with ordered symbols and section markers.
+- searchMarkets(text), searchIndicators(text), getTechnicalAnalysis(symbol).
+- Websocket data calls accept timeoutMs, signal (AbortSignal), credentials ({ session, signature }) and client (shared TradingViewClient). HTTP lookups accept signal in options.
+- Candle calls can use a custom MarketDataProvider; TradingViewProvider is the default source adapter.
+- Errors are TradingViewError with a code (SYMBOL_ERROR, TIMEOUT, STUDY_ERROR, NO_DATA...).
+
+Low-level API: TradingViewClient, client.createChart() (ChartSession: setMarket, setTimeframe, fetchMore, replay, createStudy), client.createQuoteSession(), PineIndicator, BuiltInIndicator, HTTP functions (loginUser, getUser, getIndicator, getPrivateIndicators, getDrawings, PinePermissionManager).
+
+Pine studies need a TradingView account (session cookies). Built-in studies and candles/quotes work anonymously, with history limits.
+Docs: docs/data-api.md, docs/low-level-api.md, docs/migration-v4.md, docs/v4-coverage.md, docs/v4-reliability.md, docs/protocol-contributing.md. Examples: examples/.
+No CLI, MCP server, backtesting engine or hosted trading API is shipped. Do not claim otherwise.
+Questions and bugs: https://github.com/Mathieu2301/TradingView-API/issues/new/choose

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mathieuc/tradingview",
-  "version": "4.0.0-beta.4",
+  "version": "4.0.0-rc.0",
   "description": "TradingView market data for JavaScript and TypeScript: candles, quotes, indicators and strategies, with a simple data API and full low-level access.",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,7 +21,13 @@
   "files": [
     "dist",
     "README.md",
-    "docs"
+    "docs",
+    "scripts/endurance.mjs",
+    "scripts/probe-account.mjs",
+    "assets",
+    "llms.txt",
+    "examples",
+    "scripts/parity.mjs"
   ],
   "sideEffects": false,
   "scripts": {
@@ -36,7 +42,9 @@
     "check": "npm run typecheck && npm run lint && npm test && npm run build && npm run smoke",
     "prepack": "npm run build",
     "probe:endurance": "npm run build && node scripts/endurance.mjs",
-    "probe:parity": "npm run build && node scripts/parity.mjs"
+    "probe:parity": "npm run build && node scripts/parity.mjs",
+    "probe:account": "npm run build && node scripts/probe-account.mjs",
+    "test:coverage": "vitest run --coverage"
   },
   "repository": {
     "type": "git",
@@ -67,6 +75,7 @@
     "@eslint/js": "^9.39.0",
     "@types/node": "^22.20.5",
     "@types/ws": "^8.18.1",
+    "@vitest/coverage-v8": "^4.1.11",
     "eslint": "^9.39.0",
     "typescript": "~5.9.3",
     "typescript-eslint": "^8.46.0",

package/scripts/endurance.mjs

@@ -0,0 +1,93 @@
+/** Opt-in live endurance probe. No credentials are read or logged. */
+import { TradingViewClient } from '../dist/index.js';
+import { watchCandles, watchQuotes } from '../dist/data/index.js';
+
+const argument = (name, fallback) => {
+  const raw = process.argv.find((value) => value.startsWith(`--${name}=`))?.split('=')[1];
+  const number = raw === undefined ? fallback : Number(raw);
+  if (!Number.isFinite(number) || number <= 0) throw new Error(`--${name} must be positive`);
+  return number;
+};
+
+const textArgument = (name, fallback) => process.argv.find((value) => value.startsWith(`--${name}=`))?.split('=')[1] ?? fallback;
+const minutes = argument('minutes', 120);
+const cycleSeconds = argument('cycle-seconds', 600);
+const heartbeatThreshold = argument('heartbeat-threshold', 30);
+const requirePostThresholdUpdates = process.argv.includes('--require-post-threshold-updates');
+const symbol = textArgument('symbol', 'BINANCE:BTCUSDT');
+const timeframe = textArgument('timeframe', '1');
+const chartType = textArgument('chart-type', undefined);
+const deadline = Date.now() + minutes * 60_000;
+const metrics = { cycles: 0, starts: 0, failures: 0, candleUpdates: 0, quoteUpdates: 0, heartbeats: 0, postThresholdCandleUpdates: 0, postThresholdQuoteUpdates: 0, errors: [] };
+let interrupted = false;
+for (const signal of ['SIGINT', 'SIGTERM']) process.once(signal, () => { interrupted = true; });
+
+const report = (event, extra = {}) => console.log(JSON.stringify({
+  at: new Date().toISOString(), event, ...extra,
+}));
+
+function waitForCycle(ms, watchers) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => resolve('elapsed'), ms);
+    Promise.race(watchers.map((watcher) => watcher.closed)).then(() => {
+      clearTimeout(timer);
+      resolve('closed');
+    });
+  });
+}
+
+const status = setInterval(() => report('status', { ...metrics, errors: metrics.errors.slice(-3) }), 60_000);
+report('start', { minutes, cycleSeconds, symbol, timeframe, chartType, heartbeatThreshold, requirePostThresholdUpdates });
+try {
+  while (!interrupted && Date.now() < deadline) {
+    metrics.cycles += 1;
+    const client = new TradingViewClient();
+    let cycleHeartbeats = 0;
+    client.on('heartbeat', () => { metrics.heartbeats += 1; cycleHeartbeats += 1; });
+    client.on('error', (error) => metrics.errors.push(error.code));
+    let candles;
+    let quotes;
+    try {
+      candles = await watchCandles({ symbol, timeframe, chartType, count: 5, client }, {
+        onData: () => {
+          metrics.candleUpdates += 1;
+          if (cycleHeartbeats > heartbeatThreshold) metrics.postThresholdCandleUpdates += 1;
+        },
+        onError: (error) => metrics.errors.push(error.code),
+      });
+      quotes = await watchQuotes({ symbols: [symbol], fields: 'price', client }, {
+        onData: () => {
+          metrics.quoteUpdates += 1;
+          if (cycleHeartbeats > heartbeatThreshold) metrics.postThresholdQuoteUpdates += 1;
+        },
+        onError: (error) => metrics.errors.push(error.code),
+      });
+      if (candles.latest.length !== 5 || typeof quotes.latest[symbol]?.lp !== 'number') {
+        throw new Error('Initial market snapshots incomplete');
+      }
+      metrics.starts += 1;
+      report('connected', { cycle: metrics.cycles, candles: candles.latest.length, quotePricePresent: true });
+      const duration = Math.min(cycleSeconds * 1000, deadline - Date.now());
+      const outcome = await waitForCycle(duration, [candles, quotes]);
+      if (outcome === 'closed' && !interrupted) throw new Error('Watcher closed before planned rotation');
+      report('rotation', { cycle: metrics.cycles, outcome });
+    } catch (error) {
+      metrics.failures += 1;
+      metrics.errors.push(error?.code ?? error?.message ?? String(error));
+      report('failure', { cycle: metrics.cycles, code: error?.code, message: error?.message });
+    } finally {
+      await Promise.allSettled([candles?.stop(), quotes?.stop()]);
+      await client.close();
+    }
+    if (metrics.failures >= 3) break;
+    if (metrics.failures && Date.now() < deadline) await new Promise((resolve) => setTimeout(resolve, 3_000));
+  }
+} finally {
+  clearInterval(status);
+  report('summary', { ...metrics, errors: metrics.errors.slice(-10), interrupted });
+}
+if (interrupted || metrics.failures || metrics.errors.length || metrics.starts === 0
+  || metrics.quoteUpdates === 0 || metrics.candleUpdates === 0
+  || (requirePostThresholdUpdates && (!metrics.postThresholdCandleUpdates || !metrics.postThresholdQuoteUpdates))) {
+  process.exitCode = 1;
+}

package/scripts/parity.mjs

@@ -0,0 +1,54 @@
+/** Opt-in live comparison with the published v3 package. */
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const entry = process.env.TV_V3_ENTRY;
+if (!entry) throw new Error('Set TV_V3_ENTRY to the installed v3 main.js path');
+const { Client } = require(entry);
+const { getCandles } = await import('../dist/data/index.js');
+const symbol = 'BINANCE:BTCEUR';
+
+async function legacyCandles(timeframe) {
+  const client = new Client();
+  const chart = new client.Session.Chart();
+  try {
+    return await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error('V3 chart timed out')), 20_000);
+      const fail = (...parts) => { clearTimeout(timer); reject(new Error(parts.map(String).join(' '))); };
+      chart.onError(fail);
+      client.onError(fail);
+      chart.onUpdate(() => {
+        if (chart.periods.length < 20) return;
+        clearTimeout(timer);
+        resolve(chart.periods.map(({ time, open, max, min, close, volume }) => ({
+          time, open, high: max, low: min, close, volume,
+        })).sort((a, b) => a.time - b.time));
+      });
+      chart.setMarket(symbol, { timeframe, range: 20 });
+    });
+  } finally {
+    chart.delete();
+    await client.end();
+  }
+}
+
+let total = 0;
+let mismatches = 0;
+for (const timeframe of ['D', '60']) {
+  const oldBars = await legacyCandles(timeframe);
+  const newBars = await getCandles({ symbol, timeframe, count: 20 });
+  // Last bar can change between requests. V3 rounds volume to two decimals.
+  const oldClosed = oldBars.slice(0, -1);
+  const newClosed = newBars.slice(0, -1);
+  const differences = oldClosed.flatMap((bar, index) => {
+    const next = newClosed[index];
+    const comparable = next && { ...next, volume: Math.round(next.volume * 100) / 100 };
+    return JSON.stringify(bar) === JSON.stringify(comparable) ? [] : [index];
+  });
+  if (oldBars.length !== 20 || newBars.length !== 20) differences.push(-1);
+  total += oldClosed.length;
+  mismatches += differences.length;
+  console.log(JSON.stringify({ timeframe, v3Bars: oldBars.length, v4Bars: newBars.length,
+    closedBarsCompared: oldClosed.length, mismatchIndexes: differences }));
+}
+console.log(JSON.stringify({ closedBarsCompared: total, mismatches }));
+if (mismatches) process.exitCode = 1;