ai/gateway/knowledge/platform/shapes.md

description

description
Chart shape types (trend lines, Fibonacci, rectangles, channels, etc.), point requirements, override properties, and WorkspacePatch patterns for adding/modifying/deleting shapes on the TradingView chart.

Chart Shapes

Shapes are persistent TradingView chart drawings stored in the shapes workspace store. Read them with WorkspaceRead("shapes") and create/modify/delete them with ShapesMutate. Do not use WorkspacePatch for shapes — it requires knowledge of the internal path structure and is error-prone.

Always read chartState first to get the current symbol and visible start_time/end_time for placing points correctly.

---

Shape Object

{
  "id": "string — unique ID you assign (e.g. 'trendline-btc-1')",
  "type": "string — see type table below",
  "points": [{ "time": 1700000000, "price": 45000.0, "channel": "optional" }],
  "color": "#2962FF",
  "line_width": 2,
  "line_style": "solid",
  "properties": {},
  "symbol": "BTC/USDT.BINANCE",
  "created_at": 1700000000,
  "modified_at": 1700000000
}

• line_style: "solid" | "dashed" | "dotted"
• properties: passed directly as TradingView overrides (see Drawings Overrides)
• time values must be Unix timestamps in seconds; they are snapped to the nearest candle boundary automatically

---

Supported Shape Types

type	Description	Points
trend_line	Trend line between two price/time points	2
horizontal_line	Horizontal price level across the chart	1
vertical_line	Vertical time marker	1
rectangle	Price/time rectangle (two corners)	2
circle	Circle centered at first point, edge at second	2
arrow	Arrow from point 1 to point 2	2
fib_retracement	Fibonacci retracement levels between two points	2
fib_trend_ext	Trend-based Fibonacci extension (A→B→C)	3
parallel_channel	Parallel channel (two-line + channel width)	3
pitchfork	Andrews pitchfork (handle + two tines)	3
gannbox_fan	Gann fan from a pivot point	2
path	Free-form polyline through 2+ points	2+
text	Text label anchored at a price/time location	1
head_and_shoulders	Head and shoulders pattern overlay	7

For the full TradingView drawing catalog (including Elliott waves, patterns, annotations, etc.) see Drawings List and CreateShapeOptions.

---

ShapesMutate Patterns

Use ShapesMutate — not WorkspacePatch — to add, update, or remove shapes. Any combination of operations can be sent in a single call.

Add a shape

ShapesMutate({
  add: [{
    id: "trendline-1",
    type: "trend_line",
    points: [
      { time: 1700000000, price: 42000 },
      { time: 1700172800, price: 45000 }
    ],
    color: "#2962FF",
    line_width: 2,
    line_style: "solid",
    symbol: "BTC/USDT.BINANCE"
  }]
})

Update a property

ShapesMutate({ update: [{ id: "trendline-1", color: "#FF5722" }] })

Delete a shape

ShapesMutate({ remove: ["trendline-1"] })

Combined (add + remove in one call)

ShapesMutate({
  add: [{ id: "hline-support", type: "horizontal_line", points: [{ time: 0, price: 42000 }], symbol: "BTC/USDT.BINANCE" }],
  remove: ["trendline-1"]
})

---

Override Properties

These map to TradingView drawing override keys passed in the properties field:

Property key	Type	Notes
linecolor	string (hex)	Same as top-level color — prefer color
linewidth	number	Same as top-level line_width — prefer line_width
linestyle	number	0 = solid, 1 = dashed, 2 = dotted — prefer line_style
fillBackground	boolean	Fill enclosed areas (rectangles, circles, etc.)
backgroundColor	string (hex)	Fill color when fillBackground is true
transparency	number	Fill transparency 0–100
extendLeft	boolean	Extend line left (rays, horizontal lines)
extendRight	boolean	Extend line right
showLabel	boolean	Show price/time label on the shape

For the complete per-type override reference, consult Drawings Overrides.

---

Notes

• ID collisions: read the shapes store first to check existing IDs before adding
• Symbol filter: the web client only renders shapes where shape.symbol matches the current chart symbol — always set it
• Horizontal lines only need a price in their single point; time is ignored
• Vertical lines only need a time in their single point; price is ignored
• Text shapes: set properties.text to the label string