marketmyna 0.2.0__py3-none-any.whl

marketmyna/services/big_trades.py

@@ -0,0 +1,335 @@
+"""Big trades outside India (India: NSE bulk/block deals, marketmyna/data/nse_deals.py).
+
+- us:        insider open-market buys and sells from the latest SEC Form 4
+             filings (EDGAR). Needs SEC_USER_AGENT (name + contact email),
+             as SEC's fair-access policy requires.
+- china_a:   Shanghai / Shenzhen block trades (大宗交易) with buyer and seller
+             branches, via Eastmoney's data centre (same host the listings use).
+- hong_kong: Southbound Stock Connect - the HK stocks mainland investors
+             bought and sold most each day (Shanghai and Shenzhen links).
+- crypto:    no public trade-level whale feed, so the closest free signal:
+             Binance futures positioning of the largest accounts (top-trader
+             long/short), open interest change and taker buy/sell balance.
+
+Each market is cached for CACHE_SECONDS.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import threading
+import time
+import xml.etree.ElementTree as ET
+from concurrent.futures import ThreadPoolExecutor
+from datetime import date, datetime, timedelta
+from typing import Callable, Optional
+
+logger = logging.getLogger(__name__)
+
+CACHE_SECONDS = 3600
+EASTMONEY = "https://datacenter-web.eastmoney.com/api/data/v1/get"
+SEC_FEED = ("https://www.sec.gov/cgi-bin/browse-edgar?action=getcurrent&type=4&company=&dateb=&owner=include"
+            "&start={start}&count=100&output=atom")
+POSITION_COINS = ["BTC", "ETH", "SOL", "XRP", "BNB", "DOGE", "ADA", "AVAX", "LINK", "SUI"]
+
+_cache: dict[tuple, tuple[float, dict]] = {}
+_lock = threading.Lock()
+
+
+def _json(url: str, params: Optional[dict] = None, headers: Optional[dict] = None):
+    import requests
+
+    r = requests.get(url, params=params, timeout=20, headers=headers or {"User-Agent": "Mozilla/5.0 MarketMyna"})
+    r.raise_for_status()
+    return r.json()
+
+
+def _num(v) -> Optional[float]:
+    try:
+        return float(v)
+    except (TypeError, ValueError):
+        return None
+
+
+# ------------------------------------------------------------- US: Form 4
+
+_ATOM = {"a": "http://www.w3.org/2005/Atom"}
+
+
+def parse_feed(xml_text: str) -> list[tuple[str, str]]:
+    """Atom feed -> unique (cik, accession) of Form 4 filings, issuer entries first."""
+    out: dict[str, str] = {}
+    for entry in ET.fromstring(xml_text).findall("a:entry", _ATOM):
+        link = entry.find("a:link", _ATOM)
+        href = link.get("href") if link is not None else ""
+        m = re.search(r"/data/(\d+)/(\d{18})/", href or "")
+        if m and m.group(2) not in out:
+            out[m.group(2)] = m.group(1)
+    return [(cik, acc) for acc, cik in out.items()]
+
+
+def _t(node, path: str) -> str:
+    el = node.find(path)
+    return (el.text or "").strip() if el is not None and el.text else ""
+
+
+def parse_form4(xml_text: str) -> list[dict]:
+    """Open-market purchases (P) and sales (S) in one Form 4, one row per
+    side, shares summed and price volume-weighted."""
+    root = ET.fromstring(xml_text)
+    symbol = _t(root, "issuer/issuerTradingSymbol").upper()
+    issuer = _t(root, "issuer/issuerName")
+    owner = _t(root, "reportingOwner/reportingOwnerId/rptOwnerName")
+    rel = root.find("reportingOwner/reportingOwnerRelationship")
+    roles = []
+    if rel is not None:
+        if _t(rel, "isDirector") in ("1", "true"):
+            roles.append("Director")
+        if _t(rel, "isOfficer") in ("1", "true"):
+            roles.append(_t(rel, "officerTitle") or "Officer")
+        if _t(rel, "isTenPercentOwner") in ("1", "true"):
+            roles.append("10% owner")
+    sides: dict[str, dict] = {}
+    for tx in root.findall("nonDerivativeTable/nonDerivativeTransaction"):
+        code = _t(tx, "transactionCoding/transactionCode")
+        if code not in ("P", "S"):
+            continue  # grants, option exercises, tax withholding... are not market trades
+        shares = _num(_t(tx, "transactionAmounts/transactionShares/value")) or 0
+        price = _num(_t(tx, "transactionAmounts/transactionPricePerShare/value")) or 0
+        side = sides.setdefault(code, {"qty": 0.0, "value": 0.0, "date": _t(tx, "transactionDate/value")})
+        side["qty"] += shares
+        side["value"] += shares * price
+    rows = []
+    for code, s in sides.items():
+        if not s["qty"]:
+            continue
+        rows.append({
+            "date": s["date"][:10], "kind": "insider", "symbol": symbol, "name": issuer,
+            "client": owner.title() if owner.isupper() else owner, "side": "buy" if code == "P" else "sell",
+            "qty": s["qty"], "price": s["value"] / s["qty"] if s["qty"] else None, "value": s["value"] or None,
+            "remarks": ", ".join(roles) or None,
+        })
+    return rows
+
+
+def _us(fetch_text: Optional[Callable[[str], str]] = None, max_filings: int = 120) -> dict:
+    from .sec_mdna import user_agent
+
+    ua = user_agent()  # raises SecNotConfigured with the fix
+    if fetch_text is None:
+        import requests
+
+        session = requests.Session()
+        session.headers.update({"User-Agent": ua, "Accept-Encoding": "gzip, deflate"})
+        gate = threading.Semaphore(6)  # SEC allows 10 requests/second
+
+        def fetch_text(url: str) -> str:
+            with gate:
+                r = session.get(url, timeout=20)
+                time.sleep(0.15)
+            r.raise_for_status()
+            return r.text
+
+    filings: list[tuple[str, str]] = []
+    for start in (0, 100):
+        filings += parse_feed(fetch_text(SEC_FEED.format(start=start)))
+    seen, unique = set(), []
+    for cik, acc in filings:
+        if acc not in seen:
+            seen.add(acc)
+            unique.append((cik, acc))
+    unique = unique[:max_filings]
+
+    def one(item):
+        cik, acc = item
+        try:
+            import json
+
+            index = json.loads(fetch_text(f"https://www.sec.gov/Archives/edgar/data/{cik}/{acc}/index.json"))
+            names = [f["name"] for f in index.get("directory", {}).get("item", []) if f["name"].endswith(".xml")]
+            if not names:
+                return []
+            return parse_form4(fetch_text(f"https://www.sec.gov/Archives/edgar/data/{cik}/{acc}/{names[0]}"))
+        except Exception as exc:
+            logger.debug("Form 4 %s skipped: %s", acc, exc)
+            return []
+
+    with ThreadPoolExecutor(max_workers=6) as pool:
+        rows = [r for found in pool.map(one, unique) for r in found]
+    rows.sort(key=lambda r: -(r["value"] or 0))
+    return {
+        "title": "Insider buys & sells (SEC Form 4)",
+        "subtitle": "Open-market purchases and sales by executives, directors and 10% owners in the latest filings",
+        "currency": "$", "deals": rows,
+        "note": f"Latest {len(unique)} insider filings (Form 4) with the US regulator; open-market trades only (code P / S), "
+                "so grants, option exercises and tax withholding are left out. Insiders sell for many reasons; "
+                "buys are the rarer, stronger signal.",
+    }
+
+
+# -------------------------------------------------- China A: block trades
+
+
+def parse_blocks(rows: list[dict]) -> list[dict]:
+    out = []
+    for r in rows:
+        if str(r.get("SECURITY_TYPE_WEB")) != "1":  # 1 = A-share stock (skip ETFs, bonds)
+            continue
+        premium = _num(r.get("PREMIUM_RATIO"))
+        out.append({
+            "date": str(r.get("TRADE_DATE", ""))[:10], "kind": "block", "symbol": r.get("SECURITY_CODE"),
+            "name": r.get("SECURITY_NAME_ABBR"),
+            "client": f"{r.get('BUYER_NAME') or '?'} ← {r.get('SELLER_NAME') or '?'}",
+            "side": "premium" if (premium or 0) > 0 else "discount" if (premium or 0) < 0 else "at market",
+            "qty": _num(r.get("DEAL_VOLUME")), "price": _num(r.get("DEAL_PRICE")), "value": _num(r.get("DEAL_AMT")),
+            "remarks": f"{premium * 100:+.1f}% vs close" if premium is not None else None,
+        })
+    return out
+
+
+def _china(days: int, fetch=_json) -> dict:
+    since = (date.today() - timedelta(days=days + 16)).isoformat()  # holidays (Golden Week, CNY) can run 9 days
+    data = fetch(EASTMONEY, {
+        "reportName": "RPT_DATA_BLOCKTRADE", "columns": "ALL", "sortColumns": "TRADE_DATE,DEAL_AMT", "sortTypes": "-1,-1",
+        "pageSize": 500, "pageNumber": 1, "source": "WEB", "client": "WEB", "filter": f"(TRADE_DATE>='{since}')",
+    })
+    rows = parse_blocks(((data or {}).get("result") or {}).get("data") or [])
+    if rows:
+        latest = max(r["date"] for r in rows)
+        cutoff = (date.fromisoformat(latest) - timedelta(days=days - 1)).isoformat()
+        rows = [r for r in rows if r["date"] >= cutoff]
+    rows.sort(key=lambda r: -(r["value"] or 0))
+    return {
+        "title": "Block trades (Shanghai & Shenzhen)",
+        "subtitle": "Large negotiated trades between brokerage branches, with the price against the day's close",
+        "currency": "¥", "deals": rows,
+        "note": "Buyer ← seller are brokerage branches; 机构专用 means an institution's dedicated seat. A deep discount "
+                "often means a large holder exiting; a premium, a buyer keen to get size. Source: Eastmoney.",
+    }
+
+
+# ------------------------------------------ Hong Kong: southbound connect
+
+
+def parse_southbound(rows: list[dict], link: str) -> list[dict]:
+    out = []
+    for r in rows:
+        net = _num(r.get("NET_BUY_AMT"))
+        out.append({
+            "date": str(r.get("TRADE_DATE", ""))[:10], "kind": f"southbound ({link})", "symbol": r.get("SECURITY_CODE"),
+            "name": r.get("SECURITY_NAME"), "client": f"Mainland investors via {link}",
+            "side": "net buy" if (net or 0) >= 0 else "net sell", "qty": None, "price": _num(r.get("CLOSE_PRICE")),
+            "value": abs(net) if net is not None else _num(r.get("DEAL_AMT")),
+            "remarks": (f"bought HK${(_num(r.get('BUY_AMT')) or 0) / 1e6:,.0f}m · sold HK${(_num(r.get('SELL_AMT')) or 0) / 1e6:,.0f}m"
+                        if r.get("BUY_AMT") is not None else None),
+        })
+    return out
+
+
+def _hk_english(rows: list[dict], names: Optional[dict[str, str]] = None) -> None:
+    """Eastmoney sends Chinese names; our HK listing has the English ones."""
+    if names is None:
+        try:
+            from ..data.listings import get_store
+
+            names = {r["symbol"]: r["name"] for r in get_store().rows("hong_kong")}
+        except Exception:
+            names = {}
+    for r in rows:
+        en = names.get(str(r.get("symbol")))
+        if en:
+            r["name_local"], r["name"] = r["name"], en
+
+
+def _hong_kong(days: int, fetch=_json, names: Optional[dict[str, str]] = None) -> dict:
+    since = (date.today() - timedelta(days=days + 16)).isoformat()  # holidays (Golden Week, CNY) can run 9 days
+    rows: list[dict] = []
+    for code, link in (("002", "Shanghai link"), ("004", "Shenzhen link")):
+        data = fetch(EASTMONEY, {
+            "reportName": "RPT_MUTUAL_TOP10DEAL", "columns": "ALL", "sortColumns": "TRADE_DATE,RANK", "sortTypes": "-1,1",
+            "pageSize": 200, "pageNumber": 1, "source": "WEB", "client": "WEB",
+            "filter": f'(MUTUAL_TYPE="{code}")(TRADE_DATE>=\'{since}\')',
+        })
+        rows += parse_southbound(((data or {}).get("result") or {}).get("data") or [], link)
+    if rows:
+        latest = max(r["date"] for r in rows)
+        cutoff = (date.fromisoformat(latest) - timedelta(days=days - 1)).isoformat()
+        rows = [r for r in rows if r["date"] >= cutoff]
+    rows.sort(key=lambda r: -(r["value"] or 0))
+    _hk_english(rows, names)
+    return {
+        "title": "Southbound Stock Connect",
+        "subtitle": "The Hong Kong stocks mainland investors traded most, and whether they were net buyers or sellers",
+        "currency": "HK$", "deals": rows,
+        "note": "Daily top-10 traded stocks on each southbound link (Shanghai and Shenzhen), sorted by net amount. "
+                "Mainland flows have become a big driver of HK prices. Source: Eastmoney / HKEX.",
+    }
+
+
+# ------------------------------------------------ crypto: big-trader positioning
+
+
+def _coin_positioning(coin: str, fetch=_json) -> Optional[dict]:
+    base = "https://fapi.binance.com/futures/data"
+    sym = f"{coin}USDT"
+    top = fetch(f"{base}/topLongShortPositionRatio", {"symbol": sym, "period": "1d", "limit": 8})
+    oi = fetch(f"{base}/openInterestHist", {"symbol": sym, "period": "1d", "limit": 8})
+    taker = fetch(f"{base}/takerlongshortRatio", {"symbol": sym, "period": "1d", "limit": 2})
+    if not top or not oi:
+        return None
+    last_top, prev_top = top[-1], top[-2] if len(top) > 1 else top[-1]
+    oi_now = _num(oi[-1]["sumOpenInterestValue"])
+    oi_1d = _num(oi[-2]["sumOpenInterestValue"]) if len(oi) > 1 else None
+    oi_7d = _num(oi[0]["sumOpenInterestValue"]) if len(oi) > 1 else None
+    return {
+        "coin": coin,
+        "top_long_pct": round(_num(last_top["longAccount"]) * 100, 1),
+        "top_ratio": _num(last_top["longShortRatio"]),
+        "top_ratio_change": (_num(last_top["longShortRatio"]) or 0) - (_num(prev_top["longShortRatio"]) or 0),
+        "open_interest": oi_now,
+        "oi_change_1d": (oi_now / oi_1d - 1) * 100 if oi_now and oi_1d else None,
+        "oi_change_7d": (oi_now / oi_7d - 1) * 100 if oi_now and oi_7d else None,
+        "taker_ratio": _num(taker[-1]["buySellRatio"]) if taker else None,
+    }
+
+
+def _crypto(fetch=_json) -> dict:
+    with ThreadPoolExecutor(max_workers=5) as pool:
+        rows = [r for r in pool.map(lambda c: _safe(_coin_positioning, c, fetch), POSITION_COINS) if r]
+    return {
+        "title": "Whale positioning (crypto futures)",
+        "subtitle": "How the largest futures accounts are positioned, and whether leverage is building or unwinding",
+        "currency": "$", "positions": rows,
+        "note": "Top traders = the 20% of accounts with the biggest margin balances; their long % is by position size. "
+                "Open interest = total value of open futures; rising OI with rising price = new money, falling OI = "
+                "positions closing. Taker ratio > 1 = more aggressive buying than selling yesterday. Source: a major crypto exchange's futures data.",
+    }
+
+
+def _safe(fn, *args):
+    try:
+        return fn(*args)
+    except Exception as exc:
+        logger.info("Positioning %s skipped: %s", args[0], exc)
+        return None
+
+
+def build(market: str, days: int = 1, use_cache: bool = True) -> dict:
+    market = market.lower()
+    builders: dict[str, Callable[[], dict]] = {
+        "us": _us, "china_a": lambda: _china(days), "hong_kong": lambda: _hong_kong(days), "crypto": _crypto,
+    }
+    if market not in builders:
+        raise ValueError("Big trades are available for India, US, China A, Hong Kong and crypto")
+    key = (market, days if market in ("china_a", "hong_kong") else 0)
+    if use_cache:
+        with _lock:
+            hit = _cache.get(key)
+        if hit and time.time() - hit[0] < CACHE_SECONDS:
+            return hit[1]
+    out = {"market": market, "days": days, "as_of": datetime.now().isoformat(timespec="minutes"), **builders[market]()}
+    if use_cache and (out.get("deals") or out.get("positions")):
+        with _lock:
+            _cache[key] = (time.time(), out)
+    return out

marketmyna/services/brokers/angel.py

@@ -0,0 +1,271 @@
+"""Angel One SmartAPI: live NSE prices for the Markets / Watchlist tables.
+
+Free with an Angel One account (smartapi.angelone.in -> create an app for
+the API key). The server logs itself in every day with the client code,
+PIN and the TOTP secret shown when enabling TOTP, so prices keep flowing
+without a manual morning login.
+
+Only the Market Quote REST endpoint is used (up to 50 symbols per call).
+NSE symbols are mapped to Angel's instrument tokens with their public
+instrument master, cached on disk for a day.
+
+Note: showing exchange prices to the public needs the exchange's data
+licence; check NSE's terms before launch.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import logging
+import os
+import struct
+import threading
+import time
+from pathlib import Path
+from typing import Optional
+
+from marketmyna.core.home import app_home
+
+logger = logging.getLogger(__name__)
+
+API = os.environ.get("ANGEL_API_ROOT", "https://apiconnect.angelone.in")
+SCRIP_MASTER = os.environ.get(
+    "ANGEL_SCRIP_MASTER", "https://margincalculator.angelone.in/OpenAPI_File/files/OpenAPIScripMaster.json")
+BATCH = 50  # symbols per quote call (API limit)
+# Market Quote limits per Angel account (docs: RateLimit): 10/s, 500/min,
+# 5000/hour. Every app user shares the one account, so stay under the
+# hourly cap: about 1.1 calls a second for the tables (~4,000 an hour), which
+# leaves room for the Market insights' live prices (services/live_market.py:
+# 10 calls a minute for the 500 largest names, ~600 an hour).
+CALLS_PER_SECOND = float(os.environ.get("ANGEL_QUOTE_CALLS_PER_SECOND", 1.1))
+MASTER_MAX_AGE = 20 * 3600
+
+
+class AngelError(Exception):
+    def __init__(self, message: str, code: str = "", http: int = 0):
+        super().__init__(message)
+        self.code, self.http = code, http
+
+    @property
+    def session_expired(self) -> bool:
+        # AG8001 invalid / AG8002 expired / AG8003 missing token (docs: Error Codes).
+        return self.http == 401 or self.code in ("AG8001", "AG8002", "AG8003")
+
+
+def totp(secret: str, now: Optional[float] = None, digits: int = 6, step: int = 30) -> str:
+    """RFC 6238 time-based code from a base32 secret (what authenticator apps show)."""
+    key = base64.b32decode(secret.replace(" ", "").upper() + "=" * (-len(secret.replace(" ", "")) % 8))
+    counter = int((now if now is not None else time.time()) // step)
+    digest = hmac.new(key, struct.pack(">Q", counter), hashlib.sha1).digest()
+    offset = digest[-1] & 0x0F
+    code = (struct.unpack(">I", digest[offset:offset + 4])[0] & 0x7FFFFFFF) % (10 ** digits)
+    return str(code).zfill(digits)
+
+
+def configured(config) -> bool:
+    return all(getattr(config, f, None) for f in ("angel_api_key", "angel_client_code", "angel_pin", "angel_totp_secret"))
+
+
+def _headers(config, token: Optional[str] = None) -> dict:
+    h = {
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+        "X-UserType": "USER",
+        "X-SourceID": "WEB",
+        "X-ClientLocalIP": "127.0.0.1",
+        "X-ClientPublicIP": "127.0.0.1",
+        "X-MACAddress": "00:00:00:00:00:00",
+        "X-PrivateKey": config.angel_api_key,
+    }
+    if token:
+        h["Authorization"] = f"Bearer {token}"
+    return h
+
+
+def _post(path: str, config, body: dict, token: Optional[str] = None) -> dict:
+    import requests
+
+    r = requests.post(API + path, headers=_headers(config, token), data=json.dumps(body), timeout=10)
+    try:
+        data = r.json()
+    except ValueError:
+        detail = "rate limit exceeded" if r.status_code == 403 else "no JSON"
+        raise AngelError(f"Angel One answered HTTP {r.status_code} ({detail})", http=r.status_code)
+    # The docs use both status/errorcode and success/errorCode.
+    ok = data.get("status", data.get("success", False))
+    code = data.get("errorcode") or data.get("errorCode") or ""
+    if r.status_code >= 400 or not ok:
+        raise AngelError(data.get("message") or f"Angel One error (HTTP {r.status_code})", code=code, http=r.status_code)
+    return data
+
+
+class AngelClient:
+    """One logged-in session, shared; logs in again when it expires."""
+
+    def __init__(self, config):
+        self.config = config
+        self._token: Optional[str] = None
+        self._logged_at = 0.0
+        self._lock = threading.Lock()
+        self._tokens: dict[str, str] = {}  # NSE symbol -> instrument token
+        self._tokens_at = 0.0
+
+    # -------------------------------------------------------------- session
+    def login(self) -> str:
+        cfg = self.config
+        data = _post("/rest/auth/angelbroking/user/v1/loginByPassword", cfg, {
+            "clientcode": cfg.angel_client_code, "password": cfg.angel_pin, "totp": totp(cfg.angel_totp_secret),
+        })
+        token = (data.get("data") or {}).get("jwtToken")
+        if not token:
+            raise AngelError("Angel One login returned no session token")
+        self._token, self._logged_at = token, time.time()
+        return token
+
+    def _session(self) -> str:
+        with self._lock:
+            # A SmartAPI session lasts until 12 midnight (IST): log in again on a new day.
+            if not self._token or _ist_date(self._logged_at) != _ist_date(time.time()):
+                self.login()
+            return self._token
+
+    # -------------------------------------------------------------- symbols
+    def _symbol_tokens(self) -> dict[str, str]:
+        if self._tokens and time.time() - self._tokens_at < MASTER_MAX_AGE:
+            return self._tokens
+        path = Path(getattr(self.config, "app_dir", app_home())) / "cache" / "angel_nse_tokens.json"
+        data: Optional[dict] = None
+        if path.exists() and time.time() - path.stat().st_mtime < MASTER_MAX_AGE:
+            try:
+                data = json.loads(path.read_text(encoding="utf-8"))
+            except ValueError:
+                data = None
+        if data is None:
+            import requests
+
+            r = requests.get(SCRIP_MASTER, timeout=60)
+            r.raise_for_status()
+            data = parse_master(r.json())
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(json.dumps(data), encoding="utf-8")
+        self._tokens, self._tokens_at = data, time.time()
+        return data
+
+    # -------------------------------------------------------------- quotes
+    def quotes(self, symbols: list[str]) -> dict[str, dict]:
+        """NSE symbol -> {price, change, change_percent, volume, time}."""
+        tokens = self._symbol_tokens()
+        wanted = {tokens[s.upper()]: s.upper() for s in symbols if s.upper() in tokens}
+        out: dict[str, dict] = {}
+        ids = list(wanted)
+        for i in range(0, len(ids), BATCH):
+            chunk = ids[i:i + BATCH]
+            body = {"mode": "FULL", "exchangeTokens": {"NSE": chunk}}
+            try:
+                data = _post("/rest/secure/angelbroking/market/v1/quote/", self.config, body, self._session())
+            except AngelError as exc:
+                if not exc.session_expired:
+                    raise  # e.g. rate limit: logging in again would only add calls
+                with self._lock:
+                    self._token = None
+                data = _post("/rest/secure/angelbroking/market/v1/quote/", self.config, body, self._session())
+            for q in (data.get("data") or {}).get("fetched") or []:
+                sym = wanted.get(str(q.get("symbolToken")))
+                ltp = _num(q.get("ltp"))
+                if sym and ltp:
+                    out[sym] = {
+                        "price": ltp,
+                        "change": _num(q.get("netChange")),
+                        "change_percent": _num(q.get("percentChange")),
+                        "volume": _num(q.get("tradeVolume")),
+                        "time": _feed_time(q.get("exchFeedTime")) or time.time(),
+                        **order_book(q),
+                    }
+        return out
+
+
+def order_book(q: dict) -> dict:
+    """FULL-mode extras: pending buy / sell quantity, the best five bids and
+    offers, average traded price and circuit limits. Missing fields are left out."""
+    out = {
+        "buy_qty": _num(q.get("totBuyQuan")),
+        "sell_qty": _num(q.get("totSellQuan")),
+        "avg_price": _num(q.get("avgPrice")),
+        "last_qty": _num(q.get("lastTradeQty")),
+        "upper_circuit": _num(q.get("upperCircuit")),
+        "lower_circuit": _num(q.get("lowerCircuit")),
+    }
+    out = {k: v for k, v in out.items() if v is not None}
+    depth = q.get("depth") or {}
+    sides = {}
+    for side in ("buy", "sell"):
+        levels = [{"price": _num(lv.get("price")), "quantity": _num(lv.get("quantity")), "orders": _num(lv.get("orders"))}
+                  for lv in depth.get(side) or [] if isinstance(lv, dict)]
+        # Empty levels come back as price 0 (no order at that rank).
+        sides[side] = [lv for lv in levels if lv["price"] and lv["quantity"]][:5]
+    if sides["buy"] or sides["sell"]:
+        out["depth"] = sides
+    return out
+
+
+def parse_master(rows: list[dict]) -> dict[str, str]:
+    """NSE cash-market symbols (RELIANCE-EQ, NIFTYBEES-EQ, ...) -> token,
+    keyed by the plain symbol MarketMyna uses (RELIANCE)."""
+    out: dict[str, str] = {}
+    for r in rows:
+        # The live file says "NSE"; the docs' sample says "nse_cm".
+        if r.get("exch_seg") not in ("NSE", "nse_cm") or r.get("instrumenttype"):
+            continue
+        sym = str(r.get("symbol", ""))
+        for series in ("-EQ", "-BE", "-BZ", "-SM", "-ST"):
+            if sym.endswith(series):
+                base = sym[: -len(series)]
+                # Prefer the normal -EQ series when a symbol trades in several.
+                if base not in out or series == "-EQ":
+                    out[base] = str(r.get("token"))
+                break
+    return out
+
+
+def _ist_date(epoch: float):
+    from datetime import datetime
+    from zoneinfo import ZoneInfo
+
+    return datetime.fromtimestamp(epoch, ZoneInfo("Asia/Kolkata")).date()
+
+
+def _feed_time(text: Optional[str]) -> Optional[float]:
+    from datetime import datetime
+    from zoneinfo import ZoneInfo
+
+    if not text:
+        return None
+    try:
+        return datetime.strptime(text, "%d-%b-%Y %H:%M:%S").replace(tzinfo=ZoneInfo("Asia/Kolkata")).timestamp()
+    except ValueError:
+        return None
+
+
+def _num(value) -> Optional[float]:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+_client: Optional[AngelClient] = None
+_client_lock = threading.Lock()
+
+
+def client(config) -> AngelClient:
+    """Shared client; rebuilt when the credentials change."""
+    global _client
+    with _client_lock:
+        key = (config.angel_api_key, config.angel_client_code, config.angel_pin, config.angel_totp_secret)
+        if _client is None or getattr(_client, "_key", None) != key:
+            _client = AngelClient(config)
+            _client._key = key  # type: ignore[attr-defined]
+        return _client