---
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

```json
{
  "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](https://www.tradingview.com/charting-library-docs/latest/customization/overrides/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](https://www.tradingview.com/charting-library-docs/latest/ui_elements/drawings/Drawings-List/) and [CreateShapeOptions](https://www.tradingview.com/charting-library-docs/latest/api/interfaces/Charting_Library.CreateShapeOptions/#shape).

---

## 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](https://www.tradingview.com/charting-library-docs/latest/customization/overrides/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