Analyze a chart

Run the chart agent and retrieve its analysis, chart annotations, and setup when one is supported.

POST/v1/analysis/runs

Request body

The agent sees the exact input PNG, with OHLCV available for its tools. It decides which analysis and drawings fit your request. No forced pattern count or guaranteed trade.

market.symbolstring · required: For example BINANCE:BTCUSDT or NASDAQ:AAPL. Binance spot history covers BTC, ETH and SOL; the connected feed supports accessible instruments with provider-dependent history. Your own candles are also accepted.
market.intervalenum: 1, 5, 15, 60, 240, or D. Intraday intervals are minutes.
market.rangeobject: Either { bars: 320 } (2–2000) or { from, to }. Both date bounds are required. The range is [from, to), with only fully closed candles.
viewobject: PNG dimensions, dark or light theme, and volume visibility. Defaults: 1440 × 900, dark, volume on.
commandsarray · optional: Existing typed drawing commands, up to 100. Chart-write scope is required. Never arbitrary HTML or JavaScript.
instructionobject: mode: prompted, professional_auto or respond_only; prompt: your instructions. Professional auto uses the existing chart-analysis brain.
modelobject · optional: provider: openai or grok; name: a configured model identifier. Server defaults apply when omitted.
delivery.modeenum: artifact (default) or inline_base64. Images always carry dimensions, SHA-256 and expiration.

curl -X POST "$AGENT_CHARTING_URL/v1/analysis/runs" \
  -H "Authorization: Bearer $AGENT_CHARTING_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-chart-request-001" \
  -d '{
  "market": {
    "symbol": "BINANCE:BTCUSDT",
    "interval": "240",
    "range": {
      "bars": 320
    }
  },
  "instruction": {
    "mode": "professional_auto",
    "prompt": "Analyze the visible chart as a professional technical analyst. Draw the relevant structure, patterns and best-supported setup when justified. Explain the thesis, invalidation, targets and what to watch. Do not force a pattern or a trade."
  }
}'

202 · accepted (example)

{
  "id": "run_…",
  "object": "analysis.run",
  "status": "queued",
  "links": {
    "self": "/v1/analysis/runs/run_…",
    "events": "/v1/analysis/runs/run_…/events"
  }
}

Response and permissions

Analysis returns 202 immediately by default. A completed run includes analysis.text, setup (when created), commands, inputImage, image, verification and provenance. A failed job has status failed and an error; acceptance is not success.

Required scopes: market:read chart:read chart:write agent:run memory:write setup:write