Skip to content

Simplify the README #357

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Mathieu2301 merged 1 commit into from
Nov 14, 2026
Merged

Simplify the README #357

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
184 changes: 28 additions & 156 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,175 +1,47 @@
# TradingView-API
# TradingView API [![GitHub stars](https://img.shields.io/github/stars/Mathieu2301/TradingView-API.svg?style=social&label=Star)](https://github.com/Mathieu2301/TradingView-API/stargazers)

**Build with market data, from your first chart to a running watcher.** Fetch candles and quotes, run indicators and strategies, and turn ideas into working tools. An independent community project, not an official TradingView API.

[Get started](#get-started) · [Explore examples](examples) · [Read the data API guide](docs/data-api.md)

**Language:** English · [Français](docs/README.fr.md) · [Español](docs/README.es.md) · [Português](docs/README.pt.md)

[![Tests](https://github.com/Mathieu2301/TradingView-API/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/Mathieu2301/TradingView-API/actions/workflows/tests.yml) [![npm](https://badgen.net/npm/v/@mathieuc/tradingview)](https://www.npmjs.com/package/@mathieuc/tradingview) [![Stars](https://img.shields.io/github/stars/Mathieu2301/TradingView-API?style=social)](https://github.com/Mathieu2301/TradingView-API)
[![Tests](https://github.com/Mathieu2301/TradingView-API/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/Mathieu2301/TradingView-API/actions/workflows/tests.yml)
[![CodeFactor](https://www.codefactor.io/repository/github/mathieu2301/tradingview-api/badge/main)](https://www.codefactor.io/repository/github/mathieu2301/tradingview-api/overview/main)
[![npm downloads](https://badgen.net/npm/dt/@mathieuc/tradingview)](https://www.npmjs.com/package/@mathieuc/tradingview)
[![npm version](https://badgen.net/npm/v/@mathieuc/tradingview)](https://www.npmjs.com/package/@mathieuc/tradingview)

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

<a href="https://molted.studio/dreams/ai-agent-for-tradingview-data?utm_source=github&utm_medium=readme&utm_campaign=tradingview-api"><img src="assets/readme-film.webp" alt="Film: a trader asks an AI agent to turn a private TradingView indicator into a bot; the agent installs TradingView-API, backtests it and trades it on a demo account" width="100%"></a>

**Turn your TradingView indicators into a trading bot, just by chatting.** An AI agent on molted installs TradingView-API, backtests your setup and runs it 24/7 on a demo account. Real money only when you say so.

**[Create my AI agent →](https://molted.studio/dreams/ai-agent-for-tradingview-data?utm_source=github&utm_medium=readme&utm_campaign=tradingview-api)**

▶ With sound:

https://github.com/user-attachments/assets/88859255-9e80-435e-95d4-f6f40bf0946b

### One request, real data

> **V4 is the default npm release.** Install with `npm install @mathieuc/tradingview` to use `getCandles` and the new data API.

```js
import { getCandles } from '@mathieuc/tradingview/data';

const candles = await getCandles({ symbol: 'BINANCE:BTCUSDT', timeframe: 'D', count: 40 });
console.log(candles.at(-1)); // { time, open, high, low, close, volume }
```

![Recorded demonstration: a candle request returns 40 daily BTC/USDT candles, visualized as a line chart](assets/readme-demo.gif)
Get realtime market prices, indicator values and backtests from TradingView! 📈

*An actual candle request, recorded on 2 October 2026 with the development preview (`fetchCandles`, called `getCandles` in version 4) and visualized for this demo. Prices are not live.*
🌐 English · [Français](docs/README.fr.md) · [Español](docs/README.es.md) · [Português](docs/README.pt.md)

Prefer to start without code? The setup paths below work too.
## 🟢 Need help with your project?

> **Version 4 is a breaking rewrite** in TypeScript, with a new API and no compatibility layer. Coming from v3? Read the [migration guide](docs/migration-v4.md). Every v3 feature is still available: see the [coverage matrix](docs/v4-coverage.md) and [reliability evidence](docs/v4-reliability.md). The [RC preparation report](docs/v4-stabilization.md) tracks current checks and remaining release gates. npm versions 3.x keep the previous `Client` API; check the [npm page](https://www.npmjs.com/package/@mathieuc/tradingview) for the version you install.
🚀 **[Click here to get help with your project](https://molted.studio/dreams/ai-agent-for-tradingview-data?utm_source=github&utm_medium=readme&utm_campaign=tradingview-api&utm_content=need-help)**

## Get started
<a href="https://molted.studio/dreams/ai-agent-for-tradingview-data?utm_source=github&utm_medium=readme&utm_campaign=tradingview-api&utm_content=film"><img src="assets/readme-film.webp" alt="Film: a trader gets help from an AI agent that installs TradingView-API, backtests the setup and runs it on a demo account" width="100%"></a>

### Interactive quick-start
## ✨ Features

The interactive launcher is included in V4:
- ✅ Realtime candles and quotes
- ✅ Indicator values: built-in and Pine indicators, invite-only included (with access)
- ✅ Strategy reports
- ✅ Honest backtests: no look-ahead, fees, random-entry baseline
- ✅ Replay mode + fake replay mode (free plan)
- ✅ Values for a specific date range
- ✅ Screener and hotlists
- ✅ Your watchlists and the drawings on your charts
- ✅ TradingView's technical analysis
- 💡 Want a feature? [Ask here](https://github.com/Mathieu2301/TradingView-API/issues/new/choose)

```bash
npx @mathieuc/tradingview
```

Run it from your project directory with Node.js 20+. Choose a path:

1. **Autonomous agent (recommended)** — opens the [TradingView-API market watcher on Molted Studio](https://molted.studio/dreams/ai-agent-for-tradingview-data?utm_source=github&utm_medium=readme&utm_campaign=tradingview-api). No local project setup.
2. **Claude Code CLI** — starts your installed `claude` CLI here with a ready-to-use project prompt.
3. **Codex CLI** — starts your installed `codex` CLI here with the same prompt.
4. **Another local coding agent** — prints the prompt to paste into your agent.
5. **Install the library only** — runs `npm install @mathieuc/tradingview` here, without generating files or starting an agent.

Claude Code and Codex must already be installed and authenticated. Their normal permission prompts remain enabled. If launch fails, the prompt is printed for manual use. If no browser is available, the hosted link remains visible.

Use `--choice 4` to print the prompt directly, or `--help` for usage. Non-interactive callers must pass `--choice`. To try the launcher from this checkout:
## 📦 Installation

```bash
npm ci && npm run build
node bin/tradingview.mjs
npm i @mathieuc/tradingview
```

### Install manually

```bash
npm install @mathieuc/tradingview
# Or: bun add @mathieuc/tradingview
```

V4 is installed by default. V3 remains available with `@mathieuc/tradingview@3`; read the migration guide before upgrading existing V3 projects.

The V4 package is ESM with TypeScript declarations. CommonJS projects can `require()` it on Node 20.19+ or 22.12+, or use `await import()`.

### Want to contribute?

[Open an issue](https://github.com/Mathieu2301/TradingView-API/issues/new/choose) to discuss a feature or report a bug, or send a pull request. Questions and early ideas are welcome; you do not need a perfect reproduction to start a conversation. `npm run check` runs the type check, lint, tests, build and package smoke test.

## Data API

The data API handles connections, sessions, timeouts and cleanup for you. It suits any application: scripts, servers, dashboards, bots or agents.

```ts
import {
getCandles, watchCandles, getQuote, getIndicatorData, searchMarkets,
} from '@mathieuc/tradingview/data';

// One-shot: resolves with complete data, then releases everything.
const hourly = await getCandles({ symbol: 'BINANCE:BTCUSDT', timeframe: '60', count: 500 });
const lastWeek = await getCandles({ symbol: 'NASDAQ:AAPL', timeframe: '15', from: new Date(Date.now() - 7 * 86_400_000) });
const quote = await getQuote('BINANCE:BTCUSDT');
const [market] = await searchMarkets('ethereum', { type: 'crypto' });

// Watcher: keeps streaming until stopped.
const watcher = await watchCandles({ symbol: 'BINANCE:BTCUSDT', timeframe: '1' }, {
onData: (candles) => console.log(candles.at(-1)?.close),
onError: (error) => console.error(error.code, error.message),
});
await watcher.stop();

// Indicators and strategies (Pine scripts need an account).
const { values } = await getIndicatorData({
symbol: 'BINANCE:BTCUSDT', indicator: 'STD;RSI', credentials: { session, signature },
});
```

| Need | Function |
| --- | --- |
| Candles: latest bars, deep history, date ranges, Heikin Ashi/Renko/... | `getCandles`, `watchCandles` |
| Quotes: last price, change, bid/ask, volume... | `getQuote`, `getQuotes`, `watchQuotes` |
| Indicator values, drawings and strategy reports | `getIndicatorData`, `watchIndicator` |
| Symbol metadata | `getSymbolInfo` |
| Stock/crypto screening and ranked lists | `getScreener`, `getHotlist` |
| Account watchlists (read-only) | `getWatchlists` |
| Search and ratings | `searchMarkets`, `searchIndicators`, `getTechnicalAnalysis` |

Websocket data functions accept `timeoutMs`, an `AbortSignal`, account `credentials`, and an optional shared `client`. HTTP lookups accept an `AbortSignal` through their options. Errors are `TradingViewError`s with a `code` such as `SYMBOL_ERROR`, `TIMEOUT` or `STUDY_ERROR`. Read the [data API guide](docs/data-api.md) for every option.

## Backtest API

Write the entry rule; `@mathieuc/tradingview/backtest` does the rest: frozen candles, look-ahead rejection, entry at the next open, fees and slippage on both sides, pessimistic fills, in-sample/out-of-sample split, four exits and a seeded random-entry baseline.

```ts
import { backtest, formatReport, rsiDivergence } from '@mathieuc/tradingview/backtest';

const { report } = await backtest({
symbol: 'BINANCE:BTCUSDT', timeframe: '240', years: 2,
signal: rsiDivergence(), // Or your own: (candles) => [{ bar, direction: 'long' | 'short' }]
});
console.log(formatReport(report)); // report is plain JSON: rows per exit and split, trades, warnings
```

It makes no claim of profitability: a negative or inconclusive result is a valid outcome. Read the [backtest guide](docs/backtest.md).

## Low-level API

For full control (several charts and studies on one connection, replay mode, raw packets), use the client and sessions directly:

```ts
import { TradingViewClient, getIndicator } from '@mathieuc/tradingview';

const client = new TradingViewClient({ credentials: { session, signature } }); // Credentials are optional
const chart = client.createChart();

chart.on('update', () => console.log(chart.lastCandle?.close));
chart.on('error', (error) => console.error(error.message));
chart.setMarket('BINANCE:BTCUSDT', { timeframe: '60', count: 300 });

const supertrend = chart.createStudy(await getIndicator('STD;Supertrend'));
supertrend.on('update', () => console.log(supertrend.values.at(-1)));

// When your application is finished:
await client.close();
```

The [low-level API reference](docs/low-level-api.md) covers charts, replay, studies, quotes, account and layout functions, Pine permissions, custom transports and protocol helpers. The [examples](examples) show each feature.

## Accounts and limits
📚 [Getting started](docs/getting-started.md) · [Data API](docs/data-api.md) · [Backtest](docs/backtest.md) · [Low-level API](docs/low-level-api.md) · [Examples](examples)

Without an account, TradingView serves limited data: shorter intraday history, no Pine studies, and possibly delayed or substitute feeds. With your `sessionid` and `sessionid_sign` cookies (`credentials`), you get what your account can access. Keep them in environment variables or a secret store; never put them in source files, issues or prompts.
## 🐛 Problems

## Project links
If you have errors or unwanted behavior, please [open an issue](https://github.com/Mathieu2301/TradingView-API/issues/new/choose).

- [GitHub repository](https://github.com/Mathieu2301/TradingView-API)
- [Trendshift community highlight](https://trendshift.io/repositories/26416)
- [npm package](https://www.npmjs.com/package/@mathieuc/tradingview)
- [Examples](examples)
- [Report a bug or ask for a feature](https://github.com/Mathieu2301/TradingView-API/issues/new/choose)
___

TradingView is a trademark of its respective owner. This project is not affiliated with or endorsed by TradingView. Check your data provider's terms and applicable market-data permissions for your use case.
<sub>Independent community project. TradingView is a trademark of its respective owner; this project is not affiliated with or endorsed by TradingView.</sub>
Binary file removed assets/readme-demo.gif
View file
Open in desktop
Binary file not shown.
Loading
Loading