# SMC Toolkit
[](https://opensource.org/licenses/MIT)
[](https://badge.fury.io/py/smc-toolkit)
[](https://www.python.org/downloads/)
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
```bash
pip install smc-toolkit
```
## Quickstart
Here is a brief example of how to analyze the NASDAQ index data from Yahoo Finance.
```python
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.
| Column | Description |
| --------------------- | --------------------------------------------------------------------------- |
| `swing_h_l` | `1` for a new Swing Low, `-1` for a new Swing High. |
| `bos` | `1` for a bullish BOS, `-1` for a bearish BOS. |
| `bos_level` | The price level of the swing point that was broken. |
| `choch` | `2` for a bullish CHoCH, `-2` for a bearish CHoCH. |
| `choch_level` | The price level of the swing point that was broken to cause the CHoCH. |
| `int_...` | The same columns prefixed with `int_` for the internal structure. |
### `ob_df` (Order Blocks) DataFrame
Contains the identified Order Blocks.
| Column | Description |
| ------------ | ----------------------------------------------------------- |
| `ob_time` | Timestamp of the candle that forms the Order Block. |
| `start_time` | Start time of the price leg that led to the CHoCH. |
| `end_time` | End time of the price leg (timestamp of the CHoCH). |
| `ob_top` | Top price level of the Order Block. |
| `ob_bottom` | Bottom price level of the Order Block. |
| `ob_type` | `bullish` or `bearish`. |
### `fvg_df` (Fair Value Gaps) DataFrame
Contains the identified Fair Value Gaps.
| Column | Description |
| ----------- | ----------------------------------------------------------- |
| `fvg_type` | `bullish` or `bearish`. |
| `fvg_top` | Top price level of the FVG. |
| `fvg_bottom`| Bottom price level of the FVG. |
| `fvg_mid` | Mid-point price of the FVG. |
| `mitigated` | `True` if the price has returned to the FVG's mid-point. |
| `start_time`| Start timestamp of the 3-bar pattern forming the FVG. |
| `end_time` | End timestamp of the 3-bar pattern. |
## 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "smc-toolkit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "trading, smart-money, bos, choch, fvg, orderblock",
"author": null,
"author_email": "Luyi Zhao <tysxchina@163.com>",
"download_url": "https://files.pythonhosted.org/packages/7b/04/56df6b0dfc95cb3cca21f27f5ea444dd5eeaa92af4cb1c0941766783e429/smc-toolkit-0.1.0.tar.gz",
"platform": null,
"description": "# SMC Toolkit\r\n\r\n[](https://opensource.org/licenses/MIT)\r\n[](https://badge.fury.io/py/smc-toolkit)\r\n[](https://www.python.org/downloads/)\r\n\r\nA simple, fast, and vectorized Python library for Smart Money Concept (SMC) analysis, perfect for local feature extraction, strategy backtesting, and quantitative analysis.\r\n\r\nThis 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.\r\n\r\n## Features\r\n\r\n- **Vectorized & Fast**: Leverages Pandas and NumPy for efficient calculations.\r\n- **Core SMC Concepts**: Accurately identifies:\r\n - Swing Highs & Lows\r\n - Break of Structure (BOS)\r\n - Change of Character (CHoCH)\r\n - Order Blocks (OB)\r\n - Fair Value Gaps (FVG)\r\n- **Multi-Structure Analysis**: Differentiates between primary (main) and internal market structures.\r\n- **Built-in Visualization**: Includes a ready-to-use Matplotlib function to instantly plot and verify results.\r\n\r\n## Installation\r\n\r\n```bash\r\npip install smc-toolkit\r\n```\r\n\r\n## Quickstart\r\n\r\nHere is a brief example of how to analyze the NASDAQ index data from Yahoo Finance.\r\n\r\n```python\r\nimport pandas as pd\r\nimport smc_toolkit as smc # alias for easier usage\r\n\r\n# === Load sample OHLCV data ===\r\ndf = pd.read_csv(\"assets/data_example.csv\", parse_dates=['date'])\r\ndf = df.rename(columns=str.lower) # ensure lowercase\r\ndf.set_index(['code', 'date'], inplace=True)\r\n\r\n# === Step 1: Extract structure including internal swing points ===\r\nstructure = df.groupby('code', group_keys=False).apply(\r\n smc.process_smc_with_internal,\r\n swing_size=50, # swing detection window (external)\r\n internal_size=5 # smaller window for internal structure\r\n)\r\n\r\n# === Step 2: Extract Order Blocks ===\r\nob_df = structure.groupby('code').apply(smc.extract_ob_blocks).reset_index(drop=True)\r\n\r\n# === Step 3: Extract Fair Value Gaps ===\r\nfvg_df = structure.groupby('code').apply(smc.extract_fvg).reset_index(drop=True)\r\n\r\n# === Step 4: Plot results ===\r\nsmc.plot_smc_structure(\r\n code='000001.XSHE',\r\n result_df=structure,\r\n ob_df=ob_df,\r\n fvg_df=fvg_df,\r\n show_internal=True\r\n)\r\n\r\n```\r\n\r\nRunning the code above will generate a plot similar to this:\r\n\r\n\r\n\r\n\r\n\r\n## Output DataFrames\r\n\r\n### `structure` DataFrame\r\n\r\nThis is the main DataFrame with all candles and their calculated SMC attributes.\r\n\r\n| Column | Description |\r\n| --------------------- | --------------------------------------------------------------------------- |\r\n| `swing_h_l` | `1` for a new Swing Low, `-1` for a new Swing High. |\r\n| `bos` | `1` for a bullish BOS, `-1` for a bearish BOS. |\r\n| `bos_level` | The price level of the swing point that was broken. |\r\n| `choch` | `2` for a bullish CHoCH, `-2` for a bearish CHoCH. |\r\n| `choch_level` | The price level of the swing point that was broken to cause the CHoCH. |\r\n| `int_...` | The same columns prefixed with `int_` for the internal structure. |\r\n\r\n### `ob_df` (Order Blocks) DataFrame\r\n\r\nContains the identified Order Blocks.\r\n\r\n| Column | Description |\r\n| ------------ | ----------------------------------------------------------- |\r\n| `ob_time` | Timestamp of the candle that forms the Order Block. |\r\n| `start_time` | Start time of the price leg that led to the CHoCH. |\r\n| `end_time` | End time of the price leg (timestamp of the CHoCH). |\r\n| `ob_top` | Top price level of the Order Block. |\r\n| `ob_bottom` | Bottom price level of the Order Block. |\r\n| `ob_type` | `bullish` or `bearish`. |\r\n\r\n### `fvg_df` (Fair Value Gaps) DataFrame\r\n\r\nContains the identified Fair Value Gaps.\r\n\r\n| Column | Description |\r\n| ----------- | ----------------------------------------------------------- |\r\n| `fvg_type` | `bullish` or `bearish`. |\r\n| `fvg_top` | Top price level of the FVG. |\r\n| `fvg_bottom`| Bottom price level of the FVG. |\r\n| `fvg_mid` | Mid-point price of the FVG. |\r\n| `mitigated` | `True` if the price has returned to the FVG's mid-point. |\r\n| `start_time`| Start timestamp of the 3-bar pattern forming the FVG. |\r\n| `end_time` | End timestamp of the 3-bar pattern. |\r\n\r\n\r\n## Plotting Legend\r\n\r\nThe `plot_smc_structure` function uses the following visual cues:\r\n\r\n\r\n| Element | Marker / Style | Color | Meaning |\r\n| --------------------- | ------------------------------ | ------------ | ----------------------------------------- |\r\n| Swing High | Downward Triangle (`v`) |  | A confirmed primary swing high point. |\r\n| Swing Low | Upward Triangle (`^`) |  | A confirmed primary swing low point. |\r\n| Bullish BOS | Dashed Horizontal Line |  | Break of Structure to the upside. |\r\n| Bearish BOS | Dashed Horizontal Line |  | Break of Structure to the downside. |\r\n| Bullish CHoCH | Solid Horizontal Line |  | Change of Character to bullish. |\r\n| Bearish CHoCH | Solid Horizontal Line |  | Change of Character to bearish. |\r\n| Bullish Order Block | Shaded Vertical Area |  | A bullish order block zone. |\r\n| Bearish Order Block | Shaded Vertical Area |  | A bearish order block zone. |\r\n| Bullish FVG | Shaded Vertical Area |  | A bullish Fair Value Gap. |\r\n| Bearish FVG | Shaded Vertical Area |  | A bearish Fair Value Gap. |\r\n| Mitigated FVG | Hatched Shaded Area |  | An FVG that has been at least 50% filled. |\r\n| Internal Structures | Smaller markers / Lighter lines|  | All of the above for internal structure. |\r\n\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License.\r\n\r\n\r\n\r\n\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Smart Money Concepts (SMC) analysis toolkit for BOS, CHoCH, FVG, OB, and swing structure.",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/Louisjzhao/smc-toolkit"
},
"split_keywords": [
"trading",
" smart-money",
" bos",
" choch",
" fvg",
" orderblock"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a664e5ca79df2e80e940d8acdd56a5f0b1c8329e6975280b857ab3210abbf884",
"md5": "c186a60ff7da93af62a914c30b80f132",
"sha256": "21f5e0ed5876f1889004b1208d53734a9bc0d9ffebe37783f90afc28b0cbed25"
},
"downloads": -1,
"filename": "smc_toolkit-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c186a60ff7da93af62a914c30b80f132",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 4532,
"upload_time": "2025-07-14T12:27:28",
"upload_time_iso_8601": "2025-07-14T12:27:28.495566Z",
"url": "https://files.pythonhosted.org/packages/a6/64/e5ca79df2e80e940d8acdd56a5f0b1c8329e6975280b857ab3210abbf884/smc_toolkit-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7b0456df6b0dfc95cb3cca21f27f5ea444dd5eeaa92af4cb1c0941766783e429",
"md5": "f75a1669ef96d23b5a24322327d078fa",
"sha256": "9af7f3b1d66e05ee489565b1726bf02acc41ec2d860e3ab1f8729e4a286e948a"
},
"downloads": -1,
"filename": "smc-toolkit-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "f75a1669ef96d23b5a24322327d078fa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 4440,
"upload_time": "2025-07-14T12:27:29",
"upload_time_iso_8601": "2025-07-14T12:27:29.678762Z",
"url": "https://files.pythonhosted.org/packages/7b/04/56df6b0dfc95cb3cca21f27f5ea444dd5eeaa92af4cb1c0941766783e429/smc-toolkit-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-14 12:27:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Louisjzhao",
"github_project": "smc-toolkit",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "numpy",
"specs": []
},
{
"name": "pandas",
"specs": []
},
{
"name": "matplotlib",
"specs": []
}
],
"lcname": "smc-toolkit"
}
JSON
