HyperView

Turn TradingView ideas into testable, terminal-speed trading systems.

HyperView is a CLI-first toolkit for downloading TradingView market data, backtesting Python strategies with Pine-like execution behavior, and optimizing parameters in a repeatable workflow.

Vietnamese version: README.vi.md

Support This Project

If you discover a strong strategy using this repo, please consider giving the project a star and forking it to support further development.

Pain Points

Manual optimization on TradingView charts is slow, hard to reproduce, and difficult to audit.
Results often diverge between Pine and local scripts because fill assumptions differ.
Data, presets, and reports are scattered across CSVs, notebooks, and ad-hoc scripts.
Multi-strategy and multi-pair research takes too long without a standardized pipeline.

Solution

A unified CLI workflow: download -> signal -> backtest -> optimize -> export artifacts.
A TradingView-like backtester (next-bar-open entries + intrabar SL/TP path simulation).
Automatic preset/report/context storage for comparison and reproducible reruns.
Pine input optimization with best-parameter injection into exported Pine scripts.

Key Features

Historical download from TradingView websocket (up to ~40K bars with eligible authenticated session).
Python strategy framework + TA-Lib (20 wrapped indicators + direct TA-Lib access).
Backtesting with mathematically correct portfolio aggregation from combined equity curves.
SL/TP optimization via Optuna (TPE), with top preset persistence.
Two-stage Pine optimization + batch optimization for multiple strategy files.
Structured artifacts (data/, results/, strategies/raw/, strategies/optimized/).

FAQ (Pro Account & Tick Data)

Can I use HyperView without a TradingView Pro account?

Yes. You can still use download, backtest, and optimization features without Pro.
In practice, data depth is typically lower for anonymous/non-authenticated sessions (often around ~5K bars), while authenticated paid sessions can reach higher limits (up to ~40K bars, depending on account/session availability).

Does HyperView support tick data?

No. HyperView is candle/timeframe based (1m, 5m, 15m, 1h, etc.), not tick-by-tick data stream based.

Is `1m` data equivalent to tick data?

No. 1m is still aggregated OHLCV bar data, not raw market ticks.

Can this be used for tick-level/HFT validation?

Not natively in the current architecture. The backtester uses bar-level + intrabar-path assumptions, not full tick replay.

Do I need any TradingView API key?

No. The downloader uses TradingView websocket/session mechanics and optional local browser session credentials.

Practical Outcomes

Faster strategy research loops by replacing chart-click workflows with automated CLI pipelines.
Easier team collaboration through consistent presets, reports, and saved contexts.
Lower mismatch risk when moving from Pine ideas to quantitative validation.
Better scaling for multi-strategy, multi-symbol, and multi-timeframe experiments.

Improvements Over The Original Fork Source

The fork improvements are not only cosmetic; they are implemented as concrete workflow tasks:

CLI Standardization Task
- Unified command entry around tradingview-backtest.
- Kept backward-compatible aliases: hyperview, python -m hyperview.
- Goal: reduce team friction across local terminal + AI CLI usage.
Pine Optimization Pipeline Task
- Added optimized Pine export with best params injected into defaults.
- Added compact filename metrics (np/dd/pf/tc) for fast scanning.
- Added per-run metadata headers in exported Pine snapshots.
Batch Orchestration Task
- Added batch runner to optimize multiple Pine files from strategies/raw/.
- Added matrix execution for symbols/timeframes.
- Added leaderboard outputs for top results aggregation.
Artifact Contract Task
- Standardized directories:
  - strategies/raw/
  - strategies/optimized/
  - results/optimizations/<symbol>/<timeframe>/
- Goal: deterministic outputs for commit/push/audit and easier collaboration.
Automation & Onboarding Task
- Added cross-platform bootstrap scripts (.cmd, .ps1, .sh).
- Added GitHub release workflow and build smoke checks.
- Added Codex/Claude quick workflow guidance in docs.

Prerequisites

Core runtime requirements

Python 3.11+
TA-Lib — installed automatically by pip install. Pre-built wheels are available for major OS/Python combinations.
rich — installed automatically for CLI tables/panels/progress UI.
Firefox (optional) — for authenticated TradingView session reuse (higher historical bar limits).

Additional requirements to use fork improvements fully

Git + GitHub CLI (gh) — needed for release automation, fork sync, and GitHub-native workflow management.
One of uvx / pipx / pip — needed for portable install/run modes documented in this fork.
Writable workspace for artifacts — required because this fork intentionally tracks richer outputs in:
- data/
- results/
- strategies/raw/
- strategies/optimized/

Verification baseline (recommended before serious runs)

python -m unittest discover -s tests -v
python -m hyperview --help
python -m hyperview list-strategies

Install & Run Anywhere

Canonical CLI command is now tradingview-backtest.
Backwards-compatible aliases still work: tvbacktest, hyperview, and python -m hyperview.

Option A (Recommended, npx-like): `uvx`

# Run directly from GitHub (no long-lived install)
uvx --from git+https://github.com/<org>/tradingview-backtest.git tradingview-backtest --help

# After publishing to PyPI
uvx tradingview-backtest --help

Option B (npm -g-like): `pipx`

pipx install tradingview-backtest
tradingview-backtest --help

Option C (Universal fallback): `pip`

python -m pip install tradingview-backtest
python -m hyperview --help

Bootstrap Scripts (from this repo)

# Windows (cmd)
scripts\bootstrap.cmd local

# Windows (PowerShell)
.\scripts\bootstrap.ps1 -Mode local

# Linux/macOS
./scripts/bootstrap.sh local

Quick Start (Project Development)

# Install in editable mode (creates `tradingview-backtest`, `tvbacktest`, and `hyperview`)
pip install -e .

# Download data for specific pairs
tradingview-backtest download-data --pairs NASDAQ:NFLX NASDAQ:AAPL --timeframe 1h --session extended

# Or define your pairs in config.json and download multiple timeframes at once:
tradingview-backtest download-data --timeframe 1h 15m

# Run a single backtest (uses config pairlist)
tradingview-backtest backtest --sl 3.23 --tp 13.06 --mode long

# Or target a specific symbol using values from a hyperopt preset file
tradingview-backtest backtest --symbol NASDAQ:NFLX --preset-file results/adx_stochastic_presets.json

# Hyper-optimize SL/TP across all pairs in config
tradingview-backtest hyperopt --mode long

# List cached data and registered strategies
tradingview-backtest list-data
tradingview-backtest list-strategies

You can still run via python -m hyperview for environments that prefer module execution.

Python bytecode is redirected into the project-level .pycache/ directory, so runtime imports do not create scattered __pycache__ folders under hyperview/ or strategy/.

Fast Workflow With Codex CLI / Claude Code

This repo works well with both Codex CLI and Claude Code for AI-assisted development.

1) One-time setup

# Clone repo
git clone https://github.com/hungpixi/tradingview-backtest.git
cd tradingview-backtest

# Bootstrap local env (cross-platform script)
# Windows:
scripts\bootstrap.cmd local
# Linux/macOS:
./scripts/bootstrap.sh local

2) Prompt examples for AI CLI

"Run pine-batch-optimize for OANDA:XAUUSD on 15m and summarize best result."
"Add a new CLI flag for pine-optimize and include unit tests."
"Refactor hyperview/cli/pine.py but keep command behavior backward-compatible."
"Review this branch for regressions in backtest and pine optimize flow."

3) Quick verification before commit

python -m unittest discover -s tests -v
python -m hyperview --help
python -m hyperview list-strategies

4) Tips for better AI output quality

Be explicit about the goal and desired output (specific files/reports/commands).
Always require verification commands before an AI says work is done.
For larger changes, ask for scoped commits (feat, chore, docs).
In this repo, prioritize real CLI validation (download-data, backtest, hyperopt, pine-optimize) rather than code-only edits.

How It Works

Download — Connects to TradingView's websocket using your existing Firefox session cookies. Supports up to 40K historical bars on paid plans with automatic backfill.
Signal — Runs a pluggable strategy (e.g. the included MACD+RSI or ADX+Stochastic) in pure Python with TA-Lib indicator parity.
Backtest — Simulates trades bar-by-bar using TradingView-parity fill assumptions (next-bar-open entry, intrabar SL/TP exit ordering). Multi-pair runs produce a true PORTFOLIO aggregate row with combined equity-curve statistics.
Hyper-Optimize — Runs Bayesian optimization (Optuna TPE) across SL/TP combinations, then updates a strategy preset file with the best result for each pair/context.

Terminal Output

Both the backtest and hyperopt commands produce styled terminal output using rich:

Backtest summary — A bordered table with colored directional arrows (▲ green for gains, ▼ red for losses) on Return, Drawdown, Expectancy, and Worst Trade, using readable short labels that fit a normal terminal width. When multiple pairs are run, a PORTFOLIO row is appended with mathematically correct aggregate statistics computed from a combined equity curve (not simple averages).
Hyperopt results — A panel header showing strategy/mode/timeframe, bullet-point data and signal summaries per pair, and a top-N results table with cyan-highlighted parameter columns (SL/TP) visually separated from metric columns.

Repository Layout

pyproject.toml              Package metadata & CLI entry point
config.json                 Default configuration (timeframe, pairlist, opt ranges)
config.schema.json          JSON Schema for editor validation & autocompletion
data/                       Cached candle CSVs (auto-generated)
results/                    Optimization presets & reports (auto-generated)
strategies/raw/             Source Pine scripts for optimization input
strategies/optimized/       Best optimized Pine exports (filename includes metrics)

`strategy/` — Pluggable Strategy Framework

strategy/
├── __init__.py             Plugin registry & auto-discovery
├── base.py                 BaseStrategy ABC & prepare_candles()
├── indicators.py           TA-Lib wrappers, conversion helpers & signal toolkit
├── adx_stochastic.py       ADX+Stochastic strategy
└── macd_rsi.py             MACD+RSI strategy

`hyperview/` — Core Engine

hyperview/
├── __main__.py             Module entry point (python -m hyperview)
├── config.py               Config loader (JSON + CLI overrides + env vars)
├── models.py               Shared dataclasses (CandleRequest, Trade, BacktestMetrics, …)
├── presets.py              Preset load/save for optimized SL/TP parameters
├── validators.py           Configuration & preset validation rules
├── runtime.py              Bytecode cache redirection
│
├── cli/                    CLI router & subcommand handlers
│   ├── __init__.py         Argument parser & main() dispatcher
│   ├── formatting.py       Shared formatting helpers (rich tables, arrow decorators)
│   ├── backtest.py         backtest command
│   ├── download.py         download-data command
│   ├── hyperopt.py         hyperopt command
│   └── list.py             list-data & list-strategies commands
│
├── backtest/
│   └── engine.py           TradingView-parity OHLC simulator
│
├── downloader/
│   ├── client.py           TradingView websocket downloader & cache orchestration
│   ├── cache.py            CSV-backed local candle cache
│   ├── credentials.py      Firefox credential extraction
│   ├── session.py          WebSocket chart session manager
│   └── timeframes.py       Timeframe constants & utilities
│
└── hyperopt/
    └── optimizer.py        Bayesian optimizer (Optuna TPE)

Configuration

HyperView loads defaults from config.json at the project root. CLI flags always override config values.

The sample below shows a customized setup; if a key is omitted, HyperView falls back to runtime defaults.

{
    "timeframe": "1h",
    "session": "regular",
    "mode": "long",
    "strategy": "adx_stochastic",
    "initial_capital": 100000,
    "data_dir": "data",
    "output_dir": "results",
    "pairlist": [
        "NASDAQ:NFLX",
        "NASDAQ:TSLA",
        "COINBASE:BTCUSD",
        "COINBASE:ETHUSD"
    ],
    "optimization": {
        "n_trials": 200,
        "objective": "net_profit_pct",
        "top_n": 10,
        "sl_range": { "min": 1.0, "max": 15.0 },
        "tp_range": { "min": 1.0, "max": 15.0 }
    }
}

Use --config /path/to/custom.json to load a different file.

Pairlist

The pairlist array defines the symbols you want to work with. Every entry must use the EXCHANGE:SYMBOL format — this lets you mix pairs from different exchanges in a single config:

"pairlist": [
    "NASDAQ:NFLX",
    "NASDAQ:TSLA",
    "NASDAQ:AAPL",
    "COINBASE:BTCUSD"
]

When you run a command without --pairs or --symbol, HyperView automatically uses the config pairlist — downloading, backtesting, or optimizing every pair in sequence. If you pass --pairs or --symbol on the CLI, the config pairlist is ignored for that run.

You can maintain separate config files for different asset classes:

hyperview --config stocks.json download-data
hyperview --config crypto.json hyperopt --mode long

CLI Reference

All command examples below can use tradingview-backtest (recommended) or legacy alias hyperview.

Migration Notes

hyperview command is still supported for backward compatibility.
New canonical command for docs/releases is tradingview-backtest.
Short alias tvbacktest is also available.

`download-data` — Fetch Candle Data

# Download all pairs from config pairlist
hyperview download-data

# Or specify pairs directly, including multiple timeframes
hyperview download-data --pairs NASDAQ:NFLX NASDAQ:AAPL NASDAQ:TSLA --timeframe 1h 15m --start 2023-01-03

Flag	Required	Default	Description
`--pairs`	No	config pairlist	One or more `EXCHANGE:SYMBOL` pairs (overrides pairlist)
`--timeframe`	No	config	One or more bar intervals: `1m` `5m` `15m` `1h` `4h` `1d` etc.
`--start` / `--end`	No	—	Date range (ISO format)
`--session`	No	config	`regular` or `extended`
`--adjustment`	No	`splits`	Price adjustment (`splits`, `dividends`, `none`)

`backtest` — Single Strategy Evaluation

# Backtest all pairs from config pairlist
hyperview backtest --sl 5.0 --tp 5.0 --mode long --start 2023-01-03

# Or target a specific symbol using a preset file created by hyperopt
hyperview backtest --symbol NASDAQ:NFLX --preset-file results/adx_stochastic_presets.json --start 2023-01-03

If --sl and --tp are omitted, HyperView looks for a matching entry in the provided --preset-file using pair + timeframe + session + adjustment + mode. CLI values still override preset-file values.

Flag	Required	Default	Description
`--symbol`	No	config pairlist	`EXCHANGE:SYMBOL` pair (overrides pairlist)
`--sl`	No*	—	Stop-loss % (*required unless a matching `--preset-file` entry exists)
`--tp`	No*	—	Take-profit % (*required unless a matching `--preset-file` entry exists)
`--preset-file`	No	auto-detected	Path to a strategy preset JSON (auto-detects `<strategy>_presets.json` in output dir)
`--strategy`	No	config	Strategy name (e.g. `macd_rsi`, `adx_stochastic`)
`--mode`	No	`long`	`long`, `short`, or `both`
`--timeframe`, `--session`, `--adjustment`, `--start`, `--end`	No	config / defaults	Standard filters

`hyperopt` — Hyper-Optimize SL/TP

# Optimize all pairs from config pairlist (runs one optimization per pair)
hyperview hyperopt --n-trials 300

# Or target a specific symbol
hyperview hyperopt --symbol NASDAQ:NFLX --n-trials 300

Flag	Required	Default	Description
`--symbol`	No	config pairlist	`EXCHANGE:SYMBOL` pair (overrides pairlist)
`--sl-min`, `--sl-max`	No	config	Stop-loss % search range
`--tp-min`, `--tp-max`	No	config	Take-profit % search range
`--n-trials`	No	config	Number of Bayesian optimization trials (default: 200)
`--objective`	No	config	`net_profit_pct` `profit_factor` `win_rate_pct` `max_drawdown_pct` `trade_count`
`--top-n`	No	config	Number of top candidates to keep
`--strategy`, `--mode`, `--timeframe`, `--adjustment`, etc.	No	config / defaults	Standard filters

`list-data` — Show Cached Datasets

hyperview list-data

`list-strategies` — Show Available Strategies

hyperview list-strategies

`pine-optimize` — Optimize Pine Inputs + Export Best Pine

hyperview pine-optimize --pine-file strategies/raw/smc_swing_strategy.pine --symbol OANDA:XAUUSD --timeframe 15m

Exports best Pine by default to strategies/optimized/.
Default optimized filename template: {symbol}_{tf}_{strategy}_np{net}_dd{dd}_pf{pf}_tc{trades}.pine
Pair/timeframe reports are written under: results/optimizations/<symbol>/<timeframe>/

`pine-batch-optimize` — Run Matrix Optimization for Many Pine Files

hyperview pine-batch-optimize --input-dir strategies/raw --symbols OANDA:XAUUSD OANDA:EURUSD --timeframes 15m 1h

Runs pine-optimize for each pine x symbol x timeframe.
Writes aggregate leaderboard files:
- results/optimizations/leaderboard.json
- results/optimizations/leaderboard.md

Indicators

HyperView ships with 20 wrapped indicators backed by TA-Lib, plus 4 signal helpers. You also have direct access to all 150+ TA-Lib functions via the to_numpy / wrap conversion helpers.

Wrapped Indicators

Category	Functions
Moving Averages	`ema`, `sma`, `wma`
Momentum	`rsi`, `macd`, `stochastic`, `stochastic_rsi`, `cci`, `williams_r`, `momentum`, `roc`
Trend	`adx` (returns ADX, +DI, −DI), `aroon` (returns down, up), `psar`
Volatility	`atr`, `bollinger_bands` (returns upper, middle, lower)
Volume	`obv`, `mfi`, `ad`, `vwap`

Signal Helpers

Function	Description
`crossed_above(a, b)`	True on bars where `a` crosses above `b`
`crossed_below(a, b)`	True on bars where `a` crosses below `b`
`barssince(cond)`	Bars since condition was last True
`to_unix_timestamp(dt)`	Convert ISO date string to UTC unix timestamp

Using TA-Lib Directly

For any of TA-Lib's 150+ functions not wrapped above, call talib directly and use the conversion helpers:

import talib
from strategy.indicators import to_numpy, wrap

df["cci"] = wrap(talib.CCI(to_numpy(df["high"]),
                            to_numpy(df["low"]),
                            to_numpy(df["close"]), timeperiod=20), df.index)

Adding Custom Strategies

Create a new file in strategy/ (e.g. my_strategy.py)
Subclass BaseStrategy and implement generate_signals(), default_settings(), required_columns()
Decorate the class with @register_strategy

Strategies are auto-discovered at startup — no manual imports needed.

from strategy import register_strategy
from strategy.base import BaseStrategy
from strategy.indicators import ema, crossed_above

@register_strategy
class MyStrategy(BaseStrategy):
    strategy_name = "my_strategy"

    def default_settings(self):
        return {"fast_period": 10, "slow_period": 20}

    def required_columns(self):
        return ["time", "open", "high", "low", "close"]

    def generate_signals(self, candles, settings):
        df = self.prepare_candles(candles)

        fast = ema(df["close"], settings["fast_period"])
        slow = ema(df["close"], settings["slow_period"])

        df["buy_signal"] = crossed_above(fast, slow)
        df["sell_signal"] = crossed_above(slow, fast)
        df["in_date_range"] = True
        df["enable_long"] = True
        df["enable_short"] = False

        return df

Then use it: hyperview backtest --symbol NASDAQ:NFLX --strategy my_strategy --sl 5 --tp 5

Output Files

Hyperopt updates a strategy preset file in results/:

results/macd_rsi_presets.json

Each file stores one best preset per exact pair + timeframe + session + adjustment + mode combination for that strategy. Re-running hyperopt replaces only the matching entry and preserves other contexts already saved in the file.

Backtest Assumptions

The simulator approximates TradingView's intrabar fill behavior:

Entry: Signal-generated market orders fill on the next bar open
Intrabar path: If a bar opens closer to its high, path is open → high → low → close; closer to its low, path is open → low → high → close
Position sizing: 100% of equity per trade, no pyramiding
SL/TP exits: Checked against the intrabar price path within the same bar

Name		Name	Last commit message	Last commit date
hyperview		hyperview
scripts		scripts
strategy		strategy
tests		tests
.copilotignore		.copilotignore
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
README.vi.md		README.vi.md
config.json		config.json
config.schema.json		config.schema.json
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation

HyperView

Support This Project

Pain Points

Solution

Key Features

FAQ (Pro Account & Tick Data)

Can I use HyperView without a TradingView Pro account?

Does HyperView support tick data?

Is 1m data equivalent to tick data?

Can this be used for tick-level/HFT validation?

Do I need any TradingView API key?

Practical Outcomes

Improvements Over The Original Fork Source

Prerequisites

Core runtime requirements

Additional requirements to use fork improvements fully

Verification baseline (recommended before serious runs)

Install & Run Anywhere

Option A (Recommended, npx-like): uvx

Option B (npm -g-like): pipx

Option C (Universal fallback): pip

Bootstrap Scripts (from this repo)

Quick Start (Project Development)

Fast Workflow With Codex CLI / Claude Code

1) One-time setup

2) Prompt examples for AI CLI

3) Quick verification before commit

4) Tips for better AI output quality

How It Works

Terminal Output

Repository Layout

strategy/ — Pluggable Strategy Framework

hyperview/ — Core Engine

Configuration

Pairlist

CLI Reference

Migration Notes

download-data — Fetch Candle Data

backtest — Single Strategy Evaluation

hyperopt — Hyper-Optimize SL/TP

list-data — Show Cached Datasets

list-strategies — Show Available Strategies

pine-optimize — Optimize Pine Inputs + Export Best Pine

pine-batch-optimize — Run Matrix Optimization for Many Pine Files

Indicators

Wrapped Indicators

Signal Helpers

Using TA-Lib Directly

Adding Custom Strategies

Output Files

Backtest Assumptions

About

Topics

Resources

Stars

Watchers

Forks

Used by

Contributors

Languages