tvkit

tvkit — Async Python client for TradingView market data.

Access real-time and historical TradingView data with a modern async Python API. Designed for quantitative research, trading tools, and data pipelines.

Features

• Real-time OHLCV streaming via WebSocket with async generators
• Automatic reconnection with exponential backoff — transient disconnects recovered transparently
• Historical data retrieval by bar count or explicit date range
• Automatic segmented fetching for large historical OHLCV date ranges (TradingView historical depth limits still apply)
• Multi-market scanner: 69 global markets, 101+ financial metrics
• Multi-format data export: Polars DataFrames, JSON, CSV
• Symbol format auto-conversion: EXCHANGE-SYMBOL and EXCHANGE:SYMBOL both accepted
• Async symbol validation with retry and flexible format support
• Full type safety with Pydantic models throughout
• Python 3.11+ with async/await and context manager patterns

Installation

Available on PyPI: https://pypi.org/project/tvkit/

uv add tvkit        # recommended
pip install tvkit

Quick Example

import asyncio
from tvkit.api.chart.ohlcv import OHLCV

async def main() -> None:
    async with OHLCV() as client:
        # Fetch last 10 daily bars for Apple
        bars = await client.get_historical_ohlcv(
            exchange_symbol="NASDAQ:AAPL",
            interval="1D",
            bars_count=10,
        )
    for bar in bars:
        print(bar.timestamp, bar.close)
        # 1785850200.0 309.38

asyncio.run(main())

Output:

10 rows total, showing 5

date is derived — OHLCVBar has 6 fields: timestamp, open, high, low, close, volume

The print() above emits the first and sixth columns only: 1785850200.0 309.38.

Example output — live market values will differ.

See more working examples in examples/.

Authenticated Sessions

Authenticate with your TradingView account to unlock larger historical data windows beyond the anonymous 5,000-bar limit. See TradingView Pricing for the full plan comparison.

# Browser cookie extraction — Chrome or Firefox (must be logged in to TradingView)
async with OHLCV(browser="chrome") as client:
    await client.wait_until_ready()           # optional: wait for probe-confirmed max_bars
    account = client.account
    if account:
        print(f"Tier: {account.tier}, max_bars: {account.max_bars}")
    bars = await client.get_historical_ohlcv(
        exchange_symbol="NASDAQ:AAPL",
        interval="1D",
        bars_count=10_000,
    )

# Firefox
async with OHLCV(browser="firefox") as client: ...

# Direct token injection (CI/CD — no browser required)
async with OHLCV(auth_token=os.environ["TVKIT_AUTH_TOKEN"]) as client: ...

# Anonymous (default — no changes required)
async with OHLCV() as client: ...

Environment variables (alternative to kwargs):

export TVKIT_BROWSER=chrome        # equivalent to OHLCV(browser="chrome")
export TVKIT_AUTH_TOKEN=<token>    # equivalent to OHLCV(auth_token=...)

Troubleshooting:

• BrowserCookieError — not logged in to TradingView in the browser; log in and retry
• ProfileFetchError — session expired; log out and back in to TradingView

More details: Authenticated Sessions Guide · Account Capabilities · Auth Reference

Automatic Reconnection

Reconnection is on by default — no changes needed to existing call sites:

async with OHLCV() as client:
    # Transient disconnects are recovered automatically (5 attempts, 1s–30s backoff).
    async for bar in client.get_ohlcv("NASDAQ:AAPL", "1D"):
        print(bar.close)

Output:

309.38
311.0
312.41
313.33
...

The stream replays the bars_count window first, then waits for live updates — it does not terminate on its own.

Tune it for long-running pipelines:

from tvkit.api.chart import OHLCV, StreamConnectionError

async with OHLCV(max_attempts=10, base_backoff=2.0, max_backoff=60.0) as client:
    try:
        async for bar in client.get_ohlcv("NASDAQ:AAPL", "1D"):
            print(bar.close)
    except StreamConnectionError:
        print("Stream permanently lost after all attempts")

Output:

309.38
311.0
312.41
313.33
...

Identical while the connection holds. StreamConnectionError is raised only after all 10 attempts are exhausted, printing Stream permanently lost after all attempts.

Symbol Format Reference

Canonical format: EXCHANGE:SYMBOL. Dash notation (EXCHANGE-SYMBOL) is automatically converted. See concepts/symbols.md for the full reference.

Documentation

Full documentation index → docs/index.md

Getting Started

• Installation — Python version, uv, pip, source install, verification
• Quickstart — Four self-contained examples in under 15 lines each
• First Script — Annotated walkthrough from install to first data fetch

Concepts

• Symbols — Format rules, exchange prefixes, auto-conversion
• Intervals — All supported timeframes and format strings
• Streaming vs Historical — When to use each method
• Scanner Columns — Column sets and when to use each
• Account Capabilities — Plan tiers, bar limits, and capability detection

Guides

• Historical Data — Bar count mode, date-range mode, Polars integration
• Real-time Streaming — WebSocket streaming, multiple symbols, reconnection
• Authenticated Sessions — Browser cookies, token injection, capability detection
• Scanner — 69 global markets, sorting, pagination, regional analysis
• Exporting Data — DataExporter, CSV, JSON, Polars with metadata
• Macro Indicators — INDEX:NDFI, USI:PCC, regime detection

Reference

• Chart API — OHLCV client: all methods, parameters, return types
• Authentication — tvkit.auth — AuthManager, TradingViewCredentials, TradingViewAccount
• Chart Utils — Interval validation, timestamp utilities
• Scanner API — ScannerService interface and request models
• Markets — All 69 markets, regions, exchange identifiers
• Export API — DataExporter interface and export formats
• Full Reference Index

Architecture

• System Overview — Four modules, async rationale, module dependencies
• WebSocket Protocol — TradingView message format, session lifecycle

Development

• Release Process — Quality gates, version bump, publish
• Testing Strategy — Test organisation, mocking, coverage
• Architecture Decisions — Key decisions with rationale

Support

• FAQ — Symbol formats, bar limits, async requirement, disconnect handling
• Roadmap — Planned features
• Why tvkit — Design goals, vs rolling your own WebSocket
• Limitations — Bar caps, rate limits, data coverage gaps
• Data Sources — TradingView data origin, real-time vs delayed

Examples

Working scripts in examples/ — clone the repo and run immediately.

Why tvkit

TradingView provides powerful market data but does not offer an official Python SDK. tvkit implements the TradingView WebSocket protocol and provides:

• A clean async Python API
• Strong typing via Pydantic
• Structured OHLCV models
• High-level data utilities (export, scanners)

Without needing to reverse-engineer the protocol yourself. See docs/why-tvkit.md for the full rationale.

Stability

tvkit is under active development. The public API is expected to remain stable within minor versions. Breaking changes will follow semantic versioning.

Contributing

See CONTRIBUTING.md for the development environment setup, quality gate commands, and pull request process.

Quality gates before every commit:

uv run ruff check .
uv run ruff format .
uv run mypy tvkit/
uv run python -m pytest tests/ -v

License

MIT — see LICENSE