Using Visual Chart Annotations

TL;DR

Read the current Shells chart id, then write chart changes through the chart workspace API. The same annotation tool works for the default live chart and for agent-created workspace charts.

Typical flow (switch default market):

1. visual_set_active_market(query="PENGU perp")
   -> switches the live chart, order book, trades, and trade ticket together
2. chart_id = data["frontend_context"]["active_market_request"]["market_id"]
3. visual_add_workspace_chart_annotation(
     chart_id=chart_id,
     type="marker",
     config={"time": "2026-05-21T06:00:00Z", "price": 0.035, "shape": "flag", "color": "#22c55e"}
   )

Typical flow (default chart):

1. visual_get_frontend_context()
   -> {"ok": true, "data": {"frontend_context": {"chart": {"id": "hl-perp-BTC", "market_id": "hl-perp-BTC", "market_type": "hl-perp"}}}}
2. chart_id = data["frontend_context"]["chart"]["id"]
3. visual_add_workspace_chart_annotation(
     chart_id=chart_id,
     type="horizontal_line",
     config={"price": 73500, "color": "#ef4444", "label": "Support"}
   )
4. The annotation appears on the user's default chart.

Typical flow (agent-created visual pane):

1. visual_search_chart_series(query="BTC ETH relative performance")
   -> copy compatible `source` objects and each result's `shape.default_y`
2. visual_create_chart(
     chart_id="btc-eth-relative",
     title="BTC vs ETH",
     kind="line",
     lookback_days=90,
     series=[
       {"id": "btc", "label": "BTC", "source": <BTC source>, "x": "ts", "y": "price_usd"},
       {"id": "eth", "label": "ETH", "source": <ETH source>, "x": "ts", "y": "price_usd"}
     ],
     transforms=[{"type": "rebase", "base": 100}]
   )
3. visual_set_active_chart(chart_id="btc-eth-relative")
4. visual_add_workspace_chart_annotation(
     chart_id="btc-eth-relative",
     type="text_label",
     config={"time": "2026-05-21T06:00:00Z", "price": 120, "text": "Relative breakout"}
   )

MCP tools

All gate on is_opencode_instance() and return {"ok": false, "error": {"code": "not_opencode_instance"}} when run outside Shells.

Chart panes

Use visual_set_active_market when the user asks to show, switch to, or open one tradable market such as "show AAVE", "switch to PENGU perp", "open POL spot", or "show this Polymarket market". It is the one-call path that updates the default chart and the rest of the trading context.

Use visual_create_chart when the user asks for a new visual pane, comparison, APY/funding chart, table, or custom derived visualization, not when they only want to switch or annotate the live chart.

If visual_create_chart returns ok: false, do not tell the user the chart is ready. Read the error, pick a compatible source/kind, and retry.

Supported source types:

• market_price: {"type": "market_price", "market_id": "hl-perp-btc"}
• dataset_series: returned by visual_search_chart_series; preferred for known backend datasets, including the current Delta Lab registry-backed series
• delta_lab_asset: {"type": "delta_lab_asset", "symbol": "USDC", "series": "lending", "venue"?: "...", "basis"?: true}. Legacy fallback only; use a returned dataset_series source when available.
• inline: {"type": "inline", "points": [{...}]}

Single-series time-series workspace charts render in TradingView. Multi-series comparisons currently use the workspace line renderer; keep using line plus rebase for relative performance charts.

For tradable perp charts, pass context_market_id so the shell switches the order book, trades, and trade ticket while keeping the workspace chart active:

{
  "chart_id": "pengu-price",
  "title": "PENGU Perp",
  "kind": "price_candle",
  "context_market_id": "hl-perp-pengu",
  "series": [
    {
      "id": "pengu-price",
      "label": "PENGU",
      "source": {"type": "dataset_series", "dataset_id": "hyperliquid.perp.price", "params": {"coin": "PENGU", "interval": "1h"}},
      "x": "ts",
      "y": "price_usd"
    }
  ]
}

Supported transforms: filter, latest_by, top_n, rebase, pct_change, scale, multiply, ratio, spread, moving_average. Prefer rebase(base=100) for relative performance across different units.

Transforms can live on the chart or on a single series. Copy any default_transforms from a search result into the series transforms, then add metric conversions. Use series-level transforms when only one dataset needs conversion. Chart-level transforms hit every series unless you scope them with "series_ids": ["..."].

Scaling a ratio: put scale on the ratio transform itself — {"type": "ratio", "left": "a", "right": "b", "scale": 1e6, "label_suffix": "(×10⁶)", "unit": "ratio"} — which scales only the derived series. Never use a chart-level scale for this: it multiplies the sources before division, so it corrupts them and mathematically cancels out of the ratio.

Delta Lab APY/rate fields are decimal fractions. 0.12 means 12%, not 0.12%.

For Pendle/lending/Boros/yield APY or APR fields such as implied_apy, underlying_apy, supply_apr, borrow_apr, fixed_rate_mark, and floating_rate_oracle, convert to display percent:

{"type": "scale", "factor": 100, "unit": "%", "label_suffix": "(%)"}

For annualizing hourly funding to display percent:

{
  "id": "btc-funding",
  "label": "BTC Funding",
  "source": {"type": "dataset_series", "dataset_id": "hyperliquid.perp.funding", "params": {"coin": "BTC"}},
  "x": "ts",
  "y": "funding_rate",
  "unit": "%",
  "axis": "right",
  "transforms": [{"type": "scale", "factor": 876000, "unit": "%", "label_suffix": "(annualized %)"}]
}

Series can set color and axis (left or right). Keep related units on the same axis; use a right axis only when overlaying unrelated units.

Dataset selection

Always search known datasets before inventing or fetching your own data.

0. If the user asks for a single tradable token/perp/spot/prediction market, use visual_set_active_market first. Do not search chart datasets or create a workspace chart for simple market switches.
1. Use visual_search_chart_series with the user intent/assets first. Do not pass kind by default; inspect returned kind, shape.default_y, shape.columns, and shape.supported_chart_kinds to decide whether to use the candidate.
2. Prefer a common source family across compared series. For example, use Hyperliquid perp prices for BTC and ETH together; do not mix Hyperliquid BTC with CoinGecko ETH unless there is no common source.
3. For asset price/performance requests, prefer Hyperliquid perp price series over spot/fallback price series unless the user explicitly asks for spot. Prefer registry-returned Delta Lab dataset_series sources for lending/yield/Boros/Pendle/funding research series, CoinGecko only as broad spot price fallback, and DeFiLlama for current ranked yield tables/bars.
4. Pass kind only to narrow a known data family (funding, yield, price) or a large result set. Do not pass chart kinds such as line as the first search because that hides useful candidate metadata.
5. Use Polymarket-specific tools/API for prediction markets. Do not route Polymarket discovery through chart-series search.
6. Use inline only when the registry does not expose the needed data. If using inline data, keep it small and describe the columns in the chart label or nearby message.
7. Set lookback_days on visual_create_chart when the user gives a time window. Use 90 for "3 months".
8. When a chart represents a tradable Hyperliquid perp, set context_market_id to hl-perp-<symbol-lowercase> unless the tool result already provides a more specific market id.

Registry results include:

• source: copy this into the chart series spec.
• shape.default_y: use this as the series y field unless a different column is intentional.
• shape.columns: read this before choosing transforms such as latest_by, top_n, ratio, or spread.

Annotation types

For bulk catalyst markers on the live/default chart, prefer a single event marker overlay:

{
  "type": "event_markers",
  "id": "zec-catalysts",
  "data": [
    {
      "time": "2026-05-21T06:00:00Z",
      "price": 690,
      "label": "ZEC hits $690",
      "color": "#ef4444",
      "shape": "flag"
    }
  ]
}

Use data as the canonical event array. Legacy markers is accepted, but new calls should not use it.

TradingView indicators

visual_set_chart_indicators(chart_id, indicators) applies native TradingView studies to the live/default chart or a workspace chart. Replace semantics: the list you pass becomes the chart's full indicator set; [] clears. Current indicators are readable at chart_workspace.defaultIndicators[chart_id].

[
  {"name": "ema", "inputs": {"length": 21}},
  {"name": "bollinger", "inputs": {"length": 20, "mult": 2}},
  {"name": "rsi"}
]

Names are case-insensitive; the canonical study names are also accepted. Unknown names return a 400 listing the supported set. Use the friendly param names from the table — the backend translates them to the study's actual TradingView input ids (several built-ins use positional in_0/in_1 ids). Unrecognized input keys pass through untouched, so exact TV input ids and advanced inputs (smoothingLine, maType, …) also work. Omit inputs entirely for TradingView defaults — prefer that unless the user asked for specific parameters. Optional forceOverlay overrides the pane default; optional id makes an entry stable across replaces. visual_create_chart accepts the same list via indicators.

Indicators render only on TradingView-backed charts: the live market chart, price_candle charts, and single-series time-series line charts. Bar, table, and multi-series recharts panels ignore them.

Previewing data before charting

visual_preview_series(series, kind?, transforms?, lookback_days?, limit?) dry-run resolves the exact series/transforms payload you would pass to visual_create_chart — nothing is saved. The compact response carries, per series: points, first_x/last_x, unit, y_first/y_last/y_min/y_max, and sample_head/sample_tail point arrays. Use it to catch unit and scaling mistakes (decimal APYs, unreadably tiny ratios) before the chart exists. The same automatic percent-scaling of known rate fields applied by visual_create_chart is applied here, so the preview matches the render.

Gotchas

• marker does not accept label. Use text_label for annotated points.
• Use ISO-8601 strings for time values when possible. The renderer also accepts unix seconds, but do not hand-compute timestamps.
• For default chart annotations, use the exact frontend_context.chart.id.
• For workspace charts, use the chart_id passed to visual_create_chart.
• Default chart annotations are stored in chart_workspace.defaultAnnotations; workspace chart annotations are stored in the chart's overlays.
• After writing default chart overlays, verify chart_workspace.defaultAnnotations[chart_id] contains the expected overlay and, for event markers, that its data array has the expected count.
• Chart workspace state is scoped to the current Shells instance, not the user vault.