xfinlink

https://xfinlink.com/docs
Admin
xfinlink is a Python client and API for comprehensive US equity financial data including prices,...
Tokens:14,333
Snippets:123
Trust Score:7.5
Update:5 months ago
Show doc for...
Tokens:
Raw
### Quick Example: Fetch AAPL Prices

Source: https://xfinlink.com/docs

Fetches and displays the head of daily price data for AAPL. This is a basic example to get started with the xfinlink library.

```python
import xfinlink as xfl
xfl.set_api_key("YOUR_API_KEY")

df = xfl.prices("AAPL", start="2025-01-01", end="2025-03-31")
print(df[["date", "close", "adj_close", "volume"]].head())
```

--------------------------------

### Install and Authenticate xfinlink

Source: https://xfinlink.com/docs

Installs the xfinlink library and sets the API key. Ensure you call set_api_key() before any other xfinlink functions.

```bash
pip install xfinlink
```

```python
import xfinlink as xfl
xfl.set_api_key("YOUR_API_KEY")  # get a free key at https://xfinlink.com/signup
```

--------------------------------

### Install xfinlink Package

Source: https://xfinlink.com/docs

Install the xfinlink Python package using pip.

```terminal
pip install xfinlink
```

--------------------------------

### Python Authentication Setup

Source: https://xfinlink.com/docs

Configure the xfinlink Python client with your API key.

```python
import xfinlink as xfl

# Set your API key — get a free key at https://xfinlink.com/signup
xfl.set_api_key("YOUR_API_KEY")
```

--------------------------------

### Python Quick Start with xfinlink

Source: https://xfinlink.com/docs

Set your API key and make initial queries for prices, fundamentals, metrics, index constituents, search, and entity resolution using the xfinlink Python client.

```python
import xfinlink as xfl

# Set your API key — get a free key at https://xfinlink.com/signup
xfl.set_api_key("YOUR_API_KEY")

# Historical prices
prices = xfl.prices("AAPL", start="2024-01-01")

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

# Pre-computed metrics (P/E, ROE, margins, ...)
metrics = xfl.metrics("AAPL", fields=["pe_ratio", "roe"])

# Index constituents
sp500 = xfl.index("sp500")

# Search for entities
results = xfl.search(q="apple")

# Entity resolution (handles ticker recycling)
entity = xfl.resolve("GM")
```

--------------------------------

### Grok (xAI) API Integration

Source: https://xfinlink.com/docs

Python code example for integrating with the xAI API to query financial data using the Xfinlink MCP server. This requires an xAI API key and specifies the MCP server URL as a tool.

```python
from openai import OpenAI

client = OpenAI(
    api_key="your-xai-api-key",
    base_url="https://api.x.ai/v1",
)

response = client.responses.create(
    model="grok-4.20-reasoning",
    input=[{"role": "user", "content": "What's AAPL's quarterly revenue trend?"}],
    tools=[
        {
            "type": "mcp",
            "server_url": "https://api.xfinlink.com/mcp?api_key=YOUR_API_KEY",
            "server_label": "xfinlink",
        },
    ],
)

```

--------------------------------

### Python Request for Prices

Source: https://xfinlink.com/docs

Fetch historical price data for a given ticker, specifying the start date and desired fields.

```python
df = xfl.prices("AAPL", start="2024-01-01", fields=["close", "volume"])
```

--------------------------------

### Get Financial Metrics

Source: https://xfinlink.com/docs

Retrieve a selection of financial metrics for a specified ticker. You can choose the period type (annual/quarterly) and specific fields to return.

```python
df = xfl.metrics("AAPL", fields=["pe_ratio", "roe", "market_cap"])
```

--------------------------------

### Fetch Historical Prices with Date Object

Source: https://xfinlink.com/docs

Retrieves historical OHLCV data using a Python date object for the start date.

```python
from datetime import date
df = xfl.prices("AAPL", start=date(2025, 1, 1))
```

--------------------------------

### Fetch Historical Prices for Multiple Tickers

Source: https://xfinlink.com/docs

Retrieves historical OHLCV data for multiple tickers. If only start date is provided, it defaults to 1 year ago.

```python
df = xfl.prices(["AAPL", "MSFT"], start="2025-01-01")
```

--------------------------------

### Get Index Constituents

Source: https://xfinlink.com/docs

Retrieves a list of constituents for a specified index (e.g., S&P 500, Nasdaq 100) either currently or historically. Supports pagination with limit and offset. Maximum limit is 1000.

```python
df = xfl.index("sp500")
```

```python
df = xfl.index("ndx100", as_of="2020-01-01")
```

--------------------------------

### Python Entity Resolution

Source: https://xfinlink.com/docs

Resolve a ticker symbol to get its full entity history, including name, ticker validity dates, and classifications.

```python
info = xfl.resolve("GM")
for entity in info["data"]["GM"]["entities"]:
    print(entity["name"], entity["ticker_valid_from"], entity["ticker_valid_to"])
```

--------------------------------

### Get Insider Transactions

Source: https://xfinlink.com/docs

Fetch insider transaction data for a given ticker, filtering by transaction type, insider role, and other parameters. This endpoint is part of the Pro tier.

```python
df = xfl.insiders("TSLA", transaction_type="open_market_sell", insider_role="CEO")
```

--------------------------------

### Get Index Constituents

Source: https://xfinlink.com/docs

Retrieve current and historical constituents for major stock market indices like S&P 500, Nasdaq 100, Dow Jones, and Russell 2000. Supports specifying a point-in-time date.

```python
df = xfl.index("sp500")
df = xfl.index("sp500", as_of="2020-01-01")
```

--------------------------------

### Retrieve Insider Transactions

Source: https://xfinlink.com/docs

Fetches insider transaction data from SEC filings (Forms 3/4/5) for specified tickers. Allows filtering by date range, transaction type, insider role, and minimum value. Coverage starts from 1986. This feature requires a Pro tier subscription.

```python
df = xfl.insiders("AAPL", period="1y")
```

```python
df = xfl.insiders("TSLA", transaction_type="open_market_sell")
```

```python
df = xfl.insiders("NVDA", insider_role="CEO", min_value=1_000_000)
```

```python
df = xfl.insiders("META", acquisition_or_disposition="A", insider_role="Director")
```

--------------------------------

### Compare Revenue, Net Income, and Operating Cash Flow

Source: https://xfinlink.com/docs

Fetches annual fundamental data for multiple tech companies and prints their revenue and net income. Use this to compare financial performance across different entities.

```python
import xfinlink as xfl

df = xfl.fundamentals(
    ["AAPL", "MSFT", "GOOGL"],
    period_type="annual",
    fields=["revenue", "net_income", "operating_cash_flow"],
    start="2024-01-01",
)
print(df[["ticker", "period_end", "revenue", "net_income"]])
```

--------------------------------

### Rank Sector by Market Cap using Search and Metrics

Source: https://xfinlink.com/docs

Searches for companies within the Information Technology sector, retrieves their market cap and P/E ratio, and ranks them by market capitalization. Handles up to 100 tickers per call for metrics.

```python
import xfinlink as xfl
xfl.set_api_key("YOUR_API_KEY")

tech = xfl.search(gics_sector="Information Technology", limit=50)
tickers = tech["ticker"].dropna().tolist()

# metrics already returns entity_name — no need to merge with search results
# metrics accepts up to 100 tickers per call (prices and fundamentals: max 100)
m = xfl.metrics(tickers, fields=["market_cap", "pe_ratio", "roe"])
latest = m.sort_values("period_end").groupby("ticker").tail(1).reset_index(drop=True)
print(latest.sort_values("market_cap", ascending=False).head(20))
```

--------------------------------

### Set API Key and Handle Errors

Source: https://xfinlink.com/docs

Demonstrates how to set your API key and catch potential XfinlinkErrors, such as invalid tickers or rate limits. Ensure your API key is valid before making requests.

```python
import xfinlink as xfl
xfl.set_api_key("YOUR_API_KEY")

try:
    df = xfl.prices("INVALIDTICKER")
except xfl.XfinlinkError as e:
    print(e)  # "xfinlink: Ticker 'INVALIDTICKER' not found. Fix: ..."
```

--------------------------------

### Calculate Cumulative Return from Daily Prices

Source: https://xfinlink.com/docs

Fetches daily closing prices, adjusted closing prices, and daily total returns for a company over a year. It then calculates and displays the cumulative return. Note that 'adj_close' is adjusted for splits only.

```python
import xfinlink as xfl
xfl.set_api_key("YOUR_API_KEY")

# adj_close is split-only adjusted (stable, no dividend component)
# return_daily is total return including dividends (use this for performance)
# There is no dividend-adjusted price column — compute from return_daily if needed
df = xfl.prices("AAPL", period="1y", fields=["close", "adj_close", "return_daily"])
df["cum_return"] = (1 + df["return_daily"]).cumprod() - 1
print(f"Total return: {df['cum_return'].iloc[-1]:.2%}")
```

--------------------------------

### Fetch Quarterly Fundamentals for a Company

Source: https://xfinlink.com/docs

Retrieves quarterly revenue, gross profit, operating income, net income, and diluted EPS for a specified company over a 2-year period. Requires setting an API key and imports the xfinlink library.

```python
import xfinlink as xfl
xfl.set_api_key("YOUR_API_KEY")

# period_type is case-insensitive: "annual", "quarterly", "Annual" all work
df = xfl.fundamentals(
    "AAPL",
    period_type="quarterly",
    fields=["revenue", "gross_profit", "operating_income", "net_income", "eps_diluted"],
    period="2y",
)
print(df[["period_end", "revenue", "net_income", "eps_diluted"]])
```

--------------------------------

### Python Request for Fundamentals with Segments

Source: https://xfinlink.com/docs

Fetch fundamental data including revenue segments for a given ticker.

```python
df = xfl.fundamentals("AAPL", include_segments=True)
```

--------------------------------

### Fetch Quarterly Fundamentals with Specific Fields

Source: https://xfinlink.com/docs

Retrieves quarterly financial statement data, selecting specific fields such as revenue, net income, and EPS.

```python
df = xfl.fundamentals("AAPL", period_type="quarterly", fields=["revenue", "net_income", "eps_diluted"])
```

--------------------------------

### Python Request for Fundamentals

Source: https://xfinlink.com/docs

Retrieve annual financial fundamental data for a ticker, selecting specific fields like revenue and net income.

```python
df = xfl.fundamentals("AAPL", period_type="annual",
                fields=["revenue", "net_income"])
```

--------------------------------

### Cursor MCP Configuration

Source: https://xfinlink.com/docs

Configuration for the Cursor IDE to connect to the Xfinlink MCP server. This involves adding the server URL to the `.cursor/mcp.json` file.

```json
{
  "mcpServers": {
    "xfinlink": {
      "url": "https://api.xfinlink.com/mcp?api_key=YOUR_API_KEY"
    }
  }
}
```

--------------------------------

### Claude Desktop Configuration

Source: https://xfinlink.com/docs

Configuration for connecting to the Xfinlink MCP server via Claude Desktop. This involves adding the server details to the `claude_desktop_config.json` file.

```json
{
  "mcpServers": {
    "xfinlink": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.xfinlink.com/mcp?api_key=YOUR_API_KEY"]
    }
  }
}
```

--------------------------------

### Fetch Annual Fundamentals with Segment Breakdowns

Source: https://xfinlink.com/docs

Retrieves annual financial statement data, including detailed revenue segment breakdowns when include_segments is set to True.

```python
df = xfl.fundamentals("AAPL", include_segments=True, period_type="annual")
```

--------------------------------

### Analyze Quarterly Cash Flow

Source: https://xfinlink.com/docs

Fetches quarterly operating cash flow, free cash flow, capital expenditures, and net income for a company over 2 years. It then filters and displays specific cash flow metrics for a chosen quarter.

```python
import xfinlink as xfl
xfl.set_api_key("YOUR_API_KEY")

# Quarterly cash flows are already single-quarter standalone values
# (de-cumulated from SEC YTD convention at ingestion time)
df = xfl.fundamentals(
    "AAPL",
    period_type="quarterly",
    fields=["operating_cash_flow", "free_cash_flow", "capital_expenditures", "net_income_cf"],
    period="2y",
)
# Filter to a specific quarter
q3 = df[df["fiscal_period"] == "Q3"].iloc[-1]
print(f"AAPL {q3['fiscal_period']} FY{int(q3['fiscal_year'])}:")
print(f"  Operating cash flow: ${q3['operating_cash_flow']:,.0f}M")
print(f"  Free cash flow:      ${q3['free_cash_flow']:,.0f}M")
print(f"  Capital expenditures: ${q3['capital_expenditures']:,.0f}M")
```

--------------------------------

### Fetch Specific Metrics for Multiple Tickers

Source: https://xfinlink.com/docs

Retrieves specified computed financial metrics for a list of tickers simultaneously.

```python
df = xfl.metrics(["AAPL", "MSFT", "GOOGL"], fields=["pe_ratio", "market_cap"])
```

--------------------------------

### /v1/prices/{ticker}

Source: https://xfinlink.com/docs

Retrieves OHLCV prices with split adjustment, total returns, and dividend/split event data for US-listed stocks and ETFs. Supports various aggregation intervals and allows filtering by fields and adjustment mode.

```APIDOC
## GET /v1/prices/{ticker}

### Description
Retrieves OHLCV prices with split adjustment, total returns, and dividend/split event data. Coverage back to 1996 for every US-listed stock and ETF. Supports daily through yearly aggregation intervals.

### Method
GET

### Endpoint
/v1/prices/{ticker}

### Parameters
#### Path Parameters
- **ticker** (str | list[str]) - Required - Ticker(s) to fetch.

#### Query Parameters
- **start** (str (ISO date)) - Optional - Earliest date, inclusive.
- **end** (str (ISO date)) - Optional - Latest date, inclusive. Defaults to today.
- **interval** (str) - Optional - Aggregation interval: 1d, 3d, 1w, 1mo, 3mo, 6mo, 1y. Defaults to "1d".
- **fields** (list[str]) - Optional - Subset of columns. Defaults to all 12 fields.
- **adjust** (str) - Optional - Adjustment mode: split (default) or none. Defaults to "split".

### Request Example
```python
import xfinlink as xfl
df = xfl.prices("AAPL", start="2024-01-01", fields=["close", "volume"])
```

### Response
#### Success Response (200)
- **date** (str) - The date of the price data.
- **ticker** (str) - The ticker symbol.
- **close** (float) - The closing price.
- **volume** (int) - The trading volume.

#### Response Example
```
  date        ticker   close      volume
  2024-01-02  AAPL     185.64  45,123,456
  2024-01-03  AAPL     184.25  42,889,012
  2024-01-04  AAPL     181.91  49,301,234
  ...
```
```

--------------------------------

### cURL Request with API Key

Source: https://xfinlink.com/docs

Make an API request using cURL, passing the API key in the 'X-API-Key' header.

```curl
curl -H "X-API-Key: your-api-key" \
  https://api.xfinlink.com/v1/prices/AAPL?start=2024-01-01
```

--------------------------------

### Python Search by Query

Source: https://xfinlink.com/docs

Perform a fuzzy search for financial entities by name or ticker symbol.

```python
df = xfl.search(q="apple")
```

--------------------------------

### /v1/metrics/{ticker}

Source: https://xfinlink.com/docs

Retrieves a comprehensive set of 37 pre-computed financial metrics for specified company tickers. Supports filtering by period type and specific fields.

```APIDOC
## GET /v1/metrics/{ticker}

### Description
Fetches 37 pre-computed financial metrics derived from prices and fundamentals for a given ticker.

### Method
GET

### Endpoint
/v1/metrics/{ticker}

### Parameters
#### Path Parameters
- **ticker** (str) - Required - Ticker or comma-separated tickers.

#### Query Parameters
- **period_type** (str) - Optional (default: `annual`) - Specifies the data period: `annual` or `quarterly`.
- **fields** (str) - Optional (default: `all`) - Comma-separated list of metric names to retrieve. Available fields include:
  - **Valuation:** `market_cap`, `market_cap_diluted`, `enterprise_value`, `pe_ratio`, `ps_ratio`, `pb_ratio`, `price_to_cash_flow`, `ev_ebitda`, `earnings_yield`, `dividend_yield`
  - **Profitability:** `gross_margin`, `operating_margin`, `net_margin`, `ebitda_margin`, `roe`, `roa`, `roic`
  - **Leverage:** `debt_to_equity`, `debt_to_assets`, `long_term_debt_to_equity`, `long_term_debt_to_assets`, `current_ratio`, `quick_ratio`, `interest_coverage`
  - **Efficiency:** `asset_turnover`, `inventory_turnover`
  - **Per-share ($/share):** `revenue_per_share`, `book_value_per_share`, `tangible_book_value_per_share`, `cash_per_share`, `debt_per_share`, `ocf_per_share`, `fcf_per_share`, `ebit_per_share`, `ebitda_per_share`, `capex_per_share`, `working_capital_per_share`
- **start** (str) - Optional - Start date for `period_end` in ISO format.
- **end** (str) - Optional - End date for `period_end` in ISO format.
- **limit** (int) - Optional (default: 20) - Rows per page.

### Request Example
```python
df = xfl.metrics("AAPL", fields=["pe_ratio", "roe", "market_cap"])
```
```

--------------------------------

### Utility Functions

Source: https://xfinlink.com/docs

Provides access to utility functions for checking API status, usage, and configuring the API client.

```APIDOC
## Utility Functions

### Description
Provides access to utility functions for checking API status, usage, and configuring the API client.

### Available Functions
- **xfl.status() -> dict**: Checks the health status of the API.
- **xfl.usage() -> dict**: Retrieves rate limit status (requires an API key).
- **xfl.llm_context() -> str**: Prints and returns the content of this documentation file.
- **xfl.set_api_base(url: str)**: Allows overriding the base API URL, useful for testing.

### Examples
```python
# Check API status
status = xfl.status()
print(status)

# Check API usage (requires API key)
usage = xfl.usage()
print(usage)

# Get LLM context
context = xfl.llm_context()
print(context)

# Override API base URL for testing
xfl.set_api_base("http://localhost:8000")
```
```

--------------------------------

### Fetch Annual Metrics for a Period

Source: https://xfinlink.com/docs

Retrieves computed financial metrics on an annual basis for a specified ticker and period. Defaults to 'annual' period type.

```python
df = xfl.metrics("AAPL", period_type="annual", period="5y")
```

--------------------------------

### Fetch Annual Fundamentals for a Period

Source: https://xfinlink.com/docs

Retrieves annual financial statement data for a specified ticker over a given period. Defaults to 'restated' version.

```python
df = xfl.fundamentals("AAPL", period_type="annual", period="5y")
```

--------------------------------

### Fetch Historical Prices by Period

Source: https://xfinlink.com/docs

Retrieves historical OHLCV data for specified tickers using a predefined period (e.g., '1y' for one year).

```python
df = xfl.prices("AAPL MSFT GOOG", period="1y")
```

--------------------------------

### Utility Functions

Source: https://xfinlink.com/docs

Provides utility functions for checking API health, monitoring rate limit status, and overriding the API base URL for testing.

```python
xfl.status()
```

```python
xfl.usage()
```

```python
xfl.llm_context()
```

```python
xfl.set_api_base(url: str)
```

--------------------------------

### xfl.metrics

Source: https://xfinlink.com/docs

Retrieves 37 computed financial metrics, calculated from fundamentals and prices. Supports filtering by period type and specific fields.

```APIDOC
## xfl.metrics

### Description
Retrieves 37 computed financial metrics, calculated from fundamentals and prices. Supports filtering by period type and specific fields. Max 100 tickers per call.

### Method
`xfl.metrics`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **ticker** (str | list[str] | tuple) - Required - The stock ticker symbol(s).
- **period_type** (str) - Optional - Type of period to retrieve ("annual" or "quarterly"). Defaults to "annual".
- **fields** (list[str] | str | None) - Optional - Specific metrics to retrieve (e.g., "pe_ratio", "market_cap").
- **start** (str | date | None) - Optional - The start date for the data. Defaults to 1 year ago.
- **end** (str | date | None) - Optional - The end date for the data.
- **period** (str | None) - Optional - The number of periods to retrieve (e.g., "5y").
- **limit** (int) - Optional - Maximum number of rows to return. Defaults to 20.
- **max_rows** (int) - Optional - Maximum total rows allowed. Defaults to 10000.

### Request Example
```python
df = xfl.metrics("AAPL", period_type="annual", period="5y")
df = xfl.metrics("AAPL", fields=["pe_ratio", "roe", "market_cap"])
df = xfl.metrics(["AAPL", "MSFT", "GOOGL"], fields=["pe_ratio", "market_cap"])
```

### Response
Returns a pandas DataFrame containing computed financial metrics. Columns include structural data (entity_id, ticker, entity_name, period_end, period_type) and selectable metric fields.
```

--------------------------------

### /v1/resolve/{ticker}

Source: https://xfinlink.com/docs

Provides the full entity history for a given ticker symbol, including all companies that have used the ticker, their validity dates, classifications, and index memberships.

```APIDOC
## GET /v1/resolve/{ticker}

### Description
Full entity history for a ticker. Every company that ever used this ticker, with validity dates, classifications, and index membership.

### Method
GET

### Endpoint
/v1/resolve/{ticker}

### Parameters
#### Path Parameters
- **ticker** (str) - Required - Ticker symbol to resolve.

#### Query Parameters
- **as_of** (str (ISO date)) - Optional - Resolve as of a specific date.
- **include** (str) - Optional - "index", "classifications"

### Request Example
```python
import xfinlink as xfl
info = xfl.resolve("GM")
for entity in info["data"]["GM"]["entities"]:
    print(entity["name"], entity["ticker_valid_from"], entity["ticker_valid_to"])
```
```

--------------------------------

### Fetch Specific Fields for Historical Prices

Source: https://xfinlink.com/docs

Retrieves historical OHLCV data, selecting only specific fields like 'close' and 'volume'.

```python
df = xfl.prices("AAPL", fields=["close", "volume"])
```

--------------------------------

### MCP Server URL

Source: https://xfinlink.com/docs

The base URL for the MCP server. Replace YOUR_API_KEY with your actual API key obtained from the Xfinlink dashboard.

```text
https://api.xfinlink.com/mcp?api_key=YOUR_API_KEY
```

--------------------------------

### /v1/search

Source: https://xfinlink.com/docs

Enables discovery of financial entities by name, sector, type, or classification code. Supports fuzzy searching and filtering by various criteria.

```APIDOC
## GET /v1/search

### Description
Discover entities by name, sector, type, or classification code.

### Method
GET

### Endpoint
/v1/search

### Parameters
#### Query Parameters
- **q** (str) - Optional - Fuzzy search on name or ticker.
- **gics_sector** (str) - Optional - Filter by GICS sector name.
- **entity_type** (str) - Optional - Filter by entity type (corporation, etc.).
- **sic** (str) - Optional - Filter by SIC code.
- **naics** (str) - Optional - Filter by NAICS code.
- **country** (str) - Optional - Country filter. Defaults to "US".
- **limit** (int) - Optional - Results per page (max 500). Defaults to 50.
- **offset** (int) - Optional - Pagination offset. Defaults to 0.

### Request Example
```python
import xfinlink as xfl
df = xfl.search(gics_sector="Consumer Staples")
df = xfl.search(q="apple")
```
```

--------------------------------

### xfl.prices

Source: https://xfinlink.com/docs

Retrieves historical price data with server-side OHLCV aggregation. Supports multiple tickers and various time periods and intervals.

```APIDOC
## xfl.prices

### Description
Retrieves historical price data with server-side OHLCV aggregation. Supports multiple tickers and various time periods and intervals. Max 100 tickers per call.

### Method
`xfl.prices`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **ticker** (str | list[str] | tuple) - Required - The stock ticker symbol(s).
- **start** (str | date | None) - Optional - The start date for the data. Defaults to 1 year ago.
- **end** (str | date | None) - Optional - The end date for the data.
- **period** (str | None) - Optional - Predefined period for data retrieval (e.g., "1w", "1y", "max").
- **interval** (str) - Optional - The data interval (e.g., "1d", "1w"). Defaults to "1d".
- **fields** (list[str] | str | None) - Optional - Specific data fields to retrieve (e.g., "close", "volume").
- **adjust** (str) - Optional - Adjustment type for prices (e.g., "split", "none"). Defaults to "split".
- **limit** (int) - Optional - Maximum number of rows to return. Defaults to 5000.
- **max_rows** (int) - Optional - Maximum total rows allowed. Defaults to 10000.

### Request Example
```python
df = xfl.prices("AAPL", start="2025-01-01", end="2025-06-30")
df = xfl.prices(["AAPL", "MSFT"], start="2025-01-01")
df = xfl.prices("AAPL MSFT GOOG", period="1y")
df = xfl.prices("AAPL", start=date(2025, 1, 1))
df = xfl.prices("AAPL", fields=["close", "volume"])
```

### Response
Returns a pandas DataFrame containing historical price data. Columns include structural data (entity_id, ticker, entity_name, gics_sector, date) and selectable data fields (open, high, low, close, adj_close, volume, return_daily, shares_outstanding, exchange_code, split_ratio, dividend, market_cap).
```

--------------------------------

### Fetch Fundamentals for S&P 500 Constituents

Source: https://xfinlink.com/docs

Retrieves annual revenue and net income for all S&P 500 constituents. It handles fetching data in batches of 100 tickers due to API limits and concatenates the results.

```python
import xfinlink as xfl
xfl.set_api_key("YOUR_API_KEY")

sp = xfl.index("sp500")
tickers = sp["ticker"].dropna().tolist()

# fundamentals: max 100 tickers per call
# prices: max 100 tickers per call
# metrics: max 100 tickers per call
import pandas as pd
frames = []
for i in range(0, len(tickers), 100):
    batch = tickers[i:i+100]
    df = xfl.fundamentals(batch, period_type="annual", fields=["revenue", "net_income"], period="1y")
    frames.append(df)
result = pd.concat(frames, ignore_index=True)
print(result.sort_values("revenue", ascending=False).head(20))
```

--------------------------------

### /v1/fundamentals/{ticker}

Source: https://xfinlink.com/docs

Fetches reported financial statements including income statement, balance sheet, and cash flow data for US companies. Supports filtering by period type, specific fields, and inclusion of segment data.

```APIDOC
## GET /v1/fundamentals/{ticker}

### Description
Reported financials — income statement, balance sheet, cash flow — back to 1950 for most listed US companies.

### Method
GET

### Endpoint
/v1/fundamentals/{ticker}

### Parameters
#### Path Parameters
- **ticker** (str | list[str]) - Required - Ticker(s) to fetch.

#### Query Parameters
- **period_type** (str) - Optional - "annual" | "quarterly" | "all". Defaults to "all".
- **fields** (list[str]) - Optional - Subset of 148 available fields.
- **include** (str) - Optional - "segments" — adds revenue breakdowns by geography, product, and business segment.
- **segment_members** (str) - Optional - "primary" or "all". Primary returns segments summing to revenue; all includes subtotals. Defaults to "primary".
- **start** (str (ISO date)) - Optional - Earliest period_end.
- **end** (str (ISO date)) - Optional - Latest period_end.

### Request Example
```python
import xfinlink as xfl
df = xfl.fundamentals("AAPL", period_type="annual", fields=["revenue", "net_income"])
# With revenue segments
df = xfl.fundamentals("AAPL", include_segments=True)
```
```

--------------------------------

### xfl.fundamentals

Source: https://xfinlink.com/docs

Retrieves financial statement data including income, balance sheet, and cash flow. Supports filtering by period type, version, and specific fields.

```APIDOC
## xfl.fundamentals

### Description
Retrieves financial statement data including income, balance sheet, and cash flow. Supports filtering by period type, version, and specific fields. Max 100 tickers per call.

### Method
`xfl.fundamentals`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **ticker** (str | list[str] | tuple) - Required - The stock ticker symbol(s).
- **start** (str | date | None) - Optional - The start date for the data. Defaults to 1 year ago.
- **end** (str | date | None) - Optional - The end date for the data.
- **period** (str | None) - Optional - The number of periods to retrieve (e.g., "5y").
- **period_type** (str) - Optional - Type of period to retrieve ("annual", "quarterly", or "all"). Defaults to "all".
- **version** (str) - Optional - Version of the financial statement ("restated", "original", or "all"). Defaults to "restated".
- **fields** (list[str] | str | None) - Optional - Specific financial fields to retrieve.
- **include_segments** (bool) - Optional - Whether to include revenue segment breakdowns. Defaults to False.
- **limit** (int) - Optional - Maximum number of rows to return. Defaults to 5000.
- **max_rows** (int) - Optional - Maximum total rows allowed. Defaults to 10000.

### Request Example
```python
df = xfl.fundamentals("AAPL", period_type="annual", period="5y")
df = xfl.fundamentals("AAPL", period_type="quarterly", fields=["revenue", "net_income", "eps_diluted"])
df = xfl.fundamentals("AAPL", include_segments=True, period_type="annual")
```

### Response
Returns a pandas DataFrame containing financial statement data. Columns include structural data (entity_id, ticker, entity_name, gics_sector, period_end, period_type, fiscal_year, fiscal_period, filing_date, version, source) and selectable financial fields. If include_segments is True, additional segment data is included.
```

--------------------------------

### Fetch Historical Prices for a Single Ticker

Source: https://xfinlink.com/docs

Retrieves historical OHLCV data for a specified ticker within a date range. Defaults to daily intervals and includes split adjustments.

```python
df = xfl.prices("AAPL", start="2025-01-01", end="2025-06-30")
```

--------------------------------

### Calculate AAPL Cumulative Return

Source: https://xfinlink.com/docs

Retrieves daily prices for AAPL and calculates the cumulative total return for a specified period. This is ideal for backtesting and performance analysis.

```python
import xfinlink as xfl

df = xfl.prices("AAPL", start="2024-01-01", end="2024-12-31")
df["cumulative_return"] = (1 + df["return_daily"]).cumprod() - 1
print(f"AAPL 2024 total return: {df['cumulative_return'].iloc[-1]:.1%}")
```

--------------------------------

### /v1/index/{index_name}

Source: https://xfinlink.com/docs

Retrieves current and historical constituents for specified stock market indices. Supports filtering by index name and point-in-time membership.

```APIDOC
## GET /v1/index/{index_name}

### Description
Retrieves current and historical index constituents for supported indices.

### Method
GET

### Endpoint
/v1/index/{index_name}

### Parameters
#### Path Parameters
- **index_name** (str) - Required - Index name (e.g., `sp500`, `ndx100`, `djia`, `russell2000`).

#### Query Parameters
- **as_of** (str) - Optional (default: `today`) - Point-in-time membership date in ISO format.
- **limit** (int) - Optional (default: 500) - Results per page (max 1000).
- **offset** (int) - Optional (default: 0) - Pagination offset.

### Request Example
```python
df = xfl.index("sp500")
df = xfl.index("sp500", as_of="2020-01-01")
```
```

--------------------------------

### Search for Entities

Source: https://xfinlink.com/docs

Searches for companies or entities based on various criteria like name, GICS sector, entity type, SIC, NAICS, or country. Supports pagination with limit and offset. Maximum limit is 500.

```python
df = xfl.search(q="apple")
```

```python
df = xfl.search(gics_sector="Energy", limit=100)
```

```python
df = xfl.search(entity_type="etf")
```

--------------------------------

### Resolve Company Information by Ticker

Source: https://xfinlink.com/docs

Retrieves detailed entity information for one or more tickers, including classifications and index membership. Handles up to 100 tickers per call.

```python
info = xfl.resolve("GM")
entities = info["data"]["GM"]["entities"]
info = xfl.resolve("AAPL", include=["classifications"])
```

--------------------------------

### xfl.index

Source: https://xfinlink.com/docs

Retrieves constituents of a specified index, either current or historical. Supports indices like S&P 500, NASDAQ 100, DJIA, and Russell 2000.

```APIDOC
## xfl.index(index_name, as_of, limit, offset)

### Description
Index constituents, current or historical. Available indices: "sp500", "ndx100", "djia", "russell2000". Max limit: 1000.

### Method
Not applicable (Python function)

### Parameters
#### Path Parameters
None

#### Query Parameters
- **index_name** (str) - Optional - The name of the index. Defaults to "sp500". Available: "sp500", "ndx100", "djia", "russell2000".
- **as_of** (str | date | None) - Optional - Retrieves constituents as of a specific date.
- **limit** (int) - Optional - Maximum number of results to return. Defaults to 500. Max limit: 1000.
- **offset** (int) - Optional - Number of results to skip. Defaults to 0.

### Request Example
```python
df = xfl.index("sp500")
df = xfl.index("ndx100", as_of="2020-01-01")
```

### Response
#### Success Response
Returns a pandas DataFrame with the following columns:
- `entity_id`
- `ticker`
- `entity_name`
- `added_date`
- `removed_date`

#### Response Example
```python
# Example DataFrame output for S&P 500 constituents
#   entity_id ticker entity_name added_date removed_date
# 0   id456    MSFT  Microsoft Corp 1994-01-31         None
# 1   id789    GOOG  Alphabet Inc.  2014-04-01         None
```
```

--------------------------------

### Compute Dividend-Adjusted Close Price

Source: https://xfinlink.com/docs

Calculates the dividend-adjusted closing price using split-adjusted close and daily returns. This is useful for accurate historical performance analysis when dividends are involved.

```python
import xfinlink as xfl

df = xfl.prices("AAPL", start="2020-01-01", fields=["adj_close", "return_daily"])

# Build cumulative total return index
df["total_return_index"] = (1 + df["return_daily"]).cumprod()

# Derive dividend-adjusted price series
df["div_adj_close"] = df["adj_close"].iloc[-1] * df["total_return_index"] / df["total_return_index"].iloc[-1]
```

--------------------------------

### xfl.resolve

Source: https://xfinlink.com/docs

Resolves tickers to show companies that have used them, including validity dates. Supports up to 100 tickers per call and can include detailed entity information.

```APIDOC
## xfl.resolve(ticker, include)

### Description
Entity resolution. Shows every company that has used a ticker, with validity dates. Max 100 tickers per call.

### Method
Not applicable (Python function)

### Parameters
#### Path Parameters
None

#### Query Parameters
- **ticker** (str | list[str] | tuple) - Required - The ticker symbol or a list/tuple of ticker symbols to resolve.
- **include** (list[str] | None) - Optional - Specifies additional details to include, such as `["index","classifications"]`. If None, all details are included.

### Request Example
```python
info = xfl.resolve("GM")
entities = info["data"]["GM"]["entities"]
info = xfl.resolve("AAPL", include=["classifications"])
```

### Response
#### Success Response
Returns a dictionary containing:
- `data`: Contains resolved entity information keyed by ticker.
  - `TICKER`: Object containing entity details.
    - `entities`: List of entities associated with the ticker, each with fields like `entity_id`, `name`, `entity_type`, `country`, `figi`, `cik`, `ticker_valid_from`, `ticker_valid_to`.
      - `classifications`: Object with `sic_code`, `naics_code`, `gics_sector`, `gics_group`, `gics_industry`, `gics_subindustry`.
      - `index_membership`: List of index memberships with `index`, `added`, `removed` dates.
- `meta`: Metadata including `tickers_requested`, `tickers_resolved`, `tickers_unresolved`, and `include` parameters used.

#### Response Example
```json
{
  "data": {
    "GM": {
      "entities": [
        {
          "entity_id": "some_id",
          "name": "General Motors Company",
          "entity_type": "company",
          "country": "US",
          "figi": "BBG000B9XRY4",
          "cik": "0000320193",
          "ticker_valid_from": "1970-01-01",
          "ticker_valid_to": null,
          "classifications": {
            "sic_code": "3711",
            "naics_code": "336111",
            "gics_sector": "Consumer Discretionary",
            "gics_group": "Automobiles & Components",
            "gics_industry": "Automobiles",
            "gics_subindustry": "Automobiles"
          },
          "index_membership": [
            {
              "index": "S&P 500",
              "added": "1970-01-01",
              "removed": null
            }
          ]
        }
      ]
    }
  },
  "meta": {
    "tickers_requested": 1,
    "tickers_resolved": 1,
    "tickers_unresolved": [],
    "include": ["index", "classifications"]
  }
}
```
```

--------------------------------

### Python Search by GICS Sector

Source: https://xfinlink.com/docs

Search for financial entities filtered by their GICS sector.

```python
df = xfl.search(gics_sector="Consumer Staples")
```

--------------------------------

### xfl.search

Source: https://xfinlink.com/docs

Searches for financial entities based on various criteria including keywords, GICS sector, entity type, SIC, NAICS, and country. Returns results as a pandas DataFrame.

```APIDOC
## xfl.search(q, gics_sector, entity_type, sic, naics, country, limit, offset)

### Description
Search for entities. Max limit: 500.

### Method
Not applicable (Python function)

### Parameters
#### Path Parameters
None

#### Query Parameters
- **q** (str | None) - Optional - A query string to search for entities.
- **gics_sector** (str | None) - Optional - Filter by GICS sector.
- **entity_type** (str | None) - Optional - Filter by entity type (e.g., "etf").
- **sic** (str | None) - Optional - Filter by SIC code.
- **naics** (str | None) - Optional - Filter by NAICS code.
- **country** (str) - Optional - Filter by country. Defaults to "US".
- **limit** (int) - Optional - Maximum number of results to return. Defaults to 50. Max limit: 500.
- **offset** (int) - Optional - Number of results to skip. Defaults to 0.

### Request Example
```python
df = xfl.search(q="apple")
df = xfl.search(gics_sector="Energy", limit=100)
df = xfl.search(entity_type="etf")
```

### Response
#### Success Response
Returns a pandas DataFrame with the following columns:
- `entity_id`
- `ticker`
- `entity_name`
- `entity_type`
- `gics_sector`
- `gics_sub_industry`
- `sic`
- `naics`
- `country`

#### Response Example
```python
# Example DataFrame output
#   entity_id ticker entity_name entity_type gics_sector gics_sub_industry   sic   naics country
# 0   id123    AAPL  Apple Inc.     company  Technology        Software  3571  541511      US
```
```

--------------------------------

### /v1/insiders/{ticker} Pro

Source: https://xfinlink.com/docs

Fetches insider transaction data from SEC filings for specified tickers. Supports filtering by transaction type, date range, insider role, and more. This endpoint is part of the Pro tier.

```APIDOC
## GET /v1/insiders/{ticker} Pro

### Description
Retrieves insider transactions from SEC Form 3, 4, and 5 filings. Coverage is from 1996 to present. This endpoint requires a Pro tier subscription.

### Method
GET

### Endpoint
/v1/insiders/{ticker}

### Parameters
#### Path Parameters
- **ticker** (str) - Required - Ticker or comma-separated tickers (up to 100).

#### Query Parameters
- **start** (str) - Optional (default: `1y ago`) - Earliest transaction_date in ISO format.
- **end** (str) - Optional - Latest transaction_date in ISO format.
- **transaction_type** (str) - Optional - Decoded type, e.g., `open_market_buy`, `open_market_sell`, `grant_or_award`, `option_exercise`, `tax_withholding`, `gift`. Can be comma-separated for multiple types.
- **acquisition_or_disposition** (str) - Optional - Filter by `A` (Acquisition) or `D` (Disposition).
- **ownership_type** (str) - Optional - Filter by `direct` or `indirect` ownership.
- **form_type** (str) - Optional - Filter by form type: `3`, `4`, `5` (or amended forms like `4/A`).
- **insider_role** (str) - Optional - Substring match on the insider's role (e.g., `CEO`, `CFO`, `Director`).
- **insider_name** (str) - Optional - Substring match on the insider's name.
- **min_value** (num) - Optional - Minimum transaction value in dollars.
- **include_amendments** (bool) - Optional (default: `false`) - Whether to include amendment rows.
- **limit** (int) - Optional (default: 1000) - Rows per page (max 5000).

### Fields Returned
`entity_id`, `ticker`, `entity_name`, `transaction_date`, `filing_date`, `form_type`, `insider_name`, `insider_role`, `transaction_code`, `transaction_type`, `acquisition_or_disposition`, `shares`, `shares_held_after`, `transaction_price`, `transaction_value`, `ownership_type`, `is_amendment`, `document_id`.

### Request Example
```python
df = xfl.insiders("TSLA", transaction_type="open_market_sell", insider_role="CEO")
```
```

--------------------------------

### Resolve Entity and Ticker History for GM

Source: https://xfinlink.com/docs

Resolves the entity 'GM' to find historical ticker information, including validity periods. This is useful for understanding corporate actions like bankruptcies and ticker changes.

```python
import xfinlink as xfl

info = xfl.resolve("GM")
for entity in info["data"]["GM"]["entities"]:
    print(f"{entity['name']}: {entity['ticker_valid_from']} → {entity['ticker_valid_to']}")
# General Motors Corporation (pre-2009 bankruptcy): 1962-07-02 → 2009-06-01
# General Motors Company: None → None (current)
```
Tokens:
Raw