Skip to main content

Agent Builder API

This page describes the public contract for Rion agents and local tools that need to understand HyperionX charts, Code Lab scripts, drawings, news, research windows, and guarded simulation actions.

The current implementation includes in-app chart context plus a localhost Rion desktop API. The API is designed so agents can inspect platform state without scraping 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

Current Local HTTP API​

The local API binds to localhost and uses a desktop token. Rion bridge calls send the token as a bearer token. Integrations should treat the token as private local process state, not as a user credential to log or share.

Default base path:

http://127.0.0.1:5217

If the default port is unavailable, HyperionX scans the configured fallback range.

Current read endpoints:

GET /health
GET /api/v1/rion/health
GET /api/v1/rion/capabilities
GET /api/v1/rion/tools/schema
GET /api/v1/rion/state
GET /api/v1/rion/chart
GET /api/v1/rion/candles?scope=analysis|recent|visible&limit=120
GET /api/v1/rion/indicators
GET /api/v1/rion/signals
GET /api/v1/rion/drawings
GET /api/v1/rion/news
GET /api/v1/rion/chart-trader
GET /api/v1/rion/orders
GET /api/v1/rion/positions
GET /api/v1/rion/scripts
GET /api/v1/rion/strategy-tools
GET /api/v1/rion/validator/status
GET /api/v1/rion/optimizer/status
GET /api/v1/rion/context
GET /api/v1/rion/memory

Current action endpoints:

POST /api/v1/rion/action
POST /api/v1/rion/validator/action
POST /api/v1/rion/optimizer/action
POST /api/v1/rion/code-lab/action
POST /api/v1/rion/drawings/action
POST /api/v1/rion/trading/action

Compatibility aliases also exist under /api/v1/desktop/.... New integrations should prefer /api/v1/rion/....

API rules:

  • Read-only by default.
  • No credentials.
  • No order submission without explicit permissions and confirmation.
  • No wallet signing.
  • No hidden platform paths.
  • Redact secret-like parameters.
  • Include build/version info for compatibility checks.
  • Audit action requests and results.
  • Keep live trading locked unless product policy, settings, risk controls, and entitlements allow it.

CLI Direction​

A terminal-friendly CLI can wrap the same local API. This is not required for the current desktop workflow, but the local API should stay stable enough for a future CLI.

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

Tool Permissions​

The safe progression 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.