Seed DSE issued shares and transaction fees

App/routers/stocks/crud.py

@@ -378,6 +378,7 @@ async def get_market_highlights(limit: int = 5) -> Dict:
             "turnover": profile.turnover,
             "deals": profile.deals,
             "market_cap": profile.market_cap,
+            "total_shares_issued": profile.total_shares_issued,
             "logo_url": profile.logo_url,
             "market_segment": profile.market_segment,
         }

App/routers/stocks/dse_transaction_fees.json

@@ -0,0 +1,41 @@
+{
+  "schema_version": 1,
+  "currency": "TZS",
+  "unit": "percent_of_consideration",
+  "source_note": "DSE equity transaction cost table supplied for seed data on 2026-05-13.",
+  "bands": [
+    {
+      "label": "Up to 10 mln",
+      "min_consideration": 0,
+      "max_consideration": 10000000,
+      "brokerage_commission": 1.70,
+      "transaction_fee_cmsa": 0.14,
+      "transaction_fee_dse": 0.14,
+      "fidelity_fee": 0.02,
+      "csd_fee": 0.06,
+      "total_cost_to_investor": 2.06
+    },
+    {
+      "label": "Next 40 mln",
+      "min_consideration": 10000000,
+      "max_consideration": 50000000,
+      "brokerage_commission": 1.50,
+      "transaction_fee_cmsa": 0.14,
+      "transaction_fee_dse": 0.14,
+      "fidelity_fee": 0.02,
+      "csd_fee": 0.06,
+      "total_cost_to_investor": 1.86
+    },
+    {
+      "label": "Above 50 mln",
+      "min_consideration": 50000000,
+      "max_consideration": null,
+      "brokerage_commission": 0.80,
+      "transaction_fee_cmsa": 0.14,
+      "transaction_fee_dse": 0.14,
+      "fidelity_fee": 0.02,
+      "csd_fee": 0.06,
+      "total_cost_to_investor": 1.16
+    }
+  ]
+}

App/routers/stocks/routes.py

@@ -26,7 +26,7 @@ from .crud import (
 )
 from .service import fetch_dse_stock_data
 from .metrics import calculate_metrics
-from .models import Stock, StockPriceData, Dividend
+from .models import Stock, StockPriceData, Dividend, StockProfile
 from .news_service import (
     build_news_queries,
     extract_article_content,
@@ -42,6 +42,7 @@ from typing import Dict, List, Optional
 from datetime import datetime, timedelta, date
 from .utils import AsyncCurlCffiDividendScraper, run_stock_import_task
 from .dse import DseScraper
+from .seed import load_dse_transaction_fee_seed_data
 from App.routers.users.utils import get_current_user
 
 router = APIRouter(prefix="/stocks", tags=["stocks"])
@@ -100,6 +101,7 @@ async def list_stocks_orm():
                 "low": float(latest.low) if latest else (float(profile.day_low) if profile and profile.day_low is not None else None),
                 "volume": latest.volume if latest else (profile.volume if profile else None),
                 "market_cap": latest.market_cap if latest else (profile.market_cap if profile else None),
+                "total_shares_issued": profile.total_shares_issued if profile else None,
                 "latest_date": latest.date.isoformat() if latest else None,
                 "logo_url": profile.logo_url if profile else None,
                 "security_type": profile.security_type if profile else None,
@@ -117,6 +119,38 @@ async def list_stocks_orm():
         raise AppException(status_code=500, message=f"Error retrieving stocks: {str(e)}")
 
 
+@router.get("/reference/issued-shares", response_model=ResponseModel)
+async def list_issued_shares():
+    profiles = await StockProfile.all().select_related("stock").order_by("stock__symbol")
+    data = [
+        {
+            "symbol": profile.stock.symbol,
+            "name": profile.stock.name,
+            "isin": profile.security_id,
+            "security_type": profile.security_type,
+            "issued_shares": profile.total_shares_issued,
+            "source": profile.source,
+        }
+        for profile in profiles
+        if profile.total_shares_issued is not None
+    ]
+    return ResponseModel(
+        success=True,
+        message="Issued share reference data retrieved",
+        data={"stocks": data, "count": len(data)},
+    )
+
+
+@router.get("/reference/transaction-fees", response_model=ResponseModel)
+async def get_dse_transaction_fees():
+    payload = load_dse_transaction_fee_seed_data()
+    return ResponseModel(
+        success=True,
+        message="DSE transaction fee seed data retrieved",
+        data=payload,
+    )
+
+
 @router.get("/{symbol}/price/{price_date}", response_model=ResponseModel)
 async def get_stock_price_by_date(symbol: str, price_date: str):
     """Return the closing price for a stock on a given date (or nearest prior trading day)."""

App/routers/stocks/seed.py

@@ -3,10 +3,12 @@ from datetime import date
 from pathlib import Path
 from decimal import Decimal, InvalidOperation
 
-from .models import Stock, StockCompanyInfo, Dividend
+from .models import Stock, StockCompanyInfo, StockProfile, Dividend
 
 STOCK_COMPANY_DATA_PATH = Path(__file__).parent / "stock_company_data.json"
 STOCK_DIVIDEND_DATA_PATH = Path(__file__).parent / "stock_dividends_data.json"
+STOCK_REFERENCE_DATA_PATH = Path(__file__).parent / "stock_reference_data.json"
+DSE_TRANSACTION_FEES_PATH = Path(__file__).parent / "dse_transaction_fees.json"
 
 
 def load_stock_company_seed_data() -> dict:
@@ -23,6 +25,20 @@ def load_stock_dividend_seed_data() -> dict:
         return {"dividends": []}
 
 
+def load_stock_reference_seed_data() -> dict:
+    try:
+        return json.loads(STOCK_REFERENCE_DATA_PATH.read_text(encoding="utf-8"))
+    except Exception:
+        return {"stocks": []}
+
+
+def load_dse_transaction_fee_seed_data() -> dict:
+    try:
+        return json.loads(DSE_TRANSACTION_FEES_PATH.read_text(encoding="utf-8"))
+    except Exception:
+        return {"bands": []}
+
+
 def _clip(value: str | None, max_length: int) -> str | None:
     if value is None:
         return None
@@ -125,3 +141,31 @@ async def sync_stock_dividends_from_json() -> int:
             synced += 1
 
     return synced
+
+
+async def sync_stock_reference_data_from_json() -> int:
+    payload = load_stock_reference_seed_data()
+    synced = 0
+
+    for entry in payload.get("stocks", []):
+        symbol = str(entry.get("symbol") or "").strip().upper()
+        issued_shares = entry.get("issued_shares")
+        if not symbol or issued_shares is None:
+            continue
+
+        stock = await Stock.get_or_none(symbol=symbol)
+        if stock is None:
+            stock = await Stock.create(symbol=symbol, name=entry.get("legal_name") or symbol)
+        elif entry.get("legal_name") and stock.name == stock.symbol:
+            stock.name = entry["legal_name"]
+            await stock.save(update_fields=["name", "updated_at"])
+
+        profile, _ = await StockProfile.get_or_create(stock=stock)
+        profile.security_id = _clip(entry.get("isin"), 50)
+        profile.security_type = _clip(entry.get("security_type"), 30)
+        profile.total_shares_issued = int(issued_shares)
+        profile.source = _clip(payload.get("source_name"), 50)
+        await profile.save()
+        synced += 1
+
+    return synced

App/routers/stocks/stock_reference_data.json

@@ -0,0 +1,262 @@
+{
+  "schema_version": 1,
+  "last_verified_at": "2026-05-13",
+  "source_name": "CSD & Registry Company Limited Issuer Companies List",
+  "source_url": "https://csdr.co.tz/content/issuer-companies-list",
+  "stocks": [
+    {
+      "symbol": "CRDB",
+      "legal_name": "CRDB Bank PLC",
+      "isin": "TZ1996100305",
+      "issued_shares": 2611838584,
+      "security_type": "Equity",
+      "listing_date": "2009-06-17",
+      "listing_class": "domestic"
+    },
+    {
+      "symbol": "DSE",
+      "legal_name": "Dar es Salaam Stock Exchange PLC",
+      "isin": "TZ1996102434",
+      "issued_shares": 23824020,
+      "security_type": "Equity",
+      "listing_date": "2016-07-12",
+      "listing_class": "domestic"
+    },
+    {
+      "symbol": "DCB",
+      "legal_name": "DCB Commercial Bank PLC",
+      "isin": "TZ1996100214",
+      "issued_shares": 195293826,
+      "security_type": "Equity",
+      "listing_date": "2008-09-16",
+      "listing_class": "domestic"
+    },
+    {
+      "symbol": "JATU",
+      "legal_name": "JATU Public Limited Company",
+      "isin": "TZ1996103804",
+      "issued_shares": 19938837,
+      "security_type": "Equity",
+      "listing_date": "2020-11-23",
+      "listing_class": "domestic"
+    },
+    {
+      "symbol": "MBP",
+      "legal_name": "Maendeleo Bank PLC",
+      "isin": "TZ1996101683",
+      "issued_shares": 26431550,
+      "security_type": "Equity",
+      "listing_date": "2013-11-04",
+      "listing_class": "domestic"
+    },
+    {
+      "symbol": "MKCB",
+      "legal_name": "Mkombozi Commercial Bank PLC",
+      "isin": "TZ1996101972",
+      "issued_shares": 23555002,
+      "security_type": "Equity",
+      "listing_date": "2014-12-29",
+      "listing_class": "domestic"
+    },
+    {
+      "symbol": "MUCOBA",
+      "legal_name": "MUCOBA Bank PLC",
+      "isin": "TZ1996102418",
+      "issued_shares": 32666227,
+      "security_type": "Equity",
+      "listing_date": "2016-06-08",
+      "listing_class": "domestic"
+    },
+    {
+      "symbol": "MCB",
+      "legal_name": "Mwalimu Commercial Bank PLC",
+      "isin": "TZ1996102129",
+      "issued_shares": 61824920,
+      "security_type": "Equity",
+      "listing_date": "2015-11-27",
+      "listing_class": "domestic"
+    },
+    {
+      "symbol": "NICO",
+      "legal_name": "National Investment Company Limited",
+      "isin": "TZ1996103077",
+      "issued_shares": 61644834,
+      "security_type": "Equity",
+      "listing_date": "2018-06-06",
+      "listing_class": "domestic"
+    },
+    {
+      "symbol": "NMB",
+      "legal_name": "National Microfinance Bank PLC",
+      "isin": "TZ1996100222",
+      "issued_shares": 500000000,
+      "security_type": "Equity",
+      "listing_date": "2008-11-06",
+      "listing_class": "domestic"
+    },
+    {
+      "symbol": "PAL",
+      "legal_name": "Precision Air Services PLC",
+      "isin": "TZ1996101048",
+      "issued_shares": 160469800,
+      "security_type": "Equity",
+      "listing_date": "2011-12-21",
+      "listing_class": "domestic"
+    },
+    {
+      "symbol": "SWALA",
+      "legal_name": "Swala Oil and Gas Tanzania PLC",
+      "isin": "TZ1996101865",
+      "issued_shares": 106201621,
+      "security_type": "Equity",
+      "listing_date": "2014-08-11",
+      "listing_class": "domestic"
+    },
+    {
+      "symbol": "SWIS",
+      "legal_name": "Swissport Tanzania PLC",
+      "isin": "TZ1996100040",
+      "issued_shares": 36000000,
+      "security_type": "Equity",
+      "listing_date": "2003-06-03",
+      "listing_class": "domestic"
+    },
+    {
+      "symbol": "TCCL",
+      "legal_name": "Tanga Cement PLC",
+      "isin": "TZ1996100057",
+      "issued_shares": 63671045,
+      "security_type": "Equity",
+      "listing_date": "2002-09-26",
+      "listing_class": "domestic"
+    },
+    {
+      "symbol": "TBL",
+      "legal_name": "Tanzania Breweries Limited PLC",
+      "isin": "TZ1996100016",
+      "issued_shares": 295056063,
+      "security_type": "Equity",
+      "listing_date": "1998-09-19",
+      "listing_class": "domestic"
+    },
+    {
+      "symbol": "TCC",
+      "legal_name": "Tanzania Cigarette Company Limited",
+      "isin": "TZ1996100032",
+      "issued_shares": 100000000,
+      "security_type": "Equity",
+      "listing_date": "2000-11-16",
+      "listing_class": "domestic"
+    },
+    {
+      "symbol": "TPCC",
+      "legal_name": "Tanzania Portland Cement Company Limited",
+      "isin": "TZ1996100024",
+      "issued_shares": 179923100,
+      "security_type": "Equity",
+      "listing_date": "2006-09-29",
+      "listing_class": "domestic"
+    },
+    {
+      "symbol": "TTP",
+      "legal_name": "TATEPA Limited",
+      "isin": "TZ1996100065",
+      "issued_shares": 95057184,
+      "security_type": "Equity",
+      "listing_date": "1999-12-07",
+      "listing_class": "domestic"
+    },
+    {
+      "symbol": "AFRIPRISE",
+      "aliases": ["TICL"],
+      "legal_name": "Afriprise Investment PLC",
+      "isin": "TZ1996103010",
+      "issued_shares": 146034913,
+      "security_type": "Equity",
+      "listing_date": "2018-03-16",
+      "listing_class": "domestic"
+    },
+    {
+      "symbol": "TOL",
+      "legal_name": "TOL Gases PLC",
+      "isin": "TZ1996100008",
+      "issued_shares": 57505963,
+      "security_type": "Equity",
+      "listing_date": "1998-04-15",
+      "listing_class": "domestic"
+    },
+    {
+      "symbol": "VODA",
+      "legal_name": "Vodacom Tanzania PLC",
+      "isin": "TZ1996102715",
+      "issued_shares": 2240000300,
+      "security_type": "Equity",
+      "listing_date": "2017-08-15",
+      "listing_class": "domestic"
+    },
+    {
+      "symbol": "YETU",
+      "legal_name": "Yetu Microfinance PLC",
+      "isin": "TZ1996102343",
+      "issued_shares": 12112894,
+      "security_type": "Equity",
+      "listing_date": "2016-03-10",
+      "listing_class": "domestic"
+    },
+    {
+      "symbol": "EABL",
+      "legal_name": "East African Breweries Limited",
+      "isin": "KE0000000216",
+      "issued_shares": 790774356,
+      "security_type": "Equity",
+      "listing_date": "2005-06-29",
+      "listing_class": "foreign_cross_listed"
+    },
+    {
+      "symbol": "JHL",
+      "legal_name": "Jubilee Holdings Limited",
+      "isin": "KE0000000273",
+      "issued_shares": 72472950,
+      "security_type": "Equity",
+      "listing_date": "2006-12-20",
+      "listing_class": "foreign_cross_listed"
+    },
+    {
+      "symbol": "KA",
+      "legal_name": "Kenya Airways Limited",
+      "isin": "KE0000000307",
+      "issued_shares": 5681423711,
+      "security_type": "Equity",
+      "listing_date": "2004-10-01",
+      "listing_class": "foreign_cross_listed"
+    },
+    {
+      "symbol": "KCB",
+      "legal_name": "KCB Group Limited",
+      "isin": "KE0000000315",
+      "issued_shares": 2970340000,
+      "security_type": "Equity",
+      "listing_date": "2008-12-23",
+      "listing_class": "foreign_cross_listed"
+    },
+    {
+      "symbol": "NMG",
+      "legal_name": "Nation Media Group",
+      "isin": "KE0000000380",
+      "issued_shares": 188542286,
+      "security_type": "Equity",
+      "listing_date": "2014-06-12",
+      "listing_class": "foreign_cross_listed"
+    },
+    {
+      "symbol": "USL",
+      "legal_name": "Uchumi Supermarket Limited",
+      "isin": "KE0000000489",
+      "issued_shares": 364965594,
+      "security_type": "Equity",
+      "listing_date": "2014-08-15",
+      "listing_class": "foreign_cross_listed"
+    }
+  ]
+}
+

db.py

@@ -69,6 +69,7 @@ async def init_db():
     await ensure_user_auth_profile_schema()
     await ensure_admin_schema()
     await ensure_stock_news_schema()
+    await sync_stock_reference_seed_data()
     await sync_fund_info_seed_data()
     await sync_stock_company_seed_data()
     await sync_stock_dividend_seed_data()
@@ -154,6 +155,16 @@ async def sync_stock_company_seed_data():
         return
 
 
+async def sync_stock_reference_seed_data():
+    """Populate stock issued-share reference data from the bundled seed JSON."""
+    try:
+        from App.routers.stocks.seed import sync_stock_reference_data_from_json
+
+        await sync_stock_reference_data_from_json()
+    except Exception:
+        return
+
+
 async def sync_stock_dividend_seed_data():
     """Populate curated stock dividend history from bundled research JSON."""
     try: