Metadata-Version: 2.4
Name: xfinlink
Version: 0.10.0
Summary: Financial data API client — prices, fundamentals, entity resolution for all US equities
Author: xfinlink team
License-Expression: MIT
Project-URL: Homepage, https://xfinlink.com
Project-URL: Repository, https://github.com/xfinlink/xfinlink
Project-URL: Documentation, https://xfinlink.com/docs
Keywords: finance,stock,prices,fundamentals,SEC,EDGAR,ticker,entity-resolution,financial-data,API
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24
Requires-Dist: pandas>=1.5
Requires-Dist: typer>=0.9
Requires-Dist: rich>=13
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Dynamic: license-file

# xfinlink

Free financial data API for US equities — prices, fundamentals, metrics, entity resolution, index constituents, and insider transactions.

## Install

```bash
pip install xfinlink
```

## Quick start

```python
import xfinlink as xfl

xfl.set_api_key("your-key")  # or set XFINLINK_API_KEY env var
# Get a free key at https://xfinlink.com/signup

# Historical prices
df = xfl.prices("AAPL", start="2024-01-01", end="2024-12-31")
print(df[["date", "close", "adj_close", "volume"]].head())

# Multi-ticker
df = xfl.prices(["AAPL", "MSFT", "GOOGL"], start="2024-01-01")

# Financial statements
df = xfl.fundamentals("AAPL", period_type="annual")

# Computed metrics (P/E, ROE, margins, etc.)
df = xfl.metrics("AAPL", fields=["pe_ratio", "roe", "market_cap"])

# Entity resolution
info = xfl.resolve("GM")

# Search
df = xfl.search(q="apple")

# S&P 500 constituents
df = xfl.index("sp500")

# Check usage
xfl.usage()
```

## Defaults

- `start` defaults to 1 year ago if omitted.
- Pagination stops at `max_rows` (default 10,000). Increase if you need more.
- `date` and `period_end` are regular DataFrame columns, not the index.

## API endpoints

| Endpoint | Use case |
|---|---|
| `GET /v1/prices/{ticker}` | Historical prices, volume, dividends, splits |
| `GET /v1/fundamentals/{ticker}` | Financial statements |
| `GET /v1/metrics/{ticker}` | Pre-computed financial metrics |
| `GET /v1/resolve/{ticker}` | Entity resolution, corporate history |
| `GET /v1/search` | Find companies by name, sector, SIC, NAICS |
| `GET /v1/index/{name}` | Index constituents (current or historical) |
| `GET /v1/index/{name}/events` | Index additions and removals as a dated event log |
| `GET /v1/insiders/{ticker}` | Insider transactions (paid plans) |

Ticker endpoints accept comma-separated symbols, for example `/v1/prices/AAPL,MSFT,GOOGL`. Tickers per call on data endpoints scale by plan: 1 (Free), 100 (Pro), 500 (Business), 1,000 (Redistribution); `/v1/resolve` supports up to 10.

## Rate limits

Requests per day: Free 100 (40/hour burst), Pro 10,000, Business 50,000, Redistribution 100,000. Only the Free tier is throttled per hour. Paid plans also unlock full history (daily prices back to 1996, fundamentals back to 1950). See [pricing](https://xfinlink.com/pricing).

## Links

- Docs: https://xfinlink.com/docs
- Signup: https://xfinlink.com/signup
- LLM context: https://xfinlink.com/llms.txt
