Contracts Module Reference

The contracts/ directory in tradingview-strategy defines shared constants, color maps, session timing, macro windows, and the StrategyFlags schema. Every interpreter and the engine import from these modules to ensure consistent behavior.

All modules are re-exported from src/contracts/index.js:

export * from './indicator-names.js';
export * from './session-times.js';
export * from './macro-windows.js';
export * from './colors.js';
export * from './signal-schema.js';

---

colors.js -- Color Normalization & Constants

TradingView returns colors in multiple formats: ARGB 32-bit integers (e.g., 4289734556), hex strings, and rgb()/rgba() strings. The contracts module normalizes all of these to a canonical #rrggbb lowercase hex format.

normalizeColor(raw)

Converts any color representation to lowercase 6-character hex.

Input format	Example	Output
#rrggbb	#ff0000	#ff0000 (passthrough)
#rrggbbaa	#ff0000cc	#ff0000 (alpha stripped)
#rgb	#f00	#ff0000 (expanded)
rgb(r,g,b)	rgb(255,0,0)	#ff0000
rgba(r,g,b,a)	rgba(0,128,255,0.5)	#0080ff
ARGB integer	4289734556	#b0279c
Numeric string	"4289734556"	#b0279c
null / undefined	--	#000000

ARGB integer decoding: TradingView internally stores colors as unsigned 32-bit ARGB values. The alpha channel (bits 24-31) is discarded; only R (bits 16-23), G (bits 8-15), and B (bits 0-7) are used.

colorsMatch(a, b, tolerance = 10)

Fuzzy comparison of two colors with per-channel tolerance (0-255). Both inputs are normalized before comparison.

colorsMatch('#ff0000', '#f50505', 10);  // true  (within tolerance)
colorsMatch('#ff0000', '#00ff00', 10);  // false (way outside)
colorsMatch('rgb(255,0,0)', '#ff0000'); // true  (normalizes first)

Color Constant Maps

All hex values below are verified from live TradingView chart data.

BIAS_COLORS

Key	Hex	Meaning
level	#b0279c	PDH/PDL/PWH/PWL level lines
separator	#453a36	Day/week separator lines

SESSION_COLORS

Key	Hex	Meaning
macro	#b73a67	Macro window boundary lines
ext_swept	#888888	Swept extension (gray dashed)
ext_lo	#44bb44	Active low extension (green solid)
ext_hi	#ff4444	Active high extension (red solid)
reext	#ff9900	Re-extended range (orange)

OB_COLORS

Key	Hex	Meaning
bear_line	#00009b	Bearish OB lines -- blue, drawn ABOVE price
bull_line	#ff6229	Bullish OB lines -- orange, drawn BELOW price
bear_mid	#00009b	Bearish OB midline
bull_mid	#ff6229	Bullish OB midline

Color-position convention

Blue (#00009b) lines are above price = bearish order blocks (resistance/sell zones). Orange (#ff6229) lines are below price = bullish order blocks (support/buy zones).

SMT_COLORS

Key	Hex	Meaning
bull	#000000	Default bullish SMT color (black)
bear	#000000	Default bearish SMT color (black)

---

indicator-names.js -- Canonical Study Filters

These strings are used as the study_filter parameter when calling MCP Pine graphics tools. They must match the study names returned by chart.getState(), which may differ from the Pine Script indicator() title.

Constant	Value	Indicator
BIAS_AI	'HTF Bias AI'	HTF Bias AI indicator
SESSION_HUNT_AI	'Session Bias'	Session Hunt AI indicator
OB_AI	'OB AI'	Order Block AI indicator
SMT_DIVERGENCES	'SMT AI'	SMT Divergences indicator

The ALL_INDICATORS array exports all four names for batch operations.

---

session-times.js -- Session Windows & Entry Timing

All times are in Eastern Time (America/New_York). The timezone constant is exported as TIMEZONE.

SESSIONS

Defines the three ICT trading sessions:

Session	Start	End	Label
asia	20:00	00:00	Asia
london	02:00	05:00	London
ny_am	07:00	11:00	NY AM

GAP_SCAN

Windows between the target session end and the entry window start, used for gap analysis:

Mode	Start	End
NY	05:00	07:00
London	00:00	02:00

ENTRY_WINDOW

The active trading windows when new entries are permitted:

Mode	Start	End
NY	07:00	15:00
London	02:00	07:00

EOD_HOUR

End-of-day cutoff: 15 (3:00 PM ET).

getCurrentWindow(hour, minute, mode)

Returns the current session window identifier based on ET time and session mode.

NY mode windows (in order through the day):

Time range (ET)	Return value
20:00+ (prev day)	'pre_session'
00:00 - 02:00	'asia'
02:00 - 05:00	'london'
05:00 - 07:00	'gap_scan'
07:00 - 11:00	'ny_am'
11:00 - 15:00	'ny_pm'
15:00+	'post_eod'

London mode windows:

Time range (ET)	Return value
20:00+ (prev day)	'pre_session'
00:00 - 02:00	'gap_scan'
02:00 - 05:00	'asia'
05:00 - 07:00	'london'
07:00+	'post_eod'

---

macro-windows.js -- ICT Macro Time Windows

ICT macro windows are 20-minute blocks centered on the top of the hour (:50 to :10), plus one 30-minute afternoon window. All times in Eastern Time.

MACROS Array

#	Window	Label
1	06:50 - 07:10	06:50-07:10
2	07:50 - 08:10	07:50-08:10
3	08:50 - 09:10	08:50-09:10
4	09:50 - 10:10	09:50-10:10
5	10:50 - 11:10	10:50-11:10
6	12:50 - 13:10	12:50-13:10
7	13:50 - 14:10	13:50-14:10
8	14:50 - 15:10	14:50-15:10
9	15:15 - 15:45	15:15-15:45
10	15:50 - 16:10	15:50-16:10

Macro window #9

The 15:15-15:45 window is 30 minutes (not 20) and does not follow the :50-:10 pattern. This is the "last hour" macro.

checkMacro(hour, minute)

Returns whether the given ET time falls within any macro window.

checkMacro(8, 55);  // { in_macro: true,  macro_name: '08:50-09:10' }
checkMacro(8, 30);  // { in_macro: false, macro_name: null }
checkMacro(15, 20); // { in_macro: true,  macro_name: '15:15-15:45' }

---

signal-schema.js -- StrategyFlags Schema

Defines the shape of the StrategyFlags JSON output produced by the scan pipeline, along with validation logic.

Allowed Enum Values (ENUMS)

Field	Allowed values
bias_direction	'bullish', 'bearish', 'neutral'
dol_target	'PDH', 'PDL', null
session_mode	'NY', 'London'
session_window	'pre_session', 'asia', 'london', 'gap_scan', 'ny_am', 'ny_pm', 'post_eod'
hunt_side	'HUNT_HIGH', 'HUNT_LOW', 'INVALID', null
trade_direction	'long', 'short', null

validateFlags(flags)

Validates a StrategyFlags object against the schema. Returns an array of error strings (empty array = valid).

Validated fields:

• Top-level: timestamp (string), symbol (string), timeframe (string)
• bias: daily (bias_direction enum), weekly (bias_direction enum), hit_target (boolean)
• session: mode (session_mode enum), hunt.side (hunt_side enum)
• structure: order_blocks (required), atr (required)
• smt: required object
• price: required object
• decision: setup_valid (boolean), direction (trade_direction enum), confluence_factors (array), no_trade_reasons (array)