# Smc Python Library

> smc-python-library

- Skill: `mahmoud20138/smc-python-library` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mahmoud20138/smc-python-library`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mahmoud20138/smc-python-library/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mahmoud20138 (https://skillmd.com/u/mahmoud20138)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mahmoud20138/smc-python-library

---


# smc-python-library

USE FOR:
  - "SMC indicators in Python"
  - "FVG / order block / BOS / CHoCH detection in code"
  - "ICT kill zones in Python"
  - "smart money concepts library"
  - "programmatic SMC analysis on OHLC data"
  - "liquidity sweeps detection Python"
tags: [SMC, ICT, Python, FVG, order-blocks, BOS, CHoCH, liquidity, swing-highs-lows, kill-zones]
kind: library
category: ict-smart-money

---

## What Is smartmoneyconcepts?

Python library implementing all core ICT/SMC indicators on OHLC DataFrames.
- Repo: https://github.com/joshyattridge/smart-money-concepts
- Install: `pip install smartmoneyconcepts`
- Input: pandas DataFrame with columns `["open", "high", "low", "close", "volume"]`

---

## Installation

```bash
pip install smartmoneyconcepts
```

```python
from smartmoneyconcepts import smc
import pandas as pd
```

---

## Full API Reference

### 1. Fair Value Gap (FVG)

```python
fvg = smc.fvg(ohlc, join_consecutive=False)
```

**Returns per row:**
- `FVG`: `1` (bullish gap) · `-1` (bearish gap) · `NaN` (no gap)
- `Top`: upper boundary of the gap
- `Bottom`: lower boundary of the gap
- `MitigatedIndex`: candle index that closed/filled the gap

**Concept:**
```
Bullish FVG:  candle[i-1].high < candle[i+1].low   → gap above
Bearish FVG:  candle[i-1].low  > candle[i+1].high  → gap below
```

**Parameters:**
- `join_consecutive=True`: merges adjacent FVGs → single zone (highest top, lowest bottom)

---

### 2. Swing Highs and Lows

```python
swings = smc.swing_highs_lows(ohlc, swing_length=50)
```

**Returns:**
- `HighLow`: `1` (swing high) · `-1` (swing low) · `NaN`
- `Level`: price of the swing point

**Concept:**
```
Swing High: highest high within swing_length candles before AND after
Swing Low:  lowest low  within swing_length candles before AND after
```

---

### 3. Break of Structure (BOS) & Change of Character (CHoCH)

```python
# Requires swing_highs_lows output first
swings = smc.swing_highs_lows(ohlc, swing_length=50)
structure = smc.bos_choch(ohlc, swings, close_break=True)
```

**Returns:**
- `BOS`: `1` (bullish BOS) · `-1` (bearish BOS)
- `CHOCH`: `1` (bullish CHoCH) · `-1` (bearish CHoCH)
- `Level`: price level that was broken
- `BrokenIndex`: candle that broke the level

**`close_break` parameter:**
```
True  → break confirmed only when candle CLOSES beyond level
False → break on wick touch (high/low crosses level)
```

**BOS vs CHoCH:**
```
BOS   → continuation: structure break in direction of trend
CHoCH → reversal: structure break AGAINST current trend direction
```

---

### 4. Order Blocks (OB)

```python
swings = smc.swing_highs_lows(ohlc, swing_length=50)
ob = smc.ob(ohlc, swings, close_mitigation=False)
```

**Returns:**
- `OB`: `1` (bullish OB) · `-1` (bearish OB)
- `Top`: upper boundary
- `Bottom`: lower boundary
- `OBVolume`: sum of current + 2 previous candle volumes
- `Percentage`: strength = `min(highVol, lowVol) / max(highVol, lowVol)`

**Strength interpretation:**
```
Percentage → 1.0 (100%) = equal bull/bear volume = strongest OB
Percentage → 0.1 (10%)  = highly imbalanced = weaker OB
```

---

### 5. Liquidity

```python
swings = smc.swing_highs_lows(ohlc, swing_length=50)
liq = smc.liquidity(ohlc, swings, range_percent=0.01)
```

**Returns:**
- `Liquidity`: `1` (buy-side) · `-1` (sell-side)
- `Level`: price of liquidity cluster
- `End`: index of last swing in the cluster
- `Swept`: index of candle that swept the liquidity

**Concept:**
```
Multiple swing highs within range_percent (1%) of each other
→ clustered stops/liquidity pool above = buy-side liquidity
→ price will likely sweep these before reversing
```

---

### 6. Previous High and Low

```python
prev_hl = smc.previous_high_low(ohlc, time_frame="1D")
```

**Returns:**
- `PreviousHigh` · `PreviousLow`
- `BrokenHigh`: `1` when price breaks prior period high
- `BrokenLow`: `1` when price breaks prior period low

**Supported timeframes:** `"15m"` · `"1H"` · `"4H"` · `"1D"` · `"1W"` · `"1M"`

---

### 7. Sessions (Kill Zones)

```python
session = smc.sessions(ohlc, session="London open kill zone",
                        start_time=None, end_time=None, time_zone="UTC")
```

**Built-in sessions:**
```
"Sydney"                    "Tokyo"
"London"                    "New York"
"Asian kill zone"           "London open kill zone"
"New York kill zone"        "london close kill zone"
"Custom"                    → requires start_time + end_time "HH:MM"
```

**Returns:**
- `Active`: `1` if candle is within session · `0` if not
- `High`: session high so far
- `Low`: session low so far

---

### 8. Retracements

```python
swings = smc.swing_highs_lows(ohlc, swing_length=50)
ret = smc.retracements(ohlc, swings)
```

**Returns:**
- `Direction`: `1` (bullish move) · `-1` (bearish move)
- `CurrentRetracement%`: current retracement from last swing
- `DeepestRetracement%`: max retracement seen in this move

---

## Complete Usage Example

```python
from smartmoneyconcepts import smc
import pandas as pd

# Load OHLCV data (lowercase columns required)
df = pd.read_csv("EURUSD_H1.csv")
df.columns = ["open", "high", "low", "close", "volume"]

# Step 1: Swing structure (prerequisite for most indicators)
swings = smc.swing_highs_lows(df, swing_length=20)

# Step 2: Market structure
structure = smc.bos_choch(df, swings, close_break=True)

# Step 3: Order blocks
ob = smc.ob(df, swings, close_mitigation=False)

# Step 4: Fair value gaps
fvg = smc.fvg(df, join_consecutive=True)

# Step 5: Liquidity pools
liq = smc.liquidity(df, swings, range_percent=0.005)

# Step 6: Session filter (only trade London open kill zone)
session = smc.sessions(df, session="London open kill zone")

# Step 7: Previous day high/low
prev_hl = smc.previous_high_low(df, time_frame="1D")

# Combine: find bullish OBs that are active during London kill zone
bullish_ob = ob[ob["OB"] == 1]
london_active = session[session["Active"] == 1]
confluence = bullish_ob.index.intersection(london_active.index)
print(f"Bullish OBs during London KZ: {len(confluence)}")
```

---

## ICT Strategy Pattern: OB + FVG + BOS Confluence

```python
def find_confluences(df, swing_length=20):
    swings  = smc.swing_highs_lows(df, swing_length)
    bos     = smc.bos_choch(df, swings, close_break=True)
    ob      = smc.ob(df, swings)
    fvg     = smc.fvg(df)
    liq     = smc.liquidity(df, swings, range_percent=0.005)

    signals = []
    for i in df.index:
        bullish = (
            ob.loc[i, "OB"] == 1 if i in ob.index else False,      # Bullish OB
            fvg.loc[i, "FVG"] == 1 if i in fvg.index else False,   # Bullish FVG
            bos.loc[i, "BOS"] == 1 if i in bos.index else False,   # BOS up
        )
        if all(bullish):
            signals.append({"index": i, "type": "LONG", "level": ob.loc[i, "Bottom"]})

    return pd.DataFrame(signals)
```


---