xfinlink Examples

https://github.com/xfinlink/xfinlink-examples
Admin
Working Python examples for financial data analysis using xfinlink, a free financial data API for US...
Tokens:59,338
Snippets:408
Trust Score:2.9
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install xfinlink Python Package

Source: https://github.com/xfinlink/xfinlink-examples/blob/main/README.md

Install the xfinlink Python package using pip. This is the first step to using the library for financial data analysis.

```bash
pip install xfinlink
```

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

### Fetch and Process Daily Stock Prices

Source: https://github.com/xfinlink/xfinlink-examples/blob/main/blog/aapl-vs-xom-seasonality-python.md

Fetches daily closing prices and returns for specified tickers using xfinlink and processes them into monthly returns. Requires API key setup and pandas for data manipulation.

```python
import pandas as pd
import xfinlink as xfl

xfl.api_key = "YOUR_API_KEY"  # free at https://xfinlink.com/signup

tickers = ["AAPL", "XOM"]

prices = xfl.prices(
    tickers,
    start="2021-01-01",
    end="2025-12-31",
    fields=["close", "return_daily"],
)

for ticker in tickers:
    df = prices[prices["ticker"] == ticker].copy()
    df["date"] = pd.to_datetime(df["date"])
    df = df.sort_values("date").reset_index(drop=True)

    df["year"] = df["date"].dt.year
    df["month"] = df["date"].dt.month

    monthly = (
        df.groupby(["year", "month"])["return_daily"]
        .apply(lambda x: (1 + x).prod() - 1)
        .reset_index()
    )
    monthly.columns = ["year", "month", "monthly_return"]

    monthly = monthly[monthly["year"].between(2021, 2025)]

    print(f"=== {ticker} Monthly Seasonality (2021-2025, 5 complete years) ===")

    month_names = [
        "Jan", "Feb", "Mar", "Apr", "May", "Jun",
        "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
    ]

    for m in range(1, 13):
        subset = monthly[monthly["month"] == m]
        avg_ret = subset["monthly_return"].mean()
        win_rate = (subset["monthly_return"] > 0).mean()
        n = len(subset)

        bar_len = int(abs(avg_ret) * 200)
        bar = ("+" if avg_ret >= 0 else "-") * bar_len

        print(
            f"  {month_names[m-1]}  avg={avg_ret:+5.1%}"
            f"  wins={win_rate:.0%}"
            f"  n={n}"
            f"  {bar}"
        )

    print()

```

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

### Calculate and Compare Sector Sharpe and Sortino Ratios

Source: https://github.com/xfinlink/xfinlink-examples/blob/main/blog/sector-sharpe-sortino-python.md

This script fetches historical price data for sector ETFs, calculates Sharpe and Sortino ratios, and prints a ranked comparison. Ensure you have the xfinlink library installed and your API key configured.

```python
import numpy as np
import xfinlink as xfl

xfl.api_key = "YOUR_API_KEY"  # free at https://xfinlink.com/signup

sectors = {
    "XLK": "Technology",
    "XLE": "Energy",
    "XLI": "Industrials",
    "XLU": "Utilities",
    "XLV": "Healthcare",
    "XLY": "ConsDisc",
    "XLP": "ConsStaples",
    "XLF": "Financials",
}
tickers = list(sectors.keys())
rf_annual = 0.05
rf_daily = rf_annual / 252

prices = xfl.prices(tickers, period="1y", fields=["close", "return_daily"])

print(f"=== Sector Risk-Adjusted Returns: Sharpe & Sortino (1Y, Rf={int(rf_annual*100)}%) ===")
print()

results = []

for ticker in tickers:
    df = prices[prices["ticker"] == ticker].sort_values("date").copy()
    df = df.dropna(subset=["close", "return_daily"])

    returns = df["return_daily"].values
    close = df["close"].values

    total_return = close[-1] / close[0] - 1

    vol = np.std(returns, ddof=1) * np.sqrt(252)

    sharpe = (total_return - rf_annual) / vol

    excess_returns = returns - rf_daily
    downside = excess_returns[excess_returns < 0]
    downside_dev = np.sqrt(np.mean(downside ** 2)) * np.sqrt(252)
    sortino = (total_return - rf_annual) / downside_dev

    cummax = np.maximum.accumulate(close)
    drawdowns = close / cummax - 1
    max_dd = drawdowns.min()

    results.append((sectors[ticker], ticker, total_return, vol, sharpe, sortino, max_dd))

results.sort(key=lambda x: x[4], reverse=True)

for name, ticker, ret, vol, sharpe, sortino, max_dd in results:
    print(
        f"  {name:<15}({ticker})  "
        f"return={ret:+5.1%}  "
        f"vol={vol:4.1%}  "
        f"sharpe={sharpe:+5.2f}  "
        f"sortino={sortino:+5.2f}  "
        f"maxDD={max_dd:5.1%}"
    )

```

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

### Compare Profitability Across Mega-Cap Tech Stocks

Source: https://github.com/xfinlink/xfinlink-examples/blob/main/blog/mega-cap-tech-profitability-python.md

Fetches annual profitability and capital efficiency metrics for specified tickers. Requires setting an API key and installs the xfinlink library.

```python
import xfinlink as xfl
import pandas as pd

xfl.set_api_key("your_key")  # free at https://xfinlink.com/signup

# Compare profitability across mega-cap tech
tickers = ["AAPL", "MSFT", "GOOGL", "META", "AMZN", "NVDA"]

metrics = xfl.metrics(tickers, period_type="annual",
                      fields=["gross_margin", "operating_margin", "net_margin", "roe", "roa", "roic"],
                      period="3y")

# Keep most recent per ticker
latest = metrics.sort_values("period_end").groupby("ticker").tail(1)
latest = latest.sort_values("net_margin", ascending=False)

print("=== Mega-Cap Tech Profitability (Most Recent Annual) ===")
cols = ["ticker", "entity_name", "period_end", "gross_margin", "operating_margin", "net_margin", "roe", "roa"]
print(latest[cols].to_string(index=False))
print()

# Who's most capital-efficient? ROIC ranking
roic_rank = latest.sort_values("roic", ascending=False)
print("=== Return on Invested Capital (ROIC) Ranking ===")
print(roic_rank[["ticker", "entity_name", "roic"]].to_string(index=False))
print()

# Margin spread: gross - net = how much gets eaten by OpEx + taxes
latest_copy = latest.copy()
latest_copy["margin_spread"] = latest_copy["gross_margin"] - latest_copy["net_margin"]
spread = latest_copy.sort_values("margin_spread")
print("=== Margin Efficiency (Gross - Net = overhead eaten) ===")
for _, row in spread.iterrows():
    print(f"  {row['ticker']:5s}  gross={row['gross_margin']:.1%}  net={row['net_margin']:.1%}  overhead={row['margin_spread']:.1%}")

```

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

### Fetch and Screen S&P 500 Stocks by P/E Ratio

Source: https://github.com/xfinlink/xfinlink-examples/blob/main/blog/sp500-pe-ratio-screening-python.md

This Python script fetches valuation metrics (P/E, P/B, earnings yield) for a list of 30 blue-chip S&P 500 stocks. It filters out companies with negative or missing P/E ratios and then identifies the top 10 cheapest and most expensive stocks based on their P/E ratio. It also prints summary statistics for the P/E ratios across the selected universe. Ensure you have the xfinlink library installed and an API key set.

```python
import xfinlink as xfl
import pandas as pd

xfl.set_api_key("your_key")  # free at https://xfinlink.com/signup

# 30 blue-chip S&P 500 stocks across all 11 GICS sectors
tickers = [
    "AAPL", "MSFT", "NVDA", "GOOGL", "AMZN",  # Tech / Comm / Consumer
    "JPM", "BAC", "GS", "BRK.B", "V",          # Financials
    "UNH", "JNJ", "PFE", "LLY", "ABBV",        # Healthcare
    "XOM", "CVX", "COP",                        # Energy
    "PG", "KO", "PEP", "WMT", "COST",          # Consumer Staples / Disc
    "CAT", "HON", "UPS",                        # Industrials
    "NEE", "DUK",                               # Utilities
    "AMT", "PLD",                               # Real Estate
]

# Fetch valuation metrics — latest annual period for each
metrics = xfl.metrics(tickers, period_type="annual",
                      fields=["pe_ratio", "pb_ratio", "earnings_yield", "dividend_yield"],
                      period="3y")

# Keep only the most recent period per ticker
metrics = metrics.sort_values("period_end").groupby("ticker").tail(1)

# Drop rows where PE is missing or negative (unprofitable)
valid = metrics.dropna(subset=["pe_ratio"])
valid = valid[valid["pe_ratio"] > 0].copy()

# Top 10 cheapest by P/E
cheapest = valid.nsmallest(10, "pe_ratio")[["ticker", "entity_name", "period_end", "pe_ratio", "pb_ratio", "earnings_yield"]]
print("=== 10 Cheapest Blue Chips by P/E Ratio ===")
print(cheapest.to_string(index=False))
print()

# Top 10 most expensive by P/E
expensive = valid.nlargest(10, "pe_ratio")[["ticker", "entity_name", "period_end", "pe_ratio", "pb_ratio", "earnings_yield"]]
print("=== 10 Most Expensive Blue Chips by P/E Ratio ===")
print(expensive.to_string(index=False))
print()

# Summary stats
print("=== P/E Summary (30 Blue Chips) ===")
print(f"Median P/E: {valid['pe_ratio'].median():.1f}")
print(f"Mean P/E:   {valid['pe_ratio'].mean():.1f}")
print(f"Min P/E:    {valid['pe_ratio'].min():.1f} ({valid.loc[valid['pe_ratio'].idxmin(), 'ticker']})")
print(f"Max P/E:    {valid['pe_ratio'].max():.1f} ({valid.loc[valid['pe_ratio'].idxmax(), 'ticker']})")
```

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

### Perform ADF Test on Stock Prices and Returns

Source: https://github.com/xfinlink/xfinlink-examples/blob/main/blog/adf-mean-reversion-test-python.md

This snippet fetches historical stock data and performs the Augmented Dickey-Fuller test on both closing prices and daily returns for a list of tickers. It prints whether each series is stationary or has a unit root based on a p-value threshold of 0.05. Ensure you have set your API key and installed the necessary libraries (xfinlink, pandas, statsmodels).

```python
import xfinlink as xfl
import pandas as pd
from statsmodels.tsa.stattools import adfuller

xfl.set_api_key("YOUR_API_KEY")  # free at https://xfinlink.com/signup

tickers = ["AAPL", "MSFT", "XOM", "JNJ", "NVDA", "PG"]
df = xfl.prices(tickers, period="1y", fields=["close", "return_daily"])

for ticker in tickers:
    t = df[df["ticker"] == ticker].sort_values("date")

    adf_price = adfuller(t["close"].dropna(), autolag="AIC")
    adf_return = adfuller(t["return_daily"].dropna(), autolag="AIC")

    price_tag = "STATIONARY" if adf_price[1] < 0.05 else "UNIT ROOT"
    return_tag = "STATIONARY" if adf_return[1] < 0.05 else "UNIT ROOT"

    print(f"{ticker}: price p={adf_price[1]:.4f} ({price_tag})  "
          f"return p={adf_return[1]:.4f} ({return_tag})")
```

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

### Initialize xfinlink and Fetch AAPL Prices

Source: https://github.com/xfinlink/xfinlink-examples/blob/main/README.md

Initialize the xfinlink API with your key and fetch historical daily prices for AAPL. This snippet demonstrates basic API usage and data retrieval.

```python
import xfinlink as xfl
xfl.set_api_key("your_key")  # free at https://xfinlink.com/signup

df = xfl.prices("AAPL", period="1y")
print(df[["date", "close", "volume"]].head())
```

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

### Fetch and Analyze Stock Revenue Growth with Python

Source: https://github.com/xfinlink/xfinlink-examples/blob/main/blog/revenue-growth-screening-python.md

This script retrieves annual revenue and net income data for a list of tech stocks, calculates year-over-year growth rates, and ranks them. It requires the xfinlink library and a valid API key. The output displays the revenue growth ranking and identifies 'growth traps'.

```python
import xfinlink as xfl
import pandas as pd

xfl.set_api_key("your_key")  # free at https://xfinlink.com/signup

# 10 large-cap tech/growth stocks
tickers = [
    "AAPL", "MSFT", "NVDA", "GOOGL", "AMZN", "META",
    "CRM", "ADBE", "NOW", "PLTR",
]

# Get revenue and net income for the last 3 annual periods
fund = xfl.fundamentals(tickers, period_type="annual", fields=["revenue", "net_income"], period="3y")

# Keep the 2 most recent annual periods per ticker to compute YoY growth
recent = fund.sort_values("period_end").groupby("ticker").tail(2)

growth = []
for ticker in recent["ticker"].unique():
    rows = recent[recent["ticker"] == ticker].sort_values("period_end")
    if len(rows) < 2:
        continue
    prev, curr = rows.iloc[0], rows.iloc[1]
    if prev["revenue"] and prev["revenue"] > 0:
        rev_growth = (curr["revenue"] - prev["revenue"]) / prev["revenue"]
    else:
        rev_growth = None
    if prev["net_income"] and prev["net_income"] != 0:
        ni_growth = (curr["net_income"] - prev["net_income"]) / abs(prev["net_income"])
    else:
        ni_growth = None
    growth.append({
        "ticker": ticker,
        "entity_name": curr["entity_name"],
        "revenue": curr["revenue"],
        "rev_growth": rev_growth,
        "ni_growth": ni_growth,
    })

gdf = pd.DataFrame(growth).sort_values("rev_growth", ascending=False)

print("=== Revenue Growth Ranking (YoY, Most Recent Annual) ===")
for _, r in gdf.iterrows():
    rev_m = f"{r['revenue']/1e3:.0f}B" if r["revenue"] else "N/A"
    rg = f"{r['rev_growth']:.1%}" if r["rev_growth"] is not None else "N/A"
    ng = f"{r['ni_growth']:.1%}" if r["ni_growth"] is not None else "N/A"
    print(f"  {r['ticker']:5s}  rev={rev_m:>7s}  rev_growth={rg:>8s}  ni_growth={ng:>8s}")
print()

# Flag: high revenue growth but declining earnings
traps = gdf[(gdf["rev_growth"].notna()) & (gdf["rev_growth"] > 0.05) & (gdf["ni_growth"].notna()) & (gdf["ni_growth"] < 0)]
print("=== Growth Traps: Revenue Up but Earnings Down ===")
if len(traps) > 0:
    for _, r in traps.iterrows():
        print(f"  {r['ticker']}: revenue +{r['rev_growth']:.1%} but net income {r['ni_growth']:.1%}")
else:
    print("  None found — all growers are also earning more")

```

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

### Fetch SaaS Fundamentals and Calculate Growth Metrics

Source: https://github.com/xfinlink/xfinlink-examples/blob/main/blog/saas-revenue-growth-screen-python.md

This Python script uses the xfinlink library to fetch fundamental data for a list of SaaS tickers. It calculates year-over-year revenue growth, determines profitability based on net income, and computes the operating cash flow margin. Use this snippet to screen companies based on growth and cash efficiency.

```python
import xfinlink as xfl

xfl.api_key = "YOUR_API_KEY"  # free at https://xfinlink.com/signup

tickers = ["DDOG", "ZS", "CRWD", "NET", "MDB", "SNOW"]

fundamentals = xfl.fundamentals(
    tickers,
    period="3y",
    fields=["revenue", "net_income", "operating_cash_flow"],
    period_type="annual",
)

print("=== SaaS / Cloud Growth Screen (YoY Revenue Growth) ===")

results = []
for ticker in tickers:
    df = fundamentals[fundamentals["ticker"] == ticker].sort_values("period_end")
    if len(df) < 2:
        continue

    entity_name = df["entity_name"].iloc[-1]
    latest = df.iloc[-1]
    prior = df.iloc[-2]

    revenue = latest["revenue"]
    revenue_prior = prior["revenue"]
    growth = (revenue - revenue_prior) / revenue_prior if revenue_prior else 0

    net_income = latest["net_income"]
    profitable = net_income > 0 if net_income is not None else False

    ocf = latest["operating_cash_flow"]
    ocf_margin = ocf / revenue if revenue and ocf else 0

    results.append({
        "ticker": ticker,
        "entity_name": entity_name,
        "revenue": revenue,
        "growth": growth,
        "profitable": profitable,
        "ocf_margin": ocf_margin,
    })

results.sort(key=lambda x: x["growth"], reverse=True)

for r in results:
    name = r["entity_name"][:22]
    prof = "YES" if r["profitable"] else " NO"
    print(
        f"  {r['ticker']:<6} {name:<22}"
        f"  rev=${r['revenue'] / 1e6:>8,.0f}M"
        f"  growth={r['growth']:5.1%}"
        f"  profitable={prof}"
        f"  OCF_margin={r['ocf_margin']:.1%}"
    )
```

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

### Resolve Ticker Symbol Entities with xfinlink

Source: https://github.com/xfinlink/xfinlink-examples/blob/main/blog/ticker-recycling-dangers-python.md

Iterates through a list of recycled tickers to retrieve and display all entities that have ever used each symbol, including their name, valid date range, and entity ID. Requires API key setup.

```python
import xfinlink as xfl

xfl.set_api_key("your_key")  # free at https://xfinlink.com/signup

# Tickers that have been genuinely recycled between different companies
recycled = ["FB", "DELL", "GM", "TWX"]

print("=== Ticker Recycling: One Symbol, Multiple Companies ===")
print()

for ticker in recycled:
    info = xfl.resolve(ticker)
    entities = info["data"][ticker]["entities"]
    print(f'{ticker} — {len(entities)} entit{"y" if len(entities) == 1 else "ies"}')
    for e in entities:
        valid_from = e.get("ticker_valid_from", "?")
        valid_to = e.get("ticker_valid_to") or "present"
        print(f'  {e["name"]}')
        print(f'    {valid_from} → {valid_to} (entity_id={e["entity_id"]})')
    print()
```

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

### Fetch Fundamentals and Metrics

Source: https://github.com/xfinlink/xfinlink-examples/blob/main/blog/multi-endpoint-dashboard-python.md

Retrieves annual fundamental data (e.g., revenue) and valuation metrics (e.g., PE ratio, ROE) from the most recent filing period for the target stocks. Requires 'xfinlink'.

```python
# Fetch annual fundamentals (e.g., revenue)
fundamentals = xfinlink.fundamentals.annual(symbols=target_stocks)
fundamentals = fundamentals[['ticker', 'revenue']]

# Fetch valuation metrics (e.g., PE ratio, ROE)
metrics = xfinlink.valuation.metrics(symbols=target_stocks)
metrics = metrics[['ticker', 'pe_ratio', 'roe']]

print("Step 4-5: Combined")
```

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

### Screen S&P 500 Stocks by 3-Month Momentum

Source: https://github.com/xfinlink/xfinlink-examples/blob/main/blog/momentum-screening-sp500-python.md

Fetches daily prices for a list of S&P 500 tickers, calculates 6-month, 3-month, and 1-month momentum, and then ranks them by 3-month momentum. Requires the xfinlink library to be installed and an API key set.

```python
import xfinlink as xfl
import pandas as pd

xfl.set_api_key("your_key")  # free at https://xfinlink.com/signup

# Pick 20 large-cap S&P 500 stocks across sectors
tickers = [
    "AAPL", "MSFT", "NVDA", "AMZN", "META",
    "JPM", "V", "UNH", "LLY", "XOM",
    "PG", "COST", "HD", "AVGO", "CRM",
    "NFLX", "ABBV", "MRK", "PEP", "ORCL",
]

# Pull 6 months of daily prices
df = xfl.prices(tickers, period="6mo", fields=["close", "return_daily"])

# Calculate 3-month (63 trading days) and 1-month (21 days) momentum
mom = df.sort_values("date").groupby("ticker").agg(
    last_close=("close", "last"),
    total_return_6mo=("return_daily", lambda x: (1 + x).prod() - 1),
    total_return_3mo=("return_daily", lambda x: (1 + x.tail(63)).prod() - 1),
    total_return_1mo=("return_daily", lambda x: (1 + x.tail(21)).prod() - 1),
).round(4)

# Rank by 3-month momentum
mom = mom.sort_values("total_return_3mo", ascending=False)

print("=== Momentum Ranking (Top 10 by 3-Month Return) ===")
print(mom.head(10).to_string())
print()

print("=== Bottom 5 (Weakest Momentum) ===")
print(mom.tail(5).to_string())
```

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

### Fetch Scoped Price Data with xfinlink

Source: https://github.com/xfinlink/xfinlink-examples/blob/main/blog/ticker-recycling-dangers-python.md

Retrieves historical price data for a specific ticker within a given date range, ensuring data is scoped to the correct entity to avoid the ticker recycling problem. This example fetches 'close' prices for 'FB' in early 2021.

```python
print('=== Safe Pull: FB prices scoped to Meta only (2021-2022) ===')
fb_prices = xfl.prices("FB", start="2021-01-04", end="2021-01-08", fields=["close"])
if len(fb_prices) > 0:
    print(fb_prices[["ticker", "entity_name", "date", "close"]].to_string(index=False))
else:
    print("(No data — FB ticker was Meta in this range, entity resolution applied)")
```

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

### Fetch and Calculate 1-Year Total Returns

Source: https://github.com/xfinlink/xfinlink-examples/blob/main/blog/multi-endpoint-dashboard-python.md

Pulls one year of daily price data for confirmed index members and computes their total returns by compounding daily returns. Requires 'xfinlink' and 'pandas'.

```python
# Fetch one year of daily price data for confirmed members
price_data = xfinlink.price.history(symbols=confirmed_members['ticker'].tolist(), interval='1d', period='1y')

# Calculate 1-year total returns
price_data['daily_return'] = price_data['close'].pct_change()
price_data['cumulative_return'] = (1 + price_data['daily_return']).cumprod()
returns = price_data.groupby('symbol')['cumulative_return'].last() - 1
returns = returns.reset_index(name='1y_return')
print(f"Step 3: {len(price_data)} price rows")
```

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

### GARCH(1,1) Volatility Forecast for Multiple Tickers

Source: https://github.com/xfinlink/xfinlink-examples/blob/main/blog/garch-volatility-forecast-python.md

This script fits a GARCH(1,1) model to daily returns of specified tickers, forecasts next-day volatility, and compares it against historical volatility to classify the current regime. Ensure you have installed the 'arch' and 'xfinlink' libraries and replaced 'YOUR_API_KEY' with your actual API key.

```python
import numpy as np
from arch import arch_model
import xfinlink as xfl

xfl.api_key = "YOUR_API_KEY"  # free at https://xfinlink.com/signup

tickers = ["AAPL", "NVDA", "XOM", "JPM"]
prices = xfl.prices(tickers, period="1y", fields=["close", "return_daily"])

print("=== GARCH(1,1) Volatility Forecast ===")
print("(Fits a GARCH model to daily returns, forecasts next-day volatility)")
print()

for ticker in tickers:
    df = prices[prices["ticker"] == ticker].sort_values("date").copy()
    df = df.dropna(subset=["return_daily"])

    returns_pct = df["return_daily"].values * 100

    model = arch_model(returns_pct, vol="Garch", p=1, q=1, mean="Constant")
    result = model.fit(disp="off")

    omega = result.params["omega"]
    alpha = result.params["alpha[1]"]
    beta = result.params["beta[1]"]
    persistence = alpha + beta

    forecast = result.forecast(horizon=1)
    next_day_var = forecast.variance.iloc[-1, 0]
    next_day_vol_daily = np.sqrt(next_day_var) / 100
    next_day_vol_annual = next_day_vol_daily * np.sqrt(252)

    hist_vol = df["return_daily"].std() * np.sqrt(252)

    if next_day_vol_annual > hist_vol * 1.2:
        regime = "HIGH"
    elif next_day_vol_annual < hist_vol * 0.8:
        regime = "LOW"
    else:
        regime = "NORMAL"

    print(f"  {ticker}:")
    print(f"    GARCH params: omega={omega:.4f}  alpha={alpha:.4f}  beta={beta:.4f}  persistence={persistence:.4f}")
    print(f"    Forecast next-day vol: {next_day_vol_daily*100:.2f}% daily = {next_day_vol_annual*100:.1f}% annualized")
    print(f"    Historical vol:        {hist_vol*100:.1f}% annualized")
    print(f"    Regime: {regime}")
    print()

```

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

### Fetch and Process Financial Data for Inflation Hedge Analysis

Source: https://github.com/xfinlink/xfinlink-examples/blob/main/blog/oil-inflation-hedge-beta-python.md

This script fetches monthly CPI data from FRED and historical stock prices for specified tickers from xfinlink. It then calculates month-over-month percentage changes for CPI and stock returns, preparing the data for regression analysis. Ensure you have valid API keys for both FRED and xfinlink.

```python
import xfinlink as xfl
import pandas as pd
import numpy as np
from fredapi import Fred
from scipy import stats

xfl.api_key = "YOUR_API_KEY"
fred = Fred(api_key="YOUR_FRED_KEY")

# Monthly CPI
cpi = fred.get_series("CPIAUCSL", observation_start="2018-01-01")
cpi_mom = cpi.pct_change().dropna().rename("cpi_change")
cpi_mom.index = cpi_mom.index.to_period("M")

# Monthly stock returns
tickers = ["XOM", "CVX", "COP"]
df = xfl.prices(tickers, start="2018-01-01", fields=["close"])
df["date"] = pd.to_datetime(df["date"])
monthly = df.groupby(["ticker", df["date"].dt.to_period("M")])["close"].last()
returns = monthly.groupby("ticker").pct_change().dropna().rename("ret")
returns = returns.reset_index()
```

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

### Build Simple DCF Valuation Model

Source: https://github.com/xfinlink/xfinlink-examples/blob/main/blog/simple-dcf-valuation-python.md

Fetches financial data and prices, then calculates intrinsic value per share using a 5-year DCF projection and a terminal value. Compares intrinsic value to current market price to determine upside or downside.

```python
import xfinlink as xfl
import pandas as pd

xfl.set_api_key("your_key")  # free at https://xfinlink.com/signup

tickers = ["AAPL", "MSFT", "GOOGL", "AMZN", "META", "NVDA"]

fund = xfl.fundamentals(tickers, period_type="annual",
                        fields=["free_cash_flow", "shares_outstanding", "revenue"], period="3y")
latest = fund.sort_values("period_end").groupby("ticker").tail(1).copy()

prices = xfl.prices(tickers, period="1mo", fields=["close"])
last_prices = prices.sort_values("date").groupby("ticker").tail(1)[["ticker", "close"]].set_index("ticker")

DISCOUNT_RATE = 0.10
GROWTH_RATE = 0.10
TERMINAL_GROWTH = 0.03

results = []
for _, r in latest.iterrows():
    ticker = r["ticker"]
    fcf = r["free_cash_flow"]
    shares = r["shares_outstanding"]
    if pd.isna(fcf) or pd.isna(shares) or shares <= 0 or fcf <= 0:
        continue

    total_pv = 0
    projected_fcf = fcf
    for year in range(1, 6):
        projected_fcf *= (1 + GROWTH_RATE)
        total_pv += projected_fcf / (1 + DISCOUNT_RATE) ** year

    terminal_fcf = projected_fcf * (1 + TERMINAL_GROWTH)
    terminal_value = terminal_fcf / (DISCOUNT_RATE - TERMINAL_GROWTH)
    pv_terminal = terminal_value / (1 + DISCOUNT_RATE) ** 5

    intrinsic = (total_pv + pv_terminal) / shares
    current_price = last_prices.loc[ticker, "close"] if ticker in last_prices.index else None
    upside = (intrinsic / current_price - 1) if current_price else None

    results.append({"ticker": ticker, "fcf_M": fcf, "intrinsic": intrinsic, "price": current_price, "upside": upside})

rdf = pd.DataFrame(results).sort_values("upside", ascending=False)
print("=== Simple DCF Valuation (10% discount, 10% growth, 3% terminal) ===")
print()
for _, r in rdf.iterrows():
    up = f"{r['upside']:>+6.1%}" if r["upside"] else "N/A"
    verdict = "UNDERVALUED" if r["upside"] and r["upside"] > 0.15 else ("OVERVALUED" if r["upside"] and r["upside"] < -0.15 else "FAIR")
    print(f"  {r['ticker']:5s}  FCF=${r['fcf_M']/1e3:.0f}B  intrinsic=${r['intrinsic']:.2f}  price=${r['price']:.2f}  upside={up}  {verdict}")

```

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

### Fetch Sector ETF Returns and Compute Correlation Matrix

Source: https://github.com/xfinlink/xfinlink-examples/blob/main/blog/sector-correlation-matrix-python.md

Fetches one year of daily returns for eight major SPDR sector ETFs, pivots the data, renames columns for clarity, and computes the Pearson correlation matrix. Requires the xfinlink library and an API key.

```python
import itertools
import xfinlink as xfl

xfl.api_key = "YOUR_API_KEY"  # free at https://xfinlink.com/signup

tickers = ["XLK", "XLF", "XLV", "XLE", "XLY", "XLP", "XLI", "XLU"]

sector_labels = {
    "XLK": "Tech",
    "XLF": "Financials",
    "XLV": "Healthcare",
    "XLE": "Energy",
    "XLY": "ConsDisc",
    "XLP": "ConsStaples",
    "XLI": "Industrials",
    "XLU": "Utilities",
}

prices = xfl.prices(tickers, period="1y", fields=["return_daily"])

pivot = prices.pivot_table(index="date", columns="ticker", values="return_daily")
pivot = pivot.rename(columns=sector_labels)

col_order = ["Energy", "Financials", "Industrials", "Tech",
             "ConsStaples", "Utilities", "Healthcare", "ConsDisc"]
pivot = pivot[col_order]

corr = pivot.corr()

print("=== Sector Correlation Matrix (1Y Daily Returns) ===")
header = "             " + "  ".join(f"{c:>11}" for c in col_order)
print(header)

for row_label in col_order:
    values = "  ".join(f"{corr.loc[row_label, c]:11.3f}" for c in col_order)
    print(f"{row_label:<13}{values}")

pairs = []
for a, b in itertools.combinations(col_order, 2):
    pairs.append((a, b, corr.loc[a, b]))

pairs.sort(key=lambda x: x[2])

print("\nMost correlated pairs:")
for a, b, c in pairs[-3:]:
    print(f"  {a} ↔ {b}: {c:.3f}")

print("\nLeast correlated pairs (best diversifiers):")
for a, b, c in pairs[:3]:
    print(f"  {a} ↔ {b}: {c:.3f}")

```

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

### Fit 2-State Gaussian HMM to XLE Daily Returns

Source: https://github.com/xfinlink/xfinlink-examples/blob/main/blog/oil-hmm-regime-detection-python.md

This snippet demonstrates fitting a 2-state Gaussian Hidden Markov Model to daily returns of the XLE ETF. It requires the xfinlink, pandas, numpy, and hmmlearn libraries. Ensure your API key is set.

```python
import xfinlink as xfl
import pandas as pd
import numpy as np
from hmmlearn.hmm import GaussianHMM

xfl.api_key = "YOUR_API_KEY"

# XLE daily returns
df = xfl.prices("XLE", period="5y", fields=["close", "return_daily"])
df = df.sort_values("date").dropna(subset=["return_daily"])
returns = df["return_daily"].values.reshape(-1, 1)

# Fit 2-state Gaussian HMM
model = GaussianHMM(n_components=2, covariance_type="full", n_iter=200, random_state=42)
model.fit(returns)
states = model.predict(returns)

# Identify calm vs crisis by volatility
vols = [np.sqrt(model.covars_[i][0, 0]) for i in range(2)]
calm_idx = np.argmin(vols)
crisis_idx = np.argmax(vols)

for label, idx in [("CALM", calm_idx), ("CRISIS", crisis_idx)]:
    mu = model.means_[idx][0] * 100
    vol = vols[idx] * 100
    ann_vol = vol * np.sqrt(252)
    print(f"State ({label}): mean={mu:+.3f}%/day  vol={vol:.3f}%/day  ann_vol={ann_vol:.1f}%")

print(f"\nTransition: CALM->CALM={model.transmat_[calm_idx, calm_idx]:.3f}  "
      f"CRISIS->CALM={model.transmat_[crisis_idx, calm_idx]:.3f}")
```

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

### Screen Dividend Stocks by Yield and Quality

Source: https://github.com/xfinlink/xfinlink-examples/blob/main/blog/dividend-yield-screening-python.md

Fetches dividend yield, P/E ratio, and ROE for a list of tickers, then applies quality filters. Requires the xfinlink library and an API key.

```python
import xfinlink as xfl
import pandas as pd

xfl.set_api_key("your_key")  # free at https://xfinlink.com/signup

# Dividend aristocrats and other well-known dividend payers
tickers = [
    "JNJ", "PG", "KO", "PEP", "MCD",
    "MMM", "T", "VZ", "XOM", "CVX",
    "ABBV", "IBM", "HD", "WMT", "LOW",
]

# Get dividend yield and payout metrics
metrics = xfl.metrics(tickers, period_type="annual",
                      fields=["dividend_yield", "pe_ratio", "roe", "fcf_per_share", "earnings_yield"],
                      period="3y")

# Keep most recent period per ticker
latest = metrics.sort_values("period_end").groupby("ticker").tail(1)
latest = latest.dropna(subset=["dividend_yield"])
latest = latest.sort_values("dividend_yield", ascending=False)

print("=== Dividend Yield Ranking (Annual, Most Recent) ===")
cols = ["ticker", "entity_name", "period_end", "dividend_yield", "pe_ratio", "roe"]
print(latest[cols].to_string(index=False))
print()

# Calculate a simple quality score: yield > 2%, PE < 25, ROE > 15%
quality = latest[
    (latest["dividend_yield"] > 0.02) &
    (latest["pe_ratio"] > 0) &
    (latest["pe_ratio"] < 25) &
    (latest["roe"] > 0.15)
].copy()
print("=== Quality Dividend Stocks (yield>2%, PE<25, ROE>15%) ===")
print(quality[cols].to_string(index=False) if len(quality) > 0 else "None found")

```

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

### Fetch and Prepare Food CPI and Grain Returns Data

Source: https://github.com/xfinlink/xfinlink-examples/blob/main/blog/granger-grains-food-cpi-python.md

This snippet fetches monthly Food CPI data from FRED and monthly returns for the DBA commodity ETF from xfinlink. It then calculates the percentage change for both series and merges them into a single DataFrame, ensuring inner join to keep only common dates and dropping any resulting NaN values. This prepares the data for Granger causality testing.

```python
import xfinlink as xfl
import pandas as pd
import numpy as np
from fredapi import Fred
from statsmodels.tsa.stattools import grangercausalitytests

xfl.api_key = "YOUR_API_KEY"
fred = Fred(api_key="YOUR_FRED_KEY")

# Food CPI from FRED
food_cpi = fred.get_series("CPIUFDSL", observation_start="2015-01-01")
food_mom = food_cpi.pct_change().dropna().rename("food_cpi")
food_mom.index = food_mom.index.to_period("M")

# DBA monthly returns from xfinlink
df = xfl.prices("DBA", start="2015-01-01", fields=["close"])
df["date"] = pd.to_datetime(df["date"])
monthly = df.groupby(df["date"].dt.to_period("M"))["close"].last()
grain_ret = monthly.pct_change().dropna().rename("grain_ret")

merged = pd.concat([food_mom, grain_ret], axis=1, join="inner").dropna()
```
Tokens:
Raw