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)
