Metadata-Version: 2.4
Name: bfin
Version: 0.1.0
Summary: Unofficial Python client for the hosted bfin Barchart data API.
Project-URL: Homepage, https://github.com/bluedoor-ai/bfin
Project-URL: Documentation, https://api.bfin.bluedoor.sh
Project-URL: Source, https://github.com/bluedoor-ai/bfin
Author-email: BlueDoor <sam@bluedoor.sh>
License: MIT
Keywords: barchart,bfin,commodities,finance,futures,options
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
Provides-Extra: fast
Requires-Dist: curl-cffi>=0.7; extra == 'fast'
Description-Content-Type: text/markdown

# bfin — Python client for the hosted Barchart wrapper

Unofficial Python client for [bfin](https://api.bfin.bluedoor.sh), an
AI-friendly hosted wrapper over Barchart.com public data. Focus surface:
**futures, options, commodities, COT (Commitment of Traders)**.

## Install

```bash
pip install bfin
# optional, for TLS-impersonating transport
pip install bfin[fast]
```

## Quickstart

```python
from bfin import Client

bf = Client()  # or Client(contact="you@example.com") for higher limits

# Quotes
print(bf.quotes("AAPL,MSFT,SPY"))
print(bf.quotes(["GCM26", "CLM26"]))  # gold + WTI futures

# Futures lifetime hi/lo
print(bf.futures_hilo("GCM26"))

# COT (CFTC Commitment of Traders, packaged per futures category)
print(bf.cot())

# Option chain
print(bf.options_chain("AAPL", expiration="2026-06-19"))
print(bf.options_flow())                       # unusual options activity
print(bf.options_strategy("covered-calls"))    # strategy screen

# Intraday minute bars
print(bf.intraday("AAPL", interval=1, max_records=60))

# Historical daily bars
print(bf.historical("AAPL", type="daily", limit=30))

# Calendars
print(bf.calendar_earnings_dividends(country="us", limit=50))

# Discovery
print(bf.endpoints())   # full manifest
print(bf.openapi())     # OpenAPI document
```

## Response envelope

Every method returns a stable envelope:

```python
{
  "meta": {
    "provider": "barchart",
    "endpoint": "www.proxies.core-api.v1.options.chain",
    "route": "options_chain",
    "method": "GET",
    "bucket": "core-api",
    "cache": "edge",          # "miss" | "kv" | "edge" | "stale-*"
    "status": "ok",
    "identity_tier": "anonymous",
    "generated_at": "2026-05-04T...",
    "freshness": {"max_age_seconds": 60, "stale": False}
  },
  "data": { ... }              # passthrough Barchart JSON
}
```

## Rate limits

- **Anonymous** (no header): 1200 req/min, capped by 60 origin cache-misses/min.
- **Contact**: set `Client(contact="you@example.com")` → 6000 / 600.
- **API key**: `Client(api_key="...")` → 30000 / 3000 (contact `sam@bluedoor.sh`).

The hosted wrapper aggressively caches (KV + Cloudflare edge) so most repeat
reads are free. See <https://api.bfin.bluedoor.sh/v1/endpoints> for per-endpoint
TTLs.

## Escape hatch

Need an endpoint that's not yet in the typed methods? Use `raw()`:

```python
bf.raw("www.proxies.core-api.v1.options.flow", params={"limit": 50})
```

## License

MIT.
