Skip to main content

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.

The add-on lifecycle is Current. The Local Desktop API is Preview and is not a general public-network API. Use Add-on Development and Local Desktop API as the current contracts; route and permission details can change during Preview.

Reviewed 1.1.27 source

The API contract below is present in reviewed source. It is not a guarantee about the public installer or a promotion out of Preview. Check the documentation version map, then use the installed capabilities and schema. Default grounded Cloud chat has a separate, smaller tool set and has no trading or legacy research-execution tool.

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.

Preview interface

The Local Desktop API is implemented, but its public authentication bootstrap and compatibility contract are not complete. Use it only for HyperionX-launched components or an integration that was provisioned with a token before the desktop started.

The API exposes authenticated reads and scoped actions for active-chart context, drawings, research tools, Code Lab, and Hyperion Sim. Read its capabilities and tool schema at runtime instead of copying a route list into an integration. This API is local-first and must not be treated as a public network API.

Authentication And Signing​

Every local API request except a CORS preflight requires a local token, including health. The token can come from the app-generated token or the HYPERIONX_RION_LOCAL_TOKEN environment variable.

The app-generated token is private process state and has no supported public copy/reveal UI. An external integration must arrange HYPERIONX_RION_LOCAL_TOKEN before HyperionX starts. HyperionX-launched Code Lab processes receive the selected URL and token through their process environment.

Token headers:

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

Optional request signing can be enabled with environment settings. Read the installed capabilities before choosing a signing format. Reviewed 1.1.27 source advertises HPX-RION-V2, which uses HMAC-SHA256 over this canonical request:

HPX-RION-V2
KEY_ID
REQUEST_ID
METHOD
PATH
QUERY
TIMESTAMP
BODY

Signing headers:

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

In that contract, every POST requires a request ID even when signing is optional. Reuse an execution ID only for the exact same request within the advertised idempotency window. A preview and its changed execution body need different IDs. When strict signing is enabled, unsigned or stale requests are rejected.

Older builds can advertise a legacy five-line format. Do not send V2 unless it is advertised, and do not assume the older format protects request IDs or deduplicates mutations. Follow the exact normalization, time window, and retry rules in Local Desktop API.

Permission Model​

Authentication does not grant every tool. Permissions are resolved by endpoint and selected account type, then combined with license entitlements and local settings. Read the installed build's capabilities response and the Local Desktop API permission checks before each integration. A release-enabled build can expose guarded Hyperliquid and KuCoin actions, but live_trade alone is not sufficient.

Trading Guardrails​

The local HTTP trading actions are intentionally narrow. They are separate from the reviewed 1.1.27 default grounded Cloud conversation, which does not execute trades.

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.
  • In an enabled build only, guarded Hyperliquid or KuCoin actions that pass the Local Agent Live Trading API checks.

Blocked by policy:

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

A supported legacy in-app trading workflow obtains confirmation when auto-execute is off. A direct HTTP client supplies that decision through a request field such as confirmed or executeTrading; the API does not independently open a desktop confirmation dialog. When the supported simulation auto-execute policy is on, local validation still runs first. These confirmation rules do not enable trading tools in grounded Cloud chat.

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.

Keep Code Lab surfaces separate: the scoped HTTP route supports open/list/compile/status, while reviewed 1.1.27 grounded conversation tools can create and revise a task-owned indicator with the relevant permissions. Neither successful compilation nor a chat message proves correct runtime behavior. See Agent Builder API.

Audit Trail​

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

%APPDATA%\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.
  • A redacted request-body marker and bounded length, not the request-body content.

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.
  • Reject provider-account actions unless the installed release explicitly exposes that provider and every live-trading gate passes; the documented live providers are Hyperliquid and KuCoin only.
  • 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.
  • Each trading command targets Hyperion Sim or an explicitly capability-enabled Hyperliquid/KuCoin route that passes every provider-specific gate.
  • 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.