Metadata-Version: 2.4
Name: yfin
Version: 0.1.4
Summary: Python SDK for the hosted yfin Yahoo Finance API, with yfinance-compatible data access.
Project-URL: Homepage, https://yfin.dev
Project-URL: API, https://api.yfin.dev/v1/openapi.json
Project-URL: Documentation, https://github.com/bluedoor-ai/yfin#readme
Project-URL: Source, https://github.com/bluedoor-ai/yfin
Project-URL: Changelog, https://github.com/bluedoor-ai/yfin/blob/main/CHANGELOG.md
Project-URL: Comparison, https://github.com/bluedoor-ai/yfin/blob/main/yfin/COMPARISON.md
Project-URL: Compatibility, https://github.com/bluedoor-ai/yfin/blob/main/yfin/COMPATIBILITY.md
Project-URL: Benchmarks, https://github.com/bluedoor-ai/yfin/blob/main/yfin/BENCHMARKS.md
Project-URL: Rate Limits, https://github.com/bluedoor-ai/yfin/blob/main/yfin/RATE_LIMITS.md
Project-URL: Privacy, https://github.com/bluedoor-ai/yfin/blob/main/yfin/PRIVACY.md
Project-URL: LLM Summary, https://github.com/bluedoor-ai/yfin/blob/main/llms.txt
Author-email: yfin <sam@bluedoor.sh>
License: MIT
Keywords: finance,market-data,stocks,yahoo-finance,yfinance
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: beautifulsoup4>=4.11.1
Requires-Dist: certifi>=2024.2.2
Requires-Dist: curl-cffi>=0.15
Requires-Dist: pandas>=2.0
Requires-Dist: websockets>=13.0
Description-Content-Type: text/markdown

# yfin Python SDK

[![PyPI](https://img.shields.io/pypi/v/yfin.svg)](https://pypi.org/project/yfin/)
[![Python](https://img.shields.io/pypi/pyversions/yfin.svg)](https://pypi.org/project/yfin/)
[![CI](https://github.com/bluedoor-ai/yfin/actions/workflows/publish-yfin-python.yml/badge.svg)](https://github.com/bluedoor-ai/yfin/actions/workflows/publish-yfin-python.yml)
[![OpenAPI](https://img.shields.io/badge/OpenAPI-live-blue)](https://api.yfin.dev/v1/openapi.json)
[![Warm benchmark](https://img.shields.io/badge/warm%20parity-637ms%20%2F%2017%20calls-brightgreen)](https://github.com/bluedoor-ai/yfin/blob/main/yfin/BENCHMARKS.md)

yfin is a yfinance-compatible Python SDK backed by the hosted
`api.yfin.dev` Yahoo Finance API. The hosted API handles Yahoo Finance
contracts, crumb bootstrap, caching, request coalescing, and origin budgets.
The SDK adds pandas/yfinance-shaped access on top.

Use yfinance for a mature local-only notebook dependency. Use yfin when you
want the same Python shape plus a hosted REST API, shared caching, OpenAPI,
explicit rate limits, and infrastructure that absorbs Yahoo cookie/crumb/TLS
and rate-limit churn.

```bash
pip install yfin
```

## Quickstart

```python
import yfin as yf

aapl = yf.Ticker("AAPL")

print(aapl.history(period="5d", interval="1d"))
print(aapl.fast_info)
print(aapl.info)
print(aapl.option_chain())
print(aapl.funds_data.top_holdings)
print(aapl.valuation)
print(yf.download(["AAPL", "MSFT"], period="5d"))

ws = yf.WebSocket(verbose=False)
ws.subscribe("BTC-USD")
```

## Low-Level Hosted API Client

```python
import yfin

client = yfin.Client(contact="you@example.com")
print(client.quote(["AAPL", "MSFT"]))
print(client.history("NVDA", range="5d", interval="1h"))
```

Set `YFIN_BASE_URL` to override the hosted API URL.

## What yfin Ships

- yfinance-compatible `Ticker`, `Tickers`, `download`, `WebSocket`, and
  `AsyncWebSocket` APIs.
- 45 CP2-confirmed Yahoo REST contracts behind `https://api.yfin.dev`.
- OpenAPI schema at `https://api.yfin.dev/v1/openapi.json`.
- Machine-readable endpoint manifest at `https://api.yfin.dev/v1/endpoints`.
- Cache metadata and explicit typed rate-limit errors.

## Honest Performance Position

yfin is not guaranteed to beat yfinance on cold one-off notebook calls. A cold
miss goes through yfin and then Yahoo. The hosted path is designed to win when
requests are repeated, concurrent, cacheable, or run from services/agents that
benefit from managed Yahoo access.

Recent live checks:

| Probe | Result |
|---|---:|
| Anonymous forced history misses | 25/25 HTTP 200, no 429 |
| 17 forced history misses | 1.4s wall time |
| Same 17 warm hosted reads | 117ms wall time, 76ms median |
| Python SDK 17-accessor warm pass | 637ms wall time |
| Local yfinance matching 16-accessor pass | 1330ms wall time |

See the [benchmark notes](https://github.com/bluedoor-ai/yfin/blob/main/yfin/BENCHMARKS.md).

## Trust And Docs

- [Source](https://github.com/bluedoor-ai/yfin)
- [Changelog](https://github.com/bluedoor-ai/yfin/blob/main/CHANGELOG.md)
- [yfin vs yfinance](https://github.com/bluedoor-ai/yfin/blob/main/yfin/COMPARISON.md)
- [Compatibility matrix](https://github.com/bluedoor-ai/yfin/blob/main/yfin/COMPATIBILITY.md)
- [Rate limits](https://github.com/bluedoor-ai/yfin/blob/main/yfin/RATE_LIMITS.md)
- [Privacy policy](https://github.com/bluedoor-ai/yfin/blob/main/yfin/PRIVACY.md)
- [LLM/crawler summary](https://github.com/bluedoor-ai/yfin/blob/main/llms.txt)

## Rate Limits

| Identity | Total requests/minute | Yahoo-origin misses/minute |
|---|---:|---:|
| Anonymous IP | 1200 | 120 |
| `X-Yfin-Contact` / SDK `contact=` | 6000 | 600 |
| Manual API key | 30000 | 3000 |

High-volume users can email `sam@yfin.dev` for an API key.
