SMC Toolkit

A simple, fast, and vectorized Python library for Smart Money Concept (SMC) analysis, perfect for local feature extraction, strategy backtesting, and quantitative analysis.

This toolkit is designed for traders and developers who need to programmatically identify SMC structures without relying on third-party charting platforms. Its vectorized nature (powered by Pandas and NumPy) ensures high performance, making it suitable for processing large historical datasets for tasks like training Reinforcement Learning agents.

Features

• Vectorized & Fast: Leverages Pandas and NumPy for efficient calculations.
• Core SMC Concepts: Accurately identifies:
  • Swing Highs & Lows
  • Break of Structure (BOS)
  • Change of Character (CHoCH)
  • Order Blocks (OB)
  • Fair Value Gaps (FVG)
• Multi-Structure Analysis: Differentiates between primary (main) and internal market structures.
• Built-in Visualization: Includes a ready-to-use Matplotlib function to instantly plot and verify results.

Installation

pip install smc-toolkit

Quickstart

Here is a brief example of how to analyze the NASDAQ index data from Yahoo Finance.

import pandas as pd
import smc_toolkit as smc  # alias for easier usage

# === Load sample OHLCV data ===
df = pd.read_csv("assets/data_example.csv", parse_dates=['date'])
df = df.rename(columns=str.lower)  # ensure lowercase
df.set_index(['code', 'date'], inplace=True)

# === Step 1: Extract structure including internal swing points ===
structure = df.groupby('code', group_keys=False).apply(
    smc.process_smc_with_internal,
    swing_size=50,       # swing detection window (external)
    internal_size=5     # smaller window for internal structure
)

# === Step 2: Extract Order Blocks ===
ob_df = structure.groupby('code').apply(smc.extract_ob_blocks).reset_index(drop=True)

# === Step 3: Extract Fair Value Gaps ===
fvg_df = structure.groupby('code').apply(smc.extract_fvg).reset_index(drop=True)

# === Step 4: Plot results ===
smc.plot_smc_structure(
    code='000001.XSHE',
    result_df=structure,
    ob_df=ob_df,
    fvg_df=fvg_df,
    show_internal=True
)

Running the code above will generate a plot similar to this:

Output DataFrames

structure DataFrame

This is the main DataFrame with all candles and their calculated SMC attributes.

ob_df (Order Blocks) DataFrame

Contains the identified Order Blocks.

fvg_df (Fair Value Gaps) DataFrame

Contains the identified Fair Value Gaps.

Plotting Legend

The plot_smc_structure function uses the following visual cues:

Element	Marker / Style	Color	Meaning
Swing High	Downward Triangle (v)		A confirmed primary swing high point.
Swing Low	Upward Triangle (^)		A confirmed primary swing low point.
Bullish BOS	Dashed Horizontal Line		Break of Structure to the upside.
Bearish BOS	Dashed Horizontal Line		Break of Structure to the downside.
Bullish CHoCH	Solid Horizontal Line		Change of Character to bullish.
Bearish CHoCH	Solid Horizontal Line		Change of Character to bearish.
Bullish Order Block	Shaded Vertical Area		A bullish order block zone.
Bearish Order Block	Shaded Vertical Area		A bearish order block zone.
Bullish FVG	Shaded Vertical Area		A bullish Fair Value Gap.
Bearish FVG	Shaded Vertical Area		A bearish Fair Value Gap.
Mitigated FVG	Hatched Shaded Area		An FVG that has been at least 50% filled.
Internal Structures	Smaller markers / Lighter lines		All of the above for internal structure.

License

This project is licensed under the MIT License.