Metadata-Version: 2.4
Name: etffin
Version: 0.1.0
Summary: Python SDK for the hosted etffin ETF issuer data API.
Project-URL: Homepage, https://api.etffin.bluedoor.sh/v1/health
Project-URL: API, https://api.etffin.bluedoor.sh/v1/openapi.json
Project-URL: Documentation, https://github.com/bluedoor-ai/etffin#readme
Project-URL: Source, https://github.com/bluedoor-ai/etffin
Project-URL: Endpoint Catalog, https://api.etffin.bluedoor.sh/v1/endpoints
Author-email: BlueDoor <sam@bluedoor.sh>
License: MIT
Keywords: etf,etffin,finance,holdings,invesco,ishares,market-data,vanguard
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

# etffin

Python SDK for the hosted etffin ETF issuer data API.

The hosted API wraps CP-confirmed public ETF issuer contracts from iShares,
Vanguard, and Invesco behind a cached, rate-limited REST surface. It is not
affiliated with, endorsed by, or sponsored by BlackRock/iShares, Vanguard, or
Invesco.

## Install

```bash
pip install etffin
```

## Quick Start

```python
from etffin import Client

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

funds = client.funds()
providers = client.providers()

ivv = client.holdings("IVV")
voo = client.profile("VOO")
qqq = client.holdings("QQQ", refresh=True)

performance = client.performance("VOO")
exposures = client.exposures("VOO", kind="classification")
```

Convenience wrappers are also available:

```python
import etffin

data = etffin.holdings("IVV")
```

The legacy-style `etffin_client` import path is also included.

## Common Methods

- `Client.health()`, `Client.endpoints()`, and `Client.openapi()` expose API
  discovery and status metadata.
- `Client.providers()`, `Client.funds()`, `Client.provider_funds(provider)`,
  and `Client.fund(ticker)` expose the seed issuer/fund catalog.
- `Client.holdings(ticker)` returns normalized holdings when the hosted API can
  normalize the issuer payload.
- `Client.profile(ticker)`, `Client.distributions(ticker)`,
  `Client.performance(ticker)`, `Client.price(ticker)`,
  `Client.price_history(ticker)`, `Client.exposures(ticker)`, and
  `Client.premium_discount(ticker)` wrap fund-level routes.

Set `ETFFIN_BASE_URL`, `ETFFIN_CONTACT`, or `ETFFIN_API_KEY` in the environment
to configure the default client.

The hosted API and SDK expose friendly public routes only. Source endpoint URLs,
raw upstream templates, and internal validation routes are not part of the SDK
surface.
