deepentropy/tvscreener: Python Library for TradingView Market Data

deepentropy/tvscreener: Python^{↗ Bright Coding Blog} Library for TradingView Market Data

Developers building quantitative strategies, market monitors, or financial data pipelines often hit the same wall: official APIs are gated behind paywalls, rate-limited, or don't expose the granular screening filters that traders actually use. TradingView's web screener is powerful—13,000+ fields across multiple asset classes, technical indicators with arbitrary time intervals—but there's no sanctioned programmatic interface. This is the gap that deepentropy/tvscreener addresses. It's an unofficial Python library that wraps TradingView's publicly available screener endpoints, giving you DataFrame-ready market data without browser automation or reverse-engineering the frontend yourself.

What is deepentropy/tvscreener?

deepentropy/tvscreener is an open-source Python library maintained by the GitHub user deepentropy. The project sits at the intersection of financial data access and developer tooling: it provides a structured, Pythonic interface to TradingView's screener functionality, which covers six asset classes—stocks, cryptocurrency, forex, bonds, futures, and coins (CEX and DEX). The repository has accumulated 1,109 stars and 164 forks as of its last commit on July 13, 2026, with JavaScript^{↗ Bright Coding Blog} appearing as the primary language in GitHub's metadata (likely referring to the web-based Code Generator component, while the library itself is Python). It's released under the Apache License 2.0.

The library is explicitly unofficial and unaffiliated with TradingView, Inc.—a disclaimer the maintainers foreground prominently. This matters for developers evaluating it: the project depends on TradingView's public endpoints remaining accessible, and users bear the risk of terms-of-service changes. That said, the library has evolved substantively. The v0.1.0 release expanded from roughly 300 fields to 13,000+ fields, added five new screener types beyond the original stock screener, and introduced a fluent API with type-safe validation. The v0.2.0 release added MCP (Model Context Protocol) server integration, enabling AI assistants like Claude to query market data directly—a signal of where the project is heading.

The maintainers also ship a web-based Code Generator that lets you build screener queries visually and export Python code, lowering the barrier for users who don't want to memorize field names or filter syntax.

Key Features

Six Screener Types — The library covers equities (StockScreener), foreign exchange (ForexScreener), cryptocurrencies (CryptoScreener), government and corporate bonds (BondScreener), futures contracts (FuturesScreener), and coins from centralized and decentralized exchanges (CoinScreener). This breadth is unusual among unofficial TradingView wrappers, most of which focus exclusively on stocks or crypto.

13,000+ Fields with Discovery Tools — The field expansion in v0.1.0 was the project's most significant technical leap. Fields span fundamental data, technical indicators, performance metrics, and analyst ratings. The library provides search(), technicals(), and recommendations() methods on field classes to navigate this surface area without consulting external documentation.

Arbitrary Time Intervals for Technicals — Technical indicators aren't locked to daily resolution. You can request RSI, MACD, or moving averages at 1-minute, 5-minute, 15-minute, 30-minute, 1-hour, 2-hour, 4-hour, daily, weekly, or monthly intervals. Notably, the README states this works "no need to be a registered user"—a relevant detail for developers who want to avoid authentication complexity.

Fluent API with Type Safety — The select() and where() methods support method chaining, and the library validates that you're using fields compatible with your chosen screener. This catches category errors at construction time rather than at request time.

Styled Output and Streaming — Results come back as Pandas DataFrames. The beautify() function applies TradingView-style formatting: color-coded ratings, directional arrows, K/M/B/T suffixes for large numbers. The stream() method supports continuous polling with configurable intervals and callbacks for real-time monitoring.

MCP Server for AI Integration — The v0.2.0 MCP server exposes tools like discover_fields, custom_query, and asset-specific search functions, allowing AI assistants to retrieve market data as part of multi-step reasoning workflows.

Use Cases

Quantitative Screening and Strategy Backtesting — A developer building a value investing scanner can use STOCK_VALUATION_FIELDS and STOCK_DIVIDEND_FIELDS presets, apply market cap and P/E filters through the fluent API, and pipe results directly into a backtesting framework like Backtrader or Zipline. The DataFrame output eliminates parsing overhead.

Multi-Asset Monitoring Dashboards — The streaming API with on_update callbacks suits real-time dashboards. A DevOps^{↗ Bright Coding Blog} engineer could deploy a lightweight monitoring service that polls bond spreads, forex volatility, and crypto top movers at different intervals, feeding a [INTERNAL_LINK: time-series database] or alerting system.

AI-Assisted Market Research — With MCP server integration, researchers using Claude Code or similar tools can ask natural-language questions like "Which large-cap tech stocks have RSI below 30 on the 4-hour chart?" and receive structured data without leaving their development environment.

Cross-Market Arbitrage Signal Generation — The CoinScreener's coverage of both CEX and DEX coins, combined with forex and futures data, enables developers to build unified views across traditionally siloed markets—useful for detecting basis trades or funding rate anomalies.

Educational Financial Data Access — For students or independent researchers without institutional data subscriptions, the library provides a zero-cost entry point to structured market data for analysis and visualization projects.

Installation & Setup

The library is distributed via PyPI and installable with standard Python tooling.

Standard installation:

pip install tvscreener

Install from GitHub (latest development version):

pip install git+https://github.com/deepentropy/tvscreener.git

With MCP server support (v0.2.0+):

pip install tvscreener[mcp]

The [mcp] extra pulls in dependencies required for the Model Context Protocol server. After installation, the tvscreener-mcp command becomes available:

# Run the MCP server
tvscreener-mcp

# Register with Claude Code
claude mcp add tvscreener -- tvscreener-mcp

No API keys or authentication tokens are required for basic usage—this is a deliberate design choice that simplifies initial setup. The library communicates with TradingView's public endpoints. For production deployments, consider implementing your own rate-limiting logic; the README notes a minimum 1.0-second interval for streaming to avoid triggering TradingView's protections.

Real Code Examples

Basic screener usage across asset classes:

import tvscreener as tvs

# Stock Screener — returns 150 rows by default
ss = tvs.StockScreener()
df = ss.get()

# Forex Screener
fs = tvs.ForexScreener()
df = fs.get()

# Crypto Screener
cs = tvs.CryptoScreener()
df = cs.get()

# Bond, Futures, and Coin screeners (added in v0.1.0)
bs = tvs.BondScreener()
df = bs.get()

futs = tvs.FuturesScreener()
df = futs.get()

coins = tvs.CoinScreener()  # CEX and DEX coins
df = coins.get()

This example demonstrates the consistent interface across all six screeners. Each screener class follows the same .get() contract, returning a Pandas DataFrame. The default 150-row limit applies uniformly; pagination or larger result sets would require additional parameters not shown in the README's basic examples.

Fluent API with field selection and filtering:

from tvscreener import StockScreener, StockField

ss = StockScreener()

# Select specific columns to reduce payload
ss.select(
    StockField.NAME,
    StockField.PRICE,
    StockField.CHANGE_PERCENT,
    StockField.VOLUME,
    StockField.MARKET_CAPITALIZATION
)

# Apply filters using Pythonic comparison operators
ss.where(StockField.MARKET_CAPITALIZATION > 1e9)  # Large cap only
ss.where(StockField.CHANGE_PERCENT > 5)           # Movers > 5%

df = ss.get()

The fluent API replaces the imperative style of building query dictionaries. The where() method overloads comparison operators—>, >=, <, <=, between(), isin()—which the library translates into TradingView's internal filter format. Type validation ensures you don't accidentally pass a StockField to a CryptoScreener.

Technical indicators with custom time intervals:

from tvscreener import StockScreener, StockField

ss = StockScreener()

# RSI with 1-hour interval
rsi_1h = StockField.RELATIVE_STRENGTH_INDEX_14.with_interval("60")

# MACD with 4-hour interval
macd_4h = StockField.MACD_LEVEL_12_26.with_interval("240")

ss.specific_fields = [
    StockField.NAME,
    StockField.PRICE,
    rsi_1h,
    macd_4h,
]

df = ss.get()

The with_interval() method is critical for multi-timeframe analysis. The string values correspond to TradingView's interval notation: "1", "5", "15", "30", "60", "120", "240", "1D", "1W", "1M". This example retrieves hourly RSI and 4-hour MACD in a single query—functionality that typically requires multiple API calls or websocket subscriptions with official data providers.

Streaming with callback:

import tvscreener as tvs
from datetime import datetime

def on_update(df):
    print(f"Updated at {datetime.now()}: {len(df)} rows")

ss = tvs.StockScreener()

# Poll every 5 seconds, run until interrupted
try:
    for df in ss.stream(interval=5, on_update=on_update):
        pass  # Process DataFrame
except KeyboardInterrupt:
    print("Stopped streaming")

The stream() method returns a generator that yields DataFrames at the specified interval. The on_update callback runs before each yield, useful for logging or triggering downstream actions. The README explicitly warns that interval should stay at or above 1.0 seconds to respect rate limits.

Advanced Usage & Best Practices

Field Discovery at Runtime — With 13,000+ fields, memorization isn't feasible. Use StockField.search("rsi") or StockField.technicals() to programmatically discover available metrics. This is especially valuable when building user-facing tools where query requirements aren't known in advance.

Preset Composition — The built-in presets (STOCK_VALUATION_FIELDS, STOCK_DIVIDEND_FIELDS, etc.) are concatenatable lists. Combine them for domain-specific screens: STOCK_VALUATION_FIELDS + STOCK_DIVIDEND_FIELDS for income-focused value strategies. Check list_presets() for available categories.

Styled Output for Presentation — The beautify() function is designed for Jupyter/IPython environments. It mutates rating columns to colored HTML and formats large numbers. Use it for final presentation layers, not for intermediate processing where raw numeric types are needed.

Rate Limit Defensively — The library has no built-in rate limiter beyond the streaming interval minimum. For production polling, implement exponential backoff and respect HTTP 429 responses. TradingView's tolerance for unofficial access is undocumented and subject to change.

Version Pinning for Stability — The project is actively developed (last commit July 2026) with breaking changes between minor versions. Pin to specific versions in requirements files and review changelogs before upgrading, particularly if you depend on MCP server functionality.

Comparison with Alternatives

tvdatafeed excels for real-time price feeds but requires managing websocket connections and doesn't expose TradingView's screening logic. tradingview-ta is lighter weight but stuck at a smaller feature set. yfinance is more robust for historical fundamentals but lacks the technical indicator granularity and cross-asset screening that deepentropy/tvscreener provides. The trade-off is clear: deepentropy/tvscreener offers more functionality at the cost of unofficial, potentially unstable access.

FAQ

Is deepentropy/tvscreener officially supported by TradingView?
No. The README states explicitly: "This is an unofficial, third-party library and is not affiliated with, endorsed by, or connected to TradingView™ in any way."

What Python versions are supported?
The README doesn't specify; check PyPI metadata or test in your environment.

Do I need a TradingView account?
No. The README notes that technical indicators with arbitrary time intervals work "no need to be a registered user."

Can I use this for commercial trading systems?
The Apache 2.0 license permits commercial use, but TradingView's terms of service for their endpoints take precedence. Consult legal advice for production financial systems.

How does the MCP server work?
Install with pip install tvscreener[mcp], run tvscreener-mcp, and register with compatible AI assistants like Claude Code via claude mcp add.

What happens if TradingView changes their API?
The library may break. There's no SLA or official channel for updates. Monitor the GitHub repository for maintainer responses.

Is there a limit on results?
The default .get() returns 150 rows. The README doesn't document pagination parameters for larger result sets.

Conclusion

deepentropy/tvscreener fills a specific niche: developers who need programmatic access to TradingView's screening capabilities across multiple asset classes, with minimal setup friction and native Python ergonomics. The 13,000+ field coverage, arbitrary technical time intervals, and recent MCP server integration make it substantially more capable than earlier unofficial alternatives. The trade-offs are real—unofficial status, dependency on public endpoints, no guaranteed stability—but for research tools, personal strategies, and rapid prototyping, the productivity gain is significant.

The project is best suited for: quantitative developers building screening pipelines, AI-assisted research workflows, and monitoring tools where real-time official feeds aren't justified by cost. It's less appropriate for regulated financial products or systems where data provenance must be auditable.

Explore the repository, try the Code Generator, and review the full documentation to evaluate fit for your stack. The source is available at https://github.com/deepentropy/tvscreener.