tvfin 0.2.1

Lightweight Python SDK for tvfin: hosted TradingView symbols, screeners, news, calendars, options, ideas, and scripts.

tvfin

Lightweight Python SDK for tvfin, a hosted TradingView data API for builders.

tvfin gives you access to TradingView market data without running your own browser or scraper stack: symbol search, news, economic calendars, earnings and dividend events, screeners, options data, public ideas, and public scripts through product-native namespaces. Use it for dashboards, agents, notebooks, research tools, watchlists, prototyping, and app backends.

This SDK is intentionally straightforward: plain dict responses, typed errors, automatic transient retries, and a public surface that follows tvfin routes rather than upstream provider endpoint names.

Docs: https://docs.tvfin.bluedoor.sh

pip install tvfin

Quick Use

from tvfin import Client

client = Client()

symbols = client.symbols.search("apple", exchange="NASDAQ")
news = client.news.for_symbol("NASDAQ:AAPL")
screen = client.screeners.search("america", columns="name,close", limit=5)
chain = client.options.chain("AAPL", limit=10)

print(symbols["data"], news["data"], screen["data"], chain["data"])

Common Calls

client.symbols.search("tesla", type="stock")
client.news.headlines(lang="en")
client.news.flow(market="stocks")
client.calendar.economic(country="US")
client.events.earnings(limit=25, columns="name,earnings_release_date")
client.screeners.metadata("america")
client.screeners.search("america", limit=25, columns="name,close,volume")
client.screeners.global_search(markets="america,crypto", limit=25)
client.options.implied_volatility("AAPL")
client.options.underlying_aggregates("AAPL")
client.ideas.list(symbol="AAPL")
client.scripts.list(symbol="AAPL")

The client is organized around tvfin product areas: symbols, news, calendar, events, screeners, options, ideas, scripts, and management.

Runtime Support

Configuration can come from constructor options or environment variables:

Option	Environment	Purpose
base_url	TVFIN_BASE_URL	Override https://api.tvfin.bluedoor.sh; must be http or https
contact	TVFIN_CONTACT	Send optional support metadata
api_key	TVFIN_API_KEY	Send email-verified API credentials
management_token	TVFIN_MANAGEMENT_TOKEN	Manage API keys after email verification

api_key is sent as Authorization: Bearer <key> by default. Pass api_key_header="x-tvfin-key" to use X-Tvfin-Key instead.

The SDK retries transient 429, 502, 503, and 504 responses by default. Use max_retries, retry_statuses, backoff_factor, max_backoff, and backoff_jitter when you need tighter control, or set max_retries=0.

Keep API keys on a server when you do not control the runtime.

Auth Helpers

client = Client()
client.management.request_auth_otp("[e-mail]")
verified = client.management.verify_auth_otp("[e-mail]", "123456", label="agent")

api_key = verified["data"]["api_key"]
management_token = verified["data"]["management_token"]

authed = Client(api_key=api_key)
authed.management.request_limit_increase(
    requested_rps=25,
    use_case="production agent workload",
    message="Short traffic description.",
)

managed = Client(management_token=management_token)
keys = managed.management.keys.list()
created = managed.management.keys.create(label="batch job")
managed.management.keys.rotate(created["data"]["key"]["id"])

All successful calls return the hosted tvfin envelope:

{
    "data": {},
    "meta": {
        "provider": "tradingview",
        "generated_at": "2026-01-01T00:00:00Z",
        "route": "symbols_search",
    },
}

Errors

HTTP errors raise TvfinError. HTTP 429 raises TvfinRateLimitError; HTTP 503 raises TvfinServiceBusyError after retry exhaustion. Error objects include retry_after, status, request_id, and the response message.