TVdataOption

A high-performance, production-ready Python library and CLI tool for scraping and analyzing options market data directly from TradingView.

TVdataOption offers 100% anonymous data extraction across any asset class (Commodities, Equities, Indices, and Crypto), flexible time and expiration filtering, complete option chains with Greeks, and historical OHLCV candlesticks for individual option contracts.

Highlights

100% Anonymous Scraping:
- Operates out-of-the-box with zero credentials or login required.
- Automatically rotates realistic browser User-Agents (Chrome, Firefox, Safari on Windows, Mac, Linux).
- Built-in proxy configuration (http_proxy/https_proxy) to protect your IP and prevent rate limits.
Universal Asset Coverage:
- Commodities & Futures: Gold (COMEX:GC1!), Crude Oil (NYMEX:CL1!), S&P 500 (CME:ES1!), Nasdaq (CME:NQ1!), 30Y Treasury (CBOT:ZB1!), Silver (COMEX:SI1!).
- Equities & ETFs: Apple (NASDAQ:AAPL), Nvidia (NASDAQ:NVDA), Tesla (NASDAQ:TSLA), SPY (AMEX:SPY), QQQ (NASDAQ:QQQ).
- Crypto Options: CME Bitcoin (CME:BTC1!), CME Ether (CME:ETH1!).
- Asset Discovery: Search option-enabled symbols across any market via tv.search_symbols("BTC", asset_type=AssetType.FUTURES).
Flexible Expiration & Time Filtering:
- Filter by specific expiration series (e.g. series="20260909").
- Filter by date range (start_date="2026-09-01", end_date="2026-10-31").
- Filter by Days To Expiration (min_dte=7, max_dte=45).
- Extract all available expirations simultaneously.
Maximum Data Extraction (get_complete_option_surface):
- Joins Volume, Open Interest, Greeks, Implied Volatility, and Pricing into a unified 29-column dataset:
  - Contract Info: symbol, root, currency, strike, option_type, expiration
  - Expiry Metric: dte (Days To Expiration)
  - Greeks: delta, gamma, theta, vega, rho
  - Volatility: iv, bid_iv, ask_iv
  - Market Pricing: bid, ask, mid_price, spread, spread_pct, theo_price (Black-Scholes theoretical price)
  - Trading Activity: volume (strike-level call/put volume), open_interest
  - Quantitative Valuation: underlying_price, moneyness, intrinsic_value, extrinsic_value, in_the_money, breakeven
Historical Candlesticks (get_option_hist):
- Fetch historical OHLCV bars (Open, High, Low, Close, Volume) for any individual option contract.
- Supports standard timeframes: 1m, 5m, 15m, 1h, 1D, 1W.
Parallel Multi-Asset Extraction:
- Concurrent thread-pooled fetching across a list of assets (e.g. ["COMEX:GC1!", "NYMEX:CL1!", "AMEX:SPY"]).
Command-Line Interface (CLI):
- Command-line tool tvdataoption supporting search, surface extraction, historical candles, and CSV/JSON export.

Installation

Install in editable mode:

git clone https://github.com/Hewkaw02/TVdataOptionOI.git
cd TVdataOptionOI
pip install -e .

Or install dependencies directly:

pip install -r requirements.txt

Quickstart & Example Outputs

1. Anonymous URL Scraping

Pass any TradingView options URL directly to extract structured data in milliseconds without opening a browser:

from tvdataoption import TvDataOption, get_volume_summary

# 100% Anonymous mode (default)
tv = TvDataOption(anonymous=True)

url = "https://www.tradingview.com/options/volume/?symbol=COMEX%3AGC1%21&series=20260909&tab=by-strike"
df = tv.from_url(url)

print(df.sort_values(by="total_volume", ascending=False).head(10))

# Quantitative analytics summary
summary = get_volume_summary(df)
print("\n--- Summary Analysis ---")
print(f"Total Call Volume  : {summary['total_call_volume']:,}")
print(f"Total Put Volume   : {summary['total_put_volume']:,}")
print(f"Total Volume       : {summary['total_volume']:,}")
print(f"Put/Call Ratio     : {summary['put_call_ratio']}")
print(f"Max Pain Strike    : {summary['max_pain_strike']}")
print(f"Highest Call Strike: {summary['highest_call_strike']}")
print(f"Highest Put Strike : {summary['highest_put_strike']}")

Output:

 strike  call_volume  put_volume  total_volume  put_call_ratio  net_volume
 4350.0           10         161           171         16.1000        -151
 4450.0          146          13           159          0.0890         133
 4395.0          121          21           142          0.1736         100
 4440.0          130           1           131          0.0077         129
 4375.0            5         105           110         21.0000        -100
 4400.0           82           8            90          0.0976          74
 4335.0            0          65            65             NaN         -65
 4500.0           19          39            58          2.0526         -20
 4390.0           21          29            50          1.3810          -8
 4330.0            0          46            46             NaN         -46

--- Summary Analysis ---
Total Call Volume  : 1,082
Total Put Volume   : 947
Total Volume       : 2,029
Put/Call Ratio     : 0.8752
Max Pain Strike    : 4395.0
Highest Call Strike: 4450.0
Highest Put Strike : 4350.0

2. Complete Option Surface (29 Columns)

Extract the complete option surface (all strikes $\times$ expirations $\times$ Greeks $\times$ volume):

from tvdataoption import TvDataOption

tv = TvDataOption(anonymous=True)

# Extracts 29 data fields for COMEX Gold Futures
df = tv.get_complete_option_surface(symbol="COMEX:GC1!", series="20260909")

print(f"Total contracts: {len(df)}")
cols = ["symbol", "strike", "option_type", "volume", "mid_price", "iv", "delta", "gamma", "theta", "moneyness", "breakeven"]
print(df[cols].head(6))

Output:

Total contracts: 456

              symbol  strike option_type  volume  mid_price       iv    delta    gamma      theta  moneyness  breakeven
COMEX:G2W260909C4450    4450        call     146       6.95 0.274787 0.252938 0.006845 -13.853294     0.9992    4456.95
COMEX:G2W260909C4440    4440        call     130       9.50 0.272803 0.324254 0.007754 -15.471554     0.9969    4449.50
COMEX:G2W260909C4395    4395        call     121      32.75 0.278053 0.693304 0.007429 -15.443569     0.9868    4427.75
COMEX:G2W260909C4400    4400        call      82      29.80 0.276376 0.655903 0.007835 -16.082945     0.9879    4429.80
COMEX:G2W260909P4350    4350         put     161       2.05 0.303642 -0.089378 0.003130  -7.706711     0.9767    4347.95
COMEX:G2W260909P4375    4375         put     105       5.20 0.287212 -0.183464 0.005439 -11.976636     0.9823    4369.80

3. Expiration Summary & Time Filtering

Aggregate options volume per expiration or filter by Days To Expiration (DTE):

from tvdataoption import TvDataOption

tv = TvDataOption(anonymous=True)

# Volume per expiration series
df_exp = tv.get_option_volume_by_expiration("COMEX:GC1!")
print(df_exp.head(6))

Output:

expiration           expiration_time  dte     underlying family  call_volume  put_volume  total_volume  put_call_ratio  strikes_count
  20260909 2026-09-09T16:59:59-04:00    0  COMEX:GCV2026    G2W         1082         947          2029          0.8752            228
  20260910 2026-09-10T16:59:59-04:00    1  COMEX:GCV2026    G2R         1056         834          1890          0.7898            222
  20260911 2026-09-11T16:59:59-04:00    2  COMEX:GCV2026    OG2         1445        1216          2661          0.8415            211
  20260914 2026-09-14T16:59:59-04:00    5  COMEX:GCV2026    G2M         1964         278          2242          0.1415            210
  20260915 2026-09-15T16:59:59-04:00    6  COMEX:GCV2026    G3T          522         237           759          0.4540            205
  20260924 2026-09-24T16:59:59-04:00   15  COMEX:GCV2026     OG         4925        3627          8552          0.7364            640

4. Search Option-Enabled Assets

Discover assets with active options across any exchange or asset class:

from tvdataoption import TvDataOption, AssetType

tv = TvDataOption(anonymous=True)

# Search for Bitcoin futures options
btc_assets = tv.search_symbols("BTC", asset_type=AssetType.FUTURES)
for item in btc_assets:
    print(f"{item.full_symbol:<16} | {item.description}")

# Search for equity options (e.g. Nvidia)
nvda_assets = tv.search_symbols("NVDA", asset_type=AssetType.STOCK)
for item in nvda_assets:
    print(f"{item.full_symbol:<16} | {item.description}")

Output:

CME:BTC          | Bitcoin Futures
CME:MBT          | Micro Bitcoin Futures
NASDAQ:NVDA      | NVIDIA Corporation
NYSE Arca:SPY    | SPDR S&P 500 ETF TRUST

5. Historical Option Candlesticks (OHLCV)

Fetch historical candlesticks for specific option contracts:

from tvdataoption import TvDataOption, Interval

tv = TvDataOption(anonymous=True)

# Daily candlesticks for Gold Call 4400
df_daily = tv.get_option_hist(
    symbol="COMEX:G2W260909C4400",
    interval=Interval.in_daily,
    n_bars=30,
)
print(df_daily.tail(5))

Output:

                            open   high    low  close  volume                symbol
datetime                                                                           
2026-08-30 22:00:00+00:00   92.8   92.8   92.8   92.8     1.0  COMEX:G2W260909C4400
2026-09-01 22:00:00+00:00   33.0   51.3   33.0   51.3    19.0  COMEX:G2W260909C4400
2026-09-03 22:00:00+00:00   49.2   72.0   49.2   65.9    42.0  COMEX:G2W260909C4400
2026-09-06 22:00:00+00:00   30.0   30.0   12.0   12.0   199.0  COMEX:G2W260909C4400
2026-09-08 22:00:00+00:00   12.1   20.0    9.0   20.0    82.0  COMEX:G2W260909C4400

6. Multi-Asset Batch Extraction

Concurrently fetch option surfaces for multiple tickers in parallel:

from tvdataoption import TvDataOption

tv = TvDataOption(anonymous=True)

assets = ["COMEX:GC1!", "NYMEX:CL1!", "AMEX:SPY"]
results = tv.fetch_multi_assets(assets, max_workers=3)

for sym, df in results.items():
    print(f"{sym}: Extracted {len(df):,} contracts with {len(df.columns)} fields")

Output:

COMEX:GC1!: Extracted 36,553 contracts with 29 fields
NYMEX:CL1!: Extracted 18,240 contracts with 29 fields
AMEX:SPY  : Extracted 12,247 contracts with 29 fields

7. Proxy Support for Enhanced Anonymity

Route requests through custom proxy servers:

from tvdataoption import TvDataOption

tv = TvDataOption(
    anonymous=True,
    proxy="http://user:password@proxy-host:8080"
)

Command Line Interface (CLI)

Use the built-in CLI tool tvdataoption for terminal workflows and automated data dumps:

# 1. Scrape from URL and export to CSV with summary statistics
tvdataoption --url "https://www.tradingview.com/options/volume/?symbol=COMEX%3AGC1%21&series=20260909&tab=by-strike" --summary --csv gc_options.csv

# 2. Extract Complete Option Surface (all Greeks + Volume)
tvdataoption --symbol COMEX:GC1! --series 20260909 --tab surface --csv gc_surface.csv

# 3. Search for option-enabled assets
tvdataoption --search "BTC" --asset-type futures
tvdataoption --search "Gold"

# 4. Fetch historical option candles
tvdataoption --hist "COMEX:G2W260909C4400" --interval 1D --bars 30 --csv option_candles.csv

# 5. Filter by DTE range
tvdataoption --symbol AMEX:SPY --min-dte 14 --max-dte 60 --tab surface --csv spy_surface.csv

CLI Terminal Output Example:

$ tvdataoption --url "https://www.tradingview.com/options/volume/?symbol=COMEX%3AGC1%21&series=20260909&tab=by-strike" --summary

Fetching from URL: https://www.tradingview.com/options/volume/?symbol=COMEX%3AGC1%21&series=20260909&tab=by-strike

=============================================
  Options Summary for COMEX:GC1! (Series: 20260909)
=============================================
  Total Call Volume  : 1,082
  Total Put Volume   : 947
  Total Volume       : 2,029
  Put/Call Ratio     : 0.8752
  Max Pain Strike    : 4395.0
  Highest Call Strike: 4450.0
  Highest Put Strike : 4350.0
=============================================

Data Shape: 228 rows x 6 columns
 strike  call_volume  put_volume  total_volume  put_call_ratio  net_volume
 4350.0           10         161           171         16.1000        -151
 4450.0          146          13           159          0.0890         133
 4395.0          121          21           142          0.1736         100
 4440.0          130           1           131          0.0077         129
 4375.0            5         105           110         21.0000        -100
 ...

API Reference

`TvDataOption` Class

TvDataOption(
    username: Optional[str] = None,
    password: Optional[str] = None,
    auth_token: Optional[str] = None,
    proxy: Optional[Union[str, Dict[str, str]]] = None,
    anonymous: bool = True,
    timeout: int = 15,
)

Methods

Method	Parameters	Returns	Description
`get_complete_option_surface(...)`	`symbol, series, start_date, end_date, min_dte, max_dte`	`pd.DataFrame`	Extracts all 29 fields (Greeks, IV, prices, volume, moneyness, breakeven) into a unified dataset.
`get_option_hist(...)`	`symbol, interval, n_bars, extended_session`	`pd.DataFrame`	Downloads historical OHLCV candlesticks for any option contract.
`search_symbols(...)`	`query, asset_type, exchange, limit`	`List[SearchResult]`	Discovers option-enabled assets on TradingView.
`fetch_multi_assets(...)`	`symbols, series, max_workers`	`Dict[str, pd.DataFrame]`	Parallel extraction of complete surfaces across multiple assets.
`from_url(...)`	`url`	`pd.DataFrame`	Directly parses any TradingView options URL and extracts data.
`get_option_volume_by_strike(...)`	`symbol, series, aggregate_all, min_strike, max_strike`	`pd.DataFrame`	Strike-level call & put volume, Put/Call ratio, and net volume.
`get_option_volume_by_expiration(...)`	`symbol, start_date, end_date, min_dte, max_dte`	`pd.DataFrame`	Aggregates volume and contract counts per expiration date.
`get_option_volume_heatmap(...)`	`symbol, metric`	`pd.DataFrame`	Generates a strike $\times$ expiration volume matrix table.
`get_option_chain(...)`	`symbol, series, min_dte, max_dte, min_strike, max_strike`	`pd.DataFrame`	Returns full option contracts with Greeks and IV.
`get_summary(...)`	`symbol, series`	`dict`	Computes Put/Call Ratio, Total Volumes, and Max Pain Strike.

Running Tests

Execute the automated test suite with pytest:

pytest -v tests/

License

MIT License. Developed for quantitative research, algorithmic trading, and options market analytics.

Name		Name	Last commit message	Last commit date
examples		examples
scratch		scratch
tests		tests
tvdataoption		tvdataoption
.gitignore		.gitignore
README.md		README.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
setup.py		setup.py

Navigation Menu

Repository navigation

About

Repository files navigation

TVdataOption

Highlights

Installation

Quickstart & Example Outputs

1. Anonymous URL Scraping

Output:

2. Complete Option Surface (29 Columns)

Output:

3. Expiration Summary & Time Filtering

Output:

4. Search Option-Enabled Assets

Output:

5. Historical Option Candlesticks (OHLCV)

Output:

6. Multi-Asset Batch Extraction

Output:

7. Proxy Support for Enhanced Anonymity

Command Line Interface (CLI)

CLI Terminal Output Example:

API Reference

`TvDataOption` Class

Methods

Running Tests

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

TVdataOption

Highlights

Installation

Quickstart & Example Outputs

1. Anonymous URL Scraping

Output:

2. Complete Option Surface (29 Columns)

Output:

3. Expiration Summary & Time Filtering

Output:

4. Search Option-Enabled Assets

Output:

5. Historical Option Candlesticks (OHLCV)

Output:

6. Multi-Asset Batch Extraction

Output:

7. Proxy Support for Enhanced Anonymity

Command Line Interface (CLI)

CLI Terminal Output Example:

API Reference

TvDataOption Class

Methods

Running Tests

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`TvDataOption` Class