Metadata-Version: 2.4
Name: yfin
Version: 0.2.0
Summary: Lightweight Python SDK for yfin: hosted Yahoo Finance quotes, history, options, fundamentals, screeners, and search.
Project-URL: Homepage, https://yfin.dev
Project-URL: API, https://api.yfin.dev/v1/openapi.json
Project-URL: Documentation, https://docs.yfin.dev
Project-URL: Source, https://github.com/bluefin-ai/fin-services/tree/main/yfin
Project-URL: Changelog, https://github.com/bluefin-ai/fin-services/blob/main/yfin/CHANGELOG.md
Project-URL: Rate Limits, https://docs.yfin.dev/rate-limits
Project-URL: API Reference, https://docs.yfin.dev/api-reference
Project-URL: LLM Summary, https://docs.yfin.dev/llms.txt
Author-email: yfin <sam@bluedoor.sh>
License: MIT
Keywords: finance,market-data,stocks,yahoo-finance
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: certifi>=2024.2.2
Requires-Dist: curl-cffi>=0.15
Requires-Dist: websockets>=13.0
Description-Content-Type: text/markdown

# yfin

Lightweight Python SDK for yfin, a hosted Yahoo Finance data API for builders.

yfin gives you access to Yahoo Finance market data without running your own
scraper stack: quotes, historical prices, options chains, fundamentals,
screeners, symbol search, and market context 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 retries, a symbol-scoped ticker workbench, and sync/async
streaming clients.

Docs: https://docs.yfin.dev/python-sdk

```bash
pip install yfin
```

## Quick Use

```python
import yfin

client = yfin.Client()
apple = client.ticker("AAPL")

# Current quote snapshots
quotes = client.quotes.batch(["AAPL", "MSFT"])

# Historical chart data
history = apple.history(range="5d", interval="1h")

# Options chain data
chain = apple.option_chain()

print(quotes["data"], history["data"], chain["data"])
```

## Common Calls

```python
client.quotes.batch(["AAPL", "MSFT"])
client.prices.history("AAPL", range="1mo", interval="1d", events="div,splits,capitalGains")
client.options.chain("AAPL", date="2026-01-16")
client.fundamentals.get("AAPL", modules=["price", "summaryDetail"])
client.symbols.search("apple")
client.screeners.default(count=25)
client.screeners.run({
    "size": 10,
    "query": {"operator": "EQ", "operands": ["sector", "Technology"]},
})
```

The client is organized around yfin product areas: `quotes`, `prices`,
`options`, `fundamentals`, `financials`, `symbols`, `screeners`, `market`,
`calendar`, `events`, `research`, and `reference`. Use `client.ticker("AAPL")`
for symbol-scoped quote, history, options, fundamentals, financials, metadata,
and research calls.

## Runtime Support

Configuration can come from constructor options or environment variables:

| Option | Environment | Purpose |
| --- | --- | --- |
| `base_url` | `YFIN_BASE_URL` | Override `https://api.yfin.dev`; must be `http` or `https` |
| `contact` | `YFIN_CONTACT` | Send optional support metadata |
| `api_key` | `YFIN_API_KEY` | Send email-verified API credentials |
| `management_token` | `YFIN_MANAGEMENT_TOKEN` | Manage API keys after email verification |

`api_key` is sent as `Authorization: Bearer <key>` by default. Pass
`api_key_header="x-yfin-key"` to use `X-Yfin-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 = yfin.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 = yfin.Client(api_key=api_key)
authed.management.request_limit_increase(
    requested_rps=25,
    use_case="production agent workload",
    message="Short traffic description.",
)

managed = yfin.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"])
```

Custom-limit requests are limited to 1 per minute per API key. You can also
email `sam@yfin.dev`.

All successful calls return the hosted yfin envelope:

```python
{
    "data": {},
    "meta": {
        "provider": "yahoo_finance",
        "generated_at": "2026-01-01T00:00:00Z",
        "route": "/v1/quote",
    },
}
```

## Errors

HTTP errors raise `YfinError`. HTTP 429 raises `YfinRateLimitError`; HTTP 503
raises `YfinServiceBusyError` after retry exhaustion. Error objects include
`retry_after`, `status`, `code`, `response`, and response headers.

```python
try:
    yfin.Client().quotes.get("AAPL")
except yfin.YfinRateLimitError as error:
    print(error.retry_after)
except yfin.YfinServiceBusyError as error:
    print("service busy", error.retry_after)
```
