Metadata-Version: 2.4
Name: safin
Version: 0.1.0
Summary: Python SDK for the hosted safin Seeking Alpha market-data API.
Project-URL: Homepage, https://safin-api.crombiesamuel.workers.dev/v1/health
Project-URL: API, https://safin-api.crombiesamuel.workers.dev/v1/openapi.json
Project-URL: Documentation, https://github.com/bluedoor-ai/safin#readme
Project-URL: Source, https://github.com/bluedoor-ai/safin
Project-URL: Endpoint Catalog, https://safin-api.crombiesamuel.workers.dev/v1/endpoints
Author-email: BlueDoor <sam@bluedoor.sh>
License: MIT
Keywords: finance,market-data,safin,seeking-alpha,stocks
Classifier: Development Status :: 3 - Alpha
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
Description-Content-Type: text/markdown

# safin Python SDK

Python SDK for `safin`, the hosted Seeking Alpha market-data API.

```bash
pip install safin
```

```python
from safin import Client

sa = Client(contact="you@example.com")

quote = sa.quote("GRAB")
ratios = sa.metrics_ratios("GRAB", fields=["pe_ratio", "ps_ratio"])
valuation = sa.valuation("GRAB")
history = sa.historical_prices("GRAB", start="2026-04-01", end="2026-05-05")
chain = sa.options_chain(ticker_id=605799, expiration_date="2026-05-15")
```

The default base URL is the verified Worker deployment:

```text
https://safin-api.crombiesamuel.workers.dev
```

Override it with `SAFIN_BASE_URL` or `Client(base_url=...)`. The configured
custom domain target is `https://api.safin.bluedoor.sh` once DNS is live.

## Public Methods

- Discovery: `health()`, `endpoints()`, `openapi()`
- Quotes: `quote(symbol)`, `quotes(symbols)`, `quotes_by_id(sa_ids)`
- Options: `options_by_symbols(symbols)`, `options_chain(ticker_id, expiration_date)`, `options_expirations(symbol)`
- Metrics and fundamentals: `metrics_ratios(symbol)`, `metrics_market(symbol)`, `symbol_data(symbol)`, `valuation(symbol)`, `estimates(ticker_id)`, `fundamentals(symbol)`, `fundamentals_metrics(symbol)`
- History and ownership: `historical_prices(symbol)`, `shares(symbol)`
- News: `news(symbol)`

All methods return the hosted API's JSON envelope as a `dict`.

## Identity

- Anonymous: works without configuration.
- Contact tier: `Client(contact="you@example.com")` sends `X-Safin-Contact`.
- Manual API key tier: `Client(api_key="...")` sends `Authorization: Bearer ...`.

Environment variables: `SAFIN_BASE_URL`, `SAFIN_CONTACT`, `SAFIN_API_KEY`.
