Local Desktop API
The Rion Local Desktop API lets a provisioned local process inspect the active HyperionX workspace and request selected desktop actions.
The API is implemented but its public authentication bootstrap, schema compatibility, and third-party support contract are not complete. It is not a stable SDK and must not be exposed on a LAN or the internet.
The HyperionX 1.1.10 baseline restricts this API to Hyperion Sim trading. Newer release-enabled builds can expose guarded Hyperliquid and KuCoin live trading; those paths are documented separately and must be discovered from the installed capabilities and tool schema.
Before You Integrate
The current API is suitable for HyperionX-launched components and integrations that can set a token before the desktop app starts. HyperionX does not currently provide a supported UI, unauthenticated discovery route, or command that reveals the app-generated token to an external developer.
If your integration has not been provisioned with a token, stop here. Do not scrape logs, process memory, or application files to obtain one.
Address And Port Selection
The server binds to IPv4 loopback only. It first tries:
http://127.0.0.1:5217
If that port is occupied, it tries each port through 5226. A preconfigured client can probe that range with an authenticated health request. Code Lab processes launched by HyperionX receive the selected base URL and token through their process environment.
Loopback limits network reachability; it does not make every local process or browser page trusted.
Authentication
Every request except a CORS preflight requires the desktop token, including health requests. Supply one of these headers:
Authorization: Bearer <token>
X-HyperionX-Desktop-Token: <token>
X-HyperionX-Rion-Token: <token>
At startup, HyperionX uses HYPERIONX_RION_LOCAL_TOKEN when that environment setting is present. Otherwise it generates a random token for that desktop process. Because the generated value has no public retrieval UI, an external integration must arrange the configured token before HyperionX starts.
Keep the token out of source code, command history, screenshots, URLs, and logs. Restart HyperionX after changing a configured token.
Deployments can additionally configure HMAC-SHA256 request signing. The capabilities response describes whether signing is required, the canonical request format, headers, and accepted clock skew. Token authentication remains required when signing is enabled.
Start With Capability Discovery
After finding the authenticated port, call:
GET /api/v1/rion/health
GET /api/v1/rion/capabilities
GET /api/v1/rion/tools/schema
Use the returned build/version and permission information instead of assuming that a route or action is enabled for every license.
The older /api/v1/desktop/... route family remains as a compatibility alias. New Preview integrations should use /api/v1/rion/....
Read Routes
| Task | Route | Notes |
|---|---|---|
| Basic health | GET /health or GET /api/v1/rion/health | Authenticated. |
| Capabilities and tool schema | GET /api/v1/rion/capabilities, GET /api/v1/rion/tools/schema | Check these before actions. |
| Platform and active chart | GET /api/v1/rion/state, GET /api/v1/rion/chart | Uses the active chart rather than a chart ID. |
| Candles | GET /api/v1/rion/candles?scope=analysis|recent|visible&limit=120 | Bounded active-chart data. |
| Indicators and signals | GET /api/v1/rion/indicators, GET /api/v1/rion/signals | Active-chart snapshots. |
| Drawings | GET /api/v1/rion/drawings | Active chart. |
| Economic news | GET /api/v1/rion/news | Supports scope=upcoming|today|week|all|past, limit, minImpact, countries, search, and refreshHours. |
| Trading state | GET /api/v1/rion/chart-trader, GET /api/v1/rion/orders, GET /api/v1/rion/positions | These currently return the same combined active trading-state payload. |
| Code Lab inventory | GET /api/v1/rion/scripts | Includes the configured custom-script root, relative paths, and timestamps. Treat the response as sensitive local-path data. |
| Research tools | GET /api/v1/rion/strategy-tools, GET /api/v1/rion/validator/status, GET /api/v1/rion/optimizer/status, GET /api/v1/rion/research-lab/status, GET /api/v1/rion/research-lab/report | Availability depends on the relevant license and active tool state. |
| Prompt context and memory | GET /api/v1/rion/context, GET /api/v1/rion/memory | Can include local chart-memory summaries. |
Action Routes
| Task | Route | Current action boundary |
|---|---|---|
| Rion chat | POST /api/v1/rion/chat | Sends the prompt through the configured AI provider and can include active-chart context. This is not a local-only operation when a cloud provider is selected. |
| General command | POST /api/v1/rion/action | Classifies a supported Rion command and applies the permission required by the resolved action. Prefer a scoped route for deterministic integrations. |
| Validator | POST /api/v1/rion/validator/action | Open, set up from the active chart, run, cancel, and report status. |
| Optimizer | POST /api/v1/rion/optimizer/action | Open, set up from the active chart, run, stop, and report status. |
| Research Lab | POST /api/v1/rion/research-lab/action | Status/open/refresh, dataset creation, local or entitled ML scans, market scans, report handoff, bounded strategy generation, backtest, optimization, and strategy-summary workflows. Exact availability is build and entitlement dependent. |
| Code Lab | POST /api/v1/rion/code-lab/action | Open Code Lab, list scripts, compile the custom project, or return compile status. It does not create or edit a source file and does not validate one arbitrary file. |
| Drawings | POST /api/v1/rion/drawings/action | List or clear drawings and create the supported levels, session ranges, high/low ranges, FVG, and support/resistance drawings. Clearing every drawing requires the explicit clearAllDrawings flag. |
| Trading actions | POST /api/v1/rion/trading/action | The 1.1.10 baseline supports Hyperion Sim place/cancel/modify/close/flatten actions. A release-enabled build can additionally expose guarded live Hyperliquid and KuCoin actions when its provider-specific capability, setting, entitlement, active account/instrument, connection, and exchange-permission checks pass. |
Supported Code Lab action names are open, list, compile, and status. CLI-like operations such as validate-script and file editing are not available in this API.
For Research Lab, inspect /tools/schema in the installed build before composing a request. Research actions can be long-running and can require selected datasets, reports, strategies, or additional entitlements.
Permission Checks
Authentication and authorization are separate. A valid token does not grant every tool.
| Permission | Required for | Current gate |
|---|---|---|
read | GET routes, chat entry, and command classification | Valid desktop token. |
draw | Drawing mutations | desktop_tools entitlement. |
codelab | Code Lab actions | code_lab entitlement. |
backtest | Validator actions | Desktop-tools and optimizer access in the current build. |
optimize | Optimizer and Research Lab actions | Desktop-tools plus optimizer access; Research Lab also checks its own eligible entitlement. |
sim_trade | Simulated order mutations | Rion simulated-trading setting plus sim_trade entitlement, followed by Hyperion Sim account validation. |
live_trade | Release-gated Hyperliquid or KuCoin order mutations | Requires a release-enabled route, live_trade entitlement, the provider's separate default-off setting, matching active account/instrument, connected provider, and required exchange permissions. It is unavailable in the 1.1.10 baseline. |
Release-enabled capability payloads expose simTrade, liveHyperliquidTrade, and liveKucoinTrade separately. Aggregate liveTrade or an entitlement is not enough: the selected trading-state payload must also report tradingAccess.allowed: true.
The selected Agent Builder profile does not scope the global HTTP token. Agent-profile permissions filter in-app specialized-agent execution; they are not per-token API scopes.
Trading Confirmation
The trading route accepts a request field such as confirmed or executeTrading. That value is an assertion made by the caller; a direct HTTP request does not open an independent desktop confirmation dialog.
A responsible client must:
- show the intended account, symbol, side, type, price, and quantity to the user
- wait for explicit approval unless the user deliberately enabled a supported auto-execute policy
- set the confirmation field only after that decision
- check the returned status before claiming that anything occurred
The 1.1.10 route accepts Hyperion Sim only. In a newer release-enabled build, follow Local Agent Live Trading API and fail closed unless the provider-specific capability and tradingAccess.allowed explicitly enable the selected account and instrument.
Audit Records
Action attempts are written to:
%APPDATA%\HyperionX\AIAgent\Audit\rion-api-yyyyMMdd.jsonl
An entry can include request ID, timestamp, method, path, permission, dry-run and accepted flags, status, and message. The request body itself is not stored; it is replaced with a marker such as [redacted body, length=123].
Audit files are troubleshooting records, not proof of a broker fill. Check the API response and authoritative account/order state.
Preview Limitations
- No supported public token-copy or token-rotation UI.
- No public OpenAPI document or generated client SDK.
- No compatibility guarantee beyond inspecting the installed build's capability response.
- No multi-chart identifier; chart routes use the active chart.
- No live stream route.
- No shipped
hxCLI. - No local live-order route in the 1.1.10 baseline; newer Hyperliquid and KuCoin support is release-gated and capability-discovered.
- Browser CORS behavior is not an authorization boundary; never expose the token to web content.
- Script inventory can reveal local paths.
For the data that can leave the desktop through /chat, see AI Data and Privacy. For in-app profile controls, see Agent Builder API. For guarded live Hyperliquid and KuCoin workflows in an enabled build, see Local Agent Live Trading API.