Metadata-Version: 2.4
Name: tvfin
Version: 0.2.1
Summary: Lightweight Python SDK for tvfin: hosted TradingView symbols, screeners, news, calendars, options, ideas, and scripts.
Project-URL: Homepage, https://tvfin.bluedoor.sh
Project-URL: Documentation, https://docs.tvfin.bluedoor.sh
Project-URL: API, https://api.tvfin.bluedoor.sh/v1/openapi.json
Project-URL: Repository, https://github.com/bluefin-ai/fin-services
Project-URL: Issues, https://github.com/bluefin-ai/fin-services/issues
Author: Bluefin
License-Expression: MIT
Keywords: finance,market-data,sdk,tradingview
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.9
Requires-Dist: certifi>=2024.2.2
Description-Content-Type: text/markdown

# 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

```bash
pip install tvfin
```

## Quick Use

```python
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

```python
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

```python
client = Client()
client.management.request_auth_otp("you@example.com")
verified = client.management.verify_auth_otp("you@example.com", "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:

```python
{
    "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.
