Indicator Contract System¶
Purpose¶
The indicator contract is the formal specification that governs how the FATBot system interprets visual elements produced by custom Pine Script indicators on TradingView. Each indicator communicates its state through Pine graphics primitives — labels, lines, boxes, and tables — which are read by the TradingView MCP's Pine graphics tools.
Every contract serves as the single source of truth for the corresponding interpreter. If the contract says a bullish bias is encoded as a table cell bgcolor, then the interpreter reads that cell's bgcolor. Nothing else.
Why Contracts Matter¶
Without a formal contract, the system would rely on fragile heuristics: string matching that breaks when label text changes, color detection that fails when a user customizes themes, or positional assumptions that collapse when indicators are reordered. The contract eliminates this by defining:
- Exactly which visual elements carry signal data (and which are cosmetic).
- The precise encoding scheme — what each color, style, position, and text pattern means.
- The state machine that converts raw visual observations into discrete strategy states.
- Edge cases and failure modes — missing elements, duplicates, ambiguity.
Contract Structure¶
Every indicator contract follows five sections:
1. Identity¶
How to locate the indicator on a chart (pine_title, study_filter, short_title).
2. Visual Channels¶
Which Pine graphics types the indicator uses:
| Channel | Pine Function | MCP Tool |
|---|---|---|
| Labels | label.new() |
data_get_pine_labels |
| Lines | line.new() |
data_get_pine_lines |
| Boxes | box.new() |
data_get_pine_boxes |
| Tables | table.new() |
data_get_pine_tables |
3. Element Dictionary¶
Catalog of every distinct visual element: identifier, meaning, mutability, pairing rules.
4. State Machine¶
How raw visual observations map to discrete strategy states (states, transitions, initial state, reset conditions).
5. Edge Cases¶
Missing elements, duplicates, ambiguous elements, timing issues, user configuration variations.
Reading Model¶
TradingView Chart
|
v
MCP Pine Graphics Tools
|
v
Raw Visual Elements (JSON)
|
v
Indicator-Specific Interpreter (applies contract rules)
|
v
Typed Strategy State
Key Constraints¶
- No plot values. MCP cannot read
plot()output. State must be encoded in labels, lines, boxes, or tables. - Snapshot reading. MCP returns current state, not a time series of changes.
- Color matching uses hex or RGB.
Indicators to Document¶
All indicators are being rebuilt from scratch. Contracts will be written as each indicator is built:
| Indicator | Status |
|---|---|
| FVG + OB + MSS | Not started |
| Next Candle Bias | Not started |
| SMT | Not started |
| Session Bias | Not started |
| Macro | Not started |
| Economic Calendar | Not started |
| EMA | Not started |
Future Direction¶
For indicators designed specifically for MCP consumption, structured payload encoding (delimiter-based or JSON) can replace natural visual encoding. See payload-format.md for guidelines.