marketmyna 0.2.0__py3-none-any.whl

marketmyna/services/ownership.py

@@ -0,0 +1,143 @@
+"""Who owns a stock and who is trading it: insider / institution split, top
+holders, recent insider buys and sells, and short interest (US).
+
+Source: Yahoo (via yfinance), which mirrors SEC Form 4 / 13F / FINRA short
+interest for US listings and exchange disclosures, more sparsely, elsewhere.
+Covers OpenBB's equity.ownership and equity.shorts endpoints (Apache 2.0).
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+import threading
+import time
+from datetime import date, datetime, timedelta
+from typing import Optional
+
+import pandas as pd
+
+from ..core.numbers import finite as _f
+
+logger = logging.getLogger(__name__)
+
+CACHE_SECONDS = 6 * 3600
+INSIDER_DAYS = 180
+
+_cache: dict[str, tuple[float, dict]] = {}
+_lock = threading.Lock()
+
+
+def _day(v) -> Optional[str]:
+    if v is None or (isinstance(v, float) and math.isnan(v)):
+        return None
+    if isinstance(v, (int, float)):
+        return datetime.fromtimestamp(v).date().isoformat()
+    try:
+        return pd.Timestamp(v).date().isoformat()
+    except (ValueError, TypeError):
+        return None
+
+
+def classify(text: str, transaction: str = "") -> str:
+    """buy | sell | other, from Yahoo's free-text insider row."""
+    t = f"{transaction} {text}".lower()
+    if "sale" in t or "sell" in t or "sold" in t:
+        return "sell"
+    if "purchase" in t or "buy" in t or "bought" in t:
+        return "buy"
+    return "other"
+
+
+def _holders(df) -> list[dict]:
+    if df is None or getattr(df, "empty", True):
+        return []
+    out = []
+    for _, r in df.head(10).iterrows():
+        out.append({"holder": str(r.get("Holder")), "pct_held": _f(r.get("pctHeld")), "shares": _f(r.get("Shares")),
+                    "value": _f(r.get("Value")), "pct_change": _f(r.get("pctChange")), "reported": _day(r.get("Date Reported"))})
+    return out
+
+
+def insider_activity(df, today: Optional[date] = None, days: int = INSIDER_DAYS) -> dict:
+    today = today or date.today()
+    since = today - timedelta(days=days)
+    rows = []
+    if df is not None and not getattr(df, "empty", True):
+        for _, r in df.iterrows():
+            when = _day(r.get("Start Date"))
+            if not when or date.fromisoformat(when) < since:
+                continue
+            rows.append({"date": when, "insider": str(r.get("Insider") or ""), "position": str(r.get("Position") or ""),
+                         "side": classify(str(r.get("Text") or ""), str(r.get("Transaction") or "")),
+                         "shares": _f(r.get("Shares")), "value": _f(r.get("Value")), "text": str(r.get("Text") or "")})
+    rows.sort(key=lambda x: x["date"], reverse=True)
+    total = lambda side, k: sum((x[k] or 0) for x in rows if x["side"] == side)  # noqa: E731
+    buys, sells = sum(x["side"] == "buy" for x in rows), sum(x["side"] == "sell" for x in rows)
+    bias = None
+    if buys or sells:
+        bias = "net buying" if total("buy", "value") > total("sell", "value") else "net selling"
+    return {"days": days, "buys": buys, "sells": sells, "buy_value": total("buy", "value"),
+            "sell_value": total("sell", "value"), "bias": bias, "recent": rows[:12]}
+
+
+def short_interest(info: dict) -> Optional[dict]:
+    shares = _f(info.get("sharesShort"))
+    if shares is None:
+        return None
+    prior = _f(info.get("sharesShortPriorMonth"))
+    return {"shares": shares, "prior_month": prior,
+            "change_pct": (shares / prior - 1) * 100 if prior else None,
+            "pct_of_float": (_f(info.get("shortPercentOfFloat")) or 0) * 100 or None,
+            "days_to_cover": _f(info.get("shortRatio")), "as_of": _day(info.get("dateShortInterest"))}
+
+
+def _deals(symbol: str) -> Optional[dict]:
+    """NSE bulk / block deals in the stock over the last 90 days."""
+    try:
+        from ..data.nse_deals import recent
+
+        return recent(90, symbol)
+    except Exception as exc:
+        logger.info("NSE deals for %s unavailable: %s", symbol, exc)
+        return None
+
+
+def build(symbol: str, market: str, ticker=None) -> dict:
+    from .analysis_run import yahoo_symbol
+
+    yf_symbol = yahoo_symbol(symbol, market)
+    live = ticker is None
+    if live:
+        with _lock:
+            hit = _cache.get(yf_symbol)
+            if hit and time.time() - hit[0] < CACHE_SECONDS:
+                return hit[1]
+        import yfinance as yf
+
+        ticker = yf.Ticker(yf_symbol)
+
+    def safe(attr):
+        try:
+            return getattr(ticker, attr)
+        except Exception as exc:
+            logger.info("%s %s unavailable: %s", yf_symbol, attr, exc)
+            return None
+
+    info = safe("info") or {}
+    out = {
+        "symbol": symbol, "market": market,
+        "breakdown": {"insiders_pct": (_f(info.get("heldPercentInsiders")) or 0) * 100 or None,
+                      "institutions_pct": (_f(info.get("heldPercentInstitutions")) or 0) * 100 or None,
+                      "float_shares": _f(info.get("floatShares")),
+                      "shares_outstanding": _f(info.get("sharesOutstanding"))},
+        "institutions": _holders(safe("institutional_holders")),
+        "funds": _holders(safe("mutualfund_holders")),
+        "insiders": insider_activity(safe("insider_transactions")),
+        "short": short_interest(info),
+        "deals": _deals(symbol) if market == "india" else None,
+    }
+    if live:
+        with _lock:
+            _cache[yf_symbol] = (time.time(), out)
+    return out

marketmyna/services/quality_scores.py

@@ -0,0 +1,199 @@
+"""Accounting quality scores from a company's last three annual statements,
+rebuilt from the published papers:
+
+- Piotroski F-score (Piotroski 2000): nine pass / fail tests on profitability,
+  leverage / liquidity and efficiency, latest year against the one before.
+- Altman Z-score (Altman 1968) for manufacturers, which needs the market
+  value of equity; Z'' (Altman 1995) for everyone else, on book equity.
+  Banks and insurers are skipped by all three scores: lending shows up as
+  operating cash flow, and they have no gross margin or current ratio.
+- Beneish M-score (Beneish 1999, 8 ratios): how far the statements look like
+  those of companies later found to have overstated earnings. Above -1.78 is
+  the paper's flag. A ratio that cannot be worked out is set to 1 (no change)
+  and listed.
+
+Input is financials.py's {key: [value per year, newest first]} for the
+income statement, balance sheet and cash flow. The scores describe the
+filings; they are not a rating or advice.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ..core.numbers import ratio as _div
+
+# Sectors scored with Altman's original model (built on listed manufacturers,
+# needs market value); the rest (services, real estate, utilities, telecom,
+# media) get Z'' on book equity
+MANUFACTURING = {"Industrials", "Basic Materials", "Consumer Cyclical", "Consumer Defensive", "Energy",
+                 "Healthcare", "Technology"}
+
+
+def _v(series: dict, key: str, i: int) -> Optional[float]:
+    vals = series.get(key) or []
+    return vals[i] if i < len(vals) else None
+
+
+def _r(x: Optional[float], digits: int = 3) -> Optional[float]:
+    return round(x, digits) if x is not None else None
+
+
+# ------------------------------------------------------------------ Piotroski
+
+def piotroski(inc: dict, bal: dict, cf: dict, financial: bool = False) -> Optional[dict]:
+    if financial:
+        return None
+    ni0, ni1 = _v(inc, "net_income", 0), _v(inc, "net_income", 1)
+    ta0, ta1, ta2 = (_v(bal, "total_assets", i) for i in range(3))
+    if ni0 is None or ta0 is None or ta1 is None:
+        return None
+    cfo = _v(cf, "operating_cf", 0)
+    # ROA on assets at the start of the year (the paper's definition)
+    roa0 = _div(ni0, ta1)
+    roa1 = _div(ni1, ta2 if ta2 is not None else ta1)
+
+    def ratio(num_key: str, den_key: str, i: int):
+        return _div(_v(bal, num_key, i), _v(bal, den_key, i))
+
+    lev0, lev1 = ratio("total_debt", "total_assets", 0), ratio("total_debt", "total_assets", 1)
+    cr0, cr1 = ratio("current_assets", "current_liabilities", 0), ratio("current_assets", "current_liabilities", 1)
+    sh0, sh1 = _v(bal, "shares", 0), _v(bal, "shares", 1)
+    gm0 = _div(_v(inc, "gross_profit", 0), _v(inc, "revenue", 0))
+    gm1 = _div(_v(inc, "gross_profit", 1), _v(inc, "revenue", 1))
+    if gm0 is not None and gm1 is not None and gm0 >= 0.999 and gm1 >= 0.999:
+        gm0 = gm1 = None  # no cost of goods reported (services): margin untestable
+    at0 = _div(_v(inc, "revenue", 0), ta1)
+    at1 = _div(_v(inc, "revenue", 1), ta2 if ta2 is not None else ta1)
+
+    def test(key, label, ok, detail):
+        return {"key": key, "label": label, "pass": ok, "detail": detail}
+
+    def pct(x):
+        return f"{x * 100:.1f}%" if x is not None else "n/a"
+
+    tests = [
+        test("roa", "Profitable (return on assets above 0)", None if roa0 is None else roa0 > 0, f"ROA {pct(roa0)}"),
+        test("cfo", "Cash from operations above 0", None if cfo is None else cfo > 0, "positive" if cfo and cfo > 0 else "zero or negative" if cfo is not None else "n/a"),
+        test("roa_up", "Return on assets improved", None if roa0 is None or roa1 is None else roa0 > roa1, f"{pct(roa1)} to {pct(roa0)}"),
+        test("accruals", "Cash from operations above net income", None if cfo is None else cfo > ni0, "earnings backed by cash" if cfo is not None and cfo > ni0 else "earnings ahead of cash" if cfo is not None else "n/a"),
+        test("leverage", "Debt to assets fell", None if lev0 is None or lev1 is None else lev0 <= lev1, f"{pct(lev1)} to {pct(lev0)}"),
+        test("liquidity", "Current ratio improved", None if cr0 is None or cr1 is None else cr0 > cr1,
+             f"{cr1:.2f} to {cr0:.2f}" if cr0 is not None and cr1 is not None else "n/a"),
+        test("dilution", "No new shares issued", None if sh0 is None or sh1 is None else sh0 <= sh1 * 1.001,
+             f"{(sh0 / sh1 - 1) * 100:+.1f}% shares" if sh0 and sh1 else "n/a"),
+        test("margin", "Gross margin improved", None if gm0 is None or gm1 is None else gm0 > gm1, f"{pct(gm1)} to {pct(gm0)}"),
+        test("turnover", "Asset turnover improved", None if at0 is None or at1 is None else at0 > at1,
+             f"{at1:.2f}x to {at0:.2f}x" if at0 is not None and at1 is not None else "n/a"),
+    ]
+    tested = [t for t in tests if t["pass"] is not None]
+    if len(tested) < 5:
+        return None
+    score = sum(1 for t in tested if t["pass"])
+    if len(tested) == 9:
+        label = "strong" if score >= 7 else "weak" if score <= 3 else "average"
+    else:
+        share = score / len(tested)
+        label = "strong" if share >= 0.75 else "weak" if share <= 0.35 else "average"
+    return {"score": score, "out_of": len(tested), "label": label, "tests": tests}
+
+
+# ------------------------------------------------------------------ Altman
+
+def altman(inc: dict, bal: dict, sector: Optional[str], market_cap: Optional[float],
+           financial: bool = False) -> Optional[dict]:
+    if financial:
+        return None
+    ta = _v(bal, "total_assets", 0)
+    tl = _v(bal, "total_liabilities", 0)
+    ca, cl = _v(bal, "current_assets", 0), _v(bal, "current_liabilities", 0)
+    re_ = _v(bal, "retained_earnings", 0)
+    ebit = _v(inc, "operating_income", 0)
+    if ebit is None and _v(inc, "pretax_income", 0) is not None:
+        ebit = _v(inc, "pretax_income", 0) + (abs(_v(inc, "interest_expense", 0) or 0))
+    sales = _v(inc, "revenue", 0)
+    equity = _v(bal, "equity", 0)
+    if not ta or not tl or ca is None or cl is None or re_ is None or ebit is None:
+        return None
+    x1, x2, x3 = (ca - cl) / ta, re_ / ta, ebit / ta
+
+    if sector in MANUFACTURING and market_cap and sales is not None:
+        x4, x5 = market_cap / tl, sales / ta
+        z = 1.2 * x1 + 1.4 * x2 + 3.3 * x3 + 0.6 * x4 + 1.0 * x5
+        model, safe, distress = "Z (manufacturers)", 2.99, 1.81
+        parts = {"working_capital": x1, "retained_earnings": x2, "ebit": x3, "market_value_to_liabilities": x4, "sales": x5}
+    else:
+        if equity is None:
+            return None
+        x4 = equity / tl
+        z = 6.56 * x1 + 3.26 * x2 + 6.72 * x3 + 1.05 * x4
+        model, safe, distress = "Z'' (non-manufacturers, book equity)", 2.6, 1.1
+        parts = {"working_capital": x1, "retained_earnings": x2, "ebit": x3, "book_equity_to_liabilities": x4}
+    zone = "safe" if z > safe else "distress" if z < distress else "grey"
+    return {"score": round(z, 2), "model": model, "zone": zone, "safe_above": safe, "distress_below": distress,
+            "parts": {k: _r(v) for k, v in parts.items()}}
+
+
+# ------------------------------------------------------------------ Beneish
+
+def beneish(inc: dict, bal: dict, cf: dict, financial: bool = False) -> Optional[dict]:
+    if financial:
+        return None
+    s0, s1 = _v(inc, "revenue", 0), _v(inc, "revenue", 1)
+    ta0, ta1 = _v(bal, "total_assets", 0), _v(bal, "total_assets", 1)
+    ni0, cfo0 = _v(inc, "net_income", 0), _v(cf, "operating_cf", 0)
+    if not s0 or not s1 or not ta0 or not ta1 or ni0 is None or cfo0 is None:
+        return None
+
+    def at(key, i, src=bal):
+        return _v(src, key, i)
+
+    rec0, rec1 = at("receivables", 0), at("receivables", 1)
+    gm0, gm1 = _div(at("gross_profit", 0, inc), s0), _div(at("gross_profit", 1, inc), s1)
+    ppe0, ppe1 = at("ppe", 0), at("ppe", 1)
+    ca0, ca1 = at("current_assets", 0), at("current_assets", 1)
+    dep0, dep1 = abs(at("depreciation", 0, cf) or 0) or None, abs(at("depreciation", 1, cf) or 0) or None
+    sga0, sga1 = at("sga", 0, inc), at("sga", 1, inc)
+    tl0, tl1 = at("total_liabilities", 0), at("total_liabilities", 1)
+
+    def quality(ca, ppe, ta):
+        return 1 - (ca + ppe) / ta if ca is not None and ppe is not None else None
+
+    def dep_rate(dep, ppe):
+        return dep / (dep + ppe) if dep is not None and ppe is not None and dep + ppe else None
+
+    ratios = {
+        "DSRI": _div(_div(rec0, s0), _div(rec1, s1)),       # receivables growing faster than sales
+        "GMI": _div(gm1, gm0),                               # gross margin falling
+        "AQI": _div(quality(ca0, ppe0, ta0), quality(ca1, ppe1, ta1)),  # more soft assets
+        "SGI": s0 / s1,                                      # sales growth
+        "DEPI": _div(dep_rate(dep1, ppe1), dep_rate(dep0, ppe0)),  # slower depreciation
+        "SGAI": _div(_div(sga0, s0), _div(sga1, s1)),        # overheads per sale
+        "LVGI": _div(_div(tl0, ta0), _div(tl1, ta1)),        # more leverage
+        "TATA": (ni0 - cfo0) / ta0,                          # accruals
+    }
+    if ratios["DSRI"] is None:
+        return None
+    neutral = [k for k, v in ratios.items() if v is None]
+    vals = {k: (1.0 if v is None else v) for k, v in ratios.items()}
+    m = (-4.84 + 0.920 * vals["DSRI"] + 0.528 * vals["GMI"] + 0.404 * vals["AQI"] + 0.892 * vals["SGI"]
+         + 0.115 * vals["DEPI"] - 0.172 * vals["SGAI"] + 4.679 * vals["TATA"] - 0.327 * vals["LVGI"])
+    return {"score": round(m, 2), "flag": m > -1.78, "threshold": -1.78,
+            "ratios": {k: _r(v) for k, v in ratios.items()}, "neutral": neutral}
+
+
+def compute(inc: dict, bal: dict, cf: dict, *, sector: Optional[str] = None,
+            market_cap: Optional[float] = None, financial: bool = False) -> Optional[dict]:
+    out = {
+        "piotroski": piotroski(inc, bal, cf, financial),
+        "altman": altman(inc, bal, sector, market_cap, financial),
+        "beneish": beneish(inc, bal, cf, financial),
+    }
+    if financial:
+        return {**out, "financial_sector": True,
+                "note": "Not scored: these models are built for non-financial companies. Banks and insurers "
+                        "book lending as operating cash flow and have no gross margin or current ratio."}
+    if not any(out.values()):
+        return None
+    out["financial_sector"] = False
+    return out

marketmyna/services/rates.py

@@ -0,0 +1,335 @@
+"""Rates & bullion for markets other than India (India has its own,
+richer card: marketmyna/services/india_rates.py).
+
+- us:        Fed funds, SOFR, Treasury 3M/2Y/10Y/30Y, 10y-2y, 30y mortgage
+             (FRED) + gold / silver in dollars (Yahoo futures).
+- hong_kong: HKMA base rate, HIBOR overnight / 1M / 3M (HKMA open API),
+             USD/HKD peg + gold / silver in HK dollars.
+- china_a:   China 3M interbank (FRED/OECD, monthly), USD/CNY + gold per
+             gram and silver per kg in yuan.
+- crypto:    perpetual-futures funding rates (Binance, Bybit fallback),
+             annualised - crypto's closest thing to an interest rate - plus
+             Bitcoin priced in gold.
+
+Every block is fetched independently; a failed block is reported and the
+rest still render. Cached for an hour per market.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor
+from datetime import date, timedelta
+from typing import Callable, Optional
+
+import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+CACHE_SECONDS = 3600
+TROY_OZ_G = 31.1034768
+TAEL_OZ = 1.20337  # 1 HK tael (37.429 g) in troy ounces
+HKMA = "https://api.hkma.gov.hk/public/market-data-and-statistics"
+FUNDING_COINS = ["BTC", "ETH", "SOL", "XRP", "DOGE", "BNB"]
+
+_cache: dict[str, tuple[float, dict]] = {}
+_lock = threading.Lock()
+
+
+def _get_json(url: str, params: Optional[dict] = None) -> dict:
+    import requests
+
+    r = requests.get(url, params=params, timeout=20, headers={"User-Agent": "Mozilla/5.0 MarketMyna"})
+    r.raise_for_status()
+    return r.json()
+
+
+def _fred(series_id: str, start: date) -> pd.Series:
+    from .macro import _fred as fred
+
+    return fred(series_id, start)
+
+
+def _yahoo(tickers: list[str]) -> dict[str, pd.Series]:
+    import yfinance as yf
+
+    from ..data import ecb_fx
+    from ..utils.yf_lock import YF_DOWNLOAD_LOCK
+
+    def download() -> dict[str, pd.Series]:
+        with YF_DOWNLOAD_LOCK:
+            df = yf.download(tickers, period="13mo", interval="1d", progress=False, auto_adjust=True, threads=True)
+        closes = df["Close"]
+        if isinstance(closes, pd.Series):
+            closes = closes.to_frame(tickers[0])
+        return {t: closes[t].dropna() for t in tickers if t in closes and closes[t].notna().sum()}
+
+    return ecb_fx.guarded(download, tickers, days=400)
+
+
+# ---------------------------------------------------------------- helpers
+
+
+def _naive(s: pd.Series) -> pd.Series:
+    idx = pd.DatetimeIndex(s.index)
+    return pd.Series(s.to_numpy(), index=idx.tz_localize(None) if idx.tz is not None else idx).sort_index()
+
+
+def _ago(s: pd.Series, days: int) -> Optional[float]:
+    past = s[s.index <= s.index[-1] - pd.Timedelta(days=days)]
+    return float(past.iloc[-1]) if len(past) else None
+
+
+def item(label: str, s: Optional[pd.Series], unit: str, note: str = "", scale: float = 1.0,
+         change: str = "points", digits: int = 2) -> Optional[dict]:
+    """One stat from a series: latest value, 1-month and 1-year change.
+
+    change="points" for rates (difference), "pct" for prices (% change)."""
+    if s is None or s.dropna().empty:
+        return None
+    s = _naive(s.dropna()) * scale
+    now = float(s.iloc[-1])
+
+    def delta(days: int) -> Optional[float]:
+        past = _ago(s, days)
+        if past is None:
+            return None
+        return now - past if change == "points" else (now / past - 1) * 100 if past else None
+
+    return {"label": label, "value": round(now, digits), "unit": unit, "note": note,
+            "change_1m": delta(30), "change_1y": delta(365), "change_kind": change,
+            "as_of": str(s.index[-1].date()),
+            "spark": [round(float(v), digits) for v in s.resample("W").last().dropna().tail(52)]}
+
+
+def _section(title: str, items: list[Optional[dict]], note: str = "", source: str = "") -> Optional[dict]:
+    items = [i for i in items if i]
+    return {"title": title, "note": note, "source": source, "items": items} if items else None
+
+
+def _run(blocks: dict[str, Callable[[], Optional[dict]]]) -> tuple[list[dict], list[str]]:
+    sections, errors = [], []
+    with ThreadPoolExecutor(max_workers=len(blocks)) as pool:
+        futures = {name: pool.submit(fn) for name, fn in blocks.items()}
+        for name, fut in futures.items():
+            try:
+                sec = fut.result()
+            except Exception as exc:
+                logger.warning("Rates block %s failed: %s", name, exc)
+                errors.append(f"{name} unavailable right now")
+                continue
+            if sec:
+                sections.append(sec)
+            else:
+                errors.append(f"{name} unavailable right now")
+    return sections, errors
+
+
+def _bullion(currency: str, fx: Optional[str], unit_note: str, *, per: str = "oz",
+             yahoo: Callable = _yahoo) -> Optional[dict]:
+    tickers = ["GC=F", "SI=F"] + ([fx] if fx else [])
+    data = yahoo(tickers)
+    gold, silver = data.get("GC=F"), data.get("SI=F")
+    if gold is None:
+        return None
+    gold, silver = _naive(gold), _naive(silver) if silver is not None else None
+    if fx:
+        rate = _naive(data[fx]) if fx in data else None
+        if rate is None:
+            return None
+        gold = pd.concat([gold, rate], axis=1).ffill().dropna().prod(axis=1)
+        silver = pd.concat([silver, rate], axis=1).ffill().dropna().prod(axis=1) if silver is not None else None
+    if per == "g":
+        g_item = item(f"Gold ({currency}/g)", gold, currency, unit_note, scale=1 / TROY_OZ_G, change="pct")
+        s_item = item(f"Silver ({currency}/kg)", silver, currency, "", scale=1000 / TROY_OZ_G, change="pct", digits=0)
+    elif per == "tael":
+        g_item = item(f"Gold ({currency}/tael)", gold, currency, unit_note, scale=TAEL_OZ, change="pct", digits=0)
+        s_item = item(f"Silver ({currency}/oz)", silver, currency, "", change="pct")
+    else:
+        g_item = item(f"Gold ({currency}/oz)", gold, currency, unit_note, change="pct", digits=0)
+        s_item = item(f"Silver ({currency}/oz)", silver, currency, "", change="pct")
+    ratio = None
+    if silver is not None:
+        both = pd.concat([gold, silver], axis=1, keys=["g", "s"]).ffill().dropna()
+        ratio = item("Gold / silver ratio", both["g"] / both["s"], "x",
+                     "Ounces of silver one ounce of gold buys; high = silver cheap vs gold", change="points", digits=1)
+    return _section("Bullion", [g_item, s_item, ratio], source="COMEX futures, market data feed")
+
+
+# ---------------------------------------------------------------- markets
+
+
+def _us(fred=_fred, yahoo=_yahoo) -> dict:
+    start = date.today() - timedelta(days=400)
+
+    def series(*ids):
+        return {i: fred(i, start) for i in ids}
+
+    def policy():
+        s = series("DFF", "SOFR", "MORTGAGE30US")
+        return _section("Policy & money market", [
+            item("Fed funds (effective)", s["DFF"], "%", "Overnight rate the Fed steers"),
+            item("SOFR", s["SOFR"], "%", "Secured overnight rate; benchmark for most US loans"),
+            item("30-year mortgage", s["MORTGAGE30US"], "%", "Freddie Mac weekly average"),
+        ], source="Official US rates data")
+
+    def treasuries():
+        s = series("DGS3MO", "DGS2", "DGS10", "DGS30", "T10Y2Y")
+        return _section("Treasury yields", [
+            item("3-month", s["DGS3MO"], "%", "Cash-like yield"),
+            item("2-year", s["DGS2"], "%", "Tracks expected Fed moves"),
+            item("10-year", s["DGS10"], "%", "Benchmark for valuations and mortgages"),
+            item("30-year", s["DGS30"], "%"),
+            item("10y − 2y spread", s["T10Y2Y"], "pts", "Below 0 (inverted) has preceded most recessions"),
+        ], note="Full curve: see the Macro tab.", source="Official US Treasury constant-maturity yields")
+
+    sections, errors = _run({"Policy rates": policy, "Treasuries": treasuries,
+                             "Bullion": lambda: _bullion("$", None, "COMEX front-month", yahoo=yahoo)})
+    return {"sections": sections, "errors": errors}
+
+
+def _hkma_series(path: str, fields: dict[str, str], date_key: str, pages: int = 400) -> dict[str, pd.Series]:
+    data = _get_json(f"{HKMA}/{path}", {"pagesize": pages, "sortby": date_key, "sortorder": "desc"})
+    records = (data.get("result") or {}).get("records") or []
+    out = {}
+    for key in fields:
+        pts = {pd.Timestamp(r[date_key]): r[key] for r in records if r.get(key) is not None}
+        if pts:
+            out[key] = pd.Series(pts).sort_index().astype(float)
+    return out
+
+
+def _hong_kong(yahoo=_yahoo) -> dict:
+    def money():
+        daily = _hkma_series("daily-monetary-statistics/daily-figures-interbank-liquidity",
+                             {"disc_win_base_rate": "", "hibor_overnight": "", "hibor_fixing_1m": ""}, "end_of_date")
+        curve = _hkma_series("monthly-statistical-bulletin/er-ir/hk-interbank-ir-daily",
+                             {"ir_3m": "", "ir_12m": ""}, "end_of_day")
+        return _section("HKMA & HIBOR", [
+            item("Base rate", daily.get("disc_win_base_rate"), "%", "HKMA discount-window base rate; follows the Fed under the peg"),
+            item("HIBOR overnight", daily.get("hibor_overnight"), "%", "Swings with HK dollar liquidity"),
+            item("HIBOR 1M", daily.get("hibor_fixing_1m"), "%", "Prices most HK mortgages (HIBOR-linked plans)"),
+            item("HIBOR 3M", curve.get("ir_3m"), "%"),
+            item("HIBOR 12M", curve.get("ir_12m"), "%"),
+        ], source="HKMA open API")
+
+    def peg():
+        data = yahoo(["HKD=X"])
+        return _section("Currency peg", [
+            item("USD / HKD", data.get("HKD=X"), "HK$", "Pegged in the 7.75 – 7.85 band; near 7.85 = weak side, HKMA drains liquidity",
+                 change="points", digits=4),
+        ], source="Market data feed")
+
+    sections, errors = _run({"HKMA rates": money, "Currency peg": peg,
+                             "Bullion": lambda: _bullion("HK$", "HKD=X", "Spot in HK dollars", per="tael", yahoo=yahoo)})
+    return {"sections": sections, "errors": errors}
+
+
+def _china(fred=_fred, yahoo=_yahoo) -> dict:
+    start = date.today() - timedelta(days=800)
+
+    def money():
+        return _section("Money market", [
+            item("3-month interbank", fred("IR3TIB01CNM156N", start), "%", "Monthly (OECD); lags a few months"),
+        ], source="Official central bank and OECD statistics")
+
+    def fx():
+        data = yahoo(["CNY=X"])
+        return _section("Currency", [
+            item("USD / CNY", data.get("CNY=X"), "¥", "Higher = weaker yuan; PBoC manages it in a daily band",
+                 change="points", digits=4),
+        ], source="Market data feed")
+
+    sections, errors = _run({"Money market": money, "Currency": fx,
+                             "Bullion": lambda: _bullion("¥", "CNY=X", "Spot converted to yuan", per="g", yahoo=yahoo)})
+    return {"sections": sections, "errors": errors}
+
+
+def _funding_binance() -> list[dict]:
+    rows = _get_json("https://fapi.binance.com/fapi/v1/premiumIndex")
+    by = {r["symbol"]: r for r in rows if isinstance(r, dict)}
+    out = []
+    for coin in FUNDING_COINS:
+        r = by.get(f"{coin}USDT")
+        if r and r.get("lastFundingRate") not in (None, ""):
+            out.append({"coin": coin, "rate_8h": float(r["lastFundingRate"]), "mark": float(r["markPrice"]),
+                        "next": int(r.get("nextFundingTime") or 0)})
+    return out
+
+
+def _funding_bybit() -> list[dict]:
+    data = _get_json("https://api.bybit.com/v5/market/tickers", {"category": "linear"})
+    by = {r["symbol"]: r for r in (data.get("result") or {}).get("list") or []}
+    out = []
+    for coin in FUNDING_COINS:
+        r = by.get(f"{coin}USDT")
+        if r and r.get("fundingRate") not in (None, ""):
+            out.append({"coin": coin, "rate_8h": float(r["fundingRate"]), "mark": float(r["markPrice"]),
+                        "next": int(r.get("nextFundingTime") or 0)})
+    return out
+
+
+def _crypto(yahoo=_yahoo, funding_sources=(_funding_binance, _funding_bybit)) -> dict:
+    def funding():
+        rows, source = [], ""
+        for fn in funding_sources:
+            try:
+                rows = fn()
+            except Exception as exc:
+                logger.warning("Funding rates via %s failed: %s", fn.__name__, exc)
+                continue
+            if rows:
+                source = "Crypto exchange futures data"
+                break
+        items = []
+        for r in rows:
+            annual = r["rate_8h"] * 3 * 365 * 100
+            items.append({
+                "label": f"{r['coin']} funding", "value": round(annual, 1), "unit": "% / yr",
+                "note": f"{r['rate_8h'] * 100:.4f}% per 8h · "
+                        + ("longs pay shorts (bullish leverage)" if r["rate_8h"] > 0 else "shorts pay longs (bearish leverage)"),
+                "change_1m": None, "change_1y": None, "change_kind": "points", "as_of": str(date.today()), "spark": [],
+                "tone": "up" if annual > 0 else "down",
+            })
+        return _section("Perpetual funding rates", items,
+                        note="What leveraged longs pay shorts, annualised. Very high = crowded longs; negative = crowded shorts.",
+                        source=f"{source} USDT perpetuals" if source else "")
+
+    def btc_gold():
+        data = yahoo(["BTC-USD", "GC=F"])
+        if "BTC-USD" not in data or "GC=F" not in data:
+            return None
+        both = pd.concat([_naive(data["BTC-USD"]), _naive(data["GC=F"])], axis=1, keys=["b", "g"]).ffill().dropna()
+        return _section("Bitcoin vs gold", [
+            item("BTC in gold ounces", both["b"] / both["g"], "oz", "How many ounces of gold one bitcoin buys", change="pct", digits=1),
+            item("Gold ($/oz)", data["GC=F"], "$", "COMEX front-month", change="pct", digits=0),
+        ], source="Market data feed")
+
+    sections, errors = _run({"Funding rates": funding, "Bitcoin vs gold": btc_gold})
+    return {"sections": sections, "errors": errors}
+
+
+BUILDERS: dict[str, Callable[[], dict]] = {
+    "us": _us, "hong_kong": _hong_kong, "china_a": _china, "crypto": _crypto,
+}
+TITLES = {"us": "US rates & bullion", "hong_kong": "Hong Kong rates & bullion",
+          "china_a": "China rates & bullion", "crypto": "Funding rates & gold"}
+
+
+def build(market: str, use_cache: bool = True) -> dict:
+    market = market.lower()
+    builder = BUILDERS.get(market)
+    if builder is None:
+        return {"market": market, "sections": [], "errors": ["Not available for this market"]}
+    if use_cache:
+        with _lock:
+            hit = _cache.get(market)
+        if hit and time.time() - hit[0] < CACHE_SECONDS:
+            return hit[1]
+    out = {"market": market, "title": TITLES[market], **builder()}
+    if use_cache and out["sections"]:
+        with _lock:
+            _cache[market] = (time.time(), out)
+    return out