Metadata-Version: 2.4
Name: nfin-sdk
Version: 0.1.1
Summary: Lightweight Python SDK for nfin: hosted Nasdaq quotes, prices, options, IPOs, calendars, market movers, news, and Nordic data.
Project-URL: Homepage, https://nfin.dev
Project-URL: API, https://api.nfin.dev/v1/openapi.json
Project-URL: Documentation, https://docs.nfin.dev
Project-URL: Source, https://github.com/bluefin-ai/fin-services/tree/main/nfin
Project-URL: PyPI, https://pypi.org/project/nfin-sdk/
Project-URL: Rate Limits, https://docs.nfin.dev/rate-limits
Project-URL: API Reference, https://docs.nfin.dev/api-reference
Project-URL: LLM Summary, https://docs.nfin.dev/llms.txt
Author-email: nfin <sam@bluedoor.sh>
License: MIT
Keywords: finance,market-data,nasdaq,stocks
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
Description-Content-Type: text/markdown

# nfin

Lightweight Python SDK for nfin, a hosted Nasdaq data API for builders.

nfin gives you access to Nasdaq market data without maintaining your own
exchange-site integration: symbol search, quotes, historical prices, options,
IPO calendars, market movers, event calendars, ownership, funds, news,
screeners, sentiment, and Nasdaq Nordic data 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, and a symbol-scoped ticker workbench.

Docs: https://docs.nfin.dev/python-sdk

```bash
pip install nfin-sdk
```

## Quick Use

```python
import nfin

client = nfin.Client()
apple = client.ticker("AAPL")

quote = apple.quote(asset_class="stocks")
history = apple.history(from_date="2026-01-01", to_date="2026-05-01")
ipos = client.ipos.calendar()

print(quote["data"], history["data"], ipos["data"])
```

## Common Calls

```python
client.symbols.search("apple")
client.quotes.get("AAPL", asset_class="stocks")
client.quotes.batch(["AAPL", "MSFT"])
client.prices.history("AAPL", from_date="2026-01-01", to_date="2026-05-01")
client.options.chain("AAPL")
client.events.earnings()
client.ipos.calendar()
client.market.movers()
client.news.press_center()
client.screeners.run("stocks")
client.nordic.search("ericsson")
```

The client is organized around nfin product areas: `symbols`, `quotes`,
`prices`, `options`, `events`, `ipos`, `market`, `ownership`, `funds`, `news`,
`screeners`, `sentiment`, `nordic`, and `management`. Use
`client.ticker("AAPL")` for symbol-scoped quote, history, chart, options,
dividend, EPS, extended-trading, realtime-trade, and short-interest calls.

## Runtime Support

Configuration can come from constructor options or environment variables:

| Option | Environment | Purpose |
| --- | --- | --- |
| `base_url` | `NFIN_BASE_URL` | Override `https://api.nfin.dev`; must be `http` or `https` |
| `contact` | `NFIN_CONTACT` | Send optional support metadata |
| `api_key` | `NFIN_API_KEY` | Send email-verified API credentials |
| `management_token` | `NFIN_MANAGEMENT_TOKEN` | Manage API keys after email verification |

`api_key` is sent as `Authorization: Bearer <key>` by default. Pass
`api_key_header="x-nfin-key"` to use `X-Nfin-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.

## Errors

HTTP errors raise `NfinError`. HTTP 429 raises `NfinRateLimitError`; HTTP 503
raises `NfinServiceBusyError` after retry exhaustion. Error objects include
`retry_after`, `status`, and request IDs when provided.
