vantafin 0.1.0__tar.gz

vantafin-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+node_modules/
+target/
+*.class
+.idea/
+.vscode/
+.DS_Store

vantafin-0.1.0/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Vantafin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vantafin-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.5
+Name: vantafin
+Version: 0.1.0
+Summary: Official Python client for the Vantafin REST API (market data, fundamentals, SEC filings, news and more).
+Project-URL: Homepage, https://vantafin.com
+Project-URL: Documentation, https://vantafin.com/docs
+Project-URL: Repository, https://github.com/vantafin/vantafin
+Project-URL: Issues, https://github.com/vantafin/vantafin/issues
+Author: Vantafin
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,finance,market-data,sec,stocks,vantafin
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.25
+Provides-Extra: websocket
+Requires-Dist: websocket-client>=1.6; extra == 'websocket'
+Description-Content-Type: text/markdown
+
+# vantafin
+
+Official Python client for the [Vantafin](https://vantafin.com) REST API - quotes,
+corporate actions, fundamentals, SEC filings, news, earnings transcripts, and
+earnings materials (IR decks, press releases, supplements).
+
+**Source:** [github.com/vantafin/vantafin](https://github.com/vantafin/vantafin)
+
+## Installation
+
+```bash
+pip install vantafin
+```
+
+Or install from source:
+
+```bash
+pip install git+https://github.com/vantafin/vantafin.git
+```
+
+## Authentication
+
+Grab your API key from **Settings → API Usage** at
+[vantafin.com/app/settings](https://vantafin.com/app/settings). Keys look like
+`vf-live-...`. You can reset a key at any time from the same page.
+
+## Quickstart
+
+```python
+from vantafin import RESTClient
+
+client = RESTClient("vf-live-your_api_key")
+
+# Latest quote
+print(client.get_quote("AAPL"))
+
+# Company profile
+print(client.get_ticker("AAPL"))
+
+# All tickers (paginated)
+page = client.list_tickers(type="stock", limit=100)
+print(page["count"], page["next_cursor"])
+```
+
+## Available methods
+
+| Method | Endpoint |
+| --- | --- |
+| `get_status()` | `GET /status` |
+| `list_tickers(...)` | `GET /companydata/tickers` |
+| `get_ticker(ticker)` | `GET /companydata/tickers/{ticker}` |
+| `get_company_by_cik(cik)` | `GET /companydata/ciks/{cik}` |
+| `get_company_by_isin(isin)` | `GET /companydata/isins/{isin}` |
+| `get_company_by_cusip(cusip)` | `GET /companydata/cusips/{cusip}` |
+| `search(query, ...)` | `GET /companydata/search` |
+| `get_quote(ticker)` | `GET /quotes/{ticker}` |
+| `get_quotes(tickers)` | `GET /quotes` |
+| `screener(...)` | `GET /screener` |
+| `screener_fields()` | `GET /screener/fields` |
+| `list_earnings(...)` | `GET /earnings` |
+| `get_earnings(ticker, ...)` | `GET /earnings/{ticker}` |
+| `list_dividends(...)` | `GET /dividends` |
+| `get_dividends(ticker, ...)` | `GET /dividends/{ticker}` |
+| `list_splits(...)` | `GET /splits` |
+| `get_splits(ticker, ...)` | `GET /splits/{ticker}` |
+| `list_ipos(...)` | `GET /ipos` |
+| `get_ipos(ticker, ...)` | `GET /ipos/{ticker}` |
+| `get_etf_holdings(ticker)` | `GET /etf-holdings/{ticker}` |
+| `get_institutional_ownership(ticker, ...)` | `GET /institutional-ownership/{ticker}` |
+| `get_fund_holdings(ticker, ...)` | `GET /fund-holdings/{ticker}` |
+| `get_short_interest(ticker, ...)` | `GET /short-interest/{ticker}` |
+| `list_insider_transactions(...)` | `GET /insider-transactions` |
+| `get_insider_transactions(ticker, ...)` | `GET /insider-transactions/{ticker}` |
+| `get_financials(ticker, ...)` | `GET /financials/{ticker}` |
+| `get_revenue_segmentation(ticker, ...)` | `GET /revenue-segmentation/{ticker}` |
+| `get_allocation_breakdown(ticker)` | `GET /allocation-breakdown/{ticker}` |
+| `get_macro(...)` | `GET /macro` |
+| `get_filings(ticker, ...)` | `GET /filings/{ticker}` |
+| `get_filing(filing_id)` | `GET /filings/by-id/{filing_id}` |
+| `get_news(...)` | `GET /news` |
+| `get_ticker_news(ticker, ...)` | `GET /news/{ticker}` |
+| `list_transcript_tickers(...)` | `GET /transcripts/tickers` |
+| `list_transcripts(ticker, ...)` | `GET /transcripts/{ticker}` |
+| `get_transcript(ticker, transcript_id)` | `GET /transcripts/{ticker}/{transcript_id}` |
+| `list_earnings_materials(ticker, ...)` | `GET /earnings-materials/{ticker}` |
+| `get_earnings_material(ticker, material_id)` | `GET /earnings-materials/{ticker}/{material_id}` |
+
+## Rate limits
+
+The API allows **1,000 requests per minute** per key. When you exceed it the
+client raises `RateLimitError` (with `.retry_after` seconds). Every response
+also carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`
+headers.
+
+## Error handling
+
+```python
+from vantafin import RESTClient, RateLimitError, NotFoundError
+
+client = RESTClient("vf-live-your_api_key")
+try:
+    client.get_quote("NOPE")
+except NotFoundError:
+    print("Unknown ticker")
+except RateLimitError as e:
+    print(f"Slow down, retry in {e.retry_after}s")
+```
+
+## WebSocket streaming
+
+Stream real-time data over a single WebSocket connection to
+`wss://socket.vantafin.com/v1/stocks`. Three channels are available:
+
+| Channel | Subscribe with | Message `type` |
+| --- | --- | --- |
+| Live news / press releases | `N.<ticker>` or `N.*` | `news` |
+| Live SEC filings | `F.<ticker>` or `F.*` | `filing` |
+| Trading halts | `H.<ticker>` or `H.*` | `halt` |
+
+The WebSocket client needs the optional `websocket-client` dependency:
+
+```bash
+pip install vantafin[websocket]
+```
+
+```python
+from vantafin import WebSocketClient
+
+ws = WebSocketClient("vf-live-your_api_key")
+ws.connect()
+ws.subscribe(["N.AAPL", "F.AAPL", "H.AAPL"])
+
+for message in ws:
+    print(message)
+```
+
+## Other languages
+
+Official clients for other languages live alongside this Python package:
+
+| Language | Folder |
+| --- | --- |
+| JavaScript / Node | [`javascript/`](./javascript) |
+| Go | [`go/`](./go) |
+| Java | [`java/`](./java) |
+| Ruby | [`ruby/`](./ruby) |
+
+## Full documentation
+
+[https://vantafin.com/docs](https://vantafin.com/docs)

vantafin-0.1.0/README.md

@@ -0,0 +1,150 @@
+# vantafin
+
+Official Python client for the [Vantafin](https://vantafin.com) REST API - quotes,
+corporate actions, fundamentals, SEC filings, news, earnings transcripts, and
+earnings materials (IR decks, press releases, supplements).
+
+**Source:** [github.com/vantafin/vantafin](https://github.com/vantafin/vantafin)
+
+## Installation
+
+```bash
+pip install vantafin
+```
+
+Or install from source:
+
+```bash
+pip install git+https://github.com/vantafin/vantafin.git
+```
+
+## Authentication
+
+Grab your API key from **Settings → API Usage** at
+[vantafin.com/app/settings](https://vantafin.com/app/settings). Keys look like
+`vf-live-...`. You can reset a key at any time from the same page.
+
+## Quickstart
+
+```python
+from vantafin import RESTClient
+
+client = RESTClient("vf-live-your_api_key")
+
+# Latest quote
+print(client.get_quote("AAPL"))
+
+# Company profile
+print(client.get_ticker("AAPL"))
+
+# All tickers (paginated)
+page = client.list_tickers(type="stock", limit=100)
+print(page["count"], page["next_cursor"])
+```
+
+## Available methods
+
+| Method | Endpoint |
+| --- | --- |
+| `get_status()` | `GET /status` |
+| `list_tickers(...)` | `GET /companydata/tickers` |
+| `get_ticker(ticker)` | `GET /companydata/tickers/{ticker}` |
+| `get_company_by_cik(cik)` | `GET /companydata/ciks/{cik}` |
+| `get_company_by_isin(isin)` | `GET /companydata/isins/{isin}` |
+| `get_company_by_cusip(cusip)` | `GET /companydata/cusips/{cusip}` |
+| `search(query, ...)` | `GET /companydata/search` |
+| `get_quote(ticker)` | `GET /quotes/{ticker}` |
+| `get_quotes(tickers)` | `GET /quotes` |
+| `screener(...)` | `GET /screener` |
+| `screener_fields()` | `GET /screener/fields` |
+| `list_earnings(...)` | `GET /earnings` |
+| `get_earnings(ticker, ...)` | `GET /earnings/{ticker}` |
+| `list_dividends(...)` | `GET /dividends` |
+| `get_dividends(ticker, ...)` | `GET /dividends/{ticker}` |
+| `list_splits(...)` | `GET /splits` |
+| `get_splits(ticker, ...)` | `GET /splits/{ticker}` |
+| `list_ipos(...)` | `GET /ipos` |
+| `get_ipos(ticker, ...)` | `GET /ipos/{ticker}` |
+| `get_etf_holdings(ticker)` | `GET /etf-holdings/{ticker}` |
+| `get_institutional_ownership(ticker, ...)` | `GET /institutional-ownership/{ticker}` |
+| `get_fund_holdings(ticker, ...)` | `GET /fund-holdings/{ticker}` |
+| `get_short_interest(ticker, ...)` | `GET /short-interest/{ticker}` |
+| `list_insider_transactions(...)` | `GET /insider-transactions` |
+| `get_insider_transactions(ticker, ...)` | `GET /insider-transactions/{ticker}` |
+| `get_financials(ticker, ...)` | `GET /financials/{ticker}` |
+| `get_revenue_segmentation(ticker, ...)` | `GET /revenue-segmentation/{ticker}` |
+| `get_allocation_breakdown(ticker)` | `GET /allocation-breakdown/{ticker}` |
+| `get_macro(...)` | `GET /macro` |
+| `get_filings(ticker, ...)` | `GET /filings/{ticker}` |
+| `get_filing(filing_id)` | `GET /filings/by-id/{filing_id}` |
+| `get_news(...)` | `GET /news` |
+| `get_ticker_news(ticker, ...)` | `GET /news/{ticker}` |
+| `list_transcript_tickers(...)` | `GET /transcripts/tickers` |
+| `list_transcripts(ticker, ...)` | `GET /transcripts/{ticker}` |
+| `get_transcript(ticker, transcript_id)` | `GET /transcripts/{ticker}/{transcript_id}` |
+| `list_earnings_materials(ticker, ...)` | `GET /earnings-materials/{ticker}` |
+| `get_earnings_material(ticker, material_id)` | `GET /earnings-materials/{ticker}/{material_id}` |
+
+## Rate limits
+
+The API allows **1,000 requests per minute** per key. When you exceed it the
+client raises `RateLimitError` (with `.retry_after` seconds). Every response
+also carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`
+headers.
+
+## Error handling
+
+```python
+from vantafin import RESTClient, RateLimitError, NotFoundError
+
+client = RESTClient("vf-live-your_api_key")
+try:
+    client.get_quote("NOPE")
+except NotFoundError:
+    print("Unknown ticker")
+except RateLimitError as e:
+    print(f"Slow down, retry in {e.retry_after}s")
+```
+
+## WebSocket streaming
+
+Stream real-time data over a single WebSocket connection to
+`wss://socket.vantafin.com/v1/stocks`. Three channels are available:
+
+| Channel | Subscribe with | Message `type` |
+| --- | --- | --- |
+| Live news / press releases | `N.<ticker>` or `N.*` | `news` |
+| Live SEC filings | `F.<ticker>` or `F.*` | `filing` |
+| Trading halts | `H.<ticker>` or `H.*` | `halt` |
+
+The WebSocket client needs the optional `websocket-client` dependency:
+
+```bash
+pip install vantafin[websocket]
+```
+
+```python
+from vantafin import WebSocketClient
+
+ws = WebSocketClient("vf-live-your_api_key")
+ws.connect()
+ws.subscribe(["N.AAPL", "F.AAPL", "H.AAPL"])
+
+for message in ws:
+    print(message)
+```
+
+## Other languages
+
+Official clients for other languages live alongside this Python package:
+
+| Language | Folder |
+| --- | --- |
+| JavaScript / Node | [`javascript/`](./javascript) |
+| Go | [`go/`](./go) |
+| Java | [`java/`](./java) |
+| Ruby | [`ruby/`](./ruby) |
+
+## Full documentation
+
+[https://vantafin.com/docs](https://vantafin.com/docs)

vantafin-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling >= 1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vantafin"
+version = "0.1.0"
+authors = [
+  { name = "Vantafin" },
+]
+description = "Official Python client for the Vantafin REST API (market data, fundamentals, SEC filings, news and more)."
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["vantafin", "stocks", "market-data", "finance", "sec", "api"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Office/Business :: Financial",
+]
+dependencies = ["requests>=2.25"]
+
+[project.optional-dependencies]
+websocket = ["websocket-client>=1.6"]
+
+[project.urls]
+Homepage = "https://vantafin.com"
+Documentation = "https://vantafin.com/docs"
+Repository = "https://github.com/vantafin/vantafin"
+Issues = "https://github.com/vantafin/vantafin/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vantafin"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src/vantafin",
+    "/LICENSE",
+    "/README.md",
+    "/pyproject.toml",
+]

vantafin-0.1.0/src/vantafin/__init__.py

@@ -0,0 +1,35 @@
+"""
+Vantafin - official Python client for the Vantafin REST API.
+
+    from vantafin import RESTClient
+
+    client = RESTClient("vf-live-your_api_key")
+    print(client.get_quote("AAPL"))
+
+Docs: https://vantafin.com/docs
+"""
+
+from .client import RESTClient
+from .ws import WebSocketClient, DEFAULT_WS_URL
+from .exceptions import (
+    VantafinError,
+    AuthenticationError,
+    RateLimitError,
+    NotFoundError,
+    BadRequestError,
+    ServerError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "RESTClient",
+    "WebSocketClient",
+    "DEFAULT_WS_URL",
+    "VantafinError",
+    "AuthenticationError",
+    "RateLimitError",
+    "NotFoundError",
+    "BadRequestError",
+    "ServerError",
+]

vantafin-0.1.0/src/vantafin/client.py

@@ -0,0 +1,376 @@
+"""Synchronous REST client for the Vantafin Data API."""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Sequence, Union
+
+import requests
+
+from .exceptions import (
+    AuthenticationError,
+    BadRequestError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    VantafinError,
+)
+
+DEFAULT_BASE_URL = "https://api.vantafin.com/v1"
+
+
+class RESTClient:
+    """
+    Client for the Vantafin REST API.
+
+    Args:
+        api_key: Your Vantafin API key (``vf-live-...``). Find or reset it in
+            Settings → API Usage at https://vantafin.com/app/settings.
+        base_url: Override the API base URL (defaults to the production API).
+        timeout: Per-request timeout in seconds.
+        session: Optionally supply a pre-configured ``requests.Session``.
+
+    Example:
+        >>> from vantafin import RESTClient
+        >>> client = RESTClient("vf-live-...")
+        >>> client.get_quote("AAPL")
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        if not api_key or not isinstance(api_key, str):
+            raise ValueError("api_key is required (e.g. 'vf-live-...').")
+        self.api_key = api_key.strip()
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._session = session or requests.Session()
+        self._session.headers.update(
+            {
+                "Authorization": f"Bearer {self.api_key}",
+                "Accept": "application/json",
+                "User-Agent": "vantafin-python/0.1.0",
+            }
+        )
+
+    # ── core request ────────────────────────────────────────────────────
+    def _get(self, path: str, params: Optional[dict] = None) -> Any:
+        url = f"{self.base_url}{path}"
+        clean = {k: v for k, v in (params or {}).items() if v is not None}
+        resp = self._session.get(url, params=clean, timeout=self.timeout)
+        return self._handle(resp)
+
+    @staticmethod
+    def _handle(resp: requests.Response) -> Any:
+        if resp.status_code < 400:
+            try:
+                return resp.json()
+            except ValueError:
+                return resp.text
+
+        try:
+            payload = resp.json()
+            message = payload.get("error") or payload.get("detail") or resp.text
+        except ValueError:
+            payload = None
+            message = resp.text or resp.reason
+
+        code = resp.status_code
+        if code == 401:
+            raise AuthenticationError(message, status_code=code, response=resp)
+        if code == 400:
+            raise BadRequestError(message, status_code=code, response=resp)
+        if code == 404:
+            raise NotFoundError(message, status_code=code, response=resp)
+        if code == 429:
+            retry_after = None
+            if isinstance(payload, dict):
+                retry_after = payload.get("retry_after_seconds")
+            if retry_after is None:
+                hdr = resp.headers.get("Retry-After")
+                retry_after = int(hdr) if hdr and hdr.isdigit() else None
+            raise RateLimitError(
+                message, retry_after=retry_after, status_code=code, response=resp
+            )
+        if code >= 500:
+            raise ServerError(message, status_code=code, response=resp)
+        raise VantafinError(message, status_code=code, response=resp)
+
+    # ── status ──────────────────────────────────────────────────────────
+    def get_status(self) -> dict:
+        """Verify the API key and read your rate-limit ceiling."""
+        return self._get("/status")
+
+    # ── company data ───────────────────────────────────────────────────────
+    def list_tickers(
+        self,
+        *,
+        search: Optional[str] = None,
+        type: Optional[str] = None,
+        cursor: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> dict:
+        """List the ticker universe. Paginate via the returned ``next_cursor``."""
+        return self._get(
+            "/companydata/tickers",
+            {"search": search, "type": type, "cursor": cursor, "limit": limit},
+        )
+
+    def get_ticker(self, ticker: str) -> dict:
+        """Full company/ETF profile for a single ticker."""
+        return self._get(f"/companydata/tickers/{ticker.upper()}")
+
+    def get_company_by_cik(self, cik: str) -> dict:
+        """Full company/ETF profile for a single SEC CIK."""
+        return self._get(f"/companydata/ciks/{cik.strip()}")
+
+    def get_company_by_isin(self, isin: str) -> dict:
+        """Full company/ETF profile for a single ISIN."""
+        return self._get(f"/companydata/isins/{isin.strip().upper()}")
+
+    def get_company_by_cusip(self, cusip: str) -> dict:
+        """Full company/ETF profile for a single CUSIP."""
+        return self._get(f"/companydata/cusips/{cusip.strip().upper()}")
+
+    def search(self, query: str, *, limit: Optional[int] = None) -> dict:
+        """Fuzzy search across tickers and company names."""
+        return self._get("/companydata/search", {"query": query, "limit": limit})
+
+    # ── market data ─────────────────────────────────────────────────────
+    def get_quote(self, ticker: str) -> dict:
+        """Latest stored quote for a ticker."""
+        return self._get(f"/quotes/{ticker.upper()}")
+
+    def get_quotes(self, tickers: Union[str, Sequence[str]]) -> dict:
+        """Latest quotes for up to 200 tickers at once."""
+        if not isinstance(tickers, str):
+            tickers = ",".join(s.upper() for s in tickers)
+        return self._get("/quotes", {"tickers": tickers})
+
+    # ── screener ────────────────────────────────────────────────────────
+    def screener(
+        self,
+        *,
+        filter: Optional[Union[str, Sequence[str]]] = None,
+        sort: Optional[str] = None,
+        order: Optional[str] = None,
+        columns: Optional[Union[str, Sequence[str]]] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> dict:
+        """Screen the equity universe across the full metric registry.
+
+        ``filter`` is one or more ``metric:operator:value`` clauses (a string or a list
+        of strings), combined with AND, e.g. ``["peRatio:below:20", "marketCap:above:1e9"]``.
+        Sort by any metric id, page with ``limit``/``offset`` and request extra metric
+        ``columns``. Call :meth:`screener_fields` for the available metrics.
+        """
+        cols = ",".join(columns) if isinstance(columns, (list, tuple)) else columns
+        flt = list(filter) if isinstance(filter, (list, tuple)) else filter
+        return self._get(
+            "/screener",
+            {
+                "filter": flt,
+                "sort": sort,
+                "order": order,
+                "columns": cols,
+                "limit": limit,
+                "offset": offset,
+            },
+        )
+
+    def screener_fields(self) -> dict:
+        """List every metric available to filter, sort or select in the screener."""
+        return self._get("/screener/fields")
+
+    # ── corporate actions ───────────────────────────────────────────────
+    def list_earnings(self, *, page: Optional[int] = None, limit: Optional[int] = None) -> dict:
+        return self._get("/earnings", {"page": page, "limit": limit})
+
+    def get_earnings(self, ticker: str, *, limit: Optional[int] = None) -> dict:
+        return self._get(f"/earnings/{ticker.upper()}", {"limit": limit})
+
+    def list_dividends(self, *, page: Optional[int] = None, limit: Optional[int] = None) -> dict:
+        return self._get("/dividends", {"page": page, "limit": limit})
+
+    def get_dividends(self, ticker: str, *, limit: Optional[int] = None) -> dict:
+        return self._get(f"/dividends/{ticker.upper()}", {"limit": limit})
+
+    def list_splits(self, *, page: Optional[int] = None, limit: Optional[int] = None) -> dict:
+        return self._get("/splits", {"page": page, "limit": limit})
+
+    def get_splits(self, ticker: str, *, limit: Optional[int] = None) -> dict:
+        return self._get(f"/splits/{ticker.upper()}", {"limit": limit})
+
+    def list_ipos(
+        self,
+        *,
+        from_: Optional[str] = None,
+        to: Optional[str] = None,
+        page: Optional[int] = None,
+        limit: Optional[int] = None,
+    ) -> dict:
+        """IPO calendar (past + upcoming) across all tickers, newest first."""
+        return self._get("/ipos", {"from": from_, "to": to, "page": page, "limit": limit})
+
+    def get_ipos(self, ticker: str, *, limit: Optional[int] = None) -> dict:
+        """Merged IPO record(s) for a single ticker."""
+        return self._get(f"/ipos/{ticker.upper()}", {"limit": limit})
+
+    # ── ownership ───────────────────────────────────────────────────────
+    def get_etf_holdings(self, ticker: str) -> dict:
+        """Constituent holdings for an ETF or mutual fund."""
+        return self._get(f"/etf-holdings/{ticker.upper()}")
+
+    def get_institutional_ownership(
+        self, ticker: str, *, limit: Optional[int] = None
+    ) -> dict:
+        return self._get(
+            f"/institutional-ownership/{ticker.upper()}", {"limit": limit}
+        )
+
+    def get_fund_holdings(self, ticker: str, *, limit: Optional[int] = None) -> dict:
+        return self._get(f"/fund-holdings/{ticker.upper()}", {"limit": limit})
+
+    def get_short_interest(self, ticker: str, *, limit: Optional[int] = None) -> dict:
+        return self._get(f"/short-interest/{ticker.upper()}", {"limit": limit})
+
+    def list_insider_transactions(
+        self, *, page: Optional[int] = None, limit: Optional[int] = None
+    ) -> dict:
+        return self._get("/insider-transactions", {"page": page, "limit": limit})
+
+    def get_insider_transactions(
+        self, ticker: str, *, page: Optional[int] = None, limit: Optional[int] = None
+    ) -> dict:
+        return self._get(
+            f"/insider-transactions/{ticker.upper()}", {"page": page, "limit": limit}
+        )
+
+    # ── fundamentals & macro ────────────────────────────────────────────
+    def get_financials(
+        self,
+        ticker: str,
+        *,
+        statement: str = "income",
+        period: str = "annual",
+        limit: Optional[int] = None,
+    ) -> dict:
+        """Financial statements: 'income', 'balance-sheet' or 'cash-flow'."""
+        return self._get(
+            f"/financials/{ticker.upper()}",
+            {"statement": statement, "period": period, "limit": limit},
+        )
+
+    def get_revenue_segmentation(
+        self,
+        ticker: str,
+        *,
+        dimension: str = "product",
+        period: str = "annual",
+    ) -> dict:
+        """Revenue by product line or geography for equity tickers."""
+        return self._get(
+            f"/revenue-segmentation/{ticker.upper()}",
+            {"dimension": dimension, "period": period},
+        )
+
+    def get_allocation_breakdown(self, ticker: str) -> dict:
+        """Sector and country weights for an ETF or mutual fund."""
+        return self._get(f"/allocation-breakdown/{ticker.upper()}")
+
+    def get_macro(self, *, category: Optional[str] = None, limit: Optional[int] = None) -> dict:
+        """Macro series. Omit ``category`` to list available categories."""
+        return self._get("/macro", {"category": category, "limit": limit})
+
+    # ── filings ─────────────────────────────────────────────────────────
+    def get_filings(
+        self,
+        ticker: str,
+        *,
+        form: Optional[str] = None,
+        page: Optional[int] = None,
+        limit: Optional[int] = None,
+    ) -> dict:
+        return self._get(
+            f"/filings/{ticker.upper()}", {"form": form, "page": page, "limit": limit}
+        )
+
+    def get_filing(self, filing_id: str) -> dict:
+        return self._get(f"/filings/by-id/{filing_id}")
+
+    # ── news ────────────────────────────────────────────────────────────
+    def get_news(
+        self,
+        *,
+        type: Optional[str] = None,
+        page: Optional[int] = None,
+        limit: Optional[int] = None,
+    ) -> dict:
+        return self._get("/news", {"type": type, "page": page, "limit": limit})
+
+    def get_ticker_news(
+        self,
+        ticker: str,
+        *,
+        type: Optional[str] = None,
+        page: Optional[int] = None,
+        limit: Optional[int] = None,
+    ) -> dict:
+        return self._get(
+            f"/news/{ticker.upper()}", {"type": type, "page": page, "limit": limit}
+        )
+
+    # ── transcripts ─────────────────────────────────────────────────────
+    def list_transcript_tickers(
+        self,
+        *,
+        search: Optional[str] = None,
+        cursor: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> dict:
+        return self._get(
+            "/transcripts/tickers",
+            {"search": search, "cursor": cursor, "limit": limit},
+        )
+
+    def list_transcripts(
+        self, ticker: str, *, page: Optional[int] = None, limit: Optional[int] = None
+    ) -> dict:
+        return self._get(f"/transcripts/{ticker.upper()}", {"page": page, "limit": limit})
+
+    def get_transcript(self, ticker: str, transcript_id: str) -> dict:
+        return self._get(f"/transcripts/{ticker.upper()}/{transcript_id}")
+
+    # ── earnings materials ──────────────────────────────────────────────
+    def list_earnings_materials(
+        self,
+        ticker: str,
+        *,
+        period: Optional[str] = None,
+        fiscal_year: Optional[int] = None,
+        page: Optional[int] = None,
+        limit: Optional[int] = None,
+    ) -> dict:
+        """List IR decks, press releases, and supplements for a ticker."""
+        return self._get(
+            f"/earnings-materials/{ticker.upper()}",
+            {"period": period, "fiscal_year": fiscal_year, "page": page, "limit": limit},
+        )
+
+    def get_earnings_material(self, ticker: str, material_id: str) -> dict:
+        """Metadata for a single earnings material."""
+        return self._get(f"/earnings-materials/{ticker.upper()}/{material_id}")
+
+    def close(self) -> None:
+        self._session.close()
+
+    def __enter__(self) -> "RESTClient":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()

vantafin-0.1.0/src/vantafin/exceptions.py

@@ -0,0 +1,38 @@
+"""Exception hierarchy for the Vantafin client."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class VantafinError(Exception):
+    """Base error for all Vantafin API failures."""
+
+    def __init__(self, message: str, *, status_code: Optional[int] = None, response=None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.response = response
+
+
+class AuthenticationError(VantafinError):
+    """Raised on 401 - missing, invalid or revoked API key."""
+
+
+class BadRequestError(VantafinError):
+    """Raised on 400 - invalid parameters."""
+
+
+class NotFoundError(VantafinError):
+    """Raised on 404 - resource does not exist."""
+
+
+class RateLimitError(VantafinError):
+    """Raised on 429 - too many requests. ``retry_after`` is seconds to wait."""
+
+    def __init__(self, message: str, *, retry_after: Optional[int] = None, **kwargs):
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class ServerError(VantafinError):
+    """Raised on 5xx - server-side failure."""

vantafin-0.1.0/src/vantafin/ws.py

@@ -0,0 +1,105 @@
+"""WebSocket client for the Vantafin real-time Data API.
+
+Streams live news / press releases (``N.<ticker>`` or ``N.*``),
+live SEC filings (``F.<ticker>`` or ``F.*``), and trading halts
+(``H.<ticker>`` or ``H.*``) over a single connection to
+``wss://socket.vantafin.com/v1/stocks``.
+
+Requires the optional ``websocket-client`` dependency::
+
+    pip install vantafin[websocket]
+
+Example::
+
+    from vantafin import WebSocketClient
+
+    ws = WebSocketClient("vf-live-your_api_key")
+    ws.connect()
+    ws.subscribe(["N.AAPL", "F.AAPL", "H.AAPL"])
+    for message in ws:
+        print(message)
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Iterable, Iterator, Optional, Union
+
+DEFAULT_WS_URL = "wss://socket.vantafin.com/v1/stocks"
+
+
+class WebSocketClient:
+    """Synchronous WebSocket client for Vantafin real-time streams.
+
+    Args:
+        api_key: Your Vantafin API key (``vf-live-...``).
+        url: Override the WebSocket URL (defaults to production).
+    """
+
+    def __init__(self, api_key: str, *, url: str = DEFAULT_WS_URL) -> None:
+        if not api_key or not isinstance(api_key, str):
+            raise ValueError("api_key is required (e.g. 'vf-live-...').")
+        self.api_key = api_key.strip()
+        self.url = url
+        self._ws = None
+
+    def connect(self, *, timeout: Optional[float] = None) -> "WebSocketClient":
+        """Open the connection, authenticating via the ``apiKey`` query parameter."""
+        try:
+            import websocket  # type: ignore
+        except ImportError as exc:  # pragma: no cover
+            raise ImportError(
+                "WebSocketClient requires the 'websocket-client' package. "
+                "Install it with: pip install vantafin[websocket]"
+            ) from exc
+
+        sep = "&" if "?" in self.url else "?"
+        full_url = f"{self.url}{sep}apiKey={self.api_key}"
+        self._ws = websocket.create_connection(full_url, timeout=timeout)
+        return self
+
+    def subscribe(self, channels: Union[str, Iterable[str]]) -> None:
+        """Subscribe to one or more channels, e.g. ``"N.AAPL"`` or ``["N.*", "F.AAPL", "H.*"]``."""
+        self._send("subscribe", channels)
+
+    def unsubscribe(self, channels: Union[str, Iterable[str]]) -> None:
+        """Unsubscribe from one or more channels."""
+        self._send("unsubscribe", channels)
+
+    def _send(self, action: str, channels: Union[str, Iterable[str]]) -> None:
+        if self._ws is None:
+            raise RuntimeError("WebSocket is not connected; call connect() first.")
+        if isinstance(channels, str):
+            channels = [channels]
+        params = ",".join(c.strip().upper() for c in channels)
+        self._ws.send(json.dumps({"action": action, "params": params}))
+
+    def recv(self) -> dict:
+        """Block for the next message and return it parsed as a dict."""
+        if self._ws is None:
+            raise RuntimeError("WebSocket is not connected; call connect() first.")
+        raw = self._ws.recv()
+        try:
+            return json.loads(raw)
+        except (json.JSONDecodeError, TypeError):
+            return {"type": "raw", "data": raw}
+
+    def __iter__(self) -> Iterator[dict]:
+        while True:
+            try:
+                yield self.recv()
+            except Exception:
+                return
+
+    def close(self) -> None:
+        if self._ws is not None:
+            try:
+                self._ws.close()
+            finally:
+                self._ws = None
+
+    def __enter__(self) -> "WebSocketClient":
+        return self.connect()
+
+    def __exit__(self, *exc) -> None:
+        self.close()