yfin 0.2.0

Lightweight Python SDK for yfin: hosted Yahoo Finance quotes, history, options, fundamentals, screeners, and search.

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

pip install yfin

Quick Use

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

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

client = yfin.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 = 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 [e-mail].

All successful calls return the hosted yfin envelope:

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

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)