TradingView Screener

https://shner-elmo.github.io/TradingView-Screener/3.2.0/
Admin
TradingView Screener is a Python package that allows you to create custom stock screeners using...
Tokens:12,227
Snippets:83
Trust Score:9.7
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install tradingview-screener with pip

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener.html

Install the package using pip. Run this command in your terminal to install tradingview-screener.

```bash
pip install tradingview-screener

```

--------------------------------

### Install rookiepy

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener.html

Installs the rookiepy library, which loads cookies from your local browser.

```bash
pip install rookiepy

```

--------------------------------

### Output of basic query

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener.html

Example output from the basic query, showing the first and last rows of the returned DataFrame with 50 rows and 5 columns.

```text
(17580,
          ticker  name   close     volume  market_cap_basic
 0   NASDAQ:NVDA  NVDA  127.25  298220762      3.130350e+12
 1      AMEX:SPY   SPY  558.70   33701795               NaN
 2   NASDAQ:TSLA  TSLA  221.10   73869589      7.063350e+11
 3    NASDAQ:QQQ   QQQ  480.26   29102854               NaN
 4    NASDAQ:AMD   AMD  156.40   76693809      2.531306e+11
 ..          ...   ...     ...        ...               ...
 45   NASDAQ:PDD   PDD  144.22    8653323      2.007628e+11
 46     NYSE:JPM   JPM  214.52    5639973      6.103447e+11
 47     NYSE:JNJ   JNJ  160.16    7274621      3.855442e+11
 48  NASDAQ:SQQQ  SQQQ    7.99  139721164               NaN
 49  NASDAQ:ASTS  ASTS   34.32   32361315      9.245616e+09

 [50 rows x 5 columns])

```

--------------------------------

### Basic query: select fields and get scanner data

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener.html

Creates a Query, selects name, close, volume, and market_cap_basic, then retrieves scanner data. By default, the result is limited to 50 rows; adjust the limit to avoid server load and potential bans.

```python
from tradingview_screener import Query

x = (Query()
 .select('name', 'close', 'volume', 'market_cap_basic')
 .get_scanner_data())
print(x)

```

--------------------------------

### Verify Update Mode with Query().select('exchange', 'update_mode')

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener.html

Runs a query to get an overview of the update_mode for each exchange. The output shows that without cookies, all exchanges return 'delayed_streaming_900'.

```python
from tradingview_screener import Query

_, df = Query().select('exchange', 'update_mode').limit(1_000_000).get_scanner_data()
df = df.groupby('exchange')['update_mode'].value_counts()
print(df)

```

```text
exchange  update_mode          
AMEX      delayed_streaming_900    3255
NASDAQ    delayed_streaming_900    4294
NYSE      delayed_streaming_900    2863
OTC       delayed_streaming_900    7129

```

--------------------------------

### Example of API request dictionary generated by Query object

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener.html

Shows the dictionary structure constructed by the Query object when using methods like select() or where(). This dictionary is sent as a JSON payload to the TradingView API via get_scanner_data().

```python
{
    'markets': ['america'],
    'symbols': {'query': {'types': []}, 'tickers': []},
    'options': {'lang': 'en'},
    'columns': ['name', 'close', 'volume', 'relative_volume_10d_calc'],
    'sort': {'sortBy': 'volume', 'sortOrder': 'desc'},
    'range': [5, 25],
    'filter': [
        {'left': 'market_cap_basic', 'operation': 'in_range', 'right': [1000000, 50000000]},
        {'left': 'relative_volume_10d_calc', 'operation': 'greater', 'right': 1.2},
        {'left': 'MACD.macd', 'operation': 'egreater', 'right': 'MACD.signal'},
    ],
}

```

--------------------------------

### Other screeners: stocks, crypto, options

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener.html

Shows how to use the built-in screeners for stocks, crypto, and options. Each returns a Query object, so you can chain methods like .select(), .where(), .order_by(), etc.

```python
from tradingview_screener import stocks, crypto, options

# top stocks by market cap in Italy
stocks('italy').limit(5).get_scanner_data()

# top CEX crypto pairs by 24 h volume
crypto().limit(5).get_scanner_data()

# AAPL options chain
options('NASDAQ:AAPL').limit(5).get_scanner_data()

```

--------------------------------

### Advanced query with filters, ordering, and pagination

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener.html

Uses Query with col() to filter by market cap, relative volume, and 1-minute MACD crossover, then orders by volume descending, offsets by 5, limits to 25 rows, and retrieves scanner data.

```python
from tradingview_screener import Query, col

(Query()
 .select('name', 'close', 'close|1', 'close|5', 'volume', 'relative_volume_10d_calc')
 .where(
     col('market_cap_basic').between(1_000_000, 50_000_000),
     col('relative_volume_10d_calc') > 1.2,
     col('MACD.macd|1') >= col('MACD.signal|1')  # 1 minute MACD
 )
 .order_by('volume', ascending=False)
 .offset(5)
 .limit(25)
 .get_scanner_data())

```

--------------------------------

### Chain methods on options screener with filters

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener.html

Demonstrates chaining .select(), .where(), .order_by(), .limit(), and .get_scanner_data() on the options screener for AAPL, filtering by expiration date and ordering by strike.

```python
from tradingview_screener import options, col

(options('NASDAQ:AAPL')
 .select('name', 'close', 'ask', 'bid', 'expiration', 'volume')
 .where(col('expiration') == 20260427)  # 2026/4/27
 .order_by('strike')
 .limit(10)
 .get_scanner_data())

```

--------------------------------

### coin() -> Query

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/screeners.html

Creates a screener for crypto coins (CoinMarketCap universe), sorted by overall rank ascending.

```APIDOC
## coin() -> Query

### Description
Creates a screener for crypto coins (CoinMarketCap universe), sorted by overall rank ascending.

### Parameters
None

### Returns
- **Query** - A Query object configured for coin screening.
```

--------------------------------

### crypto() -> Query

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/screeners.html

Creates a screener for centralised-exchange (CEX) crypto pairs, sorted by 24 h volume descending.

```APIDOC
## crypto() -> Query

### Description
Creates a screener for centralised-exchange (CEX) crypto pairs, sorted by 24 h volume descending.

### Parameters
None

### Returns
- **Query** - A Query object configured for crypto screening.
```

--------------------------------

### coin() -> Query

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/screeners.html

Creates a Query object for screening crypto coins from the CoinMarketCap universe, sorted by overall rank ascending. The returned Query is pre-configured with the appropriate market, columns, and sorting.

```APIDOC
## coin() -> Query

### Description
Screener for crypto coins (CoinMarketCap universe), sorted by overall rank ascending.

### Method
Function call

### Signature
coin() -> Query

### Parameters
None

### Returns
- **Query** - A Query object configured for crypto coin screening.

### Usage Example
```python
from tradingview_screener.screeners import coin

# Create a crypto coin screener
query = coin()
```
```

--------------------------------

### forex() - Screener for forex currency pairs

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/screeners.html

Returns a Query for forex currency pairs sorted by traded value descending. Sets the market to 'forex' and includes columns for name, close, volume, and currency.

```python
def forex() -> Query:
    """
    Screener for forex currency pairs, sorted by traded value descending.
    """
    q = Query()
    q.url = URL.format(market='forex')
    q.query = {
        'markets': ['forex'],
        'symbols': {},
        'options': {'lang': 'en'},
        'columns': ['name', 'close', 'volume', 'currency'],
        'sort': {'sortBy': 'Value.Traded', 'sortOrder': 'desc'},
        'range': DEFAULT_RANGE.copy(),
        'ignore_unknown_fields': False,
    }
    return q
```

--------------------------------

### crypto_dex() -> Query

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/screeners.html

Creates a Query object for screening decentralised-exchange (DEX) spot pairs priced in USD, sorted by 24-hour transaction count descending. The returned Query is pre-configured with the appropriate market, columns, filters, and sorting.

```APIDOC
## crypto_dex() -> Query

### Description
Screener for decentralised-exchange (DEX) spot pairs priced in USD, sorted by 24 h transaction count descending.

### Method
Function call

### Signature
crypto_dex() -> Query

### Parameters
None

### Returns
- **Query** - A Query object configured for DEX spot pair screening.

### Usage Example
```python
from tradingview_screener.screeners import crypto_dex

# Create a DEX spot pair screener
query = crypto_dex()
```
```

--------------------------------

### Screener factory functions: stocks, coin, crypto, crypto_dex

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/screeners.html

Defines four screener factory functions in the tradingview_screener.screeners module. stocks() returns a Query for the given market (default 'america'), coin() builds a Query for the CoinMarketCap coin universe, crypto() targets CEX pairs, and crypto_dex() targets DEX USD pairs. Each function sets the URL market and a full query dict with columns, sort, range, and optional filter2.

```python
from __future__ import annotations

from tradingview_screener.query import Query, DEFAULT_RANGE, URL


def stocks(market: str = 'america') -> Query:
    """
    Screener for stocks (common, preferred, DRs, and non-ETF funds), filtered to primary listings
    only and sorted by market cap descending.

    :param market: Market/country to scan, e.g. ``'america'``, ``'italy'``, ``'germany'``.
        Defaults to ``'america'``.
    """
    return Query(market)


def coin() -> Query:
    """
    Screener for crypto coins (CoinMarketCap universe), sorted by overall rank ascending.
    """
    q = Query()
    q.url = URL.format(market='coin')
    q.query = {
        'markets': ['coin'],
        'symbols': {},
        'options': {'lang': 'en'},
        'columns': [
            'ticker-view',
            'crypto_total_rank',
            'close',
            'type',
            'typespecs',
            'pricescale',
            'minmov',
            'fractional',
            'minmove2',
            'currency',
            '24h_close_change|5',
            'market_cap_calc',
            'fundamental_currency_code',
            '24h_vol_cmc',
            'circulating_supply',
            '24h_vol_to_market_cap',
            'socialdominance',
            'crypto_common_categories.tr',
            'TechRating_1D',
            'TechRating_1D.tr',
        ],
        'sort': {'sortBy': 'crypto_total_rank', 'sortOrder': 'asc'},
        'range': DEFAULT_RANGE.copy(),
        'ignore_unknown_fields': False,
    }
    return q


def crypto() -> Query:
    """
    Screener for centralised-exchange (CEX) crypto pairs, sorted by 24 h volume descending.
    """
    q = Query()
    q.url = URL.format(market='crypto')
    q.query = {
        'markets': ['crypto'],
        'symbols': {},
        'options': {'lang': 'en'},
        'columns': [
            'ticker-view',
            'exchange.tr',
            'provider-id',
            'close',
            'type',
            'typespecs',
            'pricescale',
            'minmov',
            'fractional',
            'minmove2',
            'currency',
            '24h_close_change|5',
            '24h_vol|5',
            '24h_vol_change|5',
            'TechRating_1D',
            'TechRating_1D.tr',
        ],
        'filter2': {
            'operator': 'and',
            'operands': [
                {'expression': {'left': 'centralization', 'operation': 'equal', 'right': 'cex'}}
            ],
        },
        'sort': {'sortBy': '24h_vol|5', 'sortOrder': 'desc'},
        'range': DEFAULT_RANGE.copy(),
        'ignore_unknown_fields': False,
    }
    return q


def crypto_dex() -> Query:
    """
    Screener for decentralised-exchange (DEX) spot pairs priced in USD, sorted by 24 h transaction
    count descending.
    """
    q = Query()
    q.url = URL.format(market='crypto')
    q.query = {
        'markets': ['crypto'],
        'symbols': {},
        'options': {'lang': 'en'},
        'columns': [
            'ticker-view',
            'blockchain-id.tr',
            'blockchain-id',
            'exchange.tr',
            'provider-id',
            'close',
            'type',
            'typespecs',
            'pricescale',
            'minmov',
            'fractional',
            'minmove2',
            'currency',
            '24h_close_change|5',
            'dex_txs_count_24h',
            'dex_trading_volume_24h',
            'dex_txs_count_uniq_24h',
            'dex_total_liquidity',
            'fully_diluted_value',
            'TechRating_1D',
            'TechRating_1D.tr',
        ],
        'filter2': {
            'operator': 'and',
            'operands': [
                {
                    'operation': {
                        'operator': 'and',
                        'operands': [
                            {
                                'expression': {
                                    'left': 'centralization',
                                    'operation': 'equal',
                                    'right': 'dex',
                                }
                            },
                            {
                                'expression': {
                                    'left': 'currency_id',
                                    'operation': 'equal',
                                    'right': 'USD',
                                }
                            },
                        ],
                    }
                }
            ],
        },
        'sort': {'sortBy': 'dex_txs_count_24h', 'sortOrder': 'desc'},
        'range': DEFAULT_RANGE.copy(),
        'ignore_unknown_fields': False,
    }
    return q
```

--------------------------------

### Package Imports and Module Structure

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener.html

Shows the primary imports for the tradingview_screener package, including Column, col, Query, And, Or, and various screener modules (bond, cfd, coin, crypto, crypto_dex, forex, futures, options, stocks). This is the foundational import block for using the package.

```python
"""
.. include:: ../../README.md
"""

from __future__ import annotations

from tradingview_screener.column import Column, col
from tradingview_screener.query import Query, And, Or
from tradingview_screener.screeners import (
    bond,
    cfd,
    coin,
    crypto,
    crypto_dex,
    forex,
    futures,
    options,
    stocks,
)

```

--------------------------------

### crypto() -> Query

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/screeners.html

Creates a Query object for screening centralised-exchange (CEX) crypto pairs, sorted by 24-hour volume descending. The returned Query is pre-configured with the appropriate market, columns, filters, and sorting.

```APIDOC
## crypto() -> Query

### Description
Screener for centralised-exchange (CEX) crypto pairs, sorted by 24 h volume descending.

### Method
Function call

### Signature
crypto() -> Query

### Parameters
None

### Returns
- **Query** - A Query object configured for CEX crypto pair screening.

### Usage Example
```python
from tradingview_screener.screeners import crypto

# Create a CEX crypto pair screener
query = crypto()
```
```

--------------------------------

### Load Cookies with rookiepy

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener.html

Loads cookies from Chrome (or another browser) for the TradingView domain. Replace 'chrome()' with your browser function.

```python
import rookiepy
cookies = rookiepy.to_cookiejar(rookiepy.chrome(['.tradingview.com']))  # replace chrome() with your browser

```

--------------------------------

### futures() - Screener for futures contracts

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/screeners.html

Returns a Query for futures contracts sorted by traded value descending. Sets the market to 'futures' and includes columns for name, close, volume, and currency.

```python
def futures() -> Query:
    """
    Screener for futures contracts, sorted by traded value descending.
    """
    q = Query()
    q.url = URL.format(market='futures')
    q.query = {
        'markets': ['futures'],
        'symbols': {},
        'options': {'lang': 'en'},
        'columns': ['name', 'close', 'volume', 'currency'],
        'sort': {'sortBy': 'Value.Traded', 'sortOrder': 'desc'},
        'range': DEFAULT_RANGE.copy(),
        'ignore_unknown_fields': False,
    }
    return q
```

--------------------------------

### options(underlying) - Screener for options filtered by underlying

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/screeners.html

Returns a Query for options, filtered by the given underlying symbol (e.g., 'CME_MINI:ESM2026'). Uses a custom URL for the options scanner and includes option-specific columns like strike, expiration, delta, gamma, theta, vega, and IV.

```python
def options(underlying: str) -> Query:
    """
    :param underlying: The underlying symbol to filter by, e.g. ``'CME_MINI**: ESM2026'``.
    """
    q = Query()
    q.url = 'https://scanner.tradingview.com/options/scan2?label-product=options-builder'
    q.query = {
        'columns': [
            'ask',
            'bid',
            'currency',
            'delta',
            'expiration',
            'gamma',
            'iv',
            'option-type',
            'pricescale',
            'rho',
            'root',
            'strike',
            'theoPrice',
            'theta',
            'vega',
            'bid_iv',
            'ask_iv',
        ],
        'filter2': {
            'operator': 'and',
            'operands': [{'expression': {'left': 'type', 'operation': 'equal', 'right': 'option'}}],
        },
        'ignore_unknown_fields': False,
        'index_filters': [{'name': 'underlying_symbol', 'values': [underlying]}],
        'options': {'lang': 'en'},
        'range': DEFAULT_RANGE.copy(),
    }
    return q
```

--------------------------------

### Re-run Update Mode Check with Cookies

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener.html

Re-runs the update mode check with cookies, showing that most exchanges now return 'streaming' except OTC, which remains delayed due to subscription limitations.

```python
_, df = Query().select('exchange', 'update_mode').limit(1_000_000).get_scanner_data(cookies=cookies)
df = df.groupby('exchange')['update_mode'].value_counts()
print(df)

```

```text
exchange  update_mode          
AMEX      streaming                3256
NASDAQ    streaming                4286
NYSE      streaming                2860
OTC       delayed_streaming_900    7175

```

--------------------------------

### stocks(market: str = 'america') -> Query

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/screeners.html

Creates a Query object for screening stocks (common, preferred, DRs, and non-ETF funds), filtered to primary listings only and sorted by market cap descending. The market parameter specifies the country or region to scan, defaulting to 'america'.

```APIDOC
## stocks(market: str = 'america') -> Query

### Description
Screener for stocks (common, preferred, DRs, and non-ETF funds), filtered to primary listings only and sorted by market cap descending.

### Method
Function call

### Signature
stocks(market: str = 'america') -> Query

### Parameters
#### Path Parameters
- **market** (str) - Optional - Market/country to scan, e.g. 'america', 'italy', 'germany'. Defaults to 'america'.

### Returns
- **Query** - A Query object configured for stock screening.

### Usage Example
```python
from tradingview_screener.screeners import stocks

# Create a stock screener for the US market
query = stocks(market='america')
```
```

--------------------------------

### options(underlying) - Screener for options

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/screeners.html

Returns a Query for options filtered by the given underlying symbol (e.g., 'CME_MINI:ESM2026'). Uses a dedicated options scanner URL and includes option-specific columns like delta, gamma, theta, vega, and IV.

```python
def options(underlying: str) -> Query:
    """
    :param underlying: The underlying symbol to filter by, e.g. ``'CME_MINI:ESM2026'``.
    """
    q = Query()
    q.url = 'https://scanner.tradingview.com/options/scan2?label-product=options-builder'
    q.query = {
        'columns': [
            'ask',
            'bid',
            'currency',
            'delta',
            'expiration',
            'gamma',
            'iv',
            'option-type',
            'pricescale',
            'rho',
            'root',
            'strike',
            'theoPrice',
            'theta',
            'vega',
            'bid_iv',
            'ask_iv',
        ],
        'filter2': {
            'operator': 'and',
            'operands': [{'expression': {'left': 'type', 'operation': 'equal', 'right': 'option'}}],
        },
        'ignore_unknown_fields': False,
    }
    return q
```

--------------------------------

### stocks(market: str = 'america') -> Query

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/screeners.html

Creates a screener for stocks (common, preferred, DRs, and non-ETF funds), filtered to primary listings only and sorted by market cap descending.

```APIDOC
## stocks(market: str = 'america') -> Query

### Description
Creates a screener for stocks (common, preferred, DRs, and non-ETF funds), filtered to primary listings only and sorted by market cap descending.

### Parameters
- **market** (str) - Optional - Market/country to scan, e.g. 'america', 'italy', 'germany'. Defaults to 'america'.

### Returns
- **Query** - A Query object configured for stock screening.
```

--------------------------------

### options(underlying: str)

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/screeners.html

Screener for options, filtered by the underlying symbol. Returns a Query object configured for options screening.

```APIDOC
## options(underlying: str)

### Description
Screener for options, filtered by the underlying symbol.

### Method
Function call

### Endpoint
Not applicable (library function)

### Parameters
#### Path Parameters
- **underlying** (string) - Required - The underlying symbol to filter by, e.g. `'CME_MINI:ESM2026'`.

### Request Example
```python
from tradingview_screener import screener
q = screener.options('CME_MINI:ESM2026')
```

### Response
Returns a `tradingview_screener.query.Query` object configured for options screening.

```

--------------------------------

### Manually Extract Cookies

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener.html

Shows how to manually extract the sessionid cookie from TradingView and pass it to the query.

```python
cookies = {'sessionid': '<your-session-id>'}
Query().get_scanner_data(cookies=cookies)

```

--------------------------------

### cfd() - Screener for CFDs

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/screeners.html

Returns a Query for CFDs (contracts for difference) sorted by traded value descending. Sets the market to 'cfd' and includes columns for name, close, volume, and currency.

```python
def cfd() -> Query:
    """
    Screener for CFDs (contracts for difference), sorted by traded value descending.
    """
    q = Query()
    q.url = URL.format(market='cfd')
    q.query = {
        'markets': ['cfd'],
        'symbols': {},
        'options': {'lang': 'en'},
        'columns': ['name', 'close', 'volume', 'currency'],
        'sort': {'sortBy': 'Value.Traded', 'sortOrder': 'desc'},
        'range': DEFAULT_RANGE.copy(),
        'ignore_unknown_fields': False,
    }
    return q
```

--------------------------------

### crypto_dex() - DEX spot pairs screener

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/screeners.html

Screener for decentralised-exchange (DEX) spot pairs priced in USD, sorted by 24 h transaction count descending. Uses 'centralization' equal 'dex' and 'currency_id' equal 'USD' filters, with columns for blockchain, exchange, and DEX metrics.

```python
def crypto_dex() -> Query:
    """
    Screener for decentralised-exchange (DEX) spot pairs priced in USD, sorted by 24 h transaction
    count descending.
    """
    q = Query()
    q.url = URL.format(market='crypto')
    q.query = {
        'markets': ['crypto'],
        'symbols': {},
        'options': {'lang': 'en'},
        'columns': [
            'ticker-view',
            'blockchain-id.tr',
            'blockchain-id',
            'exchange.tr',
            'provider-id',
            'close',
            'type',
            'typespecs',
            'pricescale',
            'minmov',
            'fractional',
            'minmove2',
            'currency',
            '24h_close_change|5',
            'dex_txs_count_24h',
            'dex_trading_volume_24h',
            'dex_txs_count_uniq_24h',
            'dex_total_liquidity',
            'fully_diluted_value',
            'TechRating_1D',
            'TechRating_1D.tr',
        ],
        'filter2': {
            'operator': 'and',
            'operands': [
                {
                    'operation': {
                        'operator': 'and',
                        'operands': [
                            {
                                'expression': {
                                    'left': 'centralization',
                                    'operation': 'equal',
                                    'right': 'dex',
                                }
                            },
                            {
                                'expression': {
                                    'left': 'currency_id',
                                    'operation': 'equal',
                                    'right': 'USD',
                                }
                            },
                        ],
                    }
                },
                {
                    'operation': {
                        'operator': 'or',
                        'operands': [
                            {
                                'operation': {
                                    'operator': 'and',
                                    'operands': [
                                        {
                                            'expression': {
                                                'left': 'type',
                                                'operation': 'equal',
                                                'right': 'spot',
                                            }
                                        }
                                    ],
                                }
                            }
                        ],
                    }
                },
            ],
        },
        'sort': {'sortBy': 'dex_txs_count_24h', 'sortOrder': 'desc'},
        'range': DEFAULT_RANGE.copy(),
        'ignore_unknown_fields': False,
    }
    return q
```

--------------------------------

### bond() - Screener for bonds

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/screeners.html

Returns a Query for bonds sorted by S&P long-term rating descending. Sets the market to 'bond' and includes a wide set of bond-specific columns.

```python
def bond() -> Query:
    """
    Screener for bonds, sorted by S&P long-term rating descending.
    """
    q = Query()
    q.url = URL.format(market='bond')
    q.query = {
        'markets': ['bond'],
        'symbols': {},
        'options': {'lang': 'en'},
        'columns': [
            'ticker-view',
            'exchange.tr',
            'source-logoid',
            'isin-displayed',
            'yield_to_worst',
            'close_pct',
            'close_net',
            'type',
            'typespecs',
            'fundamental_currency_code',
            'current_coupon',
            'maturity_date',
            'redemption_type.tr',
            'bond_issuer_type.tr',
            'bond_snp_rating_lt.tr',
            'bond_fitch_rating_lt.tr',
        ],
        'sort': {'sortBy': 'bond_snp_rating_lt', 'sortOrder': 'desc'},
        'range': DEFAULT_RANGE.copy(),
        'ignore_unknown_fields': False,
    }
    return q
```

--------------------------------

### futures()

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/screeners.html

Screener for futures contracts, sorted by traded value descending. Returns a Query object configured for the futures market.

```APIDOC
## futures()

### Description
Screener for futures contracts, sorted by traded value descending.

### Method
Function call

### Endpoint
Not applicable (library function)

### Parameters
None

### Request Example
```python
from tradingview_screener import screener
q = screener.futures()
```

### Response
Returns a `tradingview_screener.query.Query` object configured for futures screening.

```

--------------------------------

### coin function

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/screeners.html

Defines a screener for crypto coins (CoinMarketCap universe) sorted by overall rank ascending. It sets the URL to the 'coin' market and configures the query with crypto-specific columns and sorting.

```python
def coin() -> Query:
    """
    Screener for crypto coins (CoinMarketCap universe), sorted by overall rank ascending.
    """
    q = Query()
    q.url = URL.format(market='coin')
    q.query = {
        'markets': ['coin'],
        'symbols': {},
        'options': {'lang': 'en'},
        'columns': [
            'ticker-view',
            'crypto_total_rank',
            'close',
            'type',
            'typespecs',
            'pricescale',
            'minmov',
            'fractional',
            'minmove2',
            'currency',
            '24h_close_change|5',
            'market_cap_calc',
            'fundamental_currency_code',
            '24h_vol_cmc',
            'circulating_supply',
            '24h_vol_to_market_cap',
            'socialdominance',
            'crypto_common_categories.tr',
            'TechRating_1D',
            'TechRating_1D.tr',
        ],
        'sort': {'sortBy': 'crypto_total_rank', 'sortOrder': 'asc'},
        'range': DEFAULT_RANGE.copy(),
        'ignore_unknown_fields': False,
    }
    return q
```

--------------------------------

### Pass Cookies to Query

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener.html

Passes the loaded cookies to the get_scanner_data method to access real-time data.

```python
Query().get_scanner_data(cookies=cookies)

```

--------------------------------

### cfd()

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/screeners.html

Screener for CFDs (contracts for difference), sorted by traded value descending. Returns a Query object configured for the CFD market.

```APIDOC
## cfd()

### Description
Screener for CFDs (contracts for difference), sorted by traded value descending.

### Method
Function call

### Endpoint
Not applicable (library function)

### Parameters
None

### Request Example
```python
from tradingview_screener import screener
q = screener.cfd()
```

### Response
Returns a `tradingview_screener.query.Query` object configured for CFD screening.

```

--------------------------------

### QueryDict TypedDict

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/models.html

Defines the fields that can be passed to the TradingView scan API. Includes markets, symbols, options, columns, filter, filter2, sort, range, ignore_unknown_fields, preset, and price_conversion.

```python
class QueryDict(TypedDict, total=False):
    """
    The fields that can be passed to the tradingview scan API
    """

    markets: list[str]
    symbols: SymbolsDict
    options: dict[str, Any]  # example: `{"options": {"lang": "en"}}`
    columns: list[str]
    filter: list[FilterOperationDict]
    filter2: OperationComparisonDict
    sort: SortByDict
    range: list[int]  # list with two integers, i.e. `[0, 100]`
    ignore_unknown_fields: bool  # default false
    preset: Literal['index_components_market_pages', 'pre-market-gainers']  # there are many
    # other presets (these are just some a examples)
    price_conversion: (
        dict[Literal['to_symbol'], bool]
        | dict[
            Literal['to_currency'], str  # this string should be the currency in lower-case
        ]
    )
```

--------------------------------

### bond()

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/screeners.html

Screener for bonds, sorted by S&P long-term rating descending. Returns a Query object configured for the bond market.

```APIDOC
## bond()

### Description
Screener for bonds, sorted by S&P long-term rating descending.

### Method
Function call

### Endpoint
Not applicable (library function)

### Parameters
None

### Request Example
```python
from tradingview_screener import screener
q = screener.bond()
```

### Response
Returns a `tradingview_screener.query.Query` object configured for bond screening.

```

--------------------------------

### stocks function

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/screeners.html

Defines a screener for stocks (common, preferred, DRs, non-ETF funds) filtered to primary listings and sorted by market cap descending. The market parameter defaults to 'america'.

```python
def stocks(market: str = 'america') -> Query:
    """
    Screener for stocks (common, preferred, DRs, and non-ETF funds), filtered to primary listings
    only and sorted by market cap descending.

    :param market: Market/country to scan, e.g. ``'america'``, ``'italy'``, ``'germany'``.
        Defaults to ``'america'``.
    """
    return Query(market)
```

--------------------------------

### Authenticate via API

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener.html

Authenticates directly via TradingView's API. Note that this method has restrictions on login frequency and may trigger CAPTCHA or account flagging.

```python
from http.cookiejar import CookieJar

import requests
from tradingview_screener import Query


def authenticate(username: str, password: str) -> CookieJar:
    session = requests.Session()
    r = session.post(
       'https://www.tradingview.com/accounts/signin/', 
       headers={'User-Agent': 'Mozilla/5.0', 'Referer': 'https://www.tradingview.com'}, 
       data={'username': username, 'password': password, 'remember': 'on'}, 
       timeout=60,
    )
    r.raise_for_status()
    if r.json().get('error'):
        raise Exception(f'Failed to authenticate: \n{r.json()}')
    return session.cookies


cookies = authenticate('<your-username-or-email>', '<your-password>')
Query().get_scanner_data(cookies=cookies)

```

--------------------------------

### crypto function

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/screeners.html

Defines a screener for centralised-exchange (CEX) crypto pairs, sorted by 24h volume descending. It sets the market to 'crypto' and configures the query with crypto-specific columns and filters.

```python
def crypto() -> Query:
    """
    Screener for centralised-exchange (CEX) crypto pairs, sorted by 24 h volume descending.
    """
    q = Query()
    q.url = URL.format(market='crypto')
    q.query = {
        'markets': ['crypto'],
        'symbols': {},
        'options': {'lang': 'en'},
        'columns': [
            'ticker-view',
            'exchange.tr',
            'provider-id',
            'close',
            'type',
            'typespecs',
            'pricescale',
            'minmov',
            'fractional',
            'minmove2',
            'currency',
            '24h_close_change|5',
            '24h_vol|5',
            '24h_vol_change|5',
            'TechRating_1D',
            'TechRating_1D.tr',
        ],
        'filter2': {
            'operator': 'and',
            'operands': [
                {'expression': {'left': 'centralization', 'operation': 'equal', 'right': 'cex'}}
            ],
        },
        'sort': {'sortBy': '24h_vol|5', 'sortOrder': 'desc'},
        'range': DEFAULT_RANGE.copy(),
        'ignore_unknown_fields': False,
    }
    return q
```

--------------------------------

### format_technical_rating: Convert rating float to string

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/util.html

Converts a technical rating float to a human-readable string. The first block includes the module import and a comment referencing a GitHub issue; the second block is the function definition alone. Ratings are mapped to 'Strong Buy', 'Buy', 'Neutral', 'Sell', or 'Strong Sell' based on thresholds of 0.5, 0.1, -0.1, and -0.5.

```python
from __future__ import annotations


# see issue: https://github.com/shner-elmo/TradingView-Screener/issues/12
def format_technical_rating(rating: float) -> str:
    if rating >= 0.5:
        return 'Strong Buy'
    elif rating >= 0.1:
        return 'Buy'
    elif rating >= -0.1:
        return 'Neutral'
    elif rating >= -0.5:
        return 'Sell'
    # elif x >= -0.1:
    else:
        return 'Strong Sell'
```

```python
def format_technical_rating(rating: float) -> str:
    if rating >= 0.5:
        return 'Strong Buy'
    elif rating >= 0.1:
        return 'Buy'
    elif rating >= -0.1:
        return 'Neutral'
    elif rating >= -0.5:
        return 'Sell'
    # elif x >= -0.1:
    else:
        return 'Strong Sell'
```

--------------------------------

### ScreenerRowDictV2 TypedDict

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/models.html

Defines a row in the V2 screener response. 's' is the symbol (for options, e.g., 'OPRA:AAPL260821C200.0') and 'f' is a list of data values.

```python
class ScreenerRowDictV2(TypedDict):
    s: str  # for options: 'OPRA:AAPL260821C200.0'
    f: list  # data, list of values
```

--------------------------------

### OperationComparisonDict TypedDict

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/models.html

Defines a comparison operation with an 'operator' (either 'and' or 'or') and a list of operands, each being either an OperationDict or ExpressionDict.

```python
class OperationComparisonDict(TypedDict):
    operator: Literal['and', 'or']
    operands: list[OperationDict | ExpressionDict]
```

--------------------------------

### ScreenerDictV2 TypedDict

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/models.html

Defines the top-level structure of a V2 screener response, containing totalCount, fields, symbols (list of ScreenerRowDictV2), and a time string.

```python
class ScreenerDictV2(TypedDict):
    totalCount: int
    fields: list[str]
    symbols: list[ScreenerRowDictV2]
    time: str  # '2026-04-24T13:45:37Z'
```

--------------------------------

### SortByDict TypedDict

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/models.html

Defines the structure for sorting results in a screener query. The 'sortBy' field is the column name, 'sortOrder' is either 'asc' or 'desc', and 'nullsFirst' is an optional boolean.

```python
class SortByDict(TypedDict):
    sortBy: str
    sortOrder: Literal['asc', 'desc']
    nullsFirst: NotRequired[bool]
```

--------------------------------

### SymbolsDict TypedDict

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/models.html

Defines the structure for the 'symbols' field in a query. It includes 'query' for types, 'tickers' for a list of tickers, 'symbolset' for a list of symbol sets, 'watchlist' for a watchlist ID, and 'groups' for a list of group dictionaries.

```python
class SymbolsDict(TypedDict, total=False):
    query: dict[Literal['types'], list[str]]
    tickers: list[str]
    symbolset: list[str]
    watchlist: dict[Literal['id'], int]
    groups: list[dict[Literal['type', 'values'], str]]
    # for example [{'type': 'index', 'values': ['DJ:DJU']}]
```

--------------------------------

### ScreenerRowDict TypedDict

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/models.html

Defines a single row in a screener response. 's' is the symbol (e.g., 'NASDAQ:AAPL') and 'd' is a list of data values.

```python
class ScreenerRowDict(TypedDict):
    s: str  # symbol (NASDAQ:AAPL)
    d: list  # data, list of values
```

--------------------------------

### ScreenerDict TypedDict

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/models.html

Defines the top-level structure of a screener response, containing a totalCount and a list of ScreenerRowDict.

```python
class ScreenerDict(TypedDict):
    totalCount: int
    data: list[ScreenerRowDict]
```

--------------------------------

### OperationDict TypedDict

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/models.html

Defines a single operation that contains an OperationComparisonDict under the key 'operation'.

```python
class OperationDict(TypedDict):
    operation: OperationComparisonDict
```

--------------------------------

### FilterOperationDict TypedDict

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/models.html

Defines the structure for a filter operation in a TradingView screener query. The 'left' field is the column name, 'operation' is a literal union of supported operations (e.g., 'greater', 'equal', 'in_range'), and 'right' is optional for operations like 'empty' or 'nempty'.

```python
class FilterOperationDict(TypedDict):
    left: str
    operation: Literal[
        'greater',
        'egreater',
        'less',
        'eless',
        'equal',
        'nequal',
        'in_range',  # equivalent to SQL `BETWEEN` or `IN (...)`
        'not_in_range',
        'empty',
        'nempty',
        'crosses',
        'crosses_above',
        'crosses_below',
        'match',  # the same as: `LOWER(col) LIKE '%pattern%'`
        'nmatch',  # not match
        # simple match, there is no method for this operation as of right now, because it does
        # the same thing as `match`
        'smatch',
        'has',  # set must contain one of the values
        'has_none_of',  # set must NOT contain ANY of the values
        'above%',
        'below%',
        'in_range%',
        'not_in_range%',
        'in_day_range',
        'in_week_range',
        'in_month_range',
    ]
    right: Any  # its optional when the operation is `empty` or `nempty`
```

--------------------------------

### ExpressionDict TypedDict

Source: https://shner-elmo.github.io/TradingView-Screener/3.2.0/tradingview_screener/models.html

Defines a single expression that wraps a FilterOperationDict under the key 'expression'.

```python
class ExpressionDict(TypedDict):
    expression: FilterOperationDict
```
Tokens:
Raw