Skip to main content

Agent Builder API

This page describes the public contract for AI agents and terminal tools that need to understand HyperionX charts and Code Lab scripts.

The current implementation is an in-app read-only chart context API. A localhost/CLI agent API is planned so external tools can safely inspect chart state without depending on private UI objects.

Current In-App Snapshot​

The chart AI service builds an AIAgentToolSnapshot from the active chart.

Snapshot fields include:

Symbol
TimeFrame
TotalCandleCount
VisibleCandleCount
RecentCandles
VisibleCandles
Indicators
Strategies
ChartTrader

Candles include:

Time
Open
High
Low
Close
Volume

Indicators include:

Name
DisplayName
TypeName
PlotCount
ParameterCount
Parameters
InputName
InputCount
IsAutoscale

Strategies include:

Name
DisplayName
TypeName
Enabled
Account
PositionCount
ParameterCount
Parameters
State

Chart Trader includes read-only state:

IsVisible
IsReadOnly
IsConnected
Symbol
Account
OrderType
Size
Price
LastPrice
BestBid
BestAsk
SelectedLeverage
MaxLeverage
ReduceOnly
TpSlEnabled
StopStrategy
TimeInForce
Position
Entry
PnL

Planned Local HTTP API​

The planned local API should bind to localhost only and require a per-session token.

Base path:

http://127.0.0.1:{dynamicPort}/api/chart-agent/v1

Planned read endpoints:

GET /health
GET /charts
GET /charts/{chartId}
GET /charts/{chartId}/snapshot?bars=120
GET /charts/{chartId}/visible
GET /charts/{chartId}/last-candle
GET /charts/{chartId}/metadata
GET /charts/{chartId}/stream

Planned API rules:

  • Read-only by default.
  • No credentials.
  • No order submission without explicit permissions.
  • No wallet signing.
  • No hidden platform paths.
  • Redact secret-like parameters.
  • Include build/version info for compatibility checks.

Planned CLI​

A terminal-friendly CLI can wrap the same local API.

Example future commands:

hx chart list
hx chart snapshot --chart active --bars 120 --json
hx chart visible --chart active --json
hx chart stream --chart active --format ndjson
hx codelab build
hx codelab validate-script ./MyIndicator.cs

The CLI should output JSON for agent workflows and keep human-readable output as an option.

Code Lab Agent Contract​

When an AI agent writes Code Lab scripts, it must follow the HyperionX API contract:

  • Write HyperionX scripts, not scripts for other trading platforms.
  • Use the correct namespace for the selected script category.
  • Use [HyperionXProperty] for user-editable settings.
  • Use State.SetDefaults and State.Configured correctly.
  • Use Series<double> and AddSeries(...) for custom outputs.
  • Use PlotLineType.Solid or PlotLineType.Dashed.
  • Use PlotChartType.Linear or PlotChartType.Bars.
  • Use Draw.FixedText(...) or Draw.HudText(...), not Draw.TextFixed(...).
  • Use SubmitOrder(...), OrderAction, and OrderType for strategy orders.
  • Compile after editing and fix all diagnostics.

Future Tool Permissions​

The safe build order for agent tools is:

  1. Read-only chart, indicator, strategy, and chart trader inspection.
  2. Code Lab template generation and compile diagnostics.
  3. Simulation-only strategy and order tools.
  4. Confirmed chart-trader draft orders.
  5. Live broker read tools.
  6. Live trade tools only after permissions, confirmations, risk limits, and audit logs are complete.