Metadata-Version: 2.4
Name: xfinlink
Version: 0.6.0
Summary: Free 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/dignaga69/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
Provides-Extra: local
Requires-Dist: sqlalchemy>=2.0; extra == "local"
Requires-Dist: pyarrow; extra == "local"
Requires-Dist: pydantic; extra == "local"
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.

## 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 (129 fields) |
| `GET /v1/metrics/{ticker}` | 36 pre-computed ratios and per-share values |
| `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) |

All endpoints accept multi-ticker: `/v1/prices/AAPL,MSFT,GOOGL`

## Rate limits

5,000 requests/day, 500 requests/hour burst. Free.

## Links

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