Metadata-Version: 2.4
Name: xfinlink
Version: 0.9.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 (147 fields) |
| `GET /v1/metrics/{ticker}` | 108 pre-computed metrics across 9 categories |
| `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/insiders/{ticker}` | Insider transactions (Pro only) |

Ticker endpoints accept comma-separated symbols, for example `/v1/prices/AAPL,MSFT,GOOGL`. Pro supports up to 100 tickers per call on data endpoints; `/v1/resolve` supports up to 10.

## Rate limits

Free: 100/day (40/hour burst). Pro: 10,000/day (no burst). See [pricing](https://xfinlink.com/pricing).

## Links

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