HX114 - Platform Extensions and Local API

HyperionX can be extended inside the desktop app and controlled through a local Rion desktop API. These features are powerful, so they must be treated as permissioned platform workflows instead of unrestricted chat or script shortcuts.

Goals

After this lesson you should be able to:

• Understand where add-ons fit compared with indicators and strategies.
• Know what the local desktop API exposes.
• Explain the permission model for Rion actions.
• Use dry-run and confirmation flows before execution.
• Find the audit trail for local API actions.

Add-Ons

Add-ons are platform extensions that derive from AddonBase. They are not indicators and they are not strategies.

Add-ons have:

• Name
• Version
• IsLoaded
• Context
• Load(context)
• Unload()
• OnLoad()
• OnUnload()

The add-on context exposes:

• Current session.
• UI dispatcher.

Use an add-on when the feature belongs to the platform session rather than a single chart calculation. Examples include global services, session-level tools, or integrations that need app lifecycle handling.

Do not use add-ons for:

• Simple plotted calculations.
• Strategy entries and exits.
• One-off chart annotations.
• Work that should live in a chart indicator.

Local Desktop API

Rion's desktop API runs on loopback only. It starts at 127.0.0.1:5217 and can probe nearby ports if the default port is unavailable.

The API is designed for local automation and context, including:

• Health and capability checks.
• Active chart state.
• Candle data.
• Indicator and signal snapshots.
• Drawing lists and drawing actions.
• Economic news.
• Chart Trader state.
• Orders and positions.
• Script inventory.
• Validator and Optimizer status.
• Code Lab actions.
• Prompt context and chart memory.
• Structured action endpoints.

This API is local-first. It should not be treated as a public network API.

Authentication And Signing

Every local API request requires a local token. The token can come from the app-generated token or the HYPERIONX_RION_LOCAL_TOKEN environment variable.

Token headers:

• Authorization: Bearer <token>
• X-HyperionX-Desktop-Token
• X-HyperionX-Rion-Token

Optional request signing can be enabled with environment settings. The signing policy uses HMAC-SHA256 over a canonical request:

METHOD
PATH
QUERY
TIMESTAMP
BODY

Signing headers:

• X-HyperionX-Key-Id
• X-HyperionX-Timestamp
• X-HyperionX-Signature

When strict signing is enabled, unsigned or stale requests are rejected.

Permission Model

Permissions are resolved by endpoint and action type.

Permission	Typical use
read	Health, state, chart, candles, indicators, news, scripts.
draw	Chart drawing actions.
backtest	Validator actions.
optimize	Optimizer actions.
codelab	Code Lab actions and custom script compile.
sim_trade	Hyperion Sim order actions.
live_trade	Reserved for live-trade entitlement and policy gates.

Permissions depend on license entitlements and local settings. Trading actions also require the Rion settings toggle for simulated trading actions.

Trading Guardrails

Rion trading actions are intentionally narrow.

Allowed through the local action path:

• Hyperion Sim order preparation.
• Hyperion Sim order placement after confirmation or enabled auto-execute.
• Cancel working Hyperion Sim orders.
• Flatten a Hyperion Sim position.
• Close a Hyperion Sim position.
• Modify a working Hyperion Sim order.

Blocked by policy:

• Broker account order actions.
• Server-paper account order actions.
• Any trade claim without a successful local action result.
• Advice questions being treated as direct order commands.

When auto-execute is off, the chat UI must show confirmation or wait for a clear yes/proceed response. When auto-execute is on, the local validation still runs first.

Context Safety

The local API builds prompt context from the active chart, but it avoids exposing secret-like values. Parameters with names containing key, secret, password, or token are filtered from prompt context.

Prompt context can include:

• Active symbol and timeframe.
• Loaded and visible candle counts.
• Recent candles.
• Indicator names, plot values, and signal snapshots.
• Strategy names, states, and visible parameters.
• Chart Trader state.
• Platform open-window state.
• Validator and Optimizer status.

This makes Rion useful without asking the user to paste chart values manually.

Audit Trail

Desktop API actions write an audit record under the user's HyperionX app-data folder:

HyperionX\AIAgent\Audit\rion-api-yyyyMMdd.jsonl

Audit entries include:

• Request id.
• UTC timestamp.
• Method and path.
• Permission.
• Dry-run flag.
• Accepted flag.
• Status and message.
• Truncated request body.

For support, use Export Logs after a failed or unexpected action so the audit trail, app logs, build logs, and strategy output can be reviewed together.

Integration Checklist

Before building a tool on top of the local API:

• Start with health and capabilities.
• Use dry-run for actions that can change platform state.
• Respect the permission returned by the capabilities payload.
• Use chart context from the active chart instead of inventing symbol or timeframe.
• Require confirmation for trading unless the user explicitly enabled auto-execute.
• Keep broker and server-paper account actions out of the Rion local action path.
• Store request ids for troubleshooting.
• Review audit logs after failures.

Acceptance Checklist

A local automation workflow is ready when:

• The request is token-authenticated.
• Required entitlements and settings are present.
• Dry-run output matches the intended action.
• Trading commands target only Hyperion Sim.
• Confirmation or auto-execute policy is followed.
• The response is checked before telling the user anything happened.
• Audit and log export can reconstruct the action.