smart-money-heatmap 0.2.0

Smart Money Concepts signal heatmap for NSE instruments via Nubra SDK.

smart-money-heatmap

Score NSE instruments against eight Smart Money Concepts signals and get a single aggregate conviction score — bullish, bearish, or neutral.

Built on top of the Nubra Python SDK for live NSE market data.

---

Project Description

smart-money-heatmap analyses every instrument you give it across eight institutional-behaviour signals:

Signal	What it detects
VWAP Deviation	How far price has moved from the intraday volume-weighted average
OI Wall Proximity	Nearest significant options open-interest support / resistance wall
Break of Structure (BOS)	Price closing beyond a confirmed swing high or swing low
Change of Character (CHoCH)	A structural reversal — break against the prior trend
Imbalance / Displacement	A high-volume, wide-body candle signalling institutional entry
Fair Value Gap (FVG)	An unfilled price gap between candle 1 and candle 3
Order Block	Net score across all active unmitigated order block zones
Liquidity	Current volume vs session baseline, used as a confidence multiplier

Each signal scores from −100 (bearish) to +100 (bullish). The aggregate score is a weighted average of all signals, penalised for inter-signal conflict and scaled by session liquidity.

---

Install

pip install smart-money-heatmap

Requires Python ≥ 3.9 and an authenticated Nubra account for live data.

---

Usage

Python

from nubra_python_sdk.start_sdk import InitNubraSdk, NubraEnv
from smart_money_heatmap import SmartMoneyHeatmap

nubra  = InitNubraSdk(NubraEnv.PROD, env_creds=True)
hm     = SmartMoneyHeatmap(sdk=nubra)

result = hm.compute(
    instruments=["HDFCBANK", "RELIANCE", "SBIN", "NIFTY"],
    timeframe="5m",            # 1m | 5m | 15m | 1h | 1d
    include_option_chain=True, # set False to skip OI Wall (faster)
)

CLI

smheatmap --symbols HDFCBANK RELIANCE SBIN NIFTY --timeframe 5m

---

Output Format

Score interpretation

Score	Verdict
> +60	🟢 Strongly Bullish
+25 to +60	🟢 Bullish
+15 to +25	🟡 Mildly Bullish
−15 to +15	⚪ Neutral
−25 to −15	🟠 Mildly Bearish
−60 to −25	🔴 Bearish
< −60	🔴 Strongly Bearish

▲ signal is bullish  ·  ▼ signal is bearish  ·  — neutral or no edge

---

Raw Data

Behind the printed output, everything is plain Python dicts and DataFrames.

result.data — scores only

result.data
# {
#   "HDFCBANK": {"liquidity": 19.3, "vwap": 0.0, "oi_wall": 0.0, "bos": 0.0,
#                "choch": 0.0, "imbalance": 0.0, "fvg": 9.4, "order_block": 0.0,
#                "aggregate": 0.7},
#   "RELIANCE": {"liquidity": 27.6, "vwap": 56.4, "oi_wall": 0.0, "bos": 28.3,
#                "choch": 0.0, "imbalance": 40.0, "fvg": 58.0, "order_block": 64.5,
#                "aggregate": 25.8},
#   ...
# }

result.explain("RELIANCE") — full breakdown per instrument

result.explain("RELIANCE")
# {
#   "symbol": "RELIANCE",
#   "current_price": 1452.30,
#   "timeframe": "5m",
#   "data_quality": {"ok": True, "status": "valid", "reason": "..."},
#   "summary": "RELIANCE is bullish with medium confidence. Aggregate score: +25.8.",
#
#   "signals": {
#     "vwap": {
#       "name":        "vwap",
#       "score":       56.4,
#       "status":      "valid",
#       "direction":   "bullish",
#       "confidence":  0.564,
#       "directional": True,
#       "reason":      "Price is 0.52% above VWAP, showing bullish intraday positioning.",
#       "debug": {
#         "close": 1452.30, "vwap": 1444.80,
#         "distance_percent": 0.52, "session_rows": 35
#       }
#     },
#     "order_block": {
#       "name":        "order_block",
#       "score":       64.5,
#       "status":      "valid",
#       "direction":   "bullish",
#       "confidence":  0.645,
#       "directional": True,
#       "reason":      "Net OB score +64.5 from 3 active zone(s) (2 bullish, 1 bearish).",
#       "debug": {
#         "net_score": 64.5,
#         "current_price": 1452.30,
#         "active_ob_zones": [
#           {"type": "bullish", "low": 1440.0, "high": 1445.0,
#            "score": 72.1, "distance_percent": 0.5, "mitigated": False, ...},
#           ...
#         ],
#         "detected_bullish_ob_zones": [...],
#         "detected_bearish_ob_zones": [...]
#       }
#     },
#     # ... same structure for: liquidity, oi_wall, bos, choch, imbalance, fvg
#   },
#
#   "aggregate": {
#     "score":       25.8,
#     "bias":        "bullish",
#     "confidence":  "medium",
#     "explanation": "Aggregate score is +25.8, bias is bullish, confidence is medium.",
#     "bullish_reasons": ["vwap: Price is 0.52% above VWAP...", "bos: Bullish BOS...", ...],
#     "bearish_reasons": [],
#     "neutral_or_missing_reasons": ["choch: No CHoCH detected.", ...],
#     "debug": {
#       "raw_score": 29.1, "adjusted_score": 25.8,
#       "conflict_ratio": 0.0, "liquidity_confidence": 1.08,
#       "availability_ratio": 0.9, "bullish_pressure": 18.4, "bearish_pressure": 0.0
#     }
#   }
# }

result.to_dataframe() — signals × instruments

result.to_dataframe()
#              HDFCBANK  RELIANCE   SBIN  NIFTY
# liquidity        19.3      27.6   24.2   23.0
# vwap              0.0      56.4   29.0   26.3
# oi_wall           0.0       0.0    0.0    0.0
# bos               0.0      28.3    0.0   32.1
# choch             0.0       0.0    0.0    0.0
# imbalance         0.0      40.0  -32.5    0.0
# fvg               9.4      58.0   35.9   -8.7
# order_block       0.0      64.5    6.4   20.1
# aggregate         0.7      25.8    1.6    5.7

---

Result API

result.to_dataframe()        # pd.DataFrame  —  signals × instruments
result.status_dataframe()    # signal statuses per instrument
result.reasons_dataframe()   # one-line reason per signal per instrument
result.top_n(3)              # top 3 instruments by aggregate score
result.explain("RELIANCE")   # full breakdown dict for one instrument
result.to_html()             # HTML table for notebooks / dashboards

---

Configuration

Override signal defaults via the config parameter:

result = hm.compute(
    instruments=["NIFTY"],
    timeframe="5m",
    config={
        "signals": {
            "bos":         {"min_break_percent": 0.02},
            "choch":       {"min_break_percent": 0.02},
            "order_block": {"displacement_volume_ratio": 1.5},
        }
    },
)

---

License

MIT